# fareedkhan-dev/agentic-knowledge-graph architecture

> Architecture diagram of the GitHub repository fareedkhan-dev/agentic-knowledge-graph, 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/fareedkhan-dev/agentic-knowledge-graph
- Repository: https://github.com/fareedkhan-dev/agentic-knowledge-graph

## Overview

This repository is a research system for evidence-grounded biomedical question answering over PubMed. Its principal workflow turns PubMed metadata into citation/MeSH graph and abstract-vector indexes, then grounds a question, retrieves and ranks evidence, and returns a supported answer or refuses. The README also documents calibration and adversarial evaluation as important project outcomes. The graph follows documented architecture and sampled agent, traversal, retrieval, and analysis code; several construction and query links rely on README descriptions because their source was not sampled.

Main entry points: [`pipeline/kg_agent.py`](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_agent.py) (Agent traversal loop), [`pipeline/parse_pubmed.py`](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_pubmed.py) (Parquet corpus), [`pipeline/kg_traverse2.py`](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py) (Refusal and evidence gates), [`analysis/analyze_fusion.py`](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_fusion.py) (Posterior and calibration analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Corpus ingestion"]
  node_parse["XML parsing<br/>[parse_pubmed.py]"]
  node_meshparse["MeSH and SCR parsing<br/>[parse_mesh.py]"]
  node_parquet[("Parquet corpus<br/>[parse_pubmed.py]")]
end

subgraph group_indexes["Knowledge indexes"]
  node_graphbuild["Citation and ontology graph build<br/>[build_graph1.py]"]
  node_csr[("CSR knowledge graph<br/>[kg_traverse2.py]")]
  node_embedding["Abstract embedding<br/>[embed_corpus3.py]"]
  node_denseindex[("Dense vector index<br/>[embed_corpus3.py]")]
end

subgraph group_answering["Evidence answering"]
  node_agent["Agent traversal loop<br/>[kg_agent.py]"]
  node_grounder["MeSH grounding<br/>[kg_ground6.py]"]
  node_traversal["Provenance path search<br/>[kg_traverse2.py]"]
  node_retrieval["Dense retrieval<br/>[exp_fusion2.py]"]
  node_ranker["Evidence reranking<br/>[kg_answer.py]"]
  node_generator["Constrained answer generation<br/>[exp_fusion2.py]"]
  node_governance["Refusal and evidence gates<br/>[kg_traverse2.py]"]
end

subgraph group_evaluation["Evaluation and governance"]
  node_fusion["Posterior and calibration analysis<br/>[analyze_fusion.py]"]
  node_erroranalysis["Error and abstention analysis<br/>[analyze_maybe.py]"]
  node_govanalysis["Governance evaluation"]
end

node_pubmed(("PubMed baseline"))
node_question(("Biomedical question"))
node_answer["Answer with source path"]
node_refusal["Refusal"]

node_pubmed -->|"supplies XML"| node_parse
node_parse -->|"writes articles"| node_parquet
node_meshparse -->|"writes ontology"| node_parquet
node_parquet -->|"provides metadata"| node_graphbuild
node_graphbuild -->|"builds graph"| node_csr
node_parquet -->|"provides abstracts"| node_embedding
node_embedding -->|"writes vectors"| node_denseindex
node_question -->|"initiates query"| node_agent
node_agent -->|"grounds terms"| node_grounder
node_agent -->|"searches paths"| node_traversal
node_traversal -->|"reads graph"| node_csr
node_agent -->|"retrieves candidates"| node_retrieval
node_retrieval -->|"searches vectors"| node_denseindex
node_agent -->|"ranks evidence"| node_ranker
node_agent -->|"requests answer"| node_generator
node_agent -->|"checks evidence"| node_governance
node_governance -->|"permits supported result"| node_answer
node_governance -->|"rejects unsupported result"| node_refusal
node_fusion -->|"supplies cached posteriors"| node_erroranalysis
node_fusion -->|"supplies cached predictions"| node_govanalysis

click node_parse "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_pubmed.py"
click node_meshparse "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_mesh.py"
click node_parquet "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_pubmed.py"
click node_graphbuild "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/build_graph1.py"
click node_csr "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py"
click node_embedding "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/embed_corpus3.py"
click node_denseindex "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/embed_corpus3.py"
click node_agent "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_agent.py"
click node_grounder "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_ground6.py"
click node_traversal "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py"
click node_retrieval "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/exp_fusion2.py"
click node_ranker "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_answer.py"
click node_generator "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/exp_fusion2.py"
click node_governance "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py"
click node_fusion "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_fusion.py"
click node_erroranalysis "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_maybe.py"
click node_govanalysis "https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_governance.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_parse,node_meshparse,node_parquet toneBlue
class node_graphbuild,node_csr,node_embedding,node_denseindex toneAmber
class node_agent,node_grounder,node_traversal,node_retrieval,node_ranker,node_generator,node_governance toneMint
class node_fusion,node_erroranalysis,node_govanalysis toneRose
class node_pubmed,node_question,node_answer,node_refusal toneIndigo
```

## Components

### Corpus ingestion

- [XML parsing](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_pubmed.py): `pipeline/parse_pubmed.py`
- [MeSH and SCR parsing](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_mesh.py): `pipeline/parse_mesh.py`
- [Parquet corpus](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/parse_pubmed.py): `pipeline/parse_pubmed.py`

### Knowledge indexes

- [Citation and ontology graph build](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/build_graph1.py): `pipeline/build_graph1.py`
- [CSR knowledge graph](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py): `pipeline/kg_traverse2.py`
- [Abstract embedding](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/embed_corpus3.py): `pipeline/embed_corpus3.py`
- [Dense vector index](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/embed_corpus3.py): `pipeline/embed_corpus3.py`

### Evidence answering

- [Agent traversal loop](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_agent.py): `pipeline/kg_agent.py`
- [MeSH grounding](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_ground6.py): `pipeline/kg_ground6.py`
- [Provenance path search](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py): `pipeline/kg_traverse2.py`
- [Dense retrieval](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/exp_fusion2.py): `pipeline/exp_fusion2.py`
- [Evidence reranking](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_answer.py): `pipeline/kg_answer.py`
- [Constrained answer generation](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/exp_fusion2.py): `pipeline/exp_fusion2.py`
- [Refusal and evidence gates](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/pipeline/kg_traverse2.py): `pipeline/kg_traverse2.py`

### Evaluation and governance

- [Posterior and calibration analysis](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_fusion.py): `analysis/analyze_fusion.py`
- [Error and abstention analysis](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_maybe.py): `analysis/analyze_maybe.py`
- [Governance evaluation](https://github.com/fareedkhan-dev/agentic-knowledge-graph/blob/main/analysis/analyze_governance.py): `analysis/analyze_governance.py`

### Other components

- **PubMed baseline**
- **Biomedical question**
- **Answer with source path**
- **Refusal**

## Connections

- PubMed baseline → XML parsing: supplies XML
- XML parsing → Parquet corpus: writes articles
- MeSH and SCR parsing → Parquet corpus: writes ontology
- Parquet corpus → Citation and ontology graph build: provides metadata
- Citation and ontology graph build → CSR knowledge graph: builds graph
- Parquet corpus → Abstract embedding: provides abstracts
- Abstract embedding → Dense vector index: writes vectors
- Biomedical question → Agent traversal loop: initiates query
- Agent traversal loop → MeSH grounding: grounds terms
- Agent traversal loop → Provenance path search: searches paths
- Provenance path search → CSR knowledge graph: reads graph
- Agent traversal loop → Dense retrieval: retrieves candidates
- Dense retrieval → Dense vector index: searches vectors
- Agent traversal loop → Evidence reranking: ranks evidence
- Agent traversal loop → Constrained answer generation: requests answer
- Agent traversal loop → Refusal and evidence gates: checks evidence
- Refusal and evidence gates → Answer with source path: permits supported result
- Refusal and evidence gates → Refusal: rejects unsupported result
- Posterior and calibration analysis → Error and abstention analysis: supplies cached posteriors
- Posterior and calibration analysis → Governance evaluation: supplies cached predictions