@botpress/zai 2.4.0 → 2.4.2

package/src/operations/check.ts

@@ -33,7 +33,81 @@ const _Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Checks wether a condition is true or not */
+    /**
+     * Checks whether a condition is true for the given input, with an explanation.
+     *
+     * This operation evaluates natural language conditions against your input data,
+     * returning both a boolean result and a detailed explanation. Perfect for
+     * content moderation, sentiment analysis, quality checks, and business rule validation.
+     *
+     * @param input - The data to evaluate (text, object, or any value)
+     * @param condition - Natural language description of the condition to check
+     * @param options - Optional examples to guide the evaluation
+     * @returns Response with { value: boolean, explanation: string }, simplified to boolean when awaited
+     *
+     * @example Basic sentiment check
+     * ```typescript
+     * const review = "This product exceeded my expectations!"
+     * const isPositive = await zai.check(review, 'Is the sentiment positive?')
+     * // Result: true
+     *
+     * // Get full details
+     * const { value, explanation } = await zai.check(review, 'Is the sentiment positive?').result()
+     * // value: true
+     * // explanation: "The review expresses satisfaction and exceeded expectations..."
+     * ```
+     *
+     * @example Content moderation
+     * ```typescript
+     * const comment = "Great article! Very informative."
+     * const isSpam = await zai.check(comment, 'Is this spam or promotional content?')
+     * // Result: false
+     *
+     * const hasProfanity = await zai.check(comment, 'Does this contain profanity or offensive language?')
+     * // Result: false
+     * ```
+     *
+     * @example Business rules validation
+     * ```typescript
+     * const invoice = {
+     *   total: 1500,
+     *   items: ['laptop', 'mouse'],
+     *   customer: 'Enterprise Corp'
+     * }
+     *
+     * const needsApproval = await zai.check(
+     *   invoice,
+     *   'Does this invoice require manager approval? (over $1000 or enterprise customer)'
+     * )
+     * // Result: true
+     * ```
+     *
+     * @example With examples for consistency
+     * ```typescript
+     * const result = await zai.check(text, 'Is this a technical question?', {
+     *   examples: [
+     *     {
+     *       input: 'How do I deploy to production?',
+     *       check: true,
+     *       reason: 'Question about deployment process'
+     *     },
+     *     {
+     *       input: 'What time is the meeting?',
+     *       check: false,
+     *       reason: 'Not a technical question'
+     *     }
+     *   ]
+     * })
+     * ```
+     *
+     * @example Quality assurance
+     * ```typescript
+     * const code = "function add(a, b) { return a + b }"
+     * const hasDocumentation = await zai.check(code, 'Is this code properly documented?')
+     * const hasTests = await zai.check(code, 'Does this include unit tests?')
+     * const followsConventions = await zai.check(code, 'Does this follow naming conventions?')
+     * ```
+     */
     check(
       input: unknown,
       condition: string,

package/src/operations/extract.ts

@@ -41,11 +41,77 @@ type AnyObjectOrArray = Record<string, unknown> | Array<unknown>
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Extracts one or many elements from an arbitrary input */
+    /**
+     * Extracts structured data from unstructured text using a Zod schema.
+     *
+     * This operation uses LLMs to intelligently parse text and extract information
+     * according to your schema. It handles large inputs automatically by chunking
+     * and supports both objects and arrays.
+     *
+     * @param input - The text or data to extract information from
+     * @param schema - Zod schema defining the structure to extract
+     * @param options - Optional configuration for extraction behavior
+     * @returns A Response promise that resolves to data matching your schema
+     *
+     * @example Extract a single object
+     * ```typescript
+     * import { z } from '@bpinternal/zui'
+     *
+     * const personSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     *   email: z.string().email()
+     * })
+     *
+     * const text = "Contact John Doe (35) at john@example.com"
+     * const person = await zai.extract(text, personSchema)
+     * // Result: { name: 'John Doe', age: 35, email: 'john@example.com' }
+     * ```
+     *
+     * @example Extract an array of items
+     * ```typescript
+     * const productSchema = z.array(z.object({
+     *   name: z.string(),
+     *   price: z.number()
+     * }))
+     *
+     * const text = "We have Apple ($1.50), Banana ($0.80), and Orange ($1.20)"
+     * const products = await zai.extract(text, productSchema)
+     * // Result: [
+     * //   { name: 'Apple', price: 1.50 },
+     * //   { name: 'Banana', price: 0.80 },
+     * //   { name: 'Orange', price: 1.20 }
+     * // ]
+     * ```
+     *
+     * @example With custom instructions
+     * ```typescript
+     * const result = await zai.extract(document, schema, {
+     *   instructions: 'Only extract confirmed information, skip uncertain data',
+     *   chunkLength: 10000, // Smaller chunks for better accuracy
+     *   strict: true // Enforce strict schema validation
+     * })
+     * ```
+     *
+     * @example Track usage and cost
+     * ```typescript
+     * const response = zai.extract(text, schema)
+     *
+     * // Monitor progress
+     * response.on('progress', (usage) => {
+     *   console.log(`Tokens used: ${usage.tokens.total}`)
+     *   console.log(`Cost so far: $${usage.cost.total}`)
+     * })
+     *
+     * // Get full results
+     * const { output, usage, elapsed } = await response.result()
+     * console.log(`Extraction took ${elapsed}ms and cost $${usage.cost.total}`)
+     * ```
+     */
     extract<S extends OfType<any>>(input: unknown, schema: S, options?: Options): Response<S['_output']>
   }
 }
-
+const SPECIAL_CHAR = '■'
 const START = '■json_start■'
 const END = '■json_end■'
 const NO_MORE = '■NO_MORE_ELEMENT■'
@@ -330,7 +396,12 @@ ${instructions.map((x) => `• ${x}`).join('\n')}
         .filter((x) => x.trim().length > 0 && x.includes('}'))
         .map((x) => {
           try {
-            const json = x.slice(0, x.indexOf(END)).trim()
+            let json = x.slice(0, x.indexOf(END)).trim()
+
+            if (json.includes(SPECIAL_CHAR)) {
+              json = json.slice(0, json.indexOf(SPECIAL_CHAR)).trim()
+            }
+
             const repairedJson = jsonrepair(json)
             const parsedJson = JSON5.parse(repairedJson)
             const safe = schema.safeParse(parsedJson)

package/src/operations/filter.ts

@@ -42,7 +42,92 @@ const _Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Filters elements of an array against a condition */
+    /**
+     * Filters array elements based on a natural language condition.
+     *
+     * This operation evaluates each element against a condition using LLMs,
+     * returning only elements that match. Handles large arrays automatically
+     * by processing in parallel chunks.
+     *
+     * @param input - Array of elements to filter
+     * @param condition - Natural language description of what to keep
+     * @param options - Configuration for token limits per item and examples
+     * @returns Response promise resolving to filtered array
+     *
+     * @example Filter positive reviews
+     * ```typescript
+     * const reviews = [
+     *   "Great product, love it!",
+     *   "Terrible quality, broke immediately",
+     *   "Amazing! Exceeded expectations",
+     *   "Worst purchase ever"
+     * ]
+     *
+     * const positive = await zai.filter(reviews, 'Keep only positive reviews')
+     * // Result: ["Great product, love it!", "Amazing! Exceeded expectations"]
+     * ```
+     *
+     * @example Filter technical questions
+     * ```typescript
+     * const questions = [
+     *   "How do I deploy to production?",
+     *   "What time is lunch?",
+     *   "Why is the API returning 500 errors?",
+     *   "Can you book the conference room?"
+     * ]
+     *
+     * const technical = await zai.filter(
+     *   questions,
+     *   'Keep only technical or engineering questions'
+     * )
+     * // Result: ["How do I deploy to production?", "Why is the API returning 500 errors?"]
+     * ```
+     *
+     * @example Filter with object array
+     * ```typescript
+     * const products = [
+     *   { name: 'Laptop', category: 'Electronics', inStock: true },
+     *   { name: 'Desk', category: 'Furniture', inStock: false },
+     *   { name: 'Mouse', category: 'Electronics', inStock: true },
+     *   { name: 'Chair', category: 'Furniture', inStock: true }
+     * ]
+     *
+     * const available = await zai.filter(
+     *   products,
+     *   'Keep only products that are in stock'
+     * )
+     * // Returns products where inStock === true
+     * ```
+     *
+     * @example Complex filtering logic
+     * ```typescript
+     * const emails = [...] // Array of email objects
+     *
+     * const urgent = await zai.filter(
+     *   emails,
+     *   'Keep emails that are urgent, from the CEO, or mention "critical bug"'
+     * )
+     * ```
+     *
+     * @example With examples for consistency
+     * ```typescript
+     * const filtered = await zai.filter(items, 'Keep valid entries', {
+     *   examples: [
+     *     {
+     *       input: { status: 'active', verified: true },
+     *       filter: true,
+     *       reason: 'Active and verified'
+     *     },
+     *     {
+     *       input: { status: 'pending', verified: false },
+     *       filter: false,
+     *       reason: 'Not yet verified'
+     *     }
+     *   ],
+     *   tokensPerItem: 100 // Limit tokens per item for performance
+     * })
+     * ```
+     */
     filter<T>(input: Array<T>, condition: string, options?: Options): Response<Array<T>>
   }
 }

package/src/operations/group.ts

@@ -43,6 +43,156 @@ const _Options = z.object({
 
 declare module '@botpress/zai' {
   interface Zai {
+    /**
+     * Groups array items into categories based on semantic similarity or criteria.
+     *
+     * This operation intelligently categorizes items by analyzing their content and
+     * creating meaningful groups. It can discover natural groupings automatically or
+     * use predefined categories. Perfect for clustering, classification, and organization.
+     *
+     * @param input - Array of items to group
+     * @param options - Configuration for grouping behavior, instructions, and initial categories
+     * @returns Response with groups array (simplified to Record<groupLabel, items[]>)
+     *
+     * @example Automatic grouping
+     * ```typescript
+     * const messages = [
+     *   "I can't log in to my account",
+     *   "How do I reset my password?",
+     *   "When will my order arrive?",
+     *   "The app keeps crashing",
+     *   "I haven't received my package",
+     *   "Error 500 on checkout"
+     * ]
+     *
+     * const groups = await zai.group(messages, {
+     *   instructions: 'Group by type of customer issue'
+     * })
+     * // Result (simplified):
+     * // {
+     * //   "Login Issues": ["I can't log in...", "How do I reset..."],
+     * //   "Shipping Questions": ["When will my order...", "I haven't received..."],
+     * //   "Technical Errors": ["The app keeps crashing", "Error 500..."]
+     * // }
+     *
+     * // Full result:
+     * const { output } = await zai.group(messages, { instructions: '...' }).result()
+     * // output: [
+     * //   { id: 'login_issues', label: 'Login Issues', elements: [...] },
+     * //   { id: 'shipping', label: 'Shipping Questions', elements: [...] },
+     * //   { id: 'errors', label: 'Technical Errors', elements: [...] }
+     * // ]
+     * ```
+     *
+     * @example With predefined categories
+     * ```typescript
+     * const articles = [
+     *   "How to build a React app",
+     *   "Python machine learning tutorial",
+     *   "Understanding Docker containers",
+     *   "Vue.js best practices",
+     *   "Deep learning with TensorFlow"
+     * ]
+     *
+     * const groups = await zai.group(articles, {
+     *   instructions: 'Categorize by technology',
+     *   initialGroups: [
+     *     { id: 'frontend', label: 'Frontend Development' },
+     *     { id: 'backend', label: 'Backend Development' },
+     *     { id: 'ml', label: 'Machine Learning' },
+     *     { id: 'devops', label: 'DevOps & Infrastructure' }
+     *   ]
+     * })
+     * // Groups articles into predefined categories
+     * ```
+     *
+     * @example Grouping products
+     * ```typescript
+     * const products = [
+     *   { name: 'Laptop', price: 999, category: 'Electronics' },
+     *   { name: 'Desk', price: 299, category: 'Furniture' },
+     *   { name: 'Mouse', price: 29, category: 'Electronics' },
+     *   { name: 'Chair', price: 199, category: 'Furniture' }
+     * ]
+     *
+     * const grouped = await zai.group(products, {
+     *   instructions: 'Group by price range: budget (< $100), mid-range ($100-$500), premium (> $500)'
+     * })
+     * // Result:
+     * // {
+     * //   "Budget": [Mouse],
+     * //   "Mid-range": [Chair, Desk],
+     * //   "Premium": [Laptop]
+     * // }
+     * ```
+     *
+     * @example Content categorization
+     * ```typescript
+     * const emails = [
+     *   { subject: 'Meeting tomorrow', body: '...', from: 'boss@company.com' },
+     *   { subject: 'Invoice #1234', body: '...', from: 'billing@vendor.com' },
+     *   { subject: 'Weekly report', body: '...', from: 'team@company.com' },
+     *   { subject: 'Payment received', body: '...', from: 'accounting@company.com' }
+     * ]
+     *
+     * const categorized = await zai.group(emails, {
+     *   instructions: 'Categorize by email type: work communication, financial, reports',
+     *   tokensPerElement: 300 // Allow more context per email
+     * })
+     * ```
+     *
+     * @example Customer feedback grouping
+     * ```typescript
+     * const feedback = [
+     *   "Love the new UI!",
+     *   "App is too slow",
+     *   "Great customer service",
+     *   "Confusing navigation",
+     *   "Fast shipping!",
+     *   "Hard to find features"
+     * ]
+     *
+     * const grouped = await zai.group(feedback, {
+     *   instructions: 'Group by aspect: UI/UX, Performance, Customer Service, Shipping'
+     * })
+     * ```
+     *
+     * @example Topic clustering for research
+     * ```typescript
+     * const papers = [
+     *   { title: 'Transformer Networks for NLP', abstract: '...' },
+     *   { title: 'CNN Image Classification', abstract: '...' },
+     *   { title: 'BERT Language Understanding', abstract: '...' },
+     *   { title: 'Object Detection with YOLO', abstract: '...' }
+     * ]
+     *
+     * const clusters = await zai.group(papers, {
+     *   instructions: 'Group by research area',
+     *   chunkLength: 10000 // Allow more tokens for detailed abstracts
+     * })
+     * // Result: Groups papers by topic (NLP, Computer Vision, etc.)
+     * ```
+     *
+     * @example With initial seed groups
+     * ```typescript
+     * const tasks = [
+     *   "Fix login bug",
+     *   "Update documentation",
+     *   "Add dark mode",
+     *   "Optimize database queries"
+     * ]
+     *
+     * const grouped = await zai.group(tasks, {
+     *   instructions: 'Categorize development tasks',
+     *   initialGroups: [
+     *     { id: 'bugs', label: 'Bug Fixes', elements: [] },
+     *     { id: 'features', label: 'New Features', elements: [] },
+     *     { id: 'docs', label: 'Documentation', elements: [] },
+     *     { id: 'performance', label: 'Performance', elements: [] }
+     *   ]
+     * })
+     * ```
+     */
     group<T>(input: Array<T>, options?: Options): Response<Array<Group<T>>, Record<string, T[]>>
   }
 }

package/src/operations/label.ts

@@ -82,7 +82,125 @@ const _Labels = z.record(z.string().min(1).max(250), z.string()).superRefine((la
 
 declare module '@botpress/zai' {
   interface Zai {
-    /** Tags the provided input with a list of predefined labels */
+    /**
+     * Tags input with multiple labels, each with explanation, value, and confidence level.
+     *
+     * This operation evaluates input against multiple categories simultaneously, providing
+     * nuanced confidence levels (ABSOLUTELY_YES, PROBABLY_YES, AMBIGUOUS, PROBABLY_NOT, ABSOLUTELY_NOT).
+     * Perfect for content classification, intent detection, and multi-criteria evaluation.
+     *
+     * @param input - The data to label (text, object, or any value)
+     * @param labels - Object mapping label keys to their descriptions
+     * @param options - Configuration for examples, instructions, and chunking
+     * @returns Response with detailed results per label (explanation, value, confidence), simplified to booleans
+     *
+     * @example Content moderation
+     * ```typescript
+     * const comment = "This is a great article! Click here for cheap products!"
+     *
+     * const result = await zai.label(comment, {
+     *   spam: 'Is this spam or promotional content?',
+     *   helpful: 'Is this comment helpful and constructive?',
+     *   profanity: 'Does this contain profanity or offensive language?'
+     * }).result()
+     *
+     * // result.output:
+     * // {
+     * //   spam: { value: true, confidence: 0.5, explanation: 'Contains promotional link...' },
+     * //   helpful: { value: true, confidence: 1, explanation: 'Positive feedback...' },
+     * //   profanity: { value: false, confidence: 1, explanation: 'No offensive language' }
+     * // }
+     *
+     * // Simplified (when awaited directly):
+     * const simple = await zai.label(comment, { spam: 'Is this spam?' })
+     * // simple: { spam: true }
+     * ```
+     *
+     * @example Intent classification
+     * ```typescript
+     * const message = "I can't log in to my account"
+     *
+     * const intents = await zai.label(message, {
+     *   technical_issue: 'Is this a technical problem?',
+     *   urgent: 'Does this require immediate attention?',
+     *   needs_human: 'Should this be escalated to a human agent?',
+     *   billing_related: 'Is this about billing or payments?'
+     * })
+     * // Returns boolean for each intent
+     * ```
+     *
+     * @example Sentiment analysis with nuance
+     * ```typescript
+     * const review = "The product is okay, but shipping was slow"
+     *
+     * const { output } = await zai.label(review, {
+     *   positive: 'Is the overall sentiment positive?',
+     *   negative: 'Is the overall sentiment negative?',
+     *   mixed: 'Does this express mixed feelings?'
+     * }).result()
+     *
+     * // Check confidence levels
+     * if (output.mixed.confidence > 0.5) {
+     *   console.log('Mixed sentiment detected:', output.mixed.explanation)
+     * }
+     * ```
+     *
+     * @example Product categorization
+     * ```typescript
+     * const product = {
+     *   name: 'Wireless Headphones',
+     *   description: 'Noise-canceling Bluetooth headphones for music lovers',
+     *   price: 199
+     * }
+     *
+     * const categories = await zai.label(product, {
+     *   electronics: 'Is this an electronic device?',
+     *   audio: 'Is this audio equipment?',
+     *   premium: 'Is this a premium/luxury product?',
+     *   portable: 'Is this portable/mobile?'
+     * })
+     * // Returns: { electronics: true, audio: true, premium: true, portable: true }
+     * ```
+     *
+     * @example With examples for consistency
+     * ```typescript
+     * const result = await zai.label(email, {
+     *   urgent: 'Requires immediate response',
+     *   complaint: 'Customer is dissatisfied'
+     * }, {
+     *   examples: [
+     *     {
+     *       input: 'ASAP! System is down!',
+     *       labels: {
+     *         urgent: { label: 'ABSOLUTELY_YES', explanation: 'Critical issue' },
+     *         complaint: { label: 'PROBABLY_YES', explanation: 'Implicit complaint' }
+     *       }
+     *     }
+     *   ],
+     *   instructions: 'Consider tone, urgency keywords, and context'
+     * })
+     * ```
+     *
+     * @example Understanding confidence levels
+     * ```typescript
+     * const { output } = await zai.label(text, labels).result()
+     *
+     * // Confidence values:
+     * // ABSOLUTELY_YES: confidence = 1.0, value = true
+     * // PROBABLY_YES: confidence = 0.5, value = true
+     * // AMBIGUOUS: confidence = 0, value = false
+     * // PROBABLY_NOT: confidence = 0.5, value = false
+     * // ABSOLUTELY_NOT: confidence = 1.0, value = false
+     *
+     * Object.entries(output).forEach(([key, result]) => {
+     *   if (result.value && result.confidence === 1) {
+     *     console.log(`Definitely ${key}:`, result.explanation)
+     *   } else if (result.value && result.confidence === 0.5) {
+     *     console.log(`Probably ${key}:`, result.explanation)
+     *   }
+     * })
+     * ```
+     */
     label<T extends string>(
       input: unknown,
       labels: Labels<T>,

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