How cryptonomikhan/theo-ai works
Main Components
• API Service: Located under the “api” directory. This is the backend server that exposes endpoints, handles configuration, and processes external requests.
• Telegram Bot: Implemented in the “telegram” directory. This component listens for incoming messages in Telegram group chats, forwards them as requests to the API, and processes responses.
• Agents: Found in the “agents” directory. These encapsulate the business logic and smart “agno” agent functionalities. They’re responsible for performing research and determining which AI model (Formation Cloud or OpenAI) to use.
• Models: The “models” directory contains custom model implementations. This is where you’d define how data or requests are handled before reaching the agent.
• Integrations & Services:
• The “integrations” directory includes external integrations like Google Calendar.
• The “services” directory may hold modules for other external service integrations.
• Utilities: The “utils” directory provides helper resources that support configuration, logging, and system prompts.
• Deployment & Configuration:
• Files like Dockerfile, docker-compose.yml, .env.example, and environment variable instructions show that the system is containerized and configured for both local and cloud (Formation Cloud) deployments.
• Documentation & Project Flow: The “documentation” and “.cursor” directories include detailed design, flow, and architectural decisions which further suggest a planned modular design.
Relationships and Interactions
• Within the API server, the request is dispatched to the appropriate agent (within “agents/”) that handles business logic, including model selection (from “models/”) and invoking research or scheduling functions.
• The Agent then interacts with external integrations, such as calling functions in “integrations/googleCalendar.py” for scheduling or contacting Formation Cloud / OpenAI via the logic embedded in “utils” and “services”.
• Logging and configuration management is centralized through the “utils” module.
Architectural Patterns and Design Principles
• Stateless and Serverless Design: The agents are designed to be stateless (leveraging external context management). Emphasize how the components interact without holding persistent state.
• Modular Separation: The project divides responsibilities across distinct directories – separating API logic, agent processing, external integrations, and utility functions. This mirrors a microservices or modular monolith approach.
• Integration-Focused: Note how external API integrations (Telegram, Google Calendar, Formation Cloud, and OpenAI) are clearly isolated into their respective modules.
• Extensibility: The modular structure (especially in agents, integrations, and services) makes it easy to extend functionality or integrate further services.
Technologies and Frameworks
• Python (primary development language)
• agno Framework (for building AI agents)
• Docker and docker-compose (for containerization and deployment)
• Telegram Bot API (for chat integration)
• Google Calendar API, Formation Cloud, and OpenAI API (for external service integration)