agent/README.md

Agent Backend MVP

Run (Local)

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:

cp .env.example .env

Set GIGACHAT_TOKEN in .env.

2. Start:

docker compose up --build

• Public API: http://localhost:15000/api/*
• PostgreSQL + pgvector runs in db service on localhost:5432

Stop:

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).