How gokulsystems/retrieval-augmented-generation works
1. What this repo is
- This is a Python-based retrieval-augmented generation (RAG) pipeline centered on local model inference and document search.
- The architecture is intentionally lightweight: scripts orchestrate preprocessing, embedding/search, storage, and inference rather than a large framework.
2. Primary execution entrypoints
- rag_inference.py at the repo root is the main inference entrypoint.
- rag_pipeline_1/main.py is the pipeline runner for the package implementation.
- rag_pipeline_1/fastAPI1.py suggests an API-facing runtime for serving the pipeline.
- search.py and rag_pipeline_1/debug_search.py are auxiliary search/inspection entrypoints.
3. Core package boundary
- The actual implementation lives under rag_pipeline_1/.
- That package is split into three main concerns:
- engine/ for document and clinical text processing
- database/ for storage management
- communication/ for API/model interaction and orchestration
4. Document ingestion and preprocessing
- engine/pdf_to_ocr.py indicates a path for converting PDFs into OCR-extracted text.
- engine/MedicalReportCleaner.py is likely the first normalization step for noisy clinical text.
- engine/structuring.py and engine/fhir.py indicate downstream transformation into structured clinical data.
- engine/fhir_to_chuck.py likely chunks or segments structured content for retrieval.
5. Clinical/NLP enrichment layer
- engine/demographics_nlp.py suggests a specialized text-processing step for extracting demographic entities or patient metadata.
- This implies the pipeline is not generic document RAG only; it has clinical/report-specific enrichment before indexing or inference.
6. Embedding and retrieval layer
- rag_pipeline_1/vector_embedding.py is the embedding generation boundary.
- rag_pipeline_1/search_function.py and top-level search.py appear to implement retrieval/query helpers over embedded content.
- The data flow here is: cleaned/structured text → embeddings → search/retrieval candidates for generation.
7. Persistence and database management
- rag_pipeline_1/database/databaseServer.py is the storage backend or service wrapper for persisted records/vectors.
- rag_pipeline_1/database/clear_database.py is operational tooling to reset state, which matters because RAG pipelines often rely on regenerated indexes.
- rag_pipeline_1/database/ is therefore the persistence boundary between preprocessing and retrieval.
8. Inference and orchestration
- rag_inference.py and rag_pipeline_1/communication/rag_inference.py indicate an inference layer that likely coordinates retrieval results with the local model.
- The README states the project uses local GGUF model artifacts such as model.gguf and adapter.gguf, so generation is local rather than cloud-hosted.
- This makes the inference path: user query → retrieval → context assembly → local LLM generation.
9. API/communication boundary
- rag_pipeline_1/communication/apiLoader.py suggests integration with an external API or request-loading layer.
- rag_pipeline_1/fastAPI1.py is the likely service boundary for exposing the pipeline over HTTP.
- rag_pipeline_1/request.py, request2.py, request3.py, and request4.py look like manual clients or test harnesses for exercising that API.
10. Operational and diagnostic scripts
- rag_pipeline_1/testscript.py and rag_pipeline_1/debug_search.py support validation and troubleshooting of retrieval behavior.
- These scripts are important because RAG systems usually need separate debugging for indexing quality, retrieval quality, and generation quality.
11. Repository shape and duplication
- There are both root-level scripts and package-level equivalents, which suggests the repo evolved from ad hoc experimentation into a more organized package.
- The presence of requirements.txt, rag_pipeline_1/requirement.txt, and the misspelled riquirement.txt indicates environment capture is partly manual and not fully standardized.
12. High-level data flow for an architecture diagram
- Source documents enter through OCR/PDF processing.
- Text is cleaned, structured, and possibly mapped into FHIR-like representations.
- The processed content is chunked and embedded.
- Embeddings and metadata are stored in the database layer.
- Queries come through scripts or the API layer.
- Retrieval selects relevant chunks, and the local GGUF model generates the final answer.
13. Key architectural boundary to show
- The most important split is between:
- offline/ingestion-time processing: OCR, cleaning, structuring, embedding, persistence
- online/query-time processing: search, retrieval, prompt assembly, local inference, API response
- That boundary is the backbone of the repo’s architecture.
Main entry points: main.py Pipeline main · fastAPI1.py API server · search_function.py Query search · rag_inference.py Inference core
Components 21
Entry points
Top-level scripts and service runners
- RAG infer · Root-level inference entrypoint
rag_inference.py - Pipeline main · Package pipeline runner
rag_pipeline_1/main.py - API server · HTTP-facing runtime for the pipeline
rag_pipeline_1/fastAPI1.py - Search tool · Root-level search helper
search.py - Debug search · Search inspection script
rag_pipeline_1/debug_search.py
Ingestion
Document processing and enrichment before indexing
- PDF OCR · PDF to OCR text conversion
rag_pipeline_1/engine/pdf_to_ocr.py - Text cleaner · Clinical text cleanup and normalization
rag_pipeline_1/engine/MedicalReportCleaner.py - Demographics NLP · Clinical entity and metadata extraction
rag_pipeline_1/engine/demographics_nlp.py - Structuring · Transforms cleaned text into structured form
rag_pipeline_1/engine/stucturing.py - FHIR map · FHIR-oriented representation step
rag_pipeline_1/engine/fhir.py - Chunking · Segments structured content for retrieval
rag_pipeline_1/engine/fhir_to_chuck.py
Retrieval
Embedding, search, and query-time helpers
- Embeddings · Generates vector embeddings for indexed content
rag_pipeline_1/vector_embedding.py - Query search · Search and retrieval helpers over embedded content
rag_pipeline_1/search_function.py
Storage
Persistence and database management
Serving
API and inference orchestration
- Inference core · Package-level retrieval-to-generation orchestration
rag_pipeline_1/communication/rag_inference.py - API loader · External API/request integration boundary
rag_pipeline_1/communication/apiLoader.py - Request client · Manual API exercise script
rag_pipeline_1/request.py - Request client 2 · Manual API exercise script
rag_pipeline_1/request2.py - Request client 3 · Manual API exercise script
rag_pipeline_1/request3.py - Request client 4 · Manual API exercise script
rag_pipeline_1/request4.py
Connections 22
- RAG infer → Query search: retrieves · Inference uses retrieval results as context
- RAG infer → Inference core: delegates · Root inference entrypoint delegates to package orchestration
- Pipeline main → PDF OCR: ingests · Pipeline starts with document OCR/input normalization
- Pipeline main → Text cleaner: cleans · Normalizes noisy clinical text
- Pipeline main → Demographics NLP: extracts · Adds clinical metadata enrichment
- Pipeline main → Structuring: structures · Builds structured intermediate records
- Pipeline main → FHIR map: maps · Converts structured content into FHIR-like form
- Pipeline main → Chunking: chunks · Segments structured content for indexing
- Pipeline main → Embeddings: embeds · Creates embeddings from processed chunks
- Embeddings → DB server: stores · Persists vectors and metadata
- Search tool → Query search: calls · Root search script uses shared retrieval helpers
- Debug search → Query search: inspects · Debug tooling exercises retrieval behavior
- Query search → DB server: queries · Retrieval reads from persisted index/state
- Inference core → Query search: retrieves · Orchestrator fetches relevant chunks
- Inference core → API loader: loads · Orchestrator integrates with API/request boundary
- API server → API loader: serves · HTTP service exposes request handling
- Request client → API server: invokes · Manual client exercises the API service
- Request client 2 → API server: invokes · Manual client exercises the API service
- Request client 3 → API server: invokes · Manual client exercises the API service
- Request client 4 → API server: invokes · Manual client exercises the API service
- Reset DB → DB server: resets · Operational script clears persisted state
- Inference core → DB server: reads · Inference path may access stored context or metadata