Imp.Optimizer behaviour (Imp v0.5.0)

Canonical execution contract for program and training optimizers.

Optimizer modules declare what they produce and which dataset splits they consume. run/3 dispatches only through this behaviour; callback arity is never used to infer argument meaning. Operational safety failures remain raised across this boundary instead of becoming generic optimizer errors.

Summary

Types

capabilities()

kind()

requirement()

Callbacks

run(struct, program, keyword)

validate_invocation_options(keyword)

validate_invocation_options(struct, keyword)

Functions

capabilities(optimizer)

Returns validated capability metadata for an optimizer value.

run(optimizer, program, opts)

Runs an optimizer through its declared behaviour.

run(optimizer, program, opts, expected_kind)

run_with_datasets(optimizer, program, available_datasets, allowed_kinds \\ :any)

Runs an optimizer once against the named datasets available to a composed workflow.

Types

capabilities()

@type capabilities() :: %{
  kind: kind(),
  datasets: %{required(atom()) => requirement()},
  result:
    :program
    | :training_result
    | :constructed_program
    | {:workflow_result, module()}
}

kind()

@type kind() :: :program | :training | :constructor | :workflow

requirement()

@type requirement() :: :required | :optional | :unsupported

Callbacks

run(struct, program, keyword)

@callback run(struct(), program :: term(), keyword()) :: {:ok, term()} | {:error, term()}

validate_invocation_options(keyword)

(optional)

@callback validate_invocation_options(keyword()) :: :ok | {:error, term()}

validate_invocation_options(struct, keyword)

(optional)

@callback validate_invocation_options(struct(), keyword()) :: :ok | {:error, term()}

Functions

capabilities(optimizer)

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

Returns validated capability metadata for an optimizer value.

run(optimizer, program, opts)

@spec run(struct(), term(), keyword()) :: {:ok, term()} | {:error, term()}

Runs an optimizer through its declared behaviour.

run(optimizer, program, opts, expected_kind)

@spec run(struct(), term(), keyword(), kind() | :any) ::
  {:ok, term()} | {:error, term()}

run_with_datasets(optimizer, program, available_datasets, allowed_kinds \\ :any)

@spec run_with_datasets(struct(), term(), map(), [kind()] | :any) ::
  {:ok, capabilities(), term()} | {:error, term()}

Runs an optimizer once against the named datasets available to a composed workflow.