Introduction to Agentic Med-Diag

Agentic Med-Diag is a sophisticated Agentic GraphRAG (Retrieval-Augmented Generation) system specifically engineered for medical diagnosis. It processes medical literature to build a structured Neo4j knowledge graph characterized by hierarchical communities. The system leverages a multi-agent reasoning loop—comprising planning, researching, and verifying—to answer complex clinical questions with high precision and clinical grounding.

The project integrates advanced local NLP tools like GLiNER and GLiREL with Large Language Models (LLMs) via BAML for type-safe extraction. It employs hierarchical Leiden community detection to provide thematic, cluster-level insights, enabling the system to synthesize answers from broad medical contexts rather than isolated facts.

Sources: README.md:1-25, CONTRIBUTING.md:1-15

System Architecture

The system is divided into two primary data flows: Ingestion and Retrieval. Ingestion transforms raw medical text into a structured, resolved knowledge graph, while Retrieval utilizes an agentic loop to navigate this graph and provide diagnostic answers.

High-Level Data Flow

The diagram illustrates the separation between the knowledge base construction (Ingestion) and the reasoning engine (Agentic RAG).

Sources: README.md:121-125, README.md:195-215

Knowledge Graph Schema

The system uses a schema-driven approach where medical entity and relation types drive extraction and resolution. The schema is a first-class runtime value injected into all pipeline stages.

Entity and Relation Types

The default schema defines 13 entity types and 25 relation types.

Sources: README.md:88-119, am_diag/common/data_models/schema.py:40-100

Graph Model

The graph is stored in Neo4j with five primary node labels and standardized relationship structures.

Ingestion Pipeline

The ingestion process involves a multi-stage LangGraph pipeline that ensures data is extracted, normalized, and organized into hierarchical communities.

1. Extraction: Uses a three-extractor fusion (GLiNER, GLiREL, and LLM) to identify entities and relationships.
2. Normalization & Resolution: Entities are deduplicated and resolved to canonical names using deterministic methods (SemHash/MinHash) followed by LLM-based clustering.
3. Community Detection: Uses the Leiden algorithm (via Graspologic or Neo4j GDS) to partition the resolved graph into nested communities.
4. Summarization: An LLM generates structured CommunityReport outputs for each community, including findings and clinical-importance ratings.

Sources: README.md:127-156, am_diag/graph_construction/community/context.py:10-50

Agentic Reasoning Loop

The core of the retrieval process is the Agentic RAG loop, orchestrated by DeepAgents. It decomposes complex clinical queries into sub-questions and validates evidence before synthesis.

Sub-Agent Roles

Sources: README.md:217-235, am_diag/agents/prompts.py:8-60

Reasoning Sequence

Type-Safe LLM Integration (BAML)

All structured LLM interactions are handled via BAML, ensuring that the outputs from extractors, resolvers, and agents adhere to strict Pydantic-based data models. This prevents hallucination of entity types by injecting the schema as dynamic enums.

class ExtractedEntity(BaseModel):
    name: str # Canonical name (generic/INN for drugs)
    entity_type: EntityType # Constrained to schema
    description: Optional[str]
    aliases: List[str]
    score: float # 1.0 = explicit, 0.5 = inferred

Sources: am_diag/llm/baml_client/inlinedbaml.py:165-185, am_diag/llm/baml_client/types.py:65-75

Summary

Agentic Med-Diag provides a robust framework for medical diagnosis by combining structured knowledge graph construction with dynamic, agent-led reasoning. By utilizing hierarchical community detection and a plan-research-verify loop, the system moves beyond simple vector retrieval to provide clinically grounded, verifiable answers supported by multi-source medical evidence.

Sources: README.md:237-270, am_diag/common/data_models/init.py:10-60