Arcanum.Provider behaviour (arcanum v0.1.0)

Behaviour for LLM inference providers.

Each adapter (Ollama, OpenAI, Anthropic, etc.) implements this behaviour to provide a uniform interface for chat completion and model listing.

Adapters receive a ModelProfile that declares model capabilities upfront. All provider/model-specific serialization decisions are driven by the profile — no runtime detection, no retry-on-error branching.

Summary

Types

stream_event()

Callbacks

chat(provider, intent, profile)

Sends a chat completion request and returns the full response.

embed(provider, model, input)

Generates embeddings for the given text input.

list_models(provider)

Lists available models from the provider.

stream(provider, intent, profile)

Sends a streaming chat completion request.

Types

stream_event()

@type stream_event() :: {:data, Arcanum.Response.t()} | {:error, term()} | :done

Callbacks

chat(provider, intent, profile)

@callback chat(
  provider :: map(),
  intent :: Arcanum.Intent.t(),
  profile :: Arcanum.ModelProfile.t()
) ::
  {:ok, Arcanum.Response.t()} | {:error, term()}

Sends a chat completion request and returns the full response.

embed(provider, model, input)

(optional)

@callback embed(provider :: map(), model :: String.t(), input :: String.t()) ::
  {:ok, [float()]} | {:error, term()}

Generates embeddings for the given text input.

list_models(provider)

@callback list_models(provider :: map()) :: {:ok, [String.t()]} | {:error, term()}

Lists available models from the provider.

stream(provider, intent, profile)

@callback stream(
  provider :: map(),
  intent :: Arcanum.Intent.t(),
  profile :: Arcanum.ModelProfile.t()
) ::
  {:ok, Enumerable.t()} | {:error, term()}

Sends a streaming chat completion request.

Returns a stream of {:data, response} events, terminated by :done.