@botpress/zai 2.4.1 → 2.5.0

package/src/response.ts

@@ -1,13 +1,110 @@
 import { Usage, ZaiContext } from './context'
 import { EventEmitter } from './emitter'
 
-// Event types for the Response class
+/**
+ * Event types emitted during operation execution.
+ *
+ * @property progress - Emitted periodically with usage statistics (tokens, cost, requests)
+ * @property complete - Emitted when operation completes successfully with the result
+ * @property error - Emitted when operation fails with the error
+ */
 export type ResponseEvents<TComplete = any> = {
+  /** Emitted during execution with updated usage statistics */
   progress: Usage
+  /** Emitted when the operation completes with the full result */
   complete: TComplete
+  /** Emitted when the operation fails with an error */
   error: unknown
 }
 
+/**
+ * Promise-like wrapper for Zai operations with observability and control.
+ *
+ * Response provides a dual-value system:
+ * - **Simplified value**: When awaited directly, returns a simplified result (e.g., boolean for `check()`)
+ * - **Full result**: Via `.result()` method, returns `{ output, usage, elapsed }`
+ *
+ * All Zai operations return a Response instance, allowing you to:
+ * - Track progress and usage in real-time
+ * - Abort operations
+ * - Bind to external abort signals
+ * - Get detailed cost and performance metrics
+ *
+ * @template T - The full output type
+ * @template S - The simplified output type (defaults to T)
+ *
+ * @example Basic usage (simplified)
+ * ```typescript
+ * // Simplified result (boolean)
+ * const isPositive = await zai.check(review, 'Is this positive?')
+ * console.log(isPositive) // true or false
+ * ```
+ *
+ * @example Full result with usage
+ * ```typescript
+ * const response = zai.check(review, 'Is this positive?')
+ * const { output, usage, elapsed } = await response.result()
+ *
+ * console.log(output.value) // true/false
+ * console.log(output.explanation) // "The review expresses satisfaction..."
+ * console.log(usage.tokens.total) // 150
+ * console.log(usage.cost.total) // 0.002
+ * console.log(elapsed) // 1234 (ms)
+ * ```
+ *
+ * @example Progress tracking
+ * ```typescript
+ * const response = zai.summarize(longDocument, { length: 500 })
+ *
+ * response.on('progress', (usage) => {
+ *   console.log(`Progress: ${usage.requests.percentage * 100}%`)
+ *   console.log(`Tokens: ${usage.tokens.total}`)
+ *   console.log(`Cost: $${usage.cost.total}`)
+ * })
+ *
+ * const summary = await response
+ * ```
+ *
+ * @example Aborting operations
+ * ```typescript
+ * const response = zai.extract(hugeDocument, schema)
+ *
+ * // Abort after 5 seconds
+ * setTimeout(() => response.abort('Timeout'), 5000)
+ *
+ * try {
+ *   const result = await response
+ * } catch (error) {
+ *   console.log('Operation aborted:', error)
+ * }
+ * ```
+ *
+ * @example External abort signal
+ * ```typescript
+ * const controller = new AbortController()
+ * const response = zai.answer(documents, question).bindSignal(controller.signal)
+ *
+ * // User clicks cancel button
+ * cancelButton.onclick = () => controller.abort()
+ *
+ * const answer = await response
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * const response = zai.extract(text, schema)
+ *
+ * response.on('error', (error) => {
+ *   console.error('Operation failed:', error)
+ * })
+ *
+ * try {
+ *   const result = await response
+ * } catch (error) {
+ *   // Handle error
+ * }
+ * ```
+ */
 export class Response<T = any, S = T> implements PromiseLike<S> {
   private _promise: Promise<T>
   private _eventEmitter: EventEmitter<ResponseEvents<T>>
@@ -41,22 +138,107 @@ export class Response<T = any, S = T> implements PromiseLike<S> {
     })
   }
 
-  // Event emitter methods
+  /**
+   * Subscribes to events emitted during operation execution.
+   *
+   * @param type - Event type: 'progress', 'complete', or 'error'
+   * @param listener - Callback function to handle the event
+   * @returns This Response instance for chaining
+   *
+   * @example Track progress
+   * ```typescript
+   * response.on('progress', (usage) => {
+   *   console.log(`${usage.requests.percentage * 100}% complete`)
+   *   console.log(`Cost: $${usage.cost.total}`)
+   * })
+   * ```
+   *
+   * @example Handle completion
+   * ```typescript
+   * response.on('complete', (result) => {
+   *   console.log('Operation completed:', result)
+   * })
+   * ```
+   *
+   * @example Handle errors
+   * ```typescript
+   * response.on('error', (error) => {
+   *   console.error('Operation failed:', error)
+   * })
+   * ```
+   */
   public on<K extends keyof ResponseEvents<T>>(type: K, listener: (event: ResponseEvents<T>[K]) => void) {
     this._eventEmitter.on(type, listener)
     return this
   }
 
+  /**
+   * Unsubscribes from events.
+   *
+   * @param type - Event type to unsubscribe from
+   * @param listener - The exact listener function to remove
+   * @returns This Response instance for chaining
+   *
+   * @example
+   * ```typescript
+   * const progressHandler = (usage) => console.log(usage.tokens.total)
+   * response.on('progress', progressHandler)
+   * // Later...
+   * response.off('progress', progressHandler)
+   * ```
+   */
   public off<K extends keyof ResponseEvents<T>>(type: K, listener: (event: ResponseEvents<T>[K]) => void) {
     this._eventEmitter.off(type, listener)
     return this
   }
 
+  /**
+   * Subscribes to an event for a single emission.
+   *
+   * The listener is automatically removed after being called once.
+   *
+   * @param type - Event type: 'progress', 'complete', or 'error'
+   * @param listener - Callback function to handle the event once
+   * @returns This Response instance for chaining
+   *
+   * @example
+   * ```typescript
+   * response.once('complete', (result) => {
+   *   console.log('Finished:', result)
+   * })
+   * ```
+   */
   public once<K extends keyof ResponseEvents<T>>(type: K, listener: (event: ResponseEvents<T>[K]) => void) {
     this._eventEmitter.once(type, listener)
     return this
   }
 
+  /**
+   * Binds an external AbortSignal to this operation.
+   *
+   * When the signal is aborted, the operation will be cancelled automatically.
+   * Useful for integrating with UI cancel buttons or request timeouts.
+   *
+   * @param signal - AbortSignal to bind
+   * @returns This Response instance for chaining
+   *
+   * @example With AbortController
+   * ```typescript
+   * const controller = new AbortController()
+   * const response = zai.extract(data, schema).bindSignal(controller.signal)
+   *
+   * // Cancel from elsewhere
+   * cancelButton.onclick = () => controller.abort()
+   * ```
+   *
+   * @example With timeout
+   * ```typescript
+   * const controller = new AbortController()
+   * setTimeout(() => controller.abort('Timeout'), 10000)
+   *
+   * const response = zai.answer(docs, question).bindSignal(controller.signal)
+   * ```
+   */
   public bindSignal(signal: AbortSignal): this {
     if (signal.aborted) {
       this.abort(signal.reason)
@@ -74,10 +256,49 @@ export class Response<T = any, S = T> implements PromiseLike<S> {
     return this
   }
 
+  /**
+   * Aborts the operation in progress.
+   *
+   * The operation will be cancelled and throw an abort error.
+   * Any partial results will not be returned.
+   *
+   * @param reason - Optional reason for aborting (string or Error)
+   *
+   * @example
+   * ```typescript
+   * const response = zai.extract(largeDocument, schema)
+   *
+   * // Abort after 5 seconds
+   * setTimeout(() => response.abort('Operation timeout'), 5000)
+   *
+   * try {
+   *   await response
+   * } catch (error) {
+   *   console.log('Aborted:', error)
+   * }
+   * ```
+   */
   public abort(reason?: string | Error) {
     this._context.controller.abort(reason)
   }
 
+  /**
+   * Promise interface - allows awaiting the Response.
+   *
+   * When awaited, returns the simplified value (S).
+   * Use `.result()` for full output with usage statistics.
+   *
+   * @param onfulfilled - Success handler
+   * @param onrejected - Error handler
+   * @returns Promise resolving to simplified value
+   *
+   * @example
+   * ```typescript
+   * // Simplified value
+   * const isPositive = await zai.check(review, 'Is positive?')
+   * console.log(isPositive) // true
+   * ```
+   */
   // oxlint-disable-next-line no-thenable
   public then<TResult1 = S, TResult2 = never>(
     onfulfilled?: ((value: S) => TResult1 | PromiseLike<TResult1>) | null,
@@ -97,12 +318,53 @@ export class Response<T = any, S = T> implements PromiseLike<S> {
     ) as PromiseLike<TResult1 | TResult2>
   }
 
+  /**
+   * Promise interface - handles errors.
+   *
+   * @param onrejected - Error handler
+   * @returns Promise resolving to simplified value or error result
+   */
   public catch<TResult = never>(
     onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null
   ): PromiseLike<S | TResult> {
     return this._promise.catch(onrejected) as PromiseLike<S | TResult>
   }
 
+  /**
+   * Gets the full result with detailed usage statistics and timing.
+   *
+   * Unlike awaiting the Response directly (which returns simplified value),
+   * this method provides:
+   * - `output`: Full operation result (not simplified)
+   * - `usage`: Detailed token usage, cost, and request statistics
+   * - `elapsed`: Operation duration in milliseconds
+   *
+   * @returns Promise resolving to full result object
+   *
+   * @example
+   * ```typescript
+   * const { output, usage, elapsed } = await zai.check(text, condition).result()
+   *
+   * console.log(output.value) // true/false
+   * console.log(output.explanation) // "The text expresses..."
+   * console.log(usage.tokens.total) // 245
+   * console.log(usage.cost.total) // 0.0012
+   * console.log(elapsed) // 1523 (ms)
+   * ```
+   *
+   * @example Usage statistics breakdown
+   * ```typescript
+   * const { usage } = await response.result()
+   *
+   * console.log('Requests:', usage.requests.requests)
+   * console.log('Cached:', usage.requests.cached)
+   * console.log('Input tokens:', usage.tokens.input)
+   * console.log('Output tokens:', usage.tokens.output)
+   * console.log('Input cost:', usage.cost.input)
+   * console.log('Output cost:', usage.cost.output)
+   * console.log('Total cost:', usage.cost.total)
+   * ```
+   */
   public async result(): Promise<{
     output: T
     usage: Usage

package/src/zai.ts

@@ -8,9 +8,27 @@ import { Adapter } from './adapters/adapter'
 import { TableAdapter } from './adapters/botpress-table'
 import { MemoryAdapter } from './adapters/memory'
 
+/**
+ * Active learning configuration for improving AI operations over time.
+ *
+ * When enabled, Zai stores successful operation results in a table and uses them as examples
+ * for future operations, improving accuracy and consistency.
+ *
+ * @example
+ * ```typescript
+ * const activeLearning = {
+ *   enable: true,
+ *   tableName: 'MyAppLearningTable',
+ *   taskId: 'sentiment-analysis'
+ * }
+ * ```
+ */
 type ActiveLearning = {
+  /** Whether to enable active learning for this Zai instance */
   enable: boolean
+  /** Name of the Botpress table to store learning examples (must end with 'Table') */
   tableName: string
+  /** Unique identifier for this learning task */
   taskId: string
 }
 
@@ -34,11 +52,39 @@ const _ActiveLearning = z.object({
     .default('default'),
 })
 
+/**
+ * Configuration options for creating a Zai instance.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from '@botpress/client'
+ * import { Zai } from '@botpress/zai'
+ *
+ * const client = new Client({ token: 'your-token' })
+ * const config: ZaiConfig = {
+ *   client,
+ *   modelId: 'best', // Use the best available model
+ *   userId: 'user-123',
+ *   namespace: 'my-app',
+ *   activeLearning: {
+ *     enable: true,
+ *     tableName: 'MyLearningTable',
+ *     taskId: 'extraction'
+ *   }
+ * }
+ * const zai = new Zai(config)
+ * ```
+ */
 type ZaiConfig = {
+  /** Botpress client or Cognitive client instance */
   client: BotpressClientLike | Cognitive
+  /** Optional user ID for tracking and attribution */
   userId?: string
+  /** Model to use: 'best' (default), 'fast', or specific model like 'openai:gpt-4' */
   modelId?: Models
+  /** Active learning configuration to improve operations over time */
   activeLearning?: ActiveLearning
+  /** Namespace for organizing tasks (default: 'zai') */
   namespace?: string
 }
 
@@ -74,6 +120,68 @@ const _ZaiConfig = z.object({
     .default('zai'),
 })
 
+/**
+ * Zai - A type-safe LLM utility library for production-ready AI operations.
+ *
+ * Zai provides high-level abstractions for common AI tasks with built-in features like:
+ * - Active learning (learns from successful operations)
+ * - Automatic chunking for large inputs
+ * - Retry logic with error recovery
+ * - Usage tracking (tokens, cost, latency)
+ * - Type-safe schema validation with Zod
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Client } from '@botpress/client'
+ * import { Zai } from '@botpress/zai'
+ * import { z } from '@bpinternal/zui'
+ *
+ * const client = new Client({ token: process.env.BOTPRESS_TOKEN })
+ * const zai = new Zai({ client })
+ *
+ * // Extract structured data
+ * const schema = z.object({
+ *   name: z.string(),
+ *   age: z.number()
+ * })
+ * const person = await zai.extract('John is 30 years old', schema)
+ * // Output: { name: 'John', age: 30 }
+ *
+ * // Check conditions
+ * const isPositive = await zai.check('I love this product!', 'Is the sentiment positive?')
+ * // Output: true
+ *
+ * // Summarize text
+ * const summary = await zai.summarize(longDocument, { length: 100 })
+ * ```
+ *
+ * @example With active learning
+ * ```typescript
+ * const zai = new Zai({
+ *   client,
+ *   activeLearning: {
+ *     enable: true,
+ *     tableName: 'SentimentTable',
+ *     taskId: 'product-reviews'
+ *   }
+ * })
+ *
+ * // Enable learning for specific task
+ * const result = await zai.learn('sentiment').check(review, 'Is this positive?')
+ * // Future calls will use approved examples for better accuracy
+ * ```
+ *
+ * @example Chaining configuration
+ * ```typescript
+ * // Use fast model for quick operations
+ * const fastZai = zai.with({ modelId: 'fast' })
+ * await fastZai.check(text, 'Is this spam?')
+ *
+ * // Use specific model
+ * const gpt4Zai = zai.with({ modelId: 'openai:gpt-4' })
+ * await gpt4Zai.extract(document, complexSchema)
+ * ```
+ */
 export class Zai {
   protected static tokenizer: TextTokenizer = null!
   protected client: Cognitive
@@ -88,6 +196,27 @@ export class Zai {
   protected adapter: Adapter
   protected activeLearning: ActiveLearning
 
+  /**
+   * Creates a new Zai instance with the specified configuration.
+   *
+   * @param config - Configuration object containing client, model, and learning settings
+   *
+   * @example
+   * ```typescript
+   * import { Client } from '@botpress/client'
+   * import { Zai } from '@botpress/zai'
+   *
+   * const client = new Client({ token: 'your-token' })
+   * const zai = new Zai({
+   *   client,
+   *   modelId: 'best',
+   *   namespace: 'my-app',
+   *   userId: 'user-123'
+   * })
+   * ```
+   *
+   * @throws {Error} If the configuration is invalid (e.g., invalid modelId format)
+   */
   public constructor(config: ZaiConfig) {
     this._originalConfig = config
     const parsed = _ZaiConfig.parse(config) as ZaiConfig
@@ -146,6 +275,41 @@ export class Zai {
     return `${this.namespace}/${this.activeLearning.taskId}`.replace(/\/+/g, '/')
   }
 
+  /**
+   * Creates a new Zai instance with merged configuration options.
+   *
+   * This method allows you to create variations of your Zai instance with different
+   * settings without modifying the original. Useful for switching models, namespaces,
+   * or other configuration on a per-operation basis.
+   *
+   * @param options - Partial configuration to override the current settings
+   * @returns A new Zai instance with the merged configuration
+   *
+   * @example Switch to a faster model
+   * ```typescript
+   * const zai = new Zai({ client })
+   *
+   * // Use fast model for simple operations
+   * const fastZai = zai.with({ modelId: 'fast' })
+   * await fastZai.check(text, 'Is this spam?')
+   *
+   * // Use best model for complex operations
+   * const bestZai = zai.with({ modelId: 'best' })
+   * await bestZai.extract(document, complexSchema)
+   * ```
+   *
+   * @example Change namespace
+   * ```typescript
+   * const customerZai = zai.with({ namespace: 'customer-support' })
+   * const salesZai = zai.with({ namespace: 'sales' })
+   * ```
+   *
+   * @example Use specific model
+   * ```typescript
+   * const gpt4 = zai.with({ modelId: 'openai:gpt-4' })
+   * const claude = zai.with({ modelId: 'anthropic:claude-3-5-sonnet-20241022' })
+   * ```
+   */
   public with(options: Partial<ZaiConfig>): Zai {
     return new Zai({
       ...this._originalConfig,
@@ -153,6 +317,56 @@ export class Zai {
     })
   }
 
+  /**
+   * Creates a new Zai instance with active learning enabled for a specific task.
+   *
+   * Active learning stores successful operation results and uses them as examples for
+   * future operations, improving accuracy and consistency over time. Each task ID
+   * maintains its own set of learned examples.
+   *
+   * @param taskId - Unique identifier for the learning task (alphanumeric, hyphens, underscores, slashes)
+   * @returns A new Zai instance with active learning enabled for the specified task
+   *
+   * @example Sentiment analysis with learning
+   * ```typescript
+   * const zai = new Zai({
+   *   client,
+   *   activeLearning: {
+   *     enable: false,
+   *     tableName: 'AppLearningTable',
+   *     taskId: 'default'
+   *   }
+   * })
+   *
+   * // Enable learning for sentiment analysis
+   * const sentimentZai = zai.learn('sentiment-analysis')
+   * const result = await sentimentZai.check(review, 'Is this review positive?')
+   *
+   * // Each successful call is stored and used to improve future calls
+   * ```
+   *
+   * @example Different tasks for different purposes
+   * ```typescript
+   * // Extract user info with learning
+   * const userExtractor = zai.learn('user-extraction')
+   * await userExtractor.extract(text, userSchema)
+   *
+   * // Extract product info with separate learning
+   * const productExtractor = zai.learn('product-extraction')
+   * await productExtractor.extract(text, productSchema)
+   *
+   * // Each task learns independently
+   * ```
+   *
+   * @example Combining with other configuration
+   * ```typescript
+   * // Use fast model + learning
+   * const fastLearner = zai.with({ modelId: 'fast' }).learn('quick-checks')
+   * await fastLearner.check(email, 'Is this spam?')
+   * ```
+   *
+   * @see {@link ZaiConfig.activeLearning} for configuration options
+   */
   public learn(taskId: string) {
     return new Zai({
       ...this._originalConfig,