mate AGENTS.md

MATE (Multi-Agent Tree Engine) System Instructions

Code Style

• Use Python 3.8+ for all new files
• Follow PEP 8 style guidelines with 4-space indentation
• Use type hints for function parameters and return types
• Prefer descriptive variable names over comments
• Use f-strings for string formatting
• Import statements should be grouped: stdlib, third-party, local imports

Development Environment

• ALWAYS activate the virtual environment before running any Python commands
• Use source .venv/bin/activate before running Python scripts, tests, or imports
• This ensures correct package versions and dependencies are used
• All Python commands should be run within the activated virtual environment

Architecture

• Follow the Agent-Manager-Tool Factory pattern
• Keep database models in shared/utils/models.py
• Keep agent business logic separate from database operations
• Use the AgentManager for all agent initialization and hierarchy management
• Tools should be created through the ToolFactory system
• All agents must include token usage tracking callbacks

Server Architecture

• Auth Server: Always runs on port 8000 (auth_server.py)
• ADK Server: Always runs on port 8001 (adk_main.py)
• All requests go through auth server - no direct access to ADK server
• Auth server acts as a proxy to ADK server for all API requests
• Authentication is required for all requests (admin:mate by default)
• A2A (Agent-to-Agent) protocol requests are proxied through auth server

Database

• Use SQLAlchemy ORM for all database operations
• Support PostgreSQL (production), MySQL, and SQLite (development)
• Database sessions should be properly closed in finally blocks
• Use the DatabaseClient for connection management
• Agent configurations are stored in agents_config table
• Token usage is logged in token_usage_logs table
• Create migrations for each DB changes. Migrations are in shared/sql/migrations/. Each DB type have separated folder: postgresql, sqlite, mysql
• Database updates should go through the migration system, not through a separate script.
• Do not run any DB update. Prepare migrations. Migrations will be run on server run.