@huggingface/inference 1.5.1 → 1.6.0

package/README.md

@@ -2,7 +2,8 @@
 
 A Typescript powered wrapper for the Hugging Face Inference API. Learn more about the Inference API at [Hugging Face](https://huggingface.co/docs/api-inference/index).
 
-Check out the [full documentation](https://huggingface.co/docs/huggingface.js/inference/README).
+Check out the [full documentation](https://huggingface.co/docs/huggingface.js/inference/README) or try out a live [interactive notebook](https://observablehq.com/@huggingface/hello-huggingface-js-inference).
+
 
 
 ## Install
@@ -17,7 +18,9 @@ pnpm add @huggingface/inference
 
 ## Usage
 
-❗**Important note:** Using an API key is optional to get started (simply provide a random string), however you will be rate limited eventually. Join [Hugging Face](https://huggingface.co/join) and then visit [access tokens](https://huggingface.co/settings/tokens) to generate your API key.
+❗**Important note:** Using an API key is optional to get started, however you will be rate limited eventually. Join [Hugging Face](https://huggingface.co/join) and then visit [access tokens](https://huggingface.co/settings/tokens) to generate your API key for **free**. 
+
+Your API key should be kept private. If you need to protect it in front-end applications, we suggest setting up a proxy server that stores the API key.
 
 ### Basic examples
 
@@ -148,7 +151,7 @@ await hf.textToImage({
 })
 ```
 
-## Supported APIs
+## Supported Tasks
 
 ### Natural Language Processing
 
@@ -183,3 +186,9 @@ await hf.textToImage({
 ```console
 HF_ACCESS_TOKEN="your access token" npm run test
 ```
+
+## Finding appropriate models
+
+We have an informative documentation project called [Tasks](https://huggingface.co/tasks) to list available models for each task and explain how each task works in detail.
+
+It also contain demos, example outputs and other resources should you want to dig more into the ML-side of things.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type Options = {
+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.
      */
@@ -15,10 +15,10 @@ type Options = {
      * (Default: false) Boolean. If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places.
      */
     wait_for_model?: boolean;
-};
-type Args = {
+}
+interface Args {
     model: string;
-};
+}
 type FillMaskArgs = Args & {
     inputs: string;
 };
@@ -76,19 +76,19 @@ type SummarizationArgs = Args & {
         top_p?: number;
     };
 };
-type SummarizationReturn = {
+interface SummarizationReturn {
     /**
      * The string after translation
      */
     summary_text: string;
-};
+}
 type QuestionAnswerArgs = Args & {
     inputs: {
         context: string;
         question: string;
     };
 };
-type QuestionAnswerReturn = {
+interface QuestionAnswerReturn {
     /**
      * A string that’s the answer within the text.
      */
@@ -105,7 +105,7 @@ type QuestionAnswerReturn = {
      * The index (string wise) of the start of the answer within context.
      */
     start: number;
-};
+}
 type TableQuestionAnswerArgs = Args & {
     inputs: {
         /**
@@ -118,7 +118,7 @@ type TableQuestionAnswerArgs = Args & {
         table: Record<string, string[]>;
     };
 };
-type TableQuestionAnswerReturn = {
+interface TableQuestionAnswerReturn {
     /**
      * The aggregator used to get the answer
      */
@@ -135,7 +135,7 @@ type TableQuestionAnswerReturn = {
      * a list of coordinates of the cells referenced in the answer
      */
     coordinates: number[][];
-};
+}
 type TextClassificationArgs = Args & {
     /**
      * A string to be classified
@@ -196,12 +196,12 @@ type TextGenerationArgs = Args & {
         top_p?: number;
     };
 };
-type TextGenerationReturn = {
+interface TextGenerationReturn {
     /**
      * The continuated string
      */
     generated_text: string;
-};
+}
 type TokenClassificationArgs = Args & {
     /**
      * A string to be classified
@@ -224,7 +224,7 @@ type TokenClassificationArgs = Args & {
         aggregation_strategy?: "none" | "simple" | "first" | "average" | "max";
     };
 };
-type TokenClassificationReturnValue = {
+interface TokenClassificationReturnValue {
     /**
      * The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
      */
@@ -245,7 +245,7 @@ type TokenClassificationReturnValue = {
      * The string that was captured
      */
     word: string;
-};
+}
 type TokenClassificationReturn = TokenClassificationReturnValue[];
 type TranslationArgs = Args & {
     /**
@@ -253,12 +253,12 @@ type TranslationArgs = Args & {
      */
     inputs: string;
 };
-type TranslationReturn = {
+interface TranslationReturn {
     /**
      * The string after translation
      */
     translation_text: string;
-};
+}
 type ZeroShotClassificationArgs = Args & {
     /**
      * a string or list of strings
@@ -275,11 +275,11 @@ type ZeroShotClassificationArgs = Args & {
         multi_label?: boolean;
     };
 };
-type ZeroShotClassificationReturnValue = {
+interface ZeroShotClassificationReturnValue {
     labels: string[];
     scores: number[];
     sequence: string;
-};
+}
 type ZeroShotClassificationReturn = ZeroShotClassificationReturnValue[];
 type ConversationalArgs = Args & {
     inputs: {
@@ -327,14 +327,14 @@ type ConversationalArgs = Args & {
         top_p?: number;
     };
 };
-type ConversationalReturn = {
+interface ConversationalReturn {
     conversation: {
         generated_responses: string[];
         past_user_inputs: string[];
     };
     generated_text: string;
     warnings: string[];
-};
+}
 type FeatureExtractionArgs = Args & {
     /**
      * The inputs vary based on the model. For example when using sentence-transformers/paraphrase-xlm-r-multilingual-v1 the inputs will look like this:
@@ -356,7 +356,7 @@ type ImageClassificationArgs = Args & {
      */
     data: any;
 };
-type ImageClassificationReturnValue = {
+interface ImageClassificationReturnValue {
     /**
      * A float that represents how likely it is that the image file belongs to this class.
      */
@@ -365,7 +365,7 @@ type ImageClassificationReturnValue = {
      * The label for the class (model specific)
      */
     score: number;
-};
+}
 type ImageClassificationReturn = ImageClassificationReturnValue[];
 type ObjectDetectionArgs = Args & {
     /**
@@ -373,7 +373,7 @@ type ObjectDetectionArgs = Args & {
      */
     data: any;
 };
-type ObjectDetectionReturnValue = {
+interface ObjectDetectionReturnValue {
     /**
      * A dict (with keys [xmin,ymin,xmax,ymax]) representing the bounding box of a detected object.
      */
@@ -391,7 +391,7 @@ type ObjectDetectionReturnValue = {
      * A float that represents how likely it is that the detected object belongs to the given class.
      */
     score: number;
-};
+}
 type ObjectDetectionReturn = ObjectDetectionReturnValue[];
 type ImageSegmentationArgs = Args & {
     /**
@@ -399,7 +399,7 @@ type ImageSegmentationArgs = Args & {
      */
     data: any;
 };
-type ImageSegmentationReturnValue = {
+interface ImageSegmentationReturnValue {
     /**
      * The label for the class (model specific) of a segment.
      */
@@ -412,7 +412,7 @@ type ImageSegmentationReturnValue = {
      * A float that represents how likely it is that the detected object belongs to the given class.
      */
     score: number;
-};
+}
 type ImageSegmentationReturn = ImageSegmentationReturnValue[];
 type AutomaticSpeechRecognitionArgs = Args & {
     /**
@@ -420,19 +420,19 @@ type AutomaticSpeechRecognitionArgs = Args & {
      */
     data: any;
 };
-type AutomaticSpeechRecognitionReturn = {
+interface AutomaticSpeechRecognitionReturn {
     /**
      * The text that was recognized from the audio
      */
     text: string;
-};
+}
 type AudioClassificationArgs = Args & {
     /**
      * Binary audio data
      */
     data: any;
 };
-type AudioClassificationReturnValue = {
+interface AudioClassificationReturnValue {
     /**
      * The label for the class (model specific)
      */
@@ -441,7 +441,7 @@ type AudioClassificationReturnValue = {
      * A float that represents how likely it is that the audio file belongs to this class.
      */
     score: number;
-};
+}
 type AudioClassificationReturn = AudioClassificationReturnValue[];
 type TextToImageArgs = Args & {
     /**
@@ -453,7 +453,7 @@ type TextToImageArgs = Args & {
      */
     negative_prompt?: string;
 };
-type TextToImageReturn = ArrayBuffer;
+type TextToImageReturn = Blob;
 declare class HfInference {
     private readonly apiKey;
     private readonly defaultOptions;

package/dist/index.js

@@ -185,17 +185,15 @@ var HfInference = class {
         wait_for_model: true
       });
     }
-    let output;
     if (options?.blob) {
       if (!response.ok) {
         throw new Error("An error occurred while fetching the blob");
       }
-      return await response.arrayBuffer();
-    } else {
-      output = await response.json();
-      if (output.error) {
-        throw new Error(output.error);
-      }
+      return await response.blob();
+    }
+    const output = await response.json();
+    if (output.error) {
+      throw new Error(output.error);
     }
     return output;
   }

package/dist/index.mjs

@@ -160,17 +160,15 @@ var HfInference = class {
         wait_for_model: true
       });
     }
-    let output;
     if (options?.blob) {
       if (!response.ok) {
         throw new Error("An error occurred while fetching the blob");
       }
-      return await response.arrayBuffer();
-    } else {
-      output = await response.json();
-      if (output.error) {
-        throw new Error(output.error);
-      }
+      return await response.blob();
+    }
+    const output = await response.json();
+    if (output.error) {
+      throw new Error(output.error);
     }
     return output;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huggingface/inference",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "license": "MIT",
   "author": "Tim Mikeladze <tim.mikeladze@gmail.com>",
   "description": "Typescript wrapper for the Hugging Face Inference API",
@@ -39,26 +39,18 @@
     }
   },
   "devDependencies": {
-    "@types/jest": "29.4.0",
     "@types/node": "18.13.0",
-    "@typescript-eslint/eslint-plugin": "^5.51.0",
-    "@typescript-eslint/parser": "^5.51.0",
-    "eslint": "8.34.0",
-    "eslint-config-prettier": "^8.6.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-typescript-sort-keys": "^2.1.0",
-    "jest": "29.4.3",
-    "prettier": "2.8.4",
-    "ts-jest": "29.0.5",
     "tsup": "^6.6.3",
-    "typescript": "4.9.5"
+    "typescript": "4.9.5",
+    "vite": "^4.1.4",
+    "vitest": "^0.29.2"
   },
   "resolutions": {},
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --clean --dts",
     "format": "prettier --write . && eslint --quiet --fix --ext .cjs,.ts .",
-    "test": "jest --passWithNoTests",
-    "test:ci": "npm run test -- --ci --coverage",
+    "test": "vitest run",
+    "test:ci": "pnpm run test -- --coverage",
     "type-check": "tsc"
   }
 }

package/src/HfInference.ts

@@ -1,4 +1,4 @@
-export type Options = {
+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.
 	 */
@@ -16,11 +16,11 @@ export type Options = {
 	 * (Default: false) Boolean. If the model is not ready, wait for it instead of receiving 503. It limits the number of requests required to get your inference done. It is advised to only set this flag to true after receiving a 503 error as it will limit hanging in your application to known places.
 	 */
 	wait_for_model?: boolean;
-};
+}
 
-export type Args = {
+export interface Args {
 	model: string;
-};
+}
 
 export type FillMaskArgs = Args & {
 	inputs: string;
@@ -82,12 +82,12 @@ export type SummarizationArgs = Args & {
 	};
 };
 
-export type SummarizationReturn = {
+export interface SummarizationReturn {
 	/**
 	 * The string after translation
 	 */
 	summary_text: string;
-};
+}
 
 export type QuestionAnswerArgs = Args & {
 	inputs: {
@@ -96,7 +96,7 @@ export type QuestionAnswerArgs = Args & {
 	};
 };
 
-export type QuestionAnswerReturn = {
+export interface QuestionAnswerReturn {
 	/**
 	 * A string that’s the answer within the text.
 	 */
@@ -113,7 +113,7 @@ export type QuestionAnswerReturn = {
 	 * The index (string wise) of the start of the answer within context.
 	 */
 	start:  number;
-};
+}
 
 export type TableQuestionAnswerArgs = Args & {
 	inputs: {
@@ -128,7 +128,7 @@ export type TableQuestionAnswerArgs = Args & {
 	};
 };
 
-export type TableQuestionAnswerReturn = {
+export interface TableQuestionAnswerReturn {
 	/**
 	 * The aggregator used to get the answer
 	 */
@@ -145,7 +145,7 @@ export type TableQuestionAnswerReturn = {
 	 * a list of coordinates of the cells referenced in the answer
 	 */
 	coordinates: number[][];
-};
+}
 
 export type TextClassificationArgs = Args & {
 	/**
@@ -210,12 +210,12 @@ export type TextGenerationArgs = Args & {
 	};
 };
 
-export type TextGenerationReturn = {
+export interface TextGenerationReturn {
 	/**
 	 * The continuated string
 	 */
 	generated_text: string;
-};
+}
 
 export type TokenClassificationArgs = Args & {
 	/**
@@ -240,7 +240,7 @@ export type TokenClassificationArgs = Args & {
 	};
 };
 
-export type TokenClassificationReturnValue = {
+export interface TokenClassificationReturnValue {
 	/**
 	 * The offset stringwise where the answer is located. Useful to disambiguate if word occurs multiple times.
 	 */
@@ -261,7 +261,7 @@ export type TokenClassificationReturnValue = {
 	 * The string that was captured
 	 */
 	word:         string;
-};
+}
 
 export type TokenClassificationReturn = TokenClassificationReturnValue[];
 
@@ -272,12 +272,12 @@ export type TranslationArgs = Args & {
 	inputs: string;
 };
 
-export type TranslationReturn = {
+export interface TranslationReturn {
 	/**
 	 * The string after translation
 	 */
 	translation_text: string;
-};
+}
 
 export type ZeroShotClassificationArgs = Args & {
 	/**
@@ -296,11 +296,11 @@ export type ZeroShotClassificationArgs = Args & {
 	};
 };
 
-export type ZeroShotClassificationReturnValue = {
+export interface ZeroShotClassificationReturnValue {
 	labels:   string[];
 	scores:   number[];
 	sequence: string;
-};
+}
 
 export type ZeroShotClassificationReturn = ZeroShotClassificationReturnValue[];
 
@@ -351,14 +351,14 @@ export type ConversationalArgs = Args & {
 	};
 };
 
-export type ConversationalReturn = {
+export interface ConversationalReturn {
 	conversation: {
 		generated_responses: string[];
 		past_user_inputs:    string[];
 	};
 	generated_text: string;
 	warnings:       string[];
-};
+}
 
 export type FeatureExtractionArgs = Args & {
 	/**
@@ -384,7 +384,7 @@ export type ImageClassificationArgs = Args & {
 	data: any;
 };
 
-export type ImageClassificationReturnValue = {
+export interface ImageClassificationReturnValue {
 	/**
 	 * A float that represents how likely it is that the image file belongs to this class.
 	 */
@@ -393,7 +393,7 @@ export type ImageClassificationReturnValue = {
 	 * The label for the class (model specific)
 	 */
 	score: number;
-};
+}
 
 export type ImageClassificationReturn = ImageClassificationReturnValue[];
 
@@ -404,7 +404,7 @@ export type ObjectDetectionArgs = Args & {
 	data: any;
 };
 
-export type ObjectDetectionReturnValue = {
+export interface ObjectDetectionReturnValue {
 	/**
 	 * A dict (with keys [xmin,ymin,xmax,ymax]) representing the bounding box of a detected object.
 	 */
@@ -423,7 +423,7 @@ export type ObjectDetectionReturnValue = {
 	 * A float that represents how likely it is that the detected object belongs to the given class.
 	 */
 	score: number;
-};
+}
 
 export type ObjectDetectionReturn = ObjectDetectionReturnValue[];
 
@@ -434,7 +434,7 @@ export type ImageSegmentationArgs = Args & {
 	data: any;
 };
 
-export type ImageSegmentationReturnValue = {
+export interface ImageSegmentationReturnValue {
 	/**
 	 * The label for the class (model specific) of a segment.
 	 */
@@ -447,7 +447,7 @@ export type ImageSegmentationReturnValue = {
 	 * A float that represents how likely it is that the detected object belongs to the given class.
 	 */
 	score: number;
-};
+}
 
 export type ImageSegmentationReturn = ImageSegmentationReturnValue[];
 
@@ -458,12 +458,12 @@ export type AutomaticSpeechRecognitionArgs = Args & {
 	data: any;
 };
 
-export type AutomaticSpeechRecognitionReturn = {
+export interface AutomaticSpeechRecognitionReturn {
 	/**
 	 * The text that was recognized from the audio
 	 */
 	text: string;
-};
+}
 
 export type AudioClassificationArgs = Args & {
 	/**
@@ -472,7 +472,7 @@ export type AudioClassificationArgs = Args & {
 	data: any;
 };
 
-export type AudioClassificationReturnValue = {
+export interface AudioClassificationReturnValue {
 	/**
 	 * The label for the class (model specific)
 	 */
@@ -482,7 +482,7 @@ export type AudioClassificationReturnValue = {
 	 * A float that represents how likely it is that the audio file belongs to this class.
 	 */
 	score: number;
-};
+}
 
 export type AudioClassificationReturn = AudioClassificationReturnValue[];
 
@@ -498,7 +498,7 @@ export type TextToImageArgs = Args & {
 	negative_prompt?: string;
 };
 
-export type TextToImageReturn = ArrayBuffer;
+export type TextToImageReturn = Blob;
 
 export class HfInference {
 	private readonly apiKey:         string;
@@ -712,20 +712,17 @@ export class HfInference {
 			});
 		}
 
-		let output;
-
 		if (options?.blob) {
 			if (!response.ok) {
 				throw new Error("An error occurred while fetching the blob");
 			}
-			return await response.arrayBuffer();
-		} else {
-			output = await response.json();
-			if (output.error) {
-				throw new Error(output.error);
-			}
+			return await response.blob();
 		}
 
+		const output = await response.json();
+		if (output.error) {
+			throw new Error(output.error);
+		}
 		return output;
 	}