npm package: @molroo-io/sdk
Description: Unified SDK for molroo emotion engine — persona, world, LLM integration
Latest version: 0.9.1

# @molroo-io/sdk

**Thin Client SDK for molroo emotion engine**

Simplified API client with LLM integration for the molroo emotion engine.

## Quick Start

```typescript
import { Molroo } from '@molroo-io/sdk';
import { createOpenAI } from '@ai-sdk/openai';

const molroo = new Molroo({ apiKey: 'mk_live_...' });

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

// Create persona from description
const sera = await molroo.createPersona(
  'A kind and curious barista named Sera who remembers customer names',
  { llm: openai }
);

// Chat
let history: Message[] = [];
const result = await sera.chat('Hello!', { history });
console.log(result.text);  // "Hello! Welcome to our cafe."
history = result.updatedHistory;  // Manage externally
```

## Installation

```bash
npm install @molroo-io/sdk
npm install ai @ai-sdk/openai  # or @ai-sdk/anthropic, @ai-sdk/google-vertex
```

## Features

- **Unified API** — `Molroo` class for persona and world management
- **Vercel AI SDK Integration** — Use any LLM provider (OpenAI, Anthropic, Google, etc.)
- **External History Management** — Simple mode: manage conversation history yourself
- **Advanced Memory (Optional)** — Implement `MemoryAdapter` for semantic search, reflections
- **World Simulation** — Multi-agent environments with channels and interactions

## Usage Modes

### 1. Simple Mode (External History)

```typescript
const molroo = new Molroo({ apiKey: 'mk_...' });
const sera = await molroo.createPersona('...', { llm: openai });

let history = [];
const result = await sera.chat('Hello', { history });
history = result.updatedHistory;
```

### 2. Advanced Mode (MemoryAdapter)

```typescript
class MyPostgresAdapter implements MemoryAdapter {
  async saveEpisode(episode: Episode): Promise<void> {
    // Save to PostgreSQL
  }
  
  async recall(query: RecallQuery): Promise<Episode[]> {
    // Query by filters
  }
  
  async semanticRecall(query: string): Promise<Episode[]> {
    // Vector similarity search
  }
}

const sera = await molroo.createPersona('...', {
  llm: openai,
  memory: new MyPostgresAdapter()
});
```

## World Simulation

```typescript
const world = await molroo.createWorld({ name: 'Cafe' });
const sera = await molroo.createPersona('Barista Sera', { llm: openai });
await world.addPersona({ personaConfigId: sera.id, config: {...} });
```

## Migration from v0.5.x

### Breaking Changes

1. **Unified `create()` method**
   ```typescript
   // Before
   await MolrooPersona.create({...}, {personality: {...}});
   await MolrooPersona.generate({...}, "description");
   
   // After
   await molroo.createPersona({personality: {...}}, {llm});
   await molroo.createPersona("description", {llm});
   ```

2. **External history management**
   ```typescript
   // Before
   await persona.chat("Hello");  // MemoryAdapter required
   
   // After
   let history = [];
   const result = await persona.chat("Hello", {history});
   history = result.updatedHistory;
   ```

3. **Vercel AI SDK directly**
   ```typescript
   // Before
   createVercelAIAdapter({provider: 'openai', ...})
   
   // After
   createOpenAI({...})  // Pass directly
   ```

4. **Removed adapter implementations**
   - SQLite, Supabase, Pinecone adapters removed
   - Implement `MemoryAdapter` interface yourself
   - Or wait for API-hosted memory (coming soon)

## API Reference

See [API documentation](https://docs.molroo.io/sdk) for full reference.

## License

MIT