CLI Tools & Running Pipelines
Relevant source files
The following files were used as context for generating this wiki page:
CLI Tools and Running Pipelines provide the primary interface for interacting with the Agentic Medical Diagnosis system. These tools facilitate two core workflows: the ingestion of medical corpora into a knowledge graph and the execution of question-answering (QA) benchmarks using an agentic reasoning loop. The system leverages uv for dependency management and task execution, exposing commands that orchestrate complex data flows between corpus loaders, graph databases, vector stores, and LLM providers.
Sources: README.md:144-154, CONTRIBUTING.md:18-28, pyproject.toml:44-46
CLI Entry Points
The project defines two primary entry points in its pyproject.toml file. These commands are mapped to specific Python functions within the am_diag.pipelines module.
| Command | Entry Point Function | Purpose |
|---|---|---|
am-diag-ingest | am_diag.pipelines.ingestion:main | Orchestrates multi-corpus ingestion into Neo4j and vector stores. |
am-diag-qa | am_diag.pipelines.qa:main | Runs agentic clinical QA against various medical datasets. |
Sources: pyproject.toml:44-46, am_diag/pipelines/ingestion.py:144, am_diag/pipelines/qa.py:202
Ingestion Pipeline (am-diag-ingest)
The ingestion pipeline is responsible for streaming medical literature, chunking text, extracting clinical knowledge, and persisting data to Neo4j and vector stores (Qdrant or Weaviate).
Ingestion Flow
The ingestion process begins by resolving the requested corpus loaders and then iterating through each to run a full ingestion stack. This stack includes document loading, chunking, graph construction (extraction, normalization, resolution), and embedding.
The diagram shows the high-level orchestration within am_diag/pipelines/ingestion.py.
Sources: am_diag/pipelines/ingestion.py:73-109, README.md:162-176
Supported Corpora
The system maintains a CORPUS_LOADER_REGISTRY that maps string identifiers to specific loader classes.
| Corpus Key | Loader Class |
|---|---|
clinical_guidelines | ClinicalGuidelinesCorpusLoader |
pubmed | PubMedCorpusLoader |
pubmed_case_reports | PubmedCaseReportsCorpusLoader |
statpearls | StatPearlsCorpusLoader |
textbooks | TextbooksCorpusLoader |
Sources: am_diag/pipelines/ingestion.py:38-44
CLI Options for Ingestion
uv run am-diag-ingest --corpus <names> --batch-size <int>
--corpus: Comma-separated list of names (e.g.,pubmed,statpearls) orall.--batch-size: Number of documents processed per batch (default: 100).
Sources: am_diag/pipelines/ingestion.py:124-141
QA Runner Pipeline (am-diag-qa)
The QA pipeline executes evaluation benchmarks by loading clinical question samples and processing them through a DeepAgents-based reasoning loop.
QA Execution Architecture
The runner initializes a SearchEngine with retrieval configurations and then iterates through selected datasets. For each sample, it formats the question (handling MCQ, Rubric, or Open-Ended types) and invokes the answer_question agent function.
The sequence illustrates the flow of a single QA benchmark run.
Sources: am_diag/pipelines/qa.py:133-163, am_diag/pipelines/qa.py:202-237
Supported Datasets
The QA runner supports a wide range of medical benchmarks registered in DATASET_REGISTRY, including:
- MCQ:
medqa,medmcqa,pubmedqa,mmlu_med. - Reasoning:
careqa_reasoning,medcase_reasoning. - Specialty:
nejm_diagnostic,mmlu_pro_health.
Sources: am_diag/pipelines/qa.py:46-63
CLI Options for QA
uv run am-diag-qa --datasets <names> --limit <int> --output-dir <path>
--datasets: Comma-separated dataset names orall.--limit: Maximum samples per dataset for testing.--output-dir: Directory for JSON results (default:results/).
Sources: am_diag/pipelines/qa.py:182-200
Pipeline Component Logic
State Management
Pipelines use LangGraph to manage state during ingestion. The IngestionState accumulates entities, relations, and chunks as they move through various processing nodes.
The extraction pipeline state machine manages the transformation from raw text to a resolved knowledge graph.
Sources: am_diag/ingestion/extraction_pipeline.py:89-131
Reporting and Persistence
Both pipelines generate structured reports to track progress and results:
- IngestionReport: Tracks
documents_ingested,chunks_ingested,entities_ingested, andrelations_ingested. - ExtractionReport: Captures metadata about specific extraction batches, including source counts and output paths.
- QA Results: JSON files containing
sample_id,question, and the structuredanswerfrom the agent.
Sources: am_diag/ingestion/extraction_pipeline.py:65-87, am_diag/pipelines/qa.py:107-130
Summary
The CLI tools in am_diag provide a standardized way to execute the project's complex ingestion and evaluation pipelines. By abstracting the orchestration of graph databases, vector stores, and multi-agent reasoning loops into simple commands like am-diag-ing ingest and am-diag-qa, the system enables reproducible clinical knowledge graph construction and diagnostic performance benchmarking.