Imp.Optimizer.Trajectory (Imp v0.5.0)

Versioned, provider-neutral execution envelope shared by all optimizers.

The original evaluation fields remain directly available. project/3 adds a runtime identity and typed events for GEPA, MIPROv2, SIMBA, RLM, ReAct, and generic evaluation adapters. dump/1 is the canonical cross-runtime wire representation: it is JSON-safe, deterministic, and redacts secrets in structured fields. Opaque attachment bytes are preserved unchanged. load/1 validates the complete envelope and fails closed.

Summary

Types

runtime()

t()

Functions

dump(trajectory)

Dumps every trajectory field into a deterministic JSON-safe versioned map.

killed?(trajectory)

True when this trajectory's failure came from a killed evaluation task (timeout or deadline exhaustion), not from model or metric behavior.

load(state)

Loads and strictly validates a canonical trajectory wire map.

load!(state)

Loads a trajectory or raises DecodeError for any malformed field.

project(runtime, value, opts \\ [])

Projects an existing trajectory or runtime prediction into the canonical contract.

redact(trajectory, keys \\ Imp.Redaction.default_keys())

Returns a secret-redacted trajectory while preserving all typed structs.

schema_version()

Returns the current trajectory wire schema version.

validate!(trajectory)

Validates ordering, tool alignment, accounting, cache, and named parameter invariants.

validate_aligned!(trajectories)

Validates a batch as index-aligned, ordered canonical trajectories.

Types

runtime()

@type runtime() ::
  :evaluation
  | :gepa
  | :mipro_v2
  | :simba
  | :rlm
  | :agent
  | :react
  | :optimize_anything

t()

@type t() :: %Imp.Optimizer.Trajectory{
  cache: struct() | nil,
  error: term(),
  events: list(),
  example: term(),
  feedback: term(),
  index: integer(),
  metadata: map(),
  metric_metadata: map() | nil,
  named_parameters: list(),
  prediction: term(),
  program_id: term(),
  rollout_id: term(),
  runtime: runtime(),
  schema_version: pos_integer(),
  score: number(),
  timing: struct(),
  trace: list() | nil,
  usage: struct()
}

Functions

dump(trajectory)

@spec dump(t()) :: map()

Dumps every trajectory field into a deterministic JSON-safe versioned map.

killed?(trajectory)

@spec killed?(t()) :: boolean()

True when this trajectory's failure came from a killed evaluation task (timeout or deadline exhaustion), not from model or metric behavior.

load(state)

@spec load(map()) :: {:ok, t()} | {:error, struct()}

Loads and strictly validates a canonical trajectory wire map.

load!(state)

@spec load!(map()) :: t()

Loads a trajectory or raises DecodeError for any malformed field.

project(runtime, value, opts \\ [])

@spec project(runtime(), t() | Imp.Prediction.t() | map(), keyword()) :: t()

Projects an existing trajectory or runtime prediction into the canonical contract.

redact(trajectory, keys \\ Imp.Redaction.default_keys())

@spec redact(t(), [atom() | String.t()]) :: t()

Returns a secret-redacted trajectory while preserving all typed structs.

schema_version()

Returns the current trajectory wire schema version.

validate!(trajectory)

@spec validate!(t()) :: t()

Validates ordering, tool alignment, accounting, cache, and named parameter invariants.

validate_aligned!(trajectories)

@spec validate_aligned!([t()]) :: [t()]

Validates a batch as index-aligned, ordered canonical trajectories.