@botpress/zai 2.4.1 → 2.4.2

package/dist/operations/answer.js

@@ -241,17 +241,19 @@ Question to answer: "${question}"`;
       }
     ],
     transform: (text) => {
+      text = text.slice(0, text.lastIndexOf(END.slice(0, -1)));
       return parseResponse(text || "", mappings);
     }
   });
   return extracted;
 };
-const parseResponse = (response, mappings) => {
+export const parseResponse = (response, mappings) => {
   const text = response.trim();
-  if (text.includes(ANSWER_START)) {
-    return parseAnswerResponse(text, mappings);
-  } else if (text.includes(AMBIGUOUS_START)) {
+  const answersCount = (text.match(new RegExp(ANSWER_START, "g")) || []).length;
+  if (text.includes(AMBIGUOUS_START) || answersCount >= 2) {
     return parseAmbiguousResponse(text, mappings);
+  } else if (text.includes(ANSWER_START)) {
+    return parseAnswerResponse(text, mappings);
   } else if (text.includes(OUT_OF_TOPIC_START)) {
     return parseOutOfTopicResponse(text);
   } else if (text.includes(INVALID_QUESTION_START)) {

package/dist/response.js

@@ -29,19 +29,104 @@ export class Response {
       this._eventEmitter.emit("progress", usage);
     });
   }
-  // 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)
+   * })
+   * ```
+   */
   on(type, listener) {
     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)
+   * ```
+   */
   off(type, listener) {
     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)
+   * })
+   * ```
+   */
   once(type, listener) {
     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)
+   * ```
+   */
   bindSignal(signal) {
     if (signal.aborted) {
       this.abort(signal.reason);
@@ -54,9 +139,48 @@ export class Response {
     void this.once("error", () => signal.removeEventListener("abort", signalAbort));
     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)
+   * }
+   * ```
+   */
   abort(reason) {
     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
   then(onfulfilled, onrejected) {
     return this._promise.then(
@@ -72,9 +196,50 @@ export class Response {
       }
     );
   }
+  /**
+   * Promise interface - handles errors.
+   *
+   * @param onrejected - Error handler
+   * @returns Promise resolving to simplified value or error result
+   */
   catch(onrejected) {
     return this._promise.catch(onrejected);
   }
+  /**
+   * 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)
+   * ```
+   */
   async result() {
     const output = await this._promise;
     const usage = this._context.usage;

package/dist/zai.js

@@ -47,6 +47,27 @@ export class Zai {
   namespace;
   adapter;
   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)
+   */
   constructor(config) {
     this._originalConfig = config;
     const parsed = _ZaiConfig.parse(config);
@@ -89,12 +110,97 @@ 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' })
+   * ```
+   */
   with(options) {
     return new Zai({
       ...this._originalConfig,
       ...options
     });
   }
+  /**
+   * 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
+   */
   learn(taskId) {
     return new Zai({
       ...this._originalConfig,

package/e2e/data/cache.jsonl

@@ -1799,3 +1799,5 @@
 {"key":"a7dec8bb","input":"{\"body\":{\"messages\":[{\"content\":\"You are an expert research assistant specialized in answering questions using only the information provided in documents.\\n\\n# Task\\nAnswer the user's question based ONLY on the information in the provided documents. You MUST cite your sources using line numbers.\\n\\n# Document Format\\nDocuments are provided with line numbers:\\n■001 | First line of text\\n■002 | Second line of text\\n■003 | Third line of text\\n\\n# Citation Format\\nYou MUST include citations immediately after statements. Use these formats:\\n- Single line: ■035\\n- Range: ■005-010\\n- Multiple: ■035■046■094\\n\\n# Response Format\\n\\nChoose ONE of these response types:\\n\\n**TYPE 1 - ANSWER** (Use this when you can answer the question)\\n■answer\\n[Your answer with inline citations■001-003. Make sure each part is cited correctly■013. More text. ■015]\\n■end■\\n\\n**TYPE 2 - AMBIGUOUS** (Use when the question has multiple valid interpretations)\\n■ambiguous\\n[Explain the ambiguity]\\n■follow_up\\n[Ask a clarifying question]\\n■answer\\n[First interpretation with citations ■001 and part 2 as well.■002]\\n■answer\\n[Second interpretation with citations ■005 and part 2 of the answer.■006]\\n■end■\\n\\n**TYPE 3 - OUT OF TOPIC** (Use when question is completely unrelated to documents)\\n■out_of_topic\\n[Explain why it's unrelated]\\n■end■\\n\\n**TYPE 4 - INVALID QUESTION** (Use when input is not a proper question, e.g., gibberish, malformed or nonsensical)\\n■invalid_question\\n[Explain why it's invalid, e.g., \\\"The question is incomplete\\\" or \\\"The question contains nonsensical terms\\\", or \\\"Received gibberish\\\"]\\n■end■\\n\\n**TYPE 5 - MISSING KNOWLEDGE** (Use ONLY when documents lack specific details needed)\\n■missing_knowledge\\n[Explain what specific information is missing]\\n■end■\\n\\n# Important Rules\\n- PREFER answering when possible - only use missing_knowledge if truly no relevant info exists\\n- ALWAYS cite sources with line numbers\\n- Use ONLY information from the documents\\n- Be precise and factual\\n- Do NOT fabricate information\\n- Do NOT mention \\\"According to the documents\\\" or similar phrases – just provide a high-quality answer with citations\\n- Do not be too strict on the question format; assume high-level answers are acceptable unless the question clearly asks for very specific details or requests depth beyond the documents\\n\\n# Additional Instructions\\nHere are some additional instructions to follow about how to answer the question:\\nProvide a clear and concise answer based on the documents.\",\"role\":\"system\"},{\"content\":\"<documents>\\n■001 | Some content here\\n</documents>\\n\\nPlease answer the below question using the format specified above.\\nQuestion to answer: \\\"Question?1762472164277\\\"\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.answer\",\"promptSource\":\"zai:zai.answer:default\"},\"model\":\"fast\",\"reasoningEffort\":\"none\",\"signal\":{},\"stopSequences\":[\"■end■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■missing_knowledge\nThe provided document contains only the line “Some content here” and does not include any information related to the question “Question?1762472164277.” Therefore, the necessary details to answer the question are missing.\n■end","metadata":{"provider":"cerebras","usage":{"inputTokens":659,"outputTokens":82,"inputCost":0.00023065,"outputCost":0.0000615},"model":"cerebras:gpt-oss-120b","ttft":191,"latency":893,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.00029215,"warnings":[{"type":"parameter_ignored","message":"Reasoning effort \"none\" is not supported by the \"gpt-oss-120b\" model, using \"low\" effort instead"}]}}}
 {"key":"ed1db1d1","input":"{\"body\":{\"messages\":[{\"content\":\"You are an expert research assistant specialized in answering questions using only the information provided in documents.\\n\\n# Task\\nAnswer the user's question based ONLY on the information in the provided documents. You MUST cite your sources using line numbers.\\n\\n# Document Format\\nDocuments are provided with line numbers:\\n■001 | First line of text\\n■002 | Second line of text\\n■003 | Third line of text\\n\\n# Citation Format\\nYou MUST include citations immediately after statements. Use these formats:\\n- Single line: ■035\\n- Range: ■005-010\\n- Multiple: ■035■046■094\\n\\n# Response Format\\n\\nChoose ONE of these response types:\\n\\n**TYPE 1 - ANSWER** (Use this when you can answer the question)\\n■answer\\n[Your answer with inline citations■001-003. Make sure each part is cited correctly■013. More text. ■015]\\n■end■\\n\\n**TYPE 2 - AMBIGUOUS** (Use when the question has multiple valid interpretations)\\n■ambiguous\\n[Explain the ambiguity]\\n■follow_up\\n[Ask a clarifying question]\\n■answer\\n[First interpretation with citations ■001 and part 2 as well.■002]\\n■answer\\n[Second interpretation with citations ■005 and part 2 of the answer.■006]\\n■end■\\n\\n**TYPE 3 - OUT OF TOPIC** (Use when question is completely unrelated to documents)\\n■out_of_topic\\n[Explain why it's unrelated]\\n■end■\\n\\n**TYPE 4 - INVALID QUESTION** (Use when input is not a proper question, e.g., gibberish, malformed or nonsensical)\\n■invalid_question\\n[Explain why it's invalid, e.g., \\\"The question is incomplete\\\" or \\\"The question contains nonsensical terms\\\", or \\\"Received gibberish\\\"]\\n■end■\\n\\n**TYPE 5 - MISSING KNOWLEDGE** (Use ONLY when documents lack specific details needed)\\n■missing_knowledge\\n[Explain what specific information is missing]\\n■end■\\n\\n# Important Rules\\n- PREFER answering when possible - only use missing_knowledge if truly no relevant info exists\\n- ALWAYS cite sources with line numbers\\n- Use ONLY information from the documents\\n- Be precise and factual\\n- Do NOT fabricate information\\n- Do NOT mention \\\"According to the documents\\\" or similar phrases – just provide a high-quality answer with citations\\n- Do not be too strict on the question format; assume high-level answers are acceptable unless the question clearly asks for very specific details or requests depth beyond the documents\\n\\n# Additional Instructions\\nHere are some additional instructions to follow about how to answer the question:\\nProvide a clear and concise answer based on the documents.\",\"role\":\"system\"},{\"content\":\"<documents>\\n■001 | Some content here\\n</documents>\\n\\nPlease answer the below question using the format specified above.\\nQuestion to answer: \\\"Question?\\\"\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.answer\",\"promptSource\":\"zai:zai.answer:default\"},\"model\":\"fast\",\"reasoningEffort\":\"none\",\"signal\":{},\"stopSequences\":[\"■end■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■missing_knowledge\nThe provided document contains only a single line of vague text (\"Some content here\") and does not include any information relevant to answering the question posed. Therefore, the necessary details to respond are missing.\n■end","metadata":{"provider":"cerebras","usage":{"inputTokens":653,"outputTokens":77,"inputCost":0.00022855,"outputCost":0.00005775},"model":"cerebras:gpt-oss-120b","ttft":165,"latency":257,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0002863,"warnings":[{"type":"parameter_ignored","message":"Reasoning effort \"none\" is not supported by the \"gpt-oss-120b\" model, using \"low\" effort instead"}]}}}
 {"key":"78e0f785","input":"{\"body\":{\"messages\":[{\"content\":\"You are an expert research assistant specialized in answering questions using only the information provided in documents.\\n\\n# Task\\nAnswer the user's question based ONLY on the information in the provided documents. You MUST cite your sources using line numbers.\\n\\n# Document Format\\nDocuments are provided with line numbers:\\n■001 | First line of text\\n■002 | Second line of text\\n■003 | Third line of text\\n\\n# Citation Format\\nYou MUST include citations immediately after statements. Use these formats:\\n- Single line: ■035\\n- Range: ■005-010\\n- Multiple: ■035■046■094\\n\\n# Response Format\\n\\nChoose ONE of these response types:\\n\\n**TYPE 1 - ANSWER** (Use this when you can answer the question)\\n■answer\\n[Your answer with inline citations■001-003. Make sure each part is cited correctly■013. More text. ■015]\\n■end■\\n\\n**TYPE 2 - AMBIGUOUS** (Use when the question has multiple valid interpretations)\\n■ambiguous\\n[Explain the ambiguity]\\n■follow_up\\n[Ask a clarifying question]\\n■answer\\n[First interpretation with citations ■001 and part 2 as well.■002]\\n■answer\\n[Second interpretation with citations ■005 and part 2 of the answer.■006]\\n■end■\\n\\n**TYPE 3 - OUT OF TOPIC** (Use when question is completely unrelated to documents)\\n■out_of_topic\\n[Explain why it's unrelated]\\n■end■\\n\\n**TYPE 4 - INVALID QUESTION** (Use when input is not a proper question, e.g., gibberish, malformed or nonsensical)\\n■invalid_question\\n[Explain why it's invalid, e.g., \\\"The question is incomplete\\\" or \\\"The question contains nonsensical terms\\\", or \\\"Received gibberish\\\"]\\n■end■\\n\\n**TYPE 5 - MISSING KNOWLEDGE** (Use ONLY when documents lack specific details needed)\\n■missing_knowledge\\n[Explain what specific information is missing]\\n■end■\\n\\n# Important Rules\\n- PREFER answering when possible - only use missing_knowledge if truly no relevant info exists\\n- ALWAYS cite sources with line numbers\\n- Use ONLY information from the documents\\n- Be precise and factual\\n- Do NOT fabricate information\\n- Do NOT mention \\\"According to the documents\\\" or similar phrases – just provide a high-quality answer with citations\\n- Do not be too strict on the question format; assume high-level answers are acceptable unless the question clearly asks for very specific details or requests depth beyond the documents\\n\\n# Additional Instructions\\nHere are some additional instructions to follow about how to answer the question:\\nProvide a clear and concise answer based on the documents.\",\"role\":\"system\"},{\"content\":\"<documents>\\n■001 | Document 1\\n■002 | Document 2\\n■003 | Document 3\\n</documents>\\n\\nPlease answer the below question using the format specified above.\\nQuestion to answer: \\\"What is this about?\\\"\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.answer\",\"promptSource\":\"zai:zai.answer:default\"},\"model\":\"fast\",\"reasoningEffort\":\"none\",\"signal\":{},\"stopSequences\":[\"■end■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■missing_knowledge\nThe provided documents contain only titles (\"Document 1\", \"Document 2\", \"Document 3\") and do not include any substantive information about a topic, making it impossible to determine what \"this\" refers to. Additional content is needed to answer the question.\n■end","metadata":{"provider":"cerebras","usage":{"inputTokens":670,"outputTokens":102,"inputCost":0.0002345,"outputCost":0.0000765},"model":"cerebras:gpt-oss-120b","ttft":189,"latency":279,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.000311,"warnings":[{"type":"parameter_ignored","message":"Reasoning effort \"none\" is not supported by the \"gpt-oss-120b\" model, using \"low\" effort instead"}]}}}
+{"key":"67eb9851","input":"{\"body\":{\"messages\":[{\"content\":\"You are an expert research assistant specialized in answering questions using only the information provided in documents.\\n\\n# Task\\nAnswer the user's question based ONLY on the information in the provided documents. You MUST cite your sources using line numbers.\\n\\n# Document Format\\nDocuments are provided with line numbers:\\n■001 | First line of text\\n■002 | Second line of text\\n■003 | Third line of text\\n\\n# Citation Format\\nYou MUST include citations immediately after statements. Use these formats:\\n- Single line: ■035\\n- Range: ■005-010\\n- Multiple: ■035■046■094\\n\\n# Response Format\\n\\nChoose ONE of these response types:\\n\\n**TYPE 1 - ANSWER** (Use this when you can answer the question)\\n■answer\\n[Your answer with inline citations■001-003. Make sure each part is cited correctly■013. More text. ■015]\\n■end■\\n\\n**TYPE 2 - AMBIGUOUS** (Use when the question has multiple valid interpretations)\\n■ambiguous\\n[Explain the ambiguity]\\n■follow_up\\n[Ask a clarifying question]\\n■answer\\n[First interpretation with citations ■001 and part 2 as well.■002]\\n■answer\\n[Second interpretation with citations ■005 and part 2 of the answer.■006]\\n■end■\\n\\n**TYPE 3 - OUT OF TOPIC** (Use when question is completely unrelated to documents)\\n■out_of_topic\\n[Explain why it's unrelated]\\n■end■\\n\\n**TYPE 4 - INVALID QUESTION** (Use when input is not a proper question, e.g., gibberish, malformed or nonsensical)\\n■invalid_question\\n[Explain why it's invalid, e.g., \\\"The question is incomplete\\\" or \\\"The question contains nonsensical terms\\\", or \\\"Received gibberish\\\"]\\n■end■\\n\\n**TYPE 5 - MISSING KNOWLEDGE** (Use ONLY when documents lack specific details needed)\\n■missing_knowledge\\n[Explain what specific information is missing]\\n■end■\\n\\n# Important Rules\\n- PREFER answering when possible - only use missing_knowledge if truly no relevant info exists\\n- ALWAYS cite sources with line numbers\\n- Use ONLY information from the documents\\n- Be precise and factual\\n- Do NOT fabricate information\\n- Do NOT mention \\\"According to the documents\\\" or similar phrases – just provide a high-quality answer with citations\\n- Do not be too strict on the question format; assume high-level answers are acceptable unless the question clearly asks for very specific details or requests depth beyond the documents\\n\\n# Additional Instructions\\nHere are some additional instructions to follow about how to answer the question:\\nProvide a clear and concise answer based on the documents.\",\"role\":\"system\"},{\"content\":\"<documents>\\n■001 | Botpress was founded in 2016.\\n■002 | It is an AI agent platform.\\n■003 | The company is headquartered in Quebec, Canada.\\n</documents>\\n\\nPlease answer the below question using the format specified above.\\nQuestion to answer: \\\"Tell me about Botpress.\\\"\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.answer\",\"promptSource\":\"zai:zai.answer:default\"},\"model\":\"fast\",\"reasoningEffort\":\"none\",\"signal\":{},\"stopSequences\":[\"■end■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■answer\nBotpress was founded in 2016. It is an AI agent platform and the company is headquartered in Quebec, Canada.■001■002■003\n■end","metadata":{"provider":"cerebras","usage":{"inputTokens":684,"outputTokens":61,"inputCost":0.0002394,"outputCost":0.00004575},"model":"cerebras:gpt-oss-120b","ttft":281,"latency":649,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.00028515,"warnings":[{"type":"parameter_ignored","message":"Reasoning effort \"none\" is not supported by the \"gpt-oss-120b\" model, using \"low\" effort instead"}]}}}
+{"key":"cbc6f03c","input":"{\"body\":{\"messages\":[{\"content\":\"You are an expert research assistant specialized in answering questions using only the information provided in documents.\\n\\n# Task\\nAnswer the user's question based ONLY on the information in the provided documents. You MUST cite your sources using line numbers.\\n\\n# Document Format\\nDocuments are provided with line numbers:\\n■001 | First line of text\\n■002 | Second line of text\\n■003 | Third line of text\\n\\n# Citation Format\\nYou MUST include citations immediately after statements. Use these formats:\\n- Single line: ■035\\n- Range: ■005-010\\n- Multiple: ■035■046■094\\n\\n# Response Format\\n\\nChoose ONE of these response types:\\n\\n**TYPE 1 - ANSWER** (Use this when you can answer the question)\\n■answer\\n[Your answer with inline citations■001-003. Make sure each part is cited correctly■013. More text. ■015]\\n■end■\\n\\n**TYPE 2 - AMBIGUOUS** (Use when the question has multiple valid interpretations)\\n■ambiguous\\n[Explain the ambiguity]\\n■follow_up\\n[Ask a clarifying question]\\n■answer\\n[First interpretation with citations ■001 and part 2 as well.■002]\\n■answer\\n[Second interpretation with citations ■005 and part 2 of the answer.■006]\\n■end■\\n\\n**TYPE 3 - OUT OF TOPIC** (Use when question is completely unrelated to documents)\\n■out_of_topic\\n[Explain why it's unrelated]\\n■end■\\n\\n**TYPE 4 - INVALID QUESTION** (Use when input is not a proper question, e.g., gibberish, malformed or nonsensical)\\n■invalid_question\\n[Explain why it's invalid, e.g., \\\"The question is incomplete\\\" or \\\"The question contains nonsensical terms\\\", or \\\"Received gibberish\\\"]\\n■end■\\n\\n**TYPE 5 - MISSING KNOWLEDGE** (Use ONLY when documents lack specific details needed)\\n■missing_knowledge\\n[Explain what specific information is missing]\\n■end■\\n\\n# Important Rules\\n- PREFER answering when possible - only use missing_knowledge if truly no relevant info exists\\n- ALWAYS cite sources with line numbers\\n- Use ONLY information from the documents\\n- Be precise and factual\\n- Do NOT fabricate information\\n- Do NOT mention \\\"According to the documents\\\" or similar phrases – just provide a high-quality answer with citations\\n- Do not be too strict on the question format; assume high-level answers are acceptable unless the question clearly asks for very specific details or requests depth beyond the documents\\n\\n# Additional Instructions\\nHere are some additional instructions to follow about how to answer the question:\\nProvide a clear and concise answer based on the documents.\",\"role\":\"system\"},{\"content\":\"<documents>\\n■001 | The iPhone was first released by Apple in 2007.\\n■002 | Steve Jobs announced the iPhone at the Macworld conference.\\n■003 | The original iPhone had a 3.5-inch display and 2-megapixel camera.\\n■004 | The iPhone revolutionized the smartphone industry.\\n</documents>\\n\\nPlease answer the below question using the format specified above.\\nQuestion to answer: \\\"When was the iPhone released and who announced it?\\\"\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.answer\",\"promptSource\":\"zai:zai.answer:default\"},\"model\":\"fast\",\"reasoningEffort\":\"none\",\"signal\":{},\"stopSequences\":[\"■end■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■answer\nThe iPhone was first released by Apple in 2007■001, and it was announced by Steve Jobs at the Macworld conference■002.\n■end","metadata":{"provider":"cerebras","usage":{"inputTokens":721,"outputTokens":52,"inputCost":0.00025235,"outputCost":0.000039},"model":"cerebras:gpt-oss-120b","ttft":178,"latency":262,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.00029135,"warnings":[{"type":"parameter_ignored","message":"Reasoning effort \"none\" is not supported by the \"gpt-oss-120b\" model, using \"low\" effort instead"}]}}}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@botpress/zai",
   "description": "Zui AI (zai) – An LLM utility library written on top of Zui and the Botpress API",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/context.ts

@@ -18,22 +18,54 @@ export type ZaiContextProps = {
   source?: GenerateContentInput['meta']
 }
 
+/**
+ * Usage statistics tracking tokens, cost, and request metrics for an operation.
+ *
+ * This type is returned via Response events and the `.result()` method, providing
+ * real-time visibility into:
+ * - Token consumption (input/output/total)
+ * - Cost in USD (input/output/total)
+ * - Request statistics (count, errors, cache hits, progress percentage)
+ *
+ * @example
+ * ```typescript
+ * const { usage } = await zai.extract(text, schema).result()
+ *
+ * console.log(usage.tokens.total)    // 1250
+ * console.log(usage.cost.total)      // 0.0075 (USD)
+ * console.log(usage.requests.cached) // 0
+ * ```
+ */
 export type Usage = {
+  /** Request statistics */
   requests: {
+    /** Total number of requests initiated */
     requests: number
+    /** Number of requests that failed with errors */
     errors: number
+    /** Number of successful responses received */
     responses: number
+    /** Number of responses served from cache (no tokens used) */
     cached: number
+    /** Operation progress as a decimal (0.0 to 1.0) */
     percentage: number
   }
+  /** Cost statistics in USD */
   cost: {
+    /** Cost for input tokens */
     input: number
+    /** Cost for output tokens */
     output: number
+    /** Total cost (input + output) */
     total: number
   }
+  /** Token usage statistics */
   tokens: {
+    /** Input tokens consumed */
     input: number
+    /** Output tokens generated */
     output: number
+    /** Total tokens (input + output) */
     total: number
   }
 }

package/src/operations/answer.ts

@@ -136,11 +136,103 @@ const _Options = z.object({
 declare module '@botpress/zai' {
   interface Zai {
     /**
-     * Answer questions from a list of support documents with citations
-     * @param documents - Array of support documents (can be strings, objects, etc.)
+     * Answers questions from documents with citations and intelligent handling of edge cases.
+     *
+     * This operation provides a production-ready question-answering system that:
+     * - Cites sources with precise line references
+     * - Handles ambiguous questions with multiple interpretations
+     * - Detects out-of-topic or invalid questions
+     * - Identifies missing knowledge
+     * - Automatically chunks and processes large document sets
+     *
+     * @param documents - Array of documents to search (strings, objects, or any type)
      * @param question - The question to answer
-     * @param options - Optional configuration
-     * @returns Response with answer and citations, or other response types (ambiguous, out_of_topic, etc.)
+     * @param options - Configuration for chunking, examples, and instructions
+     * @returns Response with answer + citations, or error states (ambiguous, out_of_topic, invalid, missing_knowledge)
+     *
+     * @example Basic usage with string documents
+     * ```typescript
+     * const documents = [
+     *   'Botpress was founded in 2016.',
+     *   'The company is based in Quebec, Canada.',
+     *   'Botpress provides an AI agent platform.'
+     * ]
+     *
+     * const result = await zai.answer(documents, 'When was Botpress founded?')
+     * if (result.type === 'answer') {
+     *   console.log(result.answer) // "Botpress was founded in 2016."
+     *   console.log(result.citations) // [{ offset: 30, item: documents[0], snippet: '...' }]
+     * }
+     * ```
+     *
+     * @example With object documents
+     * ```typescript
+     * const products = [
+     *   { id: 1, name: 'Pro Plan', price: 99, features: ['AI', 'Analytics'] },
+     *   { id: 2, name: 'Enterprise', price: 499, features: ['AI', 'Support', 'SLA'] }
+     * ]
+     *
+     * const result = await zai.answer(products, 'What features does the Pro Plan include?')
+     * // Returns answer with citations pointing to the product objects
+     * ```
+     *
+     * @example Handling different response types
+     * ```typescript
+     * const result = await zai.answer(documents, question)
+     *
+     * switch (result.type) {
+     *   case 'answer':
+     *     console.log('Answer:', result.answer)
+     *     console.log('Sources:', result.citations)
+     *     break
+     *
+     *   case 'ambiguous':
+     *     console.log('Question is ambiguous:', result.ambiguity)
+     *     console.log('Clarifying question:', result.follow_up)
+     *     console.log('Possible answers:', result.answers)
+     *     break
+     *
+     *   case 'out_of_topic':
+     *     console.log('Question unrelated:', result.reason)
+     *     break
+     *
+     *   case 'invalid_question':
+     *     console.log('Invalid question:', result.reason)
+     *     break
+     *
+     *   case 'missing_knowledge':
+     *     console.log('Insufficient info:', result.reason)
+     *     break
+     * }
+     * ```
+     *
+     * @example With custom instructions
+     * ```typescript
+     * const result = await zai.answer(documents, 'What is the pricing?', {
+     *   instructions: 'Provide detailed pricing breakdown including all tiers',
+     *   chunkLength: 8000 // Process in smaller chunks for accuracy
+     * })
+     * ```
+     *
+     * @example Large document sets (auto-chunking)
+     * ```typescript
+     * // Handles thousands of documents automatically
+     * const manyDocs = await loadDocuments() // 1000+ documents
+     * const result = await zai.answer(manyDocs, 'What is the refund policy?')
+     * // Automatically chunks, processes in parallel, and merges results
+     * ```
+     *
+     * @example Tracking citations
+     * ```typescript
+     * const result = await zai.answer(documents, question)
+     * if (result.type === 'answer') {
+     *   result.citations.forEach(citation => {
+     *     console.log(`At position ${citation.offset}:`)
+     *     console.log(`  Cited: "${citation.snippet}"`)
+     *     console.log(`  From document:`, citation.item)
+     *   })
+     * }
+     * ```
      */
     answer<T>(documents: T[], question: string, options?: Options<T>): Response<AnswerResult<T>, AnswerResult<T>>
   }
@@ -490,6 +582,7 @@ Question to answer: "${question}"`
       },
     ],
     transform: (text) => {
+      text = text.slice(0, text.lastIndexOf(END.slice(0, -1))) // Remove anything after END
       // Parse and validate response - errors will be caught and retried
       return parseResponse(text || '', mappings)
     },
@@ -500,15 +593,18 @@ Question to answer: "${question}"`
 
 /**
  * Parse LLM response into structured result
+ * @internal - Exported for testing purposes only
  */
-const parseResponse = <T>(response: string, mappings: LineMapping<T>[]): AnswerResult<T> => {
+export const parseResponse = <T>(response: string, mappings: LineMapping<T>[]): AnswerResult<T> => {
   const text = response.trim()
 
+  const answersCount = (text.match(new RegExp(ANSWER_START, 'g')) || []).length
+
   // Check response type
-  if (text.includes(ANSWER_START)) {
-    return parseAnswerResponse(text, mappings)
-  } else if (text.includes(AMBIGUOUS_START)) {
+  if (text.includes(AMBIGUOUS_START) || answersCount >= 2) {
     return parseAmbiguousResponse(text, mappings)
+  } else if (text.includes(ANSWER_START)) {
+    return parseAnswerResponse(text, mappings)
   } else if (text.includes(OUT_OF_TOPIC_START)) {
     return parseOutOfTopicResponse(text)
   } else if (text.includes(INVALID_QUESTION_START)) {
@@ -569,7 +665,7 @@ const parseAmbiguousResponse = <T>(text: string, mappings: LineMapping<T>[]): Am
   // Extract all possible answers (match until next ■answer or end of string)
   const answerPattern = /■answer(.+?)(?=■answer|$)/gs
   const answers: AnswerWithCitations<T>[] = []
-  let match
+  let match: RegExpExecArray | null
 
   while ((match = answerPattern.exec(text)) !== null) {
     const answerText = match[1].trim()