@ai-sdk/huggingface 1.0.16 → 1.0.18

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @ai-sdk/huggingface
 
+## 1.0.18
+
+### Patch Changes
+
+- 2b8369d: chore: add docs to package dist
+
+## 1.0.17
+
+### Patch Changes
+
+- 8dc54db: chore: add src folders to package bundle
+- Updated dependencies [8dc54db]
+  - @ai-sdk/openai-compatible@2.0.17
+
 ## 1.0.16
 
 ### Patch Changes

package/docs/170-huggingface.mdx

@@ -0,0 +1,119 @@
+---
+title: Hugging Face
+description: Learn how to use Hugging Face Provider.
+---
+
+# Hugging Face Provider
+
+The [Hugging Face](https://huggingface.co/) provider offers access to thousands of language models through [Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers/index), including models from Meta, DeepSeek, Qwen, and more.
+
+API keys can be obtained from [Hugging Face Settings](https://huggingface.co/settings/tokens).
+
+## Setup
+
+The Hugging Face provider is available via the `@ai-sdk/huggingface` module. You can install it with:
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/huggingface" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/huggingface" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/huggingface" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/huggingface" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `huggingface` from `@ai-sdk/huggingface`:
+
+```ts
+import { huggingface } from '@ai-sdk/huggingface';
+```
+
+For custom configuration, you can import `createHuggingFace` and create a provider instance with your settings:
+
+```ts
+import { createHuggingFace } from '@ai-sdk/huggingface';
+
+const huggingface = createHuggingFace({
+  apiKey: process.env.HUGGINGFACE_API_KEY ?? '',
+});
+```
+
+You can use the following optional settings to customize the Hugging Face provider instance:
+
+- **baseURL** _string_
+
+  Use a different URL prefix for API calls, e.g. to use proxy servers.
+  The default prefix is `https://router.huggingface.co/v1`.
+
+- **apiKey** _string_
+
+  API key that is being sent using the `Authorization` header. It defaults to
+  the `HUGGINGFACE_API_KEY` environment variable. You can get your API key
+  from [Hugging Face Settings](https://huggingface.co/settings/tokens).
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+
+## Language Models
+
+You can create language models using a provider instance:
+
+```ts
+import { huggingface } from '@ai-sdk/huggingface';
+import { generateText } from 'ai';
+
+const { text } = await generateText({
+  model: huggingface('deepseek-ai/DeepSeek-V3-0324'),
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+});
+```
+
+You can also use the `.responses()` or `.languageModel()` factory methods:
+
+```ts
+const model = huggingface.responses('deepseek-ai/DeepSeek-V3-0324');
+// or
+const model = huggingface.languageModel('moonshotai/Kimi-K2-Instruct');
+```
+
+Hugging Face language models can be used in the `streamText` function
+(see [AI SDK Core](/docs/ai-sdk-core)).
+
+You can explore the latest and trending models with their capabilities, context size, throughput and pricing on the [Hugging Face Inference Models](https://huggingface.co/inference/models) page.
+
+## Model Capabilities
+
+| Model                                       | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
+| ------------------------------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `meta-llama/Llama-3.1-8B-Instruct`          | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `meta-llama/Llama-3.1-70B-Instruct`         | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `meta-llama/Llama-3.3-70B-Instruct`         | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `meta-llama/Llama-4-Scout-17B-16E-Instruct` | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `deepseek-ai/DeepSeek-V3-0324`              | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `deepseek-ai/DeepSeek-R1`                   | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `deepseek-ai/DeepSeek-R1-Distill-Llama-70B` | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `Qwen/Qwen3-235B-A22B-Instruct-2507`        | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `Qwen/Qwen3-Coder-480B-A35B-Instruct`       | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `Qwen/Qwen2.5-VL-7B-Instruct`               | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `google/gemma-3-27b-it`                     | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+| `moonshotai/Kimi-K2-Instruct`               | <Cross size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
+
+<Note>
+  The capabilities depend on the specific model you're using. Check the model
+  documentation on Hugging Face Hub for detailed information about each model's
+  features.
+</Note>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/huggingface",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,9 +8,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
+    "src",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -20,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "2.0.16",
+    "@ai-sdk/openai-compatible": "2.0.17",
     "@ai-sdk/provider": "3.0.4",
     "@ai-sdk/provider-utils": "4.0.8"
   },
@@ -29,7 +34,7 @@
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.1",
+    "@ai-sdk/test-server": "1.0.2",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -55,7 +60,7 @@
   "scripts": {
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
-    "clean": "rm -rf dist *.tsbuildinfo",
+    "clean": "rm -rf dist docs *.tsbuildinfo",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

package/src/huggingface-config.ts

@@ -0,0 +1,9 @@
+import { FetchFunction } from '@ai-sdk/provider-utils';
+
+export type HuggingFaceConfig = {
+  provider: string;
+  url: (options: { modelId: string; path: string }) => string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  generateId?: () => string;
+};

package/src/huggingface-error.ts

@@ -0,0 +1,17 @@
+import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+const huggingfaceErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    type: z.string().optional(),
+    code: z.string().optional(),
+  }),
+});
+
+export type HuggingFaceErrorData = z.infer<typeof huggingfaceErrorDataSchema>;
+
+export const huggingfaceFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: huggingfaceErrorDataSchema,
+  errorToMessage: data => data.error.message,
+});

package/src/huggingface-provider.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from 'vitest';
+import { createHuggingFace } from './huggingface-provider';
+
+describe('HuggingFaceProvider', () => {
+  describe('createHuggingFace', () => {
+    it('should create provider with default configuration', () => {
+      const provider = createHuggingFace();
+
+      expect(provider).toMatchInlineSnapshot(`[Function]`);
+      expect(typeof provider.responses).toBe('function');
+      expect(typeof provider.languageModel).toBe('function');
+    });
+
+    it('should create provider with custom settings', () => {
+      const provider = createHuggingFace({
+        apiKey: 'custom-key',
+        baseURL: 'https://custom.url',
+        headers: { 'Custom-Header': 'test' },
+      });
+
+      expect(typeof provider).toBe('function');
+      expect(provider).toHaveProperty('responses');
+      expect(provider).toHaveProperty('languageModel');
+    });
+  });
+
+  describe('model creation methods', () => {
+    it('should expose responses method', () => {
+      const provider = createHuggingFace();
+
+      expect(typeof provider.responses).toBe('function');
+    });
+
+    it('should expose languageModel method', () => {
+      const provider = createHuggingFace();
+
+      expect(typeof provider.languageModel).toBe('function');
+    });
+  });
+
+  describe('unsupported functionality', () => {
+    it('should throw for text embedding models', () => {
+      const provider = createHuggingFace();
+
+      expect(() =>
+        provider.embeddingModel('any-model'),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `[AI_NoSuchModelError: Hugging Face Responses API does not support text embeddings. Use the Hugging Face Inference API directly for embeddings.]`,
+      );
+    });
+
+    it('should throw for image models', () => {
+      const provider = createHuggingFace();
+
+      expect(() =>
+        provider.imageModel('any-model'),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `[AI_NoSuchModelError: Hugging Face Responses API does not support image generation. Use the Hugging Face Inference API directly for image models.]`,
+      );
+    });
+  });
+});

package/src/huggingface-provider.ts

@@ -0,0 +1,119 @@
+import {
+  LanguageModelV3,
+  NoSuchModelError,
+  ProviderV3,
+} from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  generateId,
+  loadApiKey,
+  withoutTrailingSlash,
+} from '@ai-sdk/provider-utils';
+import { HuggingFaceResponsesLanguageModel } from './responses/huggingface-responses-language-model';
+import { HuggingFaceResponsesModelId } from './responses/huggingface-responses-settings';
+
+export interface HuggingFaceProviderSettings {
+  /**
+Hugging Face API key.
+*/
+  apiKey?: string;
+  /**
+Base URL for the API calls.
+*/
+  baseURL?: string;
+  /**
+Custom headers to include in the requests.
+*/
+  headers?: Record<string, string>;
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+*/
+  fetch?: FetchFunction;
+
+  generateId?: () => string;
+}
+
+export interface HuggingFaceProvider extends ProviderV3 {
+  /**
+Creates a Hugging Face responses model for text generation.
+*/
+  (modelId: HuggingFaceResponsesModelId): LanguageModelV3;
+
+  /**
+Creates a Hugging Face responses model for text generation.
+*/
+  languageModel(modelId: HuggingFaceResponsesModelId): LanguageModelV3;
+
+  /**
+Creates a Hugging Face responses model for text generation.
+*/
+  responses(modelId: HuggingFaceResponsesModelId): LanguageModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+/**
+Create a Hugging Face provider instance.
+ */
+export function createHuggingFace(
+  options: HuggingFaceProviderSettings = {},
+): HuggingFaceProvider {
+  const baseURL =
+    withoutTrailingSlash(options.baseURL) ?? 'https://router.huggingface.co/v1';
+
+  const getHeaders = () => ({
+    Authorization: `Bearer ${loadApiKey({
+      apiKey: options.apiKey,
+      environmentVariableName: 'HUGGINGFACE_API_KEY',
+      description: 'Hugging Face',
+    })}`,
+    ...options.headers,
+  });
+
+  const createResponsesModel = (modelId: HuggingFaceResponsesModelId) => {
+    return new HuggingFaceResponsesLanguageModel(modelId, {
+      provider: 'huggingface.responses',
+      url: ({ path }) => `${baseURL}${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+      generateId: options.generateId ?? generateId,
+    });
+  };
+
+  const provider = (modelId: HuggingFaceResponsesModelId) =>
+    createResponsesModel(modelId);
+
+  provider.specificationVersion = 'v3' as const;
+  provider.languageModel = createResponsesModel;
+  provider.responses = createResponsesModel;
+
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+      message:
+        'Hugging Face Responses API does not support text embeddings. Use the Hugging Face Inference API directly for embeddings.',
+    });
+  };
+  provider.textEmbeddingModel = provider.embeddingModel;
+
+  provider.imageModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'imageModel',
+      message:
+        'Hugging Face Responses API does not support image generation. Use the Hugging Face Inference API directly for image models.',
+    });
+  };
+
+  return provider;
+}
+
+/**
+Default Hugging Face provider instance.
+ */
+export const huggingface = createHuggingFace();

package/src/index.ts

@@ -0,0 +1,10 @@
+export { createHuggingFace, huggingface } from './huggingface-provider';
+export type {
+  HuggingFaceProvider,
+  HuggingFaceProviderSettings,
+} from './huggingface-provider';
+export type {
+  HuggingFaceResponsesModelId,
+  HuggingFaceResponsesSettings,
+} from './responses/huggingface-responses-settings';
+export type { OpenAICompatibleErrorData as HuggingFaceErrorData } from '@ai-sdk/openai-compatible';

package/src/responses/convert-huggingface-responses-usage.ts

@@ -0,0 +1,54 @@
+import { LanguageModelV3Usage } from '@ai-sdk/provider';
+
+export type HuggingFaceResponsesUsage = {
+  input_tokens: number;
+  input_tokens_details?: {
+    cached_tokens?: number;
+  };
+  output_tokens: number;
+  output_tokens_details?: {
+    reasoning_tokens?: number;
+  };
+  total_tokens: number;
+};
+
+export function convertHuggingFaceResponsesUsage(
+  usage: HuggingFaceResponsesUsage | undefined | null,
+): LanguageModelV3Usage {
+  if (usage == null) {
+    return {
+      inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined,
+      },
+      raw: undefined,
+    };
+  }
+
+  const inputTokens = usage.input_tokens;
+  const outputTokens = usage.output_tokens;
+  const cachedTokens = usage.input_tokens_details?.cached_tokens ?? 0;
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens ?? 0;
+
+  return {
+    inputTokens: {
+      total: inputTokens,
+      noCache: inputTokens - cachedTokens,
+      cacheRead: cachedTokens,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: outputTokens,
+      text: outputTokens - reasoningTokens,
+      reasoning: reasoningTokens,
+    },
+    raw: usage,
+  };
+}

package/src/responses/convert-to-huggingface-responses-messages.ts

@@ -0,0 +1,111 @@
+import {
+  SharedV3Warning,
+  LanguageModelV3Prompt,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+
+export async function convertToHuggingFaceResponsesMessages({
+  prompt,
+}: {
+  prompt: LanguageModelV3Prompt;
+}): Promise<{
+  input: string | Array<any>;
+  warnings: Array<SharedV3Warning>;
+}> {
+  const messages: Array<any> = [];
+  const warnings: Array<SharedV3Warning> = [];
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        messages.push({ role: 'system', content });
+        break;
+      }
+
+      case 'user': {
+        messages.push({
+          role: 'user',
+          content: content.map(part => {
+            switch (part.type) {
+              case 'text': {
+                return { type: 'input_text', text: part.text };
+              }
+              case 'file': {
+                if (part.mediaType.startsWith('image/')) {
+                  const mediaType =
+                    part.mediaType === 'image/*'
+                      ? 'image/jpeg'
+                      : part.mediaType;
+
+                  return {
+                    type: 'input_image',
+                    image_url:
+                      part.data instanceof URL
+                        ? part.data.toString()
+                        : `data:${mediaType};base64,${part.data}`,
+                  };
+                } else {
+                  throw new UnsupportedFunctionalityError({
+                    functionality: `file part media type ${part.mediaType}`,
+                  });
+                }
+              }
+              default: {
+                const _exhaustiveCheck: never = part;
+                throw new Error(`Unsupported part type: ${_exhaustiveCheck}`);
+              }
+            }
+          }),
+        });
+
+        break;
+      }
+
+      case 'assistant': {
+        for (const part of content) {
+          switch (part.type) {
+            case 'text': {
+              messages.push({
+                role: 'assistant',
+                content: [{ type: 'output_text', text: part.text }],
+              });
+              break;
+            }
+            case 'tool-call': {
+              // tool calls are handled by the responses API
+              break;
+            }
+
+            case 'tool-result': {
+              // tool results are handled by the responses API
+              break;
+            }
+
+            case 'reasoning': {
+              // include reasoning content in the message text
+              messages.push({
+                role: 'assistant',
+                content: [{ type: 'output_text', text: part.text }],
+              });
+              break;
+            }
+          }
+        }
+
+        break;
+      }
+
+      case 'tool': {
+        warnings.push({ type: 'unsupported', feature: 'tool messages' });
+        break;
+      }
+
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  return { input: messages, warnings };
+}