FastAPI Repo Chat Agent

A multi-agent, graph-powered codebase analysis system built using Burr, FastMCP, and Neo4j. This project allows users to ask complex architectural and semantic questions about a Python codebase (by default, the FastAPI repository) and uses a coordinated team of AI agents to find and explain the answers.

Architecture

The system uses a master-subordinate (hub and spoke) orchestration model built on Burr for state management and FastMCP for tool provisioning.

Components

1. Gateway (FastAPI): The main entry point. Exposes REST endpoints (/api/chat, /api/index) and runs the Master Orchestrator in-process.
2. Neo4j Graph Database: Stores the Abstract Syntax Tree (AST) of the target codebase, representing Module, Class, and Function nodes and their relationships (CONTAINS, DEPENDS_ON, CALLS).
3. Indexer Agent: Parses the codebase using Python's ast module and ingests the semantic structure into Neo4j.
4. Graph Query Agent: A specialized sub-agent that translates natural language goals into Cypher queries, searches the Neo4j graph, and returns precise entity names and file paths.
5. Code Analyst Agent: A specialized sub-agent that takes the file paths discovered by the Graph Query Agent, reads the raw source code, and performs deep semantic analysis to answer the user's original question.
6. Master Orchestrator: Uses Burr to dynamically plan a Directed Acyclic Graph (DAG) of tasks based on the user's prompt, routes those tasks to the appropriate sub-agents, and synthesizes the final response.

Execution Flow

1. User Request: User sends a query to /api/chat.
2. Planning: The Master Orchestrator uses an LLM to generate an execution plan (a DAG of tasks).
3. Execution: The orchestrator triggers sub-orchestrators for each task (respecting dependencies).
   • The Graph Query Agent typically runs first to locate relevant components.
   • The Code Analyst Agent runs next to read the code and analyze logic.
4. Synthesis: Each sub-agent compiles a detailed markdown report of its findings in its done_step.
5. Final Output: The Master Orchestrator compiles all sub-agent reports into a single, comprehensive response.

Running Locally

The system is containerized and managed via Docker Compose.

# Start all services (Gateway, Neo4j, and MCP Servers)
docker-compose up -d --build

# Run a test query against the gateway
uv run python test_query.py

Technologies

• Python 3.13 (managed via uv)
• FastAPI
• Burr (State Machine / Orchestration)
• FastMCP (Model Context Protocol)
• LiteLLM (LLM Abstraction Layer)
• Neo4j (Graph Database)
• Docker Compose