Imp.Optimizer.Artifact (Imp v0.5.0)

Durable champion/challenger lifecycle for portable optimizer outputs.

Artifacts contain checksummed Imp.Saving program states or explicit parameter-only snapshots and redacted provenance. Applying a candidate copies only optimizable predictor parameters onto a compatible live program, preserving its runtime LMs, adapters, and trusted callbacks. Persisted names remain strings and are resolved against that trusted live program; artifact bytes never create atoms or depend on unrelated modules preloading them.

Summary

Types

artifact()

candidate()

selection()

Functions

apply(artifact, program, selection \\ :champion, opts \\ [])

Applies one candidate's portable parameters and canonical report to a compatible live program.

candidate(id, program, opts \\ [])

Builds a checksummed candidate from a portable optimizer output.

compare(artifact, left, right, opts \\ [])

Compares candidate scores and named predictor parameters.

from_optimized_program(program, opts \\ [])

Captures the selected parameters and attached report from an optimized program.

inspect(artifact)

Returns an operational summary without rehydrating program callbacks.

new(champion, challengers \\ [], opts \\ [])

Creates a versioned artifact from one champion and zero or more challengers.

parameter_candidate(id, program, opts \\ [])

Builds a checksummed candidate containing only named predictor parameters.

promote(artifact, candidate_id)

Promotes a challenger and records the prior champion for rollback.

read!(path)

Reads and validates a supported optimizer artifact schema.

rollback(artifact)

Restores the most recently preserved champion.

value(artifact, selection \\ :champion)

Returns one selected portable value without restoring executable code.

value_candidate(id, value, opts \\ [])

Builds a checksummed candidate containing one canonical JSON value.

write!(artifact, path)

Atomically writes a validated artifact as owner-readable JSON.

Types

artifact()

@type artifact() :: %{required(String.t()) => term()}

candidate()

@type candidate() :: %{required(String.t()) => term()}

selection()

@type selection() :: :champion | String.t()

Functions

apply(artifact, program, selection \\ :champion, opts \\ [])

@spec apply(artifact(), struct(), selection(), keyword()) :: struct()

Applies one candidate's portable parameters and canonical report to a compatible live program.

candidate(id, program, opts \\ [])

@spec candidate(String.t(), struct(), keyword()) :: candidate()

Builds a checksummed candidate from a portable optimizer output.

compare(artifact, left, right, opts \\ [])

@spec compare(artifact(), selection(), selection(), keyword()) :: map()

Compares candidate scores and named predictor parameters.

from_optimized_program(program, opts \\ [])

@spec from_optimized_program(struct(), keyword()) :: artifact()

Captures the selected parameters and attached report from an optimized program.

This is the shared durable handoff for program optimizers. The returned artifact contains no consumer module or runtime binding; deploying code must reconstruct a trusted compatible program and call apply/4.

inspect(artifact)

@spec inspect(artifact()) :: map()

Returns an operational summary without rehydrating program callbacks.

new(champion, challengers \\ [], opts \\ [])

@spec new(candidate(), [candidate()], keyword()) :: artifact()

Creates a versioned artifact from one champion and zero or more challengers.

parameter_candidate(id, program, opts \\ [])

@spec parameter_candidate(String.t(), struct(), keyword()) :: candidate()

Builds a checksummed candidate containing only named predictor parameters.

Use this for consumer-defined multi-predictor modules that cannot and should not be serialized as arbitrary structs. The artifact retains each predictor's signature, demonstrations, and config, but never the consumer module, LM, adapter, callbacks, or other runtime state. Reconstruct the trusted program in the deploying application, then pass it to apply/4.

promote(artifact, candidate_id)

@spec promote(artifact(), String.t()) :: artifact()

Promotes a challenger and records the prior champion for rollback.

read!(path)

@spec read!(Path.t()) :: artifact()

Reads and validates a supported optimizer artifact schema.

rollback(artifact)

@spec rollback(artifact()) :: artifact()

Restores the most recently preserved champion.

value(artifact, selection \\ :champion)

@spec value(artifact(), selection()) :: term()

Returns one selected portable value without restoring executable code.

value_candidate(id, value, opts \\ [])

@spec value_candidate(String.t(), term(), keyword()) :: candidate()

Builds a checksummed candidate containing one canonical JSON value.

write!(artifact, path)

@spec write!(artifact(), Path.t()) :: :ok

Atomically writes a validated artifact as owner-readable JSON.