How namansharma2408/causal-rag works
1. What this repository is
- A Python-based conversational analytics system for transcript data.
- The core architecture is a multi-agent RAG pipeline: retrieve relevant transcript evidence, reason over it, optionally cross-check it, and return a grounded answer.
2. Primary runtime and entry points
- The app is built around a FastAPI server (server.py) with supporting orchestration in app.py and api.py.
- __main__.py and cli.py suggest the system can also be started from the command line, not only through Docker.
- frontend.html is a lightweight browser UI that talks to the backend API.
3. End-user request flow
- A user submits a question in the web UI or via POST /api/query.
- The request is handled by the server layer, passed into the application/session orchestration layer, and then into the core RAG pipeline in ragSystem.py.
- The response is returned as a conversational answer, with optional proof and quality checks.
4. Core orchestration boundary
- ragSystem.py is the main pipeline coordinator.
- It wires together the agents in the correct order and manages the overall retrieval-to-answer flow.
- This file is the best place to think of as the “brain” of the system when drawing the architecture.
5. Agent pipeline
- The repository defines a staged agent chain in agents/:
- Decomposer breaks the user question into subproblems.
- Router decides how to handle the query and likely what retrieval path to use.
- Retriever pulls candidate evidence.
- Reranker improves candidate ordering.
- Extractor selects the most relevant supporting snippets.
- Reasoner synthesizes the final answer.
- Proof adds evidence/justification.
- QualityChecker evaluates answer quality.
- thinking.py and proof.py indicate optional deeper reasoning and verification paths.
6. Retrieval architecture
- The README describes hybrid retrieval: vector similarity plus BM25-style keyword scoring.
- That means the retrieval layer is not purely embedding-based; it combines semantic and lexical search for better transcript lookup.
- The retriever/reranker/extractor stages form the evidence selection boundary before generation.
7. Model and provider layer
- services/llmProvider.py, services/embedding.py, and services/ollama.py abstract external model access.
- Gemini is the required default LLM provider via GEMINI_API_KEY.
- Ollama is an optional local inference path used for “Thinking Mode,” which enables multi-model consensus.
- This is a key deployment boundary: cloud LLM calls versus local model serving.
8. State, memory, and persistence
- services/memory.py and models.py indicate shared conversation/session structures.
- The README says session state is persisted in chatSessions/*.json, so chat continuity is at least partly file-backed.
- services/mongodb.py and scripts/initMongoDb.py show MongoDB is also part of the system, likely for transcript storage or indexed data management.
- This creates a split between short-lived chat/session memory and longer-lived data persistence.
9. Transcript data boundary
- services/transcripts.py is the domain-specific data access layer for transcript content.
- In architectural terms, transcript data flows from storage into retrieval, then through the agent pipeline, and back out as grounded answers.
- This is the main business-data boundary of the repo.
10. Deployment topology
- docker-compose.yml, Dockerfile, and scripts/dockerEntrypoint.sh define a containerized runtime.
- The README implies at least two containers/services in practice: the app and MongoDB.
- The app expects environment configuration from .env, especially GEMINI_API_KEY, and optionally MongoDB/Ollama endpoints.
11. Operational tooling
- Makefile provides lifecycle commands such as build, up, down, logs, and cleanup.
- This is important for the architecture diagram because the system is designed to be run as a packaged local stack, not just as a library.
12. Suggested architecture diagram boundaries
- Client boundary: browser UI / API consumer.
- Application boundary: FastAPI server + request/session orchestration.
- Reasoning boundary: ragSystem.py plus the agent chain.
- Data boundary: transcripts, chat session JSON, MongoDB.
- External service boundary: Gemini API and optional Ollama local models.
Main entry points: retriever.py Retriever · app.py App Orchestration · server.py Server · ragSystem.py RAG System
Components 27
Client
User-facing request sources
- Browser UI · Lightweight in-browser chat surface
frontend.html - CLI Entry · Command-line startup path
cli.py - Module Main · Package entrypoint for local execution
__main__.py
Application
HTTP API and orchestration entrypoints
- Server · HTTP server and API surface
server.py - API Layer · API handlers and request translation
api.py - App Orchestration · Application/session coordination
app.py
Reasoning
RAG pipeline and agent chain
- RAG System · Main retrieval-to-answer workflow
ragSystem.py - Router · Chooses handling path for a query
agents/router.py - Decomposer · Breaks a question into smaller tasks
agents/decomposer.py - Retriever · Pulls candidate transcript evidence
agents/retriever.py - Reranker · Reorders retrieved candidates
agents/reranker.py - Extractor · Selects the most relevant supporting snippets
agents/extractor.py - Reasoner · Synthesizes the grounded response
agents/reasoner.py - Proof · Adds evidence and justification
agents/proof.py - Quality Check · Assesses answer quality
agents/quality.py - Thinking Mode · Optional deeper reasoning and multi-model checks
agents/thinking.py
Data
Conversation, transcript, and persistence boundaries
- Transcripts · Transcript retrieval and domain data access
services/transcripts.py - Memory · Conversation/session state management
services/memory.py - Models · Shared data structures for sessions and messages
models.py - MongoDB · Long-lived transcript or index storage
services/mongodb.py
External
Model and service integrations
- LLM Provider · Abstraction over external LLM calls
services/llmProvider.py - Embeddings · Embedding generation for retrieval
services/embedding.py - Ollama · Optional local inference path
services/ollama.py
Deployment
Container and local runtime tooling
- Compose Stack · Containerized app and database topology
docker-compose.yml - App Image · Application container build definition
Dockerfile - Entrypoint · Container startup script
scripts/dockerEntrypoint.sh - Makefile · Lifecycle commands for local stack
Makefile
Connections 27
- Browser UI → Server: chat request · User submits a question through the web UI
- CLI Entry → App Orchestration: start · CLI launches the application flow
- Module Main → Server: boot · Module entrypoint starts the API server
- Server → API Layer: route · HTTP requests are handed to API handlers
- API Layer → App Orchestration: session flow · Request is translated into app/session orchestration
- App Orchestration → RAG System: query · Application layer invokes the core RAG pipeline
- RAG System → Router: dispatch · Pipeline chooses a handling path
- Router → Decomposer: split · Complex queries are decomposed into subproblems
- Decomposer → Retriever: retrieve · Subproblems drive evidence lookup
- Retriever → Transcripts: fetch · Transcript content is loaded for search
- Retriever → Embeddings: vectorize · Embedding-based similarity is used in retrieval
- Retriever → MongoDB: lookup · Persistent transcript or index data can be queried
- Retriever → Reranker: candidates · Retrieved evidence is forwarded for ranking
- Reranker → Extractor: top evidence · Best candidates are distilled into snippets
- Extractor → Reasoner: context · Selected evidence becomes generation context
- Reasoner → LLM Provider: generate · Final answer synthesis uses the LLM provider
- Reasoner → Proof: justify · Optional evidence-backed explanation is added
- Proof → Quality Check: check · Answer and proof can be evaluated for quality
- RAG System → Thinking Mode: optional path · Thinking mode enables deeper multi-model reasoning
- Thinking Mode → Ollama: local inference · Optional local model execution for consensus or checks
- App Orchestration → Memory: store session · Conversation state is persisted during the session
- Memory → Models: serialize · Session and message structures define stored state
- App Orchestration → Models: use schemas · Application logic uses shared data models
- Server → Compose Stack: deploys with · Server is commonly run as part of the stack
- Compose Stack → MongoDB: service · Container stack includes MongoDB
- App Image → Entrypoint: starts · Container image uses the startup script
- Makefile → Compose Stack: orchestrates · Make targets manage the containerized stack