@huggingface/tasks 0.13.1-test → 0.13.1-test2

package/src/snippets/common.ts

@@ -0,0 +1,39 @@
+import type { ChatCompletionInputMessage, GenerationParameters } from "../tasks/index.js";
+
+export function stringifyMessages(
+	messages: ChatCompletionInputMessage[],
+	opts?: {
+		indent?: string;
+		attributeKeyQuotes?: boolean;
+		customContentEscaper?: (str: string) => string;
+	}
+): string {
+	let messagesStr = JSON.stringify(messages, null, "\t");
+	if (opts?.indent) {
+		messagesStr = messagesStr.replaceAll("\n", `\n${opts.indent}`);
+	}
+	if (!opts?.attributeKeyQuotes) {
+		messagesStr = messagesStr.replace(/"([^"]+)":/g, "$1:");
+	}
+	if (opts?.customContentEscaper) {
+		messagesStr = opts.customContentEscaper(messagesStr);
+	}
+	return messagesStr;
+}
+
+type PartialGenerationParameters = Partial<Pick<GenerationParameters, "temperature" | "max_tokens" | "top_p">>;
+
+export function stringifyGenerationConfig(
+	config: PartialGenerationParameters,
+	opts: {
+		indent: string;
+		attributeValueConnector: string;
+		attributeKeyQuotes?: boolean;
+	}
+): string {
+	const quote = opts.attributeKeyQuotes ? `"` : "";
+
+	return Object.entries(config)
+		.map(([key, val]) => `${quote}${key}${quote}${opts.attributeValueConnector}${val}`)
+		.join(`,${opts.indent}`);
+}

package/src/snippets/curl.spec.ts

@@ -0,0 +1,94 @@
+import type { ModelDataMinimal } from "./types.js";
+import { describe, expect, it } from "vitest";
+import { getCurlInferenceSnippet } from "./curl.js";
+
+describe("inference API snippets", () => {
+	it("conversational llm", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.1-8B-Instruct",
+			pipeline_tag: "text-generation",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getCurlInferenceSnippet(model, "api_token");
+
+		expect(snippet.content)
+			.toEqual(`curl 'https://api-inference.huggingface.co/models/meta-llama/Llama-3.1-8B-Instruct/v1/chat/completions' \\
+-H "Authorization: Bearer api_token" \\
+-H 'Content-Type: application/json' \\
+--data '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "messages": [
+		{
+			"role": "user",
+			"content": "What is the capital of France?"
+		}
+	],
+    "max_tokens": 500,
+    "stream": true
+}'`);
+	});
+
+	it("conversational llm non-streaming", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.1-8B-Instruct",
+			pipeline_tag: "text-generation",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getCurlInferenceSnippet(model, "api_token", { streaming: false });
+
+		expect(snippet.content)
+			.toEqual(`curl 'https://api-inference.huggingface.co/models/meta-llama/Llama-3.1-8B-Instruct/v1/chat/completions' \\
+-H "Authorization: Bearer api_token" \\
+-H 'Content-Type: application/json' \\
+--data '{
+    "model": "meta-llama/Llama-3.1-8B-Instruct",
+    "messages": [
+		{
+			"role": "user",
+			"content": "What is the capital of France?"
+		}
+	],
+    "max_tokens": 500,
+    "stream": false
+}'`);
+	});
+
+	it("conversational vlm", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.2-11B-Vision-Instruct",
+			pipeline_tag: "image-text-to-text",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getCurlInferenceSnippet(model, "api_token");
+
+		expect(snippet.content)
+			.toEqual(`curl 'https://api-inference.huggingface.co/models/meta-llama/Llama-3.2-11B-Vision-Instruct/v1/chat/completions' \\
+-H "Authorization: Bearer api_token" \\
+-H 'Content-Type: application/json' \\
+--data '{
+    "model": "meta-llama/Llama-3.2-11B-Vision-Instruct",
+    "messages": [
+		{
+			"role": "user",
+			"content": [
+				{
+					"type": "text",
+					"text": "Describe this image in one sentence."
+				},
+				{
+					"type": "image_url",
+					"image_url": {
+						"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
+					}
+				}
+			]
+		}
+	],
+    "max_tokens": 500,
+    "stream": true
+}'`);
+	});
+});

package/src/snippets/curl.ts

@@ -0,0 +1,120 @@
+import type { PipelineType } from "../pipelines.js";
+import type { ChatCompletionInputMessage, GenerationParameters } from "../tasks/index.js";
+import { stringifyGenerationConfig, stringifyMessages } from "./common.js";
+import { getModelInputSnippet } from "./inputs.js";
+import type { InferenceSnippet, ModelDataMinimal } from "./types.js";
+
+export const snippetBasic = (model: ModelDataMinimal, accessToken: string): InferenceSnippet => ({
+	content: `curl https://api-inference.huggingface.co/models/${model.id} \\
+	-X POST \\
+	-d '{"inputs": ${getModelInputSnippet(model, true)}}' \\
+	-H 'Content-Type: application/json' \\
+	-H "Authorization: Bearer ${accessToken || `{API_TOKEN}`}"`,
+});
+
+export const snippetTextGeneration = (
+	model: ModelDataMinimal,
+	accessToken: string,
+	opts?: {
+		streaming?: boolean;
+		messages?: ChatCompletionInputMessage[];
+		temperature?: GenerationParameters["temperature"];
+		max_tokens?: GenerationParameters["max_tokens"];
+		top_p?: GenerationParameters["top_p"];
+	}
+): InferenceSnippet => {
+	if (model.tags.includes("conversational")) {
+		// Conversational model detected, so we display a code snippet that features the Messages API
+		const streaming = opts?.streaming ?? true;
+		const exampleMessages = getModelInputSnippet(model) as ChatCompletionInputMessage[];
+		const messages = opts?.messages ?? exampleMessages;
+
+		const config = {
+			...(opts?.temperature ? { temperature: opts.temperature } : undefined),
+			max_tokens: opts?.max_tokens ?? 500,
+			...(opts?.top_p ? { top_p: opts.top_p } : undefined),
+		};
+		return {
+			content: `curl 'https://api-inference.huggingface.co/models/${model.id}/v1/chat/completions' \\
+-H "Authorization: Bearer ${accessToken || `{API_TOKEN}`}" \\
+-H 'Content-Type: application/json' \\
+--data '{
+    "model": "${model.id}",
+    "messages": ${stringifyMessages(messages, {
+			indent: "\t",
+			attributeKeyQuotes: true,
+			customContentEscaper: (str) => str.replace(/'/g, "'\\''"),
+		})},
+    ${stringifyGenerationConfig(config, {
+			indent: "\n    ",
+			attributeKeyQuotes: true,
+			attributeValueConnector: ": ",
+		})},
+    "stream": ${!!streaming}
+}'`,
+		};
+	} else {
+		return snippetBasic(model, accessToken);
+	}
+};
+
+export const snippetZeroShotClassification = (model: ModelDataMinimal, accessToken: string): InferenceSnippet => ({
+	content: `curl https://api-inference.huggingface.co/models/${model.id} \\
+	-X POST \\
+	-d '{"inputs": ${getModelInputSnippet(model, true)}, "parameters": {"candidate_labels": ["refund", "legal", "faq"]}}' \\
+	-H 'Content-Type: application/json' \\
+	-H "Authorization: Bearer ${accessToken || `{API_TOKEN}`}"`,
+});
+
+export const snippetFile = (model: ModelDataMinimal, accessToken: string): InferenceSnippet => ({
+	content: `curl https://api-inference.huggingface.co/models/${model.id} \\
+	-X POST \\
+	--data-binary '@${getModelInputSnippet(model, true, true)}' \\
+	-H "Authorization: Bearer ${accessToken || `{API_TOKEN}`}"`,
+});
+
+export const curlSnippets: Partial<
+	Record<
+		PipelineType,
+		(model: ModelDataMinimal, accessToken: string, opts?: Record<string, unknown>) => InferenceSnippet
+	>
+> = {
+	// Same order as in js/src/lib/interfaces/Types.ts
+	"text-classification": snippetBasic,
+	"token-classification": snippetBasic,
+	"table-question-answering": snippetBasic,
+	"question-answering": snippetBasic,
+	"zero-shot-classification": snippetZeroShotClassification,
+	translation: snippetBasic,
+	summarization: snippetBasic,
+	"feature-extraction": snippetBasic,
+	"text-generation": snippetTextGeneration,
+	"image-text-to-text": snippetTextGeneration,
+	"text2text-generation": snippetBasic,
+	"fill-mask": snippetBasic,
+	"sentence-similarity": snippetBasic,
+	"automatic-speech-recognition": snippetFile,
+	"text-to-image": snippetBasic,
+	"text-to-speech": snippetBasic,
+	"text-to-audio": snippetBasic,
+	"audio-to-audio": snippetFile,
+	"audio-classification": snippetFile,
+	"image-classification": snippetFile,
+	"image-to-text": snippetFile,
+	"object-detection": snippetFile,
+	"image-segmentation": snippetFile,
+};
+
+export function getCurlInferenceSnippet(
+	model: ModelDataMinimal,
+	accessToken: string,
+	opts?: Record<string, unknown>
+): InferenceSnippet {
+	return model.pipeline_tag && model.pipeline_tag in curlSnippets
+		? curlSnippets[model.pipeline_tag]?.(model, accessToken, opts) ?? { content: "" }
+		: { content: "" };
+}
+
+export function hasCurlInferenceSnippet(model: Pick<ModelDataMinimal, "pipeline_tag">): boolean {
+	return !!model.pipeline_tag && model.pipeline_tag in curlSnippets;
+}

package/src/snippets/index.ts

@@ -0,0 +1,7 @@
+import * as inputs from "./inputs.js";
+import * as curl from "./curl.js";
+import * as python from "./python.js";
+import * as js from "./js.js";
+export * from "./types.js";
+
+export { inputs, curl, python, js };

package/src/snippets/inputs.ts

@@ -0,0 +1,167 @@
+import type { PipelineType } from "../pipelines.js";
+import type { ChatCompletionInputMessage } from "../tasks/index.js";
+import type { ModelDataMinimal } from "./types.js";
+
+const inputsZeroShotClassification = () =>
+	`"Hi, I recently bought a device from your company but it is not working as advertised and I would like to get reimbursed!"`;
+
+const inputsTranslation = () => `"Меня зовут Вольфганг и я живу в Берлине"`;
+
+const inputsSummarization = () =>
+	`"The tower is 324 metres (1,063 ft) tall, about the same height as an 81-storey building, and the tallest structure in Paris. Its base is square, measuring 125 metres (410 ft) on each side. During its construction, the Eiffel Tower surpassed the Washington Monument to become the tallest man-made structure in the world, a title it held for 41 years until the Chrysler Building in New York City was finished in 1930. It was the first structure to reach a height of 300 metres. Due to the addition of a broadcasting aerial at the top of the tower in 1957, it is now taller than the Chrysler Building by 5.2 metres (17 ft). Excluding transmitters, the Eiffel Tower is the second tallest free-standing structure in France after the Millau Viaduct."`;
+
+const inputsTableQuestionAnswering = () =>
+	`{
+	"query": "How many stars does the transformers repository have?",
+	"table": {
+		"Repository": ["Transformers", "Datasets", "Tokenizers"],
+		"Stars": ["36542", "4512", "3934"],
+		"Contributors": ["651", "77", "34"],
+		"Programming language": [
+			"Python",
+			"Python",
+			"Rust, Python and NodeJS"
+		]
+	}
+}`;
+
+const inputsVisualQuestionAnswering = () =>
+	`{
+	"image": "cat.png",
+	"question": "What is in this image?"
+}`;
+
+const inputsQuestionAnswering = () =>
+	`{
+	"question": "What is my name?",
+	"context": "My name is Clara and I live in Berkeley."
+}`;
+
+const inputsTextClassification = () => `"I like you. I love you"`;
+
+const inputsTokenClassification = () => `"My name is Sarah Jessica Parker but you can call me Jessica"`;
+
+const inputsTextGeneration = (model: ModelDataMinimal): string | ChatCompletionInputMessage[] => {
+	if (model.tags.includes("conversational")) {
+		return model.pipeline_tag === "text-generation"
+			? [{ role: "user", content: "What is the capital of France?" }]
+			: [
+					{
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: "Describe this image in one sentence.",
+							},
+							{
+								type: "image_url",
+								image_url: {
+									url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg",
+								},
+							},
+						],
+					},
+			  ];
+	}
+	return `"Can you please let us know more details about your "`;
+};
+
+const inputsText2TextGeneration = () => `"The answer to the universe is"`;
+
+const inputsFillMask = (model: ModelDataMinimal) => `"The answer to the universe is ${model.mask_token}."`;
+
+const inputsSentenceSimilarity = () =>
+	`{
+	"source_sentence": "That is a happy person",
+	"sentences": [
+		"That is a happy dog",
+		"That is a very happy person",
+		"Today is a sunny day"
+	]
+}`;
+
+const inputsFeatureExtraction = () => `"Today is a sunny day and I will get some ice cream."`;
+
+const inputsImageClassification = () => `"cats.jpg"`;
+
+const inputsImageToText = () => `"cats.jpg"`;
+
+const inputsImageSegmentation = () => `"cats.jpg"`;
+
+const inputsObjectDetection = () => `"cats.jpg"`;
+
+const inputsAudioToAudio = () => `"sample1.flac"`;
+
+const inputsAudioClassification = () => `"sample1.flac"`;
+
+const inputsTextToImage = () => `"Astronaut riding a horse"`;
+
+const inputsTextToSpeech = () => `"The answer to the universe is 42"`;
+
+const inputsTextToAudio = () => `"liquid drum and bass, atmospheric synths, airy sounds"`;
+
+const inputsAutomaticSpeechRecognition = () => `"sample1.flac"`;
+
+const inputsTabularPrediction = () =>
+	`'{"Height":[11.52,12.48],"Length1":[23.2,24.0],"Length2":[25.4,26.3],"Species": ["Bream","Bream"]}'`;
+
+const inputsZeroShotImageClassification = () => `"cats.jpg"`;
+
+const modelInputSnippets: {
+	[key in PipelineType]?: (model: ModelDataMinimal) => string | ChatCompletionInputMessage[];
+} = {
+	"audio-to-audio": inputsAudioToAudio,
+	"audio-classification": inputsAudioClassification,
+	"automatic-speech-recognition": inputsAutomaticSpeechRecognition,
+	"document-question-answering": inputsVisualQuestionAnswering,
+	"feature-extraction": inputsFeatureExtraction,
+	"fill-mask": inputsFillMask,
+	"image-classification": inputsImageClassification,
+	"image-to-text": inputsImageToText,
+	"image-segmentation": inputsImageSegmentation,
+	"object-detection": inputsObjectDetection,
+	"question-answering": inputsQuestionAnswering,
+	"sentence-similarity": inputsSentenceSimilarity,
+	summarization: inputsSummarization,
+	"table-question-answering": inputsTableQuestionAnswering,
+	"tabular-regression": inputsTabularPrediction,
+	"tabular-classification": inputsTabularPrediction,
+	"text-classification": inputsTextClassification,
+	"text-generation": inputsTextGeneration,
+	"image-text-to-text": inputsTextGeneration,
+	"text-to-image": inputsTextToImage,
+	"text-to-speech": inputsTextToSpeech,
+	"text-to-audio": inputsTextToAudio,
+	"text2text-generation": inputsText2TextGeneration,
+	"token-classification": inputsTokenClassification,
+	translation: inputsTranslation,
+	"zero-shot-classification": inputsZeroShotClassification,
+	"zero-shot-image-classification": inputsZeroShotImageClassification,
+};
+
+// Use noWrap to put the whole snippet on a single line (removing new lines and tabulations)
+// Use noQuotes to strip quotes from start & end (example: "abc" -> abc)
+export function getModelInputSnippet(
+	model: ModelDataMinimal,
+	noWrap = false,
+	noQuotes = false
+): string | ChatCompletionInputMessage[] {
+	if (model.pipeline_tag) {
+		const inputs = modelInputSnippets[model.pipeline_tag];
+		if (inputs) {
+			let result = inputs(model);
+			if (typeof result === "string") {
+				if (noWrap) {
+					result = result.replace(/(?:(?:\r?\n|\r)\t*)|\t+/g, " ");
+				}
+				if (noQuotes) {
+					const REGEX_QUOTES = /^"(.+)"$/s;
+					const match = result.match(REGEX_QUOTES);
+					result = match ? match[1] : result;
+				}
+			}
+			return result;
+		}
+	}
+	return "No input example has been defined for this model task.";
+}

package/src/snippets/js.spec.ts

@@ -0,0 +1,148 @@
+import type { InferenceSnippet, ModelDataMinimal } from "./types.js";
+import { describe, expect, it } from "vitest";
+import { getJsInferenceSnippet } from "./js.js";
+
+describe("inference API snippets", () => {
+	it("conversational llm", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.1-8B-Instruct",
+			pipeline_tag: "text-generation",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getJsInferenceSnippet(model, "api_token") as InferenceSnippet[];
+
+		expect(snippet[0].content).toEqual(`import { HfInference } from "@huggingface/inference"
+
+const client = new HfInference("api_token")
+
+let out = "";
+
+const stream = client.chatCompletionStream({
+	model: "meta-llama/Llama-3.1-8B-Instruct",
+	messages: [
+		{
+			role: "user",
+			content: "What is the capital of France?"
+		}
+	],
+	max_tokens: 500
+});
+
+for await (const chunk of stream) {
+	if (chunk.choices && chunk.choices.length > 0) {
+		const newContent = chunk.choices[0].delta.content;
+		out += newContent;
+		console.log(newContent);
+	}  
+}`);
+	});
+
+	it("conversational llm non-streaming", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.1-8B-Instruct",
+			pipeline_tag: "text-generation",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getJsInferenceSnippet(model, "api_token", { streaming: false }) as InferenceSnippet[];
+
+		expect(snippet[0].content).toEqual(`import { HfInference } from "@huggingface/inference"
+
+const client = new HfInference("api_token")
+
+const chatCompletion = await client.chatCompletion({
+	model: "meta-llama/Llama-3.1-8B-Instruct",
+	messages: [
+		{
+			role: "user",
+			content: "What is the capital of France?"
+		}
+	],
+	max_tokens: 500
+});
+
+console.log(chatCompletion.choices[0].message);`);
+	});
+
+	it("conversational vlm", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.2-11B-Vision-Instruct",
+			pipeline_tag: "image-text-to-text",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getJsInferenceSnippet(model, "api_token") as InferenceSnippet[];
+
+		expect(snippet[0].content).toEqual(`import { HfInference } from "@huggingface/inference"
+
+const client = new HfInference("api_token")
+
+let out = "";
+
+const stream = client.chatCompletionStream({
+	model: "meta-llama/Llama-3.2-11B-Vision-Instruct",
+	messages: [
+		{
+			role: "user",
+			content: [
+				{
+					type: "text",
+					text: "Describe this image in one sentence."
+				},
+				{
+					type: "image_url",
+					image_url: {
+						url: "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
+					}
+				}
+			]
+		}
+	],
+	max_tokens: 500
+});
+
+for await (const chunk of stream) {
+	if (chunk.choices && chunk.choices.length > 0) {
+		const newContent = chunk.choices[0].delta.content;
+		out += newContent;
+		console.log(newContent);
+	}  
+}`);
+	});
+
+	it("conversational llm", async () => {
+		const model: ModelDataMinimal = {
+			id: "meta-llama/Llama-3.1-8B-Instruct",
+			pipeline_tag: "text-generation",
+			tags: ["conversational"],
+			inference: "",
+		};
+		const snippet = getJsInferenceSnippet(model, "api_token") as InferenceSnippet[];
+
+		expect(snippet[0].content).toEqual(`import { HfInference } from "@huggingface/inference"
+
+const client = new HfInference("api_token")
+
+let out = "";
+
+const stream = client.chatCompletionStream({
+	model: "meta-llama/Llama-3.1-8B-Instruct",
+	messages: [
+		{
+			role: "user",
+			content: "What is the capital of France?"
+		}
+	],
+	max_tokens: 500
+});
+
+for await (const chunk of stream) {
+	if (chunk.choices && chunk.choices.length > 0) {
+		const newContent = chunk.choices[0].delta.content;
+		out += newContent;
+		console.log(newContent);
+	}  
+}`);
+	});
+});