AiFlow.Ollama.Error exception (AiFlow v0.1.0)

View Source

Defines an error structure and helper functions for handling errors in the AiFlow.Ollama module.

This module provides a consistent way to represent and handle errors that occur during interactions with the Ollama API, such as HTTP request failures, file operation errors, invalid inputs, or server issues. Errors are categorized by type (e.g., :http, :network, :file, :invalid), and each error includes a human-readable message for better debugging and user feedback.

Error Structure

The %Error{} struct contains:

  • type: An atom indicating the error category (:http, :network, :file, :invalid, :pull, :server, :client, :unknown).
  • reason: The underlying cause of the error (e.g., HTTP status, file error code, or custom term).
  • message: A human-readable description of the error.
  • status: An optional HTTP status code (for :http errors).

Examples

iex> AiFlow.Ollama.Error.invalid("Digest must be a valid SHA256 hash")
%AiFlow.Ollama.Error{
  type: :invalid,
  reason: :invalid_input,
  message: "Digest must be a valid SHA256 hash",
  status: nil
}

iex> AiFlow.Ollama.Error.http(404, "Not found")
%AiFlow.Ollama.Error{
  type: :http,
  reason: :not_found,
  message: "HTTP request failed with status 404: Not found",
  status: 404
}

iex> error = AiFlow.Ollama.Error.file(:enoent)
iex> AiFlow.Ollama.Error.to_string(error)
"File operation failed: file not found"

Summary

Types

error_reason()
error_type()
t()

Functions

client(reason)

Creates an error for client-related issues.

file(reason)

Creates an error for file-related issues.

http(status, reason)

Creates an error for HTTP-related issues.

invalid(message)

Creates an error for invalid input parameters.

network(reason)

Creates an error for network-related issues.

pull(reason)

Creates an error for pull operation issues (e.g., pulling a model from the Ollama API).

raise_error(operation, arg2)

Raises an error with a formatted message based on the operation and error struct.

server(reason)

Creates an error for server-related issues.

to_string(arg1)

Converts an error struct to a string for logging or display.

unknown(reason)

Creates an error for unknown or uncategorized issues.

Types

error_reason()

@type error_reason() ::
  {:http_error, integer(), term()}
  | :timeout
  | :conn_refused
  | :enoent
  | :eacces
  | :invalid_input
  | term()

error_type()

@type error_type() ::
  :http | :network | :file | :invalid | :pull | :server | :client | :unknown

t()

@type t() :: %AiFlow.Ollama.Error{
  __exception__: true,
  message: String.t(),
  reason: error_reason(),
  status: integer() | nil,
  type: error_type()
}

Functions

client(reason)

@spec client(term()) :: t()

Creates an error for client-related issues.

Parameters

  • reason: A term describing the client error.

Returns

  • %Error{} with type: :client and a formatted message.

Examples

iex> AiFlow.Ollama.Error.client("Internal client error")
%AiFlow.Ollama.Error{
  type: :client,
  reason: "Internal client error",
  message: "Client error: Internal client error",
  status: nil
}

file(reason)

@spec file(term()) :: t()

Creates an error for file-related issues.

Parameters

  • reason: An atom or term representing the file error (e.g., :enoent, :eacces).

Returns

  • %Error{} with type: :file and a formatted message.

Examples

iex> AiFlow.Ollama.Error.file(:enoent)
%AiFlow.Ollama.Error{
  type: :file,
  reason: :enoent,
  message: "File operation failed: file not found",
  status: nil
}

http(status, reason)

@spec http(integer(), term()) :: t()

Creates an error for HTTP-related issues.

Parameters

  • status: An integer representing the HTTP status code (e.g., 404, 500).
  • reason: A term describing the HTTP error (e.g., "Not found", :bad_request).

Returns

  • %Error{} with type: :http, the provided status, and a formatted message.

Examples

iex> AiFlow.Ollama.Error.http(404, "Not found")
%AiFlow.Ollama.Error{
  type: :http,
  reason: :not_found,
  message: "HTTP request failed with status 404: Not found",
  status: 404
}

invalid(message)

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

Creates an error for invalid input parameters.

Parameters

  • message: A string describing the invalid input.

Returns

  • %Error{} with type: :invalid, reason: :invalid_input, and the provided message.

Examples

iex> AiFlow.Ollama.Error.invalid("Digest must be a valid SHA256 hash")
%AiFlow.Ollama.Error{
  type: :invalid,
  reason: :invalid_input,
  message: "Digest must be a valid SHA256 hash",
  status: nil
}

network(reason)

@spec network(term()) :: t()

Creates an error for network-related issues.

Parameters

  • reason: A term describing the network error (e.g., :timeout, :conn_refused).

Returns

  • %Error{} with type: :network and a formatted message.

Examples

iex> AiFlow.Ollama.Error.network(:timeout)
%AiFlow.Ollama.Error{
  type: :network,
  reason: :timeout,
  message: "Network error: timeout",
  status: nil
}

pull(reason)

@spec pull(term()) :: t()

Creates an error for pull operation issues (e.g., pulling a model from the Ollama API).

Parameters

  • reason: A term describing the pull error.

Returns

  • %Error{} with type: :pull and a formatted message.

Examples

iex> AiFlow.Ollama.Error.pull("Model not found")
%AiFlow.Ollama.Error{
  type: :pull,
  reason: "Model not found",
  message: "Pull operation failed: Model not found",
  status: nil
}

raise_error(operation, arg2)

@spec raise_error(atom(), t()) :: no_return()

Raises an error with a formatted message based on the operation and error struct.

Parameters

  • operation: An atom representing the operation that failed (e.g., :check_blob, :create_blob).
  • error: An %Error{} struct containing error details.

Raises

  • Raises an %AiFlow.Ollama.Error{} with a formatted message.

Examples

iex> error = AiFlow.Ollama.Error.invalid("Invalid digest")
iex> AiFlow.Ollama.Error.raise_error(:check_blob, error)
** (AiFlow.Ollama.Error) check_blob failed: Invalid digest

iex> error = AiFlow.Ollama.Error.http(500, "Server error")
iex> AiFlow.Ollama.Error.raise_error(:create_blob, error)
** (AiFlow.Ollama.Error) create_blob failed: HTTP request failed with status 500: Server error

server(reason)

@spec server(term()) :: t()

Creates an error for server-related issues.

Parameters

  • reason: A term describing the server error.

Returns

  • %Error{} with type: :server and a formatted message.

Examples

iex> AiFlow.Ollama.Error.server("Internal server error")
%AiFlow.Ollama.Error{
  type: :server,
  reason: "Internal server error",
  message: "Server error: Internal server error",
  status: nil
}

to_string(arg1)

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

Converts an error struct to a string for logging or display.

Parameters

  • error: An %Error{} struct.

Returns

  • A string representing the error's message.

Examples

iex> error = AiFlow.Ollama.Error.file(:enoent)
iex> AiFlow.Ollama.Error.to_string(error)
"File operation failed: file not found"

unknown(reason)

@spec unknown(term()) :: t()

Creates an error for unknown or uncategorized issues.

Parameters

  • reason: A term describing the unknown error.

Returns

  • %Error{} with type: :unknown and a formatted message.

Examples

iex> AiFlow.Ollama.Error.unknown(:unexpected_error)
%AiFlow.Ollama.Error{
  type: :unknown,
  reason: :unexpected_error,
  message: "Unknown error: unexpected_error",
  status: nil
}