mate: Instructions file for Codex

MATE (Multi-Agent Tree Engine) System Instructions

Project Overview

MATE (Multi-Agent Tree Engine) is a production-ready web platform built on top of Google ADK (with optional LangGraph runtime support) that adds database-driven agent management, multi-LLM support, external OpenAI-compatible agent endpoints, RBAC, MCP integration, token tracking, guardrails, EU AI Act compliance features, and a dashboard UI with Work Room code canvas.

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
• Match existing style when editing existing code

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

Quick Start

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.lock
cp .env.example .env

# Run (auto-applies DB migrations, default SQLite)
python auth_server.py
# Dashboard: http://localhost:8000 (default login: admin/mate)

# Docker alternative
docker-compose up

Architecture

• Agent-Manager-Tool Factory pattern: Centralized initialization and management
• Dual-Server Design:
  • Auth Server: Runs on port 8000 (auth_server.py, FastAPI with HTTP Basic Auth, proxies authenticated requests to the agent server)
  • Agent Server: Runs on port 8001 (internal, not directly exposed). Runtime framework selectable via AGENT_FRAMEWORK:
    • adk (default): Google ADK web server (adk_main.py)
    • langgraph: LangGraph runtime (langgraph_main.py + shared/utils/langgraph/, emulates ADK wire contract)
• All requests go through auth server — no direct external access to agent runtime server
• A2A (Agent-to-Agent) and MCP protocol requests are proxied through auth server
• Business logic is strictly separated from database operations
• shared/callbacks/ hooks into agent lifecycle for RBAC (rbac_callback.py), token tracking (token_usage_callback.py), and guardrails (model_guardrail.py, function_call_guardrail.py)
• Rate limiting and request throttling via server/rate_limit_middleware.py