How t-hara-coretec/rag_demo_20250424 works
Project type and purpose
• This is a full‑stack chat application with Retrieval‑Augmented Generation (RAG).
• Purpose: Provide an interactive chat interface where user queries can be answered directly by an AI model or enriched with information retrieved from PDF documents.
File structure
• Top‑level components:
• chat_app.py, chat_app.html, chat_app.ts: main backend entrypoint and frontend assets
• rag_utils/: RAG implementation modules (pdf_processor, vector_store, rag_service, web_processor)
• datas/: PDF document store for ingestion
• chroma_db/: persistent vector store database (ChromaDB)
• Support scripts:
• create_flowchart.py / create_png_flowchart.py: tooling to generate flowcharts
• run.sh: startup script
• Test and cache directories for unit tests and web caching
• Configuration:
• rag_requirements.txt: Python dependencies
• run.sh: launch command
Extract key architecture hints from the README
• Three RAG components in rag_utils: PDF processing → vector store → RAG service
• The backend serves an HTML+TypeScript frontend at http://localhost:8000
• AI model integration using pydantic‑ai
Main components
a. Frontend (Browser):
• HTML/TypeScript client
• UI elements for chat input, RAG toggle
b. Backend (Python Application Server):
• HTTP server (chat_app.py) exposing REST or WebSocket endpoints
• Chat controller/orchestrator that receives requests from frontend
• Agent integration with AI model (pydantic‑ai)
c. RAG Pipeline:
• PDF Processor (rag_utils/pdf_processor.py): extract & chunk text
• Vector Store (rag_utils/vector_store.py): interface to ChromaDB
• RAG Service (rag_utils/rag_service.py): coordinate retrieval + augmentation
• Optional: Web Processor (rag_utils/web_processor.py) for fetching web pages
d. Data Stores:
• ChromaDB (chroma_db/chroma.sqlite3): stores embeddings & metadata
• Datas folder: source PDF documents
• Web cache: local JSON cache of fetched web pages
e. External Dependencies:
• AI Model API (pydantic‑ai)
• Chromadb library
Relationships & data flows
1. User submits a message in the frontend
2. Frontend calls backend chat endpoint
3. Backend determines if RAG is enabled
– If disabled: pass query directly to AI model, return response
– If enabled:
a. Invoke PDF Processor to read & chunk docs from datas/
b. Store or load chunks into Vector Store (ChromaDB)
c. RAG Service queries vector store for top‑k relevant chunks
d. Combine user query + retrieved chunks, call AI model
e. Return enriched response to frontend
4. Backend may persist logs to server_log.txt
Architectural patterns & design principles
• Layered architecture: Presentation (frontend) → Application (chat_app.py) → Domain/RAG modules → Persistence (ChromaDB)
• Separation of concerns: PDF ingestion, storage, retrieval, and chat orchestration are in distinct modules
• Stateful vs. stateless: Backend is stateless per request, state (embeddings) is in ChromaDB
• Extensibility: Web processor can be swapped in/out, AI model is configurable
• Clear, human‑readable labels on all components
• A note indicating configuration points (e.g., toggle RAG, model selection)