# staspog/s21_agent architecture

> Architecture diagram of the GitHub repository staspog/s21_agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/staspog/s21_agent
- Repository: https://github.com/staspog/s21_agent

## Overview

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

Main entry points: [`src/search.py`](https://github.com/staspog/s21_agent/blob/main/src/search.py) (Similarity search), [`src/gigachat_api.py`](https://github.com/staspog/s21_agent/blob/main/src/gigachat_api.py) (GigaChat adapter), [`src/embeddings.py`](https://github.com/staspog/s21_agent/blob/main/src/embeddings.py) (Embeddings and FAISS), [`src/api.py`](https://github.com/staspog/s21_agent/blob/main/src/api.py) (FastAPI /ask)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_container["Docker service<br/>container runtime"]
  node_api["FastAPI /ask<br/>HTTP API<br/>[api.py]"]
  node_client["HTTP client script<br/>[test_client.py]"]
  node_dependencies["Python dependencies<br/>runtime dependencies<br/>[requirements.txt]"]
  node_legacy_prototype["Legacy console prototype<br/>legacy entry point"]
end

subgraph group_retrieval["Retrieval pipeline"]
  node_loader["Data loader<br/>ingestion<br/>[data_loader.py]"]
  node_embeddings["Embeddings and FAISS<br/>vector indexing<br/>[embeddings.py]"]
  node_search["Similarity search<br/>retrieval<br/>[search.py]"]
end

subgraph group_knowledge["Knowledge artifacts"]
  node_chunks["Chunk content<br/>corpus artifact<br/>[chunks.json]"]
  node_chunk_map["Chunk mapping<br/>retrieval mapping<br/>[chunks_map.json]"]
  node_faiss_index[("FAISS index<br/>vector store<br/>[chunks.index]")]
end

subgraph group_external["External generation"]
  node_gigachat_adapter["GigaChat adapter<br/>LLM integration<br/>[gigachat_api.py]"]
  node_gigachat{{"GigaChat API<br/>external LLM"}}
  node_api_key["GIGACHAT_API_KEY<br/>credential"]
end

node_client -->|"POST question"| node_api
node_container -->|"runs"| node_api
node_dependencies -.->|"installed in"| node_container
node_api -->|"question"| node_search
node_search -->|"query embedding"| node_embeddings
node_search -->|"top-k search"| node_faiss_index
node_search -->|"resolve results"| node_chunk_map
node_search -->|"question and context"| node_gigachat_adapter
node_gigachat_adapter -->|"generate answer"| node_gigachat
node_gigachat -->|"answer"| node_gigachat_adapter
node_gigachat_adapter -.->|"authenticates with"| node_api_key
node_gigachat_adapter -->|"generated response"| node_api
node_loader -->|"loads or produces"| node_chunks
node_loader -->|"normalized chunks"| node_embeddings
node_embeddings -->|"builds or loads"| node_faiss_index
node_embeddings -->|"maintains positions"| node_chunk_map
node_chunks -.->|"chunk records"| node_chunk_map

click node_container "https://github.com/staspog/s21_agent/blob/main/Dockerfile"
click node_api "https://github.com/staspog/s21_agent/blob/main/src/api.py"
click node_client "https://github.com/staspog/s21_agent/blob/main/src/test_client.py"
click node_loader "https://github.com/staspog/s21_agent/blob/main/src/data_loader.py"
click node_embeddings "https://github.com/staspog/s21_agent/blob/main/src/embeddings.py"
click node_search "https://github.com/staspog/s21_agent/blob/main/src/search.py"
click node_chunks "https://github.com/staspog/s21_agent/blob/main/content/chunks.json"
click node_chunk_map "https://github.com/staspog/s21_agent/blob/main/content/chunks_map.json"
click node_faiss_index "https://github.com/staspog/s21_agent/blob/main/content/chunks.index"
click node_gigachat_adapter "https://github.com/staspog/s21_agent/blob/main/src/gigachat_api.py"
click node_dependencies "https://github.com/staspog/s21_agent/blob/main/requirements.txt"
click node_legacy_prototype "https://github.com/staspog/s21_agent/blob/main/src/old_prototype_main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_container,node_api,node_client,node_dependencies,node_legacy_prototype toneBlue
class node_loader,node_embeddings,node_search toneAmber
class node_chunks,node_chunk_map,node_faiss_index toneMint
class node_gigachat_adapter,node_gigachat,node_api_key toneRose
```

## Components

### Runtime

- [Docker service](https://github.com/staspog/s21_agent/blob/main/Dockerfile): container runtime · Runs the Python API service. · `Dockerfile`
- [FastAPI /ask](https://github.com/staspog/s21_agent/blob/main/src/api.py): HTTP API · Stateless question request boundary. · `src/api.py`
- [HTTP client script](https://github.com/staspog/s21_agent/blob/main/src/test_client.py): client · `src/test_client.py`
- [Python dependencies](https://github.com/staspog/s21_agent/blob/main/requirements.txt): runtime dependencies · Python 3.10, FastAPI, SentenceTransformers, FAISS, and GigaChat. · `requirements.txt`
- [Legacy console prototype](https://github.com/staspog/s21_agent/blob/main/src/old_prototype_main.py): legacy entry point · Not the documented service entry point. · `src/old_prototype_main.py`

### Retrieval pipeline

- [Data loader](https://github.com/staspog/s21_agent/blob/main/src/data_loader.py): ingestion · Loads source material or persisted chunks. · `src/data_loader.py`
- [Embeddings and FAISS](https://github.com/staspog/s21_agent/blob/main/src/embeddings.py): vector indexing · Creates embeddings and constructs or loads the vector index. · `src/embeddings.py`
- [Similarity search](https://github.com/staspog/s21_agent/blob/main/src/search.py): retrieval · Embeds questions, searches FAISS, and resolves matched chunks. · `src/search.py`

### Knowledge artifacts

- [Chunk content](https://github.com/staspog/s21_agent/blob/main/content/chunks.json): corpus artifact · `content/chunks.json`
- [Chunk mapping](https://github.com/staspog/s21_agent/blob/main/content/chunks_map.json): retrieval mapping · Maps FAISS positions to chunk metadata or content. · `content/chunks_map.json`
- [FAISS index](https://github.com/staspog/s21_agent/blob/main/content/chunks.index): vector store · Persisted index requiring compatible embeddings. · `content/chunks.index`

### External generation

- [GigaChat adapter](https://github.com/staspog/s21_agent/blob/main/src/gigachat_api.py): LLM integration · Builds grounded requests from question and retrieved context. · `src/gigachat_api.py`
- **GigaChat API**: external LLM · Requires outbound access and API credentials.
- **GIGACHAT_API_KEY**: credential · Environment or .env supplied secret.

## Connections

- HTTP client script → FastAPI /ask: POST question
- Docker service → FastAPI /ask: runs
- Python dependencies → Docker service: installed in
- FastAPI /ask → Similarity search: question
- Similarity search → Embeddings and FAISS: query embedding
- Similarity search → FAISS index: top-k search
- Similarity search → Chunk mapping: resolve results
- Similarity search → GigaChat adapter: question and context
- GigaChat adapter → GigaChat API: generate answer
- GigaChat API → GigaChat adapter: answer
- GigaChat adapter → GIGACHAT_API_KEY: authenticates with
- GigaChat adapter → FastAPI /ask: generated response
- Data loader → Chunk content: loads or produces
- Data loader → Embeddings and FAISS: normalized chunks
- Embeddings and FAISS → FAISS index: builds or loads
- Embeddings and FAISS → Chunk mapping: maintains positions
- Chunk content → Chunk mapping: chunk records