Configuration

Project-level configuration for paths, runtime settings, and environment management

Configuration Enums

Enums for runtime mode and conda implementation type.

CondaType


def CondaType(
    args:VAR_POSITIONAL, kwds:VAR_KEYWORD
):

Type of conda implementation to use.

RuntimeMode


def RuntimeMode(
    args:VAR_POSITIONAL, kwds:VAR_KEYWORD
):

Runtime mode for the capability system.

Configuration Dataclasses

RuntimeConfig holds conda/environment settings. CJMConfig is the main configuration container with paths and runtime settings.

RuntimeConfig


def RuntimeConfig(
    mode:RuntimeMode=<RuntimeMode.SYSTEM: 'system'>, conda_type:CondaType=<CondaType.CONDA: 'conda'>,
    prefix:Optional=None, binaries:Dict=<factory>
)->None:

Runtime environment configuration.

SubstrateConfig


def SubstrateConfig(
    drift_detection:bool=True, empirical_tracking:bool=True, prefetch_stall_threshold_seconds:float=60.0,
    diagnostics_retention_days:float=30.0, diagnostics_retention_max_mb:Optional=None
)->None:

Substrate behavior toggles.

Loaded from the substrate: section of cjm.yaml. Each flag gates a substrate-wide behavior that hosts can disable when they don’t want the per-load or per-execute cost.

  • drift_detection (CR-8): per-load /config_schema HTTP call + hash comparison against the manifest’s stored hash. CapabilityManager’s load path branches around _check_config_schema_drift when False.
  • empirical_tracking (CR-7): per-execute resource sample recording into EmpiricalResourceStore. CapabilityManager skips record_sample calls when False; the store’s lazy-init also short-circuits.
  • prefetch_stall_threshold_seconds (CR-4 / Session A 2026-05-27): how long proxy.prefetch waits with no observed progress (via /progress polling) before declaring a stall. Replaces per-capability wall-clock timeouts — operators no longer race network speed against an arbitrary value. Capabilities defeat the stall counter by calling self.report_progress(...) periodically during long lifecycle operations (model download / vLLM server startup). Default 60 s; bump higher for capabilities that don’t report progress, or lower if false-positive stalls are noisy.

CJMConfig


def CJMConfig(
    runtime:RuntimeConfig=<factory>, data_dir:Path=<factory>, capabilities_config:Path=<factory>,
    models_dir:Optional=None, substrate:SubstrateConfig=<factory>
)->None:

Main configuration for cjm-substrate.

Configuration Loading

Functions for loading configuration with layered resolution:

  1. CLI flags (highest priority)
  2. Environment variables
  3. cjm.yaml file
  4. Defaults (backward compatible)

load_config


def load_config(
    config_path:Optional=None, # CLI --cjm-config
    data_dir:Optional=None, # CLI --data-dir
    conda_prefix:Optional=None, # CLI --conda-prefix
    conda_type:Optional=None, # CLI --conda-type
)->CJMConfig: # Resolved configuration

Load config with layered resolution (CLI > env vars > yaml > defaults).

Global Config Access

Functions for getting and setting the module-level configuration singleton.

reset_config


def reset_config(
    
)->None:

Reset to unloaded state (for testing).

set_config


def set_config(
    config:CJMConfig, # Configuration to set as current
)->None:

Set current config (called by CLI callback).

get_config


def get_config(
    
)->CJMConfig: # Current configuration

Get current config (loads defaults if not set).

Examples

# Test default configuration
reset_config()
cfg = get_config()

print("Default configuration:")
print(f"  data_dir: {cfg.data_dir}")
print(f"  manifests_dir: {cfg.manifests_dir}")
print(f"  capability_data_dir: {cfg.capability_data_dir}")
print(f"  journal_db_path: {cfg.journal_db_path}")
print(f"  diagnostics_db_path: {cfg.diagnostics_db_path}")
print(f"  capabilities_config: {cfg.capabilities_config}")
print(f"  runtime.mode: {cfg.runtime.mode}")
print(f"  runtime.conda_type: {cfg.runtime.conda_type}")

# CR-14: the two observability stores live beside the sibling stores under data_dir
assert cfg.journal_db_path == cfg.data_dir / "journal.db"
assert cfg.diagnostics_db_path == cfg.data_dir / "diagnostics.db"
# Test CLI override
reset_config()
cfg = load_config(data_dir=Path("/custom/path"))

print("With CLI override:")
print(f"  data_dir: {cfg.data_dir}")
print(f"  manifests_dir: {cfg.manifests_dir}")
print(f"  capability_data_dir: {cfg.capability_data_dir}")
With CLI override:
  data_dir: /custom/path
  manifests_dir: /custom/path/manifests
  plugin_data_dir: /custom/path/data
# Test dataclass creation
runtime = RuntimeConfig(
    mode=RuntimeMode.LOCAL,
    conda_type=CondaType.MINIFORGE,
    prefix=Path("./runtime")
)

config = CJMConfig(
    runtime=runtime,
    data_dir=Path("./.cjm")
)

print("Custom configuration:")
print(f"  runtime.mode: {config.runtime.mode}")
print(f"  runtime.conda_type: {config.runtime.conda_type}")
print(f"  runtime.prefix: {config.runtime.prefix}")
print(f"  data_dir: {config.data_dir}")
Custom configuration:
  runtime.mode: RuntimeMode.LOCAL
  runtime.conda_type: CondaType.MINIFORGE
  runtime.prefix: runtime
  data_dir: .cjm
# Test conda_binary_path property
runtime_with_binaries = RuntimeConfig(
    conda_type=CondaType.MICROMAMBA,
    mode=RuntimeMode.LOCAL,
    prefix=Path("./runtime"),
    binaries={"linux-x64": Path("./runtime/bin/micromamba")}
)

config_with_binaries = CJMConfig(runtime=runtime_with_binaries)
print(f"conda_binary_path (from binaries): {config_with_binaries.conda_binary_path}")

# Test default path generation when binaries not specified
runtime_no_binaries = RuntimeConfig(
    conda_type=CondaType.MICROMAMBA,
    mode=RuntimeMode.LOCAL,
    prefix=Path("./runtime")
)

config_no_binaries = CJMConfig(runtime=runtime_no_binaries)
print(f"conda_binary_path (default): {config_no_binaries.conda_binary_path}")
conda_binary_path (from binaries): runtime/bin/micromamba
conda_binary_path (default): runtime/bin/micromamba
# Cleanup
reset_config()