Telegram AI Assistant Bot

Overview

The Telegram AI Assistant Bot is a reasoning-driven AI agent, named Cortex-R, designed to interact with users via Telegram. It uses multiple Model Context Protocol (MCP) servers to perform various tasks such as web searches, document processing, mathematical calculations, and Google services integration (e.g., Gmail and Google Sheets). The bot employs both stdio and sse transport protocols to communicate with these MCP servers.

Features

- Telegram Integration: The bot interacts with users through Telegram, responding to their queries and tasks. - Multi-MCP Server Support: Utilizes multiple MCP servers for diverse functionalities. - Gmail integration for email management. - Google Sheets integration for spreadsheet operations. - Web search capabilities using DuckDuckGo. - Document processing and semantic search. - Mathematical calculations. - Dynamic Tool Discovery: Automatically discovers tools from MCP servers during initialization. - Customizable Agent Strategy: Supports different strategies like conservative, retry-once, and explore-all. - Memory Management: Retrieves and stores memory items to enhance task-solving capabilities. - Configurable Persona: Allows customization of tone, verbosity, and behavior.

Architecture

The bot is built using the following components:

1. Telegram Bot Integration

The bot is implemented in telegram_agent.py using the python-telegram-bot library. It handles user messages and commands such as /start and /help. User queries are processed by the Cortex-R agent.

2. Core Components

- Agent Loop (core/loop.py): Manages the main execution loop of the agent, including perception, planning, and tool execution. - Session Management (core/session.py): Handles communication with multiple MCP servers using stdio and sse transport protocols. - Strategy (core/strategy.py): Implements planning strategies for decision-making.

3. MCP Servers

The bot interacts with the following MCP servers: - Gmail Server (gmail_server.py): Manages email operations such as sending, reading, and trashing emails. - Google Sheets Server (mcp_gdrive_server.py): Handles spreadsheet operations like creating, updating, and sharing Google Sheets. - Web Search Server (mcp_server_3.py): Performs web searches using DuckDuckGo and fetches webpage content. - Document Processing Server (mcp_server_2.py): Processes documents for semantic search and indexing. - Math Server (mcp_server_1.py): Performs mathematical calculations.

4. Configuration

- Profiles (config/profiles.yaml): Defines agent settings, including strategy, memory configuration, and MCP server details. - Models (config/models.json): Specifies the models used for text generation and embeddings. - Environment Variables (.env): Stores sensitive information like API keys and file paths.

Workflow

1. Initialization: - The bot loads MCP server configurations from profiles.yaml. - Initializes the MultiMCP dispatcher to discover tools from all configured MCP servers.

2. User Interaction:
- Users interact with the bot via Telegram.
- The bot processes user messages and determines the required tools to fulfill the task.

3. Task Execution:
- The agent uses perception to understand the user query.
- Plans the next action using the defined strategy.
- Executes the required tool from the appropriate MCP server.
- Retrieves results and responds to the user.

4. Memory Management:
- Stores tool outputs and user queries as memory items.
- Retrieves relevant memories to assist in task-solving.

Configuration

Environment Variables

Set the following variables in the .env file: - GEMINI_API_KEY: API key for the Gemini model. - SERVICE_ACCOUNT_PATH: Path to the Google service account JSON file. - DRIVE_FOLDER_ID: Google Drive folder ID for storing files. - CREDENTIALS_PATH: Path to the OAuth client credentials file. - TOKEN_PATH: Path to the token file for Google APIs.

MCP Server Configuration

Define MCP servers in config/profiles.yaml:

mcp_servers:
  - id: gmail
    type: stdio
    script: gmail_server.py
    cwd: <path-to-server>
  - id: gdrive
    type: stdio
    script: mcp_gdrive_server.py
    cwd: <path-to-server>
  - id: math
    type: sse
    script: mcp_server_1.py
    url: http://localhost:8000/sse
    cwd: <path-to-server>
  - id: documents
    type: stdio
    script: mcp_server_2.py
    cwd: <path-to-server>
  - id: websearch
    type: stdio
    script: mcp_server_3.py
    cwd: <path-to-server>

Installation

1. Clone the repository:

   git clone <repository-url>
   cd <repository-folder>
   

2. Sync dependencies using uv:

   uv sync
   

3. Set up environment variables in .env. 4. Start the Telegram bot:

   uv run telegram_agent.py
   

Usage

- Start the bot on Telegram using the /start command. - Send queries or tasks to the bot, such as: - "Find the current F1 standings and share them in a Google Sheet." - "Send an email to example@gmail.com with the subject 'Meeting Update'."

Contributing

Contributions are welcome! Please follow these steps: 1. Fork the repository. 2. Create a new branch for your feature or bug fix. 3. Submit a pull request with a detailed description of your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.