# harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system architecture

> Architecture diagram of the GitHub repository harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system
- Repository: https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system

## Overview

1. **Overall shape**
   This is a Python, state-graph-driven biomedical analysis app. The runtime entrypoint appears to be `app.py`, which drives a LangGraph-style pipeline defined under `pipeline/`. The system is organized as a sequence of stateful nodes rather than a monolithic model call.

2. **Primary use case**
   The repository is focused on PCOS hypothesis analysis from a small clinical input vector, with an emphasis on explainability and auditability. The README describes a clinician-facing decision-support workflow: retrieve literature, synthesize a hypothesis, score it mathematically, and present an explainable summary.

3. **Execution pipeline**
   The core architecture lives in `pipeline/graph.py`, `pipeline/state.py`, and `pipeline/nodes/`. The nodes represent ordered processing stages:
   - ingestion / retrieval
   - hypothesis generation
   - dual analysis
   - assembly
   - XAI generation
   - judge/guard logic

4. **Node 1: retrieval and grounding**
   `pipeline/nodes/node1_ingestion.py` is the grounding layer. It likely combines the incoming patient features with biomedical context pulled from local corpus/cache data. The repository includes `data/pcos_literature_corpus.json` and `data/pubmed_cache.json`, which strongly suggests the retrieval step is designed to work from cached PubMed-style literature rather than live web scraping alone.

5. **Node 2: hypothesis synthesis**
   `pipeline/nodes/node2_hypothesis.py` is the reasoning layer that transforms the retrieved context plus clinical facts into a structured hypothesis. This is where the multi-agent or consensus-style logic described in the README would live, producing phenotype/risk/biomarker-style outputs for downstream evaluation.

6. **Node 3: dual analysis**
   `pipeline/nodes/node3_dual_analysis.py` is the scoring and validation layer. The README indicates two mathematical lenses: a classical Bayesian-style credibility update and a simulated quantum/plausibility metric. The corresponding support code likely sits in `utils/quantum_utils.py`, with this node converting the hypothesis into numeric confidence/consistency signals.

7. **Assembly and explainability**
   `pipeline/nodes/node4_assembly.py` and `pipeline/nodes/node5_xai.py` form the packaging and explanation boundary. Assembly consolidates outputs from prior nodes into a schema-consistent result, while XAI turns that result into human-readable rationale. The README explicitly frames this as the “clinical diagnostic dossier” stage.

8. **Control and safety**
   `pipeline/nodes/node_judge.py` suggests a supervisory node for loop control, acceptance/rejection, or guardrail decisions. This is important architecturally because it separates “generate” from “approve/continue,” which helps prevent uncontrolled recursion or low-confidence propagation through the graph.

9. **State and data boundaries**
   `pipeline/state.py` likely defines the shared state object passed between nodes. That shared state is the main in-memory boundary of the system: each node reads the previous node’s outputs and writes its own artifacts back into the graph state. For architecture diagrams, this is the central data bus of the application.

10. **Persistence and observability**
   The repo has a dedicated audit path under `data/audit_trail/` plus `utils/audit_logger.py`. That means the system is designed to persist intermediate reasoning, not just final answers. This audit trail is a separate compliance/traceability boundary from the main inference path.

11. **External/data dependencies**
   The notable non-core dependencies are:
   - **PubMed/literature grounding** via cached data and `utils/pubmed_client.py`
   - **Neo4j support** via `utils/neo4j_client.py` and `utils/neo4j_seed.py`, though the README says knowledge-graph sources were removed/simplified, so this looks more like legacy, optional, or test-support infrastructure than the main path
   - **LLM/Ollama integration** suggested by tests such as `tests/test_ollama.py`, indicating local model inference is part of the environment

12. **Data assets**
   The `data/` folder is part of the architecture, not just fixtures. It contains mock patient inputs, PCOS thresholds, a curated literature corpus, and cached PubMed responses. That means the app can run in a semi-offline, reproducible mode with deterministic inputs for testing and demos.

13. **Quality and verification**
   The `tests/` directory is broad and architecture-relevant: it checks imports, PubMed retrieval, query behavior, pipeline evaluation, app remarks, Ollama integration, and Neo4j connectivity/relation inspection. This indicates the system has multiple integration boundaries, not just pure unit tests.

14. **What to show in a diagram**
   A good diagram should emphasize four layers:  
   - **UI / entrypoint**: `app.py`  
   - **Stateful pipeline**: `pipeline/graph.py` plus the node chain  
   - **Support services**: PubMed/cache, audit logger, optional Neo4j, quantum utilities  
   - **Data stores**: local JSON corpora, thresholds, mock patients, audit trail  
   The key flow is patient input → retrieval → hypothesis → scoring → assembly/XAI → audited output.

Main entry points: [`pipeline/state.py`](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/state.py) (State), [`pipeline/nodes/node3_dual_analysis.py`](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node3_dual_analysis.py) (Dual Analysis), [`pipeline/nodes/node1_ingestion.py`](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node1_ingestion.py) (Ingestion), [`pipeline/nodes/node4_assembly.py`](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node4_assembly.py) (Assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_app["App<br/>entrypoint<br/>[app.py]"]
end

subgraph group_pipeline["Pipeline"]
  node_graph["Graph<br/>[graph.py]"]
  node_state[("State<br/>[state.py]")]
  node_crew["Crew Setup<br/>agent wiring<br/>[crew_setup.py]"]
  node_ingestion["Ingestion<br/>grounding node<br/>[node1_ingestion.py]"]
  node_hypothesis["Hypothesis<br/>reasoning node"]
  node_analysis["Dual Analysis<br/>scoring node"]
  node_assembly["Assembly<br/>packaging node<br/>[node4_assembly.py]"]
  node_xai["XAI<br/>explanation node<br/>[node5_xai.py]"]
  node_judge["Judge<br/>guard node<br/>[node_judge.py]"]
end

subgraph group_support["Support"]
  node_pubmed["PubMed Client<br/>retrieval service<br/>[pubmed_client.py]"]
  node_quantum["Quantum Utils<br/>metrics helper<br/>[quantum_utils.py]"]
  node_audit["Audit Logger<br/>logging service<br/>[audit_logger.py]"]
  node_neo4j[("Neo4j Client<br/>graph db adapter<br/>[neo4j_client.py]")]
end

subgraph group_data["Data"]
  node_patients["Mock Patients<br/>input dataset<br/>[mock_patients.json]"]
  node_corpus["Literature Corpus<br/>corpus dataset"]
  node_thresholds["Thresholds<br/>rules dataset"]
  node_cache["PubMed Cache<br/>cache dataset<br/>[pubmed_cache.json]"]
  node_trail[("Audit Trail<br/>output store")]
end

node_app -->|"launches"| node_graph
node_graph -->|"uses"| node_state
node_graph -->|"configures"| node_crew
node_state -->|"feeds"| node_ingestion
node_ingestion -->|"retrieves"| node_pubmed
node_pubmed -->|"consults"| node_corpus
node_pubmed -->|"reads"| node_cache
node_ingestion -->|"passes context"| node_hypothesis
node_hypothesis -->|"scores"| node_analysis
node_analysis -->|"computes"| node_quantum
node_analysis -->|"outputs"| node_assembly
node_assembly -->|"explains"| node_xai
node_xai -->|"reviews"| node_judge
node_judge -.->|"loop back"| node_ingestion
node_judge -->|"accepts"| node_assembly
node_assembly -->|"logs"| node_audit
node_audit -->|"persists"| node_trail
node_analysis -.->|"optional lookup"| node_neo4j
node_state -->|"initializes from"| node_patients
node_state -->|"references"| node_thresholds

click node_app "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/app.py"
click node_graph "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/graph.py"
click node_state "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/state.py"
click node_crew "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/agents/crew_setup.py"
click node_ingestion "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node1_ingestion.py"
click node_hypothesis "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node2_hypothesis.py"
click node_analysis "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node3_dual_analysis.py"
click node_assembly "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node4_assembly.py"
click node_xai "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node5_xai.py"
click node_judge "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node_judge.py"
click node_pubmed "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/pubmed_client.py"
click node_quantum "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/quantum_utils.py"
click node_audit "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/audit_logger.py"
click node_neo4j "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/neo4j_client.py"
click node_patients "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/mock_patients.json"
click node_corpus "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pcos_literature_corpus.json"
click node_thresholds "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pcos_thresholds.json"
click node_cache "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pubmed_cache.json"
click node_trail "https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/tree/main/data/audit_trail"

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 toneBlue
class node_graph,node_state,node_crew,node_ingestion,node_hypothesis,node_analysis,node_assembly,node_xai,node_judge toneAmber
class node_pubmed,node_quantum,node_audit,node_neo4j toneMint
class node_patients,node_corpus,node_thresholds,node_cache,node_trail toneRose
```

## Components

### Entry

Runtime entrypoint and top-level app orchestration

- [App](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/app.py): entrypoint · Starts the analysis workflow · `app.py`

### Pipeline

Stateful LangGraph-style analysis workflow

- [Graph](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/graph.py): workflow graph · Builds and connects the stateful pipeline · `pipeline/graph.py`
- [State](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/state.py): shared state · Carries data between pipeline stages · `pipeline/state.py`
- [Crew Setup](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/agents/crew_setup.py): agent wiring · Configures agent/runtime behavior · `pipeline/agents/crew_setup.py`
- [Ingestion](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node1_ingestion.py): grounding node · Combines patient input with literature context · `pipeline/nodes/node1_ingestion.py`
- [Hypothesis](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node2_hypothesis.py): reasoning node · Synthesizes a structured PCOS hypothesis · `pipeline/nodes/node2_hypothesis.py`
- [Dual Analysis](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node3_dual_analysis.py): scoring node · Applies credibility and plausibility scoring · `pipeline/nodes/node3_dual_analysis.py`
- [Assembly](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node4_assembly.py): packaging node · Consolidates stage outputs into final structure · `pipeline/nodes/node4_assembly.py`
- [XAI](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node5_xai.py): explanation node · Generates clinician-readable rationale · `pipeline/nodes/node5_xai.py`
- [Judge](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/pipeline/nodes/node_judge.py): guard node · Controls acceptance, looping, and stop decisions · `pipeline/nodes/node_judge.py`

### Support

Auxiliary services and integration helpers

- [PubMed Client](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/pubmed_client.py): retrieval service · Fetches or resolves biomedical literature data · `utils/pubmed_client.py`
- [Quantum Utils](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/quantum_utils.py): metrics helper · Supports plausibility-style numeric analysis · `utils/quantum_utils.py`
- [Audit Logger](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/audit_logger.py): logging service · Persists reasoning and trace artifacts · `utils/audit_logger.py`
- [Neo4j Client](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/utils/neo4j_client.py): graph db adapter · Optional knowledge-graph connectivity · `utils/neo4j_client.py`

### Data

Local corpora, caches, thresholds, and audit outputs

- [Mock Patients](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/mock_patients.json): input dataset · Representative clinical input vectors · `data/mock_patients.json`
- [Literature Corpus](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pcos_literature_corpus.json): corpus dataset · Curated PCOS literature base · `data/pcos_literature_corpus.json`
- [Thresholds](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pcos_thresholds.json): rules dataset · Domain thresholds and scoring parameters · `data/pcos_thresholds.json`
- [PubMed Cache](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/blob/main/data/pubmed_cache.json): cache dataset · Cached PubMed-style retrieval results · `data/pubmed_cache.json`
- [Audit Trail](https://github.com/harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system/tree/main/data/audit_trail): output store · Persistent record of analysis runs · `data/audit_trail`

## Connections

- App → Graph: launches · Entrypoint starts the workflow graph
- Graph → State: uses · Graph executes over shared state
- Graph → Crew Setup: configures · Agent setup informs pipeline runtime
- State → Ingestion: feeds · Initial clinical context enters ingestion
- Ingestion → PubMed Client: retrieves · Grounds the case in biomedical literature
- PubMed Client → Literature Corpus: consults · Uses curated literature sources
- PubMed Client → PubMed Cache: reads · Falls back to cached retrieval results
- Ingestion → Hypothesis: passes context · Grounded evidence flows into hypothesis synthesis
- Hypothesis → Dual Analysis: scores · Hypothesis is evaluated numerically
- Dual Analysis → Quantum Utils: computes · Uses helper metrics for plausibility analysis
- Dual Analysis → Assembly: outputs · Scored results are assembled downstream
- Assembly → XAI: explains · Structured result becomes human-readable rationale
- XAI → Judge: reviews · Explanation and result are checked for continuation
- Judge → Ingestion: loop back · Low-confidence or incomplete runs can repeat
- Judge → Assembly: accepts · Approved runs proceed toward final packaging
- Assembly → Audit Logger: logs · Intermediate and final artifacts are recorded
- Audit Logger → Audit Trail: persists · Audit records are written to the trail
- Dual Analysis → Neo4j Client: optional lookup · Optional knowledge-graph integration
- State → Mock Patients: initializes from · Mock inputs seed the shared case state
- State → Thresholds: references · Domain rules inform stateful evaluation
