@botpress/zai 2.4.1 → 2.5.0

package/dist/response.js

@@ -29,19 +29,104 @@ export class Response {
       this._eventEmitter.emit("progress", usage);
     });
   }
-  // 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)
+   * })
+   * ```
+   */
   on(type, listener) {
     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)
+   * ```
+   */
   off(type, listener) {
     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)
+   * })
+   * ```
+   */
   once(type, listener) {
     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)
+   * ```
+   */
   bindSignal(signal) {
     if (signal.aborted) {
       this.abort(signal.reason);
@@ -54,9 +139,48 @@ export class Response {
     void this.once("error", () => signal.removeEventListener("abort", signalAbort));
     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)
+   * }
+   * ```
+   */
   abort(reason) {
     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
   then(onfulfilled, onrejected) {
     return this._promise.then(
@@ -72,9 +196,50 @@ export class Response {
       }
     );
   }
+  /**
+   * Promise interface - handles errors.
+   *
+   * @param onrejected - Error handler
+   * @returns Promise resolving to simplified value or error result
+   */
   catch(onrejected) {
     return this._promise.catch(onrejected);
   }
+  /**
+   * 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)
+   * ```
+   */
   async result() {
     const output = await this._promise;
     const usage = this._context.usage;

package/dist/zai.js

@@ -47,6 +47,27 @@ export class Zai {
   namespace;
   adapter;
   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)
+   */
   constructor(config) {
     this._originalConfig = config;
     const parsed = _ZaiConfig.parse(config);
@@ -89,12 +110,97 @@ 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' })
+   * ```
+   */
   with(options) {
     return new Zai({
       ...this._originalConfig,
       ...options
     });
   }
+  /**
+   * 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
+   */
   learn(taskId) {
     return new Zai({
       ...this._originalConfig,