Core HTTP execution layer for all inference requests.
Mirrors the logic in makeRequestOptions.ts and utils/request.ts from the JS package.
Responsibilities
- Builds URL, headers and body by delegating to the provider module
- Executes POST requests via
Req/Finch - Streams SSE via a
Taskthat feeds aStream.resource - Auto-retries once on HTTP 503 (configurable)
- Emits
[:huggingface_client, :request, :start|:stop|:exception]telemetry - Redacts Authorization from error structs
Summary
Functions
Builds the complete HTTP request map from args + provider module.
Executes a synchronous (non-streaming) POST and returns the parsed response body.
Returns {:ok, stream} where each element is a decoded JSON map from an SSE data frame.
Types
@type auth_method() :: :hf_token | :provider_key | :credentials_include | :none
@type request_opts() :: %{ optional(:access_token) => String.t() | nil, optional(:provider) => String.t() | nil, optional(:endpoint_url) => String.t() | nil, optional(:bill_to) => String.t() | nil, optional(:task) => String.t() | nil, optional(:output_type) => atom() | nil, optional(:retry_on_503) => boolean(), optional(:req_opts) => keyword(), optional(:mapping) => map() | nil }
Functions
@spec build_request(map(), module(), request_opts()) :: {:ok, map()} | {:error, Exception.t()}
Builds the complete HTTP request map from args + provider module.
Returns {:ok, %{url, headers, body, provider_module, auth_method}} or {:error, exception}.
@spec execute(map(), module(), request_opts()) :: {:ok, {term(), map()}} | {:error, Exception.t()}
Executes a synchronous (non-streaming) POST and returns the parsed response body.
Returns {:ok, {body, context}} or {:error, exception}.
@spec stream(map(), module(), request_opts()) :: {:ok, Enumerable.t()} | {:error, Exception.t()}
Returns {:ok, stream} where each element is a decoded JSON map from an SSE data frame.
Internally spawns a Task to perform the HTTP request. The task is shut down when
the stream is halted or garbage-collected.