Zai class
The package exports one class: Zai. This class gives you access to the library’s methods.
To create a new Zai instance using your Botpress client:
ZaiConfig
required
Methods
Here’s a reference for all methods available with theZai object.
All of the methods below return a
Response object. If you just await the method’s result, it will return simplest form of the result. However, the Response object also has its own methods for accessing the result, event handling, and request control.check()
Checks whether a condition is true or false for the given input.
unknown
required
The input data to check the condition against.
string
required
The condition to check against the input.
CheckOptions
Response<CheckResult, boolean>
extract()
Extracts one or many elements from an arbitrary input using a schema.
unknown
required
The input data to extract elements from.
ZodSchema
required
The Zod schema defining the structure of the data to extract.
ExtractOptions
Response<T>
The extracted data matching the provided schema.
filter()
Filters elements of an array against a condition.
array
required
The array of elements to filter.
string
required
The condition to filter elements against.
FilterOptions
Response<array>
The filtered array containing only elements that match the condition.
label()
Tags the provided input with a list of predefined labels.
unknown
required
The input data to label.
Record<string, string>
required
A mapping of label keys to their descriptions/questions.
LabelOptions
Response<LabelResults, BooleanLabels>
rewrite()
Rewrites a string according to the provided prompt.
string
required
The original text to rewrite.
string
required
The prompt describing how to rewrite the text.
RewriteOptions
Response<string>
The rewritten text according to the prompt.
summarize()
Summarizes a text of any length to a summary of the desired length.
string
required
The original text to summarize.
SummarizeOptions
Response<string>
The summarized text according to the specified options.
text()
Generates a text of the desired length according to the prompt.
string
required
The prompt describing what text to generate.
TextOptions
Response<string>
The generated text according to the prompt.
sort()
Sorts array items based on natural language sorting criteria.
array
required
The array of items to sort.
string
required
Natural language description of how to sort (e.g., “by priority”, “newest first”, “from least expensive to most expensive”).
SortOptions
Response<array>
The sorted array according to the specified instructions.
rate()
Rates array items on a 1-5 scale based on single or multiple criteria.
array
required
The array of items to rate.
string | Record<string, string>
required
Single criterion (string) or multiple criteria (object mapping criterion names to descriptions).Ratings scale: 1 = Very Bad, 2 = Bad, 3 = Average, 4 = Good, 5 = Very Good
RateOptions
Response<RatingResult[], SimplifiedRatingResult[]>
For single criterion (string instructions), returns array of numbers (total scores).For multiple criteria (object instructions), returns array of objects with scores per criterion and total.
group()
Groups array items into categories based on semantic similarity or criteria.
Array<T>
required
The array of items to group.
GroupOptions
Response<Group<T>[], Record<string, T[]>>
Simplified form: Object mapping group labels to arrays of items.Full form: Array of group objects with id, label, and elements.
answer()
Answers questions from documents with citations and intelligent handling of edge cases.
array
required
Array of documents to search (strings, objects, or any type).
string
required
The question to answer.
AnswerOptions
Response<AnswerResult>
The result can be one of five types:
patch()
Patches files based on natural language instructions using the micropatch protocol.
Array<File>
required
Array of files to patch.
string
required
Natural language instructions describing what changes to make.
PatchOptions
Response<Array<File>>
Array of patched files with the same structure as input, plus:
with()
Creates a new Zai instance with modified configuration options.
Partial<ZaiConfig>
required
Configuration options to override. Can include any of the
ZaiConfig properties: client, userId, modelId, activeLearning, or namespace.Zai
A new Zai instance with the updated configuration.
learn()
Creates a new Zai instance with active learning enabled for the specified task ID.
string
required
The ID of the task for active learning. This will be used to organize and retrieve examples for improving future responses.
Zai
A new Zai instance with active learning enabled for the specified task.
Response methods
All Zai operations return aResponse object that implements promise-like behavior while providing additional functionality for event handling and request control.
You can call any of the following methods on the Response object:
result()
Returns the complete result including output, usage statistics, and elapsed time.
Promise<ResultData>
on()
Registers an event listener for the specified event type.
'progress' | 'complete' | 'error'
required
The event type to listen for:
progress: Emitted during request processing with usage statisticscomplete: Emitted when the operation completes successfullyerror: Emitted when an error occurs
(event: EventData) => void
required
The callback function to execute when the event is emitted.
Response
The same Response instance for method chaining.
off()
Removes an event listener for the specified event type.
'progress' | 'complete' | 'error'
required
The event type to remove the listener from.
(event: EventData) => void
required
The specific listener function to remove.
Response
The same Response instance for method chaining.
once()
Registers an event listener that will be called only once.
'progress' | 'complete' | 'error'
required
The event type to listen for.
(event: EventData) => void
required
The callback function to execute when the event is emitted.
Response
The same Response instance for method chaining.
bindSignal()
Binds an AbortSignal to the response for cancellation control.
AbortSignal
required
The AbortSignal to bind to this response.
Response
The same Response instance for method chaining.
abort()
Aborts the ongoing operation.
string | Error
Optional reason for the abortion.
void
No return value.
then()
Attaches callbacks for the resolution and/or rejection of the response.
(value: T) => TResult1 | PromiseLike<TResult1>
Callback to execute when the response resolves successfully.
(reason: any) => TResult2 | PromiseLike<TResult2>
Callback to execute when the response rejects.
PromiseLike<TResult1 | TResult2>
A promise-like object for further chaining.
catch()
Attaches a callback for handling rejection of the response.
(reason: any) => TResult | PromiseLike<TResult>
Callback to execute when the response rejects.
PromiseLike<T | TResult>
A promise-like object for further chaining.