# jmponcebe/pharmagraphrag architecture

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

- Interactive diagram: https://gitdiagram.com/jmponcebe/pharmagraphrag
- Repository: https://github.com/jmponcebe/pharmagraphrag

## Overview

PharmaGraphRAG answers pharmaceutical safety questions by combining FAERS-derived relationships in Neo4j with semantic retrieval over DailyMed label text, then generating grounded responses. Users enter through the Streamlit chat or REST API; classic queries extract entities, retrieve graph and vector context, and invoke an LLM. Agent and multi-agent modes select specialized tools against the same knowledge layer. Data ingestion and evaluation are included as product capabilities. Some subsystem wiring is documented in the README but was not present in sampled source, so uncertain links are omitted.

Main entry points: [`src/pharmagraphrag/api/main.py`](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/api/main.py) (REST API), [`src/pharmagraphrag/agent/tools.py`](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/tools.py) (Agent Tools), [`src/pharmagraphrag/vectorstore/store.py`](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/store.py) (Vector Store), [`src/pharmagraphrag/ui/app.py`](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/ui/app.py) (Streamlit Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_ui["Streamlit Chat<br/>[app.py]"]
  node_api["REST API<br/>[main.py]"]
end

subgraph group_query["Query and Retrieval"]
  node_queryengine["Query Engine<br/>[query_engine.py]"]
  node_entities["Entity Extraction"]
  node_retriever["Dual Retriever<br/>[retriever.py]"]
  node_llm["LLM Client<br/>[client.py]"]
end

subgraph group_agent["Agent Modes"]
  node_agentgraph["ReAct Agent<br/>[graph.py]"]
  node_agenttools["Agent Tools<br/>[tools.py]"]
  node_supervisor["Multi-Agent Supervisor<br/>[multi.py]"]
end

subgraph group_knowledge["Knowledge Stores"]
  node_graphqueries["Graph Queries<br/>[queries.py]"]
  node_neo4j[("Neo4j Graph")]
  node_vectorstore[("Vector Store<br/>[store.py]")]
  node_chromadb[("ChromaDB")]
end

subgraph group_ingest["Data Ingestion"]
  node_faersclean["FAERS Cleaning<br/>[clean_faers.py]"]
  node_labelingest["Label Ingestion<br/>[ingest_dailymed.py]"]
  node_graphloader["Graph Loader<br/>[loader.py]"]
  node_chunker["Text Chunking<br/>[chunker.py]"]
  node_embedder["Embedding<br/>[embedder.py]"]
end

node_user(("Questioner"))
node_faers["FDA FAERS"]
node_dailymed["DailyMed / openFDA"]
node_gemini["Gemini API"]
node_ollama["Ollama"]

node_user -->|"asks"| node_ui
node_user -->|"requests"| node_api
node_ui -.->|"HTTP query"| node_api
node_api -->|"processes query"| node_queryengine
node_queryengine -->|"extracts entities"| node_entities
node_queryengine -->|"retrieves context"| node_retriever
node_retriever -->|"fetches graph context"| node_graphqueries
node_graphqueries -->|"queries"| node_neo4j
node_retriever -->|"searches labels"| node_vectorstore
node_vectorstore -->|"queries"| node_chromadb
node_api -->|"generates answer"| node_llm
node_llm -->|"generates"| node_gemini
node_llm -.->|"generates"| node_ollama
node_ui -.->|"local agent mode"| node_agentgraph
node_api -->|"runs agent query"| node_agentgraph
node_api -->|"runs multi-agent"| node_supervisor
node_agentgraph -->|"dispatches tools"| node_agenttools
node_supervisor -->|"delegates tool work"| node_agenttools
node_agenttools -->|"retrieves drug data"| node_graphqueries
node_agenttools -->|"searches label text"| node_vectorstore
node_faers -->|"provides reports"| node_faersclean
node_dailymed -->|"provides labels"| node_labelingest
node_faersclean -->|"supplies processed data"| node_graphloader
node_labelingest -->|"supplies label data"| node_graphloader
node_graphloader -->|"loads graph"| node_neo4j
node_labelingest -->|"supplies label text"| node_chunker
node_chunker -->|"prepares chunks"| node_embedder
node_embedder -->|"adds embeddings"| node_vectorstore

click node_ui "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/ui/app.py"
click node_api "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/api/main.py"
click node_queryengine "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/query_engine.py"
click node_entities "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/entity_extractor.py"
click node_retriever "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/retriever.py"
click node_llm "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/llm/client.py"
click node_graphqueries "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/graph/queries.py"
click node_vectorstore "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/store.py"
click node_agentgraph "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/graph.py"
click node_agenttools "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/tools.py"
click node_supervisor "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/multi.py"
click node_faersclean "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/data/clean_faers.py"
click node_labelingest "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/data/ingest_dailymed.py"
click node_graphloader "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/graph/loader.py"
click node_chunker "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/chunker.py"
click node_embedder "https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/embedder.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,node_api toneBlue
class node_queryengine,node_entities,node_retriever,node_llm toneAmber
class node_agentgraph,node_agenttools,node_supervisor,node_gemini toneMint
class node_graphqueries,node_neo4j,node_vectorstore,node_chromadb toneRose
class node_faersclean,node_labelingest,node_graphloader,node_chunker,node_embedder,node_user,node_faers,node_dailymed,node_ollama toneIndigo
```

## Components

### User Interfaces

- [Streamlit Chat](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/ui/app.py): `src/pharmagraphrag/ui/app.py`
- [REST API](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/api/main.py): `src/pharmagraphrag/api/main.py`

### Query and Retrieval

- [Query Engine](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/query_engine.py): `src/pharmagraphrag/engine/query_engine.py`
- [Entity Extraction](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/entity_extractor.py): `src/pharmagraphrag/engine/entity_extractor.py`
- [Dual Retriever](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/engine/retriever.py): `src/pharmagraphrag/engine/retriever.py`
- [LLM Client](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/llm/client.py): `src/pharmagraphrag/llm/client.py`

### Agent Modes

- [ReAct Agent](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/graph.py): `src/pharmagraphrag/agent/graph.py`
- [Agent Tools](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/tools.py): `src/pharmagraphrag/agent/tools.py`
- [Multi-Agent Supervisor](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/agent/multi.py): `src/pharmagraphrag/agent/multi.py`

### Knowledge Stores

- [Graph Queries](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/graph/queries.py): `src/pharmagraphrag/graph/queries.py`
- **Neo4j Graph**
- [Vector Store](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/store.py): `src/pharmagraphrag/vectorstore/store.py`
- **ChromaDB**

### Data Ingestion

- [FAERS Cleaning](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/data/clean_faers.py): `src/pharmagraphrag/data/clean_faers.py`
- [Label Ingestion](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/data/ingest_dailymed.py): `src/pharmagraphrag/data/ingest_dailymed.py`
- [Graph Loader](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/graph/loader.py): `src/pharmagraphrag/graph/loader.py`
- [Text Chunking](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/chunker.py): `src/pharmagraphrag/vectorstore/chunker.py`
- [Embedding](https://github.com/jmponcebe/pharmagraphrag/blob/main/src/pharmagraphrag/vectorstore/embedder.py): `src/pharmagraphrag/vectorstore/embedder.py`

### Other components

- **Questioner**
- **FDA FAERS**
- **DailyMed / openFDA**
- **Gemini API**
- **Ollama**

## Connections

- Questioner → Streamlit Chat: asks
- Questioner → REST API: requests
- Streamlit Chat → REST API: HTTP query
- REST API → Query Engine: processes query
- Query Engine → Entity Extraction: extracts entities
- Query Engine → Dual Retriever: retrieves context
- Dual Retriever → Graph Queries: fetches graph context
- Graph Queries → Neo4j Graph: queries
- Dual Retriever → Vector Store: searches labels
- Vector Store → ChromaDB: queries
- REST API → LLM Client: generates answer
- LLM Client → Gemini API: generates
- LLM Client → Ollama: generates
- Streamlit Chat → ReAct Agent: local agent mode
- REST API → ReAct Agent: runs agent query
- REST API → Multi-Agent Supervisor: runs multi-agent
- ReAct Agent → Agent Tools: dispatches tools
- Multi-Agent Supervisor → Agent Tools: delegates tool work
- Agent Tools → Graph Queries: retrieves drug data
- Agent Tools → Vector Store: searches label text
- FDA FAERS → FAERS Cleaning: provides reports
- DailyMed / openFDA → Label Ingestion: provides labels
- FAERS Cleaning → Graph Loader: supplies processed data
- Label Ingestion → Graph Loader: supplies label data
- Graph Loader → Neo4j Graph: loads graph
- Label Ingestion → Text Chunking: supplies label text
- Text Chunking → Embedding: prepares chunks
- Embedding → Vector Store: adds embeddings