How keshx-3/web-based-rag-assistant works
What this project is (type + purpose)
This is a single-service Python application with a Streamlit web UI that runs a Retrieval-Augmented Generation (RAG) workflow. It has two explicit “logic loops”:
• Knowledge Ingestion (ETL): URL(s) → fetch web content → clean/split → embed → store vectors in local ChromaDB.
• Contextual Inference (RAG): user question → embed query → similarity search in Chroma → build grounded prompt with top‑k chunks → call Groq LLaMA 3.1 → answer + citations (and LaTeX rendering).
It’s not a multi-service distributed system; it’s a monolithic app that depends on external APIs (Groq) and local persistence (Chroma vectorstore on disk).
What the file tree implies architecturally
From the tree:
• main.py = presentation + interaction layer
Streamlit UI, chat memory, LaTeX rendering, user inputs (URLs, questions), displays citations.
• rag.py = domain/service layer
ETL (WebBaseLoader, chunking) + embeddings + vectorstore ops + retrieval + prompt assembly (likely) + LLM call orchestration (via LangChain).
• requirements.txt = dependency boundary (Streamlit, LangChain, Chroma, HF embeddings, Groq SDK, etc.)
• .env.example + .env (runtime) = secret/config boundary (GROQ_API_KEY)
README also mentions a resources/vectorstore/ persistent path (not shown in tree but should exist at runtime). Treat it as local disk storage owned by the app process.
Goal: show what runs, what it talks to, and what data stores exist.
Nodes to include
• User (Browser)
• Streamlit App (Python process)
• External Web Sources (any HTTP/HTTPS site)
• Groq API (LLaMA 3.1 8B Instant) (external inference)
• Local Vector Store (ChromaDB on disk) (persistent)
• Embedding Model runtime: HuggingFace gte-base-en-v1.5
(likely local inference; if it downloads model weights, note “HF model files cache” as optional local storage)
• Browser → Streamlit: “User inputs (URLs, questions)”
• Streamlit → Web Sources: “Fetch HTML/text”
• Streamlit → Embeddings: “Compute embeddings”
• Streamlit ↔ ChromaDB: “Upsert chunks / Similarity search (cosine)”
• Streamlit → Groq: “RAG prompt + context”
• Groq → Streamlit: “Grounded answer”
• Streamlit → Browser: “Answer + citations + rendered LaTeX”
Labels that matter
• “k=8 top chunks”
• “chunk size ~1500 chars w/ overlap”
• “768-d embeddings”
• “persistent vectorstore path: resources/vectorstore/ (local)”
Goal: show the two loops as time-ordered interactions.
Sequence 1: Ingestion loop (ETL)
Return ingestion status to UI
Sequence 2: Inference loop (RAG)
UI renders response + st.latex() where applicable + citations
Goal: map files → responsibilities and show internal boundaries.
• main.py
• UI components (URL input, query input, chat display)
• Session state / chat memory
• LaTeX detection & rendering pipeline (st.latex)
• Calls into rag.py
• rag.py
• Loader: WebBaseLoader
• Cleaner: regex artifact stripper
• Splitter: RecursiveCharacterTextSplitter
• Embeddings: HF gte-base-en-v1.5
• Vectorstore adapter: Chroma
• Retriever: top‑k (k=8), cosine similarity
• Prompt builder: “strict grounding”
• LLM client: Groq (LLaMA 3.1)
Cross-cutting
• Config: .env → GROQ_API_KEY
• Persistence: resources/vectorstore/ (Chroma collection)
• Custom: orchestration glue, cleaning, prompt constraints, UI/latex, memory
• Library-managed: chunker, embeddings wrapper, Chroma client, Groq client (depending on implementation)
Relationships + interactions to highlight (the “truth” of the architecture)
• It’s a single runtime (Streamlit) doing both ingestion and inference.
• It has a local durable store (Chroma on disk) that is reused across sessions/runs.
• It has two major external dependencies:
1) arbitrary websites for ingestion
2) Groq for generation
• Embeddings are a distinct compute stage (often local, CPU/GPU dependent) and are used twice (docs and query).
• Citation support depends on document metadata (URL) flowing from ingestion → vectorstore → retrieval → UI.
Practical “don’t overthink it” checklist (but be very detailed)
• Where does content come from? (URLs → loader)
• Where does it persist? (Chroma on disk path)
• What transforms happen before storage? (clean → chunk → embed)
• What transforms happen before generation? (embed query → retrieve → prompt)
• What enforces correctness? (grounding prompt constraints)
• What’s external and failure-prone? (web fetch + Groq API)
• Where are secrets stored? (.env / GROQ_API_KEY)
• What is the runtime entrypoint? (streamlit run main.py)