# pbaniket/research_assistant architecture

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

- Interactive diagram: https://gitdiagram.com/pbaniket/research_assistant
- Repository: https://github.com/pbaniket/research_assistant

## Overview

1. **What this repo is**
   - A fully local, document-grounded Q&A system using a standard RAG pipeline.
   - It answers questions over PDFs stored on disk, without sending data to external APIs.

2. **Top-level architecture**
   - `app.py` is the entrypoint and orchestrator.
   - `processing.py` owns offline document ingestion and index creation.
   - `qa.py` owns online question answering: retrieval, prompt assembly, and response generation.
   - `config.py` centralizes paths and runtime settings.

3. **Offline ingestion boundary**
   - The first major subsystem is the document pipeline.
   - PDFs are loaded from a local `docs/` folder, cleaned, split into overlapping chunks, embedded, and written into a FAISS index under `faiss_index/`.
   - This stage is meant to happen once or whenever the source documents change.

4. **Document preprocessing flow**
   - Source: local PDF files.
   - Processing: page-level loading, text cleanup, chunking with overlap to preserve context across boundaries.
   - Output: chunk metadata plus embeddings suitable for retrieval.
   - The design keeps page/document provenance so answers can cite source document and page number.

5. **Indexing and persistence**
   - FAISS is the persistent retrieval layer.
   - The vector index is cached locally so startup does not require rebuilding embeddings every time.
   - This makes the system stateful across runs, but only through local files.

6. **Online question-answering flow**
   - User input enters through the chat UI and is handled by the QA subsystem.
   - The question is embedded, matched against FAISS, and the most relevant chunks are pulled as context.
   - That retrieved context is inserted into a prompt template along with the question.
   - The local LLM generates an answer constrained to the retrieved context.

7. **Model runtime boundary**
   - The generative model runs locally in GGUF format via llama.cpp-compatible tooling.
   - The embedding model is separate from the generator: sentence-transformer embeddings for retrieval, Gemma-2 for answer synthesis.
   - This separation is important architecturally because retrieval and generation have different compute roles and dependency stacks.

8. **User interface and interaction**
   - Gradio provides the chat UI and serves the local web app.
   - `app.py` likely wires the UI callback to the QA pipeline and initializes the index if needed before launching the server.
   - The UI is thin; it does not own business logic.

9. **Configuration and portability**
   - `config.py` holds project-relative paths for documents, models, and index storage.
   - This makes the repo portable across OSes and local setups, because the runtime is driven by filesystem layout rather than hard-coded machine-specific paths.

10. **Data boundaries**
   - Input boundary: local PDFs in `docs/`.
   - Working boundary: chunked text and embeddings in memory during processing.
   - Persistent boundary: FAISS index on disk in `faiss_index/`.
   - Runtime boundary: model files in `models/` and the Gradio server process.

11. **Technology footprint that matters architecturally**
   - LangChain provides the RAG plumbing and likely document/loading abstractions.
   - FAISS provides fast nearest-neighbor retrieval.
   - Sentence-Transformers provides the retrieval embeddings.
   - Gradio provides the local interactive front end.
   - Llama.cpp enables local inference from a GGUF model file.

12. **How to diagram it**
   - Draw two phases: an offline indexing pipeline and an online chat pipeline.
   - Show local PDFs feeding ingestion, then a cached FAISS store.
   - Show user queries entering Gradio, flowing to retrieval in FAISS, then to the local LLM, and finally back to the UI with citations.
   - Emphasize that all compute and storage remain local to the machine.

Main entry points: [`app.py`](https://github.com/pbaniket/research_assistant/blob/main/app.py) (App), [`qa.py`](https://github.com/pbaniket/research_assistant/blob/main/qa.py) (QA), [`processing.py`](https://github.com/pbaniket/research_assistant/blob/main/processing.py) (Ingestion), [`config.py`](https://github.com/pbaniket/research_assistant/blob/main/config.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_offline["Offline indexing"]
  node_processing["Ingestion<br/>pipeline<br/>[processing.py]"]
  node_pdfs["Local PDFs<br/>source"]
  node_clean_chunk["Clean & split<br/>transform"]
  node_embedder{{"Embed docs<br/>embedding model"}}
  node_faiss[("FAISS store<br/>vector index")]
end

subgraph group_online["Online QA"]
  node_qa["QA<br/>pipeline<br/>[qa.py]"]
  node_chat_ui["Gradio UI<br/>web ui"]
  node_query_embed{{"Query embedder<br/>embedding model"}}
  node_retriever["Retriever<br/>search"]
  node_prompt["Prompt builder<br/>prompting"]
  node_llm{{"Local LLM<br/>generator"}}
  node_answer["Answer<br/>output"]
end

node_app["App<br/>entrypoint<br/>[app.py]"]
node_config["Config<br/>settings<br/>[config.py]"]

node_app -->|"loads settings"| node_config
node_app -->|"initializes index"| node_processing
node_app -->|"starts UI"| node_chat_ui
node_pdfs -->|"documents"| node_processing
node_processing -->|"prepares text"| node_clean_chunk
node_clean_chunk -->|"chunk embeddings"| node_embedder
node_embedder -->|"stores vectors"| node_faiss
node_faiss -->|"search corpus"| node_retriever
node_chat_ui -->|"user question"| node_qa
node_qa -->|"embed query"| node_query_embed
node_query_embed -->|"similarity search"| node_retriever
node_retriever -->|"context"| node_prompt
node_qa -->|"assemble prompt"| node_prompt
node_prompt -->|"generate answer"| node_llm
node_llm -->|"response"| node_answer
node_answer -->|"display"| node_chat_ui

click node_app "https://github.com/pbaniket/research_assistant/blob/main/app.py"
click node_config "https://github.com/pbaniket/research_assistant/blob/main/config.py"
click node_processing "https://github.com/pbaniket/research_assistant/blob/main/processing.py"
click node_qa "https://github.com/pbaniket/research_assistant/blob/main/qa.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_processing,node_pdfs,node_clean_chunk,node_embedder,node_faiss toneBlue
class node_qa,node_chat_ui,node_query_embed,node_retriever,node_prompt,node_llm,node_answer toneAmber
class node_app,node_config toneNeutral
```

## Components

### Offline indexing

Local document ingestion and FAISS index creation

- [Ingestion](https://github.com/pbaniket/research_assistant/blob/main/processing.py): pipeline · Loads PDFs, cleans text, chunks content, and builds embeddings · `processing.py`
- **Local PDFs**: source · Input document set stored on disk
- **Clean & split**: transform · Text cleanup and overlapping chunking with provenance
- **Embed docs**: embedding model · Sentence-transformer embeddings for document chunks
- **FAISS store**: vector index · Persistent local retrieval index for chunks and metadata

### Online QA

Interactive retrieval and local answer generation

- [QA](https://github.com/pbaniket/research_assistant/blob/main/qa.py): pipeline · Retrieves context, builds prompts, and generates answers · `qa.py`
- **Gradio UI**: web ui · Thin local chat interface for user questions
- **Query embedder**: embedding model · Embeds the user question for similarity search
- **Retriever**: search · Finds the most relevant chunks in FAISS
- **Prompt builder**: prompting · Assembles retrieved context and the question into an answer prompt
- **Local LLM**: generator · GGUF llama.cpp-compatible model for grounded answer synthesis
- **Answer**: output · Returns the response with source-grounded context

### Other components

- [App](https://github.com/pbaniket/research_assistant/blob/main/app.py): entrypoint · Launches the local server and wires the main flows · `app.py`
- [Config](https://github.com/pbaniket/research_assistant/blob/main/config.py): settings · Central paths and runtime settings · `config.py`

## Connections

- App → Config: loads settings · Reads project paths and runtime configuration
- App → Ingestion: initializes index · Ensures the local vector store exists before serving
- App → Gradio UI: starts UI · Launches the local Gradio application
- Local PDFs → Ingestion: documents · Source PDFs are ingested from disk
- Ingestion → Clean & split: prepares text · Cleans pages and splits them into overlapping chunks
- Clean & split → Embed docs: chunk embeddings · Creates dense representations for each chunk
- Embed docs → FAISS store: stores vectors · Persists embeddings and metadata into FAISS
- FAISS store → Retriever: search corpus · Provides nearest-neighbor lookup over indexed chunks
- Gradio UI → QA: user question · Sends the user prompt into the QA pipeline
- QA → Query embedder: embed query · Encodes the question for retrieval
- Query embedder → Retriever: similarity search · Uses the query vector to find relevant chunks
- Retriever → Prompt builder: context · Passes top matching chunks and provenance
- QA → Prompt builder: assemble prompt · Combines question and retrieved context
- Prompt builder → Local LLM: generate answer · Feeds the grounded prompt to the local model
- Local LLM → Answer: response · Produces the final answer text
- Answer → Gradio UI: display · Returns the answer back to the chat interface
