> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hugging Face Connector

> Deliver trained AI models from Narrative to Hugging Face Hub

The Hugging Face Connector exports trained AI models from Narrative's model repository to [Hugging Face Hub](https://huggingface.co), making them available for inference and sharing.

## Overview

Unlike audience delivery connectors that push data to advertising platforms, the Hugging Face Connector handles **model delivery**. After you train a model in Narrative's Model Studio, the connector uploads it to your Hugging Face account as a private model repository.

Delivered models include:

* All model weights and configuration files
* Inference files (`handler.py` and `requirements.txt`) for Hugging Face's inference infrastructure
* A version tag (e.g., `v1`) for tracking model iterations

## Requirements

### Hugging Face access token

You need a Hugging Face **User Access Token** with write permissions. The connector supports two token types:

| Token Type           | Required Permissions                                                     |
| -------------------- | ------------------------------------------------------------------------ |
| Fine-grained token   | `repo.content.read` and `repo.write`, scoped to at least one entity      |
| Write token (legacy) | Automatically grants access to your namespace and all your organizations |

<Warning>
  Organization tokens and other non-user token types are not supported. The token must be a **User Access Token**.
</Warning>

The token must grant write access to at least one model repository, organization, or user namespace.

### Delivery destinations

When delivering a model, you choose where it goes on Hugging Face:

| Option                    | Description                                                                      |
| ------------------------- | -------------------------------------------------------------------------------- |
| New model repository      | Creates a new private repository under the selected owner (organization or user) |
| Existing model repository | Delivers to a repository that already exists                                     |

## Installation

<Steps>
  <Step title="Navigate to the connector">
    In Narrative, go to **Installed Apps** in the left navigation and select **Hugging Face Connector**.
  </Step>

  <Step title="Add a profile">
    Click **Add profile** to begin connecting your Hugging Face account.
  </Step>

  <Step title="Enter your access token">
    Paste your Hugging Face User Access Token into the token field and click **Validate**.
  </Step>

  <Step title="Review accessible entities">
    After validation, expand **Hugging Face Access Token Details** to see the organizations, users, and model repositories your token grants write access to. These are the destinations available for model delivery.
  </Step>

  <Step title="Name your profile">
    Enter a **Profile name** and optional **Description**, then click **Create**.
  </Step>
</Steps>

Your profile is automatically enabled after creation and appears in the **Connector profiles** list on the settings page.

## Delivering a model

Model delivery happens automatically after training completes in Model Studio:

1. Train a model in **Model Studio** by selecting a base model, training dataset, and compute instance
2. Once training finishes, a delivery job is created that uses your connector profile
3. The connector downloads the model from Narrative's model store, prepares inference files, and uploads everything to Hugging Face Hub
4. The model appears as a **private repository** in your Hugging Face account, tagged with the model version

<Note>
  Delivery can take up to 30 minutes depending on model size. The process is idempotent—if a delivery is interrupted, it can safely retry without creating duplicates.
</Note>

## Troubleshooting

### Token validation errors

| Error                       | Cause                                               | Resolution                                                                                       |
| --------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Token is invalid            | Token doesn't authenticate with Hugging Face        | Verify the token value in your [Hugging Face settings](https://huggingface.co/settings/tokens)   |
| Must be a user access token | Token is an organization token or unrecognized type | Create a new User Access Token on Hugging Face                                                   |
| Must grant write access     | Token has no writable entities                      | Update token permissions to include `repo.content.read` and `repo.write` for at least one entity |

### Expired or revoked token

If your token expires or is revoked after profile creation, the profile detail page displays a warning. Contact Narrative Support to resolve the issue—you'll need to create a new profile with a valid token.

***

## Related content

<CardGroup cols={2}>
  <Card title="Connectors Overview" icon="plug" href="/reference/connectors/index">
    Reference documentation for all available connectors
  </Card>

  <Card title="Data Activation Overview" icon="bullseye-arrow" href="/concepts/data-activation/overview">
    Understand how connectors deliver data
  </Card>
</CardGroup>