Skip to content

Config Adapters

Config adapters provide model-specific interfaces to discover, canonicalize, and ingest complex file-based configurations. They enable tracking of calibration-sensitive parameters as queryable database tables while preserving full config provenance via artifacts.

Decision Guide

Criterion Use Config Adapters Use In-Memory Config
Config location Multiple files (YAML, CSV, HOCON) Python dict or Pydantic model
Config structure Layered inheritance, file hierarchies Flat or simple nesting
Queryable parameters Calibration-sensitive values Simple facets suffice
File tracking Need content hashing per file No file artifacts needed

For in-memory configuration, see Config, Facets, and Identity Inputs.

Architecture

Config adapters implement three phases:

Config Directory
    ↓
discover()           ← Locate files, compute content hash
    ↓
CanonicalConfig
    ↓
canonicalize()       ← Generate artifact specs + ingest specs
    ↓
CanonicalizationResult (artifacts + ingestables)
    ↓
tracker.canonicalize_config()  ← Log artifacts, ingest to DB
    ↓
Queryable Tables + Full Provenance

Adapter Guides

Detailed, model-specific implementations live here:

These guides include discovery/canonicalization behaviors, ingestion schemas, and query examples. The API patterns are shared: you construct an adapter, call tracker.canonicalize_config(...) or tracker.prepare_config(...), and then query the resulting cache tables.

Extensibility

Config adapters follow a Protocol interface, making it straightforward to add support for other models. Future adapters might include:

  • Additional HOCON/YAML models: Layered config discovery + calibration-sensitive key extraction
  • Custom Models: Any model with file-based config that needs parameterization tracking

If you'd like to add an adapter for your own model, consult the ActivitySim adapter source as a reference implementation.

See Also