@botpress/zai 2.4.1 → 2.5.0

package/src/operations/extract.ts

@@ -41,7 +41,73 @@ 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']>
   }
 }

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