# sruthisree11/ncert-q-a-bot architecture

> Architecture diagram of the GitHub repository sruthisree11/ncert-q-a-bot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sruthisree11/ncert-q-a-bot
- Repository: https://github.com/sruthisree11/ncert-q-a-bot

## Overview

#### Purpose and Entry Points
This is a local, CLI-based RAG assistant for answering questions over NCERT textbook PDFs. It has two operational entry points:
- Offline corpus ingestion/index construction: `src/build_vector_store.py`
- Interactive retrieval and answer generation: `src/qa_cli.py`

#### Source Corpus and Persistent Knowledge Store
PDFs are the authoritative document corpus under `data/pdfs/`, currently including NCERT files such as `data/pdfs/hesc106.pdf`. The build stage converts this corpus into two coupled local artifacts:
- Serialized chunk metadata/text: `data/chunks.pkl`
- FAISS nearest-neighbor index: `data/chunks_index.faiss`

The index and pickle must remain aligned: FAISS retrieves vector positions, while the pickle provides the corresponding textual context.

#### Ingestion and Index-Build Pipeline
`src/build_vector_store.py` is the batch pipeline boundary between raw documents and retrievable knowledge. It:
1. Reads PDFs from `data/pdfs/`.
2. Extracts document text via a PDF library.
3. Splits text into semantic chunks.
4. Creates embeddings.
5. Persists chunks and the FAISS index to `data/chunks.pkl` and `data/chunks_index.faiss`.

Rebuilding the store is required when PDFs or chunking/embedding behavior changes.

#### Retrieval and Answering Pipeline
`src/qa_cli.py` is the runtime application. It accepts a natural-language question from the terminal, loads the local FAISS index and chunk collection, embeds the question, and retrieves the most relevant chunks. Retrieved passages become the grounding context for Gemini rather than being answered solely from the model’s general knowledge.

The control flow is: user question → query embedding → FAISS similarity search → retrieved chunk context → prompt assembly → Gemini response → terminal output.

#### Prompt Boundary
`prompts/qa_prompt.txt` defines the answer-generation prompt template. It is the principal policy/context boundary between deterministic local retrieval and the external generative model. Changes here can alter how retrieved textbook excerpts are presented, how strictly answers follow context, and the final response format without rebuilding the vector store.

#### External Services and Runtime Dependencies
The system runs on Python 3 with local FAISS CPU search and local persisted artifacts. Google Gemini is the external generation service, authenticated through `GEMINI_API_KEY` loaded from a root `.env` file. Relevant dependency expectations are declared in `requirements.txt`, including FAISS, PDF extraction, dotenv, and Google’s generative AI SDK.

#### Architectural Constraints
The repository is intentionally single-machine and file-backed: no web server, database, queue, or remote vector database is present. Index construction and question answering are separate commands, allowing query-time execution to avoid PDF parsing and index generation. Data quality depends on readable PDFs and successful extraction from `data/pdfs/`.

Main entry points: [`src/build_vector_store.py`](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/build_vector_store.py) (Build vector store), [`src/qa_cli.py`](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/qa_cli.py) (QA CLI), [`data/chunks.pkl`](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/data/chunks.pkl) (Chunk collection), [`requirements.txt`](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/requirements.txt) (Python dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Offline index build"]
  node_build_cli["Build vector store<br/>Python batch CLI"]
  node_pdf_extraction["PDF text extraction<br/>pipeline stage"]
  node_semantic_chunking["Semantic chunking<br/>pipeline stage"]
  node_document_embeddings["Document embeddings<br/>pipeline stage"]
end

subgraph group_runtime["Interactive QA"]
  node_qa_cli["QA CLI<br/>Python interactive CLI<br/>[qa_cli.py]"]
  node_terminal_user(("Terminal user<br/>CLI input/output"))
  node_query_embedding["Query embedding<br/>runtime stage"]
  node_similarity_search["FAISS similarity search<br/>runtime stage"]
  node_prompt_template["QA prompt template<br/>prompt policy<br/>[qa_prompt.txt]"]
  node_prompt_assembly["Grounded prompt assembly<br/>runtime stage"]
end

subgraph group_storage["Local files"]
  node_pdf_corpus["NCERT PDFs<br/>source corpus"]
  node_chunks[("Chunk collection<br/>serialized metadata<br/>[chunks.pkl]")]
  node_faiss_index[("FAISS index<br/>local vector index<br/>[chunks_index.faiss]")]
end

subgraph group_external["External service"]
  node_gemini{{"Google Gemini<br/>generation API"}}
  node_environment["Gemini API key<br/>environment configuration"]
end

node_dependencies["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]

node_pdf_corpus -->|"reads"| node_build_cli
node_build_cli -->|"extracts"| node_pdf_extraction
node_pdf_extraction -->|"text"| node_semantic_chunking
node_semantic_chunking -->|"chunks"| node_document_embeddings
node_semantic_chunking -->|"persists text and metadata"| node_chunks
node_document_embeddings -->|"builds vectors"| node_faiss_index
node_terminal_user -->|"question"| node_qa_cli
node_qa_cli -->|"embeds query"| node_query_embedding
node_query_embedding -->|"query vector"| node_similarity_search
node_faiss_index -->|"loads and searches"| node_similarity_search
node_similarity_search -->|"retrieved positions"| node_chunks
node_chunks -->|"retrieved passages"| node_prompt_assembly
node_prompt_template -->|"template"| node_prompt_assembly
node_prompt_assembly -->|"grounded prompt"| node_gemini
node_environment -.->|"authenticates"| node_gemini
node_gemini -->|"answer"| node_terminal_user
node_dependencies -.->|"runtime packages"| node_build_cli
node_dependencies -.->|"runtime packages"| node_qa_cli

click node_build_cli "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/build_vector_store.py"
click node_chunks "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/data/chunks.pkl"
click node_faiss_index "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/data/chunks_index.faiss"
click node_qa_cli "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/qa_cli.py"
click node_prompt_template "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/prompts/qa_prompt.txt"
click node_dependencies "https://github.com/sruthisree11/ncert-q-a-bot/blob/main/requirements.txt"

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_build_cli,node_pdf_extraction,node_semantic_chunking,node_document_embeddings toneBlue
class node_qa_cli,node_terminal_user,node_query_embedding,node_similarity_search,node_prompt_template,node_prompt_assembly toneAmber
class node_pdf_corpus,node_chunks,node_faiss_index toneMint
class node_gemini,node_environment toneRose
class node_dependencies toneNeutral
```

## Components

### Offline index build

Batch conversion of PDFs into aligned retrieval artifacts.

- [Build vector store](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/build_vector_store.py): Python batch CLI · Offline ingestion entry point. · `src/build_vector_store.py`
- **PDF text extraction**: pipeline stage
- **Semantic chunking**: pipeline stage
- **Document embeddings**: pipeline stage

### Interactive QA

CLI retrieval and answer-generation flow.

- [QA CLI](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/src/qa_cli.py): Python interactive CLI · Runtime question-answering entry point. · `src/qa_cli.py`
- **Terminal user**: CLI input/output
- **Query embedding**: runtime stage
- **FAISS similarity search**: runtime stage
- [QA prompt template](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/prompts/qa_prompt.txt): prompt policy · Controls grounding and answer format without rebuilding the index. · `prompts/qa_prompt.txt`
- **Grounded prompt assembly**: runtime stage

### Local files

Single-machine corpus and persistent knowledge store.

- **NCERT PDFs**: source corpus · Authoritative textbook documents.
- [Chunk collection](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/data/chunks.pkl): serialized metadata · Text and metadata aligned to FAISS vector positions. · `data/chunks.pkl`
- [FAISS index](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/data/chunks_index.faiss): local vector index · `data/chunks_index.faiss`

### External service

- **Google Gemini**: generation API · External grounded answer generation.
- **Gemini API key**: environment configuration

### Other components

- [Python dependencies](https://github.com/sruthisree11/ncert-q-a-bot/blob/main/requirements.txt): dependency manifest · Declares FAISS, PDF, dotenv, and Gemini SDK dependencies. · `requirements.txt`

## Connections

- NCERT PDFs → Build vector store: reads
- Build vector store → PDF text extraction: extracts
- PDF text extraction → Semantic chunking: text
- Semantic chunking → Document embeddings: chunks
- Semantic chunking → Chunk collection: persists text and metadata
- Document embeddings → FAISS index: builds vectors
- Terminal user → QA CLI: question
- QA CLI → Query embedding: embeds query
- Query embedding → FAISS similarity search: query vector
- FAISS index → FAISS similarity search: loads and searches
- FAISS similarity search → Chunk collection: retrieved positions
- Chunk collection → Grounded prompt assembly: retrieved passages
- QA prompt template → Grounded prompt assembly: template
- Grounded prompt assembly → Google Gemini: grounded prompt
- Gemini API key → Google Gemini: authenticates
- Google Gemini → Terminal user: answer
- Python dependencies → Build vector store: runtime packages
- Python dependencies → QA CLI: runtime packages