npm package: @plimver/sdk
Description: Official TypeScript SDK for Plimver AI Platform - Unified LLM, RAG, and Memory API
Author: Plimver Team
Latest version: 1.0.0

# @plimver/sdk

Official TypeScript SDK for the **Plimver AI Platform** - Unified LLM, RAG, and Memory API.

## Installation

```bash
npm install @plimver/sdk
# or
pnpm add @plimver/sdk
# or
yarn add @plimver/sdk
```

## Quick Start

```typescript
import { Plimver } from '@plimver/sdk';
// or: import { PlimverClient } from '@plimver/sdk';

const plimver = new Plimver({
  apiKey: 'pk_live_your_api_key',
  workspaceId: 'ws_your_workspace_id'
});

// Simple chat
const response = await plimver.chat('What is machine learning?');
console.log(response.text);
```

## Features

- ✅ **Type-safe** - Full TypeScript support with auto-completion
- ✅ **Streaming** - Async generator for real-time responses
- ✅ **Multimodal** - Images, audio, and video support
- ✅ **RAG** - Document upload and vector search
- ✅ **Memory** - Conversation history management
- ✅ **Retries** - Built-in retry with exponential backoff
- ✅ **22+ LLM Providers** - OpenAI, Anthropic, Google, Groq, and more

## Usage Examples

### Basic Chat

```typescript
// Simple message
const response = await plimver.chat('Hello!');
console.log(response.text);

// With options
const response = await plimver.chat('Explain quantum computing', {
  mode: 'chat_and_rag',  // Use RAG for context
  model: 'gpt-4o',       // Specific model
  temperature: 0.5,
  userId: 'user-123'     // Isolate conversation
});
```

### Conversation History

```typescript
const response = await plimver.chatWithMessages([
  { role: 'user', content: 'My name is Alice' },
  { role: 'assistant', content: 'Nice to meet you, Alice!' },
  { role: 'user', content: 'What is my name?' }
]);

console.log(response.text); // "Your name is Alice"
```

### Streaming

```typescript
// Stream response token by token
for await (const chunk of plimver.stream('Tell me a story')) {
  process.stdout.write(chunk.content || '');
}

// With options
for await (const chunk of plimver.stream('Write a poem', { 
  mode: 'chat_only',
  model: 'claude-3-5-sonnet'
})) {
  if (chunk.done) {
    console.log('\n\nTokens used:', chunk.usage?.total_tokens);
  } else {
    process.stdout.write(chunk.content || '');
  }
}
```

### Vision (Images)

```typescript
// Analyze an image
const response = await plimver.vision(
  'What do you see in this image?',
  'https://example.com/photo.jpg'
);

// With base64
const response = await plimver.vision(
  'Describe this diagram',
  'data:image/png;base64,iVBORw0KGgo...'
);
```

### Audio

```typescript
// Transcribe or analyze audio (requires Gemini 1.5 Pro+)
const response = await plimver.audio(
  'Transcribe this audio and summarize it',
  'https://example.com/audio.mp3',
  { model: 'gemini-1.5-pro' }
);
```

### Video

```typescript
// Analyze video (requires Gemini 1.5 Pro+)
const response = await plimver.video(
  'What happens in this video?',
  'https://example.com/video.mp4',
  { model: 'gemini-1.5-pro' }
);
```

### RAG Documents

```typescript
// Upload a document
await plimver.documents.upload(
  'Plimver is an AI platform that provides unified LLM access...',
  { source: 'about-plimver.txt' }
);

// Upload a file (Node.js)
import { readFileSync } from 'fs';
const file = readFileSync('document.pdf');
await plimver.documents.uploadFile(file, 'document.pdf');

// List documents
const docs = await plimver.documents.list();
console.log(`${docs.length} documents indexed`);

// Search documents
const results = await plimver.documents.search('what is plimver', 5);
results.forEach(r => console.log(r.source, r.score));

// Delete a document
await plimver.documents.delete('about-plimver.txt');
```

### Memory Management

```typescript
// Get conversation history for a user
const messages = await plimver.memory.get('user-123', 50);

// Clear user's history
await plimver.memory.clear('user-123');

// Clear all history (danger!)
await plimver.memory.clearAll();
```

### Routing Modes

```typescript
// Auto (smart routing based on query)
await plimver.chat('Hello', { mode: 'auto' });

// Chat only (no RAG, no memory)
await plimver.chat('Hello', { mode: 'chat_only' });

// RAG only (search documents, no memory)
await plimver.chat('What is in my docs?', { mode: 'rag_only' });

// Chat + RAG (full context)
await plimver.chat('Summarize my documents', { mode: 'chat_and_rag' });
```

### Error Handling

```typescript
import { Plimver, PlimverError } from '@plimver/sdk';

try {
  const response = await plimver.chat('Hello');
} catch (error) {
  if (error instanceof PlimverError) {
    console.error(`API Error ${error.status}: ${error.message}`);
  } else {
    throw error;
  }
}
```

## Configuration

```typescript
const plimver = new Plimver({
  // Required
  apiKey: 'pk_live_...',
  workspaceId: 'ws_...',
  
  // Optional
  baseUrl: 'https://api.plimvr.tech',  // Custom API URL
  timeout: 30000,                       // Request timeout (ms)
  maxRetries: 2,                        // Retry on failure
});
```

## Supported Models

The SDK works with any model configured in your workspace:

| Provider | Models |
|----------|--------|
| OpenAI | gpt-4o, gpt-4o-mini, gpt-4-turbo |
| Anthropic | claude-3-5-sonnet, claude-3-opus |
| Google | gemini-2.0-flash, gemini-1.5-pro |
| Groq | llama-3.1-70b, mixtral-8x7b |
| DeepSeek | deepseek-chat, deepseek-coder |
| xAI | grok-beta |
| + 15 more... | |

## License

MIT © Plimver Team