furyhawk/agent_alpha
1
0
Fork 0
mirror of https://github.com/furyhawk/agent_alpha.git synced 2026-07-20 10:15:33 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: update architecture docs to reflect refactored agent factory and DI wiring

Browse Source
This commit is contained in:
furyhawk
2026-06-16 21:05:23 +08:00
parent 21cea2cf97
commit 74ca457827
2 changed files with 12 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+4 -1
View File
@@ -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.
agents.md
+8 -6
View File
@@ -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