Using as an App

manolo-bot is ready to use as a standalone Telegram chat bot. It handles message queuing, multimodal inputs (images/voice), and tool execution out of the box.

Quick Start

  1. Install the package:

    pip install manolo-bot

  2. Configure environment: Create a .env file in your current directory or set environment variables directly:

    TELEGRAM_BOT_TOKEN=your_telegram_token
GOOGLE_API_KEY=your_gemini_api_key
# Add other configuration as needed

  3. Run the bot:

    manolo-bot

Configuration Details

The bot is configured entirely via environment variables. You can set these in your terminal or, more conveniently, in a .env file in the project root.

LLM Providers

You must provide at least one API key or a local model configuration.

  • GOOGLE_API_KEY: API key for Google Gemini. If set, the bot defaults to gemini-2.0-flash.

  • OPENAI_API_KEY: API key for OpenAI.

  • OPENAI_API_BASE_URL: Use this for OpenAI-compatible services (like LM Studio or LocalAI).

  • OLLAMA_MODEL: Name of a model running on your local Ollama instance (e.g., llama3).

Advanced Model Selection:

  • OPENAI_API_MODEL: Override the default OpenAI model (e.g., gpt-4o).

  • GOOGLE_API_MODEL: Override the default Gemini model (e.g., gemini-1.5-pro).

Telegram Bot Settings

To get these values, talk to @BotFather on Telegram.

  • TELEGRAM_BOT_TOKEN: Required. Your unique bot token.

  • TELEGRAM_BOT_NAME: The display name you gave your bot.

  • TELEGRAM_BOT_USERNAME: The @username of your bot.

  • BOT_UUID: A unique identifier for this bot instance (default: default-bot-uuid). Used to isolate conversation history in storage.

  • USER_ID: Your Telegram User ID (default: 0). Used for internal tracking and metadata.

Bot Persona and Instructions

Customize how the bot behaves and speaks.

  • TELEGRAM_BOT_INSTRUCTIONS: Full system instructions for the LLM. Overrides all other instructions.

  • TELEGRAM_BOT_INSTRUCTIONS_CHARACTER: Defines the bot’s “personality” (e.g., “You are a helpful assistant”).

  • TELEGRAM_BOT_INSTRUCTIONS_EXTRA: Additional instructions appended to the main system prompt.

  • PREFERRED_LANGUAGE: The language the bot should prefer (default: Spanish).

Agent and Tools

Note

Using Agent Mode is highly recommended for a better experience, as it allows the bot to reason and use tools effectively.

  • AGENT_MODE: Set to True (recommended) to enable “Agentic” behavior. In this mode, the bot doesn’t just respond; it thinks and acts. It will use the LLM to reason about your request and can perform multiple iterations (like searching the internet, reading web pages, and refining its search) until it completes the task.

  • USE_TOOLS: Set to True to allow the bot to use tools. In non-agent mode, it uses tools in a more direct, single-step way.

  • AGENT_INSTRUCTIONS: Custom rules that guide how the agent should reason and prioritize its actions when AGENT_MODE is active.

Search Configuration

The bot can search the web to answer your questions. By default, it uses DuckDuckGo (no API key required). For better results, you can enable Tavily Search:

  • USE_TAVILY_SEARCH: Set to True to use Tavily instead of DuckDuckGo.

  • TAVILY_SEARCH_KEY: Your Tavily API key (get one at tavily.com).

Image and Voice

  • IMAGE_MULTIMODAL: Set to True to allow the bot to “see” images you send or reply to.

  • AUDIO_MULTIMODAL: (Experimental) Set to True to allow the bot to “hear” voice messages. Currently only supported by Google Gemini.

  • WEBUI_SD_API_URL: If you have a Stable Diffusion Web UI running, provide its URL here to enable the /generate_image capability.

  • WEBUI_SD_API_PARAMS: A JSON string of parameters for the Stable Diffusion API (e.g., {“steps”: 20, “width”: 512}).

  • WEBUI_SD_API_NEGATIVE_PROMPT: Words or concepts you want Stable Diffusion to avoid.

Storage and Persistence

  • STORAGE_TYPE:

    • memory (default): Conversation history is lost when the bot stops.

    • redis: Conversation history is saved in a Redis database.

  • REDIS_URL: Connection string if using Redis (e.g., redis://localhost:6379/0).

Model Context Protocol (MCP)

manolo-bot can connect to external tool servers using MCP.

  • ENABLE_MCP: Set to True to enable.

  • MCP_SERVERS_CONFIG: A JSON string defining your MCP servers.

Example Config:

{
  "weather": {
    "url": "http://localhost:8000/mcp/",
    "transport": "streamable_http"
  }
}

Interaction Control

  • TELEGRAM_ALLOWED_CHATS: Comma-separated list of IDs. If set, the bot will only respond in these chats.

  • ALLOW_PRIVATE_CHATS: Set to False to prevent the bot from responding in direct messages.

  • ENABLE_GROUP_ASSISTANT: If True, the bot will proactively respond to messages containing a ? in groups, even if not directly mentioned.

  • ADD_NO_ANSWER: If True, the bot will reply with “NO_ANSWER” if it doesn’t understand a message or isn’t sure if it should respond.

  • SIMULATE_TYPING: If True, the bot will simulate typing before sending a response.

  • SIMULATE_TYPING_WPM: Typing speed in words per minute (default: 100).

  • SIMULATE_TYPING_MAX_TIME: Maximum time in seconds to simulate typing (default: 10).

Advanced Settings

Fine-tune the bot’s performance and logging.

  • LOGGING_LEVEL: Set the verbosity of logs (DEBUG, INFO, WARNING, ERROR, CRITICAL).

  • CONTEXT_MAX_TOKENS: Maximum number of tokens to keep in conversation memory (default: 4096).

  • WEB_CONTENT_REQUEST_TIMEOUT_SECONDS: Timeout for tools that fetch web content (default: 10).

  • RATE_LIMITER_REQUESTS_PER_SECOND: Max requests per second (default: 0.25).

  • RATE_LIMITER_CHECK_EVERY_N_SECONDS: Interval between rate limit checks (default: 0.1).

  • RATE_LIMITER_MAX_BUCKET_SIZE: Token bucket size for rate limiting (default: 10).

Available Commands

  • /flushcontext: Use this in a chat to clear the bot’s memory for that specific conversation. In groups, this is restricted to administrators.

Running with Docker

For production deployment, using Docker Compose (V2) is recommended:

docker compose up -d

If you encounter a KeyError: 'ContainerConfig' when using the older docker-compose tool, please upgrade to Docker Compose V2.

This will start both the bot and a Redis instance for persistent storage.