# aayushbokde/decision_guided_rag architecture

> Architecture diagram of the GitHub repository aayushbokde/decision_guided_rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aayushbokde/decision_guided_rag
- Repository: https://github.com/aayushbokde/decision_guided_rag

## Overview

This is a Streamlit research demo and evaluation codebase for comparing standard RAG with decision-guided context filtering and accumulated-evidence early exit. The user selects or enters a question, chooses a pipeline, and receives a generated answer with retrieval, decision, and timing details. Shared embedding and similarity-retrieval code supports the pipelines; separate evaluation modules assess answer quality and compare results. The README identifies KeywordOracle as a development proxy, not JEV. Some app and pipeline wiring is unsampled, so uncertain internal links are omitted.

Main entry points: [`app.py`](https://github.com/aayushbokde/decision_guided_rag/blob/main/app.py) (Streamlit demo), [`src/jev_rag_research/jev_rag/rag.py`](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/rag.py) (Filtered RAG), [`src/jev_rag_research/shared/embeddings.py`](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/embeddings.py) (Text embedding), [`src/jev_rag_research/jev_rag/early_exit.py`](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/early_exit.py) (Early-exit RAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_demo["Interactive demo"]
  node_app["Streamlit demo<br/>[app.py]"]
  node_questions["Question data<br/>[questions.json]"]
  node_chunks["Chunk data<br/>[chunks.json]"]
  node_chunked_questions["Chunked questions"]
  node_embedding_data["Chunk embeddings"]
end

subgraph group_pipelines["RAG pipelines"]
  node_normal["Normal RAG<br/>[rag.py]"]
  node_filtered["Filtered RAG<br/>[rag.py]"]
  node_early["Early-exit RAG<br/>[early_exit.py]"]
  node_oracle["Keyword oracle<br/>[oracle.py]"]
  node_decision["Decision contract<br/>[decision.py]"]
end

subgraph group_shared["Shared retrieval"]
  node_embed["Text embedding<br/>[embeddings.py]"]
  node_retrieval["Similarity retrieval<br/>[retrieval.py]"]
  node_prep["Dataset preparation<br/>[prepare_dataset.py]"]
  node_chunking["Dataset chunking<br/>[chunk_dataset.py]"]
  node_embed_dataset["Dataset embedding<br/>[embed_dataset.py]"]
end

subgraph group_evaluation["Research evaluation"]
  node_retrieval_eval["Retrieval evaluation"]
  node_threshold["Threshold sweep<br/>[threshold_sweep.py]"]
  node_answer_eval["Answer evaluation"]
  node_early_eval["Early-exit evaluation"]
  node_filtered_eval["Filtered evaluation"]
  node_comparison["Result comparison"]
end

node_user(("Questioner"))
node_ollama["Ollama service"]

node_user -->|"asks question"| node_app
node_app -->|"loads examples"| node_questions
node_app -->|"loads chunks"| node_chunks
node_app -->|"loads embeddings"| node_embedding_data
node_app -->|"runs selected mode"| node_normal
node_app -->|"runs selected mode"| node_filtered
node_app -->|"runs selected mode"| node_early
node_normal -->|"embeds query"| node_embed
node_normal -->|"retrieves chunks"| node_retrieval
node_normal -->|"generates answer"| node_ollama
node_filtered -->|"embeds query"| node_embed
node_filtered -->|"retrieves candidates"| node_retrieval
node_filtered -->|"scores relevance"| node_oracle
node_filtered -->|"generates answer"| node_ollama
node_early -->|"embeds query"| node_embed
node_early -->|"retrieves candidates"| node_retrieval
node_early -->|"checks evidence"| node_oracle
node_early -->|"generates answer"| node_ollama
node_oracle -->|"returns decision"| node_decision
node_embed -->|"requests embeddings"| node_ollama
node_prep -.->|"prepares questions"| node_questions
node_chunking -.->|"writes chunks"| node_chunks
node_chunking -.->|"writes questions"| node_chunked_questions
node_embed_dataset -.->|"writes embeddings"| node_embedding_data
node_embed_dataset -.->|"embeds dataset"| node_embed
node_retrieval_eval -->|"embeds queries"| node_embed
node_retrieval_eval -->|"measures recall"| node_retrieval
node_threshold -->|"embeds queries"| node_embed
node_threshold -->|"retrieves chunks"| node_retrieval
node_threshold -->|"sweeps decisions"| node_oracle
node_answer_eval -.->|"evaluates results"| node_normal
node_early_eval -.->|"evaluates results"| node_early
node_filtered_eval -.->|"evaluates results"| node_filtered
node_comparison -.->|"compares results"| node_normal
node_comparison -.->|"compares results"| node_filtered

click node_app "https://github.com/aayushbokde/decision_guided_rag/blob/main/app.py"
click node_questions "https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/questions.json"
click node_chunks "https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/chunks.json"
click node_chunked_questions "https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/chunked_questions.json"
click node_embedding_data "https://github.com/aayushbokde/decision_guided_rag/blob/main/embeddings/chunk_embeddings.json"
click node_normal "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/normal_rag/rag.py"
click node_filtered "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/rag.py"
click node_early "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/early_exit.py"
click node_oracle "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/oracle.py"
click node_decision "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/decision.py"
click node_embed "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/embeddings.py"
click node_retrieval "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/retrieval.py"
click node_prep "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/prepare_dataset.py"
click node_chunking "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/chunk_dataset.py"
click node_embed_dataset "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/embed_dataset.py"
click node_retrieval_eval "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/evaluate_retrieval.py"
click node_threshold "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/threshold_sweep.py"
click node_answer_eval "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_answers.py"
click node_early_eval "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_early_exit_answers.py"
click node_filtered_eval "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_filtered_answers.py"
click node_comparison "https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/compare_rag_results.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_app,node_questions,node_chunks,node_chunked_questions,node_embedding_data toneBlue
class node_normal,node_filtered,node_early,node_oracle,node_decision toneAmber
class node_embed,node_retrieval,node_prep,node_chunking,node_embed_dataset toneMint
class node_retrieval_eval,node_threshold,node_answer_eval,node_early_eval,node_filtered_eval,node_comparison toneRose
class node_user,node_ollama toneIndigo
```

## Components

### Interactive demo

- [Streamlit demo](https://github.com/aayushbokde/decision_guided_rag/blob/main/app.py): `app.py`
- [Question data](https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/questions.json): `processed/questions.json`
- [Chunk data](https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/chunks.json): `processed/chunks.json`
- [Chunked questions](https://github.com/aayushbokde/decision_guided_rag/blob/main/processed/chunked_questions.json): `processed/chunked_questions.json`
- [Chunk embeddings](https://github.com/aayushbokde/decision_guided_rag/blob/main/embeddings/chunk_embeddings.json): `embeddings/chunk_embeddings.json`

### RAG pipelines

- [Normal RAG](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/normal_rag/rag.py): `src/jev_rag_research/normal_rag/rag.py`
- [Filtered RAG](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/rag.py): `src/jev_rag_research/jev_rag/rag.py`
- [Early-exit RAG](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/early_exit.py): `src/jev_rag_research/jev_rag/early_exit.py`
- [Keyword oracle](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/oracle.py): `src/jev_rag_research/jev_rag/oracle.py`
- [Decision contract](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/jev_rag/decision.py): `src/jev_rag_research/jev_rag/decision.py`

### Shared retrieval

- [Text embedding](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/embeddings.py): `src/jev_rag_research/shared/embeddings.py`
- [Similarity retrieval](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/retrieval.py): `src/jev_rag_research/shared/retrieval.py`
- [Dataset preparation](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/prepare_dataset.py): `src/jev_rag_research/shared/prepare_dataset.py`
- [Dataset chunking](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/chunk_dataset.py): `src/jev_rag_research/shared/chunk_dataset.py`
- [Dataset embedding](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/embed_dataset.py): `src/jev_rag_research/shared/embed_dataset.py`

### Research evaluation

- [Retrieval evaluation](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/shared/evaluate_retrieval.py): `src/jev_rag_research/shared/evaluate_retrieval.py`
- [Threshold sweep](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/threshold_sweep.py): `src/jev_rag_research/evaluation/threshold_sweep.py`
- [Answer evaluation](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_answers.py): `src/jev_rag_research/evaluation/evaluate_answers.py`
- [Early-exit evaluation](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_early_exit_answers.py): `src/jev_rag_research/evaluation/evaluate_early_exit_answers.py`
- [Filtered evaluation](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/evaluate_filtered_answers.py): `src/jev_rag_research/evaluation/evaluate_filtered_answers.py`
- [Result comparison](https://github.com/aayushbokde/decision_guided_rag/blob/main/src/jev_rag_research/evaluation/compare_rag_results.py): `src/jev_rag_research/evaluation/compare_rag_results.py`

### Other components

- **Questioner**
- **Ollama service**

## Connections

- Questioner → Streamlit demo: asks question
- Streamlit demo → Question data: loads examples
- Streamlit demo → Chunk data: loads chunks
- Streamlit demo → Chunk embeddings: loads embeddings
- Streamlit demo → Normal RAG: runs selected mode
- Streamlit demo → Filtered RAG: runs selected mode
- Streamlit demo → Early-exit RAG: runs selected mode
- Normal RAG → Text embedding: embeds query
- Normal RAG → Similarity retrieval: retrieves chunks
- Normal RAG → Ollama service: generates answer
- Filtered RAG → Text embedding: embeds query
- Filtered RAG → Similarity retrieval: retrieves candidates
- Filtered RAG → Keyword oracle: scores relevance
- Filtered RAG → Ollama service: generates answer
- Early-exit RAG → Text embedding: embeds query
- Early-exit RAG → Similarity retrieval: retrieves candidates
- Early-exit RAG → Keyword oracle: checks evidence
- Early-exit RAG → Ollama service: generates answer
- Keyword oracle → Decision contract: returns decision
- Text embedding → Ollama service: requests embeddings
- Dataset preparation → Question data: prepares questions
- Dataset chunking → Chunk data: writes chunks
- Dataset chunking → Chunked questions: writes questions
- Dataset embedding → Chunk embeddings: writes embeddings
- Dataset embedding → Text embedding: embeds dataset
- Retrieval evaluation → Text embedding: embeds queries
- Retrieval evaluation → Similarity retrieval: measures recall
- Threshold sweep → Text embedding: embeds queries
- Threshold sweep → Similarity retrieval: retrieves chunks
- Threshold sweep → Keyword oracle: sweeps decisions
- Answer evaluation → Normal RAG: evaluates results
- Early-exit evaluation → Early-exit RAG: evaluates results
- Filtered evaluation → Filtered RAG: evaluates results
- Result comparison → Normal RAG: compares results
- Result comparison → Filtered RAG: compares results