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

# Hugging Face

> Trace Hugging Face Inference SDK calls in Braintrust to debug prompts, evaluate models, and monitor production usage

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[Hugging Face Inference](https://huggingface.co/docs/inference-providers/) provides a unified interface to LLMs, embeddings, and other models hosted on Hugging Face and routed providers. Braintrust traces chat completions, text generation, and feature extraction calls.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-typescript">
    Setup
  </h2>

  Install the Braintrust and `@huggingface/inference` packages, then set your API keys. Requires `@huggingface/inference` v2.0.0 or later (any 2.x, 3.x, or 4.x release).

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pnpm add braintrust @huggingface/inference
        ```

        ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        npm install braintrust @huggingface/inference
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      HUGGINGFACE_API_KEY=<your-huggingface-token>

      # For organizations on the EU data plane, use https://api-eu.braintrust.dev
      # For self-hosted deployments, use your data plane URL
      # BRAINTRUST_API_URL=<your-braintrust-api-url>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-typescript">
    Auto-instrumentation
  </h2>

  To trace Hugging Face Inference SDK calls without modifying your application code, initialize Braintrust normally, then run your app with Braintrust's import hook to patch the SDK at runtime.

  <Steps>
    <Step title="Initialize Braintrust and call Hugging Face">
      <CodeGroup>
        ```javascript title="trace-huggingface-auto.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        import { initLogger } from "braintrust";
        import * as huggingFace from "@huggingface/inference";

        initLogger({
          projectName: "huggingface-example",
          apiKey: process.env.BRAINTRUST_API_KEY,
        });

        const client = new huggingFace.InferenceClient(
          process.env.HUGGINGFACE_API_KEY,
        );

        const response = await client.chatCompletion({
          model: "meta-llama/Llama-3.1-8B-Instruct",
          provider: "featherless-ai",
          messages: [
            {
              role: "user",
              content: "Reply with exactly OK.",
            },
          ],
          max_tokens: 16,
          temperature: 0,
        });

        console.log(response.choices?.[0]?.message?.content);
        ```
      </CodeGroup>
    </Step>

    <Step title="Run with the import hook">
      ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      node --import braintrust/hook.mjs trace-huggingface-auto.js
      ```

      The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects — compile your TypeScript to JavaScript, then run the compiled file with the import hook.

      <Note>
        If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  To trace Hugging Face clients manually, wrap them yourself with `wrapHuggingFace()`. Use this when you want to trace selected clients, or wrap the module directly before constructing clients.

  <CodeGroup>
    ```javascript title="trace-huggingface-wrap.js" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import { initLogger, wrapHuggingFace } from "braintrust";
    import * as huggingFace from "@huggingface/inference";

    initLogger({
      projectName: "huggingface-example",
      apiKey: process.env.BRAINTRUST_API_KEY,
    });

    const hf = wrapHuggingFace(huggingFace);
    const client = new hf.InferenceClient(process.env.HUGGINGFACE_API_KEY);

    const embedding = await client.featureExtraction({
      inputs: "Paris France",
      model: "thenlper/gte-large",
      provider: "hf-inference",
    });

    console.log(embedding);
    ```
  </CodeGroup>

  `wrapHuggingFace()` can wrap either:

  * The module import itself, including `InferenceClient`, `InferenceClientEndpoint`, `HfInference`, and `HfInferenceEndpoint`.
  * An already-constructed client instance.

  If you use routed or custom endpoints via `client.endpoint(...)`, Braintrust records the endpoint URL in span metadata.

  <h2 id="what-traced-typescript">
    What Braintrust traces
  </h2>

  Braintrust traces these `@huggingface/inference` SDK calls, capturing:

  * Chat completions, including streaming chat with first-token timing.
  * Text generation, including streaming text generation with first-token timing.
  * Feature extraction, summarized as embedding count, length, and batch count.
  * Token usage, including prompt, completion, and total tokens.
  * Request metadata, including model, provider, and selected request parameters.
  * Response identifiers, including ID, model, object, created, and finish reason.
  * Routed endpoint URL when calling `client.endpoint(...)`.

  <h2 id="resources-typescript">
    Resources
  </h2>

  * [Hugging Face Inference SDK](https://github.com/huggingface/huggingface.js/tree/main/packages/inference)
  * [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/)
  * [Trace LLM calls](/instrument/trace-llm-calls)
</View>