# prajwal25xd/rag-failure-diagnosis-tool architecture

> Architecture diagram of the GitHub repository prajwal25xd/rag-failure-diagnosis-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prajwal25xd/rag-failure-diagnosis-tool
- Repository: https://github.com/prajwal25xd/rag-failure-diagnosis-tool

## Overview

This is a local Streamlit tool for answering tender questions while diagnosing possible RAG failures. A user submits a question and mode; the orchestrator plans a SQL, RAG, or hybrid route, gathers metadata and/or document evidence, produces an answer, and returns evidence and diagnostics for display. The documented diagnostic capabilities cover retrieval, chunk quality, conflicting evidence, and answer reasoning. Some connections below rely on the README’s architecture description because relevant source was not sampled; unsampled implementation details are not inferred.

Main entry points: [`agent/orchestrator.py`](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/orchestrator.py) (Query Orchestrator), [`main.py`](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/main.py) (RAG Pipeline), [`config.py`](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/config.py) (Runtime Configuration), [`retrieval/hybrid_search.py`](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/hybrid_search.py) (Hybrid Ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Question Interface"]
  node_dashboard["Streamlit Dashboard<br/>[app.py]"]
end

subgraph group_workflow["Query Workflow"]
  node_orchestrator["Query Orchestrator<br/>[orchestrator.py]"]
  node_planner["Route Planner<br/>[query_planner.py]"]
  node_sql_exec["Metadata Executor<br/>[sql_executor.py]"]
  node_merger["Answer Merger<br/>[evidence_merger.py]"]
end

subgraph group_retrieval["Evidence Retrieval"]
  node_rag_pipeline["RAG Pipeline<br/>[main.py]"]
  node_hybrid["Hybrid Ranking<br/>[hybrid_search.py]"]
  node_vector["Vector Search<br/>[vector_search.py]"]
  node_keyword["Keyword Search<br/>[keyword_search.py]"]
end

subgraph group_diagnosis["RAG Diagnostics"]
  node_retrieval_diag["Retrieval Diagnosis"]
  node_chunk_diag["Chunking Diagnosis"]
  node_conflict_diag["Conflict Diagnosis"]
  node_reason_diag["Reasoning Diagnosis"]
  node_summary["Diagnostic Summary"]
end

subgraph group_services["Data and Model Services"]
  node_metadata_db[("Tender Metadata")]
  node_chunks_db[("Indexed Chunks")]
  node_embedding_service["HF Embeddings"]
  node_lm_studio["LM Studio"]
  node_lm_client["LM Client"]
  node_config["Runtime Configuration<br/>[config.py]"]
end

node_user(("Questioner"))

node_user -->|"submits question"| node_dashboard
node_dashboard -->|"starts query"| node_orchestrator
node_orchestrator -->|"plans route"| node_planner
node_planner -.->|"requests plan"| node_lm_client
node_lm_client -.->|"calls model"| node_lm_studio
node_orchestrator -->|"runs metadata query"| node_sql_exec
node_sql_exec -->|"reads metadata"| node_metadata_db
node_orchestrator -->|"runs RAG"| node_rag_pipeline
node_rag_pipeline -->|"retrieves evidence"| node_hybrid
node_hybrid -->|"gets vector ranks"| node_vector
node_hybrid -->|"gets keyword ranks"| node_keyword
node_vector -->|"searches vectors"| node_chunks_db
node_keyword -->|"searches text"| node_chunks_db
node_vector -->|"embeds question"| node_embedding_service
node_orchestrator -->|"synthesizes answer"| node_merger
node_merger -->|"generates answer"| node_lm_studio
node_rag_pipeline -->|"checks retrieval"| node_retrieval_diag
node_rag_pipeline -->|"checks chunks"| node_chunk_diag
node_rag_pipeline -->|"checks conflicts"| node_conflict_diag
node_rag_pipeline -->|"checks reasoning"| node_reason_diag
node_orchestrator -->|"builds summary"| node_summary
node_dashboard -->|"displays report"| node_user
node_config -->|"configures search"| node_vector
node_config -->|"configures ranking"| node_hybrid
node_config -->|"configures checks"| node_chunk_diag
node_config -->|"configures checks"| node_conflict_diag
node_config -->|"configures checks"| node_reason_diag

click node_dashboard "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/app.py"
click node_orchestrator "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/orchestrator.py"
click node_planner "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/query_planner.py"
click node_sql_exec "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/sql_executor.py"
click node_merger "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/evidence_merger.py"
click node_rag_pipeline "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/main.py"
click node_hybrid "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/hybrid_search.py"
click node_vector "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/vector_search.py"
click node_keyword "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/keyword_search.py"
click node_lm_client "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/lm_studio_client.py"
click node_config "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/config.py"
click node_retrieval_diag "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/retrieval_diagnosis.py"
click node_chunk_diag "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/chunking_diagnosis.py"
click node_conflict_diag "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/conflict_diagnosis.py"
click node_reason_diag "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/reasoning_diagnosis.py"
click node_summary "https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/diagnostic_summary.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_dashboard toneBlue
class node_orchestrator,node_planner,node_sql_exec,node_merger toneAmber
class node_rag_pipeline,node_hybrid,node_vector,node_keyword toneMint
class node_retrieval_diag,node_chunk_diag,node_conflict_diag,node_reason_diag,node_summary toneRose
class node_metadata_db,node_chunks_db,node_embedding_service,node_lm_studio,node_lm_client,node_config,node_user toneIndigo
```

## Components

### Question Interface

- [Streamlit Dashboard](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/app.py): `app.py`

### Query Workflow

- [Query Orchestrator](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/orchestrator.py): `agent/orchestrator.py`
- [Route Planner](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/query_planner.py): `agent/query_planner.py`
- [Metadata Executor](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/sql_executor.py): `agent/sql_executor.py`
- [Answer Merger](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/evidence_merger.py): `agent/evidence_merger.py`

### Evidence Retrieval

- [RAG Pipeline](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/main.py): `main.py`
- [Hybrid Ranking](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/hybrid_search.py): `retrieval/hybrid_search.py`
- [Vector Search](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/vector_search.py): `retrieval/vector_search.py`
- [Keyword Search](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/retrieval/keyword_search.py): `retrieval/keyword_search.py`

### RAG Diagnostics

- [Retrieval Diagnosis](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/retrieval_diagnosis.py): `diagnostics/retrieval_diagnosis.py`
- [Chunking Diagnosis](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/chunking_diagnosis.py): `diagnostics/chunking_diagnosis.py`
- [Conflict Diagnosis](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/conflict_diagnosis.py): `diagnostics/conflict_diagnosis.py`
- [Reasoning Diagnosis](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/reasoning_diagnosis.py): `diagnostics/reasoning_diagnosis.py`
- [Diagnostic Summary](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/diagnostics/diagnostic_summary.py): `diagnostics/diagnostic_summary.py`

### Data and Model Services

- **Tender Metadata**
- **Indexed Chunks**
- **HF Embeddings**
- **LM Studio**
- [LM Client](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/agent/lm_studio_client.py): `agent/lm_studio_client.py`
- [Runtime Configuration](https://github.com/prajwal25xd/rag-failure-diagnosis-tool/blob/main/config.py): `config.py`

### Other components

- **Questioner**

## Connections

- Questioner → Streamlit Dashboard: submits question (evidence: `README.md`)
- Streamlit Dashboard → Query Orchestrator: starts query (evidence: `README.md`)
- Query Orchestrator → Route Planner: plans route (evidence: `agent/orchestrator.py`)
- Route Planner → LM Client: requests plan
- LM Client → LM Studio: calls model
- Query Orchestrator → Metadata Executor: runs metadata query (evidence: `agent/orchestrator.py`)
- Metadata Executor → Tender Metadata: reads metadata (evidence: `README.md`)
- Query Orchestrator → RAG Pipeline: runs RAG (evidence: `agent/orchestrator.py`)
- RAG Pipeline → Hybrid Ranking: retrieves evidence (evidence: `README.md`)
- Hybrid Ranking → Vector Search: gets vector ranks (evidence: `retrieval/hybrid_search.py`)
- Hybrid Ranking → Keyword Search: gets keyword ranks (evidence: `retrieval/hybrid_search.py`)
- Vector Search → Indexed Chunks: searches vectors (evidence: `README.md`)
- Keyword Search → Indexed Chunks: searches text (evidence: `README.md`)
- Vector Search → HF Embeddings: embeds question (evidence: `README.md`)
- Query Orchestrator → Answer Merger: synthesizes answer (evidence: `agent/orchestrator.py`)
- Answer Merger → LM Studio: generates answer (evidence: `README.md`)
- RAG Pipeline → Retrieval Diagnosis: checks retrieval (evidence: `main.py`)
- RAG Pipeline → Chunking Diagnosis: checks chunks (evidence: `main.py`)
- RAG Pipeline → Conflict Diagnosis: checks conflicts (evidence: `main.py`)
- RAG Pipeline → Reasoning Diagnosis: checks reasoning (evidence: `main.py`)
- Query Orchestrator → Diagnostic Summary: builds summary (evidence: `agent/orchestrator.py`)
- Streamlit Dashboard → Questioner: displays report (evidence: `README.md`)
- Runtime Configuration → Vector Search: configures search (evidence: `retrieval/vector_search.py`)
- Runtime Configuration → Hybrid Ranking: configures ranking (evidence: `retrieval/hybrid_search.py`)
- Runtime Configuration → Chunking Diagnosis: configures checks (evidence: `diagnostics/chunking_diagnosis.py`)
- Runtime Configuration → Conflict Diagnosis: configures checks (evidence: `diagnostics/conflict_diagnosis.py`)
- Runtime Configuration → Reasoning Diagnosis: configures checks (evidence: `diagnostics/reasoning_diagnosis.py`)