@orchard9ai/world-api-sdk/README.md

TypeScript SDK for Companion World API - AI-powered social simulation platform

# @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

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

## Quick Start

```typescript
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:

```typescript
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

```typescript
// 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:

```typescript
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](https://github.com/adaptive-neural-agent-framework/companion-world-api/tree/main/docs/api).

## License

MIT