# prajitha-j/re-ranker-rag-pipeline architecture

> Architecture diagram of the GitHub repository prajitha-j/re-ranker-rag-pipeline, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prajitha-j/re-ranker-rag-pipeline
- Repository: https://github.com/prajitha-j/re-ranker-rag-pipeline

## Overview

1. **What this system is**
   - This repository implements an audit-focused RAG pipeline that answers natural-language questions over audit reports, IR paragraphs, compliance rules, and tabular evidence.
   - The architecture is not a simple retriever-plus-LLM; it is a staged planning/execution system built around BAG (Bag-of-Actions-Graph).

2. **Primary runtime entrypoints**
   - `server_v3.py` is the API-facing runtime, and `streamlit_app.py` is the interactive UI.
   - Both frontends feed requests into `pipeline.py`, which is the main orchestrator for the end-to-end query flow.

3. **End-to-end query flow**
   - A user query moves through three sequential stages: **Interpret → Strategize → Synthesize**.
   - Between Strategize and Synthesize, retrieved evidence is re-ranked by `evidence_reranker.py` using a BGE re-ranker before the final LLM response is produced.

4. **Interpret stage boundary**
   - `interpret_bag.py` handles query understanding: extracting entities like state, department, domain, and financial years.
   - Supporting modules such as `query_parser.py`, `schema_loader.py`, and `filter_normalizer*.py` shape the user request into structured constraints that downstream tools can consume.

5. **Strategize stage boundary**
   - `strategize_bag.py` decides which tools to invoke and in what order based on query intent.
   - The pipeline explicitly supports three query types: `count`, `content`, and `calculate`, which drive different retrieval and computation behaviors.

6. **Dynamic tool system**
   - `tool_registry.py` and `execution.py` form the dynamic dispatch layer.
   - `tools.py` contains the tool implementations, while `schemas/` contains JSON schemas that expose those tools to the LLM in a structured way.
   - The key architectural point is that tools are discovered at runtime rather than hardcoded into prompt logic or execution branches.

7. **Tool groups and responsibilities**
   - The toolset is organized around four functional groups: query understanding, filter planning, search execution, and calculation.
   - `table_agent.py` and `observation_agent.py` suggest specialized internal helpers for table-heavy analysis and evidence handling, which fit into the tool-driven execution model.

8. **Retrieval and data access layer**
   - `audit_db_client.py` is the main interface to the audit database, which the README indicates is PostgreSQL with pgvector used for retrieval.
   - `milvus_client.py` and `Milvus_metadata_helper.py` provide Milvus support, likely as a secondary or legacy vector-search path.
   - This makes the retrieval boundary a distinct subsystem from the LLM layer: evidence is fetched, filtered, and ranked before synthesis.

9. **LLM and re-ranking services**
   - `llm_client.py` abstracts calls to the model serving backend, which the README describes as vLLM-hosted Mistral/Qwen models.
   - Embeddings and ranking are externalized: BGE-M3 is used for embeddings, and TEI serves the BGE re-ranker.
   - The final answer is produced only after evidence has been reordered by relevance.

10. **Synthesis stage**
   - `synthesize_bag.py` combines the structured plan, ranked evidence, and query context into the final response.
   - `conv.py` likely supports conversational state or response assembly, keeping the synthesis layer separate from retrieval and planning.

11. **Configuration and service boundaries**
   - `config.py` and `.env.example` define the environment-driven integration points for databases, model servers, and other infrastructure.
   - The README also names MinIO as document storage, so the repo sits in front of several external services rather than owning the full data plane itself.

12. **Operational and diagnostic code**
   - The `debug_*.py`, `health_check.py`, `Server_check.py`, `Log_analyzer.py`, and `Token_tracker.py` files are support tooling for validation, observability, and troubleshooting.
   - `qa_packets/` and `test_dynamic_tools.py` indicate an offline evaluation and regression-testing layer for the tool-discovery and retrieval behavior.

13. **What to draw in an architecture diagram**
   - Show two clients, UI and API, feeding into `pipeline.py`.
   - From there, draw the three BAG stages, with a tool-dispatch branch in the middle and a reranking step before synthesis.
   - Separate the internal orchestration layer from the external services: PostgreSQL/pgvector, Milvus, LLM serving via vLLM, embedding/rerank services, and document storage.

Main entry points: [`pipeline.py`](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/pipeline.py) (Pipeline), [`tools.py`](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/tools.py) (Tools), [`interpret_bag.py`](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/interpret_bag.py) (Interpret), [`config.py`](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/config.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_server_v3["API server<br/>runtime<br/>[server_v3.py]"]
  node_streamlit_app["UI app<br/>runtime<br/>[streamlit_app.py]"]
end

subgraph group_core["Orchestration"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
  node_interpret_bag["Interpret<br/>planner<br/>[interpret_bag.py]"]
  node_strategize_bag["Strategize<br/>planner<br/>[strategize_bag.py]"]
  node_evidence_reranker["Reranker"]
  node_synthesize_bag["Synthesize<br/>generator<br/>[synthesize_bag.py]"]
end

subgraph group_tools["Tooling"]
  node_query_parser["Parser<br/>normalizer<br/>[query_parser.py]"]
  node_schema_loader["Schema loader<br/>[schema_loader.py]"]
  node_filter_normalizer["Filter norm<br/>normalizer"]
  node_tool_registry["Registry<br/>dispatcher<br/>[tool_registry.py]"]
  node_execution["Execution<br/>dispatcher<br/>[execution.py]"]
  node_tools_py["Tools<br/>[tools.py]"]
  node_table_agent["Table agent<br/>helper<br/>[table_agent.py]"]
  node_observation_agent["Observation agent<br/>helper"]
end

subgraph group_data["Data & Services"]
  node_audit_db_client[("Audit DB<br/>db client<br/>[audit_db_client.py]")]
  node_milvus_client[("Milvus<br/>vector client<br/>[milvus_client.py]")]
  node_llm_client["LLM client<br/>model client<br/>[llm_client.py]"]
  node_config["Config<br/>[config.py]"]
end

subgraph group_ops["Ops"]
end

node_server_v3 -->|"requests"| node_pipeline
node_streamlit_app -->|"requests"| node_pipeline
node_pipeline -->|"stage 1"| node_interpret_bag
node_interpret_bag -->|"parse"| node_query_parser
node_interpret_bag -->|"load schema"| node_schema_loader
node_interpret_bag -->|"normalize"| node_filter_normalizer
node_pipeline -->|"stage 2"| node_strategize_bag
node_strategize_bag -->|"discover tools"| node_tool_registry
node_tool_registry -->|"dispatch"| node_execution
node_execution -->|"invoke"| node_tools_py
node_tools_py -->|"retrieve"| node_audit_db_client
node_tools_py -->|"vector search"| node_milvus_client
node_tools_py -->|"assist"| node_table_agent
node_tools_py -->|"assist"| node_observation_agent
node_pipeline -->|"rerank"| node_evidence_reranker
node_evidence_reranker -->|"rank model"| node_llm_client
node_pipeline -->|"stage 3"| node_synthesize_bag
node_synthesize_bag -->|"generate"| node_llm_client
node_pipeline -->|"settings"| node_config
node_audit_db_client -->|"connect"| node_config
node_milvus_client -->|"connect"| node_config
node_llm_client -->|"connect"| node_config

click node_server_v3 "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/server_v3.py"
click node_streamlit_app "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/streamlit_app.py"
click node_pipeline "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/pipeline.py"
click node_interpret_bag "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/interpret_bag.py"
click node_strategize_bag "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/strategize_bag.py"
click node_evidence_reranker "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/evidence_reranker.py"
click node_synthesize_bag "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/synthesize_bag.py"
click node_query_parser "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/query_parser.py"
click node_schema_loader "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/schema_loader.py"
click node_filter_normalizer "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/filter_normalizer.py"
click node_tool_registry "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/tool_registry.py"
click node_execution "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/execution.py"
click node_tools_py "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/tools.py"
click node_table_agent "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/table_agent.py"
click node_observation_agent "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/observation_agent.py"
click node_audit_db_client "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/audit_db_client.py"
click node_milvus_client "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/milvus_client.py"
click node_llm_client "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/llm_client.py"
click node_config "https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server_v3,node_streamlit_app toneBlue
class node_pipeline,node_interpret_bag,node_strategize_bag,node_evidence_reranker,node_synthesize_bag toneAmber
class node_query_parser,node_schema_loader,node_filter_normalizer,node_tool_registry,node_execution,node_tools_py,node_table_agent,node_observation_agent toneMint
class node_audit_db_client,node_milvus_client,node_llm_client,node_config toneRose
```

## Components

### Clients

User-facing entrypoints into the pipeline

- [API server](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/server_v3.py): runtime · API-facing runtime entrypoint · `server_v3.py`
- [UI app](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/streamlit_app.py): runtime · Interactive user interface entrypoint · `streamlit_app.py`

### Orchestration

Query planning and execution flow

- [Pipeline](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/pipeline.py): orchestrator · Main end-to-end query coordinator · `pipeline.py`
- [Interpret](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/interpret_bag.py): planner · Extracts entities and structured constraints from queries · `interpret_bag.py`
- [Strategize](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/strategize_bag.py): planner · Chooses tools and execution order from query intent · `strategize_bag.py`
- [Reranker](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/evidence_reranker.py): ranker · Reorders retrieved evidence before synthesis · `evidence_reranker.py`
- [Synthesize](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/synthesize_bag.py): generator · Builds the final answer from plan and evidence · `synthesize_bag.py`

### Tooling

Dynamic tools and stage-specific helpers

- [Parser](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/query_parser.py): normalizer · Parses user intent and query structure · `query_parser.py`
- [Schema loader](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/schema_loader.py): schema · Loads structured schemas for constraints and tools · `schema_loader.py`
- [Filter norm](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/filter_normalizer.py): normalizer · Normalizes filters into downstream-friendly form · `filter_normalizer.py`
- [Registry](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/tool_registry.py): dispatcher · Discovers and exposes tools at runtime · `tool_registry.py`
- [Execution](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/execution.py): dispatcher · Invokes registered tools dynamically · `execution.py`
- [Tools](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/tools.py): toolset · Core tool implementations for retrieval and computation · `tools.py`
- [Table agent](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/table_agent.py): helper · Specialized helper for table-heavy analysis · `table_agent.py`
- [Observation agent](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/observation_agent.py): helper · Helper for evidence handling and observations · `observation_agent.py`

### Data & Services

External retrieval, model, and storage services

- [Audit DB](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/audit_db_client.py): db client · Primary audit database access layer · `audit_db_client.py`
- [Milvus](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/milvus_client.py): vector client · Secondary or legacy vector search client · `milvus_client.py`
- [LLM client](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/llm_client.py): model client · Abstraction over hosted LLM serving · `llm_client.py`
- [Config](https://github.com/prajitha-j/re-ranker-rag-pipeline/blob/main/config.py): configuration · Environment-driven service and integration settings · `config.py`

## Connections

- API server → Pipeline: requests · API requests enter the main pipeline
- UI app → Pipeline: requests · UI queries enter the main pipeline
- Pipeline → Interpret: stage 1 · Query understanding and constraint extraction
- Interpret → Parser: parse · Interpretation uses query parsing helpers
- Interpret → Schema loader: load schema · Structured schemas guide interpretation
- Interpret → Filter norm: normalize · Filters are normalized for downstream use
- Pipeline → Strategize: stage 2 · Strategy selection and tool planning
- Strategize → Registry: discover tools · Tool availability is resolved at runtime
- Registry → Execution: dispatch · Registry feeds the dynamic execution layer
- Execution → Tools: invoke · Execution calls into tool implementations
- Tools → Audit DB: retrieve · Tools fetch audit evidence from the main database
- Tools → Milvus: vector search · Tools can query vector storage when needed
- Tools → Table agent: assist · Table-heavy tasks are delegated to a helper
- Tools → Observation agent: assist · Evidence and observation handling is delegated to a helper
- Pipeline → Reranker: rerank · Retrieved evidence is reordered before synthesis
- Reranker → LLM client: rank model · Reranking relies on external model serving
- Pipeline → Synthesize: stage 3 · Final response synthesis
- Synthesize → LLM client: generate · LLM client produces the final answer
- Pipeline → Config: settings · Runtime behavior is driven by environment configuration
- Audit DB → Config: connect · Database connectivity is configured externally
- Milvus → Config: connect · Vector store connectivity is configured externally
- LLM client → Config: connect · Model serving endpoints come from configuration