@botpress/zai 1.0.0-beta.2 → 1.0.0-beta.4

package/src/operations/rewrite.ts

@@ -1,148 +0,0 @@
-import { z } from '@bpinternal/zui'
-
-import { fastHash, stringify, takeUntilTokens } from '../utils'
-import { Zai } from '../zai'
-import { PROMPT_INPUT_BUFFER } from './constants'
-
-type Example = z.input<typeof Example> & { instructions?: string }
-const Example = z.object({
-  input: z.string(),
-  output: z.string()
-})
-
-export type Options = z.input<typeof Options>
-const Options = z.object({
-  examples: z.array(Example).default([]),
-  length: z.number().min(10).max(16_000).optional().describe('The maximum number of tokens to generate')
-})
-
-declare module '../zai' {
-  interface Zai {
-    /** Rewrites a string according to match the prompt */
-    rewrite(original: string, prompt: string, options?: Options): Promise<string>
-  }
-}
-
-const START = '■START■'
-const END = '■END■'
-
-Zai.prototype.rewrite = async function (this: Zai, 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: string[] = []
-
-  const originalSize = tokenizer.count(original)
-  if (options.length && originalSize > options.length) {
-    instructions.push(`The original text is ${originalSize} tokens long – 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: string, prompt: string) => {
-    return `
-Prompt: ${prompt}
-
-${START}
-${before}
-${END}
-`.trim()
-  }
-
-  const Key = fastHash(
-    stringify({
-      taskId,
-      taskType,
-      input: original,
-      prompt
-    })
-  )
-
-  const formatExample = ({ input, output, instructions }: Example) => {
-    return [
-      { type: 'text' as const, role: 'user' as const, content: format(input, instructions || prompt) },
-      { type: 'text' as const, role: 'assistant' as const, content: `${START}${output}${END}` }
-    ]
-  }
-
-  const defaultExamples: Example[] = [
-    { input: 'Hello, how are you?', output: 'Bonjour, comment ça va?', instructions: 'translate to French' },
-    { input: '1\n2\n3', output: '3\n2\n1', instructions: 'reverse the order' }
-  ]
-
-  const tableExamples = taskId
-    ? await this.adapter.getExamples<string, string>({
-        input: original,
-        taskId,
-        taskType
-      })
-    : []
-
-  const exactMatch = tableExamples.find((x) => x.key === Key)
-  if (exactMatch) {
-    return exactMatch.output
-  }
-
-  const savedExamples: Example[] = [
-    ...tableExamples.map((x) => ({ input: x.input as string, output: x.output as string })),
-    ...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) => `• ${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 as string
-
-  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/src/operations/summarize.test.ts

@@ -1,25 +0,0 @@
-import { check } from '@botpress/vai'
-import { describe, it } from 'vitest'
-
-import { BotpressDocumentation, getZai } from './__tests'
-
-describe('zai.summarize', () => {
-  const zai = getZai()
-
-  it.skip('summarize long document to a concise 2000 token summary', async () => {
-    const result = await zai.summarize(BotpressDocumentation, {
-      length: 2000,
-      prompt: `Extract the Table of Contents for the Botpress Documentation. Pay special attention to all the different features. Focus on horizontal coverage of features rather than going in depth into one feature. The goal is to have a complete overview of what the documentation covers.`
-    })
-
-    check(result, 'The text is a summary of the Botpress documentation').toBe(true)
-    check(result, 'The text explains shortly what botpress is').toBe(true)
-    check(result, 'The text uses markdown format').toBe(true)
-    check(result, 'The text has some information about integrations').toBe(true)
-    check(result, 'The text has a section about Flows (or Workflows)').toBe(true)
-    check(result, 'The text has a section about the Botpress API').toBe(true)
-    check(result, 'The text mentions the notion of workspaces').toBe(true)
-    check(result, 'The text has some information about the Webchat').toBe(true)
-    check(result, 'The text has some information about HITL (human in the loop)').toBe(true)
-  })
-})

package/src/operations/summarize.ts

@@ -1,193 +0,0 @@
-import { z } from '@bpinternal/zui'
-
-import _ from 'lodash'
-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 '../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.test.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect } from 'vitest'
-import { check } from '@botpress/vai'
-
-import { getZai, tokenizer } from './__tests'
-
-describe('zai.text', { timeout: 60_000 }, () => {
-  const zai = getZai()
-
-  it('generate a horror novel with no params', async () => {
-    const story = await zai.text('write a short horror novel')
-    check(story, 'is a short horror story').toBe(true)
-  })
-
-  it('No fluffy text at the beginning', async () => {
-    const story = await zai.text('write a short horror novel')
-
-    check(story, 'There is no LLM fluff at the beginning', {
-      examples: [
-        {
-          value: 'Title: A horror story\nChapter 1: The woods\nOnce upen a time, ...',
-          expected: true,
-          reason: 'It begins straight with a story, no fluff at the beginning'
-        },
-        { value: 'Once upon a time, a ...', expected: true, reason: 'The story starts directly' },
-        {
-          value: 'Sure, I will generate a story.\nOnce upen a time, a...',
-          expected: false,
-          reason: 'There is some fluff at the beginning'
-        }
-      ]
-    }).toBe(true)
-  })
-
-  it('No fluffy text at the end', async () => {
-    const story = await zai.text('write a short horror novel')
-
-    check(story, 'There is no LLM fluff at the end', {
-      examples: [
-        {
-          value: 'Title: A horror story\nChapter 1: The woods\nOnce upen a time, ... The End.',
-          expected: true,
-          reason: 'The end is clear and direct, no fluff at the end'
-        },
-        {
-          value:
-            'Sure, I will generate a story.\nOnce upen a time, a... The End.\nLet me know if you want more or if you are happy with this.',
-          expected: false,
-          reason: 'There is some fluff from the assistant at the end.'
-        }
-      ]
-    }).toBe(true)
-  })
-
-  it('length/max tokens param', async () => {
-    const story = await zai.text('write a short but complete horror story (with conclusion)', { length: 100 })
-    expect(tokenizer.count(story)).toBeLessThanOrEqual(110)
-
-    check(story, 'could be the beginning of a horror story').toBe(true)
-  })
-})

package/src/operations/text.ts

@@ -1,63 +0,0 @@
-import { z } from '@bpinternal/zui'
-
-import _ from 'lodash'
-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 '../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/operations/zai-learn.test.ts

@@ -1,85 +0,0 @@
-import { describe, it, expect, afterAll, beforeEach, afterEach, vi } from 'vitest'
-
-import { getClient, getZai } from './__tests'
-
-import { check } from '@botpress/vai'
-import { Client } from '@botpress/client'
-
-describe('zai.learn / generic', { timeout: 60_000 }, () => {
-  const client = getClient()
-  let tableName = 'ZaiTestInternalTable'
-  let taskId = 'test'
-  let zai = getZai()
-
-  beforeEach(async () => {
-    zai = getZai().with({
-      activeLearning: {
-        enable: true,
-        taskId,
-        tableName
-      }
-    })
-  })
-
-  afterEach(async () => {
-    try {
-      await client.deleteTableRows({ table: tableName, deleteAllRows: true })
-    } catch (err) {}
-  })
-
-  afterAll(async () => {
-    try {
-      await client.deleteTable({ table: tableName })
-    } catch (err) {}
-  })
-
-  it('saves examples to tables', async () => {
-    const value = await zai
-      .learn(taskId)
-      .check('This text is very clearly written in English.', 'is an english sentence')
-
-    const { rows } = await client.findTableRows({ table: tableName })
-
-    expect(value).toBe(true)
-    expect(rows.length).toBe(1)
-
-    check(rows[0].explanation, 'is an explanation sentence')
-    expect(rows[0].explanation).not.toContain('Final Answer:')
-    expect(rows[0].output).toMatchObject({ value: true })
-    expect(rows[0].input).toMatchInlineSnapshot(`
-      {
-        "value": "This text is very clearly written in English.",
-      }
-    `)
-    expect(rows[0].taskId).toEqual('zai/test')
-    expect(rows[0].taskType).toBe('zai.check')
-  })
-
-  it('works even if tables are down', async () => {
-    const upsertTableRows = vi.fn(async () => {
-      throw new Error('Table is down')
-    })
-
-    const findTableRows = vi.fn(async () => {
-      throw new Error('Table is down')
-    })
-
-    const client = {
-      ...getClient(),
-      findTableRows,
-      upsertTableRows
-    } as unknown as Client
-
-    const value = await zai
-      .with({ client })
-      .learn(taskId)
-      .check('This text is very clearly written in English.', 'is an english sentence')
-
-    const { rows } = await getClient().findTableRows({ table: tableName })
-
-    expect(value).toBe(true)
-    expect(rows.length).toBe(0)
-    expect(upsertTableRows).toHaveBeenCalledTimes(1)
-    expect(findTableRows).toHaveBeenCalledTimes(1)
-  })
-})

package/src/operations/zai-retry.test.ts

@@ -1,64 +0,0 @@
-import { describe, it, expect, vi } from 'vitest'
-
-import { getClient, getZai } from './__tests'
-
-import { Client } from '@botpress/client'
-
-describe('zai retry', { timeout: 60_000 }, () => {
-  const client = getClient()
-  let zai = getZai().with({ retry: { maxRetries: 3 } })
-
-  it('retries 3 times and succeeds', async () => {
-    let retryCount = 0
-    const throwingClient = {
-      ...client,
-      callAction: vi.fn((input) => {
-        if (++retryCount < 3) {
-          throw new Error('Failed to call model')
-        }
-        return client.callAction(input)
-      })
-    } as unknown as Client
-
-    const value = await zai
-      .with({ client: throwingClient })
-      .check('This text is very clearly written in English.', 'is an english sentence')
-
-    expect(value).toBe(true)
-    expect(retryCount).toBe(3)
-  })
-
-  it('retries 0 times when success', async () => {
-    const fn = vi.fn((input) => client.callAction(input))
-
-    const throwingClient = {
-      ...client,
-      callAction: fn
-    } as unknown as Client
-
-    const value = await zai
-      .with({ client: throwingClient })
-      .check('This text is very clearly written in English.', 'is an english sentence')
-
-    expect(value).toBe(true)
-    expect(fn).toHaveBeenCalledOnce()
-  })
-
-  it('fails when exceeded max', async () => {
-    const fn = vi.fn(() => {
-      throw new Error('Failed to call model')
-    })
-
-    const throwingClient = {
-      ...client,
-      callAction: fn
-    } as unknown as Client
-
-    const value = zai
-      .with({ client: throwingClient, retry: { maxRetries: 1 } })
-      .check('This text is very clearly written in English.', 'is an english sentence')
-
-    await expect(value).rejects.toThrowError(/retries/)
-    expect(fn).toHaveBeenCalledTimes(2)
-  })
-})