Metadata-Version: 2.4
Name: telegram-auto-translate
Version: 0.1.16
Summary: Telegram userbot that automatically translates outgoing messages using Claude and GPT
Project-URL: Homepage, https://github.com/aimoda/telegram-auto-translate
Project-URL: Repository, https://github.com/aimoda/telegram-auto-translate
Project-URL: Issues, https://github.com/aimoda/telegram-auto-translate/issues
Author: ai.moda
License-Expression: MIT
License-File: LICENSE
Keywords: anthropic,auto-translate,bedrock,claude,openai,telegram,telethon,translation,userbot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: anthropic[bedrock]
Requires-Dist: httpx[http2]
Requires-Dist: openai[bedrock]
Requires-Dist: pydantic
Requires-Dist: telethon
Description-Content-Type: text/markdown

# Telegram Auto-Translate

[![PyPI version](https://img.shields.io/pypi/v/telegram-auto-translate.svg)](https://pypi.org/project/telegram-auto-translate/)

**A Telegram userbot that automatically translates your outgoing messages using conversation context.**

| Before | After |
|--------|-------|
| ![Before translation](screenshot-before.png) | ![After translation](screenshot-after.png) |

---

## How It Works

```
Your message → Detect languages → Translate with Claude → Clean output → Edit in place
```

1. **Watch** - Monitors your outgoing messages
2. **Analyze** - Gathers recent chat context (default: 10 messages)
3. **Detect** - Uses GPT-5.6 Luna to identify the target language based on who you're replying to
4. **Skip if unnecessary** - Won't translate if your message is already in the target language
5. **Translate** - Claude translates with full conversation context, matching the chat's tone and style
6. **Clean** - Strips any LLM artifacts (preambles, quotes) from the output
7. **Edit** - Replaces your original message with the translation

---

## Installation

### Via PyPI (Recommended)

```bash
pip install telegram-auto-translate
```

### From Source

```bash
git clone https://github.com/aimoda/telegram-auto-translate
cd telegram-auto-translate
pip install -e .
```

---

## Quick Start

```bash
# Set required environment variables
# Get TG_API_ID and TG_API_HASH from https://my.telegram.org/apps
export TG_API_ID="your_api_id"
export TG_API_HASH="your_api_hash"
export BEDROCK_AWS_PROFILE="your_aws_profile"

# Run
telegram-auto-translate
```

On first run, Telethon will prompt for your phone number and login code.

---

## Prerequisites

- **Python 3.10+**
- **Telegram API credentials** - Get `API_ID` and `API_HASH` from [my.telegram.org](https://my.telegram.org)
- **AWS account** with Amazon Bedrock access to both the Anthropic (Claude) and OpenAI (GPT) models, plus appropriate IAM permissions

---

## Configuration

### Telegram

| Variable | Description |
|----------|-------------|
| `TG_API_ID` | Your Telegram API ID (required) |
| `TG_API_HASH` | Your Telegram API hash (required) |
| `TG_SESSION_NAME` | Session file name (default: `translator_session`) |

### AWS Bedrock (Claude + GPT)

Both models run on Amazon Bedrock, authenticated with SigV4 request signing from
a single AWS profile — there is no separate OpenAI API key. They use different
Bedrock endpoints:

- **Claude** goes through `bedrock-runtime` (`InvokeModel`), so it can use the
  `global.` cross-region inference profile — dynamic routing with no regional
  pricing premium.
- **GPT** goes through the regional Mantle endpoint
  (`https://bedrock-mantle.<region>.api.aws`), which is the only way OpenAI
  models are served on Bedrock.

1. **[Create an IAM user](https://us-east-1.console.aws.amazon.com/iam/home#/users/create)** with programmatic access, then attach an IAM policy with Bedrock invoke permissions:

```json
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowBedrockModelInvocationInAUSCANNZUKUS",
            "Effect": "Allow",
            "Action": [
                "bedrock:InvokeModel",
                "bedrock:InvokeModelWithResponseStream"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:RequestedRegion": [
                        "us-east-1",
                        "us-east-2",
                        "us-west-1",
                        "us-west-2",
                        "ca-central-1",
                        "ca-west-1",
                        "eu-west-2",
                        "ap-southeast-2",
                        "ap-southeast-4",
                        "unspecified"
                    ]
                }
            },
            "Resource": [
                "arn:aws:bedrock:*::foundation-model/*",
                "arn:aws:bedrock:*:*:provisioned-model/*",
                "arn:aws:bedrock:*:*:imported-model/*",
                "arn:aws:bedrock:*:*:inference-profile/*"
            ]
        }
    ]
}
```

2. **Add credentials** to `~/.aws/credentials`:

```ini
[telegram-translator-bedrock]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
```

3. **Set the profile**:

```bash
export BEDROCK_AWS_PROFILE="telegram-translator-bedrock"
export BEDROCK_AWS_REGION="us-east-1"  # optional, us-east-1 is default
```

4. **Enable model access** for both `global.anthropic.claude-opus-5` and
   `openai.gpt-5.6-luna`. Claude routes globally via the inference profile, but
   GPT is served per-region — see [model support by AWS Region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-region-compatibility.html)
   and set `BEDROCK_AWS_REGION` to one that serves `openai.gpt-5.6-luna`.

---

## Usage

```bash
telegram-auto-translate [options]
```

### Command-Line Flags

| Flag | Description | Default |
|------|-------------|---------|
| `--dry-run` | Log translations without editing messages | Off |
| `--debug` | Verbose logging of API calls | Off |
| `--context-messages N` | Number of previous messages for context | 10 |
| `--bedrock-profile NAME` | AWS profile for Bedrock | `$BEDROCK_AWS_PROFILE` |
| `--bedrock-region REGION` | AWS region for Bedrock | `us-east-1` |
| `--anthropic-model MODEL` | Claude model ID | `global.anthropic.claude-opus-5` |
| `--openai-model MODEL` | GPT model for detection/cleaning | `openai.gpt-5.6-luna` |

### Environment Variables Reference

| Variable | Required | Description |
|----------|----------|-------------|
| `TG_API_ID` | Yes | Telegram API ID |
| `TG_API_HASH` | Yes | Telegram API hash |
| `BEDROCK_AWS_PROFILE` | Yes | AWS credentials profile (used for both Claude and GPT) |
| `BEDROCK_AWS_REGION` | No | AWS region (default: `us-east-1`) |
| `TG_SESSION_NAME` | No | Session file name |
| `ANTHROPIC_MODEL` | No | Claude model override |
| `OPENAI_MODEL` | No | GPT model override |
| `CONTEXT_MESSAGES` | No | Context message count |

---

## Examples

**Test without editing messages:**
```bash
telegram-auto-translate --dry-run --debug
```

**Use more context for better translations:**
```bash
telegram-auto-translate --context-messages 20
```

**Run in a different Bedrock region:**
```bash
BEDROCK_AWS_REGION="us-east-2" telegram-auto-translate
```

---

## Troubleshooting

### "TG_API_ID and TG_API_HASH are required"
Set both environment variables or pass `--api-id` and `--api-hash` flags.

### "BEDROCK_AWS_PROFILE is required"
Set `BEDROCK_AWS_PROFILE` to your AWS credentials profile name. The same profile
signs requests for both the Claude and GPT models.

### Translation not happening
- Check that there are previous messages in the chat (the bot needs context)
- Your message might already be in the detected target language
- Use `--debug` to see detection results

### "AccessDeniedException" from Bedrock
Verify your IAM policy includes `bedrock:InvokeModel` permission and that both
`global.anthropic.claude-opus-5` and `openai.gpt-5.6-luna` are enabled for your
account and region.

### First run hangs
Telethon is waiting for your phone number. Enter it in the terminal.

---

## Development Setup

For local development and contributions:

### Create and activate virtual environment
```bash
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### Install the package
```bash
# Install in editable mode for development
pip install -e .
```

### Run the application
```bash
# Option 1: Use the installed command
telegram-auto-translate

# Option 2: Run as module (without installing)
PYTHONPATH=src python -m telegram_auto_translate
```

---

## Why Bedrock?

Everything runs on **Amazon Bedrock**: Claude Opus 5 for translation, GPT-5.6 Luna
for language detection and output cleaning. One AWS account, one credentials
profile, one set of data-handling terms. Claude uses the `global.` inference
profile for cross-region routing without the regional pricing premium.

| Task | Model | Why |
|------|-------|-----|
| Translation | Claude Opus 5 | Adaptive thinking for nuanced, context-aware translations |
| Language Detection | GPT-5.6 Luna | Excellent structured output performance |
| Output Cleaning | GPT-5.6 Luna | Reliable artifact removal |

We prefer Bedrock for its data handling policies:
- [Inputs and outputs are not logged by default](https://docs.aws.amazon.com/bedrock/latest/userguide/abuse-detection.html)
- [Zero operator access](https://aws.amazon.com/blogs/machine-learning/exploring-the-zero-operator-access-design-of-mantle/) for the GPT models, which are served through Mantle
- [Configurable data retention](https://docs.aws.amazon.com/bedrock/latest/userguide/data-retention.html), including zero data retention on eligible accounts
