Imp.Optimize.Anything.StructuredStrategy behaviour (Imp v0.5.0)

Copy Markdown View Source

A checkpoint-safe mutation strategy for native structured Optimize Anything artifacts.

A strategy receives the complete native artifact, reflective evaluation data, and the top-level components selected for this proposal. It returns a complete replacement artifact. Imp validates the exact seed-derived shape and value types and rejects changes outside the selected components before the shared GEPA engine sees an internal representation.

Strategies are configured with a stable, consumer-owned version identifier:

strategy =
  Imp.Optimize.Anything.StructuredStrategy.new(MyArtifactStrategy,
    id: "routing-policy/v1",
    config: %{"max_retries" => 3}
  )

config =
  Imp.Optimize.Anything.Config.new(
    engine: [max_candidate_proposals: 4],
    reflection: [structured_strategy: strategy]
  )

The strategy module must implement propose/4. Configuration is restricted to JSON-native data so checkpoints never serialize executable code or create atoms dynamically.

Summary

Types

artifact()
component()
proposal()
reflective_dataset()
t()

Callbacks

propose(artifact, reflective_dataset, list, term)

Functions

from_map(map)

Restores a strategy binding without creating module atoms dynamically.

identity(structured_strategy)

Returns the stable module/id/config identity bound into checkpoints.

new(module, opts)

Creates a native structured-artifact strategy with stable resume identity.

to_map(strategy)

Returns a versioned JSON-safe representation of the strategy binding.

Types

artifact()

@type artifact() :: map()

component()

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

proposal()

@type proposal() ::
  {:ok, artifact()} | {:ok, artifact(), map()} | {:error, term()} | artifact()

reflective_dataset()

@type reflective_dataset() :: map()

t()

@type t() :: %Imp.Optimize.Anything.StructuredStrategy{
  config: map() | list() | String.t() | number() | boolean() | nil,
  id: String.t(),
  identity: String.t(),
  module: module()
}

Callbacks

propose(artifact, reflective_dataset, list, term)

@callback propose(artifact(), reflective_dataset(), [component()], term()) :: proposal()

Functions

from_map(map)

@spec from_map(map()) :: t()

Restores a strategy binding without creating module atoms dynamically.

identity(structured_strategy)

@spec identity(t()) :: String.t()

Returns the stable module/id/config identity bound into checkpoints.

new(module, opts)

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

Creates a native structured-artifact strategy with stable resume identity.

to_map(strategy)

@spec to_map(t()) :: map()

Returns a versioned JSON-safe representation of the strategy binding.