# karimulislambd/agentic-research-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/karimulislambd/agentic-research-assistant
- Repository: https://github.com/karimulislambd/agentic-research-assistant

## Overview

This is a Streamlit research assistant for querying uploaded papers. Users upload PDFs, which are parsed into citable chunks and indexed; questions enter a Groq-backed agent that can search the papers or the web, then the UI displays its answer and citations. A separate LLM judge scores faithfulness and relevance. The graph follows the shown calls and README-described capabilities; unsampled details are not expanded beyond documented behavior.

Main entry points: [`app.py`](https://github.com/karimulislambd/agentic-research-assistant/blob/main/app.py) (Streamlit chat), [`agent/core.py`](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/core.py) (Tool-calling loop), [`config.py`](https://github.com/karimulislambd/agentic-research-assistant/blob/main/config.py) (Runtime configuration), [`rag/ingest.py`](https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/ingest.py) (PDF ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_ui["Streamlit chat<br/>[app.py]"]
end

subgraph group_rag["Paper retrieval"]
  node_ingest["PDF ingestion<br/>[ingest.py]"]
  node_chunks["PDF parsing and chunking<br/>[ingest.py]"]
  node_store[("Embedding and FAISS store<br/>[store.py]")]
end

subgraph group_agent["Agent and tools"]
  node_agentloop["Tool-calling loop<br/>[core.py]"]
  node_prompts["System prompts<br/>[prompts.py]"]
  node_dispatcher["Tool dispatcher<br/>[tools.py]"]
  node_papersearch["Paper search<br/>[tools.py]"]
  node_websearch["Web search<br/>[tools.py]"]
end

subgraph group_evaluation["Answer evaluation"]
  node_judge["LLM answer judge<br/>[judge.py]"]
end

node_user(("Researcher"))
node_config["Runtime configuration<br/>[config.py]"]
node_groq{{"Groq API"}}
node_web{{"Public web"}}

node_user -->|"asks and uploads"| node_ui
node_ui -->|"ingests PDFs"| node_ingest
node_ingest -->|"parses and chunks"| node_chunks
node_ingest -->|"adds chunks"| node_store
node_ui -->|"submits question"| node_agentloop
node_agentloop -->|"uses prompt"| node_prompts
node_agentloop -->|"dispatches tools"| node_dispatcher
node_dispatcher -->|"routes search"| node_papersearch
node_dispatcher -->|"routes search"| node_websearch
node_papersearch -->|"searches passages"| node_store
node_websearch -->|"requests results"| node_web
node_agentloop -->|"requests completions"| node_groq
node_ui -->|"evaluates answer"| node_judge
node_judge -->|"uses judge prompt"| node_prompts
node_judge -->|"requests evaluation"| node_groq
node_agentloop -->|"reads settings"| node_config
node_ui -->|"checks settings"| node_config
node_ingest -->|"reads chunk settings"| node_config
node_store -->|"reads model settings"| node_config
node_judge -->|"reads judge settings"| node_config

click node_ui "https://github.com/karimulislambd/agentic-research-assistant/blob/main/app.py"
click node_ingest "https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/ingest.py"
click node_chunks "https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/ingest.py"
click node_store "https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/store.py"
click node_agentloop "https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/core.py"
click node_prompts "https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/prompts.py"
click node_dispatcher "https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py"
click node_papersearch "https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py"
click node_websearch "https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py"
click node_judge "https://github.com/karimulislambd/agentic-research-assistant/blob/main/evaluation/judge.py"
click node_config "https://github.com/karimulislambd/agentic-research-assistant/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_ui toneBlue
class node_ingest,node_chunks,node_store toneAmber
class node_agentloop,node_prompts,node_dispatcher,node_papersearch,node_websearch,node_groq toneMint
class node_judge toneRose
class node_user,node_web toneIndigo
class node_config toneTeal
```

## Components

### User interface

- [Streamlit chat](https://github.com/karimulislambd/agentic-research-assistant/blob/main/app.py): `app.py`

### Paper retrieval

- [PDF ingestion](https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/ingest.py): `rag/ingest.py`
- [PDF parsing and chunking](https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/ingest.py): `rag/ingest.py`
- [Embedding and FAISS store](https://github.com/karimulislambd/agentic-research-assistant/blob/main/rag/store.py): `rag/store.py`

### Agent and tools

- [Tool-calling loop](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/core.py): `agent/core.py`
- [System prompts](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/prompts.py): `agent/prompts.py`
- [Tool dispatcher](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py): `agent/tools.py`
- [Paper search](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py): `agent/tools.py`
- [Web search](https://github.com/karimulislambd/agentic-research-assistant/blob/main/agent/tools.py): `agent/tools.py`

### Answer evaluation

- [LLM answer judge](https://github.com/karimulislambd/agentic-research-assistant/blob/main/evaluation/judge.py): `evaluation/judge.py`

### Other components

- **Researcher**
- [Runtime configuration](https://github.com/karimulislambd/agentic-research-assistant/blob/main/config.py): `config.py`
- **Groq API**
- **Public web**

## Connections

- Researcher → Streamlit chat: asks and uploads (evidence: `README.md`)
- Streamlit chat → PDF ingestion: ingests PDFs (evidence: `app.py`)
- PDF ingestion → PDF parsing and chunking: parses and chunks (evidence: `rag/ingest.py`)
- PDF ingestion → Embedding and FAISS store: adds chunks (evidence: `rag/ingest.py`)
- Streamlit chat → Tool-calling loop: submits question (evidence: `app.py`)
- Tool-calling loop → System prompts: uses prompt (evidence: `agent/core.py`)
- Tool-calling loop → Tool dispatcher: dispatches tools (evidence: `agent/core.py`)
- Tool dispatcher → Paper search: routes search (evidence: `agent/tools.py`)
- Tool dispatcher → Web search: routes search (evidence: `agent/tools.py`)
- Paper search → Embedding and FAISS store: searches passages (evidence: `agent/tools.py`)
- Web search → Public web: requests results (evidence: `agent/tools.py`)
- Tool-calling loop → Groq API: requests completions (evidence: `agent/core.py`)
- Streamlit chat → LLM answer judge: evaluates answer (evidence: `app.py`)
- LLM answer judge → System prompts: uses judge prompt (evidence: `evaluation/judge.py`)
- LLM answer judge → Groq API: requests evaluation (evidence: `evaluation/judge.py`)
- Tool-calling loop → Runtime configuration: reads settings (evidence: `agent/core.py`)
- Streamlit chat → Runtime configuration: checks settings (evidence: `app.py`)
- PDF ingestion → Runtime configuration: reads chunk settings (evidence: `rag/ingest.py`)
- Embedding and FAISS store → Runtime configuration: reads model settings (evidence: `rag/store.py`)
- LLM answer judge → Runtime configuration: reads judge settings (evidence: `evaluation/judge.py`)
