API Reference - Gambiarra

Comprehensive reference for all exported functions, types, and interfaces in the Gambiarra SDK.

createGambiarra()

Creates a Gambiarra provider for use with Vercel AI SDK.

function createGambiarra(options: GambiarraOptions): GambiarraProvider

Parameters

options

GambiarraOptions

required

Configuration options for the provider

Show GambiarraOptions

roomCode

string

required

The 6-character room code to connect to

hubUrl

string

default:"http://localhost:3000"

Base URL of the Gambiarra hub

Returns

GambiarraProvider

object

Provider interface with routing methods and utilities

Show GambiarraProvider

participant

(id: string) => LanguageModel

Route to a specific participant by ID

model

(name: string) => LanguageModel

Route to the first participant running the specified model

any

() => LanguageModel

Route to any random online participant

listParticipants

() => Promise<ParticipantInfo[]>

List all participants in the room

listModels

() => Promise<GambiarraModel[]>

List available models in OpenAI-compatible format

baseURL

string

Base URL for direct OpenAI-compatible API access

Example

import { createGambiarra } from "gambiarra-sdk";
import { generateText } from "ai";

const gambiarra = createGambiarra({ roomCode: "ABC123" });

const result = await generateText({
  model: gambiarra.any(),
  prompt: "Hello!",
});

Provider Methods

participant()

Route requests to a specific participant by ID.

participant(id: string): LanguageModel

string

required

The unique identifier of the participant

Example

const result = await generateText({
  model: gambiarra.participant("participant-123"),
  prompt: "Route to specific machine",
});

model()

Route requests to the first online participant running the specified model.

model(name: string): LanguageModel

name

string

required

The model name to match (e.g., “llama3”, “gpt-4”)

Example

const result = await generateText({
  model: gambiarra.model("llama3"),
  prompt: "Use Llama 3 model",
});

The model name is prefixed with model: internally, so gambiarra.model("llama3") becomes model:llama3 in the routing layer.

any()

Route requests to any random online participant.

any(): LanguageModel

Example

const result = await generateText({
  model: gambiarra.any(),
  prompt: "Use any available participant",
});

Internally uses the model ID * which the hub interprets as “any random online participant”.

listParticipants()

Retrieve all participants in the room.

listParticipants(): Promise<ParticipantInfo[]>

Returns

participants

ParticipantInfo[]

Array of participant information objects

Show ParticipantInfo

string

Unique participant identifier

nickname

string

Human-readable participant name

model

string

Model name (e.g., “llama3”, “gpt-4”)

endpoint

string

OpenAI-compatible endpoint URL

status

'online' | 'offline'

Current online status

lastSeen

number

Timestamp of last health check (Unix milliseconds)

specs

MachineSpecs

Hardware specifications

Show MachineSpecs

gpu

string

GPU model (e.g., “RTX 4090”)

vram

number

VRAM in GB

ram

number

System RAM in GB

cpu

string

CPU model

config

GenerationConfig

Default generation configuration

Show GenerationConfig

temperature

number

Sampling temperature (0.0 to 2.0)

max_tokens

number

Maximum tokens to generate

top_p

number

Nucleus sampling threshold

frequency_penalty

number

Frequency penalty (-2.0 to 2.0)

presence_penalty

number

Presence penalty (-2.0 to 2.0)

Example

const participants = await gambiarra.listParticipants();

participants.forEach((p) => {
  console.log(`${p.nickname}: ${p.status}`);
  if (p.specs) {
    console.log(`  GPU: ${p.specs.gpu}, VRAM: ${p.specs.vram}GB`);
  }
});

listModels()

Retrieve available models in OpenAI-compatible format.

listModels(): Promise<GambiarraModel[]>

Returns

models

GambiarraModel[]

Array of model information objects

Show GambiarraModel

string

Model identifier (participant ID in Gambiarra)

nickname

string

Participant nickname

model

string

Actual model name (e.g., “llama3”)

endpoint

string

OpenAI-compatible endpoint URL

Example

const models = await gambiarra.listModels();

models.forEach((m) => {
  console.log(`${m.id}: ${m.model} at ${m.endpoint}`);
});

HTTP Client

createClient()

Create an HTTP client for managing rooms and participants.

function createClient(options?: ClientOptions): GambiarraClient

Parameters

options

ClientOptions

Client configuration options

Show ClientOptions

hubUrl

string

default:"http://localhost:3000"

Base URL of the Gambiarra hub

Returns

GambiarraClient

object

Client interface with room and participant management methods

Example

import { createClient } from "gambiarra-sdk";

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

Client Methods

create()

Create a new room.

create(name: string, password?: string): Promise<CreateRoomResponse>

name

string

required

Human-readable room name

password

string

Optional password for room protection

Returns

response

CreateRoomResponse

Show CreateRoomResponse

room

RoomInfo

Created room information

Show RoomInfo

string

Unique room identifier

code

string

6-character room code

name

string

Room name

createdAt

number

Creation timestamp (Unix milliseconds)

participantCount

number

Number of participants in the room

hostId

string

ID of the host participant

Example

const { room, hostId } = await client.create("My Room", "secret123");
console.log(`Created room: ${room.code}`);

list()

List all rooms on the hub.

list(): Promise<RoomInfo[]>

Returns

rooms

RoomInfo[]

Array of room information objects

Example

const rooms = await client.list();
rooms.forEach((r) => {
  console.log(`${r.name} (${r.code}): ${r.participantCount} participants`);
});

join()

Join a room as a participant.

join(
  code: string,
  participant: CreateParticipantOptions
): Promise<JoinRoomResponse>

code

string

required

6-character room code

participant

CreateParticipantOptions

required

Participant configuration

Show CreateParticipantOptions

string

required

Unique participant identifier

nickname

string

required

Human-readable participant name

model

string

required

Model name (e.g., “llama3”)

endpoint

string

required

OpenAI-compatible endpoint URL

password

string

Room password (required if room is protected)

specs

MachineSpecs

Hardware specifications

config

GenerationConfig

Default generation configuration

Returns

response

JoinRoomResponse

Show JoinRoomResponse

participant

ParticipantInfo

Created participant information

roomId

string

Room identifier

Example

const { participant, roomId } = await client.join("ABC123", {
  id: "my-bot",
  nickname: "My Ollama",
  model: "llama3",
  endpoint: "http://localhost:11434",
  specs: {
    gpu: "RTX 4090",
    vram: 24,
  },
});

leave()

Leave a room.

leave(code: string, participantId: string): Promise<{ success: boolean }>

code

string

required

6-character room code

participantId

string

required

Participant ID to remove

Example

await client.leave("ABC123", "my-bot");
console.log("Left the room");

getParticipants()

Get all participants in a room.

getParticipants(code: string): Promise<ParticipantInfo[]>

code

string

required

6-character room code

Example

const participants = await client.getParticipants("ABC123");
console.log(`${participants.length} participants in room`);

healthCheck()

Send a health check for a participant.

healthCheck(
  code: string,
  participantId: string
): Promise<{ success: boolean }>

code

string

required

6-character room code

participantId

string

required

Participant ID sending the health check

Health checks should be sent every 10 seconds. Participants are marked offline after 30 seconds of inactivity.

Example

setInterval(async () => {
  await client.healthCheck("ABC123", "my-bot");
}, 10_000);

Error Classes

ClientError

Error thrown when HTTP client requests fail.

class ClientError extends Error {
  readonly status: number;
  readonly response?: unknown;
}

status

number

HTTP status code

response

unknown

Original response data from the server

Example

import { ClientError } from "gambiarra-sdk";

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

Type Exports

All core types from @gambiarra/core are re-exported:

import type {
  // Room types
  RoomInfo,
  
  // Participant types
  ParticipantInfo,
  ParticipantStatus,
  
  // Configuration types
  GenerationConfig,
  MachineSpecs,
  HubConfig,
  NetworkConfig,
  OllamaConfig,
  
  // Chat types
  ChatCompletion,
  ChatCompletionChunk,
  ChatCompletionMessage,
  ChatCompletionMessageParam,
  ChatCompletionCreateParams,
  
  // Model types
  Model,
  ModelDeleted,
  LlmMetrics,
} from "gambiarra-sdk";

Schema Exports

Zod schemas for runtime validation (exported with Schema suffix):

import {
  ParticipantInfoSchema,
  RoomInfoSchema,
  GenerationConfigSchema,
  MachineSpecsSchema,
  HubConfigSchema,
  NetworkConfigSchema,
  OllamaConfigSchema,
  ParticipantStatusSchema,
  LlmMetricsSchema,
} from "gambiarra-sdk";

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

Constants

Exported timing constants:

import {
  HEALTH_CHECK_INTERVAL,
  PARTICIPANT_TIMEOUT,
} from "gambiarra-sdk";

console.log(HEALTH_CHECK_INTERVAL); // 10000 (10 seconds)
console.log(PARTICIPANT_TIMEOUT);   // 30000 (30 seconds)

Namespaces

Re-exported namespaces from @gambiarra/core:

rooms

import { rooms } from "gambiarra-sdk";

// Room management
const room = rooms.create("Room Name", "host-id");
const room = rooms.get(id);
const room = rooms.getByCode(code);
const allRooms = rooms.list();
rooms.remove(id);

// Participant management
rooms.addParticipant(roomId, participant);
rooms.removeParticipant(roomId, participantId);
const participants = rooms.getParticipants(roomId);

participants

import { participants } from "gambiarra-sdk";

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

hub

import { hub } from "gambiarra-sdk";

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

console.log(myHub.url); // http://0.0.0.0:3000
myHub.close();

Get Started

CLI Commands

SDK

Terminal UI

Guides

Advanced

​createGambiarra()

​Parameters

​Returns

​Example

​Provider Methods

​participant()

​Example

​model()

​Example

​any()

​Example

​listParticipants()

​Returns

​Example

​listModels()

​Returns

​Example

​HTTP Client

​createClient()

​Parameters

​Returns

​Example

​Client Methods

​create()

​Returns

​Example

​list()

​Returns

​Example

​join()

​Returns

​Example

​leave()

​Example

​getParticipants()

​Example

​healthCheck()

​Example

​Error Classes

​ClientError

​Example

​Type Exports

​Schema Exports

​Constants

​Namespaces

​rooms

​participants

​hub

​Next Steps

Usage Guide

Quickstart

Build docs developers (and LLMs) love

createGambiarra()

Parameters

Returns

Example

Provider Methods

participant()

Example

model()

Example

any()

Example

listParticipants()

Returns

Example

listModels()

Returns

Example

HTTP Client

createClient()

Parameters

Returns

Example

Client Methods

create()

Returns

Example

list()

Returns

Example

join()

Returns

Example

leave()

Example

getParticipants()

Example

healthCheck()

Example

Error Classes

ClientError

Example

Type Exports

Schema Exports

Constants

Namespaces

rooms

participants

hub

Next Steps