Skip to main content
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 Botpress 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 install @botpress/zai @botpress/client @bpinternal/zui
This also installs:

​
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 result = await zai.check(email, 'is spam')
const { value, explanation } = await result.result()

​
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