@botpress/zai 2.4.1 → 2.5.0

package/src/operations/rate.ts

@@ -76,8 +76,118 @@ export type SimplifiedRatingResult<T extends RatingInstructions> = T extends str
 declare module '@botpress/zai' {
   interface Zai {
     /**
-     * Rates an array of items based on provided instructions.
-     * Returns a number (1-5) if instructions is a string, or a Record<string, number> if instructions is a Record.
+     * Rates array items on a 1-5 scale based on single or multiple criteria.
+     *
+     * This operation evaluates each item and assigns numeric ratings (1-5) where:
+     * - 1 = Very Bad, 2 = Bad, 3 = Average, 4 = Good, 5 = Very Good
+     *
+     * Supports both simple single-criterion rating (string instructions) and
+     * multi-criteria rating (object with criterion → description mapping).
+     *
+     * @param input - Array of items to rate
+     * @param instructions - Single criterion (string) or multiple criteria (object)
+     * @param options - Configuration for chunking and tokens per item
+     * @returns Response with ratings array (simplified to numbers for single criterion)
+     *
+     * @example Single criterion rating
+     * ```typescript
+     * const reviews = [
+     *   "Amazing product! Best purchase ever!",
+     *   "It's okay, nothing special",
+     *   "Terrible quality, broke immediately"
+     * ]
+     *
+     * const ratings = await zai.rate(reviews, 'Rate the sentiment')
+     * // Result: [5, 3, 1] (simplified to numbers)
+     *
+     * // Get full details
+     * const { output } = await zai.rate(reviews, 'Rate the sentiment').result()
+     * // output[0]: { sentiment: 5, total: 5 }
+     * ```
+     *
+     * @example Multi-criteria rating
+     * ```typescript
+     * const essays = [
+     *   "... student essay text ...",
+     *   "... another essay ...",
+     * ]
+     *
+     * const ratings = await zai.rate(essays, {
+     *   grammar: 'Rate the grammar and spelling',
+     *   clarity: 'Rate how clear and well-organized the writing is',
+     *   argumentation: 'Rate the strength of arguments and evidence'
+     * })
+     *
+     * // Result: [
+     * //   { grammar: 4, clarity: 5, argumentation: 3, total: 12 },
+     * //   { grammar: 3, clarity: 4, argumentation: 4, total: 11 }
+     * // ]
+     * ```
+     *
+     * @example Rating customer support conversations
+     * ```typescript
+     * const conversations = [
+     *   { agent: 'John', messages: [...], duration: 300 },
+     *   { agent: 'Jane', messages: [...], duration: 180 }
+     * ]
+     *
+     * const ratings = await zai.rate(conversations, {
+     *   professionalism: 'How professional was the agent?',
+     *   helpfulness: 'How helpful was the agent in solving the issue?',
+     *   efficiency: 'How efficiently was the conversation handled?'
+     * })
+     *
+     * // Calculate average scores
+     * const avgProfessionalism = ratings.reduce((sum, r) => sum + r.professionalism, 0) / ratings.length
+     * ```
+     *
+     * @example Rating code quality
+     * ```typescript
+     * const codeSamples = [
+     *   "function foo() { return x + y }",
+     *   "const calculateTotal = (items) => items.reduce((sum, item) => sum + item.price, 0)",
+     * ]
+     *
+     * const quality = await zai.rate(codeSamples, {
+     *   readability: 'How readable and clear is the code?',
+     *   best_practices: 'Does it follow coding best practices?',
+     *   documentation: 'Is the code well-documented?'
+     * })
+     * ```
+     *
+     * @example Product review rating
+     * ```typescript
+     * const products = [
+     *   { name: 'Laptop', reviews: [...], avgStars: 4.2 },
+     *   { name: 'Mouse', reviews: [...], avgStars: 3.8 }
+     * ]
+     *
+     * const ratings = await zai.rate(
+     *   products,
+     *   'Rate overall product quality based on reviews and rating',
+     *   {
+     *     tokensPerItem: 500, // Allow more tokens for detailed reviews
+     *     maxItemsPerChunk: 20 // Process 20 products per chunk
+     *   }
+     * )
+     * ```
+     *
+     * @example Finding highest-rated items
+     * ```typescript
+     * const ratings = await zai.rate(items, {
+     *   quality: 'Product quality',
+     *   value: 'Value for money',
+     *   design: 'Design and aesthetics'
+     * })
+     *
+     * // Sort by total score
+     * const sorted = items
+     *   .map((item, idx) => ({ item, rating: ratings[idx] }))
+     *   .sort((a, b) => b.rating.total - a.rating.total)
+     *
+     * console.log('Top rated:', sorted[0].item)
+     * console.log('Score breakdown:', sorted[0].rating)
+     * ```
      */
     rate<T, I extends RatingInstructions>(
       input: Array<T>,

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>
   }
 }