@botpress/zai 2.4.0 → 2.4.2

package/src/operations/rewrite.ts

@@ -33,7 +33,90 @@ const Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Rewrites a string according to match the prompt */
+    /**
+     * Rewrites text according to specific instructions while preserving the core meaning.
+     *
+     * This operation transforms text based on natural language instructions. Perfect for
+     * tone adjustment, format conversion, translation, simplification, and style changes.
+     *
+     * @param original - The text to rewrite
+     * @param prompt - Instructions describing how to transform the text
+     * @param options - Configuration for examples and length constraints
+     * @returns Response promise resolving to the rewritten text
+     *
+     * @example Change tone
+     * ```typescript
+     * const original = "Your request has been denied due to insufficient funds."
+     * const friendly = await zai.rewrite(
+     *   original,
+     *   'Make this sound more friendly and empathetic'
+     * )
+     * // Result: "We appreciate your interest, but unfortunately we're unable to proceed..."
+     * ```
+     *
+     * @example Simplify technical content
+     * ```typescript
+     * const technical = "The API implements RESTful architecture with OAuth 2.0 authentication..."
+     * const simple = await zai.rewrite(
+     *   technical,
+     *   'Explain this in simple terms for non-technical users'
+     * )
+     * ```
+     *
+     * @example Professional email conversion
+     * ```typescript
+     * const casual = "Hey, can you send me that report? Thanks!"
+     * const professional = await zai.rewrite(
+     *   casual,
+     *   'Rewrite this as a formal business email'
+     * )
+     * // Result: "Dear colleague, I would appreciate it if you could share the report..."
+     * ```
+     *
+     * @example Format conversion
+     * ```typescript
+     * const paragraph = "First do this. Then do that. Finally do this other thing."
+     * const bullets = await zai.rewrite(
+     *   paragraph,
+     *   'Convert this to a bulleted list'
+     * )
+     * // Result:
+     * // - First do this
+     * // - Then do that
+     * // - Finally do this other thing
+     * ```
+     *
+     * @example With examples for consistent style
+     * ```typescript
+     * const result = await zai.rewrite(
+     *   original,
+     *   'Rewrite in our brand voice',
+     *   {
+     *     examples: [
+     *       {
+     *         input: 'We offer many products.',
+     *         output: 'Discover our curated collection of innovative solutions.'
+     *       },
+     *       {
+     *         input: 'Contact us for help.',
+     *         output: "We're here to support your success. Let's connect!"
+     *       }
+     *     ],
+     *     length: 200 // Limit output length
+     *   }
+     * )
+     * ```
+     *
+     * @example Translation-like transformation
+     * ```typescript
+     * const code = "if (user.isActive && user.hasPermission) { allowAccess() }"
+     * const pseudocode = await zai.rewrite(
+     *   code,
+     *   'Convert this code to natural language pseudocode'
+     * )
+     * // Result: "If the user is active AND has permission, then allow access"
+     * ```
+     */
     rewrite(original: string, prompt: string, options?: Options): Response<string>
   }
 }

package/src/operations/sort.ts

@@ -35,17 +35,119 @@ type SortingCriteria = Record<
 declare module '@botpress/zai' {
   interface Zai {
     /**
-     * Sorts an array of items based on provided instructions.
-     * Returns the sorted array directly when awaited.
-     * Use .result() to get detailed scoring information including why each item got its position.
+     * Sorts array items based on natural language sorting criteria.
      *
-     * @example
-     * // Simple usage
-     * const sorted = await zai.sort(items, 'from least expensive to most expensive')
+     * This operation intelligently orders items according to your instructions, understanding
+     * complex sorting logic like priority, quality, chronology, or any custom criteria.
+     * Perfect for ranking, organizing, and prioritizing lists based on subjective or
+     * multi-faceted criteria.
      *
-     * @example
-     * // Get detailed results
-     * const { output: sorted, usage } = await zai.sort(items, 'by priority').result()
+     * @param input - Array of items to sort
+     * @param instructions - Natural language description of how to sort (e.g., "by priority", "newest first")
+     * @param options - Configuration for tokens per item
+     * @returns Response resolving to the sorted array
+     *
+     * @example Sort by price
+     * ```typescript
+     * const products = [
+     *   { name: 'Laptop', price: 999 },
+     *   { name: 'Mouse', price: 29 },
+     *   { name: 'Keyboard', price: 79 }
+     * ]
+     *
+     * const sorted = await zai.sort(products, 'from least expensive to most expensive')
+     * // Result: [Mouse ($29), Keyboard ($79), Laptop ($999)]
+     * ```
+     *
+     * @example Sort by priority/urgency
+     * ```typescript
+     * const tasks = [
+     *   "Update documentation",
+     *   "Fix critical security bug",
+     *   "Add new feature",
+     *   "System is down - all users affected"
+     * ]
+     *
+     * const prioritized = await zai.sort(tasks, 'by urgency and impact, most urgent first')
+     * // Result: ["System is down...", "Fix critical security bug", "Add new feature", "Update documentation"]
+     * ```
+     *
+     * @example Sort by quality/rating
+     * ```typescript
+     * const reviews = [
+     *   "Product is okay",
+     *   "Absolutely amazing! Best purchase ever!",
+     *   "Terrible, broke immediately",
+     *   "Good quality for the price"
+     * ]
+     *
+     * const sorted = await zai.sort(reviews, 'by sentiment, most positive first')
+     * // Result: [amazing review, good review, okay review, terrible review]
+     * ```
+     *
+     * @example Sort by complexity
+     * ```typescript
+     * const problems = [
+     *   "Fix typo in README",
+     *   "Redesign entire authentication system",
+     *   "Update a dependency version",
+     *   "Implement new microservice architecture"
+     * ]
+     *
+     * const sorted = await zai.sort(problems, 'by complexity, simplest first')
+     * ```
+     *
+     * @example Sort by relevance to query
+     * ```typescript
+     * const documents = [
+     *   "Article about cats",
+     *   "Article about dogs and their training",
+     *   "Article about dog breeds",
+     *   "Article about fish"
+     * ]
+     *
+     * const sorted = await zai.sort(
+     *   documents,
+     *   'by relevance to "dog training", most relevant first'
+     * )
+     * // Result: [dogs and training, dog breeds, cats, fish]
+     * ```
+     *
+     * @example Sort candidates by fit
+     * ```typescript
+     * const candidates = [
+     *   { name: 'Alice', experience: 5, skills: ['React', 'Node'] },
+     *   { name: 'Bob', experience: 10, skills: ['Python', 'ML'] },
+     *   { name: 'Charlie', experience: 3, skills: ['React', 'TypeScript'] }
+     * ]
+     *
+     * const sorted = await zai.sort(
+     *   candidates,
+     *   'by fit for a senior React developer position, best fit first'
+     * )
+     * ```
+     *
+     * @example Sort chronologically
+     * ```typescript
+     * const events = [
+     *   "Started the project last month",
+     *   "Will launch next week",
+     *   "Met with client yesterday",
+     *   "Planning meeting tomorrow"
+     * ]
+     *
+     * const chronological = await zai.sort(events, 'in chronological order')
+     * // Understands relative time expressions
+     * ```
+     *
+     * @example With token limit per item
+     * ```typescript
+     * const sorted = await zai.sort(
+     *   longDocuments,
+     *   'by relevance to climate change research',
+     *   { tokensPerItem: 500 } // Allow 500 tokens per document
+     * )
+     * ```
      */
     sort<T>(input: Array<T>, instructions: string, options?: Options): Response<Array<T>, Array<T>>
   }

package/src/operations/summarize.ts

@@ -58,7 +58,80 @@ const Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Summarizes a text of any length to a summary of the desired length */
+    /**
+     * Summarizes text of any length to a target length using intelligent chunking strategies.
+     *
+     * This operation can handle documents from a few paragraphs to entire books. It uses
+     * two strategies based on document size:
+     * - **Sliding window**: For moderate documents, processes overlapping chunks iteratively
+     * - **Merge sort**: For very large documents, recursively summarizes and merges
+     *
+     * @param original - The text to summarize
+     * @param options - Configuration for length, focus, format, and chunking strategy
+     * @returns Response promise resolving to the summary text
+     *
+     * @example Basic summarization
+     * ```typescript
+     * const article = "Long article text here..."
+     * const summary = await zai.summarize(article, {
+     *   length: 100 // Target 100 tokens (~75 words)
+     * })
+     * ```
+     *
+     * @example Custom focus and format
+     * ```typescript
+     * const meetingNotes = "... detailed meeting transcript ..."
+     * const summary = await zai.summarize(meetingNotes, {
+     *   length: 200,
+     *   prompt: 'Key decisions, action items, and next steps',
+     *   format: 'Bullet points with clear sections for Decisions, Actions, and Next Steps'
+     * })
+     * ```
+     *
+     * @example Summarizing very large documents
+     * ```typescript
+     * const book = await readFile('large-book.txt', 'utf-8') // 100k+ tokens
+     * const summary = await zai.summarize(book, {
+     *   length: 500,
+     *   intermediateFactor: 4, // Intermediate summaries can be 4x target length
+     *   prompt: 'Main themes, key events, and character development'
+     * })
+     * // Automatically uses merge-sort strategy for efficiency
+     * ```
+     *
+     * @example Technical documentation summary
+     * ```typescript
+     * const docs = "... API documentation ..."
+     * const summary = await zai.summarize(docs, {
+     *   length: 300,
+     *   prompt: 'Core API endpoints, authentication methods, and rate limits',
+     *   format: 'Structured markdown with code examples where relevant'
+     * })
+     * ```
+     *
+     * @example Adjusting chunking strategy
+     * ```typescript
+     * const summary = await zai.summarize(document, {
+     *   length: 150,
+     *   sliding: {
+     *     window: 30000,  // Process 30k tokens at a time
+     *     overlap: 500    // 500 token overlap between windows
+     *   }
+     * })
+     * ```
+     *
+     * @example Progress tracking for long documents
+     * ```typescript
+     * const response = zai.summarize(veryLongDocument, { length: 400 })
+     *
+     * response.on('progress', (usage) => {
+     *   console.log(`Progress: ${Math.round(usage.requests.percentage * 100)}%`)
+     *   console.log(`Tokens used: ${usage.tokens.total}`)
+     * })
+     *
+     * const summary = await response
+     * ```
+     */
     summarize(original: string, options?: Options): Response<string>
   }
 }

package/src/operations/text.ts

@@ -19,7 +19,56 @@ const Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Generates a text of the desired length according to the prompt */
+    /**
+     * Generates text content based on a natural language prompt.
+     *
+     * This operation creates original text content using LLMs with optional length constraints.
+     * Perfect for generating descriptions, emails, articles, creative content, and more.
+     *
+     * @param prompt - Natural language description of what text to generate
+     * @param options - Optional configuration for text length
+     * @returns Response promise resolving to the generated text
+     *
+     * @example Product description
+     * ```typescript
+     * const description = await zai.text(
+     *   'Write a compelling product description for eco-friendly bamboo toothbrushes'
+     * )
+     * ```
+     *
+     * @example With length constraint
+     * ```typescript
+     * const tagline = await zai.text(
+     *   'Create a catchy tagline for a fitness app',
+     *   { length: 10 } // ~10 tokens (7-8 words)
+     * )
+     * ```
+     *
+     * @example Email generation
+     * ```typescript
+     * const email = await zai.text(`
+     *   Write a professional email to a customer explaining
+     *   that their order will be delayed by 2 days due to weather.
+     *   Apologize and offer a 10% discount on their next purchase.
+     * `, { length: 150 })
+     * ```
+     *
+     * @example Blog post
+     * ```typescript
+     * const blogPost = await zai.text(`
+     *   Write an informative blog post about the benefits of meditation
+     *   for software developers. Include practical tips and scientific research.
+     * `, { length: 500 })
+     * ```
+     *
+     * @example Social media content
+     * ```typescript
+     * const tweet = await zai.text(
+     *   'Write an engaging tweet announcing our new AI-powered chatbot feature',
+     *   { length: 30 } // Twitter-friendly length
+     * )
+     * ```
+     */
     text(prompt: string, options?: Options): Response<string>
   }
 }

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