pydantic-ai-channels 0.1.2

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 for testing
• (Optional) Slack bot token for Slack integration testing

---

Setting Up the Development Environment

1. Clone the repository

   git clone https://gitlab.com/rzk.ssr/pydantic-ai-channels.git
   cd pydantic-ai-channels
   

2. Install dependencies with uv

   uv sync
   

   This will create a virtual environment and install all runtime and development dependencies.

3. Activate the virtual environment (optional)

   source .venv/bin/activate   # On Windows: .venv\Scripts\activate
   

4. Set up pre‑commit hooks (for code quality)

   uv run pre-commit install
   

5. Configure environment variables
   Create a .env file with:

   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

  uv run pytest
  

• Run with coverage

  uv run pytest --cov=pydantic_ai_channels --cov-report=term-missing
  

• Run a specific test file

  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

  uv run ruff check .
  

• Format

  uv run ruff format .
  

• Type checking (using Pyright / mypy) – run manually with

  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.