@botpress/zai 2.1.2 → 2.1.3

package/README.md

@@ -1,57 +1,253 @@
-# Zui AI
+# Zai - AI Operations Made Simple
 
-**Zai** (stands for _Zui + AI_) is a lightweight utility library that uses AI to manipulate and generate Zui schemas and objects.
+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.
 
-It's built on top of Zui and the Botpress client to interface with the different LLMs.
+## ✨ Key Features
 
-## Usage
+- **🎯 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
-import Zai from '@botpress/zai'
+// 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. Text - Generate content
+
+```typescript
+const blogPost = await zai.text('Write about the future of AI', {
+  length: 1000,
+  temperature: 0.7,
+})
+```
+
+### 7. 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: new Client({}), // your botpress client here
+  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')
 ```
 
-## Array
+## ⚙️ Configuration
+
+### Model Selection
 
 ```typescript
-await zai.filter(['cat', 'dog', 'carrot'], 'is an animal')
+// 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`)
+})
 
-// Not implemented yet
-// await zai.map(filtered, z.object({ animal: z.string(), name: z.string() }))
-// await zai.sort(named, 'from most dangerous to least dangerous')
-// await zai.cluster(named, 'based on color')
-// await zai.append(named, 'another one')
+const summary = await response
 ```
 
-## String
+### Usage Monitoring
 
 ```typescript
-await zai.text('a story about ....')
-await zai.summarize(book)
-await zai.rewrite('Hello, I am ...', 'make it longer')
+const result = await zai.extract(text, schema)
+const usage = await result.usage()
 
-// Not implemented yet
-// await zai.rate(novel, ['is the novel good?', 'how creative is it?', 'quality of writing', 'is the ending good?'])
-// await zai.label(tweet, [{ label: '' }])
-// await zai.classify(tweet, [])
+console.log({
+  tokens: usage.totalTokens,
+  cost: usage.totalCost,
+  latency: usage.totalLatency,
+})
 ```
 
-## Boolean
+## 🎯 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
-await zai.check({ name: 'hey', bio: '...' }, 'contains insults')
+const processedData = await zai.with({ temperature: 0.3 }).learn('data-extraction').extract(document, complexSchema)
 ```
 
-## Object
+### Handling Large Documents
 
 ```typescript
-await zai.extract('My name is Sly and I am from Canada !', z.object({ name: z.string(), country: z.string() }))
+// Automatically chunks and processes in parallel
+const extractedData = await zai.extract(
+  hugeDocument, // 100k+ tokens
+  z.array(recordSchema),
+  { chunkSize: 4000 }
+)
+```
 
-// Not implemented yet
-// await zai.extend({ name: 'Sylvain' }, z.object({ country: z.string() }))
-// await zai.diff(before, after)
-// await zai.edit(object, '')
+### 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
+- `.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

package/dist/response.js

@@ -50,13 +50,14 @@ export class Response {
       this.abort(signal.reason);
     };
     signal.addEventListener("abort", () => signalAbort());
-    this.once("complete", () => signal.removeEventListener("abort", signalAbort));
-    this.once("error", () => signal.removeEventListener("abort", signalAbort));
+    void this.once("complete", () => signal.removeEventListener("abort", signalAbort));
+    void this.once("error", () => signal.removeEventListener("abort", signalAbort));
     return this;
   }
   abort(reason) {
     this._context.controller.abort(reason);
   }
+  // oxlint-disable-next-line no-thenable
   then(onfulfilled, onrejected) {
     return this._promise.then(
       (value) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@botpress/zai",
   "description": "Zui AI (zai) – An LLM utility library written on top of Zui and the Botpress API",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -29,7 +29,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@botpress/cognitive": "0.1.31",
+    "@botpress/cognitive": "0.1.32",
     "json5": "^2.2.3",
     "jsonrepair": "^3.10.0",
     "lodash-es": "^4.17.21"

package/src/response.ts

@@ -68,8 +68,8 @@ export class Response<T = any, S = T> implements PromiseLike<S> {
 
     signal.addEventListener('abort', () => signalAbort())
 
-    this.once('complete', () => signal.removeEventListener('abort', signalAbort))
-    this.once('error', () => signal.removeEventListener('abort', signalAbort))
+    void this.once('complete', () => signal.removeEventListener('abort', signalAbort))
+    void this.once('error', () => signal.removeEventListener('abort', signalAbort))
 
     return this
   }
@@ -78,6 +78,7 @@ export class Response<T = any, S = T> implements PromiseLike<S> {
     this._context.controller.abort(reason)
   }
 
+  // oxlint-disable-next-line no-thenable
   public then<TResult1 = S, TResult2 = never>(
     onfulfilled?: ((value: S) => TResult1 | PromiseLike<TResult1>) | null,
     onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null