gambi-sdk

TypeScript SDK for Gambi - a distributed LLM coordination system.

Installation

npm install gambi-sdk

or

bun add gambi-sdk

or

pnpm add gambi-sdk

Overview

The SDK provides organized namespaces for interacting with Gambi hubs:

• rooms - Manage rooms and participants
• participants - Create and configure participants
• hub - Create and manage hubs
• createClient - HTTP client for remote hubs
• Types - Full TypeScript type definitions

Quick Start

Creating a Local Hub

import { hub, rooms, participants } from "gambi-sdk";

// Create a hub
const myHub = hub.create({ port: 3000 });
console.log(`Hub running at ${myHub.url}`);

// Create a room
const room = rooms.create("My AI Room", "host-id-123");
console.log(`Room code: ${room.code}`);

// Create and add a participant
const participant = participants.create({
  nickname: "Local Ollama",
  model: "llama3",
  endpoint: "http://localhost:11434",
  specs: {
    gpu: "RTX 4090",
    vram: 24,
  },
});

rooms.addParticipant(room.id, participant);

Using the HTTP Client

Connect to a remote Gambi hub:

import { createClient } from "gambi-sdk";

const client = createClient({ hubUrl: "http://hub.example.com:3000" });

// Create a room
const { room, hostId } = await client.create("Remote Room");

// Join the room
await client.join(room.code, {
  id: "participant-1",
  nickname: "My Bot",
  model: "gpt-4",
  endpoint: "http://localhost:11434",
});

// Get participants
const participants = await client.getParticipants(room.code);

// Health check
await client.healthCheck(room.code, "participant-1");

// Leave the room
await client.leave(room.code, "participant-1");

With Vercel AI SDK

Use Gambi as an AI provider:

import { createGambi } from "gambi-sdk";
import { generateText } from "ai";

const gambi = createGambi({ roomCode: "ABC123" });

const result = await generateText({
  model: gambi.any(), // Defaults to OpenResponses
  prompt: "Hello, world!",
});

const legacy = createGambi({
  roomCode: "ABC123",
  defaultProtocol: "chatCompletions",
});

const legacyResult = await generateText({
  model: legacy.any(),
  prompt: "Use explicit legacy chat/completions mode",
});

Local Network Discovery

For local Node.js or Bun applications, you can resolve a room first and keep the provider/client creation explicit:

import { createGambi, resolveGambiTarget } from "gambi-sdk";
// or import only discovery (smaller import, no AI SDK needed at runtime):
// import { resolveGambiTarget } from "gambi-sdk/discovery";

const target = await resolveGambiTarget({
  roomCode: "ABC123",
});

const gambi = createGambi({
  hubUrl: target.hubUrl,
  roomCode: target.roomCode,
});

The SDK also exposes discoverHubs() and discoverRooms() if you want to build your own room picker UI. All discovery functions are available from the root export or from gambi-sdk/discovery.

API Reference

rooms

Manage rooms and participants:

// Create a room
const room = rooms.create(name, hostId);

// Get rooms
const room = rooms.get(id);
const room = rooms.getByCode(code);
const allRooms = rooms.list();
const roomsWithCount = rooms.listWithParticipantCount();

// Remove a room
rooms.remove(id);

// Participant management
rooms.addParticipant(roomId, participant);
rooms.removeParticipant(roomId, participantId);
rooms.getParticipants(roomId);
rooms.getParticipant(roomId, participantId);
rooms.updateParticipantStatus(roomId, participantId, status);
rooms.updateLastSeen(roomId, participantId);

// Find participants
rooms.findParticipantByModel(roomId, modelName);
rooms.getRandomOnlineParticipant(roomId);

// Maintenance
rooms.checkStaleParticipants();
rooms.clear(); // Testing only

participants

Create and configure participants:

// Create a participant
const participant = participants.create({
  nickname: "Bot Name",
  model: "llama3",
  endpoint: "http://localhost:11434",
  specs: {
    gpu: "RTX 4090",
    vram: 24,
    ram: 64,
    cpu: "AMD Ryzen 9",
  },
  config: {
    temperature: 0.7,
    max_tokens: 2048,
  },
});

// Merge configurations
const merged = participants.mergeConfig(baseConfig, overrides);

hub

Create and manage hubs:

const myHub = hub.create({
  port: 3000,
  hostname: "0.0.0.0",
  mdns: true,
  cors: ["*"],
});

// Hub provides: server, url, mdnsName, close()
console.log(myHub.url); // http://0.0.0.0:3000
myHub.close(); // Cleanup

createClient

HTTP client for remote hubs:

const client = createClient({ hubUrl: "http://hub:3000" });

// Create room
const { room, hostId } = await client.create("Room Name");

// List rooms
const rooms = await client.list();

// Join room
const { participant, roomId } = await client.join(code, {
  id: "participant-id",
  nickname: "Bot",
  model: "llama3",
  endpoint: "http://localhost:11434",
});

// Leave room
await client.leave(code, participantId);

// Get participants
const participants = await client.getParticipants(code);

// Health check
await client.healthCheck(code, participantId);

Types

All core types are re-exported:

import type {
  RoomInfo,
  ParticipantInfo,
  ParticipantStatus,
  GenerationConfig,
  MachineSpecs,
  HubConfig,
  NetworkConfig,
} from "gambi-sdk";

Runtime Validation

Zod schemas are exported with Schema suffix:

import {
  ParticipantInfoSchema,
  RoomInfoSchema,
  GenerationConfigSchema,
} from "gambi-sdk";

// Validate at runtime
const result = ParticipantInfoSchema.parse(data);

Tree-shaking

Import only what you need for optimal bundle size:

// Import specific namespaces
import { rooms, participants, hub } from "gambi-sdk";

// Or destructure what you need
import { createClient, createGambi } from "gambi-sdk";

Modern bundlers (webpack, esbuild, rollup) will tree-shake unused exports.

Architecture

The SDK is a zero-duplication wrapper around @gambi/core:

• types.ts - Re-exports all core types
• protocol.ts - Re-exports protocol messages
• rooms.ts - Re-exports Room namespace
• participants.ts - Re-exports Participant namespace
• hub.ts - Re-exports Hub creation
• utils.ts - Re-exports utilities (logo, etc)
• client.ts - NEW: HTTP client implementation

Philosophy: Core contains implementation, SDK is the user-facing API.

Examples

Complete Workflow

import { hub, rooms, participants } from "gambi-sdk";

// 1. Create hub
const myHub = hub.create({ port: 3000 });

// 2. Create room
const room = rooms.create("AI Collaboration", "host-123");

// 3. Add participants
const bot1 = participants.create({
  nickname: "Llama 3",
  model: "llama3",
  endpoint: "http://localhost:11434",
});

const bot2 = participants.create({
  nickname: "GPT-4",
  model: "gpt-4",
  endpoint: "http://localhost:11435",
});

rooms.addParticipant(room.id, bot1);
rooms.addParticipant(room.id, bot2);

// 4. List participants
const allParticipants = rooms.getParticipants(room.id);
console.log(`${allParticipants.length} participants in room`);

// 5. Cleanup
myHub.close();

Health Checks

// Send periodic health checks
setInterval(() => {
  rooms.updateLastSeen(roomId, participantId);
}, 10_000);

// Check for stale participants
const stale = rooms.checkStaleParticipants();
for (const { roomId, participantId } of stale) {
  console.log(`Participant ${participantId} is offline`);
}

Error Handling

import { ClientError } from "gambi-sdk";

try {
  await client.join("INVALID", participant);
} catch (error) {
  if (error instanceof ClientError) {
    console.error(`HTTP ${error.status}: ${error.message}`);
    console.error(error.response); // Original response data
  }
}

Testing

bun test

License

MIT