configuration

Configuration models for the pipeline and each stage.

Bases: BaseModel

Validated top-level configuration for the CorridorKey pipeline.

Nests one settings block per stage plus cross-cutting concerns (logging, device). All Path fields support tilde and environment variable expansion.

Load with :func:~corridorkey.infra.config.load_config.

Example corridorkey.toml::

[logging]
level = "INFO"
dir = "~/.config/corridorkey/logs"

[preprocess]
img_size = 2048
image_upsample_mode = "bicubic"

[inference]
checkpoint_path = "~/models/greenformer.pth"
use_refiner = true

[postprocess]
fg_upsample_mode = "bicubic"
alpha_upsample_mode = "lanczos4"

[writer]
alpha_format = "exr"
processed_format = "exr"

`to_inference_config(device=None, _return_resolved_refiner_mode=False)`

Build an :class:~corridorkey.stages.inference.InferenceConfig.

Probes VRAM at most once — the same measurement resolves both img_size (when set to 0/auto) and refiner_mode (when set to "auto"), avoiding two separate pynvml calls at startup.

Parameters:

Name	Type	Description	Default
`device`	`str \| None`	Override the device string. If None, uses `self.device`.	`None`
`_return_resolved_refiner_mode`	`bool`	Internal flag used by `to_pipeline_config` to receive the resolved refiner mode alongside the config so it can be stored in `PipelineConfig` and passed to `PipelineRunner` without a second VRAM probe.	`False`

`to_pipeline_config(device=None, model=None)`

Build a :class:~corridorkey.runtime.runner.PipelineConfig from this config.

Resolves device and img_size once, then builds all stage configs consistently. Pass the result directly to PipelineRunner.

Parameters:

Name	Type	Description	Default
`device`	`str \| None`	Resolved device string (from `resolve_device(config.device)`). If None, uses `self.device` as-is.	`None`
`model`		Pre-loaded model (`nn.Module`). If None, `PipelineRunner` will load it from the checkpoint path at run time.	`None`

Returns:

Type	Description
	PipelineConfig ready to pass to `PipelineRunner`.

`to_postprocess_config()`

Build a :class:~corridorkey.stages.postprocessor.PostprocessConfig.

`to_preprocess_config(device=None, resolved_img_size=None)`

Build a :class:~corridorkey.stages.preprocessor.PreprocessConfig.

Parameters:

Name	Type	Description	Default
`device`	`str \| None`	Override the device string. If None, uses `self.device`.	`None`
`resolved_img_size`	`int \| None`	Pre-resolved img_size (from to_inference_config). If None, uses preprocess.img_size (or 2048 if 0).	`None`

`to_writer_config(output_dir)`

Build a :class:~corridorkey.stages.writer.WriteConfig.

Parameters:

Name	Type	Description	Default
`output_dir`		Root directory for all outputs (clip-specific).	required

Bases: BaseModel

User-facing preprocessing settings.

Mirrors :class:~corridorkey.stages.preprocessor.PreprocessConfig but lives in the config layer so it can be loaded from TOML / env vars.

In corridorkey.toml::

[preprocess]
img_size = 0  # 0 = auto-select based on VRAM
image_upsample_mode = "bicubic"
sharpen_strength = 0.3
half_precision = false
source_passthrough = true

Bases: BaseModel

User-facing inference settings.

Mirrors :class:~corridorkey.stages.inference.InferenceConfig but lives in the config layer so it can be loaded from TOML / env vars.

In corridorkey.toml::

[inference]
checkpoint_path = "~/models/greenformer.pth"
use_refiner = true
mixed_precision = true
model_precision = "auto"
refiner_mode = "auto"
refiner_scale = 1.0

Bases: BaseModel

User-facing postprocessing settings.

Mirrors :class:~corridorkey.stages.postprocessor.PostprocessConfig but lives in the config layer so it can be loaded from TOML / env vars.

In corridorkey.toml::

[postprocess]
fg_upsample_mode = "lanczos4"
alpha_upsample_mode = "lanczos4"
despill_strength = 0.5
auto_despeckle = true
despeckle_size = 400
despeckle_dilation = 25
despeckle_blur = 5
source_passthrough = true
edge_erode_px = 3
edge_blur_px = 7

Bases: BaseModel

User-facing writer settings.

Mirrors :class:~corridorkey.stages.writer.WriteConfig but lives in the config layer so it can be loaded from TOML / env vars.

In corridorkey.toml::

[writer]
alpha_enabled = true
alpha_format = "png"
fg_enabled = true
fg_format = "png"
processed_enabled = true
processed_format = "png"
comp_enabled = true
exr_compression = "dwaa"

Bases: BaseModel

Cross-cutting logging settings.

These apply to the whole pipeline regardless of which stage is running. The interface layer (CLI, GUI, web) adds its own handler on top — this controls only the file handler written to disk.

In corridorkey.toml::

[logging]
level = "INFO"
dir = "~/.config/corridorkey/logs"

Loader Functions

Load and validate CorridorKey configuration from all sources.

Resolution order (lowest to highest priority): defaults < global config < project config < env vars < overrides

Like :func:load_config but also returns per-field source metadata.

The following functions are re-exported from utilityhub_config: write_config, ensure_config_file, get_config_path. Refer to that package's documentation for their full signatures.