Configuration API

Reference Text Configuration

experiment_name: reference
seed: 42
supervision:
  contract_version: stage3-supervision-v2
  manifest_path: null
model:
  base_model_name: sentence-transformers/all-MiniLM-L6-v2
  fusion: masked_mean
  dimension: 16
  radius_bound: 8.0
loss:
  code_code_weight: 1.0
  radial_weight: 1.0
  target_temperature: 1.0
  radial_step: 1.0
  logit_scale_init: 1.0
  logit_scale_range: [0.01, 100.0]
data_loader:
  queries_per_step: 128
training:
  learning_rate: 0.0001
  weight_decay: 0.01
  warmup_epochs: 1
  lr_plateau_factor: 0.5
  lr_plateau_patience: 2
  early_stopping_patience: 5
  trainer:
    max_epochs: 40
    accelerator: auto
    devices: 1
    precision: bf16-mixed
    gradient_clip_val: 1.0
    accumulate_grad_batches: 1

The complete config also supplies LoRA/MoE settings and tokenization/description paths. manifest_path: null is the committed state, and a valid pre-generation one; with no manifest, train refuses at the mandatory bundle gate and names the command to generate a bundle. The objective is req11-v1, and retired loss, curvature, mining, curriculum and streaming-path overrides are rejected, as are the unread data section and dirs.conf_dir and dirs.docs_dir, so a run config saved before their removal must drop them.

CUDA uses the configured bf16-mixed backbone precision. Fusion, projection, head, geometry and losses remain float32; CPU and MPS use 32-true. Text training uses one device. The learned scales have no weight decay. training.trainer.val_check_interval remains a parsed field but is unread; the outcome monitor runs at each epoch end without a validation loader.

train --checkpoint-load-mode exact is the sole load mode. Exact resume requires the same contract, seed, experiment directory and 21 run settings, including effective precision and budget. Old objective checkpoints cannot migrate weights. See exact resume.

This Machine's Manifests

The bundle manifest is a machine path, so it is set in the gitignored conf/local.yaml rather than in tracked YAML. conf/local.example.yaml shows the form:

config:
  supervision:
    manifest_path: data/supervision/stage3-supervision-v2/<bundle-id>/manifest.json
graph:
  supervision_manifest_path: data/supervision/stage3-supervision-v2/<bundle-id>/manifest.json

Each section is named for the tracked file it overrides, conf/config.yaml or conf/graph.yaml. These two keys are the only ones allowed, and each must be a repo-relative path under data/. Any other key would be a setting the Mac records and a remote instance never sees, so it is refused, as is a path that is absolute, outside data/ or not in the normal form data supervision prints. read_local_config validates the file. apply_local_config applies it at the entry points (train, the tools commands, remote and HGCN's main), after the tracked YAML and before key=value overrides. Library callers that load a YAML themselves read only that file. NAICS_EMBEDDER_LOCAL_CONFIG=off disables the override, and any other value names the file to read instead, relative to the checkout root.

Reference

CheckpointLoadMode

Bases: str, Enum

How a training run uses a checkpoint: exact resume, the one mode.

The weights-only migration is deleted (roadmap D2); the option keeps its name and default.

Config

Bases: BaseModel

Main configuration for NAICS training.

from_yaml(yaml_path) classmethod

Load configuration from YAML file.

override(overrides)

Apply overrides using dot notation.

to_dict()

Convert config to dictionary.

to_yaml(path)

Save config to YAML file.

DataLoaderConfig

Bases: BaseModel

Data loading and preprocessing configuration.

DecisionConfig

Bases: BaseModel

Req 5's decision procedure (roadmap Stage 4): the paired bootstrap and the seed floor, and the economic decision's relative margin (Req 24).

DirConfig

Bases: BaseModel

File system directory configuration.

DistancesConfig

Bases: BaseModel

Configuration for computing pairwise distances.

from_yaml(yaml_path) classmethod

Load configuration from YAML file.

DownloadConfig

Bases: BaseModel

Configuration for downloading and preprocessing NAICS data.

from_yaml(yaml_path) classmethod

Load configuration from YAML file.

GraphConfig

Bases: BaseModel

Base configuration for HGCN training.

from_yaml(yaml_path) classmethod

Load GraphConfig from YAML file.

LoRAConfig

Bases: BaseModel

LoRA (Low-Rank Adaptation) configuration.

LocalConfig

Bases: BaseModel

What conf/local.yaml sets, by dotted key, and the file as named (None when unread).

LossConfig

Bases: BaseModel

Loss function configuration: Req 11's three terms and their two learned logit scales (spec 4.1).

The logit-scale keys refuse exactly what LogitScale refuses (P22), so a configuration that validates never fails when the model builds its scales.

init_lies_in_the_range()

Both scales start at logit_scale_init, which must lie inside logit_scale_range.

range_is_positive_and_not_empty(value) classmethod

Spec section 5: refuse a range that is empty or not positive, or has an end that is not finite, as LogitScale does.

MoEConfig

Bases: BaseModel

Mixture of Experts configuration.

validate_top_k_vs_experts()

Ensure top_k doesn't exceed num_experts.

ModelConfig

Bases: BaseModel

Model architecture configuration.

OutcomePanelConfig

Bases: BaseModel

How the outcome panel's index-entry roles are drawn (roadmap D4), and its selection log.

RegressorBranchRecord

Bases: BaseModel

The Req 2 branch Stage 1's finding dictates: its decision block and section 4's excluded codes (specs/findings/employment-statistics-coverage.md).

RegressorPanelConfig

Bases: BaseModel

The regressor panel (roadmap Stage 3): QCEW inputs, held-out draw, fitting and the log.

RemoteConfig

Bases: BaseModel

Strict settings for code transport and session-specific result pulls.

fixed_pull_roots(value) classmethod

Permit exactly the four contractual result roots, in any order.

StreamingConfig

Bases: BaseModel

HGCN's streaming triplet cache: the paths, n_negatives and seed it samples and keys on.

SupervisionBuildConfig

Bases: BaseModel

Inputs and parameters for building one immutable Stage-3 supervision bundle.

has_a_recorded_window(value) classmethod

Refuse a backbone whose trained input window is not recorded (Req 9).

SupervisionRuntimeConfig

Bases: BaseModel

Which supervision contract training runs under, and the one authoritative bundle.

Training is always repaired: legacy containment and its mode key are deleted (roadmap D2).

TextOnlyConfig

Bases: BaseModel

The regressor panel's text-only comparator (roadmap D9): the arm's backbone, frozen.

fit_the_trained_window()

Refuse a max_length beyond the backbone's trained window (Req 9).

TextStreamingConfig

Bases: BaseModel

The text stage's streaming keys: the descriptions, the tokenizer and the window (P22).

The sampling keys and the legacy paths left with the old objective (spec 4.5); HGCN's StreamingConfig keeps the paths, n_negatives and seed its cache reads.

fit_the_trained_window()

Refuse a max_length beyond the backbone's trained window (Req 9).

TokenizationConfig

Bases: BaseModel

Configuration for tokenization caching.

fit_the_trained_window()

Resolve a null max_length to the trained window, and refuse a longer one (Req 9).

from_yaml(yaml_path) classmethod

Load configuration from YAML file.

TrainerConfig

Bases: BaseModel

PyTorch Lightning Trainer configuration.

validate_accelerator(v) classmethod

Validate accelerator choice.

validate_devices(v) classmethod

Refuse more than one device (spec 4.5): each process would hold its own code cache.

validate_precision(v) classmethod

Validate precision choice.

TrainingConfig

Bases: BaseModel

Optimizer and training configuration.

apply_local_config(cfg, root='.', *, local=None)

cfg with the supervision manifest conf/local.yaml sets for it, if any.

Entry points apply it after the tracked YAML and before command-line overrides. Library and test callers that load a YAML themselves read that file alone. Only the graph manifest joins a graph config's explicitly set fields: resolve_graph_config checks the explicit legacy paths against the bundle, so the config is never rebuilt from a dump.

Parameters:

Name Type Description Default
cfg C

A text Config or a GraphConfig, as loaded from its tracked YAML.

 required
root Union[str, Path]

The checkout root, as for read_local_config.

 '.'
local Optional[LocalConfig]

The override already read, if the caller has it; otherwise it is read here.

 None

Returns:

Type Description
C

cfg itself when the override sets nothing for it, otherwise a copy.

Raises:

Type Description
TypeError

If cfg is neither config.
FileNotFoundError

As read_local_config.
ValueError

As read_local_config.

load_config(config_class, yaml_path)

Generic configuration loader for any Pydantic model.

Parameters:

Name Type Description Default
config_class Type[T]

The Pydantic model class to instantiate

 required
yaml_path Union[str, Path]

Path to YAML config file (absolute, relative, or under conf/)

 required

Returns:

Type Description
T

Instance of config_class with values from YAML
Example

cfg = load_config(DownloadConfig, 'data/download.yaml')

parse_override_value(value)

Parse override value from string to appropriate type.

A bracketed list is read as a Python literal before anything else, so a list with a decimal point (loss.logit_scale_range=[0.01, 100]) is a list, not the string it would otherwise be; a bracketed value that is not a literal stays a string.

read_local_config(root='.')

The supervision manifests this machine's conf/local.yaml sets.

NAICS_EMBEDDER_LOCAL_CONFIG=off reads nothing. Any other value names the file to read in its place, relative to root, and that file must exist. Unset, <root>/conf/local.yaml is read if it exists. The file may set only LOCAL_CONFIG_KEYS, each a repo-relative path under data/. A remote launch then names the same manifest string the Mac recorded.

Parameters:

Name Type Description Default
root Union[str, Path]

The checkout root: the working directory for a command, the workflow root for remote.

 '.'

Returns:

Type Description
LocalConfig

The values set, by dotted key. Empty when the override is off or absent.

Raises:

Type Description
FileNotFoundError

If NAICS_EMBEDDER_LOCAL_CONFIG names a missing file.
ValueError

If the file is not YAML, sets any other key, or sets a manifest outside data/ or not in normal form.