import type { AudioClassificationInput, AudioClassificationOutput, AutomaticSpeechRecognitionInput, AutomaticSpeechRecognitionOutput, ChatCompletionInput, ChatCompletionOutput, DocumentQuestionAnsweringInput, DocumentQuestionAnsweringOutput, FeatureExtractionInput, FeatureExtractionOutput, FillMaskInput, FillMaskOutput, ImageClassificationInput, ImageClassificationOutput, ImageSegmentationInput, ImageSegmentationOutput, ImageToImageInput, ImageToTextInput, ImageToTextOutput, ImageToVideoInput, ImageTextToImageInput, ImageTextToVideoInput, ObjectDetectionInput, ObjectDetectionOutput, QuestionAnsweringInput, QuestionAnsweringOutput, SentenceSimilarityInput, SentenceSimilarityOutput, SummarizationInput, SummarizationOutput, TableQuestionAnsweringInput, TableQuestionAnsweringOutput, TextClassificationOutput, TextGenerationInput, TextGenerationOutput, TextToImageInput, TextToSpeechInput, TextToVideoInput, TokenClassificationInput, TokenClassificationOutput, TranslationInput, TranslationOutput, VisualQuestionAnsweringInput, VisualQuestionAnsweringOutput, ZeroShotClassificationInput, ZeroShotClassificationOutput, ZeroShotImageClassificationInput, ZeroShotImageClassificationOutput, } from "@huggingface/tasks"; import { HF_ROUTER_URL } from "../config.js"; import { InferenceClientProviderOutputError, InferenceClientRoutingError } from "../errors.js"; import type { AudioToAudioArgs, AudioToAudioOutput } from "../tasks/audio/audioToAudio.js"; import type { BaseArgs, BodyParams, HeaderParams, InferenceProvider, OutputType, RequestArgs, UrlParams, } from "../types.js"; import { toArray } from "../utils/toArray.js"; import type { ImageToImageArgs } from "../tasks/cv/imageToImage.js"; import type { AutomaticSpeechRecognitionArgs } from "../tasks/audio/automaticSpeechRecognition.js"; import type { ImageToVideoArgs } from "../tasks/cv/imageToVideo.js"; import type { ImageTextToImageArgs } from "../tasks/cv/imageTextToImage.js"; import type { ImageTextToVideoArgs } from "../tasks/cv/imageTextToVideo.js"; import type { ImageSegmentationArgs } from "../tasks/cv/imageSegmentation.js"; import type { ImageToTextArgs } from "../tasks/cv/imageToText.js"; /** * Base class for task-specific provider helpers */ export abstract class TaskProviderHelper { constructor( readonly provider: InferenceProvider, protected baseUrl: string, readonly clientSideRoutingOnly: boolean = false, ) {} /** * Return the response in the expected format. * Needs to be implemented in the subclasses. */ abstract getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: OutputType, signal?: AbortSignal, ): Promise; /** * Prepare the route for the request * Needs to be implemented in the subclasses. */ abstract makeRoute(params: UrlParams): string; /** * Prepare the payload for the request * Needs to be implemented in the subclasses. */ abstract preparePayload(params: BodyParams): unknown; /** * Prepare the base URL for the request */ makeBaseUrl(params: UrlParams): string { return params.authMethod !== "provider-key" ? `${HF_ROUTER_URL}/${this.provider}` : this.baseUrl; } /** * Prepare the body for the request */ makeBody(params: BodyParams): BodyInit { if ("data" in params.args && !!params.args.data) { return params.args.data as BodyInit; } return JSON.stringify(this.preparePayload(params)); } /** * Prepare the URL for the request */ makeUrl(params: UrlParams): string { const baseUrl = this.makeBaseUrl(params); const route = this.makeRoute(params).replace(/^\/+/, ""); if (params.urlTransform) { return params.urlTransform(`${baseUrl}/${route}`); } return `${baseUrl}/${route}`; } /** * Prepare the headers for the request */ prepareHeaders(params: HeaderParams, isBinary: boolean): Record { const headers: Record = {}; if (params.authMethod !== "none") { headers["Authorization"] = `Bearer ${params.accessToken}`; } if (!isBinary) { headers["Content-Type"] = "application/json"; } return headers; } } // PER-TASK PROVIDER HELPER INTERFACES // CV Tasks export interface TextToImageTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: OutputType, signal?: AbortSignal, ): Promise>; preparePayload(params: BodyParams): Record; } export interface TextToVideoTaskHelper { getResponse( response: unknown, url?: string, headers?: Record, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; } export interface ImageToImageTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; preparePayloadAsync(args: ImageToImageArgs): Promise; } export interface ImageToVideoTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; preparePayloadAsync(args: ImageToVideoArgs): Promise; } export interface ImageTextToImageTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; preparePayloadAsync(args: ImageTextToImageArgs): Promise; } export interface ImageTextToVideoTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; preparePayloadAsync(args: ImageTextToVideoArgs): Promise; } export interface ImageSegmentationTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record | BodyInit; preparePayloadAsync(args: ImageSegmentationArgs): Promise; } export interface ImageClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } export interface ObjectDetectionTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } export interface ImageToTextTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; preparePayloadAsync(args: ImageToTextArgs, signal?: AbortSignal): Promise; } export interface ZeroShotImageClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } // NLP Tasks export interface TextGenerationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface ConversationalTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface TextClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface QuestionAnsweringTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface FillMaskTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface ZeroShotClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface SentenceSimilarityTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface TableQuestionAnsweringTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface TokenClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface TranslationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface SummarizationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } // Audio Tasks export interface TextToSpeechTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record; } export interface TextToAudioTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams & BaseArgs>): Record; } export interface AudioToAudioTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload( params: BodyParams>, ): Record | BodyInit; preparePayloadAsync(args: AudioToAudioArgs): Promise; } export interface AutomaticSpeechRecognitionTaskHelper { getResponse( response: unknown, url?: string, headers?: HeadersInit, outputType?: undefined, signal?: AbortSignal, ): Promise; preparePayload(params: BodyParams): Record | BodyInit; preparePayloadAsync(args: AutomaticSpeechRecognitionArgs): Promise; } export interface AudioClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } // Multimodal Tasks export interface DocumentQuestionAnsweringTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } export interface FeatureExtractionTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record; } export interface VisualQuestionAnsweringTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload(params: BodyParams): Record | BodyInit; } export interface TabularClassificationTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload( params: BodyParams } } & Record>, ): Record | BodyInit; } export interface TabularRegressionTaskHelper { getResponse(response: unknown, url?: string, headers?: HeadersInit): Promise; preparePayload( params: BodyParams } } & Record>, ): Record | BodyInit; } // BASE IMPLEMENTATIONS FOR COMMON PATTERNS export class BaseConversationalTask extends TaskProviderHelper implements ConversationalTaskHelper { constructor(provider: InferenceProvider, baseUrl: string, clientSideRoutingOnly: boolean = false) { super(provider, baseUrl, clientSideRoutingOnly); } makeRoute(): string { return "v1/chat/completions"; } preparePayload(params: BodyParams): Record { return { ...params.args, model: params.model, }; } async getResponse(response: ChatCompletionOutput): Promise { if ( typeof response === "object" && Array.isArray(response?.choices) && typeof response?.created === "number" && typeof response?.id === "string" && typeof response?.model === "string" && /// Some providers (e.g. Together.ai) do not output a system_fingerprint (response.system_fingerprint === undefined || response.system_fingerprint === null || typeof response.system_fingerprint === "string") && typeof response?.usage === "object" ) { return response; } throw new InferenceClientProviderOutputError("Expected ChatCompletionOutput"); } } export class BaseTextGenerationTask extends TaskProviderHelper implements TextGenerationTaskHelper { constructor(provider: InferenceProvider, baseUrl: string, clientSideRoutingOnly: boolean = false) { super(provider, baseUrl, clientSideRoutingOnly); } preparePayload(params: BodyParams): Record { return { ...params.args, model: params.model, }; } makeRoute(): string { return "v1/completions"; } async getResponse(response: unknown): Promise { const res = toArray(response); if ( Array.isArray(res) && res.length > 0 && res.every( (x): x is { generated_text: string } => typeof x === "object" && !!x && "generated_text" in x && typeof x.generated_text === "string", ) ) { return res[0]; } throw new InferenceClientProviderOutputError("Expected Array<{generated_text: string}>"); } } export class AutoRouterConversationalTask extends BaseConversationalTask { constructor() { super("auto" as InferenceProvider, "https://router.huggingface.co"); } override makeBaseUrl(params: UrlParams): string { if (params.authMethod !== "hf-token") { throw new InferenceClientRoutingError("Cannot select auto-router when using non-Hugging Face API key."); } return this.baseUrl; } }