Configuration & Environment Variables
Relevant source files
The following files were used as context for generating this wiki page:
The am_diag system utilizes a decentralized configuration architecture where components manage their own settings through Pydantic-based classes. This design ensures that every module—ranging from extraction and ingestion to vector storage and multi-agent reasoning—is independently configurable via environment variables or direct instantiation.
The project relies on .env files for managing credentials and endpoint URLs for external services like Neo4j, Qdrant, and OpenAI-compatible LLM providers. Configuration objects typically subclass pydantic_settings.BaseSettings and use specific environment prefixes (e.g., NEO4J_, AGENT_) to map variables to internal class attributes.
Sources: CONTRIBUTING.md:46-51, README.md:445-455
Core Configuration Architecture
The system's configuration is structured around functional boundaries. Components take their configuration at construction time, allowing for runtime flexibility and clean dependency injection.
Configuration Hierarchy Diagram
The following diagram illustrates how various configuration settings flow from environment variables into specific system modules.
Sources: CONTRIBUTING.md:49-51, README.md:445-453
Environment Variables Overview
The project requires several environment variables for integration with external databases and LLM services. A template is provided in .env.example to guide the setup process.
Primary Service Settings
| Variable Group | Purpose | Examples |
|---|---|---|
| Neo4j | Graph database credentials and connection strings. | NEO4J_URI, NEO4J_USER, NEO4J_PASSWORD |
| Vector Store | Connection details for Qdrant or Weaviate. | QDRANT_URL, QDRANT_API_KEY |
| LLM / Agents | API keys and base URLs for model inference. | AGENT_BASE_URL, AGENT_API_KEY, AGENT_MODEL |
| Generic OpenAI | Specific to BAML extraction and community reporting. | OPENAI_GENERIC_BASE_URL, OPENAI_GENERIC_API_KEY |
Sources: README.md:448-458, am_diag/llm/baml_client/inlinedbaml.py:126-135
Extraction & Pipeline Configuration
Extraction behavior is governed by ExtractionPipelineConfig, which controls which extractors are active (GLiNER, GLiREL, or LLM) and the thresholds for data normalization.
Normalization Constraints
The EntityRelationNormalizer uses these configurations to filter and merge raw extraction results per chunk.
- Minimum Entity Score: Filters out entities with confidence scores below the threshold.
- Minimum Entity Length: Removes short, potentially noisy entity names.
Sources: am_diag/graph_construction/normalize.py:12-38, am_diag/ingestion/extraction_pipeline.py:53-56
# Example of configuration use in normalization
# am_diag/graph_construction/normalize.py:34-36
cfg = self._config
min_score = cfg.min_entity_score
min_length = cfg.min_entity_length
LLM Client and Retry Policies (BAML)
BAML (Boundary Machine Learning) handles type-safe LLM interactions. It defines specific client configurations and retry strategies within clients.baml (rendered as inlinedbaml.py).
Client Definitions
Multiple clients are configured for different performance tiers and providers:
- CustomGPT5 / CustomGPT5Mini: High-performance OpenAI-compatible models.
- CustomSonnet4 / CustomHaiku: Anthropic Claude models for specific reasoning tasks.
- OpenAIGeneric: Used for extraction and community report generation with a 120s timeout.
Retry Strategies
The system implements tiered retry policies to handle transient API failures:
| Policy Name | Max Retries | Strategy Type | Base Delay |
|---|---|---|---|
| GenerousRetry | 5 | Exponential Backoff | 5000ms |
| RobustRetry | 10 | Exponential Backoff | 2000ms |
| Constant | 3 | Constant Delay | 200ms |
| Exponential | 2 | Exponential Backoff | 300ms |
Sources: am_diag/llm/baml_client/inlinedbaml.py:115-155
QA Pipeline Configuration
The QaConfig class manages the execution of evaluation datasets. It allows users to specify which datasets to run and set limits on the number of samples processed.
Dataset Registry
The system maintains a registry of medical QA benchmarks including:
- Clinical Reasoning:
medqa,medmcqa,pubmedqa. - Specialty/Professional:
mmlu_pro_health,nejm_qa,supergpqa_med. - Dialog/Rubric:
healthbench,careqa.
Sources: am_diag/pipelines/qa.py:53-70, README.md:323-380
Summary
The configuration system in am_diag is designed for modularity and robustness. By leveraging pydantic-settings, the project ensures that environment-level overrides are seamlessly integrated into the application logic. The use of structured BAML clients and tiered retry policies provides a stable foundation for the complex, long-running extraction and reasoning tasks essential for medical diagnosis automation.
Sources: CONTRIBUTING.md:46-51, am_diag/llm/baml_client/inlinedbaml.py:115-125