# Configuration


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Configuration Enums

Enums for runtime mode and conda implementation type.

------------------------------------------------------------------------

### CondaType

``` python

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

```

*Type of conda implementation to use.*

------------------------------------------------------------------------

### RuntimeMode

``` python

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

``` python

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

```

*Runtime environment configuration.*

------------------------------------------------------------------------

### SubstrateConfig

``` python

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

``` python

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

``` python

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

``` python

def reset_config(
    
)->None:

```

*Reset to unloaded state (for testing).*

------------------------------------------------------------------------

### set_config

``` python

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

```

*Set current config (called by CLI callback).*

------------------------------------------------------------------------

### get_config

``` python

def get_config(
    
)->CJMConfig: # Current configuration

```

*Get current config (loads defaults if not set).*

## Examples

``` python
# 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"
```

``` python
# 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

``` python
# 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

``` python
# 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

``` python
# Cleanup
reset_config()
```