Imp.ProgramParameters (Imp v0.5.0)

Named optimizer lenses and typed parameter snapshots for Imp programs.

predictors/1 is the canonical lens used by instruction and demonstration optimizers. snapshot/1, diff/2, and apply_changes/2 provide a bounded data-only contract: IDs are stable strings, values are JSON data, each change carries a content digest guard, and a multi-change update is committed atomically.

Built-in predictors expose instruction, demos, and config parameters. Programs with persistent playbooks expose their serialized playbook. ReAct and ReActV2 also expose non-reserved tool descriptions and schemas; those lenses never serialize or replace a tool runner, the reserved submit tool, or a tool policy.

Summary

Types

entry()

name()

playbook_entry()

Functions

apply_changes(program, changes)

Applies every change or returns an error without yielding a partial program.

apply_changes_with_snapshot(program, changes)

Applies changes and also returns the committed parameter snapshot.

apply_values(program, values)

Atomically replaces the complete optimizer-visible JSON state.

apply_values!(program, values)

Atomically replaces complete optimizer-visible state or raises.

components(program)

Returns every described, typed component exposed by a program.

diff(source, target)

Returns only the minimal digest-guarded changes from source to target.

instruction_components(program)

Returns the textual instruction components consumed by GEPA.

parameters(program)

Returns the typed parameters in the current snapshot.

playbooks(program)

Returns named persistent playbook parameters exposed by a program.

predictors(program)

put_config(program, name, config)

Functionally replaces one predictor's keyword config lens.

put_demos(program, name, demos)

put_instruction(program, name, instruction)

put_playbook(program, name, playbook)

Replaces one named persistent playbook parameter.

put_tool_description(program, name, description)

Replaces a non-reserved ReAct or ReActV2 tool description.

put_tool_schema(program, name, schema)

Replaces a non-reserved ReAct or ReActV2 tool JSON schema.

snapshot(program)

Returns a revisioned, data-only snapshot of every exposed parameter.

update_playbook(program, name, update)

Functionally updates one named persistent playbook parameter.

update_predictor(program, name, update)

values(program)

Returns the complete optimizer-visible state as a stable JSON map.

Types

entry()

@type entry() :: %{name: name(), predictor: struct()}

name()

@type name() :: atom() | String.t()

playbook_entry()

@type playbook_entry() :: %{name: name(), playbook: Imp.Playbook.t()}

Functions

apply_changes(program, changes)

@spec apply_changes(struct(), [struct() | map()]) ::
  {:ok, struct()} | {:error, term()}

Applies every change or returns an error without yielding a partial program.

apply_changes_with_snapshot(program, changes)

@spec apply_changes_with_snapshot(struct(), [struct() | map()]) ::
  {:ok, struct(), struct()} | {:error, term()}

Applies changes and also returns the committed parameter snapshot.

apply_values(program, values)

@spec apply_values(struct(), map()) :: {:ok, struct()} | {:error, term()}

Atomically replaces the complete optimizer-visible JSON state.

apply_values!(program, values)

@spec apply_values!(struct(), map()) :: struct()

Atomically replaces complete optimizer-visible state or raises.

components(program)

@spec components(struct()) :: [Imp.Optimizer.Component.t()]

Returns every described, typed component exposed by a program.

diff(source, target)

@spec diff(struct(), struct()) :: [struct()]

Returns only the minimal digest-guarded changes from source to target.

instruction_components(program)

@spec instruction_components(struct()) :: [
  %{name: name(), component: Imp.Optimizer.Component.t()}
]

Returns the textual instruction components consumed by GEPA.

parameters(program)

@spec parameters(struct()) :: [struct()]

Returns the typed parameters in the current snapshot.

playbooks(program)

@spec playbooks(struct()) :: [playbook_entry()]

Returns named persistent playbook parameters exposed by a program.

predictors(program)

@spec predictors(struct()) :: [entry()]

put_config(program, name, config)

@spec put_config(struct(), name(), keyword()) :: struct()

Functionally replaces one predictor's keyword config lens.

put_demos(program, name, demos)

@spec put_demos(struct(), name(), [term()]) :: struct()

put_instruction(program, name, instruction)

@spec put_instruction(struct(), name(), String.t()) :: struct()

put_playbook(program, name, playbook)

@spec put_playbook(struct(), name(), Imp.Playbook.t()) :: struct()

Replaces one named persistent playbook parameter.

put_tool_description(program, name, description)

@spec put_tool_description(
  Imp.Predict.ReAct.t() | Imp.Predict.ReActV2.t(),
  name(),
  String.t()
) ::
  Imp.Predict.ReAct.t() | Imp.Predict.ReActV2.t()

Replaces a non-reserved ReAct or ReActV2 tool description.

put_tool_schema(program, name, schema)

@spec put_tool_schema(Imp.Predict.ReAct.t() | Imp.Predict.ReActV2.t(), name(), map()) ::
  Imp.Predict.ReAct.t() | Imp.Predict.ReActV2.t()

Replaces a non-reserved ReAct or ReActV2 tool JSON schema.

snapshot(program)

@spec snapshot(struct()) :: struct()

Returns a revisioned, data-only snapshot of every exposed parameter.

update_playbook(program, name, update)

@spec update_playbook(struct(), name(), (Imp.Playbook.t() -> Imp.Playbook.t())) ::
  struct()

Functionally updates one named persistent playbook parameter.

update_predictor(program, name, update)

@spec update_predictor(struct(), name(), (struct() -> struct())) :: struct()

values(program)

@spec values(struct()) :: %{
  required(String.t()) => Imp.Optimizer.Parameter.json_value()
}

Returns the complete optimizer-visible state as a stable JSON map.