gambiarra-sdk 0.1.4

package/README.md

@@ -0,0 +1,356 @@
+# gambiarra
+
+[![npm version](https://img.shields.io/npm/v/gambiarra)](https://www.npmjs.com/package/gambiarra)
+[![npm downloads](https://img.shields.io/npm/dm/gambiarra)](https://www.npmjs.com/package/gambiarra)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScript SDK for Gambiarra - a distributed LLM coordination system.
+
+## Installation
+
+```bash
+npm install gambiarra
+```
+
+or
+
+```bash
+bun add gambiarra
+```
+
+or
+
+```bash
+pnpm add gambiarra
+```
+
+## Overview
+
+The SDK provides organized namespaces for interacting with Gambiarra 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
+
+```typescript
+import { hub, rooms, participants } from "gambiarra";
+
+// 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 Gambiarra hub:
+
+```typescript
+import { createClient } from "gambiarra";
+
+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 Gambiarra as an AI provider:
+
+```typescript
+import { createGambiarra } from "gambiarra";
+import { generateText } from "ai";
+
+const gambiarra = createGambiarra({ roomCode: "ABC123" });
+
+const result = await generateText({
+  model: gambiarra.any(), // Random online participant
+  prompt: "Hello, world!",
+});
+```
+
+## API Reference
+
+### `rooms`
+
+Manage rooms and participants:
+
+```typescript
+// 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:
+
+```typescript
+// 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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+import type {
+  RoomInfo,
+  ParticipantInfo,
+  ParticipantStatus,
+  GenerationConfig,
+  MachineSpecs,
+  HubConfig,
+  NetworkConfig,
+} from "gambiarra";
+```
+
+### Runtime Validation
+
+Zod schemas are exported with `Schema` suffix:
+
+```typescript
+import {
+  ParticipantInfoSchema,
+  RoomInfoSchema,
+  GenerationConfigSchema,
+} from "gambiarra";
+
+// Validate at runtime
+const result = ParticipantInfoSchema.parse(data);
+```
+
+## Tree-shaking
+
+Import only what you need for optimal bundle size:
+
+```typescript
+// Import specific namespaces
+import { rooms, participants, hub } from "gambiarra";
+
+// Or destructure what you need
+import { createClient, createGambiarra } from "gambiarra";
+```
+
+Modern bundlers (webpack, esbuild, rollup) will tree-shake unused exports.
+
+## Architecture
+
+The SDK is a **zero-duplication wrapper** around `@gambiarra/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
+
+```typescript
+import { hub, rooms, participants } from "gambiarra";
+
+// 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
+
+```typescript
+// 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
+
+```typescript
+import { ClientError } from "gambiarra";
+
+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
+
+```bash
+bun test
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,90 @@
+import type { ParticipantInfo, RoomInfo } from "./types.ts";
+/**
+ * Options for creating a Gambiarra HTTP client
+ */
+export interface ClientOptions {
+    /** Base URL of the hub (default: http://localhost:3000) */
+    hubUrl?: string;
+}
+/**
+ * Options for creating a participant
+ */
+export interface CreateParticipantOptions {
+    id: string;
+    nickname: string;
+    model: string;
+    endpoint: string;
+    specs?: ParticipantInfo["specs"];
+    config?: ParticipantInfo["config"];
+}
+/**
+ * Response when creating a room
+ */
+export interface CreateRoomResponse {
+    room: RoomInfo;
+    hostId: string;
+}
+/**
+ * Response when joining a room
+ */
+export interface JoinRoomResponse {
+    participant: ParticipantInfo;
+    roomId: string;
+}
+/**
+ * HTTP client for interacting with a remote Gambiarra hub
+ *
+ * Provides methods for managing rooms and participants via HTTP.
+ */
+export interface GambiarraClient {
+    /** Create a new room */
+    create(name: string): Promise<CreateRoomResponse>;
+    /** List all rooms */
+    list(): Promise<RoomInfo[]>;
+    /** Join a room as a participant */
+    join(code: string, participant: CreateParticipantOptions): Promise<JoinRoomResponse>;
+    /** Leave a room */
+    leave(code: string, participantId: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get all participants in a room */
+    getParticipants(code: string): Promise<ParticipantInfo[]>;
+    /** Send health check for a participant */
+    healthCheck(code: string, participantId: string): Promise<{
+        success: boolean;
+    }>;
+}
+/**
+ * Error thrown when a client request fails
+ */
+export declare class ClientError extends Error {
+    readonly status: number;
+    readonly response?: unknown;
+    constructor(message: string, status: number, response?: unknown);
+}
+/**
+ * Create a new Gambiarra HTTP client
+ *
+ * @param options - Client configuration options
+ * @returns A client instance for interacting with the hub
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from "gambiarra-sdk/client";
+ *
+ * const client = createClient({ hubUrl: "http://hub.example.com:3000" });
+ *
+ * // Create a room
+ * const { room, hostId } = await client.create("My Room");
+ *
+ * // Join the room
+ * await client.join(room.code, {
+ *   id: "participant-1",
+ *   nickname: "Bot",
+ *   model: "llama3",
+ *   endpoint: "http://localhost:11434"
+ * });
+ * ```
+ */
+export declare function createClient(options?: ClientOptions): GambiarraClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,eAAe,CAAC;IAC7B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAElD,qBAAqB;IACrB,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE5B,mCAAmC;IACnC,IAAI,CACF,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,wBAAwB,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE7B,mBAAmB;IACnB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAE1E,qCAAqC;IACrC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IAE1D,0CAA0C;IAC1C,WAAW,CACT,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO;CAMhE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,eAAe,CAyEzE"}

package/dist/hub.d.ts

@@ -0,0 +1,13 @@
+export { type ChatCompletionRequest, createHub, type GambiarraModel, type Hub, type HubOptions, type ModelsListResponse, } from "@gambiarra/core/hub";
+/**
+ * Hub management namespace
+ *
+ * Provides functions for creating and managing Gambiarra hubs.
+ * A hub is the central server that manages rooms, participants, and proxies LLM requests.
+ */
+export declare const hub: {
+    /** Create a new Gambiarra hub */
+    readonly create: typeof createHub;
+};
+import { createHub } from "@gambiarra/core/hub";
+//# sourceMappingURL=hub.d.ts.map

package/dist/hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub.d.ts","sourceRoot":"","sources":["../src/hub.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,SAAS,EACT,KAAK,cAAc,EACnB,KAAK,GAAG,EACR,KAAK,UAAU,EACf,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAE7B;;;;;GAKG;AACH,eAAO,MAAM,GAAG;IACd,iCAAiC;;CAEzB,CAAC;AAGX,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { ClientError, createClient, type GambiarraClient } from "./client.ts";
+export type { ChatCompletionRequest, GambiarraModel, Hub, HubOptions, ModelsListResponse, } from "./hub.ts";
+export { hub } from "./hub.ts";
+export { participants } from "./participants.ts";
+export type * from "./protocol.ts";
+export { createGambiarra, type GambiarraOptions, type GambiarraProvider, } from "./provider.ts";
+export { rooms } from "./rooms.ts";
+export type * from "./types.ts";
+export * from "./types.ts";
+export * from "./utils.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9E,YAAY,EACV,qBAAqB,EACrB,cAAc,EACd,GAAG,EACH,UAAU,EACV,kBAAkB,GACnB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,mBAAmB,eAAe,CAAC;AAEnC,OAAO,EACL,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,mBAAmB,YAAY,CAAC;AAChC,cAAc,YAAY,CAAC;AAE3B,cAAc,YAAY,CAAC"}