# fijasmhd/python-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/fijasmhd/python-tutor
- Repository: https://github.com/fijasmhd/python-tutor

## Overview

1. **What this repo is**
   - This is a Python-based **RAG tutoring app** for Python questions.
   - Its main architecture is split into three parts: a **Streamlit chat UI**, a **LangGraph-based answer pipeline**, and an **offline ingestion/indexing pipeline**.

2. **Main entry points**
   - `app.py` is the user-facing entry point; it runs the Streamlit interface and hands user prompts into the RAG workflow.
   - `rag_agent.py` contains the core orchestration logic: retrieval, answer generation, grading, and retry/rewrite behavior.
   - `ingest.py` builds and refreshes the knowledge index from files in `docs/`.

3. **Knowledge base and indexing boundary**
   - The only visible source document is `docs/python_basics.txt`, which acts as the repository’s knowledge base.
   - `ingest.py` turns those text documents into chunks, embeds them, and stores them in Chroma.
   - This is an offline/administrative path, separate from live question answering.

4. **Persistent vector store**
   - `chroma_db/` is the local persistent ChromaDB store.
   - The presence of `chroma.sqlite3` plus binary segment files indicates the app uses **embedded local persistence**, not a remote database service.
   - At runtime, retrieval reads from this local store to fetch semantically similar chunks.

5. **Runtime request flow**
   - User asks a question in Streamlit.
   - `rag_agent.py` retrieves relevant chunks from Chroma.
   - A generation model produces an answer using only retrieved context.
   - A separate grading step evaluates whether the answer is grounded and relevant.

6. **Self-healing control loop**
   - This repo’s key architectural feature is the retry loop in the LangGraph workflow.
   - If grading fails, the system rewrites the question, retrieves again, regenerates, and regrades.
   - The loop stops when the answer passes or when a retry limit is reached, at which point a fallback response is returned.

7. **Model separation**
   - The README describes distinct LLM roles:
     - **Generator**: produces the final answer
     - **Grader**: checks grounding/support in retrieved context
     - **Rewriter**: reformulates ambiguous or weak queries
   - This separation is important architecturally because quality control is not left to a single prompt/model call.

8. **External services and dependencies**
   - The system uses the **Groq API** for LLM inference, so inference is external rather than local.
   - Embeddings are generated during ingestion, with the stack described as including **Sentence Transformers** / LangChain-style embedding integration.
   - `pyproject.toml` and `uv.lock` define the Python dependency set; `.python-version` suggests the project is intended to be run with a pinned Python version.

9. **Data ownership and boundaries**
   - The app does not appear to manage user accounts, long-term chat history, or a backend database beyond the vector store.
   - All persistent domain knowledge lives in `docs/` and `chroma_db/`.
   - User interaction state is transient in the Streamlit session, while indexed knowledge persists on disk.

10. **Operational picture**
   - The repo has a clear split between **build time** and **serve time**:
     - build time: run `ingest.py` to populate `chroma_db`
     - serve time: run `app.py` to answer questions
   - For an architecture diagram, show the user facing UI, the LangGraph workflow engine in the middle, the local Chroma persistence layer behind retrieval, and Groq as the external inference service.

Main entry points: [`rag_agent.py`](https://github.com/fijasmhd/python-tutor/blob/main/rag_agent.py) (RAG Agent), [`ingest.py`](https://github.com/fijasmhd/python-tutor/blob/main/ingest.py) (Ingestion), [`chroma_db/chroma.sqlite3`](https://github.com/fijasmhd/python-tutor/blob/main/chroma_db/chroma.sqlite3) (Chroma store), [`app.py`](https://github.com/fijasmhd/python-tutor/blob/main/app.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serve["Serve time"]
  node_app["Streamlit UI<br/>entrypoint<br/>[app.py]"]
  node_agent{{"RAG Agent<br/>workflow<br/>[rag_agent.py]"}}
  node_retrieve["Retriever<br/>retrieval"]
  node_generator["Generator<br/>llm step"]
  node_grader["Grader<br/>quality gate"]
  node_rewriter["Rewriter<br/>query transform"]
  node_fallback["Fallback reply<br/>response"]
end

subgraph group_build["Build time"]
  node_ingest{{"Ingestion<br/>pipeline<br/>[ingest.py]"}}
  node_chunks["Text chunks<br/>preprocess"]
  node_embeddings["Embeddings<br/>vectorization"]
  node_deps["Python stack<br/>tooling<br/>[pyproject.toml]"]
end

subgraph group_data["Knowledge store"]
  node_docs["Docs source<br/>corpus<br/>[python_basics.txt]"]
  node_chroma[("Chroma store<br/>vector db<br/>[chroma.sqlite3]")]
  node_segments[("Index segments<br/>persistence<br/>[data_level0.bin]")]
end

subgraph group_external["External services"]
  node_groq(("Groq API<br/>external llm"))
end

node_app -->|"send prompt"| node_agent
node_agent -->|"retrieve"| node_retrieve
node_retrieve -->|"read index"| node_chroma
node_agent -->|"generate"| node_generator
node_generator -->|"llm call"| node_groq
node_agent -->|"grade"| node_grader
node_grader -->|"llm call"| node_groq
node_agent -.->|"retry path"| node_rewriter
node_rewriter -->|"llm call"| node_groq
node_agent -.->|"give up"| node_fallback
node_ingest -->|"source docs"| node_docs
node_ingest -->|"chunk"| node_chunks
node_chunks -->|"embed"| node_embeddings
node_embeddings -->|"persist"| node_chroma
node_chroma -->|"backing files"| node_segments
node_ingest -.->|"uses"| node_deps

click node_app "https://github.com/fijasmhd/python-tutor/blob/main/app.py"
click node_agent "https://github.com/fijasmhd/python-tutor/blob/main/rag_agent.py"
click node_ingest "https://github.com/fijasmhd/python-tutor/blob/main/ingest.py"
click node_docs "https://github.com/fijasmhd/python-tutor/blob/main/docs/python_basics.txt"
click node_chroma "https://github.com/fijasmhd/python-tutor/blob/main/chroma_db/chroma.sqlite3"
click node_segments "https://github.com/fijasmhd/python-tutor/blob/main/chroma_db/8d43fc8b-fb72-4503-b1c3-85fcc0959b7a/data_level0.bin"
click node_deps "https://github.com/fijasmhd/python-tutor/blob/main/pyproject.toml"

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_app,node_agent,node_retrieve,node_generator,node_grader,node_rewriter,node_fallback toneBlue
class node_ingest,node_chunks,node_embeddings,node_deps toneAmber
class node_docs,node_chroma,node_segments toneMint
class node_groq toneRose
```

## Components

### Serve time

Interactive question answering path

- [Streamlit UI](https://github.com/fijasmhd/python-tutor/blob/main/app.py): entrypoint · User-facing chat interface and session state · `app.py`
- [RAG Agent](https://github.com/fijasmhd/python-tutor/blob/main/rag_agent.py): workflow · LangGraph orchestration for retrieval, generation, grading, and retries · `rag_agent.py`
- **Retriever**: retrieval · Fetches semantically similar chunks from the local vector store
- **Generator**: llm step · Produces grounded answers from retrieved context
- **Grader**: quality gate · Checks relevance and grounding of generated answers
- **Rewriter**: query transform · Refines weak or ambiguous questions before retrying
- **Fallback reply**: response · Returned when retries are exhausted or grading keeps failing

### Build time

Offline ingestion and indexing path

- [Ingestion](https://github.com/fijasmhd/python-tutor/blob/main/ingest.py): pipeline · Offline document chunking, embedding, and index refresh · `ingest.py`
- **Text chunks**: preprocess · Chunked document segments prepared for embedding
- **Embeddings**: vectorization · Vector representations generated during ingestion
- [Python stack](https://github.com/fijasmhd/python-tutor/blob/main/pyproject.toml): tooling · Project dependency set and pinned runtime version · `pyproject.toml`

### Knowledge store

Persistent local documents and vector index

- [Docs source](https://github.com/fijasmhd/python-tutor/blob/main/docs/python_basics.txt): corpus · Authoritative Python basics text used as the knowledge base · `docs/python_basics.txt`
- [Chroma store](https://github.com/fijasmhd/python-tutor/blob/main/chroma_db/chroma.sqlite3): vector db · Local persistent vector index used at runtime for retrieval · `chroma_db/chroma.sqlite3`
- [Index segments](https://github.com/fijasmhd/python-tutor/blob/main/chroma_db/8d43fc8b-fb72-4503-b1c3-85fcc0959b7a/data_level0.bin): persistence · Binary Chroma segment files backing the local store · `chroma_db/8d43fc8b-fb72-4503-b1c3-85fcc0959b7a/data_level0.bin`

### External services

LLM and embedding providers

- **Groq API**: external llm · Hosted inference used for generation, grading, and rewriting

## Connections

- Streamlit UI → RAG Agent: send prompt · Streamlit hands user questions into the RAG workflow
- RAG Agent → Retriever: retrieve · Workflow requests relevant context for the current query
- Retriever → Chroma store: read index · Retriever queries the persistent local vector store
- RAG Agent → Generator: generate · Workflow asks the generator to draft an answer from context
- Generator → Groq API: llm call · Answer generation is performed through the external Groq service
- RAG Agent → Grader: grade · Workflow validates grounding and relevance of the draft answer
- Grader → Groq API: llm call · Grading is also delegated to the external model service
- RAG Agent → Rewriter: retry path · Failed grading can trigger query rewriting before another attempt
- Rewriter → Groq API: llm call · Reformulation uses the external model service
- RAG Agent → Fallback reply: give up · Returns a fallback response when retries are exhausted
- Ingestion → Docs source: source docs · Offline pipeline starts from the Python basics text corpus
- Ingestion → Text chunks: chunk · Documents are split into retrievable segments
- Text chunks → Embeddings: embed · Chunk vectors are created during indexing
- Embeddings → Chroma store: persist · Embedded chunks are stored in the local vector database
- Chroma store → Index segments: backing files · Persistent index data is maintained on disk segments
- Ingestion → Python stack: uses · Build and runtime behavior depend on the pinned Python package stack
