# HuggingFace Provider

HuggingFace's Router exposes an OpenAI Responses-API-compatible endpoint
(`https://router.huggingface.co/v1/responses`) that proxies to open-source
models hosted across HuggingFace's Inference Providers. This is the only API
the Go SDK's HuggingFace provider talks to — it mirrors `@ai-sdk/huggingface`.

> The HuggingFace Router Responses API does not offer text embeddings or
> image generation. `EmbeddingModel`/`ImageModel` return an error; use the
> HuggingFace Inference API directly for those.

## Setup

### Installation

```go
import (
    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/huggingface"
)
```

### Configuration

```go
provider := huggingface.New(huggingface.Config{
    APIKey: os.Getenv("HUGGINGFACE_API_KEY"), // falls back to this env var if empty
})

model, err := provider.LanguageModel("deepseek-ai/DeepSeek-V3-0324")
```

### Get API Key

1. Sign up at [huggingface.co](https://huggingface.co)
2. Create a token in settings
3. Set the environment variable:

```bash
export HUGGINGFACE_API_KEY=hf_...
```

## Example

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/digitallysavvy/go-ai/pkg/ai"
    "github.com/digitallysavvy/go-ai/pkg/providers/huggingface"
)

func main() {
    provider := huggingface.New(huggingface.Config{
        APIKey: os.Getenv("HUGGINGFACE_API_KEY"),
    })

    model, err := provider.LanguageModel("deepseek-ai/DeepSeek-V3-0324")
    if err != nil {
        log.Fatal(err)
    }

    result, err := ai.GenerateText(context.Background(), ai.GenerateTextOptions{
        Model:  model,
        Prompt: "Explain transformers",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text)
}
```

Streaming (`ai.StreamText`) uses the Responses API's real Server-Sent Events
stream — text, reasoning, tool-call, and source deltas are emitted as they
arrive rather than being chunked after the fact.

## Tool calls, reasoning, and sources

The Responses API returns tool calls (`function_call`), MCP tool calls/lists
(`mcp_call`, `mcp_list_tools`), reasoning blocks, and URL citation sources
alongside text. The Go SDK surfaces all of these through the standard
`ai.GenerateTextResult`/`ai.StreamTextResult` content and tool-call APIs.

## Provider Options

```go
result, err := ai.GenerateText(ctx, ai.GenerateTextOptions{
    Model:  model,
    Prompt: "...",
    ProviderOptions: map[string]interface{}{
        "huggingface": map[string]interface{}{
            "metadata":         map[string]interface{}{"key": "value"},
            "instructions":     "Be concise",
            "strictJsonSchema": true,
            "reasoningEffort":  "high",
        },
    },
})
```

## Available Models

The Responses API accepts any model ID listed at
[router.huggingface.co/v1/models](https://router.huggingface.co/v1/models),
including:

| Model ID | Best For |
|----------|----------|
| meta-llama/Llama-3.3-70B-Instruct | General purpose |
| deepseek-ai/DeepSeek-V3-0324 | General purpose |
| deepseek-ai/DeepSeek-R1 | Reasoning |
| Qwen/Qwen3-Coder-480B-A35B-Instruct | Coding |
| moonshotai/Kimi-K2-Instruct | General purpose |

## Workflow Serialization

HuggingFace language models can cross a workflow boundary with
`providerutils.SerializeModel` / `DeserializeModel`. See
[Provider Serialization](https://goaisdk.com/docs/agents/workflow-agent.md#provider-serialization)
for the mechanism.

## See Also

- [HuggingFace Router Documentation](https://huggingface.co/docs/inference-providers)
- [Model Hub](https://huggingface.co/models)