@huggingface/inference 3.14.0 → 4.0.0

package/src/providers/novita.ts

@@ -14,9 +14,10 @@
  *
  * Thanks!
  */
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
 import { isUrl } from "../lib/isUrl.js";
+import type { TextToVideoArgs } from "../tasks/index.js";
 import type { BodyParams, UrlParams } from "../types.js";
+import { delay } from "../utils/delay.js";
 import { omit } from "../utils/omit.js";
 import {
 	BaseConversationalTask,
@@ -24,13 +25,18 @@ import {
 	TaskProviderHelper,
 	type TextToVideoTaskHelper,
 } from "./providerHelper.js";
+import {
+	InferenceClientInputError,
+	InferenceClientProviderApiError,
+	InferenceClientProviderOutputError,
+} from "../errors.js";
 
 const NOVITA_API_BASE_URL = "https://api.novita.ai";
-export interface NovitaOutput {
-	video: {
-		video_url: string;
-	};
+
+export interface NovitaAsyncAPIOutput {
+	task_id: string;
 }
+
 export class NovitaTextGenerationTask extends BaseTextGenerationTask {
 	constructor() {
 		super("novita", NOVITA_API_BASE_URL);
@@ -50,38 +56,112 @@ export class NovitaConversationalTask extends BaseConversationalTask {
 		return "/v3/openai/chat/completions";
 	}
 }
+
 export class NovitaTextToVideoTask extends TaskProviderHelper implements TextToVideoTaskHelper {
 	constructor() {
 		super("novita", NOVITA_API_BASE_URL);
 	}
 
-	makeRoute(params: UrlParams): string {
-		return `/v3/hf/${params.model}`;
+	override makeRoute(params: UrlParams): string {
+		return `/v3/async/${params.model}`;
 	}
 
-	preparePayload(params: BodyParams): Record<string, unknown> {
+	override preparePayload(params: BodyParams<TextToVideoArgs>): Record<string, unknown> {
+		const { num_inference_steps, ...restParameters } = params.args.parameters ?? {};
 		return {
 			...omit(params.args, ["inputs", "parameters"]),
-			...(params.args.parameters as Record<string, unknown>),
+			...restParameters,
+			steps: num_inference_steps,
 			prompt: params.args.inputs,
 		};
 	}
-	override async getResponse(response: NovitaOutput): Promise<Blob> {
-		const isValidOutput =
-			typeof response === "object" &&
-			!!response &&
-			"video" in response &&
-			typeof response.video === "object" &&
-			!!response.video &&
-			"video_url" in response.video &&
-			typeof response.video.video_url === "string" &&
-			isUrl(response.video.video_url);
 
-		if (!isValidOutput) {
-			throw new InferenceOutputError("Expected { video: { video_url: string } }");
+	override async getResponse(
+		response: NovitaAsyncAPIOutput,
+		url?: string,
+		headers?: Record<string, string>
+	): Promise<Blob> {
+		if (!url || !headers) {
+			throw new InferenceClientInputError("URL and headers are required for text-to-video task");
+		}
+		const taskId = response.task_id;
+		if (!taskId) {
+			throw new InferenceClientProviderOutputError(
+				"Received malformed response from Novita text-to-video API: no task ID found in the response"
+			);
+		}
+
+		const parsedUrl = new URL(url);
+		const baseUrl = `${parsedUrl.protocol}//${parsedUrl.host}${
+			parsedUrl.host === "router.huggingface.co" ? "/novita" : ""
+		}`;
+		const resultUrl = `${baseUrl}/v3/async/task-result?task_id=${taskId}`;
+
+		let status = "";
+		let taskResult: unknown;
+
+		while (status !== "TASK_STATUS_SUCCEED" && status !== "TASK_STATUS_FAILED") {
+			await delay(500);
+			const resultResponse = await fetch(resultUrl, { headers });
+			if (!resultResponse.ok) {
+				throw new InferenceClientProviderApiError(
+					"Failed to fetch task result",
+					{ url: resultUrl, method: "GET", headers },
+					{
+						requestId: resultResponse.headers.get("x-request-id") ?? "",
+						status: resultResponse.status,
+						body: await resultResponse.text(),
+					}
+				);
+			}
+			try {
+				taskResult = await resultResponse.json();
+				if (
+					taskResult &&
+					typeof taskResult === "object" &&
+					"task" in taskResult &&
+					taskResult.task &&
+					typeof taskResult.task === "object" &&
+					"status" in taskResult.task &&
+					typeof taskResult.task.status === "string"
+				) {
+					status = taskResult.task.status;
+				} else {
+					throw new InferenceClientProviderOutputError(
+						"Received malformed response from Novita text-to-video API: failed to get task status"
+					);
+				}
+			} catch (error) {
+				throw new InferenceClientProviderOutputError(
+					"Received malformed response from Novita text-to-video API: failed to parse task result"
+				);
+			}
 		}
 
-		const urlResponse = await fetch(response.video.video_url);
-		return await urlResponse.blob();
+		if (status === "TASK_STATUS_FAILED") {
+			throw new InferenceClientProviderOutputError("Novita text-to-video task failed");
+		}
+
+		if (
+			typeof taskResult === "object" &&
+			!!taskResult &&
+			"videos" in taskResult &&
+			typeof taskResult.videos === "object" &&
+			!!taskResult.videos &&
+			Array.isArray(taskResult.videos) &&
+			taskResult.videos.length > 0 &&
+			"video_url" in taskResult.videos[0] &&
+			typeof taskResult.videos[0].video_url === "string" &&
+			isUrl(taskResult.videos[0].video_url)
+		) {
+			const urlResponse = await fetch(taskResult.videos[0].video_url);
+			return await urlResponse.blob();
+		} else {
+			throw new InferenceClientProviderOutputError(
+				`Received malformed response from Novita text-to-video API: expected { videos: [{ video_url: string }] } format, got instead: ${JSON.stringify(
+					taskResult
+				)}`
+			);
+		}
 	}
 }

package/src/providers/nscale.ts

@@ -15,10 +15,10 @@
  * Thanks!
  */
 import type { TextToImageInput } from "@huggingface/tasks";
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
 import type { BodyParams } from "../types.js";
 import { omit } from "../utils/omit.js";
 import { BaseConversationalTask, TaskProviderHelper, type TextToImageTaskHelper } from "./providerHelper.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 
 const NSCALE_API_BASE_URL = "https://inference.api.nscale.com";
 
@@ -74,6 +74,6 @@ export class NscaleTextToImageTask extends TaskProviderHelper implements TextToI
 			return fetch(`data:image/jpeg;base64,${base64Data}`).then((res) => res.blob());
 		}
 
-		throw new InferenceOutputError("Expected Nscale text-to-image response format");
+		throw new InferenceClientProviderOutputError("Received malformed response from Nscale text-to-image API");
 	}
 }

package/src/providers/ovhcloud.ts

@@ -17,10 +17,10 @@
 
 import { BaseConversationalTask, BaseTextGenerationTask } from "./providerHelper.js";
 import type { ChatCompletionOutput, TextGenerationOutput, TextGenerationOutputFinishReason } from "@huggingface/tasks";
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
 import type { BodyParams } from "../types.js";
 import { omit } from "../utils/omit.js";
 import type { TextGenerationInput } from "@huggingface/tasks";
+import { InferenceClientProviderOutputError } from "../errors.js";
 
 const OVHCLOUD_API_BASE_URL = "https://oai.endpoints.kepler.ai.cloud.ovh.net";
 
@@ -70,6 +70,6 @@ export class OvhCloudTextGenerationTask extends BaseTextGenerationTask {
 				generated_text: completion.text,
 			};
 		}
-		throw new InferenceOutputError("Expected OVHcloud text generation response format");
+		throw new InferenceClientProviderOutputError("Received malformed response from OVHcloud text generation API");
 	}
 }

package/src/providers/providerHelper.ts

@@ -46,7 +46,7 @@ import type {
 	ZeroShotImageClassificationOutput,
 } from "@huggingface/tasks";
 import { HF_ROUTER_URL } from "../config.js";
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 import type { AudioToAudioOutput } from "../tasks/audio/audioToAudio.js";
 import type { BaseArgs, BodyParams, HeaderParams, InferenceProvider, RequestArgs, UrlParams } from "../types.js";
 import { toArray } from "../utils/toArray.js";
@@ -320,7 +320,7 @@ export class BaseConversationalTask extends TaskProviderHelper implements Conver
 			return response;
 		}
 
-		throw new InferenceOutputError("Expected ChatCompletionOutput");
+		throw new InferenceClientProviderOutputError("Expected ChatCompletionOutput");
 	}
 }
 
@@ -353,6 +353,6 @@ export class BaseTextGenerationTask extends TaskProviderHelper implements TextGe
 			return res[0];
 		}
 
-		throw new InferenceOutputError("Expected Array<{generated_text: string}>");
+		throw new InferenceClientProviderOutputError("Expected Array<{generated_text: string}>");
 	}
 }

package/src/providers/replicate.ts

@@ -14,7 +14,7 @@
  *
  * Thanks!
  */
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 import { isUrl } from "../lib/isUrl.js";
 import type { BodyParams, HeaderParams, UrlParams } from "../types.js";
 import { omit } from "../utils/omit.js";
@@ -99,7 +99,7 @@ export class ReplicateTextToImageTask extends ReplicateTask implements TextToIma
 			return await urlResponse.blob();
 		}
 
-		throw new InferenceOutputError("Expected Replicate text-to-image response format");
+		throw new InferenceClientProviderOutputError("Received malformed response from Replicate text-to-image API");
 	}
 }
 
@@ -132,7 +132,7 @@ export class ReplicateTextToSpeechTask extends ReplicateTask {
 				}
 			}
 		}
-		throw new InferenceOutputError("Expected Blob or object with output");
+		throw new InferenceClientProviderOutputError("Received malformed response from Replicate text-to-speech API");
 	}
 }
 
@@ -149,6 +149,6 @@ export class ReplicateTextToVideoTask extends ReplicateTask implements TextToVid
 			return await urlResponse.blob();
 		}
 
-		throw new InferenceOutputError("Expected { output: string }");
+		throw new InferenceClientProviderOutputError("Received malformed response from Replicate text-to-video API");
 	}
 }

package/src/providers/sambanova.ts

@@ -14,12 +14,11 @@
  *
  * Thanks!
  */
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
-
 import type { FeatureExtractionOutput } from "@huggingface/tasks";
 import type { BodyParams } from "../types.js";
 import type { FeatureExtractionTaskHelper } from "./providerHelper.js";
 import { BaseConversationalTask, TaskProviderHelper } from "./providerHelper.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 
 export class SambanovaConversationalTask extends BaseConversationalTask {
 	constructor() {
@@ -40,8 +39,8 @@ export class SambanovaFeatureExtractionTask extends TaskProviderHelper implement
 		if (typeof response === "object" && "data" in response && Array.isArray(response.data)) {
 			return response.data.map((item) => item.embedding);
 		}
-		throw new InferenceOutputError(
-			"Expected Sambanova feature-extraction (embeddings) response format to be {'data' : list of {'embedding' : number[]}}"
+		throw new InferenceClientProviderOutputError(
+			"Received malformed response from Sambanova feature-extraction (embeddings) API"
 		);
 	}
 

package/src/providers/together.ts

@@ -15,7 +15,6 @@
  * Thanks!
  */
 import type { ChatCompletionOutput, TextGenerationOutput, TextGenerationOutputFinishReason } from "@huggingface/tasks";
-import { InferenceOutputError } from "../lib/InferenceOutputError.js";
 import type { BodyParams } from "../types.js";
 import { omit } from "../utils/omit.js";
 import {
@@ -24,6 +23,7 @@ import {
 	TaskProviderHelper,
 	type TextToImageTaskHelper,
 } from "./providerHelper.js";
+import { InferenceClientProviderOutputError } from "../errors.js";
 
 const TOGETHER_API_BASE_URL = "https://api.together.xyz";
 
@@ -74,7 +74,7 @@ export class TogetherTextGenerationTask extends BaseTextGenerationTask {
 				generated_text: completion.text,
 			};
 		}
-		throw new InferenceOutputError("Expected Together text generation response format");
+		throw new InferenceClientProviderOutputError("Received malformed response from Together text generation API");
 	}
 }
 
@@ -113,6 +113,6 @@ export class TogetherTextToImageTask extends TaskProviderHelper implements TextT
 			return fetch(`data:image/jpeg;base64,${base64Data}`).then((res) => res.blob());
 		}
 
-		throw new InferenceOutputError("Expected Together text-to-image response format");
+		throw new InferenceClientProviderOutputError("Received malformed response from Together text-to-image API");
 	}
 }

package/src/tasks/audio/automaticSpeechRecognition.ts

@@ -1,10 +1,10 @@
 import type { AutomaticSpeechRecognitionInput, AutomaticSpeechRecognitionOutput } from "@huggingface/tasks";
 import { resolveProvider } from "../../lib/getInferenceProviderMapping.js";
 import { getProviderHelper } from "../../lib/getProviderHelper.js";
-import { InferenceOutputError } from "../../lib/InferenceOutputError.js";
 import type { BaseArgs, Options } from "../../types.js";
 import { innerRequest } from "../../utils/request.js";
 import type { LegacyAudioInput } from "./utils.js";
+import { InferenceClientProviderOutputError } from "../../errors.js";
 
 export type AutomaticSpeechRecognitionArgs = BaseArgs & (AutomaticSpeechRecognitionInput | LegacyAudioInput);
 /**
@@ -24,7 +24,7 @@ export async function automaticSpeechRecognition(
 	});
 	const isValidOutput = typeof res?.text === "string";
 	if (!isValidOutput) {
-		throw new InferenceOutputError("Expected {text: string}");
+		throw new InferenceClientProviderOutputError("Received malformed response from automatic-speech-recognition API");
 	}
 	return providerHelper.getResponse(res);
 }

package/src/tasks/cv/textToVideo.ts

@@ -3,7 +3,7 @@ import { resolveProvider } from "../../lib/getInferenceProviderMapping.js";
 import { getProviderHelper } from "../../lib/getProviderHelper.js";
 import { makeRequestOptions } from "../../lib/makeRequestOptions.js";
 import type { FalAiQueueOutput } from "../../providers/fal-ai.js";
-import type { NovitaOutput } from "../../providers/novita.js";
+import type { NovitaAsyncAPIOutput } from "../../providers/novita.js";
 import type { ReplicateOutput } from "../../providers/replicate.js";
 import type { BaseArgs, Options } from "../../types.js";
 import { innerRequest } from "../../utils/request.js";
@@ -15,7 +15,7 @@ export type TextToVideoOutput = Blob;
 export async function textToVideo(args: TextToVideoArgs, options?: Options): Promise<TextToVideoOutput> {
 	const provider = await resolveProvider(args.provider, args.model, args.endpointUrl);
 	const providerHelper = getProviderHelper(provider, "text-to-video");
-	const { data: response } = await innerRequest<FalAiQueueOutput | ReplicateOutput | NovitaOutput>(
+	const { data: response } = await innerRequest<FalAiQueueOutput | ReplicateOutput | NovitaAsyncAPIOutput>(
 		args,
 		providerHelper,
 		{

package/src/utils/request.ts

@@ -3,6 +3,8 @@ import { makeRequestOptions } from "../lib/makeRequestOptions.js";
 import type { InferenceTask, Options, RequestArgs } from "../types.js";
 import type { EventSourceMessage } from "../vendor/fetch-event-source/parse.js";
 import { getLines, getMessages } from "../vendor/fetch-event-source/parse.js";
+import { InferenceClientProviderApiError } from "../errors.js";
+import type { JsonObject } from "../vendor/type-fest/basic.js";
 
 export interface ResponseWrapper<T> {
 	data: T;
@@ -12,6 +14,17 @@ export interface ResponseWrapper<T> {
 	};
 }
 
+function requestArgsToJson(args: RequestArgs): JsonObject {
+	// Convert the entire args object to a JSON-serializable format
+	const argsWithData = args as RequestArgs & { data?: Blob | ArrayBuffer };
+	return JSON.parse(
+		JSON.stringify({
+			...argsWithData,
+			data: argsWithData.data ? "[Blob or ArrayBuffer]" : null,
+		})
+	) as JsonObject;
+}
+
 /**
  * Primitive to make custom calls to the inference provider
  */
@@ -39,18 +52,54 @@ export async function innerRequest<T>(
 		if (["application/json", "application/problem+json"].some((ct) => contentType?.startsWith(ct))) {
 			const output = await response.json();
 			if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-				throw new Error(
-					`Server ${args.model} does not seem to support chat completion. Error: ${JSON.stringify(output.error)}`
+				throw new InferenceClientProviderApiError(
+					`Provider ${args.provider} does not seem to support chat completion for model ${
+						args.model
+					} . Error: ${JSON.stringify(output.error)}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
 				);
 			}
-			if (output.error || output.detail) {
-				throw new Error(JSON.stringify(output.error ?? output.detail));
+			if (typeof output.error === "string" || typeof output.detail === "string") {
+				throw new InferenceClientProviderApiError(
+					`Failed to perform inference: ${output.error ?? output.detail}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			} else {
-				throw new Error(output);
+				throw new InferenceClientProviderApiError(
+					`Failed to perform inference: an HTTP error occurred when requesting the provider.`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			}
 		}
 		const message = contentType?.startsWith("text/plain;") ? await response.text() : undefined;
-		throw new Error(message ?? "An error occurred while fetching the blob");
+		throw new InferenceClientProviderApiError(
+			`Failed to perform inference: ${message ?? "an HTTP error occurred when requesting the provider"}`,
+			{
+				url,
+				method: info.method ?? "GET",
+				headers: info.headers as Record<string, string>,
+				body: requestArgsToJson(args),
+			},
+			{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: message ?? "" }
+		);
 	}
 
 	if (response.headers.get("Content-Type")?.startsWith("application/json")) {
@@ -85,26 +134,81 @@ export async function* innerStreamingRequest<T>(
 		if (response.headers.get("Content-Type")?.startsWith("application/json")) {
 			const output = await response.json();
 			if ([400, 422, 404, 500].includes(response.status) && options?.chatCompletion) {
-				throw new Error(`Server ${args.model} does not seem to support chat completion. Error: ${output.error}`);
+				throw new InferenceClientProviderApiError(
+					`Provider ${args.provider} does not seem to support chat completion for model ${
+						args.model
+					} . Error: ${JSON.stringify(output.error)}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			}
 			if (typeof output.error === "string") {
-				throw new Error(output.error);
+				throw new InferenceClientProviderApiError(
+					`Failed to perform inference: ${output.error}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			}
 			if (output.error && "message" in output.error && typeof output.error.message === "string") {
 				/// OpenAI errors
-				throw new Error(output.error.message);
+				throw new InferenceClientProviderApiError(
+					`Failed to perform inference: ${output.error.message}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			}
 			// Sambanova errors
 			if (typeof output.message === "string") {
-				throw new Error(output.message);
+				throw new InferenceClientProviderApiError(
+					`Failed to perform inference: ${output.message}`,
+					{
+						url,
+						method: info.method ?? "GET",
+						headers: info.headers as Record<string, string>,
+						body: requestArgsToJson(args),
+					},
+					{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: output }
+				);
 			}
 		}
 
-		throw new Error(`Server response contains error: ${response.status}`);
+		throw new InferenceClientProviderApiError(
+			`Failed to perform inference: an HTTP error occurred when requesting the provider.`,
+			{
+				url,
+				method: info.method ?? "GET",
+				headers: info.headers as Record<string, string>,
+				body: requestArgsToJson(args),
+			},
+			{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: "" }
+		);
 	}
 	if (!response.headers.get("content-type")?.startsWith("text/event-stream")) {
-		throw new Error(
-			`Server does not support event stream content type, it returned ` + response.headers.get("content-type")
+		throw new InferenceClientProviderApiError(
+			`Failed to perform inference: server does not support event stream content type, it returned ` +
+				response.headers.get("content-type"),
+			{
+				url,
+				method: info.method ?? "GET",
+				headers: info.headers as Record<string, string>,
+				body: requestArgsToJson(args),
+			},
+			{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: "" }
 		);
 	}
 
@@ -151,7 +255,16 @@ export async function* innerStreamingRequest<T>(
 								    typeof data.error.message === "string"
 								  ? data.error.message
 								  : JSON.stringify(data.error);
-						throw new Error(`Error forwarded from backend: ` + errorStr);
+						throw new InferenceClientProviderApiError(
+							`Failed to perform inference: an occurred while streaming the response: ${errorStr}`,
+							{
+								url,
+								method: info.method ?? "GET",
+								headers: info.headers as Record<string, string>,
+								body: requestArgsToJson(args),
+							},
+							{ requestId: response.headers.get("x-request-id") ?? "", status: response.status, body: data }
+						);
 					}
 					yield data as T;
 				}

package/src/vendor/type-fest/basic.ts

@@ -0,0 +1,31 @@
+/**
+Matches a JSON object.
+
+This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category JSON
+*/
+export type JsonObject = { [Key in string]: JsonValue } & { [Key in string]?: JsonValue | undefined };
+
+/**
+Matches a JSON array.
+
+@category JSON
+*/
+export type JsonArray = JsonValue[] | readonly JsonValue[];
+
+/**
+Matches any valid JSON primitive value.
+
+@category JSON
+*/
+export type JsonPrimitive = string | number | boolean | null;
+
+/**
+Matches any valid JSON value.
+
+@see `Jsonify` if you need to transform a type to one that is assignable to `JsonValue`.
+
+@category JSON
+*/
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;