Overview of Zai

Zai is an LLM utility library that provides a clean, type-safe API for common AI operations. For example, you can use Zai’s methods to programmatically:

• Extract structured data from an unstructured prompt
• Verify a Boolean condition within a piece of content
• Generate or summarize text

We recommend using Zai with the ADK and SDK to help process LLM inputs and outputs.

For a full list of available methods, check out the reference section.

Zai is imported by default in Execute Code Cards, Actions, and Hooks.

Installation

To install Zai for local development, run the following command in your terminal:

npm

npm install @botpress/zai @botpress/client @bpinternal/zui

pnpm install @botpress/zai @botpress/client @bpinternal/zui

yarn add @botpress/zai @botpress/client @bpinternal/zui

This also installs:

• The official Botpress client, which is necessary to create a Zai instance
• The internal Zui library, which helps create Zod schemas for many of Zai’s methods

Quick start

To get started, import the libraries and create a new Client object using your Bot ID and Personal Access Token (PAT):

import { Client } from '@botpress/client'
import { Zai } from '@botpress/zai'
import { z } from '@bpinternal/zui'

const client = new Client({ botId: 'YOUR_BOT_ID', token: 'YOUR_TOKEN' })

Then, create a new Zai instance and pass in the Client:

const zai = new Zai({ client })

If you’re using Zai within Botpress Studio, you don’t need to create a new Zai instance—it’s already available globally as zai.

Usage examples

Here are some examples of how you can use Zai:

Get structured data from text

Use the extract method to get structured data from a plain piece of text:

const text = "Blueberries are 3.99$ and are in stock."
const product = await zai.extract(
  text,
  z.object({
    name: z.string(), // Returns "blueberries"
    price: z.number(), // Returns 3.99
    inStock: z.boolean(), // Returns true
  })
)

Verify a condition

Use the check method to verify a condition against some input:

const { output } = await zai.check(email, 'is spam').result()
const { value, explanation } = output

Filter an array

Use the filter method to filter elements of an array based on a condition:

const comments = [
  "Great product, I love it!",
  "This is terrible spam content",
  "Very helpful review, thank you"
]
const cleanComments = await zai.filter(comments, 'is not spam or inappropriate')
// Returns: ["Great product, I love it!", "Very helpful review, thank you"]

Label content with categories

Use the label method to categorize content with predefined labels:

const email = "Congratulations! You've won $1,000,000! Click here now!"
const result = await zai.label(email, {
  spam: 'is this email spam?',
  urgent: 'does this email require immediate attention?',
  promotional: 'is this email promotional content?'
})
// Returns: { spam: true, urgent: false, promotional: true }

Rewrite text according to instructions

Use the rewrite method to transform text based on specific instructions:

const original = "The meeting is scheduled for tomorrow at 3pm."
const rewritten = await zai.rewrite(
  original,
  'Make this sound more professional and formal'
)
// Returns: "The meeting has been scheduled for tomorrow at 3:00 PM."

Summarize long content

Use the summarize method to create concise summaries of lengthy text:

const longArticle = "..." // Long article content
const summary = await zai.summarize(longArticle, {
  length: 100, // tokens
  prompt: 'key findings and main conclusions'
})
// Returns: A concise summary focusing on key findings

Generate text from prompts

Use the text method to generate content based on prompts:

const blogPost = await zai.text(
  'Write a brief introduction about the benefits of AI in customer service',
  { length: 200 }
)
// Returns: Generated text about AI benefits in customer service

Sort items based on criteria

Use the sort method to order items using natural language instructions:

const tasks = [
  "Update documentation",
  "Fix critical security bug",
  "Add new feature",
  "System is down - all users affected"
]
const prioritized = await zai.sort(tasks, 'by urgency and impact, most urgent first')
// Returns: ["System is down...", "Fix critical security bug", "Add new feature", "Update documentation"]

Rate items on a scale

Use the rate method to evaluate items on a 1-5 scale:

const reviews = [
  "Amazing product! Best purchase ever!",
  "It's okay, nothing special",
  "Terrible quality, broke immediately"
]
const ratings = await zai.rate(reviews, 'Rate the sentiment')
// Returns: [5, 3, 1]

Group items into categories

Use the group method to categorize items into groups:

const messages = [
  "I can't log in to my account",
  "How do I reset my password?",
  "When will my order arrive?",
  "The app keeps crashing"
]
const groups = await zai.group(messages, {
  instructions: 'Group by type of customer issue'
})
// Returns: { "Login Issues": [...], "Shipping Questions": [...], "Technical Errors": [...] }

Answer questions with citations

Use the answer method to answer questions from documents with source citations:

const documents = [
  'Botpress was founded in 2016.',
  'The company is based in Quebec, Canada.',
  'Botpress provides an AI agent platform.'
]
const result = await zai.answer(documents, 'When was Botpress founded?')
if (result.type === 'answer') {
  console.log(result.answer) // "Botpress was founded in 2016."
  console.log(result.citations) // Array of citations with source references
}

Modify files with natural language

Use the patch method to make surgical code edits across one or many files. Instead of regenerating entire files, it makes precise, minimal changes while preserving formatting and context:

const files = [{
  path: 'src/utils.ts',
  name: 'utils.ts',
  content: 'export function add(a: number, b: number) {\n  return a + b\n}'
}]
const patched = await zai.patch(files, 'add JSDoc comments to all exported functions')
// Returns modified file with JSDoc comments added