LangExtract.Provider behaviour (LangExtract v0.5.0)

Behaviour for LLM inference providers.

Each provider implements infer/2 which takes a prompt string and returns the raw LLM response. Parsing and normalization are the caller's responsibility.

Shared helpers for API key resolution and HTTP error mapping are provided for use by provider implementations.

Summary

Callbacks

build_http_client(opts)

infer(prompt, opts)

Functions

common_opts(opts, defaults)

Extracts common provider options (model, max_tokens, temperature, base_url) from opts with provider-specific defaults. For use by provider implementations.

fetch_api_key(opts, env_var)

Resolves an API key from opts or an environment variable.

map_response(arg, extract_text)

Maps a Req response to a provider result tuple.

req_options(opts, req_opts)

Merges caller-supplied :req_options into the provider's Req options.

resolve_http_client(opts, build_fn)

Returns a pre-built HTTP client from opts, or builds one via the given function.

Callbacks

build_http_client(opts)

@callback build_http_client(opts :: keyword()) ::
  {:ok, Req.Request.t()} | {:error, term()}

infer(prompt, opts)

@callback infer(prompt :: String.t(), opts :: keyword()) ::
  {:ok, String.t()} | {:error, term()}

Functions

common_opts(opts, defaults)

@spec common_opts(keyword(), keyword()) :: %{
  model: String.t(),
  max_tokens: integer(),
  temperature: number() | nil,
  base_url: String.t()
}

Extracts common provider options (model, max_tokens, temperature, base_url) from opts with provider-specific defaults. For use by provider implementations.

fetch_api_key(opts, env_var)

@spec fetch_api_key(
  keyword(),
  String.t()
) :: {:ok, String.t()} | {:error, :missing_api_key}

Resolves an API key from opts or an environment variable.

Returns {:ok, key} or {:error, :missing_api_key} if nil or empty. For use by provider implementations.

map_response(arg, extract_text)

@spec map_response(
  {:ok, Req.Response.t()} | {:error, Exception.t()},
  (term() -> {:ok, String.t()} | {:error, :empty_response})
) :: {:ok, String.t()} | {:error, term()}

Maps a Req response to a provider result tuple.

Delegates to extract_text for HTTP 200; maps error status codes and network failures to standard error tuples. For use by provider implementations.

req_options(opts, req_opts)

@spec req_options(keyword(), keyword()) :: keyword()

Merges caller-supplied :req_options into the provider's Req options.

Applies shared HTTP defaults first (120s receive timeout, transient retries), then the provider's own options, then anything in :req_options — so callers can override any Req configuration (timeouts, retry policy, pool settings, plug for testing, etc.) without the provider needing to know about them.

resolve_http_client(opts, build_fn)

@spec resolve_http_client(
  keyword(),
  (keyword() -> {:ok, Req.Request.t()} | {:error, term()})
) :: {:ok, Req.Request.t()} | {:error, term()}

Returns a pre-built HTTP client from opts, or builds one via the given function.