CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gradio--client

JavaScript and TypeScript client library for interacting with Gradio APIs, providing methods to connect to, submit predictions to, and manage connections with Gradio applications.

96

1.11x
Quality

Pending

Does it follow best practices?

Impact

96%

1.11x

Average score across 10 eval scenarios

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@gradio/client

The @gradio/client package is a comprehensive JavaScript and TypeScript client library for interacting with Gradio APIs. It provides both simple prediction methods and advanced streaming capabilities, with full support for file handling, real-time status updates, and cross-platform compatibility.

Package Information

  • Package Name: @gradio/client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @gradio/client

Core Imports

import { Client, predict, submit, FileData, MISSING_CREDENTIALS_MSG } from "@gradio/client";

// Deprecated (use Client.connect() and Client.duplicate() instead)
import { client, duplicate_space } from "@gradio/client";

For CommonJS:

const { Client, predict, submit, FileData, MISSING_CREDENTIALS_MSG } = require("@gradio/client");

Environment-specific imports:

// Browser-specific build
import { Client } from "@gradio/client/dist/browser";

// Node.js build (default)
import { Client } from "@gradio/client";

Basic Usage

Quick Start with Client Class

import { Client } from "@gradio/client";

// Connect to a Gradio app
const client = await Client.connect("https://gradio-app-url");

// Make a simple prediction
const result = await client.predict("/predict", ["Hello world"]);
console.log(result.data);

// Clean up
client.close();

Streaming Predictions

import { Client } from "@gradio/client";

const client = await Client.connect("https://gradio-app-url");

// Submit for streaming results  
const job = client.submit("/predict", ["input data"]);
for await (const message of job) {
  if (message.type === "data") {
    console.log("Result:", message.data);
  } else if (message.type === "status") {
    console.log("Status:", message.status);
  }
}

File Upload Example

import { Client, FileData } from "@gradio/client";

const client = await Client.connect("https://gradio-app-url");

// Upload a file
const fileData = new FileData({ 
  path: "./image.jpg",
  orig_name: "my-image.jpg"
});

const result = await client.predict("/upload", [fileData]);
console.log(result.data);

Standalone Functions

import { predict, submit } from "@gradio/client";

// Quick one-off prediction
const result = await predict("https://gradio-app-url", "/predict", ["input"]);

// Streaming with standalone function
const job = submit("https://gradio-app-url", "/predict", ["input"]);
for await (const message of job) {
  console.log(message);
}

Architecture

The @gradio/client library is designed around several key components:

  • Client Class: Main interface for persistent connections with automatic reconnection
  • Standalone Functions: Utility functions for simple, one-off operations
  • File Handling System: Comprehensive file upload and processing capabilities
  • Event Streaming: Real-time updates through WebSocket and Server-Sent Events
  • Type Safety: Full TypeScript integration with comprehensive type definitions
  • Cross-Platform: Works in both browser and Node.js environments

Capabilities

Client Management

Core Client class for establishing and managing connections to Gradio applications, with support for authentication, reconnection, and lifecycle management.

class Client {
  static connect(app_reference: string, options?: ClientOptions): Promise<Client>;
  static duplicate(app_reference: string, options?: DuplicateOptions): Promise<Client>;
  predict(endpoint: string | number, data?: unknown[], event_data?: unknown): Promise<PredictReturn>;
  submit(endpoint: string | number, data?: unknown[], event_data?: unknown): SubmitIterable<GradioEvent>;
  close(): void;
  reconnect(): Promise<"connected" | "broken" | "changed">;
}

interface ClientOptions {
  hf_token?: `hf_${string}`;
  status_callback?: SpaceStatusCallback | null;
  auth?: [string, string] | null;
  with_null_state?: boolean;
  events?: EventType[];
  headers?: Record<string, string>;
  query_params?: Record<string, string>;
  session_hash?: string;
}

Client Class Reference

Standalone Functions

Utility functions for quick operations without persistent connections, perfect for simple use cases and serverless environments.

function predict(
  app_reference: string,
  endpoint: string | number,
  data?: unknown[],
  event_data?: unknown
): Promise<PredictReturn>;

function submit(
  app_reference: string,
  endpoint: string | number,
  data?: unknown[],
  event_data?: unknown
): SubmitIterable<GradioEvent>;

Standalone Functions

File Handling

Comprehensive file processing system supporting multiple input formats, upload operations, and automatic type conversion.

class FileData {
  constructor(data: {
    path?: string;
    url?: string;
    orig_name?: string;
    size?: number;
    blob?: Blob;
    is_stream?: boolean;
    mime_type?: string;
  });
}

function upload_files(
  root_url: string,
  files: (Blob | File)[],
  upload_id?: string
): Promise<UploadResponse>;

function handle_file(file_or_url: File | string | Blob | Buffer): FileData | Blob | Command;

File Operations

Advanced Features

Protocol management, environment-specific optimizations, error handling, and performance tuning for production deployments.

interface GradioEvent {
  type: "data" | "status" | "log" | "render";
  data?: unknown;
  status?: Status;
  log?: string;
}

interface PredictReturn {
  data: unknown[];
  duration?: number;
  average_duration?: number;
}

Advanced Topics

Types

Core type definitions used across the @gradio/client API:

interface ClientOptions {
  hf_token?: string;
  normalise_unicode?: boolean;
  auth?: [string, string];
  headers?: Record<string, string>;
}

interface PredictReturn {
  data: unknown[];
  duration?: number;
  average_duration?: number;
}

interface SubmitIterable<T> extends AsyncIterable<T> {
  cancel: () => Promise<void>;
}

type EventType = "data" | "status" | "log" | "render";

interface GradioEvent {
  type: EventType;
  data?: unknown;
  status?: Status;
  log?: string;
}

Complete Type Reference

Authentication

HuggingFace Token

const client = await Client.connect("space-url", {
  hf_token: "your-hf-token"
});

Basic Auth

const client = await Client.connect("app-url", {
  auth: ["username", "password"]
});

Custom Headers

const client = await Client.connect("app-url", {
  headers: {
    "Authorization": "Bearer your-token",
    "Custom-Header": "value"
  }
});

Constants

The package exports several useful constants for error handling and authentication:

/** Message displayed when authentication credentials are required */
const MISSING_CREDENTIALS_MSG: string;

Usage Example:

import { Client, MISSING_CREDENTIALS_MSG } from "@gradio/client";

try {
  const client = await Client.connect("private-space");
} catch (error) {
  if (error.message === MISSING_CREDENTIALS_MSG) {
    console.log("Authentication required - please provide credentials");
  }
}

Error Handling

try {
  const client = await Client.connect("app-url");
  const result = await client.predict("/endpoint", ["data"]);
} catch (error) {
  if (error.message.includes("queue full")) {
    // Handle queue full error
  } else if (error.message.includes("connection")) {
    // Handle connection error  
  }
}

See Also

docs

advanced.md

client-class.md

file-handling.md

index.md

standalone-functions.md

types.md

tile.json