From 74ca45782747229e51e99918f5064fd522ccda1b Mon Sep 17 00:00:00 2001 From: furyhawk Date: Tue, 16 Jun 2026 21:05:23 +0800 Subject: [PATCH] docs: update architecture docs to reflect refactored agent factory and DI wiring --- CLAUDE.md | 5 ++++- agents.md | 14 ++++++++------ 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index db0eaa1..72aa786 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,15 +31,18 @@ Agent Alpha is a full-stack agentic AI application consisting of a FastAPI backe ### Backend Architecture (`/backend`) The backend follows a layered architecture: - **Core (`/backend/core`)**: The heart of the application. Contains configuration (`config.py`), database engine initialization (`database.py`), ORM models (`models.py`), and the primary agent lifecycle/inference logic (`agent.py`). + - `AgentService` is a thin orchestrator that receives a pre-built `Agent` via constructor injection (wired at startup in `app.py`'s lifespan). - **Database & Repositories**: - **Models**: SQL Alchemy ORM models are split between general domain models (in `core`) and RAG-specific models (in `db/models` like `ChatFile`, `RagDocument`). - - **Repositories**: Abstracted CRUD operations for all DB models are located in `/backend/repositories`. + - **Repositories**: Abstracted CRUD operations for all DB models are located in `/backend/repositories`. `MemoryRepository` encapsulates filesystem persistence for agent memories via `LocalBackend`. - **RAG Pipeline (`/backend/rag`)**: Handles the document ingestion lifecycle. - `connectors.py` manages sync sources. - `ingestion.py` manages the Parse → Chunk → Embed → Store pipeline. - `retrieval.py` and `reranker.py` handle multi-stage vector search and scoring. - `vectorstore.py` interfaces with Milvus. - **Services**: Domain-specific logic for file storage, RAG tracking, status streaming (via Redis/SSE), and synchronization. + - `agent_factory.py` provides `build_agent()` — a factory that wires model providers, Logfire, capabilities (`CodeMode`, `ToolSearch`, `MCP`, `WebSearch`, `InputGuard`, `ToolGuard`), subagents, skills, and RAG tools into a `pydantic-ai` agent. + - `rag_service.py` provides `RagService` which builds RAG search tools for document retrieval. - **Routes & Schemas**: FastAPI endpoints (`/routes`) are paired with Pydantic models (`/schemas`) for request validation and response serialization. - **Worker**: Handles asynchronous tasks (like heavy RAG ingestion) via an in-process dispatcher, designed to eventually move to a Redis-backed ARQ setup. diff --git a/agents.md b/agents.md index 3e6f157..cb2f736 100644 --- a/agents.md +++ b/agents.md @@ -9,23 +9,25 @@ Agents are built using the `pydantic-ai` framework. Every agent must be modulari ### 1. Core Agent (`backend/core/`) The core module should only handle high-level agent lifecycle and basic configuration. It is a "Thin Service" that orchestrates the interaction between the user request, the dependencies, and the LLM. -### 2. Factory Layer (`backend/services/factory/`) -Complex logic for initializing agents—including model provider setup, logfire integration, tool registration, and environment variable validation—must reside in specialized factories (e.g., `AgentFactory`). +### 2. Factory Layer (`backend/services/agent_factory.py`) +Complex logic for initializing agents—including model provider setup, Logfire integration, capability registration (`CodeMode`, `ToolSearch`, `MCP`, `WebSearch`, guardrails), subagent setup, skills discovery, and RAG tool injection—resides in the `build_agent()` factory function. ### 3. Service Layer (`backend/services/`) Business logic related to agent capabilities must be moved to dedicated services: -- **RAG Service**: Handles the construction of retrieval tools and interaction with vector stores. -- **Skill Service**: Manages the discovery, registration, and execution of modular "Skills". -- **Memory Service**: Orchestrates persistence of conversation history and state. +- **Agent Factory** (`agent_factory.py`): `build_agent()` wires model, capabilities, subagents, skills, and RAG tools into a configured `pydantic-ai` agent. +- **RAG Service** (`rag_service.py`): Constructs retrieval tools for vector search (by document, by collection) and registers them as agent tools. +- **Chat Service** (`chat_service.py`): Manages conversation history, session metadata, and title generation via Valkey. +- **Auth Service** (`auth_service.py`): Handles user registration, password hashing, login, and token lifecycle. ### 4. Repository Layer (`backend/repositories/`) All direct interactions with data sources (SQLAlchemy models, Milvus vector store, local filesystems) must be abstracted into repositories. - Repositories are responsible for CRUD operations and state persistence. - Repositories use `db.flush()` to ensure data integrity without premature commits in transactional blocks. +- **MemoryRepository** (`memory_repository.py`): Encapsulates agent memory filesystem persistence via `LocalBackend`; provides both the memory directory path and the backend instance for agent `RunContext`. ## Tooling & Skills - **Tools**: Must be decorated with `@agent.tool`. Descriptions must be highly descriptive for LLM comprehension. -- **Skills**: Modular capabilities stored in `/skills/`. These are registered by the `SkillService` and injected into agents as tools. +- **Skills**: Modular capabilities stored in `/skills/`. These are automatically discovered and registered by `create_deep_agent` when `include_skills=True` and `skill_directories=["./skills"]` are set in the factory. - **Dependencies**: Use FastAPI's Dependency Injection system to provide Repositories and Services to Agent logic via `RunContext`. ## Patterns