Dsxir.OptimizerSession.Checkpoint (dsxir v0.3.0)

Persisted record for one OptimizerSession state transition.

Session-owned structured fields (progress, best_program_artifact, status) are readable without invoking the optimizer. The optimizer-owned sampler_blob is opaque; only the optimizer that wrote it interprets it, using sampler_format = {module, version} as a refusal gate on resume.

Summary

Types

progress()

t()

trial_log_entry()

Functions

decode(bin)

Decode a binary back to %Checkpoint{}. Raises Dsxir.Errors.Invalid.ResumeMismatch on shape mismatch.

encode(cp)

Encode %Checkpoint{} to a deterministic binary suitable for any Store impl that accepts opaque bytes.

hash_trainset(trainset)

Hash the trainset for fingerprinting. Stable for byte-identical trainsets.

new(opts)

Build a fresh checkpoint for a brand-new session.

Types

progress()

@type progress() :: %{
  trial_log: [trial_log_entry()],
  best_score: float() | nil,
  best_trial_idx: non_neg_integer() | nil,
  attempts: non_neg_integer(),
  completed: non_neg_integer(),
  errors: non_neg_integer(),
  started_at: DateTime.t()
}

t()

@type t() :: %Dsxir.OptimizerSession.Checkpoint{
  best_program_artifact: map() | nil,
  created_at: DateTime.t(),
  optimizer: module(),
  optimizer_opts: keyword(),
  program_module: module() | nil,
  progress: progress(),
  sampler_blob: binary(),
  sampler_format: {module(), pos_integer()},
  session_id: String.t(),
  status: :running | :paused | :completed | :failed | :cancelled,
  terminal_reason: term(),
  trainset_hash: binary(),
  updated_at: DateTime.t()
}

trial_log_entry()

@type trial_log_entry() :: %{
  trial_idx: non_neg_integer(),
  candidate_id: String.t() | nil,
  score: float() | nil,
  status: :ok | :error,
  stats: map() | nil,
  duration_ms: non_neg_integer(),
  error: map() | nil,
  error_class: atom() | nil
}

Functions

decode(bin)

@spec decode(binary()) :: t()

Decode a binary back to %Checkpoint{}. Raises Dsxir.Errors.Invalid.ResumeMismatch on shape mismatch.

encode(cp)

@spec encode(t()) :: binary()

Encode %Checkpoint{} to a deterministic binary suitable for any Store impl that accepts opaque bytes.

hash_trainset(trainset)

@spec hash_trainset([term()]) :: binary()

Hash the trainset for fingerprinting. Stable for byte-identical trainsets.

new(opts)

@spec new(keyword()) :: t()

Build a fresh checkpoint for a brand-new session.