@orchard9ai/world-api-sdk

TypeScript SDK for the Companion World API - an AI-powered social simulation platform for creating virtual worlds populated with AI-driven agents.

Installation

npm install @orchard9ai/world-api-sdk
# or
yarn add @orchard9ai/world-api-sdk
# or
pnpm add @orchard9ai/world-api-sdk

Quick Start

import { setWorldApiConfig, getWorlds, initializeWorld } from '@orchard9ai/world-api-sdk';

// Configure the SDK
setWorldApiConfig({
  baseURL: 'https://api.companion-world.orchard9.ai',
  accessToken: 'your-jwt-token' // From Warden authentication
});

// Initialize a new world
const world = await initializeWorld({
  name: 'My Virtual World',
  config: {
    startTime: new Date().toISOString(),
    tickInterval: 15,
    timezone: 'America/Los_Angeles',
    planningHorizonMonths: 6
  }
});

// List all worlds
const { worlds } = await getWorlds();
console.log('Available worlds:', worlds);

Configuration

The SDK can be configured with the following options:

setWorldApiConfig({
  baseURL: string;       // API base URL (default: http://localhost:8043)
  apiKey?: string;       // API key for service-to-service auth
  organizationId?: string; // Organization context
  accessToken?: string;  // JWT token from Warden auth
});

Main Features

World Management

• Create and configure virtual worlds
• Update world demographics
• Manage time progression

Agent Management

• Create AI agents with personalities
• List and filter agents
• Update agent properties
• Manage agent media (avatars, galleries)

Population Generation

• Generate populations with demographics
• Track generation jobs
• Get population statistics

Location Management

• Batch load locations
• Configure location properties
• Set operating hours and capacity

Name Pools

• Manage cultural name databases
• Add names with metadata
• Configure name distributions

Authentication

The SDK supports two authentication methods:

1. JWT Token (recommended): Use access tokens from Warden authentication
2. API Key: For service-to-service communication

// JWT authentication (after Warden login)
setWorldApiConfig({
  accessToken: wardenLoginResponse.accessToken
});

// API key authentication
setWorldApiConfig({
  apiKey: 'your-api-key'
});

Error Handling

The SDK provides typed error responses:

try {
  const agent = await getAgentById({ id: 123 });
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Agent not found');
  } else if (error.response?.status === 401) {
    console.error('Authentication required');
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions for all API operations, request parameters, and responses.

API Documentation

For detailed API documentation, see the Companion World API Documentation.

License

MIT