144 lines
5.1 KiB
Markdown
144 lines
5.1 KiB
Markdown
# Agent Backend MVP
|
|
|
|
## Run (Local)
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
uvicorn app.main:app --reload --port 15000
|
|
```
|
|
|
|
## Run (Docker Compose)
|
|
|
|
1. Fill env values:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Set `GIGACHAT_TOKEN` in `.env`.
|
|
|
|
2. Start:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
- Public API: `http://localhost:15000/api/*`
|
|
- PostgreSQL + pgvector runs in `db` service on `localhost:5432`
|
|
|
|
Stop:
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
## Public API
|
|
|
|
- `POST /api/rag/sessions`
|
|
- `POST /api/rag/sessions/{rag_session_id}/changes`
|
|
- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}`
|
|
- `GET /api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events` (SSE progress)
|
|
- `POST /api/chat/dialogs`
|
|
- `POST /api/chat/messages`
|
|
- `GET /api/tasks/{task_id}`
|
|
- `GET /api/events?task_id=...`
|
|
- `POST /api/index/snapshot`
|
|
- `POST /api/index/changes`
|
|
- `GET /api/index/jobs/{index_job_id}`
|
|
- `GET /api/index/jobs/{index_job_id}/events` (legacy SSE progress)
|
|
|
|
RAG indexing SSE events (`/api/rag/sessions/{rag_session_id}/jobs/{index_job_id}/events`):
|
|
- `index_status`: `{"index_job_id","status","total_files",...}`
|
|
- `index_progress`: `{"index_job_id","current_file_index","total_files","processed_files","current_file_path","current_file_name"}`
|
|
- `terminal`: `{"index_job_id","status":"done|error",...}` (final event; stream closes after this event)
|
|
|
|
## Session Model
|
|
|
|
- `rag_session_id`: identifies indexed project chunks in RAG.
|
|
- `dialog_session_id`: identifies one independent dialog context within a `rag_session_id`.
|
|
- Multiple dialogs can share one `rag_session_id`.
|
|
|
|
Recommended flow:
|
|
1. call `POST /api/rag/sessions` after project selection;
|
|
2. wait for indexing job completion;
|
|
3. call `POST /api/chat/dialogs` with `rag_session_id`;
|
|
4. call `POST /api/chat/messages` with `dialog_session_id` + `rag_session_id`.
|
|
|
|
`/api/chat/messages` supports explicit routing hint:
|
|
- `mode: "auto" | "project_qa" | "project_edits" | "docs_generation" | "qa"`
|
|
- Legacy aliases are still accepted: `code_change`, `analytics_review`.
|
|
|
|
## Persistence
|
|
|
|
Persisted in PostgreSQL:
|
|
- `rag_sessions`, `rag_chunks`, `rag_index_jobs`
|
|
- `dialog_sessions`, `chat_messages`
|
|
- `router_context` (agent routing context per dialog session)
|
|
- LangGraph checkpoints via `PostgresSaver` (thread id = `dialog_session_id`)
|
|
|
|
Notes:
|
|
- RAG vectors are stored in `pgvector` column (`rag_chunks.embedding`).
|
|
- Agent context/history is restored after restart for same `dialog_session_id`.
|
|
|
|
## Agent Runtime
|
|
|
|
- Router + context store (`app/modules/agent/engine/router/*`)
|
|
- LangGraph flow execution (`app/modules/agent/engine/graphs/*`)
|
|
- Route selection:
|
|
- `default/general` -> answer flow
|
|
- `project/qa` -> answer flow
|
|
- `project/edits` -> conservative changeset flow for non-code file updates (hybrid output: `proposed_content` + `hunks`)
|
|
- `docs/generation` -> answer and/or changeset flow
|
|
- LLM provider: GigaChat (`chat/completions`)
|
|
- Prompts for graph LLM nodes: `app/modules/agent/prompts/*.txt`
|
|
- `general_answer.txt`
|
|
- `project_answer.txt`
|
|
- `project_edits_plan.txt`
|
|
- `project_edits_hunks.txt`
|
|
- `project_edits_self_check.txt`
|
|
- `docs_generation.txt`
|
|
- `docs_execution_summary.txt`
|
|
|
|
## Modules Structure
|
|
|
|
- `app/modules/chat/*`: chat API, tasks, session-scoped orchestration, event streaming.
|
|
- `app/modules/agent/*`: intent router, LangGraph flows, confluence integration, changeset validation.
|
|
- `app/modules/rag/*`: indexing API/jobs and retrieval service.
|
|
- `app/modules/shared/*`: cross-module primitives (event bus, retry, idempotency).
|
|
- `app/modules/contracts.py`: fixed inter-module contracts (`AgentRunner`, `RagRetriever`, `RagIndexer`).
|
|
|
|
## Module Boundaries
|
|
|
|
- `chat` depends on contract `AgentRunner`, but not on concrete `agent` internals.
|
|
- `agent` depends on contract `RagRetriever`, but not on `rag` indexing internals.
|
|
- `rag` exposes public/internal API and service implementation.
|
|
- wiring is centralized in `app/modules/application.py`.
|
|
|
|
## Internal API (for integration)
|
|
|
|
- `POST /internal/rag/index/snapshot`
|
|
- `POST /internal/rag/index/changes`
|
|
- `GET /internal/rag/index/jobs/{index_job_id}`
|
|
- `POST /internal/rag/retrieve`
|
|
- `POST /internal/tools/confluence/fetch`
|
|
|
|
## Environment
|
|
|
|
- `.env.example` contains full list of parameters.
|
|
- `.env` is used by Docker Compose for `db` and `backend`.
|
|
- `GIGACHAT_TOKEN`: Basic credentials for OAuth exchange (required for LLM/embeddings).
|
|
- `DATABASE_URL`: PostgreSQL DSN, default `postgresql+psycopg://agent:agent@db:5432/agent`.
|
|
- `GIGACHAT_AUTH_URL`: default `https://ngw.devices.sberbank.ru:9443/api/v2/oauth`.
|
|
- `GIGACHAT_API_URL`: default `https://gigachat.devices.sberbank.ru/api/v1`.
|
|
- `GIGACHAT_SCOPE`: default `GIGACHAT_API_PERS`.
|
|
- `GIGACHAT_SSL_VERIFY`: `true|false`, default `true`.
|
|
- `GIGACHAT_MODEL`: chat model name, default `GigaChat`.
|
|
- `GIGACHAT_EMBEDDING_MODEL`: embedding model name, default `Embeddings`.
|
|
- `AGENT_PROMPTS_DIR`: optional override path for prompt files.
|
|
|
|
Troubleshooting:
|
|
- If indexing shows `failed_files > 0` and `indexed_files = 0`, check backend logs for TLS/auth errors to GigaChat.
|
|
- In corporate environments with custom TLS chain, set `GIGACHAT_SSL_VERIFY=false` (or install proper CA certs in container).
|