# majdzidan-dev/agentic-rag architecture

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

- Interactive diagram: https://gitdiagram.com/majdzidan-dev/agentic-rag
- Repository: https://github.com/majdzidan-dev/agentic-rag

## Overview

AgenticRag is a command-line research assistant. The user enters a question in the chat loop; the agent selects a calculator, general web search, or PubMed research tool, then returns a response with scientific citations where applicable. PubMed search checks local coverage, fetches and chunks papers when needed, indexes them, retrieves and reranks passages, and can grade and rewrite queries before returning excerpts. The README documents an isolated retrieval-evaluation capability as well. Edges reflect the excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`tools/pubmed_rag.py`](https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/pubmed_rag.py) (PubMed Search Tool), [`agent.py`](https://github.com/majdzidan-dev/agentic-rag/blob/main/agent.py) (Gemini Agent), [`eval/run_eval.py`](https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/run_eval.py) (Evaluation Runner), [`rag/retrieval_grader.py`](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/retrieval_grader.py) (Retrieval Grader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_conversation["Conversation"]
  node_chat["Chat Loop<br/>[main.py]"]
  node_agent["Gemini Agent<br/>[agent.py]"]
  node_config["API Configuration<br/>[config.py]"]
end

subgraph group_tools["Assistant Tools"]
  node_calculator["Calculator<br/>[calculator.py]"]
  node_web["Web Search<br/>[web_search.py]"]
end

subgraph group_research["PubMed Research"]
  node_pubmed_tool["PubMed Search Tool<br/>[pubmed_rag.py]"]
  node_chunking["Abstract Chunking<br/>[pubmed_rag.py]"]
  node_hybrid["Hybrid Search<br/>[hybrid_search.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[reranker.py]"]
  node_grader["Retrieval Grader"]
  node_text_utils["LLM Text Helper<br/>[llm_utils.py]"]
end

subgraph group_stores["Knowledge Stores"]
  node_vector[("Vector Store<br/>[vector_store.py]")]
  node_keyword[("BM25 Index<br/>[keyword_store.py]")]
end

subgraph group_evaluation["Retrieval Evaluation"]
  node_eval_runner["Evaluation Runner<br/>[run_eval.py]"]
  node_eval_variants["Retrieval Variants"]
  node_metrics["Ranking Metrics<br/>[metrics.py]"]
end

node_user(("User"))
node_gemini{{"Gemini"}}
node_serp{{"SerpAPI"}}
node_pubmed{{"PubMed API"}}

node_user -->|"enters question"| node_chat
node_chat -->|"invokes"| node_agent
node_agent -->|"uses model"| node_gemini
node_agent -->|"dispatches"| node_calculator
node_agent -->|"dispatches"| node_web
node_agent -->|"dispatches"| node_pubmed_tool
node_web -->|"searches"| node_serp
node_pubmed_tool -->|"fetches papers"| node_pubmed
node_pubmed_tool -->|"chunks abstracts"| node_chunking
node_chunking -->|"indexes chunks"| node_vector
node_chunking -->|"indexes chunks"| node_keyword
node_pubmed_tool -->|"checks coverage"| node_vector
node_pubmed_tool -->|"retrieves candidates"| node_hybrid
node_hybrid -->|"queries dense index"| node_vector
node_hybrid -->|"queries BM25"| node_keyword
node_pubmed_tool -->|"reranks candidates"| node_reranker
node_pubmed_tool -->|"grades excerpts"| node_grader
node_grader -->|"grades and rewrites"| node_gemini
node_grader -->|"extracts response text"| node_text_utils
node_config -->|"provides API key"| node_agent
node_config -->|"provides API key"| node_web
node_config -->|"provides API key"| node_grader
node_config -->|"provides API key"| node_vector
node_eval_runner -->|"resets eval collection"| node_vector
node_eval_runner -->|"resets eval corpus"| node_keyword
node_eval_runner -->|"indexes known papers"| node_pubmed_tool
node_eval_runner -->|"runs variants"| node_eval_variants
node_eval_variants -->|"runs hybrid search"| node_hybrid
node_eval_variants -->|"reranks candidates"| node_reranker
node_eval_variants -->|"grades and rewrites"| node_grader
node_eval_runner -->|"scores rankings"| node_metrics

click node_chat "https://github.com/majdzidan-dev/agentic-rag/blob/main/main.py"
click node_agent "https://github.com/majdzidan-dev/agentic-rag/blob/main/agent.py"
click node_config "https://github.com/majdzidan-dev/agentic-rag/blob/main/config.py"
click node_calculator "https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/calculator.py"
click node_web "https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/web_search.py"
click node_pubmed_tool "https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/pubmed_rag.py"
click node_chunking "https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/pubmed_rag.py"
click node_hybrid "https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/hybrid_search.py"
click node_reranker "https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/reranker.py"
click node_grader "https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/retrieval_grader.py"
click node_text_utils "https://github.com/majdzidan-dev/agentic-rag/blob/main/llm_utils.py"
click node_vector "https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/vector_store.py"
click node_keyword "https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/keyword_store.py"
click node_eval_runner "https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/run_eval.py"
click node_eval_variants "https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/retrieval_variants.py"
click node_metrics "https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/metrics.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_chat,node_agent,node_config,node_user toneBlue
class node_calculator,node_web toneAmber
class node_pubmed_tool,node_chunking,node_hybrid,node_reranker,node_grader,node_text_utils,node_serp,node_pubmed toneMint
class node_vector,node_keyword toneRose
class node_eval_runner,node_eval_variants,node_metrics,node_gemini toneIndigo
```

## Components

### Conversation

- [Chat Loop](https://github.com/majdzidan-dev/agentic-rag/blob/main/main.py): `main.py`
- [Gemini Agent](https://github.com/majdzidan-dev/agentic-rag/blob/main/agent.py): `agent.py`
- [API Configuration](https://github.com/majdzidan-dev/agentic-rag/blob/main/config.py): `config.py`

### Assistant Tools

- [Calculator](https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/calculator.py): `tools/calculator.py`
- [Web Search](https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/web_search.py): `tools/web_search.py`

### PubMed Research

- [PubMed Search Tool](https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/pubmed_rag.py): `tools/pubmed_rag.py`
- [Abstract Chunking](https://github.com/majdzidan-dev/agentic-rag/blob/main/tools/pubmed_rag.py): `tools/pubmed_rag.py`
- [Hybrid Search](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/hybrid_search.py): `rag/hybrid_search.py`
- [Cross-Encoder Reranker](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/reranker.py): `rag/reranker.py`
- [Retrieval Grader](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/retrieval_grader.py): `rag/retrieval_grader.py`
- [LLM Text Helper](https://github.com/majdzidan-dev/agentic-rag/blob/main/llm_utils.py): `llm_utils.py`

### Knowledge Stores

- [Vector Store](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/vector_store.py): `rag/vector_store.py`
- [BM25 Index](https://github.com/majdzidan-dev/agentic-rag/blob/main/rag/keyword_store.py): `rag/keyword_store.py`

### Retrieval Evaluation

- [Evaluation Runner](https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/run_eval.py): `eval/run_eval.py`
- [Retrieval Variants](https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/retrieval_variants.py): `eval/retrieval_variants.py`
- [Ranking Metrics](https://github.com/majdzidan-dev/agentic-rag/blob/main/eval/metrics.py): `eval/metrics.py`

### Other components

- **User**
- **Gemini**
- **SerpAPI**
- **PubMed API**

## Connections

- User → Chat Loop: enters question (evidence: `README.md`)
- Chat Loop → Gemini Agent: invokes (evidence: `main.py`)
- Gemini Agent → Gemini: uses model (evidence: `agent.py`)
- Gemini Agent → Calculator: dispatches (evidence: `agent.py`)
- Gemini Agent → Web Search: dispatches (evidence: `agent.py`)
- Gemini Agent → PubMed Search Tool: dispatches (evidence: `agent.py`)
- Web Search → SerpAPI: searches (evidence: `tools/web_search.py`)
- PubMed Search Tool → PubMed API: fetches papers (evidence: `tools/pubmed_rag.py`)
- PubMed Search Tool → Abstract Chunking: chunks abstracts (evidence: `tools/pubmed_rag.py`)
- Abstract Chunking → Vector Store: indexes chunks (evidence: `tools/pubmed_rag.py`)
- Abstract Chunking → BM25 Index: indexes chunks (evidence: `tools/pubmed_rag.py`)
- PubMed Search Tool → Vector Store: checks coverage (evidence: `tools/pubmed_rag.py`)
- PubMed Search Tool → Hybrid Search: retrieves candidates (evidence: `tools/pubmed_rag.py`)
- Hybrid Search → Vector Store: queries dense index (evidence: `rag/hybrid_search.py`)
- Hybrid Search → BM25 Index: queries BM25 (evidence: `rag/hybrid_search.py`)
- PubMed Search Tool → Cross-Encoder Reranker: reranks candidates (evidence: `tools/pubmed_rag.py`)
- PubMed Search Tool → Retrieval Grader: grades excerpts (evidence: `tools/pubmed_rag.py`)
- Retrieval Grader → Gemini: grades and rewrites (evidence: `rag/retrieval_grader.py`)
- Retrieval Grader → LLM Text Helper: extracts response text (evidence: `rag/retrieval_grader.py`)
- API Configuration → Gemini Agent: provides API key (evidence: `agent.py`)
- API Configuration → Web Search: provides API key (evidence: `tools/web_search.py`)
- API Configuration → Retrieval Grader: provides API key (evidence: `rag/retrieval_grader.py`)
- API Configuration → Vector Store: provides API key (evidence: `rag/vector_store.py`)
- Evaluation Runner → Vector Store: resets eval collection (evidence: `eval/run_eval.py`)
- Evaluation Runner → BM25 Index: resets eval corpus (evidence: `eval/run_eval.py`)
- Evaluation Runner → PubMed Search Tool: indexes known papers (evidence: `eval/run_eval.py`)
- Evaluation Runner → Retrieval Variants: runs variants (evidence: `eval/run_eval.py`)
- Retrieval Variants → Hybrid Search: runs hybrid search (evidence: `eval/retrieval_variants.py`)
- Retrieval Variants → Cross-Encoder Reranker: reranks candidates (evidence: `eval/retrieval_variants.py`)
- Retrieval Variants → Retrieval Grader: grades and rewrites (evidence: `eval/retrieval_variants.py`)
- Evaluation Runner → Ranking Metrics: scores rankings (evidence: `eval/run_eval.py`)
