Imp.Optimize.Anything (Imp v0.5.0)

Copy Markdown View Source

Optimizes text, named text components, and JSON-safe structured artifacts against evaluator feedback.

The run/3 surface controls reflection, budgets, selection, caching, merging, stopping, and tracking through its options. It returns an immutable result value. Structured artifacts are an Imp-native extension to GEPA v0.1.4's str | dict[str, str] candidate contract: their exact shape and value types are derived from the seed and enforced for every proposal. A pinned-compatible :batch_evaluator may replace or accompany the scalar evaluator when an evaluation backend needs all pending candidate/example pairs in one ordered call.

Summary

Functions

best_candidate(result)

Returns the validation-selected candidate from an Optimize Anything result.

run(seed_candidate, evaluator, opts \\ [])

Runs Optimize Anything for a text or JSON-safe structured seed and returns a Result.

to_artifact(result, opts \\ [])

Exports an existing Optimize Anything result as a portable value artifact.

to_program_artifact(result, program, opts \\ [])

Exports structured component candidates onto a trusted program Artifact.

Functions

best_candidate(result)

@spec best_candidate(struct()) :: map() | String.t()

Returns the validation-selected candidate from an Optimize Anything result.

run(seed_candidate, evaluator, opts \\ [])

@spec run(String.t() | map() | nil, function() | nil, keyword()) :: struct()

Runs Optimize Anything for a text or JSON-safe structured seed and returns a Result.

to_artifact(result, opts \\ [])

@spec to_artifact(struct(), keyword()) :: Imp.Optimizer.Artifact.artifact()

Exports an existing Optimize Anything result as a portable value artifact.

Export is pure: it preserves the result's candidate order, validation scores, and selected champion without invoking an evaluator, proposer, or selector. Values must already be canonical JSON so a fresh VM can restore them without creating atoms or loading executable code.

to_program_artifact(result, program, opts \\ [])

@spec to_program_artifact(struct(), struct(), keyword()) ::
  Imp.Optimizer.Artifact.artifact()

Exports structured component candidates onto a trusted program Artifact.

Each Optimize Anything candidate must be the complete map returned by Imp.ProgramParameters.values/1. Values are validated and applied through the program's component contract before the parameter-only candidate is created. Runtime callbacks, tools, clients, and credentials remain in the supplied trusted program and are never serialized.