vitrus-sdk

Vitrus SDK

A TypeScript client for interfacing with the Vitrus WebSocket server. This library provides an Actor/Agent communication model with workflow orchestration.

Installation

# Using npm
npm install vitrus-sdk

# Using yarn
yarn add vitrus-sdk

# Using bun
bun add vitrus-sdk

Basic Usage

import Vitrus from 'vitrus-sdk';

// Initialize the client
const vitrus = new Vitrus({
  apiKey: "your-api-key",
  world: "world-id",
  baseUrl: "ws://localhost:3001" // Optional, defaults to localhost:3001
});

// Actor example (server-side)
async function runActorExample() {
  const actor = vitrus.actor("asimov");
  
  // Register command handlers
  actor.on("get-camera", () => {
    // Return screenshot or camera data
    return { data: "screenshot-data" };
  });
  
  actor.on("move", (motor: string, angle: number) => {
    // Run the action here
    console.log(`Moving ${motor} to angle ${angle}`);
    return { success: true };
  });
}

// Agent example (client-side)
async function runAgentExample() {
  // Get a scene
  const scene = vitrus.scene("zelda-initial");
  
  // Get a player
  const player = vitrus.actor("player");
  
  // Take a screenshot
  const screenshot = await actor.run("get-screenshot");
  
  // Use Vitrus' perception encoders
  const structure = await vitrus.workflow("perception-encoder", {
    image: screenshot
  });
  
  // Update scene with structure
  scene.set(structure);
  
  // Add object to scene
  scene.add(object);
  
  // Update scene object
  scene.update({
    id: "..."
  });
  
  // Remove object from scene
  scene.remove("object");
  
  // Get scene
  const sceneData = scene.get();
  
  // Upload image
  const imageUrl = await vitrus.upload_image(screenshot, "image");
  
  // Add record
  await vitrus.add_record(screenshot);
  
  // Run player command
  await player.run("press", "START");
}

Running Tests

bun test

Features

• WebSocket client that works in both browser and Node.js environments
• Actor/Agent communication model
• Scene management
• Workflow execution (perception encoders, etc.)
• Command handling between actors and agents
• Asset management (upload images, add records)

API Reference

Vitrus Class

Constructor

new Vitrus({
  apiKey: string,
  world: string,
  baseUrl?: string  // Optional, defaults to "ws://localhost:3001"
})

Methods

• actor(name: string, options?: any): Actor - Create or get an actor
• scene(sceneId: string): Scene - Get a scene
• workflow(workflowName: string, args?: any): Promise<any> - Run a workflow
• upload_image(image: any, filename?: string): Promise<string> - Upload an image
• add_record(data: any, name?: string): Promise<string> - Add a record

Actor Class

Methods

• on(commandName: string, handler: Function): Actor - Register a command handler
• run(commandName: string, ...args: any[]): Promise<any> - Run a command on an actor

Scene Class

Methods

• set(structure: any): void - Set a structure to the scene
• add(object: any): void - Add an object to the scene
• update(params: { id: string, [key: string]: any }): void - Update an object in the scene
• remove(objectId: string): void - Remove an object from the scene
• get(): any - Get the scene

License

MIT