@botpress/zai 2.5.18 → 2.6.0

package/dist/context.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from "./emitter";
+import { fastHash } from "./utils";
 export class ZaiContext {
   _startedAt = Date.now();
   _inputCost = 0;
@@ -15,8 +16,10 @@ export class ZaiContext {
   adapter;
   source;
   _eventEmitter;
+  _memoizer;
   controller = new AbortController();
   _client;
+  static _noopMemoizer = { run: (_id, fn) => fn() };
   constructor(props) {
     this._client = props.client.clone();
     this.taskId = props.taskId;
@@ -24,6 +27,7 @@ export class ZaiContext {
     this.adapter = props.adapter;
     this.source = props.source;
     this.taskType = props.taskType;
+    this._memoizer = props.memoizer ?? ZaiContext._noopMemoizer;
     this._eventEmitter = new EventEmitter();
     this._client.on("request", () => {
       this._totalRequests++;
@@ -57,6 +61,16 @@ export class ZaiContext {
     this._eventEmitter.clear();
   }
   async generateContent(props) {
+    const memoKey = `zai:memo:${this.taskType}:${this.taskId || "default"}:${fastHash(
+      JSON.stringify({
+        s: props.systemPrompt,
+        m: props.messages?.map((m) => "content" in m ? m.content : ""),
+        st: props.stopSequences
+      })
+    )}`;
+    return this._memoizer.run(memoKey, () => this._generateContentInner(props));
+  }
+  async _generateContentInner(props) {
     const maxRetries = Math.max(props.maxRetries ?? 3, 0);
     const transform = props.transform;
     let lastError = null;

package/dist/index.d.ts

@@ -41,6 +41,16 @@ declare abstract class Adapter {
     abstract saveExample<TInput, TOutput>(props: SaveExampleProps<TInput, TOutput>): Promise<void>;
 }
 
+/**
+ * A memoizer that caches the result of async operations by a unique key.
+ *
+ * When used with the Botpress ADK workflow `step` function, this enables
+ * Zai operations to resume where they left off if a workflow is interrupted.
+ *
+ */
+type Memoizer = {
+    run: <T>(id: string, fn: () => Promise<T>) => Promise<T>;
+};
 /**
  * Active learning configuration for improving AI operations over time.
  *
@@ -98,6 +108,16 @@ type ZaiConfig = {
     activeLearning?: ActiveLearning;
     /** Namespace for organizing tasks (default: 'zai') */
     namespace?: string;
+    /**
+     * Memoizer (or factory returning one) for caching cognitive call results.
+     *
+     * When provided, all LLM calls are wrapped in the memoizer, allowing results
+     * to be cached and replayed. This is useful for resuming workflow runs where
+     * Zai operations have already completed their cognitive calls.
+     *
+     * If a factory function is provided, it is called once per Zai operation invocation.
+     */
+    memoize?: Memoizer | (() => Memoizer);
 };
 /**
  * Zai - A type-safe LLM utility library for production-ready AI operations.
@@ -171,6 +191,7 @@ declare class Zai {
     protected namespace: string;
     protected adapter: Adapter;
     protected activeLearning: ActiveLearning;
+    protected _memoize?: Memoizer | (() => Memoizer);
     /**
      * Creates a new Zai instance with the specified configuration.
      *
@@ -195,6 +216,8 @@ declare class Zai {
     constructor(config: ZaiConfig);
     /** @internal */
     protected callModel(props: Parameters<Cognitive['generateContent']>[0]): ReturnType<Cognitive['generateContent']>;
+    /** @internal */
+    protected _resolveMemoizer(): Memoizer | undefined;
     protected getTokenizer(): Promise<TextTokenizer>;
     protected fetchModelDetails(): Promise<void>;
     protected get taskId(): string;
@@ -299,6 +322,7 @@ type ZaiContextProps = {
     modelId: string;
     adapter?: Adapter;
     source?: GenerateContentInput['meta'];
+    memoizer?: Memoizer;
 };
 /**
  * Usage statistics tracking tokens, cost, and request metrics for an operation.
@@ -370,8 +394,10 @@ declare class ZaiContext {
     adapter?: Adapter;
     source?: GenerateContentInput['meta'];
     private _eventEmitter;
+    private _memoizer;
     controller: AbortController;
     private _client;
+    private static _noopMemoizer;
     constructor(props: ZaiContextProps);
     getModel(): Promise<Model>;
     on<K extends keyof ContextEvents>(type: K, listener: (event: ContextEvents[K]) => void): this;
@@ -382,6 +408,7 @@ declare class ZaiContext {
         text: string | undefined;
         extracted: Out;
     }>;
+    private _generateContentInner;
     get elapsedTime(): number;
     get usage(): Usage;
 }
@@ -2143,4 +2170,4 @@ declare module '@botpress/zai' {
     }
 }
 
-export { Zai };
+export { type Memoizer, Zai };

package/dist/operations/answer.js

@@ -373,7 +373,8 @@ Zai.prototype.answer = function(documents, question, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.answer",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(
     context,

package/dist/operations/check.js

@@ -181,7 +181,8 @@ Zai.prototype.check = function(input, condition, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.check",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, check(input, condition, options, context), (result) => result.value);
 };

package/dist/operations/extract.js

@@ -313,7 +313,8 @@ Zai.prototype.extract = function(input, schema, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.extract",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, extract(input, schema, _options, context), (result) => result);
 };

package/dist/operations/filter.js

@@ -202,7 +202,8 @@ Zai.prototype.filter = function(input, condition, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.filter",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, filter(input, condition, _options, context), (result) => result);
 };

package/dist/operations/group.js

@@ -541,7 +541,8 @@ Zai.prototype.group = function(input, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.group",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, group(input, _options, context), (result) => {
     const merged = {};

package/dist/operations/label.js

@@ -276,7 +276,8 @@ Zai.prototype.label = function(input, labels, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.label",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(
     context,

package/dist/operations/patch.js

@@ -392,7 +392,8 @@ Zai.prototype.patch = function(files, instructions, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.patch",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, patch(files, instructions, _options, context), (result) => result);
 };

package/dist/operations/rate.js

@@ -335,7 +335,8 @@ Zai.prototype.rate = function(input, instructions, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.rate",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(
     context,

package/dist/operations/rewrite.js

@@ -136,7 +136,8 @@ Zai.prototype.rewrite = function(original, prompt, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.rewrite",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, rewrite(original, prompt, _options, context), (result) => result);
 };

package/dist/operations/sort.js

@@ -511,7 +511,8 @@ Zai.prototype.sort = function(input, instructions, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.sort",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(
     context,

package/dist/operations/summarize.js

@@ -148,7 +148,8 @@ Zai.prototype.summarize = function(original, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "summarize",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, summarize(original, options, context), (value) => value);
 };

package/dist/operations/text.js

@@ -60,7 +60,8 @@ Zai.prototype.text = function(prompt, _options) {
     modelId: this.Model,
     taskId: this.taskId,
     taskType: "zai.text",
-    adapter: this.adapter
+    adapter: this.adapter,
+    memoizer: this._resolveMemoizer()
   });
   return new Response(context, text(prompt, _options, context), (result) => result);
 };

package/dist/zai.js

@@ -47,6 +47,7 @@ export class Zai {
   namespace;
   adapter;
   activeLearning;
+  _memoize;
   /**
    * Creates a new Zai instance with the specified configuration.
    *
@@ -80,6 +81,7 @@ export class Zai {
       client: this.client.client,
       tableName: parsed.activeLearning.tableName
     }) : new MemoryAdapter([]);
+    this._memoize = config.memoize;
   }
   /** @internal */
   async callModel(props) {
@@ -90,6 +92,13 @@ export class Zai {
       userId: this._userId
     });
   }
+  /** @internal */
+  _resolveMemoizer() {
+    if (!this._memoize) {
+      return void 0;
+    }
+    return typeof this._memoize === "function" ? this._memoize() : this._memoize;
+  }
   async getTokenizer() {
     Zai.tokenizer ??= await (async () => {
       while (!getWasmTokenizer) {

package/e2e/data/cache.jsonl

@@ -1971,3 +1971,8 @@
 {"key":"f8a39096","input":"{\"body\":{\"messages\":[{\"content\":\"You are grouping elements into cohesive groups.\\n\\n**Instructions:** Group by food type\\n\\n\\n**Important:**\\n- Each element gets exactly ONE group label\\n- Use EXACT SAME label for similar items (case-sensitive)\\n- Create new descriptive labels when needed\\n\\n**Output Format:**\\nOne line per element:\\n■0:Group Label■\\n■1:Group Label■\\n■END■\",\"role\":\"system\"},{\"content\":\"**Elements (■0 to ■11):**\\n■0: apple■\\n■1: banana■\\n■2: orange■\\n■3: mango■\\n■4: grape■\\n■5: carrot■\\n■6: broccoli■\\n■7: spinach■\\n■8: celery■\\n■9: kale■\\n■10: rice■\\n■11: wheat■\\n\\n**Task:** For each element, output one line with its group label.\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.group\",\"promptSource\":\"zai:zai.group:default\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:Fruit■  \n■1:Fruit■  \n■2:Fruit■  \n■3:Fruit■  \n■4:Fruit■  \n■5:Vegetable■  \n■6:Vegetable■  \n■7:Vegetable■  \n■8:Vegetable■  \n■9:Vegetable■  \n■10:Grain■  \n■11:Grain■  \n","metadata":{"provider":"cerebras","usage":{"inputTokens":250,"outputTokens":220,"inputCost":0.0000875,"outputCost":0.000165},"model":"cerebras:gpt-oss-120b","ttft":150,"latency":281,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0002525}}}
 {"key":"f5cec64f","input":"{\"body\":{\"messages\":[{\"content\":\"You are grouping elements into cohesive groups.\\n\\n**Instructions:** Group by food type\\n\\n\\n**Important:**\\n- Each element gets exactly ONE group label\\n- Use EXACT SAME label for similar items (case-sensitive)\\n- Create new descriptive labels when needed\\n\\n**Output Format:**\\nOne line per element:\\n■0:Group Label■\\n■1:Group Label■\\n■END■\",\"role\":\"system\"},{\"content\":\"**Existing Groups (prefer reusing these):**\\n- Fruit\\n- Vegetable\\n- Grain\\n\\n**Elements (■0 to ■11):**\\n■0: apple■\\n■1: banana■\\n■2: orange■\\n■3: mango■\\n■4: grape■\\n■5: carrot■\\n■6: broccoli■\\n■7: spinach■\\n■8: celery■\\n■9: kale■\\n■10: rice■\\n■11: wheat■\\n\\n**Task:** For each element, output one line with its group label.\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.group\",\"promptSource\":\"zai:zai.group:default\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:Fruit■  \n■1:Fruit■  \n■2:Fruit■  \n■3:Fruit■  \n■4:Fruit■  \n■5:Vegetable■  \n■6:Vegetable■  \n■7:Vegetable■  \n■8:Vegetable■  \n■9:Vegetable■  \n■10:Grain■  \n■11:Grain■  \n","metadata":{"provider":"cerebras","usage":{"inputTokens":269,"outputTokens":222,"inputCost":0.00009415,"outputCost":0.0001665},"model":"cerebras:gpt-oss-120b","ttft":154,"latency":296,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.00026065}}}
 {"key":"b2435b9e","input":"{\"body\":{\"messages\":[{\"content\":\"You are grouping elements into cohesive groups.\\n\\n**Instructions:** Group by food type\\n\\n\\n**Important:**\\n- Each element gets exactly ONE group label\\n- Use EXACT SAME label for similar items (case-sensitive)\\n- Create new descriptive labels when needed\\n\\n**Output Format:**\\nOne line per element:\\n■0:Group Label■\\n■1:Group Label■\\n■END■\",\"role\":\"system\"},{\"content\":\"**Existing Groups (prefer reusing these):**\\n- Fruit\\n- Vegetable\\n\\n**Elements (■0 to ■1):**\\n■0: rice■\\n■1: wheat■\\n\\n**Task:** For each element, output one line with its group label.\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.group\",\"promptSource\":\"zai:zai.group:default\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:Grain■\n■1:Grain■\n","metadata":{"provider":"cerebras","usage":{"inputTokens":206,"outputTokens":172,"inputCost":0.0000721,"outputCost":0.000129},"model":"cerebras:gpt-oss-120b","ttft":192,"latency":2310,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0002011}}}
+{"key":"f0425e37","input":"{\"body\":{\"messages\":[{\"content\":\"You are rating items based on evaluation criteria.\\n\\nEvaluation Criteria:\\n**relevance**:\\n  - very_bad (1): Content rarely relevant to your interests.\\n  - bad (2): Mostly irrelevant, occasional useful info.\\n  - average (3): Balanced relevance, some useful content.\\n  - good (4): Often relevant, aligns with interests.\\n  - very_good (5): Consistently highly relevant and valuable.\\n\\n**authority**:\\n  - very_bad (1): Sender lacks credibility, unknown source.\\n  - bad (2): Low credibility, questionable expertise overall.\\n  - average (3): Moderate credibility, recognized but not expert.\\n  - good (4): Credible source, recognized expertise in industry.\\n  - very_good (5): High authority, leading expert in field.\\n\\n**frequency**:\\n  - very_bad (1): Excessive emails, overwhelming inbox daily.\\n  - bad (2): Too many emails, frequent interruptions.\\n  - average (3): Moderate volume, acceptable cadence for work.\\n  - good (4): Well-paced, occasional useful messages that add value.\\n  - very_good (5): Sporadic, only essential communications when needed.\\n\\n**responsiveness**:\\n  - very_bad (1): Never replies, unresponsive to queries.\\n  - bad (2): Rarely replies, slow response times.\\n  - average (3): Occasional replies, average speed in normal timeframe.\\n  - good (4): Usually responsive, timely replies within days.\\n  - very_good (5): Rapid, consistently helpful responses to all requests.\\n\\nFor each item, rate it on EACH criterion using one of these labels:\\nvery_bad, bad, average, good, very_good\\n\\nOutput format:\\n■0:criterion1=label;criterion2=label;criterion3=label■\\n■1:criterion1=label;criterion2=label;criterion3=label■\\n■END■\\n\\nIMPORTANT:\\n- Rate every item (■0 to ■3)\\n- Use exact criterion names: relevance, authority, frequency, responsiveness\\n- Use exact label names: very_bad, bad, average, good, very_good\\n- Use semicolons (;) between criteria\\n- Use equals (=) between criterion and label\",\"role\":\"system\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"partner@sequoia.vc\\\",\\\"subject\\\":\\\"Q4 Review\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @sequoia.vc is our investor - highest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"analyst@bankofamerica.com\\\",\\\"subject\\\":\\\"Market Report\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_bad■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: analyst@* prefix is spam - lowest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"ben@a16z.com\\\",\\\"subject\\\":\\\"Investment Discussion\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @a16z.com is potential investor - high importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"team@google.com\\\",\\\"subject\\\":\\\"Partnership Proposal\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=average■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @google.com is competitor - medium importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"roelof@sequoia.vc\\\",\\\"subject\\\":\\\"Portfolio Update\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @sequoia.vc is our investor - highest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Items to rate (■0 to ■3):\\n■0: {\\\"from\\\":\\\"sarah@sequoia.vc\\\",\\\"subject\\\":\\\"Board Meeting\\\"}■\\n■1: {\\\"from\\\":\\\"analyst@goldmansachs.com\\\",\\\"subject\\\":\\\"Earnings Report\\\"}■\\n■2: {\\\"from\\\":\\\"marc@a16z.com\\\",\\\"subject\\\":\\\"Funding Round\\\"}■\\n■3: {\\\"from\\\":\\\"recruiter@google.com\\\",\\\"subject\\\":\\\"Hiring\\\"}■\\n\\nRate each item on all criteria.\\nOutput format: ■index:criterion1=label;criterion2=label■\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.rate\",\"promptSource\":\"zai:zai.rate:zai/rate\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:relevance=very_good;authority=very_good;frequency=good;responsiveness=good■\n■1:relevance=good;authority=good;frequency=average;responsiveness=average■\n■2:relevance=good;authority=good;frequency=good;responsiveness=good■\n■3:relevance=average;authority=average;frequency=average;responsiveness=average■\n","metadata":{"provider":"cerebras","usage":{"inputTokens":1049,"outputTokens":617,"inputCost":0.00036715,"outputCost":0.00046275},"model":"cerebras:gpt-oss-120b","ttft":207,"latency":494,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0008299}}}
+{"key":"61f23c23","input":"{\"body\":{\"messages\":[{\"content\":\"You are rating items based on evaluation criteria.\\n\\nEvaluation Criteria:\\n**relevance**:\\n  - very_bad (1): Content rarely relevant to your interests.\\n  - bad (2): Mostly irrelevant, occasional useful info.\\n  - average (3): Balanced relevance, some useful content.\\n  - good (4): Often relevant, aligns with interests.\\n  - very_good (5): Consistently highly relevant and valuable.\\n\\n**authority**:\\n  - very_bad (1): Sender lacks credibility, unknown source.\\n  - bad (2): Low credibility, questionable expertise overall.\\n  - average (3): Moderate credibility, recognized but not expert.\\n  - good (4): Credible source, recognized expertise in industry.\\n  - very_good (5): High authority, leading expert in field.\\n\\n**frequency**:\\n  - very_bad (1): Excessive emails, overwhelming inbox daily.\\n  - bad (2): Too many emails, frequent interruptions.\\n  - average (3): Moderate volume, acceptable cadence for work.\\n  - good (4): Well-paced, occasional useful messages that add value.\\n  - very_good (5): Sporadic, only essential communications when needed.\\n\\n**responsiveness**:\\n  - very_bad (1): Never replies, unresponsive to queries.\\n  - bad (2): Rarely replies, slow response times.\\n  - average (3): Occasional replies, average speed in normal timeframe.\\n  - good (4): Usually responsive, timely replies within days.\\n  - very_good (5): Rapid, consistently helpful responses to all requests.\\n\\nFor each item, rate it on EACH criterion using one of these labels:\\nvery_bad, bad, average, good, very_good\\n\\nOutput format:\\n■0:criterion1=label;criterion2=label;criterion3=label■\\n■1:criterion1=label;criterion2=label;criterion3=label■\\n■END■\\n\\nIMPORTANT:\\n- Rate every item (■0 to ■3)\\n- Use exact criterion names: relevance, authority, frequency, responsiveness\\n- Use exact label names: very_bad, bad, average, good, very_good\\n- Use semicolons (;) between criteria\\n- Use equals (=) between criterion and label\",\"role\":\"system\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"analyst@bankofamerica.com\\\",\\\"subject\\\":\\\"Market Report\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_bad■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: analyst@* prefix is spam - lowest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"ben@a16z.com\\\",\\\"subject\\\":\\\"Investment Discussion\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @a16z.com is potential investor - high importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"partner@sequoia.vc\\\",\\\"subject\\\":\\\"Q4 Review\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @sequoia.vc is our investor - highest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"team@google.com\\\",\\\"subject\\\":\\\"Partnership Proposal\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=average■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @google.com is competitor - medium importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"from\\\":\\\"roelof@sequoia.vc\\\",\\\"subject\\\":\\\"Portfolio Update\\\"}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:relevance=very_good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: RULE: @sequoia.vc is our investor - highest importance rating\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Items to rate (■0 to ■3):\\n■0: {\\\"from\\\":\\\"sarah@sequoia.vc\\\",\\\"subject\\\":\\\"Board Meeting\\\"}■\\n■1: {\\\"from\\\":\\\"analyst@goldmansachs.com\\\",\\\"subject\\\":\\\"Earnings Report\\\"}■\\n■2: {\\\"from\\\":\\\"marc@a16z.com\\\",\\\"subject\\\":\\\"Funding Round\\\"}■\\n■3: {\\\"from\\\":\\\"recruiter@google.com\\\",\\\"subject\\\":\\\"Hiring\\\"}■\\n\\nRate each item on all criteria.\\nOutput format: ■index:criterion1=label;criterion2=label■\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.rate\",\"promptSource\":\"zai:zai.rate:zai/rate\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:relevance=very_good;authority=very_good;frequency=very_good;responsiveness=good■\n■1:relevance=average;authority=good;frequency=average;responsiveness=average■\n■2:relevance=good;authority=very_good;frequency=very_good;responsiveness=good■\n■3:relevance=average;authority=good;frequency=average;responsiveness=average■\n","metadata":{"provider":"cerebras","usage":{"inputTokens":1049,"outputTokens":727,"inputCost":0.00036715,"outputCost":0.00054525},"model":"cerebras:gpt-oss-120b","ttft":155,"latency":695,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0009124}}}
+{"key":"85d80390","input":"{\"body\":{\"messages\":[{\"content\":\"You are rating items based on evaluation criteria.\\n\\nEvaluation Criteria:\\n**length**:\\n  - very_bad (1): Less than 4 characters\\n  - bad (2): 4 to 5 characters\\n  - average (3): 6 to 7 characters\\n  - good (4): 8 to 11 characters\\n  - very_good (5): 12 or more characters\\n\\n**complexity**:\\n  - very_bad (1): Only one character type used\\n  - bad (2): Two character types present\\n  - average (3): Three character types present\\n  - good (4): All four types, but predictable\\n  - very_good (5): All four types, highly random\\n\\n**strength**:\\n  - very_bad (1): Easily guessable, weak overall\\n  - bad (2): Low entropy, vulnerable to attacks\\n  - average (3): Moderate security, some protections\\n  - good (4): Strong security, resistant to cracking\\n  - very_good (5): Very high security, excellent protection\\n\\nFor each item, rate it on EACH criterion using one of these labels:\\nvery_bad, bad, average, good, very_good\\n\\nOutput format:\\n■0:criterion1=label;criterion2=label;criterion3=label■\\n■1:criterion1=label;criterion2=label;criterion3=label■\\n■END■\\n\\nIMPORTANT:\\n- Rate every item (■0 to ■1)\\n- Use exact criterion names: length, complexity, strength\\n- Use exact label names: very_bad, bad, average, good, very_good\\n- Use semicolons (;) between criteria\\n- Use equals (=) between criterion and label\",\"role\":\"system\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"password\\\":\\\"Str0ng!P@ss#2024\\\",\\\"length\\\":16,\\\"hasAll\\\":true}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:length=very_good;complexity=very_good;strength=very_good■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: Strong password: 16 chars, all character types\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example - Items to rate:\\n■0: {\\\"password\\\":\\\"weak\\\",\\\"length\\\":4,\\\"hasAll\\\":false}■\\n\\nRate each item on all criteria.\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■0:length=very_bad;complexity=very_bad;strength=very_bad■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Reasoning: Weak password: only 4 chars, missing character types\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Items to rate (■0 to ■1):\\n■0: {\\\"password\\\":\\\"MyStr0ng!Pass\\\",\\\"length\\\":13,\\\"hasAll\\\":true}■\\n■1: {\\\"password\\\":\\\"bad\\\",\\\"length\\\":3,\\\"hasAll\\\":false}■\\n\\nRate each item on all criteria.\\nOutput format: ■index:criterion1=label;criterion2=label■\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.rate\",\"promptSource\":\"zai:zai.rate:zai/rate\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■0:length=very_good;complexity=very_good;strength=very_good■\n■1:length=very_bad;complexity=very_bad;strength=very_bad■\n","metadata":{"provider":"cerebras","usage":{"inputTokens":682,"outputTokens":323,"inputCost":0.0002387,"outputCost":0.00024225},"model":"cerebras:gpt-oss-120b","ttft":171,"latency":357,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.00048095}}}
+{"key":"c99aa38f","input":"{\"body\":{\"messages\":[{\"content\":\"Check if the following condition is true or false for the given input. Before answering, make sure to read the input and the condition carefully.\\nJustify your answer, then answer with either ■TRUE■ or ■FALSE■ at the very end, then add ■END■ to finish the response.\\nIMPORTANT: Make sure to answer with either ■TRUE■ or ■FALSE■ at the end of your response, but NOT both.\\n---\\nExpert Examples (#1 to #3):\\n- You have been provided with examples from previous experts. Make sure to read them carefully before making your decision.\\n- Make sure to refer to the examples provided by the experts to justify your decision (when applicable).\\n- When in doubt, ground your decision on the examples provided by the experts instead of your own intuition.\\n- When no example is similar to the input, make sure to provide a clear justification for your decision while inferring the decision-making process from the examples provided by the experts.\",\"role\":\"system\"},{\"content\":\"Expert Example #1\\n<|start_input|>\\nwhat is up\\n<|end_input|>\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"Analysis: \\\"What's up\\\" in our business scenario is NOT considered an official greeting.\\nFinal Answer: ■FALSE■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example #2\\n<|start_input|>\\nhello! how are you?\\n<|end_input|>\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"Analysis: \\\"hello!\\\" is a common greeting in English.\\nFinal Answer: ■TRUE■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Expert Example #3\\n<|start_input|>\\nwassup\\n<|end_input|>\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"Analysis: \\\"wassup\\\" is a slang term and not considered a formal greeting. It is therefore NOT considered a greeting.\\nFinal Answer: ■FALSE■\\n■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Considering the below input and above examples, is the following condition true or false?\\nExpert Example #4\\n<|start_input|>\\nWhat's up\\n<|end_input|>\\nIn your \\\"Analysis\\\", please refer to the Expert Examples # to justify your decision.\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.check\",\"promptSource\":\"zai:zai.check:zai/check\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"**Analysis:**  \nThe task is to decide whether the provided text qualifies as a greeting. The expert examples illustrate the decision criteria:\n\n- **Example #1** (“what is up”) – judged **FALSE** because this informal phrase is not counted as a greeting.  \n- **Example #2** (“hello! how are you?”) – judged **TRUE** as it contains a standard greeting (“hello”).  \n- **Example #3** (“wassup”) – judged **FALSE** since it is slang and not a formal greeting.\n\nThe input in **Example #4** is “What’s up”. This expression is essentially the same informal phrase as “what is up” and “wassup”, both of which were classified as **FALSE** in the earlier examples. Therefore, following the established pattern, “What’s up” should also be considered **not** a greeting.\n\n**Conclusion:** The condition (that the input is a greeting) is **false** for the given input.\n\n■FALSE■  \n","metadata":{"provider":"cerebras","usage":{"inputTokens":497,"outputTokens":373,"inputCost":0.00017395,"outputCost":0.00027975},"model":"cerebras:gpt-oss-120b","ttft":171,"latency":415,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0004537}}}
+{"key":"b8f325eb","input":"{\"body\":{\"messages\":[{\"content\":\"Rewrite the text between the ■START■ and ■END■ tags to match the user prompt.\",\"role\":\"system\"},{\"content\":\"Prompt: write it like we want it\\n\\n■START■\\nMicrosoft is a big company\\n■END■\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■START■# MICROSOFT IS A BIG COMPANY■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Prompt: write it like we want it\\n\\n■START■\\nGoogle is an evil company\\n■END■\",\"role\":\"user\",\"type\":\"text\"},{\"content\":\"■START■# GOOGLE IS AN EVIL COMPANY■END■\",\"role\":\"assistant\",\"type\":\"text\"},{\"content\":\"Prompt: write it like we want it\\n\\n■START■\\nBotpress is awesome\\n■END■\",\"role\":\"user\",\"type\":\"text\"}],\"meta\":{\"integrationName\":\"zai\",\"promptCategory\":\"zai:zai.rewrite\",\"promptSource\":\"zai:zai.rewrite:zai/rewrite\"},\"model\":\"fast\",\"signal\":{},\"stopSequences\":[\"■END■\"]},\"method\":\"POST\",\"url\":\"https://api.botpress.cloud/v2/cognitive/generate-text\"}","value":{"output":"■START■# BOTPRESS IS AWESOME","metadata":{"provider":"cerebras","usage":{"inputTokens":205,"outputTokens":171,"inputCost":0.00007175,"outputCost":0.00012825},"model":"cerebras:gpt-oss-120b","ttft":174,"latency":953,"cached":false,"fallbackPath":[],"stopReason":"stop","cost":0.0002}}}

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.5.18",
+  "version": "2.6.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/context.ts

@@ -1,6 +1,8 @@
 import { Cognitive, Model, GenerateContentInput, GenerateContentOutput } from '@botpress/cognitive'
 import { Adapter } from './adapters/adapter'
 import { EventEmitter } from './emitter'
+import { fastHash } from './utils'
+import type { Memoizer } from './zai'
 
 type Meta = Awaited<ReturnType<Cognitive['generateContent']>>['meta']
 
@@ -16,6 +18,7 @@ export type ZaiContextProps = {
   modelId: string
   adapter?: Adapter
   source?: GenerateContentInput['meta']
+  memoizer?: Memoizer
 }
 
 /**
@@ -94,10 +97,13 @@ export class ZaiContext {
   public source?: GenerateContentInput['meta']
 
   private _eventEmitter: EventEmitter<ContextEvents>
+  private _memoizer: Memoizer
 
   public controller: AbortController = new AbortController()
   private _client: Cognitive
 
+  private static _noopMemoizer: Memoizer = { run: (_id, fn) => fn() }
+
   public constructor(props: ZaiContextProps) {
     this._client = props.client.clone()
     this.taskId = props.taskId
@@ -105,6 +111,7 @@ export class ZaiContext {
     this.adapter = props.adapter
     this.source = props.source
     this.taskType = props.taskType
+    this._memoizer = props.memoizer ?? ZaiContext._noopMemoizer
     this._eventEmitter = new EventEmitter<ContextEvents>()
 
     this._client.on('request', () => {
@@ -148,6 +155,20 @@ export class ZaiContext {
 
   public async generateContent<Out = string>(
     props: GenerateContentProps<Out>
+  ): Promise<{ meta: Meta; output: GenerateContentOutput; text: string | undefined; extracted: Out }> {
+    const memoKey = `zai:memo:${this.taskType}:${this.taskId || 'default'}:${fastHash(
+      JSON.stringify({
+        s: props.systemPrompt,
+        m: props.messages?.map((m) => ('content' in m ? m.content : '')),
+        st: props.stopSequences,
+      })
+    )}`
+
+    return this._memoizer.run(memoKey, () => this._generateContentInner(props))
+  }
+
+  private async _generateContentInner<Out = string>(
+    props: GenerateContentProps<Out>
   ): Promise<{ meta: Meta; output: GenerateContentOutput; text: string | undefined; extracted: Out }> {
     const maxRetries = Math.max(props.maxRetries ?? 3, 0)
     const transform = props.transform

package/src/index.ts

@@ -1,4 +1,4 @@
-import { Zai } from './zai'
+import { Zai, type Memoizer } from './zai'
 
 import './operations/text'
 import './operations/rewrite'
@@ -14,3 +14,4 @@ import './operations/answer'
 import './operations/patch'
 
 export { Zai }
+export type { Memoizer }

package/src/operations/answer.ts

@@ -816,6 +816,7 @@ Zai.prototype.answer = function <T>(
     taskId: this.taskId,
     taskType: 'zai.answer',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<AnswerResult<T>, AnswerResult<T>>(

package/src/operations/check.ts

@@ -354,6 +354,7 @@ Zai.prototype.check = function (
     taskId: this.taskId,
     taskType: 'zai.check',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<

package/src/operations/extract.ts

@@ -484,6 +484,7 @@ Zai.prototype.extract = function <S extends OfType<AnyObjectOrArray>>(
     taskId: this.taskId,
     taskType: 'zai.extract',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<S['_output']>(context, extract(input, schema, _options, context), (result) => result)

package/src/operations/filter.ts

@@ -363,6 +363,7 @@ Zai.prototype.filter = function <T>(
     taskId: this.taskId,
     taskType: 'zai.filter',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<Array<T>>(context, filter(input, condition, _options, context), (result) => result)

package/src/operations/group.ts

@@ -955,6 +955,7 @@ Zai.prototype.group = function <T>(
     taskId: this.taskId,
     taskType: 'zai.group',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<Array<Group<T>>, Record<string, T[]>>(context, group(input, _options, context), (result) => {

package/src/operations/label.ts

@@ -542,6 +542,7 @@ Zai.prototype.label = function <T extends string>(
     taskId: this.taskId,
     taskType: 'zai.label',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<

package/src/operations/patch.ts

@@ -650,6 +650,7 @@ Zai.prototype.patch = function (
     taskId: this.taskId,
     taskType: 'zai.patch',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<Array<File>>(context, patch(files, instructions, _options, context), (result) => result)

package/src/operations/rate.ts

@@ -611,6 +611,7 @@ Zai.prototype.rate = function <T, I extends RatingInstructions>(
     taskId: this.taskId,
     taskType: 'zai.rate',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<Array<RatingResult<I>>, Array<SimplifiedRatingResult<I>>>(

package/src/operations/rewrite.ts

@@ -277,6 +277,7 @@ Zai.prototype.rewrite = function (this: Zai, original: string, prompt: string, _
     taskId: this.taskId,
     taskType: 'zai.rewrite',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<string>(context, rewrite(original, prompt, _options, context), (result) => result)

package/src/operations/sort.ts

@@ -800,6 +800,7 @@ Zai.prototype.sort = function <T>(
     taskId: this.taskId,
     taskType: 'zai.sort',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<Array<T>, Array<T>>(

package/src/operations/summarize.ts

@@ -306,6 +306,7 @@ Zai.prototype.summarize = function (this: Zai, original, _options): Response<str
     taskId: this.taskId,
     taskType: 'summarize',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<string, string>(context, summarize(original, options, context), (value) => value)

package/src/operations/text.ts

@@ -135,6 +135,7 @@ Zai.prototype.text = function (this: Zai, prompt: string, _options?: Options): R
     taskId: this.taskId,
     taskType: 'zai.text',
     adapter: this.adapter,
+    memoizer: this._resolveMemoizer(),
   })
 
   return new Response<string>(context, text(prompt, _options, context), (result) => result)

package/src/zai.ts

@@ -8,6 +8,17 @@ import { Adapter } from './adapters/adapter'
 import { TableAdapter } from './adapters/botpress-table'
 import { MemoryAdapter } from './adapters/memory'
 
+/**
+ * A memoizer that caches the result of async operations by a unique key.
+ *
+ * When used with the Botpress ADK workflow `step` function, this enables
+ * Zai operations to resume where they left off if a workflow is interrupted.
+ *
+ */
+export type Memoizer = {
+  run: <T>(id: string, fn: () => Promise<T>) => Promise<T>
+}
+
 /**
  * Active learning configuration for improving AI operations over time.
  *
@@ -86,6 +97,16 @@ type ZaiConfig = {
   activeLearning?: ActiveLearning
   /** Namespace for organizing tasks (default: 'zai') */
   namespace?: string
+  /**
+   * Memoizer (or factory returning one) for caching cognitive call results.
+   *
+   * When provided, all LLM calls are wrapped in the memoizer, allowing results
+   * to be cached and replayed. This is useful for resuming workflow runs where
+   * Zai operations have already completed their cognitive calls.
+   *
+   * If a factory function is provided, it is called once per Zai operation invocation.
+   */
+  memoize?: Memoizer | (() => Memoizer)
 }
 
 const _ZaiConfig = z.object({
@@ -195,6 +216,7 @@ export class Zai {
   protected namespace: string
   protected adapter: Adapter
   protected activeLearning: ActiveLearning
+  protected _memoize?: Memoizer | (() => Memoizer)
 
   /**
    * Creates a new Zai instance with the specified configuration.
@@ -236,6 +258,8 @@ export class Zai {
           tableName: parsed.activeLearning.tableName,
         })
       : new MemoryAdapter([])
+
+    this._memoize = config.memoize
   }
 
   /** @internal */
@@ -250,6 +274,14 @@ export class Zai {
     })
   }
 
+  /** @internal */
+  protected _resolveMemoizer(): Memoizer | undefined {
+    if (!this._memoize) {
+      return undefined
+    }
+    return typeof this._memoize === 'function' ? this._memoize() : this._memoize
+  }
+
   protected async getTokenizer() {
     Zai.tokenizer ??= await (async () => {
       while (!getWasmTokenizer) {