How cgoncalves94/multi-agent-pydanticai works
Project Type and Purpose
• This is a full-stack, multi-agent AI chat application.
• Frontend: Next.js + TypeScript + Material UI for the interactive chat UI.
• Backend: FastAPI + Pydantic + SQLite providing HTTP endpoints, orchestrating AI “agents,” and persisting chat sessions.
Top-Level Components
a. Frontend (frontend/)
• Next.js App (app/, page.tsx, layout.tsx)
• React Components for chat UI: ChatHeader, ChatInput, ChatMessages, CodeBlock, ImageAnalysis, SearchResults, ModeToggle
• ThemeRegistry + global CSS + Material UI theme
• apiService.ts for REST API calls
b. Backend (backend/)
• FastAPI app (app.py)
• Agent orchestrator (agents.py) implementing Code Expert, Search Expert, Image Expert
• Database module (database.py) using SQLite to store sessions and messages
• Pydantic models for request/response validation
c. Database
• SQLite file managed by SQLModel/Pydantic
d. External AI & Tools
• OpenAI GPT-4o / Google Gemini via REST API keys
• Web search API (for Search Expert)
• Image analysis API or Vision models
e. Dev & Ops
• Uvicorn runner, .env configuration, Makefile targets for dev, linting, pre-commit
Relationships and Data Flow
• Browser → Next.js frontend UI
• User inputs → React chat components → apiService
• Frontend → Backend
• HTTP(S) requests (REST endpoints exposed by FastAPI)
• Streaming vs structured JSON responses
• Backend Orchestration
• Receives user message → routes to appropriate Agent(s)
• Code Expert calls OpenAI/Gemini for code generation/execution
• Search Expert triggers web search, summarizes results
• Image Expert sends uploaded images for object detection
• Backend → Database
• Persist chat history, session IDs, agent responses
• Backend → External Services
• REST calls to AI providers and web search
• Backend → Frontend
• Streams back responses or full JSON payloads
Architectural Patterns & Principles
• Layered Separation:
• Presentation (Next.js React)
• Application/API (FastAPI endpoints)
• Domain Logic (Agent orchestrator)
• Data (SQLite via Pydantic/SQLModel)
• Single-Process Micro-service Style:
• Agents are modules, not separate deployables, but can be refactored into microservices if needed
• Streaming Data Flow:
• Use HTTP chunked responses for streaming agent replies
• API‐First Design:
• Clear Pydantic schemas for request/response
• Notes on extension points: how to add a new Agent module or swap the DB.