How fijasmhd/python-tutor works
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 RAG Agent · ingest.py Ingestion · chroma.sqlite3 Chroma store · app.py Streamlit UI
Components 15
Serve time
Interactive question answering path
- Streamlit UI · User-facing chat interface and session state
app.py - RAG Agent · LangGraph orchestration for retrieval, generation, grading, and retries
rag_agent.py - Retriever · Fetches semantically similar chunks from the local vector store
- Generator · Produces grounded answers from retrieved context
- Grader · Checks relevance and grounding of generated answers
- Rewriter · Refines weak or ambiguous questions before retrying
- Fallback reply · Returned when retries are exhausted or grading keeps failing
Build time
Offline ingestion and indexing path
- Ingestion · Offline document chunking, embedding, and index refresh
ingest.py - Text chunks · Chunked document segments prepared for embedding
- Embeddings · Vector representations generated during ingestion
- Python stack · Project dependency set and pinned runtime version
pyproject.toml
Knowledge store
Persistent local documents and vector index
- Docs source · Authoritative Python basics text used as the knowledge base
docs/python_basics.txt - Chroma store · Local persistent vector index used at runtime for retrieval
chroma_db/chroma.sqlite3 - Index segments · 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 · Hosted inference used for generation, grading, and rewriting
Connections 16
- 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