Jido.AI.Error (Jido AI v2.2.0)

Copy Markdown View Source

Splode-based error handling for Jido.AI.

Provides structured error types for AI operations including:

  • API errors (rate limits, authentication, transient failures)
  • Validation errors
  • Runtime error envelope normalization and retryability policy

Summary

Types

class()
class_module()
error_class()
error_envelope()
t()

Functions

error_envelope(type, message, details \\ %{}, retryable? \\ false)

Builds a normalized AI runtime error envelope.

normalize(reason, fallback_type \\ :execution_error, fallback_message \\ "Execution failed", extra_details \\ %{})

Normalizes arbitrary runtime error values into the canonical AI error envelope.

normalize_result(result, fallback_type \\ :invalid_result, fallback_message \\ "Invalid result envelope")

Ensures result payloads use {:ok, term, effects} or {:error, reason, effects} tuples.

retryable?(error)

Returns whether a result or error should be treated as retryable by runtime policy.

splode_error?(arg1, splode)
to_map(reason)

Serializes a runtime error term as the canonical AI runtime error map.

traverse_errors(error_or_errors, fun)

Traverses errors, calling fun for each leaf error, and returns a nested map of results grouped by each error's path.

unwrap!(result, opts \\ nil)

Raises an error if the result is an error, otherwise returns the result

Types

class()

@type class() :: %{
  :__struct__ => class_module(),
  :__exception__ => true,
  :errors => [t()],
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}

class_module()

@type class_module() ::
  Jido.AI.Error.Validation | Jido.AI.Error.API | Splode.Error.Unknown

error_class()

@type error_class() :: :validation | :api | :unknown

error_envelope()

@type error_envelope() :: %{
  type: atom(),
  message: String.t(),
  details: map(),
  retryable?: boolean()
}

t()

@type t() :: %{
  :__struct__ => module(),
  :__exception__ => true,
  :class => error_class(),
  :bread_crumbs => [String.t()],
  :vars => Keyword.t(),
  :stacktrace => Splode.Stacktrace.t() | nil,
  :context => map(),
  optional(atom()) => any()
}

Functions

error_envelope(type, message, details \\ %{}, retryable? \\ false)

@spec error_envelope(atom(), String.t(), map(), boolean()) :: error_envelope()

Builds a normalized AI runtime error envelope.

The envelope is the package-owned caller-visible contract used by tool, LLM, directive, and signal result paths.

normalize(reason, fallback_type \\ :execution_error, fallback_message \\ "Execution failed", extra_details \\ %{})

@spec normalize(term(), atom(), String.t(), map()) :: error_envelope()

Normalizes arbitrary runtime error values into the canonical AI error envelope.

normalize_result(result, fallback_type \\ :invalid_result, fallback_message \\ "Invalid result envelope")

@spec normalize_result(term(), atom(), String.t()) ::
  {:ok, term(), [term()]} | {:error, error_envelope(), [term()]}

Ensures result payloads use {:ok, term, effects} or {:error, reason, effects} tuples.

retryable?(error)

@spec retryable?(term()) :: boolean()

Returns whether a result or error should be treated as retryable by runtime policy.

splode_error?(arg1, splode)

to_map(reason)

@spec to_map(term()) :: error_envelope()

Serializes a runtime error term as the canonical AI runtime error map.

traverse_errors(error_or_errors, fun)

Traverses errors, calling fun for each leaf error, and returns a nested map of results grouped by each error's path.

See Splode.traverse_errors/2 for full documentation.

Example

iex> Elixir.Jido.AI.Error.traverse_errors(error, fn error ->
...>   Exception.message(error)
...> end)
%{name: ["name is required"]}

unwrap!(result, opts \\ nil)

Raises an error if the result is an error, otherwise returns the result

Alternatively, you can use the defsplode macro, which does this automatically.

Options

  • :error_opts - Options to pass to to_error/2 when converting the returned error
  • :unknown_error_opts - Options to pass to the unknown error if the function returns only :error. not necessary if your function always returns {:error, error}.

Examples

def function(arg) do

case do_something(arg) do
  :success -> :ok
  {:success, result} -> {:ok, result}
  {:error, error} -> {:error, error}
end

end

def function!(arg) do

YourErrors.unwrap!(function(arg))

end