# Zai - AI Operations Made Simple

Zai is a powerful LLM utility library that provides a clean, type-safe API for common AI operations. Built on Zod schemas and the Botpress API, it makes AI operations simple, intuitive, and production-ready.

## ✨ Key Features

- **🎯 Simple API** - One-liner operations for common AI tasks
- **🔒 Type Safety** - Full TypeScript support with Zod schema validation
- **🧠 Active Learning** - Learn from examples and improve over time
- **⚡ Performance** - Built-in retries, caching, and error handling
- **♾️ Infinite Documents** - Handle any document size with automatic chunking
- **📊 Usage Tracking** - Monitor tokens, costs, and performance

## 📦 Installation

```bash
npm install @botpress/zai @botpress/client @bpinternal/zui
```

## 🚀 Quick Start

```typescript
import { Client } from '@botpress/client'
import { Zai } from '@botpress/zai'
import { z } from '@bpinternal/zui'

// Initialize
const client = new Client({ botId: 'YOUR_BOT_ID', token: 'YOUR_TOKEN' })
const zai = new Zai({ client })

// Extract structured data
const person = await zai.extract(
  'John Doe is 30 years old and lives in New York',
  z.object({
    name: z.string(),
    age: z.number(),
    location: z.string(),
  })
)
// Result: { name: 'John Doe', age: 30, location: 'New York' }

// Check content
const isPositive = await zai.check('This product is amazing!', 'expresses positive sentiment')
// Result: true

// Generate text
const story = await zai.text('Write a short story about AI', { length: 200 })

// Summarize documents
const summary = await zai.summarize(longDocument, { length: 500 })
```

## 📚 Core Operations

### 1. Extract - Get structured data from text

```typescript
// Extract single object
const product = await zai.extract(
  text,
  z.object({
    name: z.string(),
    price: z.number(),
    inStock: z.boolean(),
  })
)

// Extract array of items
const products = await zai.extract(text, z.array(productSchema))
```

### 2. Check - Verify boolean conditions

```typescript
const result = await zai.check(email, 'is spam')
const { value, explanation } = await result.full()
```

### 3. Label - Apply multiple labels

```typescript
const labels = await zai.label(review, {
  positive: 'expresses positive sentiment',
  technical: 'mentions technical details',
  verified: 'from verified purchaser',
})
// Result: { positive: true, technical: false, verified: true }
```

### 4. Rewrite - Transform text

```typescript
// Translate
const french = await zai.rewrite(text, 'translate to French')

// Change tone
const formal = await zai.rewrite('Hey! What's up?', 'make it professional')
```

### 5. Filter - Filter arrays with natural language

```typescript
const techCompanies = await zai.filter(companies, 'are technology companies')
const recentPosts = await zai.filter(posts, 'were published this week')
```

### 6. Group - Organize items into categories

```typescript
// Group items automatically
const grouped = await zai.group(tasks, {
  instructions: 'Group by priority level',
})
// Result: { 'High Priority': [...], 'Medium Priority': [...], 'Low Priority': [...] }

// Group with initial categories
const categorized = await zai.group(emails, {
  instructions: 'Group by topic',
  initialGroups: [
    { id: 'work', label: 'Work' },
    { id: 'personal', label: 'Personal' },
  ],
})

// Group large datasets efficiently
const organized = await zai.group(largeArray, {
  instructions: 'Group by date',
  chunkLength: 8000, // Process in chunks for better performance
})
```

### 7. Rate - Score items on a 1-5 scale

```typescript
// Auto-generate criteria (returns total score)
const scores = await zai.rate(products, 'is it a good value product?')
// Result: [12, 8, 15] (total scores for each item)

// Get detailed ratings
const { output } = await zai.rate(products, 'is it a good value product?').result()
// Result: [
//   { affordability: 4, quality: 5, features: 3, total: 12 },
//   { affordability: 3, quality: 2, features: 3, total: 8 },
//   ...
// ]

// Use fixed criteria
const ratings = await zai.rate(passwords, {
  length: 'password length (12+ chars = very_good, 8-11 = good, 6-7 = average, 4-5 = bad, <4 = very_bad)',
  complexity: 'character variety (all types = very_good, 3 types = good, 2 types = average, 1 type = bad)',
  strength: 'overall password strength',
})
// Result: [
//   { length: 5, complexity: 5, strength: 5, total: 15 },
//   { length: 1, complexity: 1, strength: 1, total: 3 },
// ]

// Rate large datasets efficiently (parallelized)
const allRatings = await zai.rate(Array(500).fill(item), 'how complete is this?')
// Processes ~500 items in ~120ms with automatic chunking
```

### 8. Sort - Order items with natural language

```typescript
// Sort by natural criteria
const sorted = await zai.sort(emails, 'sort by urgency')
// LLM determines criteria and orders items accordingly

// Sort with detailed results
const { output } = await zai.sort(tasks, 'sort by priority').result()
// output includes scoring breakdown for each item

// Complex multi-criteria sorting
const prioritized = await zai.sort(tickets, 'sort by customer importance and issue severity')

// Sort large datasets efficiently (parallelized with chunking)
const orderedItems = await zai.sort(Array(500).fill(item), 'sort by relevance')
```

### 9. Text - Generate content

```typescript
const blogPost = await zai.text('Write about the future of AI', {
  length: 1000,
  temperature: 0.7,
})
```

### 10. Summarize - Create summaries

```typescript
// Simple summary
const summary = await zai.summarize(article)

// With custom prompt
const technicalSummary = await zai.summarize(paper, {
  length: 500,
  prompt: 'Focus on technical implementation details',
})
```

## 🧠 Active Learning

Enable active learning to improve accuracy over time:

```typescript
const zai = new Zai({
  client,
  activeLearning: {
    enable: true,
    tableName: 'ai_learning_data',
    taskId: 'sentiment-analysis',
  },
})

// Use with task ID for learning
const result = await zai.learn('sentiment-analysis').check(text, 'is positive')
```

## ⚙️ Configuration

### Model Selection

```typescript
// Use the best model (default)
const zai = new Zai({ client, model: 'best' })

// Use fast model for speed
const fastZai = new Zai({ client, model: 'fast' })

// Use specific model
const customZai = new Zai({ client, model: 'gpt-4-turbo' })
```

### Progress Tracking

```typescript
const response = zai.summarize(veryLongDocument)

// Track progress
response.on('progress', (progress) => {
  console.log(`${progress.percent}% complete`)
})

const summary = await response
```

### Usage Monitoring

```typescript
const result = await zai.extract(text, schema)
const usage = await result.usage()

console.log({
  tokens: usage.totalTokens,
  cost: usage.totalCost,
  latency: usage.totalLatency,
})
```

## 🎯 Benefits

1. **Production Ready** - Built-in error handling, retries, and rate limiting
2. **Type Safe** - Full TypeScript support with runtime validation
3. **Scalable** - Handle documents of any size with automatic chunking
4. **Cost Effective** - Track usage and optimize with active learning
5. **Developer Friendly** - Clean API with method chaining and events

## 📖 Advanced Usage

### Chaining Operations

```typescript
const processedData = await zai.with({ temperature: 0.3 }).learn('data-extraction').extract(document, complexSchema)
```

### Handling Large Documents

```typescript
// Automatically chunks and processes in parallel
const extractedData = await zai.extract(
  hugeDocument, // 100k+ tokens
  z.array(recordSchema),
  { chunkSize: 4000 }
)
```

### Custom Abort Signals

```typescript
const controller = new AbortController()
const response = zai.summarize(document, { signal: controller.signal })

// Cancel if needed
setTimeout(() => controller.abort(), 5000)
```

## 🛠️ API Reference

### Zai Class

- `new Zai(options)` - Create instance with client and configuration
- `.with(config)` - Create new instance with merged configuration
- `.learn(taskId)` - Enable active learning for specific task

### Operations

- `.extract(content, schema, options?)` - Extract structured data
- `.check(content, condition, options?)` - Verify boolean condition
- `.label(content, criteria, options?)` - Apply multiple labels
- `.rewrite(content, instruction, options?)` - Transform text
- `.filter(items, condition, options?)` - Filter array items
- `.group(items, options?)` - Organize items into categories
- `.rate(items, instructions, options?)` - Rate items on 1-5 scale
- `.sort(items, instructions, options?)` - Order items with natural language
- `.text(prompt, options?)` - Generate text
- `.summarize(content, options?)` - Create summary

### Response Methods

- `await response` - Get simple result
- `await response.full()` - Get detailed result with metadata
- `await response.usage()` - Get usage statistics
- `response.on('progress', handler)` - Track progress
- `response.abort()` - Cancel operation

## 📝 License

MIT - See LICENSE file for details