Gut.Adapter behaviour (gut v0.2.0)

Copy Markdown View Source

Defines the contract between Gut and an LLM adapter.

An adapter receives an encoded subject, a question, and a list of choices. Each choice contains an opaque ID and a description. The adapter returns one of those IDs. Gut maps the ID back to the original Elixir value.

Configure an adapter as a module or as a {module, options} tuple:

config :gut, adapter: {Gut.ReqLLM, model: "anthropic:claude-haiku-4-5"}

Gut calls init/1 and choose/4 in the caller process.

Summary

Types

choice()

An opaque choice ID and the description sent to the adapter.

spec()

An adapter module, with or without adapter-specific options.

Callbacks

choose(subject, question, choices, state)

Chooses one of the supplied opaque IDs.

init(opts)

Validates the adapter options and returns the state passed to choose/4.

Types

choice()

@type choice() :: {id :: String.t(), description :: String.t()}

An opaque choice ID and the description sent to the adapter.

spec()

@type spec() :: module() | {module(), keyword()}

An adapter module, with or without adapter-specific options.

Callbacks

choose(subject, question, choices, state)

@callback choose(
  subject :: String.t(),
  question :: String.t(),
  choices :: [choice()],
  state :: term()
) ::
  {:ok, String.t()} | {:error, Gut.Error.t()}

Chooses one of the supplied opaque IDs.

Returns a Gut.Error when the adapter or its provider cannot make a choice.

init(opts)

@callback init(opts :: keyword()) :: state :: term()

Validates the adapter options and returns the state passed to choose/4.

Raises ArgumentError when the configuration is invalid. This callback must not start an unsupervised process.