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

Top-level public API for the HuggingFace Elixir client.

All inference functions accept either a `HuggingfaceClient.Client` struct (for
shared defaults across calls) or a plain keyword list / map of per-call options.

## Quick start

    # Build a reusable client
    client = HuggingfaceClient.client("hf_your_token")

    # Chat completion
    {:ok, resp} = HuggingfaceClient.chat_completion(client, %{
      model:    "meta-llama/Llama-3-8B-Instruct",
      messages: [%{role: "user", content: "Tell me a joke."}]
    })

    # Streaming
    {:ok, stream} = HuggingfaceClient.chat_completion_stream(client, %{
      model:    "meta-llama/Llama-3-8B-Instruct",
      messages: [%{role: "user", content: "Count to five."}]
    })
    HuggingfaceClient.StreamHelpers.each_content(stream, &IO.write/1)

    # Text-to-image
    {:ok, png_bytes} = HuggingfaceClient.text_to_image(client, %{
      model:  "stabilityai/stable-diffusion-xl-base-1.0",
      inputs: "A cat wearing a space suit"
    })

# `automatic_speech_recognition`

```elixir
@spec automatic_speech_recognition(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Transcribes audio.  Pass raw audio bytes as `:inputs`.

# `chat_completion`

```elixir
@spec chat_completion(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Sends a chat-completion request.  Returns `{:ok, response_map}` or `{:error, exception}`.

# `chat_completion_stream`

```elixir
@spec chat_completion_stream(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, Enumerable.t()} | {:error, Exception.t()}
```

Sends a streaming chat-completion request.

Returns `{:ok, stream}` where `stream` is a lazy enumerable of decoded
`chat.completion.chunk` maps.  Use `HuggingfaceClient.StreamHelpers` to consume it.

# `client`

```elixir
@spec client(
  String.t() | nil,
  keyword()
) :: HuggingfaceClient.Client.t()
```

Creates a reusable `Client` struct.

## Options

- `:provider` — inference provider, e.g. `"groq"`, `"together"`. Defaults to auto-routing.
- `:bill_to` — org slug billed for router requests.
- `:endpoint_url` — custom inference endpoint URL.
- `:retry_on_503` — whether to retry once on 503 (default `true`).
- `:req_opts` — extra keyword opts forwarded to `Req`.

Raises `InputError` on unknown or mistyped options.

# `endpoint_client`

```elixir
@spec endpoint_client(String.t() | nil, String.t(), keyword()) ::
  HuggingfaceClient.Client.t()
```

Creates a `Client` bound to a specific inference `endpoint_url`.

# `feature_extraction`

```elixir
@spec feature_extraction(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, list()} | {:error, Exception.t()}
```

Extracts feature vectors / embeddings.

# `image_classification`

```elixir
@spec image_classification(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, list()} | {:error, Exception.t()}
```

Classifies images.

# `sentence_similarity`

```elixir
@spec sentence_similarity(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, list()} | {:error, Exception.t()}
```

Sentence similarity / bi-encoder scoring.

# `summarization`

```elixir
@spec summarization(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Summarises text.

# `text_generation`

```elixir
@spec text_generation(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Text-generation (non-chat).

# `text_to_image`

```elixir
@spec text_to_image(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, binary()} | {:error, Exception.t()}
```

Generates an image from a text prompt.  Returns `{:ok, binary}` (PNG/JPEG bytes).

# `translation`

```elixir
@spec translation(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, map()} | {:error, Exception.t()}
```

Translates text.

# `zero_shot_classification`

```elixir
@spec zero_shot_classification(HuggingfaceClient.Client.t() | map(), map()) ::
  {:ok, list()} | {:error, Exception.t()}
```

Classifies text into provided `candidate_labels`.

---

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