Metadata-Version: 2.2
Name: SmolAgentsTelegram
Version: 0.0.1
Summary: Wrapper To Create Telegram Agent Written in Small Agents Framework
Author: Viacheslav Kovalevskyi
Author-email: viacheslav@kovalevskyi.com
License: MIT
Description-Content-Type: text/markdown
Requires-Dist: smolagents==1.12
Requires-Dist: python-dotenv==1.1
Requires-Dist: python-telegram-bot==22
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# Smol Agents Telegram Bot Wrapper

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A Python wrapper designed to simplify the creation of Telegram bots using the [**smolagents**](https://github.com/huggingface/smolagents) framework from Hugging Face. This wrapper allows you to quickly deploy agents as Telegram bots, where each user interacts with their own persistent agent instance.

## Overview

This project provides a `start_agent_bot` function that handles the underlying `python-telegram-bot` setup. You only need to provide:

1.  Your Telegram Bot Token.
2.  A function (`generate_agent_fn`) that creates and returns a `smolagents` agent instance (e.g., `CodeAgent`, `AssistantAgent`).

The wrapper automatically manages different agent instances for each unique Telegram chat ID, ensuring conversations are isolated between users. It also includes an optional feature to restrict bot access to a predefined list of chat IDs and a command to help users find their chat ID.

## Features

* **Easy Integration:** Seamlessly integrates with the `smolagents` framework.
* **Multi-User Support:** Automatically creates and manages separate agent instances for each Telegram user (based on chat ID).
* **Stateful Conversations:** Each user interacts with their dedicated agent, maintaining conversation context (depending on the agent's implementation).
* **Access Control:** Optionally restrict bot usage to specific Telegram chat IDs.
* **Simple Setup:** Requires minimal boilerplate code to get a bot running.
* **Helper Command:** Includes a `/get_chat_id` command for users to easily find their chat ID.
* **Extensible:** Easily customize the type of agent, tools, and models used within the `smolagents` framework.

## Prerequisites

* Python 3.8+
* A Telegram Bot: Create one using [BotFather](https://t.me/botfather) on Telegram to get your `TELEGRAM_TOKEN`.
* (Optional) API keys for specific models or tools (e.g., Hugging Face Hub token if using private/gated models via `HfApiModel`).

## Installation

1.  **Clone the repository (if you haven't already):**
    ```bash
    git clone <your-repo-url>
    cd <your-repo-directory>
    ```

2.  **Create and activate a virtual environment (recommended):**
    ```bash
    python -m venv venv
    # On Windows
    venv\Scripts\activate
    # On macOS/Linux
    source venv/bin/activate
    ```

3.  **Install the package and its dependencies:**
    This will install the wrapper itself (`sat`) along with dependencies listed in `requirements.txt` (like `smolagents`, `python-telegram-bot`, `python-dotenv`, etc.).
    ```bash
    pip install .
    ```
    *For development, you might prefer an editable install:*
    ```bash
    pip install -e .
    ```

## Configuration

1.  Create a file named `.env` in the root directory of your project.
2.  Add your Telegram Bot Token to the `.env` file:
    ```dotenv
    TELEGRAM_TOKEN="YOUR_TELEGRAM_BOT_TOKEN_HERE"
    ```
3.  (Optional) If your chosen agent/model requires other API keys (like a Hugging Face token for `HfApiModel`), add them to the `.env` file as well.
    ```dotenv
    # Example if needed for private/gated models or rate limits
    # HUGGINGFACE_HUB_TOKEN="YOUR_HF_TOKEN_HERE"
    ```

## Usage

1.  **Create your main Python script** (e.g., `run_bot.py`) based on the example provided:

    ```python
    # run_bot.py
    import os
    from dotenv import load_dotenv
    # Import from this wrapper package
    from sat import start_agent_bot
    # Import from Hugging Face's smolagents
    from smolagents import CodeAgent, DuckDuckGoSearchTool, HfApiModel

    # Load environment variables from .env file
    load_dotenv()

    # Define a function that creates and returns an agent instance
    # This function will be called for each new user (chat_id)
    def generate_client(user_id):
        """Creates a CodeAgent with Gemma and DuckDuckGo search using smolagents."""
        print(f"Creating new agent for user_id: {user_id}")
        # Configure the model (using HfApiModel from smolagents)
        model = HfApiModel(model_id="google/gemma-3-27b-it") # Ensure access/tokens if needed

        # Configure the tools (using DuckDuckGoSearchTool from smolagents)
        tools = [DuckDuckGoSearchTool()]

        # Create the agent (using CodeAgent from smolagents)
        agent = CodeAgent(tools=tools, model=model)
        return agent

    if __name__ == "__main__":
        # Get the Telegram token from environment variables
        telegram_token = os.environ.get("TELEGRAM_TOKEN")
        if not telegram_token:
            raise ValueError("TELEGRAM_TOKEN not found in environment variables. Did you create a .env file?")

        # --- Optional: Restrict Access ---
        # If you want to restrict the bot to certain users, create a list of allowed chat IDs (as strings)
        # allowed_chat_ids = ["123456789", "987654321"]
        # Then pass it to start_agent_bot:
        # start_agent_bot(
        #     telegram_token=telegram_token,
        #     generate_agent_fn=generate_client,
        #     telegram_chat_ids=allowed_chat_ids # Pass the list here
        # )
        # --- End Optional ---

        # Start the bot without restrictions
        print("Starting Telegram bot...")
        start_agent_bot(
            telegram_token=telegram_token,
            generate_agent_fn=generate_client
        )

    ```

2.  **Run the script:**
    ```bash
    python run_bot.py
    ```

3.  **Interact with your bot on Telegram:**
    * Find your bot on Telegram (the one you created with BotFather).
    * Send it messages. Each message will be processed by the `smolagents` agent instance associated with your chat ID.
    * If you need to find your chat ID (e.g., to add it to the `allowed_chat_ids` list), send the command `/get_chat_id` to the bot.

## Customization

* **Different Agents:** Modify the `generate_client` function to return a different type of agent available in `smolagents`.
* **Different Tools:** Change the `tools` list within `generate_client` to use other tools compatible with `smolagents`.
* **Different Models:** Change the `model` instance within `generate_client`. Use other models supported by `smolagents` (e.g., different `HfApiModel` configurations, potentially others if the library expands). Remember to configure any necessary API keys.
* **Restricting Access:** To limit who can use the bot, create a list of allowed Telegram chat IDs (as strings) and pass it to `start_agent_bot` using the `telegram_chat_ids` parameter (see the commented-out section in the example `run_bot.py`).

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file (if you have one) or the `setup.py` file for details.

## Author

* **Viacheslav Kovalevskyi** - viacheslav@kovalevskyi.com
