Metadata-Version: 2.4
Name: pydantic-ai-telegram
Version: 0.1.2
Summary: A Python library for integrating Pydantic AI agents with Telegram bots
Author-email: Wydii <yd@bageera.ai>
License: MIT
Project-URL: Homepage, https://github.com/wydii/pydantic-ai-telegram
Project-URL: Repository, https://github.com/wydii/pydantic-ai-telegram
Project-URL: Issues, https://github.com/wydii/pydantic-ai-telegram/issues
Keywords: pydantic-ai,telegram,bot,ai,agent
Classifier: Development Status :: 3 - Alpha
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic-ai>=0.0.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: whisper
Requires-Dist: openai-whisper>=20231117; extra == "whisper"
Requires-Dist: torch>=2.0.0; extra == "whisper"
Requires-Dist: ffmpeg-python>=0.2.0; extra == "whisper"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: pydantic-ai-telegram[openai,whisper]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: ruff>=0.0.285; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Dynamic: license-file

# Pydantic AI Telegram

Wrap any [Pydantic AI](https://ai.pydantic.dev/) agent with Telegram in one line of code.

**Why?** Pydantic AI makes building AI agents simple. This library lets you expose them via Telegram instantly — perfect for personal assistants, prototypes, or internal tools - Image, documents and voice memos are supported natively.

## Installation

```bash
pip install pydantic-ai-telegram
```

With local voice transcription (requires ffmpeg):

```bash
pip install pydantic-ai-telegram[whisper]
```

## Quick Start

### Option 1: CLI Configuration

Run the interactive setup:

```bash
pydantic-ai-telegram-config
```

This creates a `.env` file with your configuration.

### Option 2: Manual Configuration

Create a `.env` file:

```bash
# Required
TELEGRAM_BOT_TOKEN=your_token_from_botfather

# Optional - Access control
TELEGRAM_ALLOWED_CHAT_IDS=123456789,987654321
TELEGRAM_ALLOWED_USERNAMES=alice,bob

# Optional - Voice transcription (local whisper)
TRANSCRIPTION_SERVICE=local
WHISPER_MODEL=turbo

# Optional - OpenAI (for agent or transcription)
OPENAI_API_KEY=sk-...

# Optional - Conversation history limit
MAX_HISTORY_MESSAGES=50
```

## Minimal Example

```python
import os
from dotenv import load_dotenv
from pydantic_ai import Agent
from pydantic_ai_telegram import TelegramAgent

load_dotenv()

# Your Pydantic AI agent
agent = Agent(
    "openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
)

# Wrap it with Telegram
bot = TelegramAgent(
    bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
    agent=agent,
)

bot.run()
```

That's it. Your agent is now accessible via Telegram.

## Voice Transcription

Local transcription uses [OpenAI Whisper](https://github.com/openai/whisper) running on your machine:

```python
from pydantic_ai_telegram import TelegramAgent, LocalWhisperTranscription

transcription = LocalWhisperTranscription(model_name="turbo")

bot = TelegramAgent(
    bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
    agent=agent,
    transcription_service=transcription,
)
```

**Note:** Cloud transcription (OpenAI API) is planned for a future release.

## License

MIT
