`femic.patchworks_variants` Module

The femic.patchworks_variants module owns FEMIC’s registry-backed Patchworks variant resolution seam.

Current responsibilities include:

loading the generic packaged Patchworks variant registry shell;
discovering installed instance-owned registry providers through femic.patchworks_variant_registries entry points;
merging an optional user overlay registry from ~/.femic/variants.yaml;
writing user overlay entries for register/update/remove flows;
resolving named scenarios attached to variants;
resolving one default scenario per variant when the registry provides one or when a variant carries exactly one scenario;
resolving named scenario sets that bundle registered scenarios across one or more variants;
resolving one default scenario set per instance when the registry provides one;
preserving richer scenario-set metadata such as instance membership, families, default markers, and notes;
resolving named variants to concrete instance roots, runtime configs, and analysis .pin paths; and
planning/executing registry-declared materialization before launch;
exposing read-only materialization-plan summaries for operator inspection;
exposing dataset-root grouped materialization summaries for operator-facing inspection and consent; and
preserving richer metadata for future runtime/scenario/materialization orchestration.

Operational shape

In user-facing terms, this module is the registry seam behind:

instances list
variants list/show/register/update/remove
variants materialization-plan
run-variant
scenarios list
run-scenario
run-default-scenario
scenario-sets list/show
run-scenario-set
run-default-scenario-set

K3Z and MKRF variant definitions are intentionally not shipped in FEMIC core. They are exposed by their instance packages when those packages are installed. The module owns more than plain .pin lookup: it also owns default scenario resolution, default scenario-set resolution, scenario-set metadata, and grouped materialization summaries for launch-time consent.

For the operator-facing workflow and examples, see Patchworks Variant and Scenario Management.

Primary entry points

load_patchworks_variant_registry()
register_patchworks_variant_registry_provider()
discover_patchworks_variant_registry_providers()
load_patchworks_user_registry_overlay()
build_patchworks_variant_materialization_plan()
materialize_patchworks_variant()
upsert_patchworks_user_variant_entry()
remove_patchworks_user_variant_entry()
PatchworksVariantRegistry
PatchworksVariantDefinition
PatchworksVariantScenarioDefinition
PatchworksScenarioSetDefinition

Registry-backed Patchworks variant resolution helpers.

class femic.patchworks_variants.PatchworksInstanceDefinition(instance_id, label, variant_ids, default_variant_id=None, default_scenario_set_id=None)[source]

Bases: object

Grouped view of variants that belong to one instance.

Parameters:

instance_id (str)
label (str)
variant_ids (tuple[str, ...])
default_variant_id (str | None)
default_scenario_set_id (str | None)

default_scenario_set_id: str | None = None

default_variant_id: str | None = None

instance_id: str

label: str

variant_ids: tuple[str, ...]

class femic.patchworks_variants.PatchworksScenarioSetDefinition(scenario_set_id, label, mode, scenarios, instance_id=None, scenario_set_family=None, default=False, notes=())[source]

Bases: object

Named collection of scenarios that can be executed together.

Parameters:

scenario_set_id (str)
label (str)
mode (str)
scenarios (tuple[PatchworksScenarioSetMember, ...])
instance_id (str | None)
scenario_set_family (str | None)
default (bool)
notes (tuple[str, ...])

default: bool = False

instance_id: str | None = None

label: str

mode: str

notes: tuple[str, ...] = ()

scenario_set_family: str | None = None

scenario_set_id: str

scenarios: tuple[PatchworksScenarioSetMember, ...]

class femic.patchworks_variants.PatchworksScenarioSetMember(variant_id, scenario_id)[source]

Bases: object

One variant/scenario reference inside a named scenario set.

Parameters:

variant_id (str)
scenario_id (str)

scenario_id: str

variant_id: str

class femic.patchworks_variants.PatchworksVariantDefinition(variant_id, label, instance_id, instance_label, variant_family, kind, instance_root, analysis_pin, runtime_config, default=False, default_scenario_id=None, notes=(), materialization=(), scenarios=(), runtime=None, source='builtin', registry_path=None)[source]

Bases: object

Resolved Patchworks variant registry entry.

Parameters:

variant_id (str)
label (str)
instance_id (str)
instance_label (str)
variant_family (str)
kind (str)
instance_root (Path)
analysis_pin (Path)
runtime_config (Path)
default (bool)
default_scenario_id (str | None)
notes (tuple[str, ...])
materialization (tuple[PatchworksVariantMaterializationAction, ...])
scenarios (tuple[PatchworksVariantScenarioDefinition, ...])
runtime (dict[str, Any] | None)
source (str)
registry_path (Path | None)

analysis_pin: Path

default: bool = False

default_scenario_id: str | None = None

instance_id: str

instance_label: str

instance_root: Path

kind: str

label: str

materialization: tuple[PatchworksVariantMaterializationAction, ...] = ()

notes: tuple[str, ...] = ()

registry_path: Path | None = None

runtime: dict[str, Any] | None = None

runtime_config: Path

scenarios: tuple[PatchworksVariantScenarioDefinition, ...] = ()

source: str = 'builtin'

variant_family: str

variant_id: str

class femic.patchworks_variants.PatchworksVariantMaterializationAction(kind, dataset_root=None, relpaths=(), estimated_bytes=None)[source]

Bases: object

Materialization hint carried by a registry entry.

Parameters:

kind (str)
dataset_root (str | None)
relpaths (tuple[str, ...])
estimated_bytes (int | None)

dataset_root: str | None = None

estimated_bytes: int | None = None

kind: str

relpaths: tuple[str, ...] = ()

class femic.patchworks_variants.PatchworksVariantMaterializationDatasetSummary(dataset_root, action_count, known_estimated_bytes, has_unknown_sizes, relpaths)[source]

Bases: object

Dataset-root grouped summary of variant materialization actions.

Parameters:

dataset_root (str)
action_count (int)
known_estimated_bytes (int)
has_unknown_sizes (bool)
relpaths (tuple[str, ...])

action_count: int

dataset_root: str

has_unknown_sizes: bool

known_estimated_bytes: int

relpaths: tuple[str, ...]

class femic.patchworks_variants.PatchworksVariantMaterializationPlan(action_count, known_estimated_bytes, has_unknown_sizes, requires_confirmation)[source]

Bases: object

Summary of the prelaunch materialization implied by one variant.

Parameters:

action_count (int)
known_estimated_bytes (int)
has_unknown_sizes (bool)
requires_confirmation (bool)

action_count: int

has_unknown_sizes: bool

known_estimated_bytes: int

requires_confirmation: bool

class femic.patchworks_variants.PatchworksVariantRegistry(variants, instances, scenario_sets, builtin_registry_loaded, user_registry_path)[source]

Bases: object

Merged built-in plus user Patchworks variant registry.

Parameters:

variants (tuple[PatchworksVariantDefinition, ...])
instances (tuple[PatchworksInstanceDefinition, ...])
scenario_sets (tuple[PatchworksScenarioSetDefinition, ...])
builtin_registry_loaded (bool)
user_registry_path (Path | None)

builtin_registry_loaded: bool

get_default_scenario(variant_id)[source]

Return the default scenario for one variant.

Parameters:: variant_id (str)
Return type:: tuple[PatchworksVariantDefinition, PatchworksVariantScenarioDefinition]

get_default_scenario_set(instance_id)[source]

Return the default scenario set for one instance.

Parameters:: instance_id (str)
Return type:: PatchworksScenarioSetDefinition

get_scenario(variant_id, scenario_id)[source]

Return one named scenario attached to one variant.

Parameters:

variant_id (str)
scenario_id (str)

Return type:

tuple[PatchworksVariantDefinition, PatchworksVariantScenarioDefinition]

get_scenario_set(scenario_set_id)[source]

Return one named scenario set or raise a registry error.

Parameters:: scenario_set_id (str)
Return type:: PatchworksScenarioSetDefinition

get_variant(variant_id)[source]

Return one variant by id or raise a registry error.

Parameters:: variant_id (str)
Return type:: PatchworksVariantDefinition

instances: tuple[PatchworksInstanceDefinition, ...]

iter_scenario_sets(*, instance_id=None)[source]

Return scenario sets, optionally filtered by instance id.

Parameters:: instance_id (str | None)
Return type:: tuple[PatchworksScenarioSetDefinition, …]

scenario_sets: tuple[PatchworksScenarioSetDefinition, ...]

user_registry_path: Path | None

variants: tuple[PatchworksVariantDefinition, ...]

exception femic.patchworks_variants.PatchworksVariantRegistryError[source]

Bases: RuntimeError

Raised when Patchworks variant registry content is invalid.

class femic.patchworks_variants.PatchworksVariantRegistryProvider(*args, **kwargs)[source]

Bases: Protocol

Provider for an external Patchworks variant registry payload.

load_registry_payload()[source]

Return a Patchworks variant registry payload mapping.

Return type:: dict[str, Any]

provider_id: str

registry_base_dir: Path

class femic.patchworks_variants.PatchworksVariantScenarioDefinition(scenario_id, label, mode, target=None, min_annual=None, iterations=None, improvement=None, stage_label=None)[source]

Bases: object

Named scenario contract attached to one registry variant.

Parameters:

scenario_id (str)
label (str)
mode (str)
target (str | None)
min_annual (float | None)
iterations (int | None)
improvement (float | None)
stage_label (str | None)

improvement: float | None = None

iterations: int | None = None

label: str

min_annual: float | None = None

mode: str

scenario_id: str

stage_label: str | None = None

target: str | None = None

femic.patchworks_variants.build_patchworks_variant_materialization_plan(variant, *, prompt_threshold_bytes=104857600)[source]

Summarize whether a variant requires guarded prelaunch materialization.

Parameters:

variant (PatchworksVariantDefinition)
prompt_threshold_bytes (int)

Return type:

PatchworksVariantMaterializationPlan

femic.patchworks_variants.builtins_install_hint_for_variant(variant, *, source_root=None, user_config_path=None)[source]

Return an install hint when a catalog-backed instance is missing locally.

Parameters:

variant (PatchworksVariantDefinition)
source_root (Path | None)
user_config_path (Path | None)

Return type:

str | None

femic.patchworks_variants.clear_patchworks_variant_registry_providers()[source]

Clear in-process Patchworks variant registry providers.

This is intended for tests and interactive diagnostics. Entry-point discovery can be re-run after clearing.

Return type:: None

femic.patchworks_variants.discover_patchworks_variant_registry_providers()[source]

Discover installed Patchworks variant registry providers.

Return type:: tuple[str, …]

femic.patchworks_variants.load_patchworks_user_registry_overlay(user_registry_path=None)[source]

Load the writable user overlay registry payload, creating an empty view if missing.

Parameters:: user_registry_path (Path | None)
Return type:: tuple[Path, dict[str, Any]]

femic.patchworks_variants.load_patchworks_variant_registry(*, user_registry_path=None, source_root=None, user_config_path=None, include_entry_points=True)[source]

Load merged built-in, provider, and optional user Patchworks registries.

Parameters:

user_registry_path (Path | None)
source_root (Path | None)
user_config_path (Path | None)
include_entry_points (bool)

Return type:

PatchworksVariantRegistry

femic.patchworks_variants.materialize_patchworks_variant(variant, *, source_root=None, user_config_path=None)[source]

Run any declared materialization actions required before Patchworks launch.

Parameters:

variant (PatchworksVariantDefinition)
source_root (Path | None)
user_config_path (Path | None)

Return type:

None

femic.patchworks_variants.register_patchworks_variant_registry_provider(provider)[source]

Register one in-process Patchworks variant registry provider.

Parameters:: provider (PatchworksVariantRegistryProvider)
Return type:: None

femic.patchworks_variants.remove_patchworks_user_variant_entry(variant_id, *, user_registry_path=None)[source]

Remove one variant entry from the writable user overlay registry.

Parameters:

variant_id (str)
user_registry_path (Path | None)

Return type:

Path

femic.patchworks_variants.resolve_patchworks_user_registry_path(user_registry_path=None)[source]

Resolve the writable user overlay registry path.

Parameters:: user_registry_path (Path | None)
Return type:: Path

femic.patchworks_variants.serialize_patchworks_variant_definition(variant)[source]

Convert one resolved variant definition back into writable YAML payload form.

Parameters:: variant (PatchworksVariantDefinition)
Return type:: dict[str, Any]

femic.patchworks_variants.summarize_patchworks_variant_materialization_by_dataset(variant)[source]

Group registry-declared materialization actions by dataset root.

Parameters:: variant (PatchworksVariantDefinition)
Return type:: tuple[PatchworksVariantMaterializationDatasetSummary, …]

femic.patchworks_variants.upsert_patchworks_user_variant_entry(variant_entry, *, user_registry_path=None, instance_label=None)[source]

Insert or replace one variant entry in the writable user overlay registry.

Parameters:

variant_entry (dict[str, Any])
user_registry_path (Path | None)
instance_label (str | None)

Return type:

Path

femic.patchworks_variants.write_patchworks_user_registry_overlay(registry_path, payload)[source]

Persist the user overlay registry YAML to disk.

Parameters:

registry_path (Path)
payload (dict[str, Any])

Return type:

None

femic.patchworks_variants Module

Operational shape

Primary entry points

`femic.patchworks_variants` Module