Imp.Optimizer.Playbook (Imp v0.5.0)

Copy Markdown View Source

Bounded optimization for persistent Imp.Playbook parameters.

The proposer receives training trajectories only. Challenger promotion requires improvement on source- and group-disjoint promotion and audit splits, bounded retained growth, and a content/provenance leakage audit. Every callback runs under a declared reservation and returns authoritative usage accounting.

This is an Elixir-native adaptation of the incremental context-learning loop explored by Dynamic Cheatsheet and ACE. It uses Imp's normal program parameter and trajectory contracts; it is not a second agent-memory runtime.

compile/6 never mutates a serving process. It returns a Result containing the baseline, challenger, decision, audit scores, usage, and exact rollback state. Application code must review that result and explicitly install result.program (or persist and restore its completed checkpoint).

Summary

Types

row()
t()

Functions

compile(optimizer, program, trainset, promotionset, auditset, opts \\ [])

Proposes, evaluates, and transactionally promotes one playbook delta.

new(opts)

Builds a validated optimizer configuration.

observed_weaknesses(request, opts \\ [])

Returns low-scoring training observations from a proposer request.

read_checkpoint!(path)

Reads and verifies a completed playbook optimizer checkpoint.

restore(checkpoint, program, parameter \\ :playbook)

Restores a completed checkpoint against fresh runtime-bound program callbacks.

retained_bytes(playbook)

Returns active and historical retained semantic bytes.

review(result)

Returns a compact, data-only challenger review before deployment.

rollback(result)

Returns the exact pre-promotion program preserved by a result.

write_checkpoint!(checkpoint, path)

Atomically writes a verified completed checkpoint as owner-readable JSON.

Types

row()

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

t()

@type t() :: %Imp.Optimizer.Playbook{
  authority_source_ids: term(),
  budget: term(),
  checkpoint_fn: term(),
  evaluator: term(),
  max_growth_bytes: term(),
  max_growth_ratio: term(),
  min_lift: term(),
  parameter: term(),
  proposer: term(),
  reservations: term()
}

Functions

compile(optimizer, program, trainset, promotionset, auditset, opts \\ [])

@spec compile(t(), struct(), [row()], [row()], [row()], keyword()) ::
  {:ok, struct()} | {:error, term()}

Proposes, evaluates, and transactionally promotes one playbook delta.

new(opts)

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

Builds a validated optimizer configuration.

observed_weaknesses(request, opts \\ [])

@spec observed_weaknesses(map(), keyword()) :: [map()]

Returns low-scoring training observations from a proposer request.

The result stays grounded in the exact training rows and admitted trajectories passed to the proposer. Observations are ordered from lowest score to highest; use below: to set the exclusive score threshold (default 1.0). Promotion and audit rows are never present in the request produced by this optimizer.

read_checkpoint!(path)

@spec read_checkpoint!(Path.t()) :: map()

Reads and verifies a completed playbook optimizer checkpoint.

restore(checkpoint, program, parameter \\ :playbook)

@spec restore(map(), struct(), Imp.ProgramParameters.name()) ::
  {:ok, struct()} | {:error, term()}

Restores a completed checkpoint against fresh runtime-bound program callbacks.

retained_bytes(playbook)

@spec retained_bytes(Imp.Playbook.t()) :: non_neg_integer()

Returns active and historical retained semantic bytes.

review(result)

@spec review(struct()) :: map()

Returns a compact, data-only challenger review before deployment.

rollback(result)

@spec rollback(struct()) :: struct()

Returns the exact pre-promotion program preserved by a result.

write_checkpoint!(checkpoint, path)

@spec write_checkpoint!(map(), Path.t()) :: :ok

Atomically writes a verified completed checkpoint as owner-readable JSON.