staspog/s21_agent

Purpose and entry points

This is a Python RAG assistant for S21 School project documentation. It retrieves relevant text chunks with SentenceTransformers + FAISS and asks GigaChat to generate an answer grounded in that context.

Primary runnable entry point is the FastAPI service in src/api.py, launched with Uvicorn. src/old_prototype_main.py is a legacy console-oriented implementation rather than the documented src/main.py, which is absent from the tree. src/test_client.py is the available HTTP client/script.

API boundary

src/api.py owns the HTTP-facing application and /ask/ question workflow. It should be treated as the stateless request boundary: accept a user question, invoke retrieval/generation services, and return the generated response.

The server is containerizable through Dockerfile; it runs as a Python service rather than a browser application.

Knowledge corpus and persisted retrieval state

The repository ships precomputed retrieval artifacts under:

• content/chunks.json

• content/chunks_map.json

• content/chunks.index

These files are the material knowledge boundary. chunks.json stores chunk content or records, chunks_map.json maps FAISS result positions to chunk metadata/content, and chunks.index is the persisted FAISS vector index. Runtime retrieval can therefore avoid re-ingesting source documentation when these artifacts are present.

Ingestion and chunk preparation

src/data_loader.py is responsible for loading source material and/or persisted chunk data. It forms the transition from filesystem documents to normalized text chunks suitable for embedding and retrieval.

The README describes .md and .txt source ingestion, but the checked-in tree contains only generated artifacts in content/; there is no visible content/data/ directory. Any corpus rebuild path must account for that deployment distinction.

Embedding and vector indexing

src/embeddings.py encapsulates SentenceTransformers embedding creation and FAISS index construction/loading. This component defines the vector representation shared by both corpus indexing and query-time search.

Its output is persisted to content/chunks.index, with positional association maintained by content/chunks_map.json. Embedding-model compatibility with an existing index is an important operational boundary: changing the model requires regenerating the index and mappings.

Retrieval

src/search.py performs similarity search against the FAISS index and resolves nearest-neighbor IDs through the chunk mapping. It is the context-selection stage between incoming questions and the LLM.

Control flow is expected to be: API question → query embedding → FAISS top-k search → matched text chunks. Retrieval quality and context size directly constrain answer quality and GigaChat prompt size.

Generation and external service integration

src/gigachat_api.py isolates calls to the external GigaChat API. It receives the user question plus retrieved context and returns a generated answer.

Authentication is supplied via GIGACHAT_API_KEY, normally loaded from environment/.env. This is the principal network and secret-management boundary; FAISS and corpus artifacts remain local, while answer generation depends on GigaChat availability and credentials.

Runtime dependencies

The material runtime is Python 3.10 with sentence-transformers, faiss-cpu, gigachat, FastAPI, and Uvicorn declared in requirements.txt. Deployment needs local access to content/ artifacts and outbound connectivity to GigaChat.