Merge branch 'main' into add-chatterbox-snippet

Author: Vaibhavs10

.github/workflows/documentation.yml

@@ -11,7 +11,7 @@ on:
       - "README.md"
       - "packages/hub/README.md"
       - "packages/inference/README.md"
-      - "packages/agents/README.md"
+      - "packages/tiny-agents/README.md"
       - ".github/workflows/documentation.yml"
 
 jobs:

.github/workflows/pr-documentation.yml

@@ -8,7 +8,7 @@ on:
       - "packages/hub/README.md"
       - "packages/doc-internal/**"
       - "packages/inference/README.md"
-      - "packages/agents/README.md"
+      - "packages/tiny-agents/README.md"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}

README.md

@@ -97,7 +97,7 @@ You can run our packages with vanilla JS, without any bundler, by using a CDN or
 
 ```html
 <script type="module">
-    import { InferenceClient } from 'https://cdn.jsdelivr.net/npm/@huggingface/inference@3.13.2/+esm';
+    import { InferenceClient } from 'https://cdn.jsdelivr.net/npm/@huggingface/inference@4.0.0/+esm';
     import { createRepo, commit, deleteRepo, listFiles } from "https://cdn.jsdelivr.net/npm/@huggingface/[email protected]/+esm";
 </script>
 ```

docs/_toctree.yml

@@ -18,14 +18,12 @@
   isExpanded: true
   sections:
     - local: mcp-client/README
-      title: Simple MCP Client and smol Agent built on top of Inference Client
-- title: "@huggingface/agent"
+      title: Simple MCP Client built on top of Inference Client
+- title: "@huggingface/tiny-agents"
   isExpanded: true
   sections:
-    - local: agents/README
-      title: Use Agents to run multi-modal workflows from a natural language API
-    - local: agents/modules
-      title: API Reference
+    - local: tiny-agents/README
+      title: A lightweight MCP-powered Agent built on top of Inference Client
 - title: "@huggingface/space-header"
   isExpanded: true
   sections:

packages/doc-internal/package.json

@@ -5,16 +5,16 @@
 	"description": "Package to generate doc for other @huggingface packages",
 	"private": true,
 	"scripts": {
-		"start": "pnpm run fix-cdn-versions && pnpm run doc-hub && pnpm run doc-inference && pnpm run doc-agents && pnpm run doc-space-header && pnpm run doc-gguf && pnpm run doc-mcp-client && cp ../../README.md ../../docs/index.md && pnpm run update-toc && pnpm run fix-md-links && pnpm run fix-md-headinghashlinks",
+		"start": "pnpm run fix-cdn-versions && pnpm run doc-hub && pnpm run doc-inference && pnpm run doc-space-header && pnpm run doc-gguf && pnpm run doc-mcp-client && pnpm run doc-tiny-agents && cp ../../README.md ../../docs/index.md && pnpm run update-toc && pnpm run fix-md-links && pnpm run fix-md-headinghashlinks",
 		"lint": "eslint --quiet --fix --ext .cjs,.ts .",
 		"lint:check": "eslint --ext .cjs,.ts .",
 		"format": "prettier --write .",
 		"format:check": "prettier --check .",
 		"doc-hub": "typedoc --tsconfig ../hub/tsconfig.json --githubPages false --plugin typedoc-plugin-markdown --out ../../docs/hub --hideBreadcrumbs --hideInPageTOC --sourceLinkTemplate https://github.com/huggingface/huggingface.js/blob/main/{path}#L{line} ../hub/index.ts",
 		"doc-inference": "typedoc --tsconfig ../inference/tsconfig.json --githubPages false --plugin typedoc-plugin-markdown --out ../../docs/inference --hideBreadcrumbs --hideInPageTOC --sourceLinkTemplate https://github.com/huggingface/huggingface.js/blob/main/{path}#L{line} ../inference/src/index.ts",
-		"doc-agents": "typedoc --tsconfig ../agents/tsconfig.json --githubPages false --plugin typedoc-plugin-markdown --out ../../docs/agents --hideBreadcrumbs --hideInPageTOC --sourceLinkTemplate https://github.com/huggingface/huggingface.js/blob/main/{path}#L{line} ../agents/src/index.ts",
 		"doc-gguf": "mkdir -p ../../docs/gguf && cp ../../packages/gguf/README.md ../../docs/gguf/README.md",
 		"doc-mcp-client": "mkdir -p ../../docs/mcp-client && cp ../../packages/mcp-client/README.md ../../docs/mcp-client/README.md",
+		"doc-tiny-agents": "mkdir -p ../../docs/tiny-agents && cp ../../packages/tiny-agents/README.md ../../docs/tiny-agents/README.md",
 		"doc-space-header": "mkdir -p ../../docs/space-header && cp ../../packages/space-header/README.md ../../docs/space-header/README.md",
 		"update-toc": "tsx update-toc.ts",
 		"fix-cdn-versions": "tsx fix-cdn-versions.ts",

packages/hub/cli.ts

@@ -2,7 +2,7 @@
 
 import { parseArgs } from "node:util";
 import { typedEntries } from "./src/utils/typedEntries";
-import { createBranch, createRepo, deleteBranch, repoExists, uploadFilesWithProgress } from "./src";
+import { createBranch, createRepo, deleteBranch, deleteRepo, repoExists, uploadFilesWithProgress } from "./src";
 import { pathToFileURL } from "node:url";
 import { stat } from "node:fs/promises";
 import { basename, join } from "node:path";
@@ -78,7 +78,6 @@ const commands = {
 			{
 				name: "repo-type" as const,
 				enum: ["dataset", "model", "space"],
-				default: "model",
 				description:
 					"The type of repo to upload to. Defaults to model. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
 			},
@@ -126,9 +125,8 @@ const commands = {
 					{
 						name: "repo-type" as const,
 						enum: ["dataset", "model", "space"],
-						default: "model",
 						description:
-							"The type of repo to create. Defaults to model. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
+							"The type of the repo to create the branch into. Defaults to model. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
 					},
 					{
 						name: "revision" as const,
@@ -173,7 +171,6 @@ const commands = {
 					{
 						name: "repo-type" as const,
 						enum: ["dataset", "model", "space"],
-						default: "model",
 						description:
 							"The type of repo to delete the branch from. Defaults to model. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
 					},
@@ -187,6 +184,35 @@ const commands = {
 			},
 		},
 	} satisfies CommandGroup,
+	repo: {
+		description: "Manage repositories on the Hub",
+		subcommands: {
+			delete: {
+				description: "Delete a repository from the Hub",
+				args: [
+					{
+						name: "repo-name" as const,
+						description:
+							"The name of the repo to delete. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
+						positional: true,
+						required: true,
+					},
+					{
+						name: "repo-type" as const,
+						enum: ["dataset", "model", "space"],
+						description:
+							"The type of the repo to delete. Defaults to model. You can also prefix the repo name with the type, e.g. datasets/username/repo-name",
+					},
+					{
+						name: "token" as const,
+						description:
+							"The access token to use for authentication. If not provided, the HF_TOKEN environment variable will be used.",
+						default: process.env.HF_TOKEN,
+					},
+				] as const,
+			},
+		},
+	} satisfies CommandGroup,
 	version: {
 		description: "Print the version of the CLI",
 		args: [] as const,
@@ -389,6 +415,54 @@ async function run() {
 			}
 			break;
 		}
+		case "repo": {
+			const repoCommandGroup = commands.repo;
+			const currentSubCommandName = subCommandName as keyof typeof repoCommandGroup.subcommands | undefined;
+
+			if (cliArgs[0] === "--help" || cliArgs[0] === "-h") {
+				if (currentSubCommandName && repoCommandGroup.subcommands[currentSubCommandName]) {
+					console.log(detailedUsageForSubcommand("repo", currentSubCommandName));
+				} else {
+					console.log(listSubcommands("repo", repoCommandGroup));
+				}
+				break;
+			}
+
+			if (!currentSubCommandName || !repoCommandGroup.subcommands[currentSubCommandName]) {
+				console.error(`Error: Missing or invalid subcommand for 'repo'.`);
+				console.log(listSubcommands("repo", repoCommandGroup));
+				process.exitCode = 1;
+				break;
+			}
+
+			const subCmdDef = repoCommandGroup.subcommands[currentSubCommandName];
+
+			switch (currentSubCommandName) {
+				case "delete": {
+					const parsedArgs = advParseArgs(cliArgs, subCmdDef.args, `repo ${currentSubCommandName}`);
+					const { repoName, repoType, token } = parsedArgs;
+
+					const repoDesignation: Parameters<typeof deleteRepo>[0]["repo"] = repoType
+						? { type: repoType as "model" | "dataset" | "space", name: repoName }
+						: repoName;
+
+					await deleteRepo({
+						repo: repoDesignation,
+						accessToken: token,
+						hubUrl: process.env.HF_ENDPOINT ?? HUB_URL,
+					});
+					console.log(`Repository '${repoName}' deleted successfully.`);
+					break;
+				}
+				default:
+					// This case should ideally be caught by the check above
+					console.error(`Error: Unknown subcommand '${currentSubCommandName}' for 'repo'.`);
+					console.log(listSubcommands("repo", repoCommandGroup));
+					process.exitCode = 1;
+					break;
+			}
+			break;
+		}
 		case "version": {
 			if (cliArgs[0] === "--help" || cliArgs[0] === "-h") {
 				console.log(detailedUsageForCommand("version"));

packages/hub/src/index.ts

@@ -18,6 +18,7 @@ export type {
 	SpaceStage,
 } from "./types/public";
 export { HubApiError, InvalidApiResponseFormatError } from "./error";
+export { HUB_URL } from "./consts";
 /**
  * Only exported for E2Es convenience
  */

packages/inference/README.md

@@ -53,7 +53,7 @@ Currently, we support the following providers:
 - [HF Inference](https://huggingface.co/docs/inference-providers/providers/hf-inference)
 - [Hyperbolic](https://hyperbolic.xyz)
 - [Nebius](https://studio.nebius.ai)
-- [Novita](https://novita.ai/?utm_source=github_huggingface&utm_medium=github_readme&utm_campaign=link)
+- [Novita](https://novita.ai)
 - [Nscale](https://nscale.com)
 - [OVHcloud](https://endpoints.ai.cloud.ovh.net/)
 - [Replicate](https://replicate.com)
@@ -96,6 +96,7 @@ Only a subset of models are supported when requesting third-party providers. You
 - [Cohere supported models](https://huggingface.co/api/partners/cohere/models)
 - [Cerebras supported models](https://huggingface.co/api/partners/cerebras/models)
 - [Groq supported models](https://console.groq.com/docs/models)
+- [Novita AI supported models](https://huggingface.co/api/partners/novita/models)
 
 ❗**Important note:** To be compatible, the third-party API must adhere to the "standard" shape API we expect on HF model pages for each pipeline task type.
 This is not an issue for LLMs as everyone converged on the OpenAI API anyways, but can be more tricky for other tasks like "text-to-image" or "automatic-speech-recognition" where there exists no standard API. Let us know if any help is needed or if we can make things easier for you!
@@ -119,6 +120,108 @@ await textGeneration({
 
 This will enable tree-shaking by your bundler.
 
+### Error handling
+
+The inference package provides specific error types to help you handle different error scenarios effectively.
+
+#### Error Types
+
+The package defines several error types that extend the base `Error` class:
+
+- `InferenceClientError`: Base error class for all Hugging Face Inference errors
+- `InferenceClientInputError`: Thrown when there are issues with input parameters
+- `InferenceClientProviderApiError`: Thrown when there are API-level errors from providers
+- `InferenceClientHubApiError`: Thrown when there are API-levels errors from the Hugging Face Hub
+- `InferenceClientProviderOutputError`: Thrown when there are issues with providers' API responses format
+
+### Example Usage
+
+```typescript
+import { InferenceClient } from "@huggingface/inference";
+import {
+  InferenceClientError,
+  InferenceClientProviderApiError,
+  InferenceClientProviderOutputError,
+  InferenceClientHubApiError,
+} from "@huggingface/inference";
+
+const client = new InferenceClient();
+
+try {
+  const result = await client.textGeneration({
+    model: "gpt2",
+    inputs: "Hello, I'm a language model",
+  });
+} catch (error) {
+  if (error instanceof InferenceClientProviderApiError) {
+    // Handle API errors (e.g., rate limits, authentication issues)
+    console.error("Provider API Error:", error.message);
+    console.error("HTTP Request details:", error.request);
+    console.error("HTTP Response details:", error.response);
+  if (error instanceof InferenceClientHubApiError) {
+    // Handle API errors (e.g., rate limits, authentication issues)
+    console.error("Hub API Error:", error.message);
+    console.error("HTTP Request details:", error.request);
+    console.error("HTTP Response details:", error.response);
+  } else if (error instanceof InferenceClientProviderOutputError) {
+    // Handle malformed responses from providers
+    console.error("Provider Output Error:", error.message);
+  } else if (error instanceof InferenceClientInputError) {
+    // Handle invalid input parameters
+    console.error("Input Error:", error.message);
+  } else {
+    // Handle unexpected errors
+    console.error("Unexpected error:", error);
+  }
+}
+
+/// Catch all errors from @huggingface/inference
+try {
+  const result = await client.textGeneration({
+    model: "gpt2",
+    inputs: "Hello, I'm a language model",
+  });
+} catch (error) {
+  if (error instanceof InferenceClientError) {
+    // Handle errors from @huggingface/inference
+    console.error("Error from InferenceClient:", error);
+  } else {
+    // Handle unexpected errors
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+### Error Details
+
+#### InferenceClientProviderApiError
+
+This error occurs when there are issues with the API request when performing inference at the selected provider.
+
+It has several properties:
+- `message`: A descriptive error message
+- `request`: Details about the failed request (URL, method, headers)
+- `response`: Response details including status code and body
+
+#### InferenceClientHubApiError
+
+This error occurs when there are issues with the API request when requesting the Hugging Face Hub API.
+
+It has several properties:
+- `message`: A descriptive error message
+- `request`: Details about the failed request (URL, method, headers)
+- `response`: Response details including status code and body
+
+
+#### InferenceClientProviderOutputError
+
+This error occurs when a provider returns a response in an unexpected format.
+
+#### InferenceClientInputError
+
+This error occurs when input parameters are invalid or missing. The error message describes what's wrong with the input.
+
+
 ### Natural Language Processing
 
 #### Text Generation

packages/inference/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@huggingface/inference",
-	"version": "3.14.0",
+	"version": "4.0.0",
 	"packageManager": "[email protected]",
 	"license": "MIT",
 	"author": "Hugging Face and Tim Mikeladze <[email protected]>",