ALLM.Error.EngineError exception (allm v0.3.0)

Errors raised by engine-level operations before any adapter call.

Layer A — serializable (no PIDs, refs, funs, or raw API keys). Refines spec §20's atom taxonomy into a first-class struct so every Layer B/C/D public function can return {:error, %ALLM.Error.EngineError{}} uniformly.

See Phase 1 design §Sub-phase 1.1 for the closed reason enum.

Summary

Types

reason()

Closed set of engine-level error reasons (spec §20, §35.4).

t()

Functions

new(reason, opts \\ [])

Build an %EngineError{} from a reason atom and optional keyword fields.

Types

reason()

@type reason() ::
  :missing_adapter
  | :missing_stream_adapter
  | :missing_model
  | :missing_key
  | :unknown_tool
  | :invalid_engine
  | :unsupported_response_format
  | :no_image_adapter

Closed set of engine-level error reasons (spec §20, §35.4).

t()

@type t() :: %ALLM.Error.EngineError{
  __exception__: true,
  cause: term() | nil,
  message: String.t(),
  metadata: map(),
  provider: atom() | nil,
  reason: reason()
}

Functions

new(reason, opts \\ [])

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

Build an %EngineError{} from a reason atom and optional keyword fields.

opts may include :message, :provider, :cause, and :metadata. When :message is omitted, it defaults to "engine error: #{reason}" so Exception.message/1 always returns a non-empty binary.

Raises ArgumentError if reason is not one of the atoms in the closed reason/0 enum.

Examples

iex> err = ALLM.Error.EngineError.new(:missing_adapter)
iex> err.reason
:missing_adapter
iex> Exception.message(err)
"engine error: missing_adapter"

iex> err = ALLM.Error.EngineError.new(:missing_key, provider: :openai, message: "OPENAI_API_KEY unset")
iex> err.provider
:openai
iex> Exception.message(err)
"OPENAI_API_KEY unset"