@botpress/zai 2.4.0 → 2.4.2

package/src/zai.ts

@@ -8,9 +8,27 @@ import { Adapter } from './adapters/adapter'
 import { TableAdapter } from './adapters/botpress-table'
 import { MemoryAdapter } from './adapters/memory'
 
+/**
+ * Active learning configuration for improving AI operations over time.
+ *
+ * When enabled, Zai stores successful operation results in a table and uses them as examples
+ * for future operations, improving accuracy and consistency.
+ *
+ * @example
+ * ```typescript
+ * const activeLearning = {
+ *   enable: true,
+ *   tableName: 'MyAppLearningTable',
+ *   taskId: 'sentiment-analysis'
+ * }
+ * ```
+ */
 type ActiveLearning = {
+  /** Whether to enable active learning for this Zai instance */
   enable: boolean
+  /** Name of the Botpress table to store learning examples (must end with 'Table') */
   tableName: string
+  /** Unique identifier for this learning task */
   taskId: string
 }
 
@@ -34,11 +52,39 @@ const _ActiveLearning = z.object({
     .default('default'),
 })
 
+/**
+ * Configuration options for creating a Zai instance.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from '@botpress/client'
+ * import { Zai } from '@botpress/zai'
+ *
+ * const client = new Client({ token: 'your-token' })
+ * const config: ZaiConfig = {
+ *   client,
+ *   modelId: 'best', // Use the best available model
+ *   userId: 'user-123',
+ *   namespace: 'my-app',
+ *   activeLearning: {
+ *     enable: true,
+ *     tableName: 'MyLearningTable',
+ *     taskId: 'extraction'
+ *   }
+ * }
+ * const zai = new Zai(config)
+ * ```
+ */
 type ZaiConfig = {
+  /** Botpress client or Cognitive client instance */
   client: BotpressClientLike | Cognitive
+  /** Optional user ID for tracking and attribution */
   userId?: string
+  /** Model to use: 'best' (default), 'fast', or specific model like 'openai:gpt-4' */
   modelId?: Models
+  /** Active learning configuration to improve operations over time */
   activeLearning?: ActiveLearning
+  /** Namespace for organizing tasks (default: 'zai') */
   namespace?: string
 }
 
@@ -74,6 +120,68 @@ const _ZaiConfig = z.object({
     .default('zai'),
 })
 
+/**
+ * Zai - A type-safe LLM utility library for production-ready AI operations.
+ *
+ * Zai provides high-level abstractions for common AI tasks with built-in features like:
+ * - Active learning (learns from successful operations)
+ * - Automatic chunking for large inputs
+ * - Retry logic with error recovery
+ * - Usage tracking (tokens, cost, latency)
+ * - Type-safe schema validation with Zod
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Client } from '@botpress/client'
+ * import { Zai } from '@botpress/zai'
+ * import { z } from '@bpinternal/zui'
+ *
+ * const client = new Client({ token: process.env.BOTPRESS_TOKEN })
+ * const zai = new Zai({ client })
+ *
+ * // Extract structured data
+ * const schema = z.object({
+ *   name: z.string(),
+ *   age: z.number()
+ * })
+ * const person = await zai.extract('John is 30 years old', schema)
+ * // Output: { name: 'John', age: 30 }
+ *
+ * // Check conditions
+ * const isPositive = await zai.check('I love this product!', 'Is the sentiment positive?')
+ * // Output: true
+ *
+ * // Summarize text
+ * const summary = await zai.summarize(longDocument, { length: 100 })
+ * ```
+ *
+ * @example With active learning
+ * ```typescript
+ * const zai = new Zai({
+ *   client,
+ *   activeLearning: {
+ *     enable: true,
+ *     tableName: 'SentimentTable',
+ *     taskId: 'product-reviews'
+ *   }
+ * })
+ *
+ * // Enable learning for specific task
+ * const result = await zai.learn('sentiment').check(review, 'Is this positive?')
+ * // Future calls will use approved examples for better accuracy
+ * ```
+ *
+ * @example Chaining configuration
+ * ```typescript
+ * // Use fast model for quick operations
+ * const fastZai = zai.with({ modelId: 'fast' })
+ * await fastZai.check(text, 'Is this spam?')
+ *
+ * // Use specific model
+ * const gpt4Zai = zai.with({ modelId: 'openai:gpt-4' })
+ * await gpt4Zai.extract(document, complexSchema)
+ * ```
+ */
 export class Zai {
   protected static tokenizer: TextTokenizer = null!
   protected client: Cognitive
@@ -88,6 +196,27 @@ export class Zai {
   protected adapter: Adapter
   protected activeLearning: 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)
+   */
   public constructor(config: ZaiConfig) {
     this._originalConfig = config
     const parsed = _ZaiConfig.parse(config) as ZaiConfig
@@ -146,6 +275,41 @@ 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' })
+   * ```
+   */
   public with(options: Partial<ZaiConfig>): Zai {
     return new Zai({
       ...this._originalConfig,
@@ -153,6 +317,56 @@ export class Zai {
     })
   }
 
+  /**
+   * 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
+   */
   public learn(taskId: string) {
     return new Zai({
       ...this._originalConfig,