@botpress/zai 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -33,22 +33,22 @@ declare const GenerationMetadata: _bpinternal_zui.ZodObject<{
         input?: number;
         output?: number;
     };
+    latency?: number;
     tokens?: {
         input?: number;
         output?: number;
     };
-    latency?: number;
 }, {
     model?: string;
     cost?: {
         input?: number;
         output?: number;
     };
+    latency?: number;
     tokens?: {
         input?: number;
         output?: number;
     };
-    latency?: number;
 }>;
 
 type SaveExampleProps<TInput, TOutput> = {
@@ -113,8 +113,8 @@ declare const ZaiConfig: _bpinternal_zui.ZodObject<{
     }>>;
     namespace: _bpinternal_zui.ZodDefault<_bpinternal_zui.ZodString>;
 }, "strip", _bpinternal_zui.ZodTypeAny, {
-    userId?: string;
     client?: Cognitive | BotpressClientLike;
+    userId?: string;
     modelId?: string;
     activeLearning?: {
         tableName?: string;
@@ -123,8 +123,8 @@ declare const ZaiConfig: _bpinternal_zui.ZodObject<{
     };
     namespace?: string;
 }, {
-    userId?: string;
     client?: Cognitive | BotpressClientLike;
+    userId?: string;
     modelId?: string;
     activeLearning?: {
         tableName?: string;
@@ -277,7 +277,12 @@ declare const Options$3: _bpinternal_zui.ZodObject<{
 declare module '@botpress/zai' {
     interface Zai {
         /** Checks wether a condition is true or not */
-        check(input: unknown, condition: string, options?: Options$3): Promise<boolean>;
+        check(input: unknown, condition: string, options?: Options$3): Promise<{
+            /** Whether the condition is true or not */
+            value: boolean;
+            /** The explanation of the decision */
+            explanation: string;
+        }>;
     }
 }
 
@@ -289,25 +294,25 @@ declare const Options$2: _bpinternal_zui.ZodObject<{
         filter: _bpinternal_zui.ZodBoolean;
         reason: _bpinternal_zui.ZodOptional<_bpinternal_zui.ZodString>;
     }, "strip", _bpinternal_zui.ZodTypeAny, {
-        filter?: boolean;
         input?: any;
+        filter?: boolean;
         reason?: string;
     }, {
-        filter?: boolean;
         input?: any;
+        filter?: boolean;
         reason?: string;
     }>, "many">>;
 }, "strip", _bpinternal_zui.ZodTypeAny, {
     examples?: {
-        filter?: boolean;
         input?: any;
+        filter?: boolean;
         reason?: string;
     }[];
     tokensPerItem?: number;
 }, {
     examples?: {
-        filter?: boolean;
         input?: any;
+        filter?: boolean;
         reason?: string;
     }[];
     tokensPerItem?: number;
@@ -410,7 +415,11 @@ declare module '@botpress/zai' {
     interface Zai {
         /** Tags the provided input with a list of predefined labels */
         label<T extends string>(input: unknown, labels: Labels<T>, options?: Options<T>): Promise<{
-            [K in T]: boolean;
+            [K in T]: {
+                explanation: string;
+                value: boolean;
+                confidence: number;
+            };
         }>;
     }
 }

package/dist/operations/check.js

@@ -42,7 +42,7 @@ Zai.prototype.check = async function(input, condition, _options) {
   }) : [];
   const exactMatch = examples.find((x) => x.key === Key);
   if (exactMatch) {
-    return exactMatch.output;
+    return { explanation: exactMatch.explanation ?? "", value: exactMatch.output };
   }
   const defaultExamples = [
     { input: "50 Cent", check: true, reason: "50 Cent is widely recognized as a public personality." },
@@ -121,6 +121,7 @@ In your "Analysis", please refer to the Expert Examples # to justify your decisi
     throw new Error(`The model did not return a valid answer. The response was: ${answer}`);
   }
   let finalAnswer;
+  const explanation = answer.replace(TRUE, "").replace(FALSE, "").replace(END, "").replace("Final Answer:", "").replace("Analysis:", "").trim();
   if (hasTrue && hasFalse) {
     finalAnswer = answer.lastIndexOf(TRUE) > answer.lastIndexOf(FALSE);
   } else {
@@ -146,8 +147,11 @@ In your "Analysis", please refer to the Expert Examples # to justify your decisi
         }
       },
       output: finalAnswer,
-      explanation: answer.replace(TRUE, "").replace(FALSE, "").replace(END, "").replace("Final Answer:", "").trim()
+      explanation
     });
   }
-  return finalAnswer;
+  return {
+    value: finalAnswer,
+    explanation: explanation.trim()
+  };
 };

package/dist/operations/label.js

@@ -55,6 +55,18 @@ const parseLabel = (label) => {
   }
   return LABELS.AMBIGUOUS;
 };
+const getConfidence = (label) => {
+  switch (label) {
+    case LABELS.ABSOLUTELY_NOT:
+    case LABELS.ABSOLUTELY_YES:
+      return 1;
+    case LABELS.PROBABLY_NOT:
+    case LABELS.PROBABLY_YES:
+      return 0.5;
+    default:
+      return 0;
+  }
+};
 Zai.prototype.label = async function(input, _labels, _options) {
   const options = Options.parse(_options ?? {});
   const labels = Labels.parse(_labels);
@@ -76,8 +88,10 @@ Zai.prototype.label = async function(input, _labels, _options) {
     const allLabels = await Promise.all(chunks.map((chunk2) => this.label(chunk2, _labels)));
     return allLabels.reduce((acc, x) => {
       Object.keys(x).forEach((key) => {
-        if (acc[key] === true) {
-          acc[key] = true;
+        if (acc[key]?.value === true) {
+          acc[key] = acc[key];
+        } else if (x[key]?.value === true) {
+          acc[key] = x[key];
         } else {
           acc[key] = acc[key] || x[key];
         }
@@ -96,7 +110,11 @@ Zai.prototype.label = async function(input, _labels, _options) {
   );
   const convertToAnswer = (mapping) => {
     return Object.keys(labels).reduce((acc, key) => {
-      acc[key] = mapping[key]?.label === "ABSOLUTELY_YES" || mapping[key]?.label === "PROBABLY_YES";
+      acc[key] = {
+        explanation: mapping[key]?.explanation ?? "",
+        value: mapping[key]?.label === LABELS.ABSOLUTELY_YES || mapping[key]?.label === LABELS.PROBABLY_YES,
+        confidence: getConfidence(mapping[key]?.label)
+      };
       return acc;
     }, {});
   };

package/e2e/data/cache.jsonl

@@ -105,3 +105,14 @@
 {"key":"d01b8e7","value":{"output":{"id":"chatcmpl-B65VO7tHpTROLR2PFoftMZaE5Jfyf","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■json_start■\n{\n  \"name\": \"JAMES BOND\",\n  \"movie\": \"CASINO ROYALE\"\n}\n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":405,"inputCost":0.0010125000000000002,"outputTokens":28,"outputCost":0.00028000000000000003},"botpress":{"cost":0.0012925000000000002}},"meta":{"cached":true}}}
 {"key":"138e86b7","value":{"output":{"id":"chatcmpl-B65hlbKAnvuGuGcAhuxPVKnN69Afl","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■START■Botpress is absolutely fantastic!","index":0,"stopReason":"stop"}],"usage":{"inputTokens":95,"inputCost":0.00023750000000000003,"outputTokens":9,"outputCost":0.00009},"botpress":{"cost":0.00032750000000000005}},"meta":{"cached":false}}}
 {"key":"42e66d0b","value":{"output":{"id":"chatcmpl-B65hq1endvtZB7KVSaoKfBwuS4nve","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■START■Botpress is absolutely incredible!","index":0,"stopReason":"stop"}],"usage":{"inputTokens":94,"inputCost":0.00023500000000000002,"outputTokens":9,"outputCost":0.00009},"botpress":{"cost":0.00032500000000000004}},"meta":{"cached":false}}}
+{"key":"b24750c2","value":{"output":{"id":"chatcmpl-BReZyP5RHIaBUTjo4gYV6XWN83ZIY","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■0:false  \n■1:true  \n■2:false  \n■3:true  \n■4:false  ","index":0,"stopReason":"stop"}],"usage":{"inputTokens":317,"inputCost":0.0007925,"outputTokens":21,"outputCost":0.00021},"botpress":{"cost":0.0010025}},"meta":{"cached":false}}}
+{"key":"3fee982e","value":{"output":{"id":"chatcmpl-BReZz9kGBc2kkqHDppuC1jvef4OXG","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■json_start■\n{\n  \"name\": \"JAMES BOND\",\n  \"movie\": \"CASINO ROYALE\"\n}\n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":284,"inputCost":0.00071,"outputTokens":28,"outputCost":0.00028000000000000003},"botpress":{"cost":0.00099}},"meta":{"cached":false}}}
+{"key":"bca8c242","value":{"output":{"id":"chatcmpl-BReZzhBpjrqZc9i3xZQd72soEYjIU","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: \"What's up\" is another common informal greeting in English, similar to \"hello!\" from Expert Example #1, as both serve as a way to initiate friendly communication. Since Expert Example #1 regards greetings positively (as shown by the answer being ■TRUE■), \"What's up\" should similarly be evaluated as ■TRUE■.\n\nFinal Answer: ■TRUE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":309,"inputCost":0.0007725000000000001,"outputTokens":75,"outputCost":0.00075},"botpress":{"cost":0.0015225}},"meta":{"cached":false}}}
+{"key":"c0182ff2","value":{"output":{"id":"chatcmpl-BRea0OnzIAwF7NjYjfNsmF2iYFGBH","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Based on the condition \"competes with us? (botpress)\", we determine whether each item is a competitor to Botpress (a conversational AI or chatbot-focused platform). Taking this into account:\n\n■0 = Nike → Not a chatbot platform; does not compete → **false**  \n■1 = Ada.cx → Conversational AI platform; competes → **true**  \n■2 = Adidas → Not a chatbot platform; does not compete → **false**  \n■3 = Moveworks → Conversational AI platform; competes → **true**  \n■4 = Lululemon → Not a chatbot platform; does not compete → **false**\n\nFinal Output:\n■0:false■1:true■2:false■3:true■4:false","index":0,"stopReason":"stop"}],"usage":{"inputTokens":239,"inputCost":0.0005975,"outputTokens":151,"outputCost":0.00151},"botpress":{"cost":0.0021075}},"meta":{"cached":false}}}
+{"key":"4808af91","value":{"output":{"id":"chatcmpl-BRea4fxYZvzR6j42CL2sifEuppEuR","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"■0:false■1:true■2:false■3:true■4:false","index":0,"stopReason":"stop"}],"usage":{"inputTokens":302,"inputCost":0.000755,"outputTokens":16,"outputCost":0.00016},"botpress":{"cost":0.000915}},"meta":{"cached":false}}}
+{"key":"216f51b3","value":{"output":{"id":"chatcmpl-BRfNoO17sUd83dAozRV4ULSNrL02h","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: Referring to Expert Example #1, the phrase \"what is up\" was considered NOT an official greeting. The input \"What's up\" is essentially the same phrase but in contracted form, and therefore should be treated the same way. Based on this, \"What's up\" is also NOT considered an official greeting. \n\nFinal Answer: ■FALSE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":365,"inputCost":0.0009125000000000001,"outputTokens":73,"outputCost":0.0007300000000000001},"botpress":{"cost":0.0016425000000000003}},"meta":{"cached":false}}}
+{"key":"d275ae64","value":{"output":{"id":"chatcmpl-BRfO9CunJK0edu6QzwK2XSOBqN3Oz","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: The phrase \"What's up\" is a common informal greeting, similar in meaning to \"hello.\" Unlike Expert Example #1 (\"wassup\"), which is highly informal slang and not universally considered a proper greeting, \"What's up\" is widely recognized as a greeting, even if informal. Expert Example #2 demonstrates that common greetings such as \"hello\" are considered TRUE, and \"What's up\" functions in a similar way.\n\nFinal Answer: ■TRUE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":372,"inputCost":0.00093,"outputTokens":93,"outputCost":0.00093},"botpress":{"cost":0.00186}},"meta":{"cached":false}}}
+{"key":"d9ea3351","value":{"output":{"id":"chatcmpl-BRfQe05pFZ6CDcvRz3FulZfaygVRa","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: In Expert Example #2, \"what is up\" is explicitly considered NOT an official greeting in the business scenario. The input \"What's up\" is the contraction of \"what is up\" and carries the exact same meaning and usage. Since Expert Example #2 determined \"what is up\" does not qualify as a greeting, the same reasoning applies to \"What's up.\" \n\nFinal Answer: ■FALSE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":428,"inputCost":0.00107,"outputTokens":84,"outputCost":0.00084},"botpress":{"cost":0.00191}},"meta":{"cached":false}}}
+{"key":"d17ac02e","value":{"output":{"id":"chatcmpl-BRfTPIN75pd3nYzGGyZ7HATPTpJvG","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: In Expert Example #1, the phrase \"what is up\" was analyzed and determined to be not considered an official greeting in the given business scenario. Similarly, \"What's up\" is an informal variation of the same phrase and aligns with the analysis in Example #1. Therefore, this input should also be considered not an official greeting based on the provided examples.\n\nFinal Answer: ■FALSE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":365,"inputCost":0.0009125000000000001,"outputTokens":81,"outputCost":0.0008100000000000001},"botpress":{"cost":0.0017225}},"meta":{"cached":false}}}
+{"key":"ef02ab44","value":{"output":{"id":"chatcmpl-BRfTSdx4wnjMxiOSK0VEXA2YlvT1D","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"Analysis: \"What's up\" is a phrase commonly used as a casual greeting. Referring to Expert Example #1, where \"wassup\" (a slang variant of \"What's up\") was considered not a formal greeting and the condition was deemed false, it would follow that \"What's up,\" while slightly more standard, falls under the same casual category and is not a formal greeting.\n\nFinal Answer: ■FALSE■  \n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":319,"inputCost":0.0007975,"outputTokens":84,"outputCost":0.00084},"botpress":{"cost":0.0016375}},"meta":{"cached":false}}}
+{"key":"e52b868e","value":{"output":{"id":"chatcmpl-BRfYXsEiwHHpIfQOoVTu8r9NCnzWQ","provider":"OpenAI","model":"gpt-4o-2024-11-20","choices":[{"role":"assistant","type":"text","content":"```\n■is_human:【The input refers to a person named Sylvain Perron, who is likely a human being. There is no suggestion otherwise.】:ABSOLUTELY_YES■\n\n■good_person:【The input mentions Sylvain Perron has no criminal record, which may suggest he is a law-abiding person. However, being a \"good person\" encompasses more than not having a criminal record, so the information is insufficient to confirm this.】:AMBIGUOUS■\n\n■bad_person:【The absence of a criminal record might indicate that Sylvain Perron is not a bad person, though this alone is insufficient to make an absolute judgment.】:PROBABLY_NOT■\n\n■canadian:【No explicit information is given about Sylvain Perron's nationality. However, according to Expert Example #1, where all users are assumed to be Canadian given the context, we can lean towards the assumption that Sylvain Perron is Canadian.】:ABSOLUTELY_YES■\n\n■is_french:【Sylvain is a common French name, as noted in Expert Example #1. \"Perron\" is also a French surname, which might suggest a French background. However, no explicit evidence confirms this person is French rather than Canadian with a French name.】:AMBIGUOUS■\n","index":0,"stopReason":"stop"}],"usage":{"inputTokens":1085,"inputCost":0.0027125,"outputTokens":271,"outputCost":0.00271},"botpress":{"cost":0.0054225}},"meta":{"cached":false}}}

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": "1.2.0",
+  "version": "2.0.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -23,7 +23,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@botpress/cognitive": "^0.1.6",
+    "@botpress/cognitive": "0.1.16",
     "json5": "^2.2.3",
     "jsonrepair": "^3.10.0",
     "lodash-es": "^4.17.21"

package/src/operations/check.ts

@@ -19,7 +19,16 @@ const Options = z.object({
 declare module '@botpress/zai' {
   interface Zai {
     /** Checks wether a condition is true or not */
-    check(input: unknown, condition: string, options?: Options): Promise<boolean>
+    check(
+      input: unknown,
+      condition: string,
+      options?: Options
+    ): Promise<{
+      /** Whether the condition is true or not */
+      value: boolean
+      /** The explanation of the decision */
+      explanation: string
+    }>
   }
 }
 
@@ -67,7 +76,7 @@ Zai.prototype.check = async function (this: Zai, input, condition, _options) {
 
   const exactMatch = examples.find((x) => x.key === Key)
   if (exactMatch) {
-    return exactMatch.output
+    return { explanation: exactMatch.explanation ?? '', value: exactMatch.output }
   }
 
   const defaultExamples = [
@@ -165,6 +174,13 @@ In your "Analysis", please refer to the Expert Examples # to justify your decisi
   }
 
   let finalAnswer: boolean
+  const explanation = answer
+    .replace(TRUE, '')
+    .replace(FALSE, '')
+    .replace(END, '')
+    .replace('Final Answer:', '')
+    .replace('Analysis:', '')
+    .trim()
 
   if (hasTrue && hasFalse) {
     // If both TRUE and FALSE are present, we need to check which one was answered last
@@ -193,9 +209,12 @@ In your "Analysis", please refer to the Expert Examples # to justify your decisi
         },
       },
       output: finalAnswer,
-      explanation: answer.replace(TRUE, '').replace(FALSE, '').replace(END, '').replace('Final Answer:', '').trim(),
+      explanation,
     })
   }
 
-  return finalAnswer
+  return {
+    value: finalAnswer,
+    explanation: explanation.trim(),
+  }
 }

package/src/operations/label.ts

@@ -14,6 +14,7 @@ const LABELS = {
   PROBABLY_YES: 'PROBABLY_YES',
   ABSOLUTELY_YES: 'ABSOLUTELY_YES',
 } as const
+
 const ALL_LABELS = Object.values(LABELS).join(' | ')
 
 type Example<T extends string> = {
@@ -78,7 +79,11 @@ declare module '@botpress/zai' {
       labels: Labels<T>,
       options?: Options<T>
     ): Promise<{
-      [K in T]: boolean
+      [K in T]: {
+        explanation: string
+        value: boolean
+        confidence: number
+      }
     }>
   }
 }
@@ -100,6 +105,20 @@ const parseLabel = (label: string): Label => {
   return LABELS.AMBIGUOUS
 }
 
+const getConfidence = (label: Label) => {
+  switch (label) {
+    case LABELS.ABSOLUTELY_NOT:
+    case LABELS.ABSOLUTELY_YES:
+      return 1
+
+    case LABELS.PROBABLY_NOT:
+    case LABELS.PROBABLY_YES:
+      return 0.5
+    default:
+      return 0
+  }
+}
+
 Zai.prototype.label = async function <T extends string>(this: Zai, input, _labels, _options) {
   const options = Options.parse(_options ?? {})
   const labels = Labels.parse(_labels)
@@ -127,15 +146,21 @@ Zai.prototype.label = async function <T extends string>(this: Zai, input, _label
     // Merge all the labels together (those who are true will remain true)
     return allLabels.reduce((acc, x) => {
       Object.keys(x).forEach((key) => {
-        if (acc[key] === true) {
-          acc[key] = true
+        if (acc[key]?.value === true) {
+          acc[key] = acc[key]
+        } else if (x[key]?.value === true) {
+          acc[key] = x[key]
         } else {
           acc[key] = acc[key] || x[key]
         }
       })
       return acc
     }, {}) as {
-      [K in T]: boolean
+      [K in T]: {
+        explanation: string
+        value: boolean
+        confidence: number
+      }
     }
   }
 
@@ -152,9 +177,19 @@ Zai.prototype.label = async function <T extends string>(this: Zai, input, _label
 
   const convertToAnswer = (mapping: { [K in T]: { explanation: string; label: Label } }) => {
     return Object.keys(labels).reduce((acc, key) => {
-      acc[key] = mapping[key]?.label === 'ABSOLUTELY_YES' || mapping[key]?.label === 'PROBABLY_YES'
+      acc[key] = {
+        explanation: mapping[key]?.explanation ?? '',
+        value: mapping[key]?.label === LABELS.ABSOLUTELY_YES || mapping[key]?.label === LABELS.PROBABLY_YES,
+        confidence: getConfidence(mapping[key]?.label),
+      }
       return acc
-    }, {}) as { [K in T]: boolean }
+    }, {}) as {
+      [K in T]: {
+        explanation: string
+        value: boolean
+        confidence: number
+      }
+    }
   }
 
   const examples = taskId