Metadata-Version: 2.4
Name: pydantic-ai-channels
Version: 0.1.2
Summary: Production-ready Telegram and Slack channels for Pydantic AI agents.
Project-URL: Homepage, https://gitlab.com/rzk.ssr/pydantic-ai-channels
Project-URL: Repository, https://gitlab.com/rzk.ssr/pydantic-ai-channels
Project-URL: Issues, https://gitlab.com/rzk.ssr/pydantic-ai-channels
Author: Pydantic AI Channels Contributors
License-File: LICENSE
Keywords: agent,ai,bot,pydantic,slack,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Requires-Dist: aiogram>=3.28.2
Requires-Dist: pydantic-ai>=1.103.0
Requires-Dist: python-magic>=0.4.27
Requires-Dist: slack-sdk>=3.42.0
Requires-Dist: telegramify-markdown[mermaid]>=1.1.5
Provides-Extra: all
Requires-Dist: aiogram>=3.28.2; extra == 'all'
Requires-Dist: discord-py>=2.3.2; extra == 'all'
Requires-Dist: motor>=3.3.2; extra == 'all'
Requires-Dist: pymongo>=4.6.1; extra == 'all'
Requires-Dist: redis>=5.0.1; extra == 'all'
Requires-Dist: slack-bolt>=1.28.0; extra == 'all'
Requires-Dist: slack-sdk>=3.42.0; extra == 'all'
Provides-Extra: discord
Requires-Dist: discord-py>=2.3.2; extra == 'discord'
Provides-Extra: mongodb
Requires-Dist: motor>=3.3.2; extra == 'mongodb'
Requires-Dist: pymongo>=4.6.1; extra == 'mongodb'
Provides-Extra: redis
Requires-Dist: redis>=5.0.1; extra == 'redis'
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.28.0; extra == 'slack'
Requires-Dist: slack-sdk>=3.42.0; extra == 'slack'
Provides-Extra: telegram
Requires-Dist: aiogram>=3.28.2; extra == 'telegram'
Description-Content-Type: text/markdown

## Project Overview

`pydantic-ai-channels` is a framework for integrating **Pydantic AI agents** with real‑world messaging platforms like **Telegram** and **Slack**. It provides a clean, type‑safe abstraction for sending and receiving messages, handling webhooks, polling, and tool calling.

Key components:
- **Channel Adapters** – Platform‑specific connectors (aiogram for Telegram, slack‑sdk for Slack).
- **Capabilities** – Pydantic AI `AbstractCapability` wrappers that inject platform tools into an agent.
- **Toolsets** – Production‑ready function tools for message sending, media uploads, inline keyboards, etc.

The project is built with Python 3.12+, uses `uv` for dependency management, and follows strict type safety and test coverage standards.

---

## Prerequisites for Development

- **Python 3.12+** (as specified in `pyproject.toml`)
- **`uv`** – the fast package installer and resolver. Install via `pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **Telegram Bot Token** – obtain one from [@BotFather](https://t.me/BotFather) for testing
- (Optional) Slack bot token for Slack integration testing

---

## Setting Up the Development Environment

1. **Clone the repository**
   ```bash
   git clone https://gitlab.com/rzk.ssr/pydantic-ai-channels.git
   cd pydantic-ai-channels
   ```

2. **Install dependencies with `uv`**
   ```bash
   uv sync
   ```
   This will create a virtual environment and install all runtime and development dependencies.

3. **Activate the virtual environment** (optional)
   ```bash
   source .venv/bin/activate   # On Windows: .venv\Scripts\activate
   ```

4. **Set up pre‑commit hooks** (for code quality)
   ```bash
   uv run pre-commit install
   ```

5. **Configure environment variables**  
   Create a `.env` file with:
   ```env
   TELEGRAM_BOT_TOKEN=your_bot_token_here
   SLACK_BOT_TOKEN=your_slack_token
   ```

---

## Running Tests

The project uses `pytest` with `pytest-asyncio` for asynchronous tests.

- **Run all tests**
  ```bash
  uv run pytest
  ```

- **Run with coverage**
  ```bash
  uv run pytest --cov=pydantic_ai_channels --cov-report=term-missing
  ```

- **Run a specific test file**
  ```bash
  uv run pytest tests/test_telegram_adapter.py
  ```

> **Note**: Some tests may require a live Telegram or Slack connection. In CI, those should be mocked or skipped.

---

## Code Quality & Formatting

The project uses **Ruff** for linting and formatting, configured in `pyproject.toml`.

- **Lint**
  ```bash
  uv run ruff check .
  ```

- **Format**
  ```bash
  uv run ruff format .
  ```

- **Type checking** (using Pyright / mypy) – run manually with
  ```bash
  uv run pyright
  ```

All commits are automatically checked by `pre-commit`. Please fix any warnings before pushing.

---

## Project Structure

```
pydantic_ai_channels/
├── capabilities/          # Pydantic AI capabilities for each platform
│   └── telegram/
├── channels/              # Channel adapters (base + platform implementations)
│   ├── base.py            # Abstract classes and message models
│   ├── telegram/
│   └── slack/
└── toolsets/              # FunctionToolset implementations
    └── telegram/

examples/                  # Example applications (e.g., gramatic agent)
tests/                     # Unit and integration tests
```

When adding a new platform (e.g., Discord), you must:
1. Implement a new `ChannelAdapter` in `channels/`.
2. Create a corresponding `*Capability` in `capabilities/`.
3. Optionally provide a toolset if the platform supports interactive tools.

---

## Contribution Guidelines

We welcome contributions! Please follow these steps:

1. **Open an issue** – Describe the bug or feature you intend to work on.
2. **Fork the repository** and create a branch with a descriptive name (e.g., `add-discord-adapter`).
3. **Write or adapt tests** – All new functionality must be covered by tests.
4. **Update documentation** – If you change the public API, update the docstrings and any relevant example.
5. **Run the full test suite** and ensure 100% coverage where possible.
6. **Open a merge request** – Fill out the MR template completely.

### Coding Standards

- **Python version**: 3.12+
- **Type hints**: Required for all functions (including `__init__` and private methods).
- **Async**: All I/O operations must be `async def`.
- **Docstrings**: Use Google style for public functions and classes.
- **Line length**: 115 characters (as configured).
- **Imports**: Use Ruff’s isort rules (combine‑as‑imports = true).

### Commit Message Style

We follow **Conventional Commits**:

```
<type>(<scope>): <subject>

<body>
```

Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.  
Scopes: `telegram`, `slack`, `capabilities`, `toolsets`, `examples`, `ci`, etc.

---

## Working with AI Agents on This Repository

If you are an **AI assistant** (like me) helping to maintain or develop this repository:

1. **Prioritize the project’s users and maintainers** over the immediate request.
    - Example: When implementing a new Telegram tool, consider how it fits the existing `TelegramToolset` pattern and whether it should be a separate capability.

2. **Always gather full context** before writing code:
    - Read the issue/merge request and any linked discussions.
    - Check the `pyproject.toml` for dependencies and tool configurations.
    - Examine existing implementations (e.g., `telegram.py`) to mimic style and error handling.

3. **Question assumptions** – If a request asks for something that breaks backward compatibility or adds unnecessary complexity, propose an alternative.

4. **Test changes locally** – Use `uv run pytest` and ensure the code passes linting.

5. **Document as you go** – Update docstrings, the `README` (once populated), or example files when introducing new concepts.

Remember: **the public API and developer experience are paramount**. Every change should make the framework more intuitive, more type‑safe, and more delightful to use.

---

## License

This project is open source. See the `LICENSE` file (once added) for details.
