> ## Documentation Index
> Fetch the complete documentation index at: https://botpress-ak-docs-20-document-updating-variables-from-outsid.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/adk/introduction) and [SDK](/integrations/sdk/overview) to help process LLM inputs and outputs.

<Note>
  For a full list of available methods, check out the [reference section](/adk/zai/reference).
</Note>

<Tip>
  Zai is imported by default in [Execute Code Cards](/studio/guides/advanced/use-code#execute-code-cards), [Actions](/studio/guides/advanced/use-code#actions), and [Hooks](studio/guides/advanced/use-code#hooks).
</Tip>

## Installation

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @botpress/zai @botpress/client @bpinternal/zui
  ```

  ```bash pnpm theme={null}
  pnpm install @botpress/zai @botpress/client @bpinternal/zui
  ```

  ```bash yarn theme={null}
  yarn add @botpress/zai @botpress/client @bpinternal/zui
  ```
</CodeGroup>

This also installs:

* The [official Botpress client](https://www.npmjs.com/package/@botpress/client), which is necessary to create a Zai instance
* The [internal Zui library](https://www.npmjs.com/package/@bpinternal/zui), 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):

```ts theme={null}
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`:

```ts theme={null}
const zai = new Zai({ client })
```

<Note>
  If you're using Zai [within Botpress Studio](/studio/guides/advanced/use-code), you don't need to create a new `Zai` instance—it's already available globally as `zai`.
</Note>

## Usage examples

Here are some examples of how you can use Zai:

### Get structured data from text

Use the [`extract`](/adk/zai/reference#extract) method to get structured data from a plain piece of text:

```ts theme={null}
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`](/adk/zai/reference#check) method to verify a condition against some input:

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

### Filter an array

Use the [`filter`](/adk/zai/reference#filter) method to filter elements of an array based on a condition:

```ts theme={null}
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`](/adk/zai/reference#label) method to categorize content with predefined labels:

```ts theme={null}
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`](/adk/zai/reference#rewrite) method to transform text based on specific instructions:

```ts theme={null}
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`](/adk/zai/reference#summarize) method to create concise summaries of lengthy text:

```ts theme={null}
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`](/adk/zai/reference#text) method to generate content based on prompts:

```ts theme={null}
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`](/adk/zai/reference#sort) method to order items using natural language instructions:

```ts theme={null}
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`](/adk/zai/reference#rate) method to evaluate items on a 1-5 scale:

```ts theme={null}
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`](/adk/zai/reference#group) method to categorize items into groups:

```ts theme={null}
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`](/adk/zai/reference#answer) method to answer questions from documents with source citations:

```ts theme={null}
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`](/adk/zai/reference#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:

```ts theme={null}
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
```