@huggingface/inference 2.6.4 → 2.6.6

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@huggingface/inference",
-  "version": "2.6.4",
-  "packageManager": "pnpm@8.3.1",
+  "version": "2.6.6",
+  "packageManager": "pnpm@8.10.5",
   "license": "MIT",
   "author": "Tim Mikeladze <tim.mikeladze@gmail.com>",
-  "description": "Typescript wrapper for the Hugging Face Inference API",
+  "description": "Typescript wrapper for the Hugging Face Inference Endpoints & Inference API",
   "repository": {
     "type": "git",
     "url": "https://github.com/huggingface/huggingface.js.git"
@@ -30,30 +30,28 @@
   ],
   "source": "src/index.ts",
   "types": "./dist/index.d.ts",
-  "main": "./dist/index.js",
-  "module": "./dist/index.mjs",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "exports": {
     "types": "./dist/index.d.ts",
-    "require": "./dist/index.js",
-    "import": "./dist/index.mjs"
+    "require": "./dist/index.cjs",
+    "import": "./dist/index.js"
   },
+  "type": "module",
   "devDependencies": {
     "@types/node": "18.13.0",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.0.4",
-    "vite": "^4.1.4",
-    "vitest": "^0.29.8"
+    "@huggingface/tasks": "^0.6.0"
   },
   "resolutions": {},
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --clean && pnpm run dts",
-    "dts": "ts-node scripts/generate-dts.ts",
+    "dts": "tsx scripts/generate-dts.ts",
     "lint": "eslint --quiet --fix --ext .cjs,.ts .",
     "lint:check": "eslint --ext .cjs,.ts .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "vitest run --config vitest.config.ts",
-    "test:browser": "vitest run --browser.name=chrome --browser.headless --config vitest.config.ts",
-    "type-check": "tsc"
+    "test": "vitest run --config vitest.config.mts",
+    "test:browser": "vitest run --browser.name=chrome --browser.headless --config vitest.config.mts",
+    "check": "tsc"
   }
 }

package/src/lib/getDefaultTask.ts

@@ -2,7 +2,7 @@ import { isUrl } from "./isUrl";
 
 /**
  * We want to make calls to the huggingface hub the least possible, eg if
- * someone is calling the inference API 1000 times per second, we don't want
+ * someone is calling Inference Endpoints 1000 times per second, we don't want
  * to make 1000 calls to the hub to get the task name.
  */
 const taskCache = new Map<string, { task: string; date: Date }>();

package/src/lib/makeRequestOptions.ts

@@ -27,7 +27,15 @@ export async function makeRequestOptions(
 	// eslint-disable-next-line @typescript-eslint/no-unused-vars
 	const { accessToken, model: _model, ...otherArgs } = args;
 	let { model } = args;
-	const { forceTask: task, includeCredentials, taskHint, ...otherOptions } = options ?? {};
+	const {
+		forceTask: task,
+		includeCredentials,
+		taskHint,
+		wait_for_model,
+		use_cache,
+		dont_load_model,
+		...otherOptions
+	} = options ?? {};
 
 	const headers: Record<string, string> = {};
 	if (accessToken) {
@@ -57,16 +65,16 @@ export async function makeRequestOptions(
 
 	if (!binary) {
 		headers["Content-Type"] = "application/json";
-	} else {
-		if (options?.wait_for_model) {
-			headers["X-Wait-For-Model"] = "true";
-		}
-		if (options?.use_cache === false) {
-			headers["X-Use-Cache"] = "false";
-		}
-		if (options?.dont_load_model) {
-			headers["X-Load-Model"] = "0";
-		}
+	}
+
+	if (wait_for_model) {
+		headers["X-Wait-For-Model"] = "true";
+	}
+	if (use_cache === false) {
+		headers["X-Use-Cache"] = "false";
+	}
+	if (dont_load_model) {
+		headers["X-Load-Model"] = "0";
 	}
 
 	const url = (() => {

package/src/tasks/custom/request.ts

@@ -2,7 +2,7 @@ import type { InferenceTask, Options, RequestArgs } from "../../types";
 import { makeRequestOptions } from "../../lib/makeRequestOptions";
 
 /**
- * Primitive to make custom calls to the inference API
+ * Primitive to make custom calls to Inference Endpoints
  */
 export async function request<T>(
 	args: RequestArgs,

package/src/tasks/custom/streamingRequest.ts

@@ -19,7 +19,7 @@ export async function* streamingRequest<T>(
 	const response = await (options?.fetch ?? fetch)(url, info);
 
 	if (options?.retry_on_error !== false && response.status === 503 && !options?.wait_for_model) {
-		return streamingRequest(args, {
+		return yield* streamingRequest(args, {
 			...options,
 			wait_for_model: true,
 		});

package/src/tasks/index.ts

@@ -18,7 +18,6 @@ export * from "./cv/imageToImage";
 export * from "./cv/zeroShotImageClassification";
 
 // Natural Language Processing tasks
-export * from "./nlp/conversational";
 export * from "./nlp/featureExtraction";
 export * from "./nlp/fillMask";
 export * from "./nlp/questionAnswering";

package/src/tasks/nlp/textGeneration.ts

@@ -1,71 +1,15 @@
+import type { TextGenerationInput, TextGenerationOutput } from "@huggingface/tasks/src/tasks/text-generation/inference";
 import { InferenceOutputError } from "../../lib/InferenceOutputError";
 import type { BaseArgs, Options } from "../../types";
 import { request } from "../custom/request";
 
-export type TextGenerationArgs = BaseArgs & {
-	/**
-	 * A string to be generated from
-	 */
-	inputs: string;
-	parameters?: {
-		/**
-		 * (Optional: True). Bool. Whether or not to use sampling, use greedy decoding otherwise.
-		 */
-		do_sample?: boolean;
-		/**
-		 * (Default: None). Int (0-250). The amount of new tokens to be generated, this does not include the input length it is a estimate of the size of generated text you want. Each new tokens slows down the request, so look for balance between response times and length of text generated.
-		 */
-		max_new_tokens?: number;
-		/**
-		 * (Default: None). Float (0-120.0). The amount of time in seconds that the query should take maximum. Network can cause some overhead so it will be a soft limit. Use that in combination with max_new_tokens for best results.
-		 */
-		max_time?: number;
-		/**
-		 * (Default: 1). Integer. The number of proposition you want to be returned.
-		 */
-		num_return_sequences?: number;
-		/**
-		 * (Default: None). Float (0.0-100.0). The more a token is used within generation the more it is penalized to not be picked in successive generation passes.
-		 */
-		repetition_penalty?: number;
-		/**
-		 * (Default: True). Bool. If set to False, the return results will not contain the original query making it easier for prompting.
-		 */
-		return_full_text?: boolean;
-		/**
-		 * (Default: 1.0). Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability.
-		 */
-		temperature?: number;
-		/**
-		 * (Default: None). Integer to define the top tokens considered within the sample operation to create new text.
-		 */
-		top_k?: number;
-		/**
-		 * (Default: None). Float to define the tokens that are within the sample operation of text generation. Add tokens in the sample for more probable to least probable until the sum of the probabilities is greater than top_p.
-		 */
-		top_p?: number;
-		/**
-		 * (Default: None). Integer. The maximum number of tokens from the input.
-		 */
-		truncate?: number;
-		/**
-		 * (Default: []) List of strings. The model will stop generating text when one of the strings in the list is generated.
-		 * **/
-		stop_sequences?: string[];
-	};
-};
-
-export interface TextGenerationOutput {
-	/**
-	 * The continuated string
-	 */
-	generated_text: string;
-}
-
 /**
  * Use to continue text from a prompt. This is a very generic task. Recommended model: gpt2 (it’s a simple model, but fun to play with).
  */
-export async function textGeneration(args: TextGenerationArgs, options?: Options): Promise<TextGenerationOutput> {
+export async function textGeneration(
+	args: BaseArgs & TextGenerationInput,
+	options?: Options
+): Promise<TextGenerationOutput> {
 	const res = await request<TextGenerationOutput[]>(args, {
 		...options,
 		taskHint: "text-generation",

package/src/tasks/nlp/textGenerationStream.ts

@@ -1,6 +1,7 @@
-import type { Options } from "../../types";
+import type { BaseArgs, Options } from "../../types";
 import { streamingRequest } from "../custom/streamingRequest";
-import type { TextGenerationArgs } from "./textGeneration";
+
+import type { TextGenerationInput } from "@huggingface/tasks/src/tasks/text-generation/inference";
 
 export interface TextGenerationStreamToken {
 	/** Token ID from the model tokenizer */
@@ -85,7 +86,7 @@ export interface TextGenerationStreamOutput {
  * Use to continue text from a prompt. Same as `textGeneration` but returns generator that can be read one token at a time
  */
 export async function* textGenerationStream(
-	args: TextGenerationArgs,
+	args: BaseArgs & TextGenerationInput,
 	options?: Options
 ): AsyncGenerator<TextGenerationStreamOutput> {
 	yield* streamingRequest<TextGenerationStreamOutput>(args, {

package/src/tasks/nlp/translation.ts

@@ -6,21 +6,23 @@ export type TranslationArgs = BaseArgs & {
 	/**
 	 * A string to be translated
 	 */
-	inputs: string;
+	inputs: string | string[];
 };
 
-export interface TranslationOutput {
+export interface TranslationOutputValue {
 	/**
 	 * The string after translation
 	 */
 	translation_text: string;
 }
 
+export type TranslationOutput = TranslationOutputValue | TranslationOutputValue[];
+
 /**
  * This task is well known to translate text from one language to another. Recommended model: Helsinki-NLP/opus-mt-ru-en.
  */
 export async function translation(args: TranslationArgs, options?: Options): Promise<TranslationOutput> {
-	const res = await request<TranslationOutput[]>(args, {
+	const res = await request<TranslationOutputValue[]>(args, {
 		...options,
 		taskHint: "translation",
 	});
@@ -28,5 +30,5 @@ export async function translation(args: TranslationArgs, options?: Options): Pro
 	if (!isValidOutput) {
 		throw new InferenceOutputError("Expected type Array<{translation_text: string}>");
 	}
-	return res?.[0];
+	return res?.length === 1 ? res?.[0] : res;
 }

package/src/types.ts

@@ -1,10 +1,12 @@
+import type { PipelineType } from "@huggingface/tasks";
+
 export interface Options {
 	/**
 	 * (Default: true) Boolean. If a request 503s and wait_for_model is set to false, the request will be retried with the same parameters but with wait_for_model set to true.
 	 */
 	retry_on_error?: boolean;
 	/**
-	 * (Default: true). Boolean. There is a cache layer on the inference API to speedup requests we have already seen. Most models can use those results as is as models are deterministic (meaning the results will be the same anyway). However if you use a non deterministic model, you can set this parameter to prevent the caching mechanism from being used resulting in a real new query.
+	 * (Default: true). Boolean. There is a cache layer on Inference API (serverless) to speedup requests we have already seen. Most models can use those results as is as models are deterministic (meaning the results will be the same anyway). However if you use a non deterministic model, you can set this parameter to prevent the caching mechanism from being used resulting in a real new query.
 	 */
 	use_cache?: boolean;
 	/**
@@ -35,39 +37,7 @@ export interface Options {
 	includeCredentials?: string | boolean;
 }
 
-export type InferenceTask =
-	| "audio-classification"
-	| "audio-to-audio"
-	| "automatic-speech-recognition"
-	| "conversational"
-	| "depth-estimation"
-	| "document-question-answering"
-	| "feature-extraction"
-	| "fill-mask"
-	| "image-classification"
-	| "image-segmentation"
-	| "image-to-image"
-	| "image-to-text"
-	| "object-detection"
-	| "video-classification"
-	| "question-answering"
-	| "reinforcement-learning"
-	| "sentence-similarity"
-	| "summarization"
-	| "table-question-answering"
-	| "tabular-classification"
-	| "tabular-regression"
-	| "text-classification"
-	| "text-generation"
-	| "text-to-image"
-	| "text-to-speech"
-	| "text-to-video"
-	| "token-classification"
-	| "translation"
-	| "unconditional-image-generation"
-	| "visual-question-answering"
-	| "zero-shot-classification"
-	| "zero-shot-image-classification";
+export type InferenceTask = Exclude<PipelineType, "other">;
 
 export interface BaseArgs {
 	/**
@@ -77,7 +47,7 @@ export interface BaseArgs {
 	 */
 	accessToken?: string;
 	/**
-	 * The model to use. Can be a full URL for HF inference endpoints.
+	 * The model to use. Can be a full URL for a dedicated inference endpoint.
 	 *
 	 * If not specified, will call huggingface.co/api/tasks to get the default model for the task.
 	 */

package/src/tasks/nlp/conversational.ts

@@ -1,81 +0,0 @@
-import { InferenceOutputError } from "../../lib/InferenceOutputError";
-import type { BaseArgs, Options } from "../../types";
-import { request } from "../custom/request";
-
-export type ConversationalArgs = BaseArgs & {
-	inputs: {
-		/**
-		 * A list of strings corresponding to the earlier replies from the model.
-		 */
-		generated_responses?: string[];
-		/**
-		 * A list of strings corresponding to the earlier replies from the user. Should be of the same length of generated_responses.
-		 */
-		past_user_inputs?: string[];
-		/**
-		 * The last input from the user in the conversation.
-		 */
-		text: string;
-	};
-	parameters?: {
-		/**
-		 * (Default: None). Integer to define the maximum length in tokens of the output summary.
-		 */
-		max_length?: number;
-		/**
-		 * (Default: None). Float (0-120.0). The amount of time in seconds that the query should take maximum. Network can cause some overhead so it will be a soft limit.
-		 */
-		max_time?: number;
-		/**
-		 * (Default: None). Integer to define the minimum length in tokens of the output summary.
-		 */
-		min_length?: number;
-		/**
-		 * (Default: None). Float (0.0-100.0). The more a token is used within generation the more it is penalized to not be picked in successive generation passes.
-		 */
-		repetition_penalty?: number;
-		/**
-		 * (Default: 1.0). Float (0.0-100.0). The temperature of the sampling operation. 1 means regular sampling, 0 means always take the highest score, 100.0 is getting closer to uniform probability.
-		 */
-		temperature?: number;
-		/**
-		 * (Default: None). Integer to define the top tokens considered within the sample operation to create new text.
-		 */
-		top_k?: number;
-		/**
-		 * (Default: None). Float to define the tokens that are within the sample operation of text generation. Add tokens in the sample for more probable to least probable until the sum of the probabilities is greater than top_p.
-		 */
-		top_p?: number;
-	};
-};
-
-export interface ConversationalOutput {
-	conversation: {
-		generated_responses: string[];
-		past_user_inputs: string[];
-	};
-	generated_text: string;
-	warnings: string[];
-}
-
-/**
- * This task corresponds to any chatbot like structure. Models tend to have shorter max_length, so please check with caution when using a given model if you need long range dependency or not. Recommended model: microsoft/DialoGPT-large.
- *
- */
-export async function conversational(args: ConversationalArgs, options?: Options): Promise<ConversationalOutput> {
-	const res = await request<ConversationalOutput>(args, { ...options, taskHint: "conversational" });
-	const isValidOutput =
-		Array.isArray(res.conversation.generated_responses) &&
-		res.conversation.generated_responses.every((x) => typeof x === "string") &&
-		Array.isArray(res.conversation.past_user_inputs) &&
-		res.conversation.past_user_inputs.every((x) => typeof x === "string") &&
-		typeof res.generated_text === "string" &&
-		(typeof res.warnings === "undefined" ||
-			(Array.isArray(res.warnings) && res.warnings.every((x) => typeof x === "string")));
-	if (!isValidOutput) {
-		throw new InferenceOutputError(
-			"Expected {conversation: {generated_responses: string[], past_user_inputs: string[]}, generated_text: string, warnings: string[]}"
-		);
-	}
-	return res;
-}