@botpress/zai 1.0.1 → 1.1.0

package/src/operations/summarize.ts

@@ -0,0 +1,193 @@
+import { z } from '@bpinternal/zui'
+
+import { chunk } from 'lodash-es'
+import { Zai } from '../zai'
+import { PROMPT_INPUT_BUFFER, PROMPT_OUTPUT_BUFFER } from './constants'
+
+export type Options = z.input<typeof Options>
+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(100_000).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(100_000),
+      overlap: z.number().min(0).max(100_000)
+    })
+    .describe('Sliding window options')
+    .default({ window: 50_000, overlap: 250 })
+})
+
+declare module '@botpress/zai' {
+  interface Zai {
+    /** Summarizes a text of any length to a summary of the desired length */
+    summarize(original: string, options?: Options): Promise<string>
+  }
+}
+
+const START = '■START■'
+const END = '■END■'
+
+Zai.prototype.summarize = async function (this: Zai, 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})`
+    )
+  }
+
+  // Ensure the sliding window is not bigger than the model input size
+  options.sliding.window = Math.min(options.sliding.window, this.Model.input.maxTokens - PROMPT_INPUT_BUFFER)
+
+  // Ensure the overlap is not bigger than the window
+  // Most extreme case possible (all 3 same size)
+  // |ooooooooooooooooooo|wwwwwwwwwwwwwww|ooooooooooooooooooo|
+  // |<---- overlap ---->|<--  window -->|<---- overlap ---->|
+  options.sliding.overlap = Math.min(options.sliding.overlap, options.sliding.window - 3 * options.sliding.overlap)
+
+  const format = (summary: string, newText: string) => {
+    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
+
+  // We split it recursively into smaller parts until we're at less than 4 window slides per part
+  // Then we use a merge strategy to combine the sub-chunks summaries
+  // This is basically a merge sort algorithm (but summary instead of sorting)
+  const N = 2 // This is the merge sort exponent
+  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((chunk) => this.summarize(chunk, options)))
+    return this.summarize(allSummaries.join('\n\n============\n\n'), options)
+  }
+
+  const summaries: string[] = []
+  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: string[] = [
+      `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 as string
+
+    if (result.includes(START)) {
+      result = result.slice(result.indexOf(START) + START.length)
+    }
+
+    if (result.includes('■')) {
+      // can happen if the model truncates the text before the entire END tag is written
+      result = result.slice(0, result.indexOf('■'))
+    }
+
+    summaries.push(result)
+    currentSummary = result
+  }
+
+  return currentSummary.trim()
+}

package/src/operations/text.ts

@@ -0,0 +1,63 @@
+import { z } from '@bpinternal/zui'
+
+import { clamp } from 'lodash-es'
+import { Zai } from '../zai'
+import { PROMPT_INPUT_BUFFER, PROMPT_OUTPUT_BUFFER } from './constants'
+
+export type Options = z.input<typeof Options>
+const Options = z.object({
+  length: z.number().min(1).max(100_000).optional().describe('The maximum number of tokens to generate')
+})
+
+declare module '@botpress/zai' {
+  interface Zai {
+    /** Generates a text of the desired length according to the prompt */
+    text(prompt: string, options?: Options): Promise<string>
+  }
+}
+
+Zai.prototype.text = async function (this: Zai, 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: string[] = []
+  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! as string
+}

package/src/sdk-interfaces/llm/generateContent.ts

@@ -0,0 +1,127 @@
+
+// This file is generated. Do not edit it manually.
+// See 'scripts/update-models.ts'
+
+/* eslint-disable */
+/* tslint:disable */
+
+export namespace llm {
+    export namespace generateContent {
+      export type Input = { 
+/** Model to use for content generation */
+model?: { id: string }
+; 
+/** Optional system prompt to guide the model */
+systemPrompt?: string
+; 
+/** Array of messages for the model to process */
+messages: Array<{ role: 'user' | 'assistant'; type?: 'text' | 'tool_calls' | 'tool_result' | 'multipart'; 
+/** Required if `type` is "tool_calls" */
+toolCalls?: Array<{ id: string; type: 'function'; function: { name: string; 
+/** Some LLMs may generate invalid JSON for a tool call, so this will be `null` when it happens. */
+arguments: 
+ { [key: string]: any } | null
+ } }>
+; 
+/** Required if `type` is "tool_result" */
+toolResultCallId?: string
+; 
+/** Required unless `type` is "tool_call". If `type` is "multipart", this field must be an array of content objects. If `type` is "tool_result" then this field should be the result of the tool call (a plain string or a JSON-encoded array or object). If `type` is "tool_call" then the `toolCalls` field should be used instead. */
+content: 
+
+string | Array<{ type: 'text' | 'image'; 
+/** Indicates the MIME type of the content. If not provided it will be detected from the content-type header of the provided URL. */
+mimeType?: string
+; 
+/** Required if part type is "text" */
+text?: string
+; 
+/** Required if part type is "image" */
+url?: string
+ }> | null
+ }>
+; 
+/** Response format expected from the model. If "json_object" is chosen, you must instruct the model to generate JSON either via the system prompt or a user message. */
+responseFormat?: 'text' | 'json_object'
+; 
+/** Maximum number of tokens allowed in the generated response */
+maxTokens?: number
+; 
+/** Sampling temperature for the model. Higher values result in more random outputs. */
+temperature?: /** Sampling temperature for the model. Higher values result in more random outputs. */ number
+; 
+/** Top-p sampling parameter. Limits sampling to the smallest set of tokens with a cumulative probability above the threshold. */
+topP?: /** Top-p sampling parameter. Limits sampling to the smallest set of tokens with a cumulative probability above the threshold. */ number
+; 
+/** Sequences where the model should stop generating further tokens. */
+stopSequences?: string[]
+; tools?: Array<{ type: 'function'; function: { 
+/** Function name */
+name: string
+; description?: string; 
+/** JSON schema of the function arguments */
+argumentsSchema?: { }
+ } }>; toolChoice?: { type?: 'auto' | 'specific' | 'any' | 'none' | ''; 
+/** Required if `type` is "specific" */
+functionName?: string
+ }; userId?: string; 
+/** Set to `true` to output debug information to the bot logs */
+debug?: boolean
+; meta?: { 
+/** Source of the prompt, e.g. agent/:id/:version cards/ai-generate, cards/ai-task, nodes/autonomous, etc. */
+promptSource?: string
+; promptCategory?: string; 
+/** Name of the integration that originally received the message that initiated this action */
+integrationName?: string
+ } };;
+      export type Output = { 
+/** Response ID from LLM provider */
+id: string
+; 
+/** LLM provider name */
+provider: string
+; 
+/** Model name */
+model: string
+; choices: Array<{ type?: 'text' | 'tool_calls' | 'tool_result' | 'multipart'; 
+/** Required if `type` is "tool_calls" */
+toolCalls?: Array<{ id: string; type: 'function'; function: { name: string; 
+/** Some LLMs may generate invalid JSON for a tool call, so this will be `null` when it happens. */
+arguments: 
+ { [key: string]: any } | null
+ } }>
+; 
+/** Required if `type` is "tool_result" */
+toolResultCallId?: string
+; 
+/** Required unless `type` is "tool_call". If `type` is "multipart", this field must be an array of content objects. If `type` is "tool_result" then this field should be the result of the tool call (a plain string or a JSON-encoded array or object). If `type` is "tool_call" then the `toolCalls` field should be used instead. */
+content: 
+
+string | Array<{ type: 'text' | 'image'; 
+/** Indicates the MIME type of the content. If not provided it will be detected from the content-type header of the provided URL. */
+mimeType?: string
+; 
+/** Required if part type is "text" */
+text?: string
+; 
+/** Required if part type is "image" */
+url?: string
+ }> | null
+; role: 'assistant'; index: number; stopReason: 'stop' | 'max_tokens' | 'tool_calls' | 'content_filter' | 'other' }>; usage: { 
+/** Number of input tokens used by the model */
+inputTokens: number
+; 
+/** Cost of the input tokens received by the model, in U.S. dollars */
+inputCost: number
+; 
+/** Number of output tokens used by the model */
+outputTokens: number
+; 
+/** Cost of the output tokens generated by the model, in U.S. dollars */
+outputCost: number
+ }; botpress: { 
+/** Total cost of the content generation, in U.S. dollars */
+cost: number
+ } };;
+    }
+}

package/src/sdk-interfaces/llm/listLanguageModels.ts

@@ -0,0 +1,19 @@
+
+// This file is generated. Do not edit it manually.
+// See 'scripts/update-models.ts'
+
+/* eslint-disable */
+/* tslint:disable */
+
+export namespace llm {
+    export namespace listLanguageModels {
+      export type Input = { };;
+      export type Output = { models: Array<{ id: string; name: string; description: string; tags: Array<'recommended' | 'deprecated' | 'general-purpose' | 'low-cost' | 'vision' | 'coding' | 'agents' | 'function-calling' | 'roleplay' | 'storytelling' | 'reasoning'>; input: { maxTokens: number; 
+/** Cost per 1 million tokens, in U.S. dollars */
+costPer1MTokens: number
+ }; output: { maxTokens: number; 
+/** Cost per 1 million tokens, in U.S. dollars */
+costPer1MTokens: number
+ } } & { id: string }> };;
+    }
+}

package/src/utils.ts

@@ -0,0 +1,61 @@
+import type { Client } from '@botpress/client'
+import { z } from '@bpinternal/zui'
+
+export const stringify = (input: unknown, beautify = true) => {
+  return typeof input === 'string' && !!input.length
+    ? input
+    : input
+    ? JSON.stringify(input, beautify ? null : undefined, beautify ? 2 : undefined)
+    : '<input is null, false, undefined or empty>'
+}
+
+export const BotpressClient = z.custom<Client | any>(
+  (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: string): string {
+  let hash = 0
+  for (let i = 0; i < str.length; i++) {
+    hash = (hash << 5) - hash + str.charCodeAt(i)
+    hash |= 0 // Convert to 32bit integer
+  }
+  return (hash >>> 0).toString(16) // Convert to unsigned and then to hex
+}
+
+export const takeUntilTokens = <T>(arr: T[], tokens: number, count: (el: T) => number) => {
+  const result: T[] = []
+  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 type GenerationMetadata = z.input<typeof GenerationMetadata>
+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/src/zai.ts

@@ -0,0 +1,193 @@
+import { Client } from '@botpress/client'
+import { z } from '@bpinternal/zui'
+import { type TextTokenizer, getWasmTokenizer } from '@botpress/wasm'
+
+import { Adapter } from './adapters/adapter'
+import { TableAdapter } from './adapters/botpress-table'
+import { MemoryAdapter } from './adapters/memory'
+import { Models } from './models'
+import { llm } from './sdk-interfaces/llm/generateContent'
+
+import { BotpressClient, GenerationMetadata } from './utils'
+
+type ModelId = (typeof Models)[number]['id']
+
+type ActiveLearning = z.input<typeof ActiveLearning>
+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')
+})
+
+type ZaiConfig = z.input<typeof ZaiConfig>
+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<ModelId | string>(
+      (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' satisfies ModelId),
+  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 {
+  protected static tokenizer: TextTokenizer = null!
+  protected client: Client
+
+  private originalConfig: ZaiConfig
+
+  private userId: string | undefined
+  private integration: string
+  private model: string
+  private retry: { maxRetries: number }
+
+  protected Model: (typeof Models)[number]
+  protected namespace: string
+  protected adapter: Adapter
+  protected activeLearning: ActiveLearning
+
+  constructor(config: ZaiConfig) {
+    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 as { maxRetries: number }
+    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 */
+  protected async callModel(
+    props: Partial<llm.generateContent.Input>
+  ): Promise<llm.generateContent.Output & { metadata: GenerationMetadata }> {
+    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, 1000))
+        } else {
+          throw new Error('Failed to call model after multiple retries')
+        }
+      }
+    }
+
+    throw new Error('Failed to call model after multiple retries')
+  }
+
+  /** @internal */
+  private async _callModel(
+    props: Partial<llm.generateContent.Input>
+  ): Promise<llm.generateContent.Output & { metadata: GenerationMetadata }> {
+    let retries = this.retry.maxRetries
+    do {
+      const start = Date.now()
+      const input: llm.generateContent.Input = {
+        messages: [],
+        temperature: 0.0,
+        topP: 1,
+        model: { id: this.model },
+        userId: this.userId,
+        ...props
+      }
+
+      const { output } = (await this.client.callAction({
+        type: `${this.integration}:generateContent`,
+        input
+      })) as unknown as { output: llm.generateContent.Output }
+
+      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)
+  }
+
+  protected async getTokenizer() {
+    Zai.tokenizer ??= await (async () => {
+      while (!getWasmTokenizer) {
+        // there's an issue with wasm, it doesn't load immediately
+        await new Promise((resolve) => setTimeout(resolve, 25))
+      }
+      return getWasmTokenizer()
+    })()
+    return Zai.tokenizer
+  }
+
+  protected get taskId() {
+    if (!this.activeLearning.enable) {
+      return undefined
+    }
+
+    return `${this.namespace}/${this.activeLearning.taskId}`.replace(/\/+/g, '/')
+  }
+
+  public with(options: Partial<ZaiConfig>): Zai {
+    return new Zai({
+      ...this.originalConfig,
+      ...options
+    })
+  }
+
+  public learn(taskId: string) {
+    return new Zai({
+      ...this.originalConfig,
+      activeLearning: { ...this.activeLearning, taskId, enable: true }
+    })
+  }
+}

package/tsconfig.json

@@ -3,6 +3,7 @@
     "target": "ESNext",
     "module": "ESNext",
     "moduleResolution": "bundler",
+    "outDir": "dist",
     "allowJs": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
@@ -16,7 +17,7 @@
     "noUnusedParameters": true,
     "noUncheckedIndexedAccess": true,
     "lib": ["dom", "ESNext", "dom.iterable"],
-    "declaration": false,
+    "declaration": true,
     "noEmit": false,
     "paths": {
       "@botpress/zai": ["./src/zai.ts"]
@@ -24,7 +25,6 @@
   },
   "exclude": ["node_modules", "dist"],
   "include": ["src/**/*", "vitest.d.ts"],
-
   "ts-node": {
     "esm": true,
     "require": ["dotenv/config", "./ensure-env.cjs"]