# `HuggingfaceClient.Request`
[🔗](https://github.com/huggingface/huggingface_client/blob/v0.1.0/lib/huggingface_client/inference/request.ex#L1)

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 `Task` that feeds a `Stream.resource`
- Auto-retries once on HTTP 503 (configurable)
- Emits `[:huggingface_client, :request, :start|:stop|:exception]` telemetry
- Redacts Authorization from error structs

# `auth_method`

```elixir
@type auth_method() :: :hf_token | :provider_key | :credentials_include | :none
```

# `request_opts`

```elixir
@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
}
```

# `build_request`

```elixir
@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}`.

# `execute`

```elixir
@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}`.

# `stream`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*