names

Author: julien-c

packages/inference/README.md

@@ -128,21 +128,21 @@ The inference package provides specific error types to help you handle different
 
 The package defines several error types that extend the base `Error` class:
 
-- `HfInferenceError`: Base error class for all Hugging Face Inference errors
-- `HfInferenceInputError`: Thrown when there are issues with input parameters
-- `HfInferenceProviderApiError`: Thrown when there are API-level errors from providers
-- `HfInferenceHubApiError`: Thrown when there are API-levels errors from the Hugging Face Hub
-- `HfInferenceProviderOutputError`: Thrown when there are issues with providers' API responses format
+- `InferenceClientError`: Base error class for all Hugging Face Inference errors
+- `InferenceClientInputError`: Thrown when there are issues with input parameters
+- `InferenceClientProviderApiError`: Thrown when there are API-level errors from providers
+- `InferenceClientHubApiError`: Thrown when there are API-levels errors from the Hugging Face Hub
+- `InferenceClientProviderOutputError`: Thrown when there are issues with providers' API responses format
 
 ### Example Usage
 
 ```typescript
 import { InferenceClient } from "@huggingface/inference";
 import {
-  HfInferenceError,
-  HfInferenceProviderApiError,
-  HfInferenceProviderOutputError,
-  HfInferenceHubApiError,
+  InferenceClientError,
+  InferenceClientProviderApiError,
+  InferenceClientProviderOutputError,
+  InferenceClientHubApiError,
 } from "@huggingface/inference";
 
 const hf = new HfInference();
@@ -153,20 +153,20 @@ try {
     inputs: "Hello, I'm a language model",
   });
 } catch (error) {
-  if (error instanceof HfInferenceProviderApiError) {
+  if (error instanceof InferenceClientProviderApiError) {
     // Handle API errors (e.g., rate limits, authentication issues)
     console.error("Provider API Error:", error.message);
     console.error("HTTP Request details:", error.request);
     console.error("HTTP Response details:", error.response);
-  if (error instanceof HfInferenceHubApiError) {
+  if (error instanceof InferenceClientHubApiError) {
     // Handle API errors (e.g., rate limits, authentication issues)
     console.error("Hub API Error:", error.message);
     console.error("HTTP Request details:", error.request);
     console.error("HTTP Response details:", error.response);
-  } else if (error instanceof HfInferenceProviderOutputError) {
+  } else if (error instanceof InferenceClientProviderOutputError) {
     // Handle malformed responses from providers
     console.error("Provider Output Error:", error.message);
-  } else if (error instanceof HfInferenceInputError) {
+  } else if (error instanceof InferenceClientInputError) {
     // Handle invalid input parameters
     console.error("Input Error:", error.message);
   } else {
@@ -182,7 +182,7 @@ try {
     inputs: "Hello, I'm a language model",
   });
 } catch (error) {
-  if (error instanceof HfInferenceError) {
+  if (error instanceof InferenceClientError) {
     // Handle errors from @huggingface/inference
     console.error("Error from InferenceClient:", error);
   } else {
@@ -194,7 +194,7 @@ try {
 
 ### Error Details
 
-#### HfInferenceProviderApiError
+#### InferenceClientProviderApiError
 
 This error occurs when there are issues with the API request when performing inference at the selected provider.
 
@@ -203,7 +203,7 @@ It has several properties:
 - `request`: Details about the failed request (URL, method, headers)
 - `response`: Response details including status code and body
 
-#### HfInferenceHubApiError
+#### InferenceClientHubApiError
 
 This error occurs when there are issues with the API request when requesting the Hugging Face Hub API.
 
@@ -213,11 +213,11 @@ It has several properties:
 - `response`: Response details including status code and body
 
 
-#### HfInferenceProviderOutputError
+#### InferenceClientProviderOutputError
 
 This error occurs when a provider returns a response in an unexpected format.
 
-#### HfInferenceInputError
+#### InferenceClientInputError
 
 This error occurs when input parameters are invalid or missing. The error message describes what's wrong with the input.
 

packages/inference/src/error.ts

@@ -3,14 +3,14 @@ import type { JsonObject } from "./vendor/type-fest/basic.js";
 /**
  * Base class for all inference-related errors.
  */
-export abstract class HfInferenceError extends Error {
+export abstract class InferenceClientError extends Error {
 	constructor(message: string) {
 		super(message);
-		this.name = "HfInferenceError";
+		this.name = "InferenceClientError";
 	}
 }
 
-export class HfInferenceInputError extends HfInferenceError {
+export class InferenceClientInputError extends InferenceClientError {
 	constructor(message: string) {
 		super(message);
 		this.name = "InputError";
@@ -30,7 +30,7 @@ interface HttpResponse {
 	body: JsonObject | string;
 }
 
-abstract class HfInferenceHttpRequestError extends HfInferenceError {
+abstract class InferenceClientHttpRequestError extends InferenceClientError {
 	httpRequest: HttpRequest;
 	httpResponse: HttpResponse;
 	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
@@ -54,7 +54,7 @@ abstract class HfInferenceHttpRequestError extends HfInferenceError {
 /**
  * Thrown when the HTTP request to the provider fails, e.g. due to API issues or server errors.
  */
-export class HfInferenceProviderApiError extends HfInferenceHttpRequestError {
+export class InferenceClientProviderApiError extends InferenceClientHttpRequestError {
 	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
 		super(message, httpRequest, httpResponse);
 		this.name = "ProviderApiError";
@@ -64,7 +64,7 @@ export class HfInferenceProviderApiError extends HfInferenceHttpRequestError {
 /**
  * Thrown when the HTTP request to the hub fails, e.g. due to API issues or server errors.
  */
-export class HfInferenceHubApiError extends HfInferenceHttpRequestError {
+export class InferenceClientHubApiError extends InferenceClientHttpRequestError {
 	constructor(message: string, httpRequest: HttpRequest, httpResponse: HttpResponse) {
 		super(message, httpRequest, httpResponse);
 		this.name = "HubApiError";
@@ -74,7 +74,7 @@ export class HfInferenceHubApiError extends HfInferenceHttpRequestError {
 /**
  * Thrown when the inference output returned by the provider is invalid / does not match the expectations
  */
-export class HfInferenceProviderOutputError extends HfInferenceError {
+export class InferenceClientProviderOutputError extends InferenceClientError {
 	constructor(message: string) {
 		super(message);
 		this.name = "ProviderOutputError";

packages/inference/src/lib/getInferenceProviderMapping.ts

@@ -4,7 +4,7 @@ import { HARDCODED_MODEL_INFERENCE_MAPPING } from "../providers/consts.js";
 import { EQUIVALENT_SENTENCE_TRANSFORMERS_TASKS } from "../providers/hf-inference.js";
 import type { InferenceProvider, InferenceProviderOrPolicy, ModelId } from "../types.js";
 import { typedInclude } from "../utils/typedInclude.js";
-import { HfInferenceHubApiError, HfInferenceInputError } from "../error.js";
+import { InferenceClientHubApiError, InferenceClientInputError } from "../error.js";
 
 export const inferenceProviderMappingCache = new Map<ModelId, InferenceProviderMapping>();
 
@@ -41,14 +41,14 @@ export async function fetchInferenceProviderMappingForModel(
 			if (resp.headers.get("Content-Type")?.startsWith("application/json")) {
 				const error = await resp.json();
 				if ("error" in error && typeof error.error === "string") {
-					throw new HfInferenceHubApiError(
+					throw new InferenceClientHubApiError(
 						`Failed to fetch inference provider mapping for model ${modelId}: ${error.error}`,
 						{ url, method: "GET" },
 						{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: error }
 					);
 				}
 			} else {
-				throw new HfInferenceHubApiError(
+				throw new InferenceClientHubApiError(
 					`Failed to fetch inference provider mapping for model ${modelId}`,
 					{ url, method: "GET" },
 					{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
@@ -59,14 +59,14 @@ export async function fetchInferenceProviderMappingForModel(
 		try {
 			payload = await resp.json();
 		} catch {
-			throw new HfInferenceHubApiError(
+			throw new InferenceClientHubApiError(
 				`Failed to fetch inference provider mapping for model ${modelId}: malformed API response, invalid JSON`,
 				{ url, method: "GET" },
 				{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
 			);
 		}
 		if (!payload?.inferenceProviderMapping) {
-			throw new HfInferenceHubApiError(
+			throw new InferenceClientHubApiError(
 				`We have not been able to find inference provider information for model ${modelId}.`,
 				{ url, method: "GET" },
 				{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
@@ -103,7 +103,7 @@ export async function getInferenceProviderMapping(
 				? EQUIVALENT_SENTENCE_TRANSFORMERS_TASKS
 				: [params.task];
 		if (!typedInclude(equivalentTasks, providerMapping.task)) {
-			throw new HfInferenceInputError(
+			throw new InferenceClientInputError(
 				`Model ${params.modelId} is not supported for task ${params.task} and provider ${params.provider}. Supported task: ${providerMapping.task}.`
 			);
 		}
@@ -124,7 +124,7 @@ export async function resolveProvider(
 ): Promise<InferenceProvider> {
 	if (endpointUrl) {
 		if (provider) {
-			throw new HfInferenceInputError("Specifying both endpointUrl and provider is not supported.");
+			throw new InferenceClientInputError("Specifying both endpointUrl and provider is not supported.");
 		}
 		/// Defaulting to hf-inference helpers / API
 		return "hf-inference";
@@ -137,13 +137,13 @@ export async function resolveProvider(
 	}
 	if (provider === "auto") {
 		if (!modelId) {
-			throw new HfInferenceInputError("Specifying a model is required when provider is 'auto'");
+			throw new InferenceClientInputError("Specifying a model is required when provider is 'auto'");
 		}
 		const inferenceProviderMapping = await fetchInferenceProviderMappingForModel(modelId);
 		provider = Object.keys(inferenceProviderMapping)[0] as InferenceProvider | undefined;
 	}
 	if (!provider) {
-		throw new HfInferenceInputError(`No Inference Provider available for model ${modelId}.`);
+		throw new InferenceClientInputError(`No Inference Provider available for model ${modelId}.`);
 	}
 	return provider;
 }

packages/inference/src/lib/getProviderHelper.ts

@@ -48,7 +48,7 @@ import * as Replicate from "../providers/replicate.js";
 import * as Sambanova from "../providers/sambanova.js";
 import * as Together from "../providers/together.js";
 import type { InferenceProvider, InferenceProviderOrPolicy, InferenceTask } from "../types.js";
-import { HfInferenceInputError } from "../error.js";
+import { InferenceClientInputError } from "../error.js";
 
 export const PROVIDERS: Record<InferenceProvider, Partial<Record<InferenceTask, TaskProviderHelper>>> = {
 	"black-forest-labs": {
@@ -282,18 +282,18 @@ export function getProviderHelper(
 		return new HFInference.HFInferenceTask();
 	}
 	if (!task) {
-		throw new HfInferenceInputError(
+		throw new InferenceClientInputError(
 			"you need to provide a task name when using an external provider, e.g. 'text-to-image'"
 		);
 	}
 	if (!(provider in PROVIDERS)) {
-		throw new HfInferenceInputError(
+		throw new InferenceClientInputError(
 			`Provider '${provider}' not supported. Available providers: ${Object.keys(PROVIDERS)}`
 		);
 	}
 	const providerTasks = PROVIDERS[provider];
 	if (!providerTasks || !(task in providerTasks)) {
-		throw new HfInferenceInputError(
+		throw new InferenceClientInputError(
 			`Task '${task}' not supported for provider '${provider}'. Available tasks: ${Object.keys(providerTasks ?? {})}`
 		);
 	}

packages/inference/src/lib/makeRequestOptions.ts

@@ -5,7 +5,7 @@ import type { InferenceProviderModelMapping } from "./getInferenceProviderMappin
 import { getInferenceProviderMapping } from "./getInferenceProviderMapping.js";
 import type { getProviderHelper } from "./getProviderHelper.js";
 import { isUrl } from "./isUrl.js";
-import { HfInferenceHubApiError, HfInferenceInputError } from "../error.js";
+import { InferenceClientHubApiError, InferenceClientInputError } from "../error.js";
 
 /**
  * Lazy-loaded from huggingface.co/api/tasks when needed
@@ -34,10 +34,10 @@ export async function makeRequestOptions(
 
 	// Validate inputs
 	if (args.endpointUrl && provider !== "hf-inference") {
-		throw new HfInferenceInputError(`Cannot use endpointUrl with a third-party provider.`);
+		throw new InferenceClientInputError(`Cannot use endpointUrl with a third-party provider.`);
 	}
 	if (maybeModel && isUrl(maybeModel)) {
-		throw new HfInferenceInputError(`Model URLs are no longer supported. Use endpointUrl instead.`);
+		throw new InferenceClientInputError(`Model URLs are no longer supported. Use endpointUrl instead.`);
 	}
 
 	if (args.endpointUrl) {
@@ -52,14 +52,14 @@ export async function makeRequestOptions(
 	}
 
 	if (!maybeModel && !task) {
-		throw new HfInferenceInputError("No model provided, and no task has been specified.");
+		throw new InferenceClientInputError("No model provided, and no task has been specified.");
 	}
 
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const hfModel = maybeModel ?? (await loadDefaultModel(task!));
 
 	if (providerHelper.clientSideRoutingOnly && !maybeModel) {
-		throw new HfInferenceInputError(`Provider ${provider} requires a model ID to be passed directly.`);
+		throw new InferenceClientInputError(`Provider ${provider} requires a model ID to be passed directly.`);
 	}
 
 	const inferenceProviderMapping = providerHelper.clientSideRoutingOnly
@@ -83,7 +83,7 @@ export async function makeRequestOptions(
 				{ fetch: options?.fetch }
 		  );
 	if (!inferenceProviderMapping) {
-		throw new HfInferenceInputError(
+		throw new InferenceClientInputError(
 			`We have not been able to find inference provider information for model ${hfModel}.`
 		);
 	}
@@ -125,7 +125,7 @@ export function makeRequestOptionsFromResolvedModel(
 		if (providerHelper.clientSideRoutingOnly) {
 			// Closed-source providers require an accessToken (cannot be routed).
 			if (accessToken && accessToken.startsWith("hf_")) {
-				throw new HfInferenceInputError(`Provider ${provider} is closed-source and does not support HF tokens.`);
+				throw new InferenceClientInputError(`Provider ${provider} is closed-source and does not support HF tokens.`);
 			}
 		}
 		if (accessToken) {
@@ -199,7 +199,9 @@ async function loadDefaultModel(task: InferenceTask): Promise<string> {
 	}
 	const taskInfo = tasks[task];
 	if ((taskInfo?.models.length ?? 0) <= 0) {
-		throw new HfInferenceInputError(`No default model defined for task ${task}, please define the model explicitly.`);
+		throw new InferenceClientInputError(
+			`No default model defined for task ${task}, please define the model explicitly.`
+		);
 	}
 	return taskInfo.models[0].id;
 }
@@ -209,7 +211,7 @@ async function loadTaskInfo(): Promise<Record<string, { models: { id: string }[]
 	const res = await fetch(url);
 
 	if (!res.ok) {
-		throw new HfInferenceHubApiError(
+		throw new InferenceClientHubApiError(
 			"Failed to load tasks definitions from Hugging Face Hub.",
 			{ url, method: "GET" },
 			{ requestId: res.headers.get("x-request-id") ?? "", status: res.status, body: await res.text() }
@@ -220,7 +222,7 @@ async function loadTaskInfo(): Promise<Record<string, { models: { id: string }[]
 
 function removeProviderPrefix(model: string, provider: string): string {
 	if (!model.startsWith(`${provider}/`)) {
-		throw new HfInferenceInputError(`Models from ${provider} must be prefixed by "${provider}/". Got "${model}".`);
+		throw new InferenceClientInputError(`Models from ${provider} must be prefixed by "${provider}/". Got "${model}".`);
 	}
 	return model.slice(provider.length + 1);
 }

packages/inference/src/providers/black-forest-labs.ts

@@ -14,7 +14,11 @@
  *
  * Thanks!
  */
-import { HfInferenceInputError, HfInferenceProviderApiError, HfInferenceProviderOutputError } from "../error.js";
+import {
+	InferenceClientInputError,
+	InferenceClientProviderApiError,
+	InferenceClientProviderOutputError,
+} from "../error.js";
 import type { BodyParams, HeaderParams, UrlParams } from "../types.js";
 import { delay } from "../utils/delay.js";
 import { omit } from "../utils/omit.js";
@@ -52,7 +56,7 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 
 	makeRoute(params: UrlParams): string {
 		if (!params) {
-			throw new HfInferenceInputError("Params are required");
+			throw new InferenceClientInputError("Params are required");
 		}
 		return `/v1/${params.model}`;
 	}
@@ -70,7 +74,7 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 			urlObj.searchParams.set("attempt", step.toString(10));
 			const resp = await fetch(urlObj, { headers: { "Content-Type": "application/json" } });
 			if (!resp.ok) {
-				throw new HfInferenceProviderApiError(
+				throw new InferenceClientProviderApiError(
 					"Failed to fetch result from black forest labs API",
 					{ url: urlObj.toString(), method: "GET", headers: { "Content-Type": "application/json" } },
 					{ requestId: resp.headers.get("x-request-id") ?? "", status: resp.status, body: await resp.text() }
@@ -96,7 +100,7 @@ export class BlackForestLabsTextToImageTask extends TaskProviderHelper implement
 				return await image.blob();
 			}
 		}
-		throw new HfInferenceProviderOutputError(
+		throw new InferenceClientProviderOutputError(
 			`Timed out while waiting for the result from black forest labs API - aborting after 5 attempts`
 		);
 	}