[Inference] top-down injection of providerHelper (#1350)

cc @hanouticelina @Wauplin 

Prompted by:
https://huggingface.slack.com/archives/C02EMARJ65P/p1744370608755449
(internal)

This PR reduces the number of places where we call `getProviderHelper`
by enforcing it's passed as an argument by the caller when needed

Because `getProviderHelper` is fallible, calling it from different
places (sometimes deep in the function call chain) can be dangerous and
result in unexpected bugs.

This PR reduces this risk by reducing the number of different places
where we call `getProviderHelper` , and instead pass it as an argument
top-down

It also has the benefits of clearly indicating which functions depend on
provider-specific logic

---------

Co-authored-by: Celina Hanouti <[email protected]>

Author: SBrandeis

packages/inference/src/lib/makeRequestOptions.ts

@@ -1,7 +1,7 @@
 import { name as packageName, version as packageVersion } from "../../package.json";
 import { HF_HEADER_X_BILL_TO, HF_HUB_URL } from "../config";
 import type { InferenceTask, Options, RequestArgs } from "../types";
-import { getProviderHelper } from "./getProviderHelper";
+import type { getProviderHelper } from "./getProviderHelper";
 import { getProviderModelId } from "./getProviderModelId";
 import { isUrl } from "./isUrl";
 
@@ -20,6 +20,7 @@ export async function makeRequestOptions(
 		data?: Blob | ArrayBuffer;
 		stream?: boolean;
 	},
+	providerHelper: ReturnType<typeof getProviderHelper>,
 	options?: Options & {
 		/** In most cases (unless we pass a endpointUrl) we know the task */
 		task?: InferenceTask;
@@ -28,6 +29,7 @@ export async function makeRequestOptions(
 	const { provider: maybeProvider, model: maybeModel } = args;
 	const provider = maybeProvider ?? "hf-inference";
 	const { task } = options ?? {};
+
 	// Validate inputs
 	if (args.endpointUrl && provider !== "hf-inference") {
 		throw new Error(`Cannot use endpointUrl with a third-party provider.`);
@@ -38,7 +40,7 @@ export async function makeRequestOptions(
 
 	if (args.endpointUrl) {
 		// No need to have maybeModel, or to load default model for a task
-		return makeRequestOptionsFromResolvedModel(maybeModel ?? args.endpointUrl, args, options);
+		return makeRequestOptionsFromResolvedModel(maybeModel ?? args.endpointUrl, providerHelper, args, options);
 	}
 
 	if (!maybeModel && !task) {
@@ -47,7 +49,6 @@ export async function makeRequestOptions(
 
 	// eslint-disable-next-line @typescript-eslint/no-non-null-assertion
 	const hfModel = maybeModel ?? (await loadDefaultModel(task!));
-	const providerHelper = getProviderHelper(provider, task);
 
 	if (providerHelper.clientSideRoutingOnly && !maybeModel) {
 		throw new Error(`Provider ${provider} requires a model ID to be passed directly.`);
@@ -62,7 +63,7 @@ export async function makeRequestOptions(
 		  });
 
 	// Use the sync version with the resolved model
-	return makeRequestOptionsFromResolvedModel(resolvedModel, args, options);
+	return makeRequestOptionsFromResolvedModel(resolvedModel, providerHelper, args, options);
 }
 
 /**
@@ -71,6 +72,7 @@ export async function makeRequestOptions(
  */
 export function makeRequestOptionsFromResolvedModel(
 	resolvedModel: string,
+	providerHelper: ReturnType<typeof getProviderHelper>,
 	args: RequestArgs & {
 		data?: Blob | ArrayBuffer;
 		stream?: boolean;
@@ -85,7 +87,6 @@ export function makeRequestOptionsFromResolvedModel(
 	const provider = maybeProvider ?? "hf-inference";
 
 	const { includeCredentials, task, signal, billTo } = options ?? {};
-	const providerHelper = getProviderHelper(provider, task);
 	const authMethod = (() => {
 		if (providerHelper.clientSideRoutingOnly) {
 			// Closed-source providers require an accessToken (cannot be routed).

packages/inference/src/providers/hf-inference.ts

@@ -385,13 +385,13 @@ export class HFInferenceQuestionAnsweringTask extends HFInferenceTask implements
 							typeof elem.end === "number" &&
 							typeof elem.score === "number" &&
 							typeof elem.start === "number"
-					)
+				  )
 				: typeof response === "object" &&
-					!!response &&
-					typeof response.answer === "string" &&
-					typeof response.end === "number" &&
-					typeof response.score === "number" &&
-					typeof response.start === "number"
+				  !!response &&
+				  typeof response.answer === "string" &&
+				  typeof response.end === "number" &&
+				  typeof response.score === "number" &&
+				  typeof response.start === "number"
 		) {
 			return Array.isArray(response) ? response[0] : response;
 		}

packages/inference/src/snippets/getInferenceSnippets.ts

@@ -11,6 +11,7 @@ import type { ChatCompletionInputMessage, GenerationParameters } from "@huggingf
 import { makeRequestOptionsFromResolvedModel } from "../lib/makeRequestOptions";
 import type { InferenceProvider, InferenceTask, RequestArgs } from "../types";
 import { templates } from "./templates.exported";
+import { getProviderHelper } from "../lib/getProviderHelper";
 
 const PYTHON_CLIENTS = ["huggingface_hub", "fal_client", "requests", "openai"] as const;
 const JS_CLIENTS = ["fetch", "huggingface.js", "openai"] as const;
@@ -130,10 +131,18 @@ const snippetGenerator = (templateName: string, inputPreparationFn?: InputPrepar
 			inputPreparationFn = prepareConversationalInput;
 			task = "conversational";
 		}
+		let providerHelper: ReturnType<typeof getProviderHelper>;
+		try {
+			providerHelper = getProviderHelper(provider, task);
+		} catch (e) {
+			console.error(`Failed to get provider helper for ${provider} (${task})`, e);
+			return [];
+		}
 		/// Prepare inputs + make request
 		const inputs = inputPreparationFn ? inputPreparationFn(model, opts) : { inputs: getModelInputSnippet(model) };
 		const request = makeRequestOptionsFromResolvedModel(
 			providerModelId ?? model.id,
+			providerHelper,
 			{
 				accessToken: accessToken,
 				provider: provider,

packages/inference/src/tasks/audio/audioClassification.ts

@@ -17,7 +17,7 @@ export async function audioClassification(
 ): Promise<AudioClassificationOutput> {
 	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", "audio-classification");
 	const payload = preparePayload(args);
-	const { data: res } = await innerRequest<AudioClassificationOutput>(payload, {
+	const { data: res } = await innerRequest<AudioClassificationOutput>(payload, providerHelper, {
 		...options,
 		task: "audio-classification",
 	});

packages/inference/src/tasks/audio/audioToAudio.ts

@@ -38,7 +38,7 @@ export interface AudioToAudioOutput {
 export async function audioToAudio(args: AudioToAudioArgs, options?: Options): Promise<AudioToAudioOutput[]> {
 	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", "audio-to-audio");
 	const payload = preparePayload(args);
-	const { data: res } = await innerRequest<AudioToAudioOutput>(payload, {
+	const { data: res } = await innerRequest<AudioToAudioOutput>(payload, providerHelper, {
 		...options,
 		task: "audio-to-audio",
 	});

packages/inference/src/tasks/audio/automaticSpeechRecognition.ts

@@ -20,7 +20,7 @@ export async function automaticSpeechRecognition(
 ): Promise<AutomaticSpeechRecognitionOutput> {
 	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", "automatic-speech-recognition");
 	const payload = await buildPayload(args);
-	const { data: res } = await innerRequest<AutomaticSpeechRecognitionOutput>(payload, {
+	const { data: res } = await innerRequest<AutomaticSpeechRecognitionOutput>(payload, providerHelper, {
 		...options,
 		task: "automatic-speech-recognition",
 	});

packages/inference/src/tasks/audio/textToSpeech.ts

@@ -14,7 +14,7 @@ interface OutputUrlTextToSpeechGeneration {
 export async function textToSpeech(args: TextToSpeechArgs, options?: Options): Promise<Blob> {
 	const provider = args.provider ?? "hf-inference";
 	const providerHelper = getProviderHelper(provider, "text-to-speech");
-	const { data: res } = await innerRequest<Blob | OutputUrlTextToSpeechGeneration>(args, {
+	const { data: res } = await innerRequest<Blob | OutputUrlTextToSpeechGeneration>(args, providerHelper, {
 		...options,
 		task: "text-to-speech",
 	});

packages/inference/src/tasks/custom/request.ts

@@ -1,3 +1,4 @@
+import { getProviderHelper } from "../../lib/getProviderHelper";
 import type { InferenceTask, Options, RequestArgs } from "../../types";
 import { innerRequest } from "../../utils/request";
 
@@ -15,6 +16,7 @@ export async function request<T>(
 	console.warn(
 		"The request method is deprecated and will be removed in a future version of huggingface.js. Use specific task functions instead."
 	);
-	const result = await innerRequest<T>(args, options);
+	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", options?.task);
+	const result = await innerRequest<T>(args, providerHelper, options);
 	return result.data;
 }

packages/inference/src/tasks/custom/streamingRequest.ts

@@ -1,5 +1,7 @@
+import { getProviderHelper } from "../../lib/getProviderHelper";
 import type { InferenceTask, Options, RequestArgs } from "../../types";
 import { innerStreamingRequest } from "../../utils/request";
+
 /**
  * Primitive to make custom inference calls that expect server-sent events, and returns the response through a generator
  * @deprecated Use specific task functions instead. This function will be removed in a future version.
@@ -14,5 +16,6 @@ export async function* streamingRequest<T>(
 	console.warn(
 		"The streamingRequest method is deprecated and will be removed in a future version of huggingface.js. Use specific task functions instead."
 	);
-	yield* innerStreamingRequest(args, options);
+	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", options?.task);
+	yield* innerStreamingRequest(args, providerHelper, options);
 }

packages/inference/src/tasks/cv/imageClassification.ts

@@ -16,7 +16,7 @@ export async function imageClassification(
 ): Promise<ImageClassificationOutput> {
 	const providerHelper = getProviderHelper(args.provider ?? "hf-inference", "image-classification");
 	const payload = preparePayload(args);
-	const { data: res } = await innerRequest<ImageClassificationOutput>(payload, {
+	const { data: res } = await innerRequest<ImageClassificationOutput>(payload, providerHelper, {
 		...options,
 		task: "image-classification",
 	});