How harveenkaur282-web/multi-agent-xai-biomedical-hypothesis-analysis-system works
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: state.py State · node3_dual_analysis.py Dual Analysis · node1_ingestion.py Ingestion · node4_assembly.py Assembly
Components 19
Pipeline
Stateful LangGraph-style analysis workflow
- Graph · Builds and connects the stateful pipeline
pipeline/graph.py - State · Carries data between pipeline stages
pipeline/state.py - Crew Setup · Configures agent/runtime behavior
pipeline/agents/crew_setup.py - Ingestion · Combines patient input with literature context
pipeline/nodes/node1_ingestion.py - Hypothesis · Synthesizes a structured PCOS hypothesis
pipeline/nodes/node2_hypothesis.py - Dual Analysis · Applies credibility and plausibility scoring
pipeline/nodes/node3_dual_analysis.py - Assembly · Consolidates stage outputs into final structure
pipeline/nodes/node4_assembly.py - XAI · Generates clinician-readable rationale
pipeline/nodes/node5_xai.py - Judge · Controls acceptance, looping, and stop decisions
pipeline/nodes/node_judge.py
Support
Auxiliary services and integration helpers
- PubMed Client · Fetches or resolves biomedical literature data
utils/pubmed_client.py - Quantum Utils · Supports plausibility-style numeric analysis
utils/quantum_utils.py - Audit Logger · Persists reasoning and trace artifacts
utils/audit_logger.py - Neo4j Client · Optional knowledge-graph connectivity
utils/neo4j_client.py
Data
Local corpora, caches, thresholds, and audit outputs
- Mock Patients · Representative clinical input vectors
data/mock_patients.json - Literature Corpus · Curated PCOS literature base
data/pcos_literature_corpus.json - Thresholds · Domain thresholds and scoring parameters
data/pcos_thresholds.json - PubMed Cache · Cached PubMed-style retrieval results
data/pubmed_cache.json - Audit Trail · Persistent record of analysis runs
data/audit_trail
Connections 20
- 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