@botpress/zai 1.0.1 → 1.2.0

package/src/operations/label.ts

@@ -0,0 +1,345 @@
+// eslint-disable consistent-type-definitions
+import { z } from '@bpinternal/zui'
+
+import { clamp, chunk } from 'lodash-es'
+import { fastHash, stringify, takeUntilTokens } from '../utils'
+import { Zai } from '../zai'
+import { PROMPT_INPUT_BUFFER } from './constants'
+
+type Label = keyof typeof LABELS
+const LABELS = {
+  ABSOLUTELY_NOT: 'ABSOLUTELY_NOT',
+  PROBABLY_NOT: 'PROBABLY_NOT',
+  AMBIGUOUS: 'AMBIGUOUS',
+  PROBABLY_YES: 'PROBABLY_YES',
+  ABSOLUTELY_YES: 'ABSOLUTELY_YES',
+} as const
+const ALL_LABELS = Object.values(LABELS).join(' | ')
+
+type Example<T extends string> = {
+  input: unknown
+  labels: Partial<Record<T, { label: Label; explanation?: string }>>
+}
+
+export type Options<T extends string> = Omit<z.input<typeof Options>, 'examples'> & {
+  examples?: Array<Partial<Example<T>>>
+}
+
+const Options = z.object({
+  examples: z
+    .array(
+      z.object({
+        input: z.any(),
+        labels: z.record(z.object({ label: z.enum(ALL_LABELS as never), explanation: z.string().optional() })),
+      })
+    )
+    .default([])
+    .describe('Examples to help the user make a decision'),
+  instructions: z.string().optional().describe('Instructions to guide the user on how to extract the data'),
+  chunkLength: z
+    .number()
+    .min(100)
+    .max(100_000)
+    .optional()
+    .describe('The maximum number of tokens per chunk')
+    .default(16_000),
+})
+
+type Labels<T extends string> = Record<T, string>
+
+const Labels = z.record(z.string().min(1).max(250), z.string()).superRefine((labels, ctx) => {
+  const keys = Object.keys(labels)
+
+  for (const key of keys) {
+    if (key.length < 1 || key.length > 250) {
+      ctx.addIssue({ message: `The label key "${key}" must be between 1 and 250 characters long`, code: 'custom' })
+    }
+
+    if (keys.lastIndexOf(key) !== keys.indexOf(key)) {
+      ctx.addIssue({ message: `Duplicate label: ${labels[key]}`, code: 'custom' })
+    }
+
+    if (/[^a-zA-Z0-9_]/.test(key)) {
+      ctx.addIssue({
+        message: `The label key "${key}" must only contain alphanumeric characters and underscores`,
+        code: 'custom',
+      })
+    }
+  }
+
+  return true
+})
+
+declare module '@botpress/zai' {
+  interface Zai {
+    /** Tags the provided input with a list of predefined labels */
+    label<T extends string>(
+      input: unknown,
+      labels: Labels<T>,
+      options?: Options<T>
+    ): Promise<{
+      [K in T]: boolean
+    }>
+  }
+}
+
+const parseLabel = (label: string): Label => {
+  label = label.toUpperCase().replace(/\s+/g, '_').replace(/_{2,}/g, '_').trim()
+  if (label.includes('ABSOLUTELY') && label.includes('NOT')) {
+    return LABELS.ABSOLUTELY_NOT
+  } else if (label.includes('NOT')) {
+    return LABELS.PROBABLY_NOT
+  } else if (label.includes('AMBIGUOUS')) {
+    return LABELS.AMBIGUOUS
+  }
+  if (label.includes('YES')) {
+    return LABELS.PROBABLY_YES
+  } else if (label.includes('ABSOLUTELY') && label.includes('YES')) {
+    return LABELS.ABSOLUTELY_YES
+  }
+  return LABELS.AMBIGUOUS
+}
+
+Zai.prototype.label = async function <T extends string>(this: Zai, input, _labels, _options) {
+  const options = Options.parse(_options ?? {})
+  const labels = Labels.parse(_labels)
+  const tokenizer = await this.getTokenizer()
+  await this.fetchModelDetails()
+
+  const taskId = this.taskId
+  const taskType = 'zai.label'
+
+  const TOTAL_MAX_TOKENS = clamp(options.chunkLength, 1000, this.ModelDetails.input.maxTokens - PROMPT_INPUT_BUFFER)
+  const CHUNK_EXAMPLES_MAX_TOKENS = clamp(Math.floor(TOTAL_MAX_TOKENS * 0.5), 250, 10_000)
+  const CHUNK_INPUT_MAX_TOKENS = clamp(
+    TOTAL_MAX_TOKENS - CHUNK_EXAMPLES_MAX_TOKENS,
+    TOTAL_MAX_TOKENS * 0.5,
+    TOTAL_MAX_TOKENS
+  )
+
+  const inputAsString = stringify(input)
+
+  if (tokenizer.count(inputAsString) > CHUNK_INPUT_MAX_TOKENS) {
+    const tokens = tokenizer.split(inputAsString)
+    const chunks = chunk(tokens, CHUNK_INPUT_MAX_TOKENS).map((x) => x.join(''))
+    const allLabels = await Promise.all(chunks.map((chunk) => this.label(chunk, _labels)))
+
+    // Merge all the labels together (those who are true will remain true)
+    return allLabels.reduce((acc, x) => {
+      Object.keys(x).forEach((key) => {
+        if (acc[key] === true) {
+          acc[key] = true
+        } else {
+          acc[key] = acc[key] || x[key]
+        }
+      })
+      return acc
+    }, {}) as {
+      [K in T]: boolean
+    }
+  }
+
+  const END = '■END■'
+
+  const Key = fastHash(
+    JSON.stringify({
+      taskType,
+      taskId,
+      input: inputAsString,
+      instructions: options.instructions ?? '',
+    })
+  )
+
+  const convertToAnswer = (mapping: { [K in T]: { explanation: string; label: Label } }) => {
+    return Object.keys(labels).reduce((acc, key) => {
+      acc[key] = mapping[key]?.label === 'ABSOLUTELY_YES' || mapping[key]?.label === 'PROBABLY_YES'
+      return acc
+    }, {}) as { [K in T]: boolean }
+  }
+
+  const examples = taskId
+    ? await this.adapter.getExamples<
+        string,
+        {
+          [K in T]: {
+            explanation: string
+            label: Label
+          }
+        }
+      >({
+        input: inputAsString,
+        taskType,
+        taskId,
+      })
+    : []
+
+  options.examples.forEach((example) => {
+    examples.push({
+      key: fastHash(JSON.stringify(example)),
+      input: example.input,
+      similarity: 1,
+      explanation: '',
+      output: example.labels as unknown as {
+        [K in T]: {
+          explanation: string
+          label: Label
+        }
+      },
+    })
+  })
+
+  const exactMatch = examples.find((x) => x.key === Key)
+  if (exactMatch) {
+    return convertToAnswer(exactMatch.output)
+  }
+
+  const allExamples = takeUntilTokens(
+    examples,
+    CHUNK_EXAMPLES_MAX_TOKENS,
+    (el) =>
+      tokenizer.count(stringify(el.input)) +
+      tokenizer.count(stringify(el.output)) +
+      tokenizer.count(el.explanation ?? '') +
+      100
+  )
+    .map((example, idx) => [
+      {
+        type: 'text' as const,
+        role: 'user' as const,
+        content: `
+Expert Example #${idx + 1}
+
+<|start_input|>
+${stringify(example.input)}
+<|end_input|>`.trim(),
+      },
+      {
+        type: 'text' as const,
+        role: 'assistant' as const,
+        content: `
+Expert Example #${idx + 1}
+============
+${Object.keys(example.output)
+  .map((key) =>
+    `
+■${key}:【${example.output[key]?.explanation}】:${example.output[key]?.label}■
+`.trim()
+  )
+  .join('\n')}
+${END}
+`.trim(),
+      },
+    ])
+    .flat()
+
+  const format = Object.keys(labels)
+    .map((key) => {
+      return `
+■${key}:【explanation (where "explanation" is answering the question "${labels[key]}")】:x■ (where x is ${ALL_LABELS})
+`.trim()
+    })
+    .join('\n\n')
+
+  const { output, meta } = await this.callModel({
+    stopSequences: [END],
+    systemPrompt: `
+You need to tag the input with the following labels based on the question asked:
+${LABELS.ABSOLUTELY_NOT}: You are absolutely sure that the answer is "NO" to the question.
+${LABELS.PROBABLY_NOT}: You are leaning towards "NO" to the question.
+${LABELS.AMBIGUOUS}: You are unsure about the answer to the question.
+${LABELS.PROBABLY_YES}: You are leaning towards "YES" to the question.
+${LABELS.ABSOLUTELY_YES}: You are absolutely sure that the answer is "YES" to the question.
+
+You need to return a mapping of the labels, an explanation and the answer for each label following the format below:
+\`\`\`
+${format}
+${END}
+\`\`\`
+
+${options.instructions}
+
+===
+You should consider the Expert Examples below to help you make your decision.
+In your "Analysis", please refer to the Expert Examples # to justify your decision.
+`.trim(),
+    messages: [
+      ...allExamples,
+      {
+        type: 'text',
+        role: 'user',
+        content: `
+Input to tag:
+<|start_input|>
+${inputAsString}
+<|end_input|>
+
+Answer with this following format:
+\`\`\`
+${format}
+${END}
+\`\`\`
+
+Format cheatsheet:
+\`\`\`
+■label:【explanation】:x■
+\`\`\`
+
+Where \`x\` is one of the following: ${ALL_LABELS}
+
+Remember: In your \`explanation\`, please refer to the Expert Examples # (and quote them) that are relevant to ground your decision-making process.
+The Expert Examples are there to help you make your decision. They have been provided by experts in the field and their answers (and reasoning) are considered the ground truth and should be used as a reference to make your decision when applicable.
+For example, you can say: "According to Expert Example #1, ..."`.trim(),
+      },
+    ],
+  })
+
+  const answer = output.choices[0].content as string
+
+  const final = Object.keys(labels).reduce((acc, key) => {
+    const match = answer.match(new RegExp(`■${key}:【(.+)】:(\\w{2,})■`, 'i'))
+    if (match) {
+      const explanation = match[1].trim()
+      const label = parseLabel(match[2])
+      acc[key] = {
+        explanation,
+        label,
+      }
+    } else {
+      acc[key] = {
+        explanation: '',
+        label: LABELS.AMBIGUOUS,
+      }
+    }
+    return acc
+  }, {}) as {
+    [K in T]: {
+      explanation: string
+      label: Label
+    }
+  }
+
+  if (taskId) {
+    await this.adapter.saveExample({
+      key: Key,
+      taskType,
+      taskId,
+      instructions: options.instructions ?? '',
+      metadata: {
+        cost: {
+          input: meta.cost.input,
+          output: meta.cost.output,
+        },
+        latency: meta.latency,
+        model: this.Model,
+        tokens: {
+          input: meta.tokens.input,
+          output: meta.tokens.output,
+        },
+      },
+      input: inputAsString,
+      output: final,
+    })
+  }
+
+  return convertToAnswer(final)
+}

package/src/operations/rewrite.ts

@@ -0,0 +1,161 @@
+// eslint-disable consistent-type-definitions
+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 '@botpress/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()
+  await this.fetchModelDetails()
+
+  const taskId = this.taskId
+  const taskType = 'zai.rewrite'
+
+  const INPUT_COMPONENT_SIZE = Math.max(100, (this.ModelDetails.input.maxTokens - PROMPT_INPUT_BUFFER) / 2)
+  prompt = tokenizer.truncate(prompt, INPUT_COMPONENT_SIZE)
+
+  const inputSize = tokenizer.count(original) + tokenizer.count(prompt)
+  const maxInputSize = this.ModelDetails.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.ModelDetails.name} = ${this.ModelDetails.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.ModelDetails.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, meta } = 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: {
+        cost: {
+          input: meta.cost.input,
+          output: meta.cost.output,
+        },
+        latency: meta.latency,
+        model: this.Model,
+        tokens: {
+          input: meta.tokens.input,
+          output: meta.tokens.output,
+        },
+      },
+      instructions: prompt,
+      input: original,
+      output: result,
+      taskType,
+      taskId,
+    })
+  }
+
+  return result
+}

package/src/operations/summarize.ts

@@ -0,0 +1,195 @@
+// eslint-disable consistent-type-definitions
+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()
+  await this.fetchModelDetails()
+
+  const INPUT_COMPONENT_SIZE = Math.max(100, (this.ModelDetails.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.ModelDetails.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.ModelDetails.output.maxTokens} tokens for this model (${this.ModelDetails.name})`
+    )
+  }
+
+  // Ensure the sliding window is not bigger than the model input size
+  options.sliding.window = Math.min(options.sliding.window, this.ModelDetails.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()
+}