mate CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MATE (Multi-Agent Tree Engine) is a production-ready web platform built on top of Google ADK that adds database-driven agent management, multi-LLM support, RBAC, MCP integration, token tracking, guardrails, and a dashboard UI.

Running the Application

# Setup
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # Set GOOGLE_API_KEY or other LLM provider key

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

# Docker alternative
docker-compose up

Two servers run: Auth Server (port 8000, FastAPI with HTTP Basic Auth) proxies authenticated requests to the Agent Server (port 8001). The agent server framework is selectable via AGENT_FRAMEWORK: adk (Google ADK runtime, adk_main.py, default) or langgraph (LangGraph runtime, langgraph_main.py, emulates ADK's HTTP/SSE wire contract — see documents/LANGGRAPH_RUNTIME.md).

Testing

# All tests
python -m unittest discover -s shared/test -p "test_*.py" -v

# Single test file
python -m unittest shared.test.test_agent_manager_simple -v

# With coverage
coverage run -m unittest discover -s shared/test -p "test_*.py"
coverage report

Tests live in shared/test/ — 506 tests covering agent management, tool factory, model switching, RBAC, authorization, migrations, guardrails, tracing, and more.

Database Migrations

python shared/migrate.py run       # Apply pending migrations
python shared/migrate.py status    # Check migration status
python shared/migrate.py create    # Create new migration
python shared/migrate.py rollback  # Roll back last migration

Migrations auto-apply on server startup. Per-database migration files are in shared/sql/migrations/{postgresql,mysql,sqlite}/.

Architecture