Skip to content

Latest commit

 

History

History
253 lines (188 loc) · 6.91 KB

README.md

File metadata and controls

253 lines (188 loc) · 6.91 KB
Raw

Telegram AI Agent Library

PyPI version Python Version License: MIT

This Python library provides a framework for creating AI-powered Telegram bots using the Telegram Core API and the phi library for AI integration.

Features

  • Secure authentication with Telegram servers
  • Inbound message processing with AI integration using phi
  • Outbound messaging capabilities
  • Chat history support for context-aware responses
  • Configurable proxy and timeout settings
  • Asynchronous operations using asyncio
  • Typing indicators for a more natural conversation flow
  • Function calling for AI-powered tools
  • Customizable logging
  • Streamlit UI for easy interaction with the agent

Installation

You can install the library directly from PyPI:

pip install telegram-ai-agent

Using Poetry

If you're using Poetry for dependency management:

poetry add telegram-ai-agent

Install from source

  1. Clone the repository:

    git clone https://github.com/ifokeev/telegram-ai-agent.git
cd telegram-ai-agent

  2. Using Poetry (recommended):

    poetry install

    This will create a virtual environment and install all dependencies automatically.

  3. Or using pip with a virtual environment:

    python -m venv .venv
source .venv/bin/activate  # On Windows, use `.venv\Scripts\activate`
pip install -e .

Note: Make sure you have Python 3.11 or higher installed on your system before proceeding with the installation.

Development Installation

For development purposes, install with additional dependencies:

# Using pip
pip install -e ".[dev]"

# Using Poetry
poetry install --with dev

This will install additional packages needed for development, such as:

  • pytest for testing
  • ruff for linting
  • black for code formatting
  • pre-commit hooks

Streamlit UI

To run the Streamlit UI, run the following command:

streamlit run streamlit_app/Home.py

and navigate to http://localhost:8501 in your web browser.

Video Tutorial

Watch our video tutorial to learn how to use the Streamlit UI:

Telegram AI Agent Streamlit UI Tutorial

The video demonstrates:

  • Setting up your Telegram account
  • Managing AI assistants
  • Running and monitoring agents
  • Using the chat interface
  • Managing user segments and campaigns

This visual guide will help you get started with the Telegram AI Agent's user interface quickly and efficiently.

Configuration

To configure the Telegram AI Agent library, you need to set up environment variables. You can do this by either creating a .env file or copying from the provided .env.example file.

Option 1: Create a new .env file

Create a .env file in the root directory of your project with the following content:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_PHONE_NUMBER=your_phone_number_here
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Proxy settings
# PROXY_TYPE=socks5
# PROXY_ADDR=1.1.1.1
# PROXY_PORT=5555
# PROXY_USERNAME=username
# PROXY_PASSWORD=password

Replace the placeholder values with your actual Telegram API credentials and OpenAI API key.

Option 2: Copy from .env.example

If you prefer not to create a new file, you can copy the .env.example file to .env and modify the values as needed.

Usage

Here's a basic example of how to use the Telegram AI Agent:

import asyncio
import logging
from dotenv import load_dotenv
import os
from telegram_ai_agent import TelegramAIAgent, TelegramConfig
from telegram_ai_agent.utils import setup_logging
from phi.assistant.assistant import Assistant
from phi.llm.openai.chat import OpenAIChat

# Load environment variables and setup logging
load_dotenv()
setup_logging()
logger = logging.getLogger(__name__)

# Optional: Load proxy settings if provided
proxy = None
if (
    os.getenv("PROXY_TYPE")
    and os.getenv("PROXY_ADDR")
    and os.getenv("PROXY_PORT")
):
    proxy = {
        'proxy_type': os.getenv("PROXY_TYPE"),  # socks5, socks4, or http
        'addr': os.getenv("PROXY_ADDR"),
        'port': int(os.getenv("PROXY_PORT")),
        'rdns': True  # Use remote DNS resolution
    }

    # Add proxy authentication if provided
    if os.getenv("PROXY_USERNAME") and os.getenv("PROXY_PASSWORD"):
        proxy['username'] = os.getenv("PROXY_USERNAME")
        proxy['password'] = os.getenv("PROXY_PASSWORD")

# Create OpenAI assistant
openai_chat = OpenAIChat(api_key=os.getenv("OPENAI_API_KEY"))
assistant = Assistant(
    llm=openai_chat,
    run_id="telegram_ai_agent",
    description="Sales representative for a tech company",
    instructions=["You are a sales representative for a tech company. You are tasked with selling a product to the user."]
)

# Create Telegram configuration
telegram_config = TelegramConfig(
    session_name="session_1",
    api_id=int(os.getenv("TELEGRAM_API_ID")),
    api_hash=os.getenv("TELEGRAM_API_HASH")),
    phone_number=os.getenv("TELEGRAM_PHONE_NUMBER"),
    proxy=proxy,
    # Optional: Advanced settings
    timeout=30,
    set_typing=True,
    typing_delay_factor=0.05,
    typing_delay_max=30.0,
    min_typing_speed=100.0,
    max_typing_speed=200.0,
    chat_history_limit=100,
)

async def get_code():
    return input("Enter the code you received: ")

async def get_password():
    return input("Enter your password: ")

async def main():
    try:
        # Create and start the Telegram AI Agent
        agent = TelegramAIAgent(
            assistant,
            telegram_config,
            logger=logger,
            code_callback=get_code,
            twofa_password_callback=get_password,
        )
        # Run agent inbound processing until disconnected
        await agent.run()
    except Exception as e:
        logger.error(f"An error occurred: {str(e)}")
    finally:
        if agent.session:
            await agent.stop()

if __name__ == "__main__":
    asyncio.run(main())

For more detailed examples, check the examples directory.

Testing

This project uses pytest for unit testing. To run the tests, first install the development dependencies:

pip install -e .[dev]

Then, you can run the tests using:

pytest tests/

The test suite includes unit tests for the TelegramAIAgent class, covering initialization, starting, stopping, sending messages, and processing incoming messages.

To add new tests or modify existing ones, check the tests/test_agent.py file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.