client/README.md

RobotHub Inference Server TypeScript Client

A TypeScript client for the RobotHub Inference Server, providing ACT (Action Chunking Transformer) model inference and session management capabilities.

Features

• ✅ Fully Generated: Client is 100% generated from OpenAPI spec
• 🔒 Type Safe: Complete TypeScript support with generated types
• 🚀 Modern: Built with Bun and modern JavaScript features
• 📦 Lightweight: Minimal dependencies, uses fetch API
• 🛠️ Developer Friendly: Comprehensive examples and documentation

Installation

# Install dependencies
bun install

# Generate client from OpenAPI spec
bun run generate

# Build the client
bun run build

Quick Start

import { RobotHubInferenceClient, CreateSessionRequest } from '@robothub/inference-server-client';

// Create client
const client = new RobotHubInferenceClient('http://localhost:8001');

// Check server health
const isHealthy = await client.isHealthy();
if (!isHealthy) {
  console.error('Server is not available');
  process.exit(1);
}

// Create and start a session
const sessionRequest: CreateSessionRequest = {
  session_id: 'my-robot-session',
  policy_path: 'LaetusH/act_so101_beyond',
  camera_names: ['front', 'wrist'],
  transport_server_url: 'http://localhost:8000'
};

const session = await client.createSession(sessionRequest);
await client.startInference('my-robot-session');

// Monitor session
const status = await client.getSessionStatus('my-robot-session');
console.log(`Status: ${status.status}`);

// Clean up
await client.deleteSession('my-robot-session');

API Reference

Client Creation

const client = new RobotHubInferenceClient(baseUrl: string);

Health Check Methods

• isHealthy(): Quick boolean health check
• getHealth(): Detailed health information

Session Management

• createSession(request: CreateSessionRequest): Create inference session
• listSessions(): List all active sessions
• getSessionStatus(sessionId: string): Get session details
• deleteSession(sessionId: string): Delete session and cleanup

Inference Control

• startInference(sessionId: string): Start model inference
• stopInference(sessionId: string): Stop model inference
• restartInference(sessionId: string): Restart model inference

Utility Methods

• waitForSessionStatus(sessionId, targetStatus, timeout): Wait for status change
• createAndStartSession(request): Create session and start inference in one call

Debug Methods

• getSystemInfo(): Get server system information
• debugResetSession(sessionId: string): Reset session state
• getSessionQueueInfo(sessionId: string): Get action queue details

Generated Types

All types are generated from the OpenAPI specification:

import type { 
  CreateSessionRequest,
  CreateSessionResponse,
  SessionStatusResponse,
  // ... all other types
} from '@robothub/inference-server-client';

Key types:

• CreateSessionRequest: Session creation parameters
• CreateSessionResponse: Session creation result with room IDs
• SessionStatusResponse: Complete session status and statistics

Examples

Basic Usage

bun run examples/basic-usage.ts

Quick Example

bun run examples/basic-usage.ts --quick

Development

Scripts

• bun run generate: Export OpenAPI schema and generate client
• bun run build: Build the client distribution
• bun run typecheck: Run TypeScript type checking
• bun run test: Run tests
• bun run clean: Clean generated files and dist

Regenerating Client

The client is automatically regenerated when you run bun run build. To manually regenerate:

# Export latest OpenAPI schema from inference server
bun run export-openapi

# Generate TypeScript client from schema
bun run generate-client

File Structure

client/
├── src/
│   ├── generated/          # Auto-generated from OpenAPI
│   │   ├── index.ts        # Generated exports
│   │   ├── services.gen.ts # Generated API methods
│   │   ├── types.gen.ts    # Generated TypeScript types
│   │   └── schemas.gen.ts  # Generated schemas
│   └── index.ts            # Main client wrapper
├── examples/
│   └── basic-usage.ts      # Usage examples
├── dist/                   # Built files
├── openapi.json           # Latest OpenAPI schema
└── package.json

Requirements

• Bun >= 1.0.0 (for development and building)
• RobotHub Inference Server running on target URL
• RobotHub Transport Server for communication rooms

Communication Architecture

The inference server uses the RobotHub communication system:

1. Camera Rooms: Receive video streams (supports multiple cameras)
2. Joint Input Room: Receives current robot joint positions (normalized -100 to +100)
3. Joint Output Room: Sends predicted joint commands (normalized -100 to +100)

All rooms are created in the same workspace for session isolation.

Error Handling

All client methods throw descriptive errors on failure:

try {
  await client.createSession(request);
} catch (error) {
  console.error('Session creation failed:', error.message);
}

Contributing

This client is auto-generated from the OpenAPI specification. To make changes:

1. Update the inference server's FastAPI endpoints
2. Regenerate the client: bun run generate
3. Update examples and documentation as needed

License

Apache 2.0 - See LICENSE file for details.