@botpress/zai 1.0.1 → 1.1.0

package/dist/operations/rewrite.js

@@ -0,0 +1,111 @@
+import { z } from "@bpinternal/zui";
+import { fastHash, stringify, takeUntilTokens } from "../utils";
+import { Zai } from "../zai";
+import { PROMPT_INPUT_BUFFER } from "./constants";
+const Example = z.object({
+  input: z.string(),
+  output: z.string()
+});
+const Options = z.object({
+  examples: z.array(Example).default([]),
+  length: z.number().min(10).max(16e3).optional().describe("The maximum number of tokens to generate")
+});
+const START = "\u25A0START\u25A0";
+const END = "\u25A0END\u25A0";
+Zai.prototype.rewrite = async function(original, prompt, _options) {
+  const options = Options.parse(_options ?? {});
+  const tokenizer = await this.getTokenizer();
+  const taskId = this.taskId;
+  const taskType = "zai.rewrite";
+  const INPUT_COMPONENT_SIZE = Math.max(100, (this.Model.input.maxTokens - PROMPT_INPUT_BUFFER) / 2);
+  prompt = tokenizer.truncate(prompt, INPUT_COMPONENT_SIZE);
+  const inputSize = tokenizer.count(original) + tokenizer.count(prompt);
+  const maxInputSize = this.Model.input.maxTokens - tokenizer.count(prompt) - PROMPT_INPUT_BUFFER;
+  if (inputSize > maxInputSize) {
+    throw new Error(
+      `The input size is ${inputSize} tokens long, which is more than the maximum of ${maxInputSize} tokens for this model (${this.Model.name} = ${this.Model.input.maxTokens} tokens)`
+    );
+  }
+  const instructions = [];
+  const originalSize = tokenizer.count(original);
+  if (options.length && originalSize > options.length) {
+    instructions.push(`The original text is ${originalSize} tokens long \u2013 it should be less than ${options.length}`);
+    instructions.push(
+      `The text must be standalone and complete in less than ${options.length} tokens, so it has to be shortened to fit the length as well`
+    );
+  }
+  const format = (before, prompt2) => {
+    return `
+Prompt: ${prompt2}
+
+${START}
+${before}
+${END}
+`.trim();
+  };
+  const Key = fastHash(
+    stringify({
+      taskId,
+      taskType,
+      input: original,
+      prompt
+    })
+  );
+  const formatExample = ({ input, output: output2, instructions: instructions2 }) => {
+    return [
+      { type: "text", role: "user", content: format(input, instructions2 || prompt) },
+      { type: "text", role: "assistant", content: `${START}${output2}${END}` }
+    ];
+  };
+  const defaultExamples = [
+    { input: "Hello, how are you?", output: "Bonjour, comment \xE7a va?", instructions: "translate to French" },
+    { input: "1\n2\n3", output: "3\n2\n1", instructions: "reverse the order" }
+  ];
+  const tableExamples = taskId ? await this.adapter.getExamples({
+    input: original,
+    taskId,
+    taskType
+  }) : [];
+  const exactMatch = tableExamples.find((x) => x.key === Key);
+  if (exactMatch) {
+    return exactMatch.output;
+  }
+  const savedExamples = [
+    ...tableExamples.map((x) => ({ input: x.input, output: x.output })),
+    ...options.examples
+  ];
+  const REMAINING_TOKENS = this.Model.input.maxTokens - tokenizer.count(prompt) - PROMPT_INPUT_BUFFER;
+  const examples = takeUntilTokens(
+    savedExamples.length ? savedExamples : defaultExamples,
+    REMAINING_TOKENS,
+    (el) => tokenizer.count(stringify(el.input)) + tokenizer.count(stringify(el.output))
+  ).map(formatExample).flat();
+  const output = await this.callModel({
+    systemPrompt: `
+Rewrite the text between the ${START} and ${END} tags to match the user prompt.
+${instructions.map((x) => `\u2022 ${x}`).join("\n")}
+`.trim(),
+    messages: [...examples, { type: "text", content: format(original, prompt), role: "user" }],
+    maxTokens: options.length,
+    stopSequences: [END]
+  });
+  let result = output.choices[0]?.content;
+  if (result.includes(START)) {
+    result = result.slice(result.indexOf(START) + START.length);
+  }
+  if (result.includes(END)) {
+    result = result.slice(0, result.indexOf(END));
+  }
+  if (taskId) {
+    await this.adapter.saveExample({
+      key: Key,
+      metadata: output.metadata,
+      instructions: prompt,
+      input: original,
+      output: result,
+      taskType,
+      taskId
+    });
+  }
+  return result;
+};

package/dist/operations/summarize.js

@@ -0,0 +1,132 @@
+import { z } from "@bpinternal/zui";
+import { chunk } from "lodash-es";
+import { Zai } from "../zai";
+import { PROMPT_INPUT_BUFFER, PROMPT_OUTPUT_BUFFER } from "./constants";
+const Options = z.object({
+  prompt: z.string().describe("What should the text be summarized to?").default("New information, concepts and ideas that are deemed important"),
+  format: z.string().describe("How to format the example text").default(
+    "A normal text with multiple sentences and paragraphs. Use markdown to format the text into sections. Use headings, lists, and other markdown features to make the text more readable. Do not include links, images, or other non-text elements."
+  ),
+  length: z.number().min(10).max(1e5).describe("The length of the summary in tokens").default(250),
+  intermediateFactor: z.number().min(1).max(10).describe("How many times longer (than final length) are the intermediate summaries generated").default(4),
+  maxIterations: z.number().min(1).default(100),
+  sliding: z.object({
+    window: z.number().min(10).max(1e5),
+    overlap: z.number().min(0).max(1e5)
+  }).describe("Sliding window options").default({ window: 5e4, overlap: 250 })
+});
+const START = "\u25A0START\u25A0";
+const END = "\u25A0END\u25A0";
+Zai.prototype.summarize = async function(original, _options) {
+  const options = Options.parse(_options ?? {});
+  const tokenizer = await this.getTokenizer();
+  const INPUT_COMPONENT_SIZE = Math.max(100, (this.Model.input.maxTokens - PROMPT_INPUT_BUFFER) / 4);
+  options.prompt = tokenizer.truncate(options.prompt, INPUT_COMPONENT_SIZE);
+  options.format = tokenizer.truncate(options.format, INPUT_COMPONENT_SIZE);
+  const maxOutputSize = this.Model.output.maxTokens - PROMPT_OUTPUT_BUFFER;
+  if (options.length > maxOutputSize) {
+    throw new Error(
+      `The desired output length is ${maxOutputSize} tokens long, which is more than the maximum of ${this.Model.output.maxTokens} tokens for this model (${this.Model.name})`
+    );
+  }
+  options.sliding.window = Math.min(options.sliding.window, this.Model.input.maxTokens - PROMPT_INPUT_BUFFER);
+  options.sliding.overlap = Math.min(options.sliding.overlap, options.sliding.window - 3 * options.sliding.overlap);
+  const format = (summary, newText) => {
+    return `
+${START}
+${summary.length ? summary : "<summary still empty>"}
+${END}
+
+Please amend the summary between the ${START} and ${END} tags to accurately reflect the prompt and the additional text below.
+
+<|start_new_information|>
+${newText}
+<|new_information|>`.trim();
+  };
+  const tokens = tokenizer.split(original);
+  const parts = Math.ceil(tokens.length / (options.sliding.window - options.sliding.overlap));
+  let iteration = 0;
+  const N = 2;
+  const useMergeSort = parts >= Math.pow(2, N);
+  const chunkSize = Math.ceil(tokens.length / (parts * N));
+  if (useMergeSort) {
+    const chunks = chunk(tokens, chunkSize).map((x) => x.join(""));
+    const allSummaries = await Promise.all(chunks.map((chunk2) => this.summarize(chunk2, options)));
+    return this.summarize(allSummaries.join("\n\n============\n\n"), options);
+  }
+  const summaries = [];
+  let currentSummary = "";
+  for (let i = 0; i < tokens.length; i += options.sliding.window) {
+    const from = Math.max(0, i - options.sliding.overlap);
+    const to = Math.min(tokens.length, i + options.sliding.window + options.sliding.overlap);
+    const isFirst = i === 0;
+    const isLast = to >= tokens.length;
+    const slice = tokens.slice(from, to).join("");
+    if (iteration++ >= options.maxIterations) {
+      break;
+    }
+    const instructions = [
+      `At each step, you will receive a part of the text to summarize. Make sure to reply with the new summary in the tags ${START} and ${END}.`,
+      "Summarize the text and make sure that the main points are included.",
+      "Ignore any unnecessary details and focus on the main points.",
+      "Use short and concise sentences to increase readability and information density.",
+      "When looking at the new information, focus on: " + options.prompt
+    ];
+    if (isFirst) {
+      instructions.push(
+        "The current summary is empty. You need to generate a summary that covers the main points of the text."
+      );
+    }
+    let generationLength = options.length;
+    if (!isLast) {
+      generationLength = Math.min(
+        tokenizer.count(currentSummary) + options.length * options.intermediateFactor,
+        maxOutputSize
+      );
+      instructions.push(
+        "You need to amend the summary to include the new information. Make sure the summary is complete and covers all the main points."
+      );
+      instructions.push(`The current summary is ${currentSummary.length} tokens long.`);
+      instructions.push(`You can amend the summary to be up to ${generationLength} tokens long.`);
+    }
+    if (isLast) {
+      instructions.push(
+        "This is the last part you will have to summarize. Make sure the summary is complete and covers all the main points."
+      );
+      instructions.push(
+        `The current summary is ${currentSummary.length} tokens long. You need to make sure it is ${options.length} tokens or less.`
+      );
+      if (currentSummary.length > options.length) {
+        instructions.push(
+          `The current summary is already too long, so you need to shorten it to ${options.length} tokens while also including the new information.`
+        );
+      }
+    }
+    const output = await this.callModel({
+      systemPrompt: `
+You are summarizing a text. The text is split into ${parts} parts, and you are currently working on part ${iteration}.
+At every step, you will receive the current summary and a new part of the text. You need to amend the summary to include the new information (if needed).
+The summary needs to cover the main points of the text and must be concise.
+
+IMPORTANT INSTRUCTIONS:
+${instructions.map((x) => `- ${x.trim()}`).join("\n")}
+
+FORMAT OF THE SUMMARY:
+${options.format}
+`.trim(),
+      messages: [{ type: "text", content: format(currentSummary, slice), role: "user" }],
+      maxTokens: generationLength,
+      stopSequences: [END]
+    });
+    let result = output?.choices[0]?.content;
+    if (result.includes(START)) {
+      result = result.slice(result.indexOf(START) + START.length);
+    }
+    if (result.includes("\u25A0")) {
+      result = result.slice(0, result.indexOf("\u25A0"));
+    }
+    summaries.push(result);
+    currentSummary = result;
+  }
+  return currentSummary.trim();
+};

package/dist/operations/text.js

@@ -0,0 +1,46 @@
+import { z } from "@bpinternal/zui";
+import { clamp } from "lodash-es";
+import { Zai } from "../zai";
+import { PROMPT_INPUT_BUFFER, PROMPT_OUTPUT_BUFFER } from "./constants";
+const Options = z.object({
+  length: z.number().min(1).max(1e5).optional().describe("The maximum number of tokens to generate")
+});
+Zai.prototype.text = async function(prompt, _options) {
+  const options = Options.parse(_options ?? {});
+  const tokenizer = await this.getTokenizer();
+  prompt = tokenizer.truncate(prompt, Math.max(this.Model.input.maxTokens - PROMPT_INPUT_BUFFER, 100));
+  if (options.length) {
+    options.length = Math.min(this.Model.output.maxTokens - PROMPT_OUTPUT_BUFFER, options.length);
+  }
+  const instructions = [];
+  let chart = "";
+  if (options.length) {
+    const length = clamp(options.length * 0.75, 5, options.length);
+    instructions.push(`IMPORTANT: Length constraint: ${length} tokens/words`);
+    instructions.push(`The text must be standalone and complete in less than ${length} tokens/words`);
+  }
+  if (options.length && options.length <= 500) {
+    chart = `
+| Tokens      | Text Length (approximate)            |
+|-------------|--------------------------------------|
+| < 5 tokens  | 1-3 words                            |
+| 5-10 tokens | 3-6 words                            |
+| 10-20 tokens| 6-15 words                           |
+| 20-50 tokens| A short sentence (15-30 words)       |
+| 50-100 tokens| A medium sentence (30-70 words)     |
+| 100-200 tokens| A short paragraph (70-150 words)   |
+| 200-300 tokens| A medium paragraph (150-200 words) |
+| 300-500 tokens| A long paragraph (200-300 words)   |`.trim();
+  }
+  const output = await this.callModel({
+    systemPrompt: `
+Generate a text that fulfills the user prompt below. Answer directly to the prompt, without any acknowledgements or fluff. Also, make sure the text is standalone and complete.
+${instructions.map((x) => `- ${x}`).join("\n")}
+${chart}
+`.trim(),
+    temperature: 0.7,
+    messages: [{ type: "text", content: prompt, role: "user" }],
+    maxTokens: options.length
+  });
+  return output?.choices?.[0]?.content;
+};

package/dist/utils.js

@@ -0,0 +1,43 @@
+import { z } from "@bpinternal/zui";
+export const stringify = (input, beautify = true) => {
+  return typeof input === "string" && !!input.length ? input : input ? JSON.stringify(input, beautify ? null : void 0, beautify ? 2 : void 0) : "<input is null, false, undefined or empty>";
+};
+export const BotpressClient = z.custom(
+  (value) => typeof value === "object" && value !== null && "callAction" in value && typeof value.callAction === "function",
+  {
+    message: "Invalid Botpress Client. Make sure to pass an instance of @botpress/client"
+  }
+);
+export function fastHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) - hash + str.charCodeAt(i);
+    hash |= 0;
+  }
+  return (hash >>> 0).toString(16);
+}
+export const takeUntilTokens = (arr, tokens, count) => {
+  const result = [];
+  let total = 0;
+  for (const value of arr) {
+    const valueTokens = count(value);
+    if (total + valueTokens > tokens) {
+      break;
+    }
+    total += valueTokens;
+    result.push(value);
+  }
+  return result;
+};
+export const GenerationMetadata = z.object({
+  model: z.string(),
+  cost: z.object({
+    input: z.number(),
+    output: z.number()
+  }).describe("Cost in $USD"),
+  latency: z.number().describe("Latency in milliseconds"),
+  tokens: z.object({
+    input: z.number(),
+    output: z.number()
+  }).describe("Number of tokens used")
+});

package/dist/zai.js

@@ -0,0 +1,140 @@
+import { z } from "@bpinternal/zui";
+import { getWasmTokenizer } from "@botpress/wasm";
+import { TableAdapter } from "./adapters/botpress-table";
+import { MemoryAdapter } from "./adapters/memory";
+import { Models } from "./models";
+import { BotpressClient } from "./utils";
+const ActiveLearning = z.object({
+  enable: z.boolean().describe("Whether to enable active learning").default(false),
+  tableName: z.string().regex(
+    /^[A-Za-z0-9_/-]{1,100}Table$/,
+    "Namespace must be alphanumeric and contain only letters, numbers, underscores, hyphens and slashes"
+  ).describe("The name of the table to store active learning tasks").default("ActiveLearningTable"),
+  taskId: z.string().regex(
+    /^[A-Za-z0-9_/-]{1,100}$/,
+    "Namespace must be alphanumeric and contain only letters, numbers, underscores, hyphens and slashes"
+  ).describe("The ID of the task").default("default")
+});
+const ZaiConfig = z.object({
+  client: BotpressClient,
+  userId: z.string().describe("The ID of the user consuming the API").optional(),
+  retry: z.object({ maxRetries: z.number().min(0).max(100) }).default({ maxRetries: 3 }),
+  modelId: z.custom(
+    (value) => {
+      if (typeof value !== "string" || !value.includes("__")) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: "Invalid model ID"
+    }
+  ).describe("The ID of the model you want to use").default("openai__gpt-4o-mini-2024-07-18"),
+  activeLearning: ActiveLearning.default({ enable: false }),
+  namespace: z.string().regex(
+    /^[A-Za-z0-9_/-]{1,100}$/,
+    "Namespace must be alphanumeric and contain only letters, numbers, underscores, hyphens and slashes"
+  ).default("zai")
+});
+export class Zai {
+  static tokenizer = null;
+  client;
+  originalConfig;
+  userId;
+  integration;
+  model;
+  retry;
+  Model;
+  namespace;
+  adapter;
+  activeLearning;
+  constructor(config) {
+    this.originalConfig = config;
+    const parsed = ZaiConfig.parse(config);
+    this.client = parsed.client;
+    const [integration, modelId] = parsed.modelId.split("__");
+    if (!integration?.length || !modelId?.length) {
+      throw new Error(`Invalid model ID: ${parsed.modelId}. Expected format: <integration>__<modelId>`);
+    }
+    this.integration = integration;
+    this.model = modelId;
+    this.namespace = parsed.namespace;
+    this.userId = parsed.userId;
+    this.retry = parsed.retry;
+    this.Model = Models.find((m) => m.id === parsed.modelId);
+    this.activeLearning = parsed.activeLearning;
+    this.adapter = parsed.activeLearning?.enable ? new TableAdapter({ client: this.client, tableName: parsed.activeLearning.tableName }) : new MemoryAdapter([]);
+  }
+  /** @internal */
+  async callModel(props) {
+    let retries = this.retry.maxRetries;
+    while (retries-- >= 0) {
+      try {
+        return await this._callModel(props);
+      } catch (e) {
+        if (retries >= 0) {
+          await new Promise((resolve) => setTimeout(resolve, 1e3));
+        } else {
+          throw new Error("Failed to call model after multiple retries");
+        }
+      }
+    }
+    throw new Error("Failed to call model after multiple retries");
+  }
+  /** @internal */
+  async _callModel(props) {
+    let retries = this.retry.maxRetries;
+    do {
+      const start = Date.now();
+      const input = {
+        messages: [],
+        temperature: 0,
+        topP: 1,
+        model: { id: this.model },
+        userId: this.userId,
+        ...props
+      };
+      const { output } = await this.client.callAction({
+        type: `${this.integration}:generateContent`,
+        input
+      });
+      const latency = Date.now() - start;
+      return {
+        ...output,
+        metadata: {
+          model: this.model,
+          latency,
+          cost: { input: output.usage.inputCost, output: output.usage.outputCost },
+          tokens: { input: output.usage.inputTokens, output: output.usage.outputTokens }
+        }
+      };
+    } while (--retries > 0);
+  }
+  async getTokenizer() {
+    Zai.tokenizer ??= await (async () => {
+      while (!getWasmTokenizer) {
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+      return getWasmTokenizer();
+    })();
+    return Zai.tokenizer;
+  }
+  get taskId() {
+    if (!this.activeLearning.enable) {
+      return void 0;
+    }
+    return `${this.namespace}/${this.activeLearning.taskId}`.replace(/\/+/g, "/");
+  }
+  with(options) {
+    return new Zai({
+      ...this.originalConfig,
+      ...options
+    });
+  }
+  learn(taskId) {
+    return new Zai({
+      ...this.originalConfig,
+      activeLearning: { ...this.activeLearning, taskId, enable: true }
+    });
+  }
+}

package/package.json

@@ -1,46 +1,48 @@
 {
   "name": "@botpress/zai",
-  "version": "1.0.1",
-  "type": "module",
-  "private": false,
   "description": "Zui AI (zai) – An LLM utility library written on top of Zui and the Botpress API",
+  "version": "1.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
-    }
+    "types": "./dist/index.d.ts",
+    "require": "./dist/index.js",
+    "import": "./dist/index.js"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "npm run build:types && npm run build:neutral",
+    "build:neutral": "esbuild src/**/*.ts src/*.ts --platform=neutral --outdir=dist",
+    "build:types": "tsup",
     "watch": "tsup --watch",
     "test": "vitest run --config vitest.config.ts",
     "test:update": "vitest -u run --config vitest.config.ts",
     "test:watch": "vitest --config vitest.config.ts",
     "build-with-latest-models": "pnpm run update-types && pnpm run update-models && pnpm run build",
-    "update-models": "ts-node ./src/scripts/update-models.ts",
-    "update-types": "ts-node ./src/scripts/update-types.ts"
+    "update-models": "ts-node ./scripts/update-models.mts",
+    "update-types": "ts-node ./scripts/update-types.mts"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "json5": "^2.2.1",
-    "jsonrepair": "^3.2.0"
+    "json5": "^2.2.3",
+    "jsonrepair": "^3.11.2",
+    "lodash-es": "^4.17.21"
   },
   "devDependencies": {
     "@botpress/vai": "0.0.1-beta.7",
-    "@types/lodash": "^4.17.0",
-    "dotenv": "^16.3.1",
+    "@types/lodash-es": "^4.17.12",
+    "dotenv": "^16.4.7",
+    "esbuild": "^0.24.2",
+    "lodash": "^4.17.21",
     "ts-node": "^10.9.2",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.0.5"
+    "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@botpress/client": "^0.36.2",
-    "@botpress/sdk": "^1.6.1",
+    "@botpress/client": "^0.40.0",
     "@botpress/wasm": "^1.0.0",
-    "lodash": "^4.17.21"
+    "@bpinternal/zui": "^0.13.4"
   }
 }

package/src/adapters/adapter.ts

@@ -0,0 +1,35 @@
+import { GenerationMetadata } from '../utils'
+
+export type SaveExampleProps<TInput, TOutput> = {
+  key: string
+  taskType: string
+  taskId: string
+  instructions: string
+  input: TInput
+  output: TOutput
+  explanation?: string
+  metadata: GenerationMetadata
+  status?: 'pending' | 'approved'
+}
+
+export type GetExamplesProps<TInput> = {
+  taskType: string
+  taskId: string
+  input: TInput
+}
+
+export abstract class Adapter {
+  abstract getExamples<TInput, TOutput>(
+    props: GetExamplesProps<TInput>
+  ): Promise<
+    Array<{
+      key: string
+      input: TInput
+      output: TOutput
+      explanation?: string
+      similarity: number
+    }>
+  >
+
+  abstract saveExample<TInput, TOutput>(props: SaveExampleProps<TInput, TOutput>): Promise<void>
+}