candidates

Classes

Candidate

CandidateLibrary

Functions

build_candidate_library

Enumerate self, no-op, and sorted-slice candidates for typed blocks.

build_candidate_library_from_checkpoint

Build and optionally write the canonical identity-keyed candidate library.

discover_bypass_checkpoints

Return bypass checkpoint dirs from ckpts/bypass* and ckpts/bypass*/symlinks.

load_block_configs_from_checkpoint

Load typed Puzzletron block_configs from a checkpoint config.json.

load_stats_identity_cache

Index existing stats by (layer_idx, subblock_config_identity).

read_candidate_library

write_candidate_library

class Candidate

Bases: object

__init__(*, layer_idx, block_config, source_kind, parent_checkpoint_identity, hidden_width=None, source_identity=None, score_identity=None, cost_identity=None, stats_identity=None, metadata=<factory>)
Parameters:

  • layer_idx (int)

  • block_config (BlockConfig)

  • source_kind (str)

  • parent_checkpoint_identity (str)

  • hidden_width (int | None)

  • source_identity (str | None)

  • score_identity (str | None)

  • cost_identity (str | None)

  • stats_identity (str | None)

  • metadata (dict[str, Any])

Return type:

None

block_config: BlockConfig
cost_identity: str | None = None
classmethod from_dict(data)
Parameters:

data (dict[str, Any])

Return type:

Candidate

hidden_width: int | None = None
property identity: Identity
layer_idx: int
metadata: dict[str, Any]
parent_checkpoint_identity: str
score_identity: str | None = None
source_identity: str | None = None
source_kind: str
stats_identity: str | None = None
to_dict()
Return type:

dict[str, Any]

class CandidateLibrary

Bases: object

__init__(*, candidates, parent_checkpoint_identity, settings_identity, metadata=<factory>)
Parameters:

  • candidates (tuple[Candidate, ...])

  • parent_checkpoint_identity (str)

  • settings_identity (str)

  • metadata (dict[str, Any])

Return type:

None

candidates: tuple[Candidate, ...]
classmethod from_candidates(candidates, *, parent_checkpoint_identity, settings, metadata=None)
Parameters:

  • candidates (Iterable[Candidate])

  • parent_checkpoint_identity (str)

  • settings (Any)

  • metadata (dict[str, Any] | None)

Return type:

CandidateLibrary

classmethod from_dict(data)
Parameters:

data (dict[str, Any])

Return type:

CandidateLibrary

property identity: str
metadata: dict[str, Any]
parent_checkpoint_identity: str
settings_identity: str
to_dict(*, include_identity=True)
Parameters:

include_identity (bool)

Return type:

dict[str, Any]

build_candidate_library(block_configs, *, search_space=None, parent_checkpoint_identity, include_self=True, include_noops=True, stats_cache=None, hidden_width=None)

Enumerate self, no-op, and sorted-slice candidates for typed blocks.

Parameters:

  • block_configs (Iterable[BlockConfig | dict[str, Any]])

  • search_space (dict[str, Any] | None)

  • parent_checkpoint_identity (str)

  • include_self (bool)

  • include_noops (bool)

  • stats_cache (dict[tuple[int | None, str], str] | None)

  • hidden_width (int | None)

Return type:

list[Candidate]

build_candidate_library_from_checkpoint(checkpoint_dir, *, search_space=None, output_path=None, puzzle_dir=None, parent_checkpoint_identity=None, include_self=True, include_noops=True, include_bypass=True, stats_paths=None, metadata=None, hidden_width=None)

Build and optionally write the canonical identity-keyed candidate library.

This is the Stage-5 virtual library builder. It does not materialize weights: sorted-slice entries describe smaller typed BlockConfig objects sourced from the parent checkpoint, no-op entries carry typed no-op subblocks, and bypass entries point at discovered bypass checkpoints.

Parameters:

  • checkpoint_dir (str | Path)

  • search_space (dict[str, Any] | None)

  • output_path (str | Path | None)

  • puzzle_dir (str | Path | None)

  • parent_checkpoint_identity (str | None)

  • include_self (bool)

  • include_noops (bool)

  • include_bypass (bool)

  • stats_paths (Iterable[str | Path] | None)

  • metadata (dict[str, Any] | None)

  • hidden_width (int | None)

Return type:

CandidateLibrary

discover_bypass_checkpoints(puzzle_dir)

Return bypass checkpoint dirs from ckpts/bypass* and ckpts/bypass*/symlinks.

Parameters:

puzzle_dir (str | Path)

Return type:

tuple[Path, …]

load_block_configs_from_checkpoint(checkpoint_dir)

Load typed Puzzletron block_configs from a checkpoint config.json.

Parameters:

checkpoint_dir (str | Path)

Return type:

tuple[BlockConfig, …]

load_stats_identity_cache(stats_paths, *, hidden_width=None)

Index existing stats by (layer_idx, subblock_config_identity).

The returned ids are stable hashes of the stats payloads. They intentionally do not include file paths, so moving a puzzle directory does not invalidate otherwise identical runtime or memory measurements.

Parameters:

  • stats_paths (Iterable[str | Path] | str | Path | None)

  • hidden_width (int | None)

Return type:

dict[tuple[int | None, str], str]

read_candidate_library(path)
Parameters:

path (str | Path)

Return type:

CandidateLibrary

write_candidate_library(path, library)
Parameters:
Return type:

None