@botpress/zai 2.2.0 → 2.3.0

package/README.md

@@ -129,7 +129,56 @@ const organized = await zai.group(largeArray, {
 })
 ```
 
-### 7. Text - Generate content
+### 7. Rate - Score items on a 1-5 scale
+
+```typescript
+// Auto-generate criteria (returns total score)
+const scores = await zai.rate(products, 'is it a good value product?')
+// Result: [12, 8, 15] (total scores for each item)
+
+// Get detailed ratings
+const { output } = await zai.rate(products, 'is it a good value product?').result()
+// Result: [
+//   { affordability: 4, quality: 5, features: 3, total: 12 },
+//   { affordability: 3, quality: 2, features: 3, total: 8 },
+//   ...
+// ]
+
+// Use fixed criteria
+const ratings = await zai.rate(passwords, {
+  length: 'password length (12+ chars = very_good, 8-11 = good, 6-7 = average, 4-5 = bad, <4 = very_bad)',
+  complexity: 'character variety (all types = very_good, 3 types = good, 2 types = average, 1 type = bad)',
+  strength: 'overall password strength',
+})
+// Result: [
+//   { length: 5, complexity: 5, strength: 5, total: 15 },
+//   { length: 1, complexity: 1, strength: 1, total: 3 },
+// ]
+
+// Rate large datasets efficiently (parallelized)
+const allRatings = await zai.rate(Array(500).fill(item), 'how complete is this?')
+// Processes ~500 items in ~120ms with automatic chunking
+```
+
+### 8. Sort - Order items with natural language
+
+```typescript
+// Sort by natural criteria
+const sorted = await zai.sort(emails, 'sort by urgency')
+// LLM determines criteria and orders items accordingly
+
+// Sort with detailed results
+const { output } = await zai.sort(tasks, 'sort by priority').result()
+// output includes scoring breakdown for each item
+
+// Complex multi-criteria sorting
+const prioritized = await zai.sort(tickets, 'sort by customer importance and issue severity')
+
+// Sort large datasets efficiently (parallelized with chunking)
+const orderedItems = await zai.sort(Array(500).fill(item), 'sort by relevance')
+```
+
+### 9. Text - Generate content
 
 ```typescript
 const blogPost = await zai.text('Write about the future of AI', {
@@ -138,7 +187,7 @@ const blogPost = await zai.text('Write about the future of AI', {
 })
 ```
 
-### 8. Summarize - Create summaries
+### 10. Summarize - Create summaries
 
 ```typescript
 // Simple summary
@@ -263,6 +312,8 @@ setTimeout(() => controller.abort(), 5000)
 - `.rewrite(content, instruction, options?)` - Transform text
 - `.filter(items, condition, options?)` - Filter array items
 - `.group(items, options?)` - Organize items into categories
+- `.rate(items, instructions, options?)` - Rate items on 1-5 scale
+- `.sort(items, instructions, options?)` - Order items with natural language
 - `.text(prompt, options?)` - Generate text
 - `.summarize(content, options?)` - Create summary
 

package/dist/index.d.ts

@@ -166,14 +166,14 @@ declare class Response<T = any, S = T> implements PromiseLike<S> {
     }>;
 }
 
-type Options$7 = {
+type Options$9 = {
     /** The maximum number of tokens to generate */
     length?: number;
 };
 declare module '@botpress/zai' {
     interface Zai {
         /** Generates a text of the desired length according to the prompt */
-        text(prompt: string, options?: Options$7): Response<string>;
+        text(prompt: string, options?: Options$9): Response<string>;
     }
 }
 
@@ -182,7 +182,7 @@ type Example$3 = {
     output: string;
     instructions?: string;
 };
-type Options$6 = {
+type Options$8 = {
     /** Examples to guide the rewriting */
     examples?: Array<Example$3>;
     /** The maximum number of tokens to generate */
@@ -191,11 +191,11 @@ type Options$6 = {
 declare module '@botpress/zai' {
     interface Zai {
         /** Rewrites a string according to match the prompt */
-        rewrite(original: string, prompt: string, options?: Options$6): Response<string>;
+        rewrite(original: string, prompt: string, options?: Options$8): Response<string>;
     }
 }
 
-type Options$5 = {
+type Options$7 = {
     /** What should the text be summarized to? */
     prompt?: string;
     /** How to format the example text */
@@ -215,7 +215,7 @@ type Options$5 = {
 declare module '@botpress/zai' {
     interface Zai {
         /** Summarizes a text of any length to a summary of the desired length */
-        summarize(original: string, options?: Options$5): Response<string>;
+        summarize(original: string, options?: Options$7): Response<string>;
     }
 }
 
@@ -225,14 +225,14 @@ type Example$2 = {
     reason?: string;
     condition?: string;
 };
-type Options$4 = {
+type Options$6 = {
     /** Examples to check the condition against */
     examples?: Array<Example$2>;
 };
 declare module '@botpress/zai' {
     interface Zai {
         /** Checks wether a condition is true or not */
-        check(input: unknown, condition: string, options?: Options$4): Response<{
+        check(input: unknown, condition: string, options?: Options$6): Response<{
             /** Whether the condition is true or not */
             value: boolean;
             /** The explanation of the decision */
@@ -246,7 +246,7 @@ type Example$1 = {
     filter: boolean;
     reason?: string;
 };
-type Options$3 = {
+type Options$5 = {
     /** The maximum number of tokens per item */
     tokensPerItem?: number;
     /** Examples to filter the condition against */
@@ -255,11 +255,11 @@ type Options$3 = {
 declare module '@botpress/zai' {
     interface Zai {
         /** Filters elements of an array against a condition */
-        filter<T>(input: Array<T>, condition: string, options?: Options$3): Response<Array<T>>;
+        filter<T>(input: Array<T>, condition: string, options?: Options$5): Response<Array<T>>;
     }
 }
 
-type Options$2 = {
+type Options$4 = {
     /** Instructions to guide the user on how to extract the data */
     instructions?: string;
     /** The maximum number of tokens per chunk */
@@ -274,7 +274,7 @@ type OfType<O, T extends __Z = __Z<O>> = T extends __Z<O> ? T : never;
 declare module '@botpress/zai' {
     interface Zai {
         /** Extracts one or many elements from an arbitrary input */
-        extract<S extends OfType<any>>(input: unknown, schema: S, options?: Options$2): Response<S['_output']>;
+        extract<S extends OfType<any>>(input: unknown, schema: S, options?: Options$4): Response<S['_output']>;
     }
 }
 
@@ -293,7 +293,7 @@ type Example<T extends string> = {
         explanation?: string;
     }>>;
 };
-type Options$1<T extends string> = {
+type Options$3<T extends string> = {
     /** Examples to help the user make a decision */
     examples?: Array<Example<T>>;
     /** Instructions to guide the user on how to extract the data */
@@ -305,7 +305,7 @@ type Labels<T extends string> = Record<T, string>;
 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$1<T>): Response<{
+        label<T extends string>(input: unknown, labels: Labels<T>, options?: Options$3<T>): Response<{
             [K in T]: {
                 explanation: string;
                 value: boolean;
@@ -327,7 +327,7 @@ type InitialGroup = {
     label: string;
     elements?: unknown[];
 };
-type Options = {
+type Options$2 = {
     instructions?: string;
     tokensPerElement?: number;
     chunkLength?: number;
@@ -335,7 +335,56 @@ type Options = {
 };
 declare module '@botpress/zai' {
     interface Zai {
-        group<T>(input: Array<T>, options?: Options): Response<Array<Group<T>>, Record<string, T[]>>;
+        group<T>(input: Array<T>, options?: Options$2): Response<Array<Group<T>>, Record<string, T[]>>;
+    }
+}
+
+type RatingInstructions = string | Record<string, string>;
+type Options$1 = {
+    /** The maximum number of tokens per item */
+    tokensPerItem?: number;
+    /** The maximum number of items to rate per chunk */
+    maxItemsPerChunk?: number;
+};
+type RatingResult<T extends RatingInstructions> = T extends string ? {
+    [key: string]: number;
+    total: number;
+} : T extends Record<string, string> ? {
+    [K in keyof T]: number;
+} & {
+    total: number;
+} : never;
+type SimplifiedRatingResult<T extends RatingInstructions> = T extends string ? number : RatingResult<T>;
+declare module '@botpress/zai' {
+    interface Zai {
+        /**
+         * Rates an array of items based on provided instructions.
+         * Returns a number (1-5) if instructions is a string, or a Record<string, number> if instructions is a Record.
+         */
+        rate<T, I extends RatingInstructions>(input: Array<T>, instructions: I, options?: Options$1): Response<Array<RatingResult<I>>, Array<SimplifiedRatingResult<I>>>;
+    }
+}
+
+type Options = {
+    /** The maximum number of tokens per item */
+    tokensPerItem?: number;
+};
+declare module '@botpress/zai' {
+    interface Zai {
+        /**
+         * Sorts an array of items based on provided instructions.
+         * Returns the sorted array directly when awaited.
+         * Use .result() to get detailed scoring information including why each item got its position.
+         *
+         * @example
+         * // Simple usage
+         * const sorted = await zai.sort(items, 'from least expensive to most expensive')
+         *
+         * @example
+         * // Get detailed results
+         * const { output: sorted, usage } = await zai.sort(items, 'by priority').result()
+         */
+        sort<T>(input: Array<T>, instructions: string, options?: Options): Response<Array<T>, Array<T>>;
     }
 }
 

package/dist/index.js

@@ -7,4 +7,6 @@ import "./operations/filter";
 import "./operations/extract";
 import "./operations/label";
 import "./operations/group";
+import "./operations/rate";
+import "./operations/sort";
 export { Zai };

package/dist/operations/group.js

@@ -4,7 +4,7 @@ import pLimit from "p-limit";
 import { ZaiContext } from "../context";
 import { Response } from "../response";
 import { getTokenizer } from "../tokenizer";
-import { stringify } from "../utils";
+import { fastHash, stringify } from "../utils";
 import { Zai } from "../zai";
 import { PROMPT_INPUT_BUFFER, PROMPT_OUTPUT_BUFFER } from "./constants";
 const _InitialGroup = z.object({
@@ -27,6 +27,8 @@ const group = async (input, _options, ctx) => {
   const options = _Options.parse(_options ?? {});
   const tokenizer = await getTokenizer();
   const model = await ctx.getModel();
+  const taskId = ctx.taskId;
+  const taskType = "zai.group";
   if (input.length === 0) {
     return [];
   }
@@ -92,6 +94,27 @@ const group = async (input, _options, ctx) => {
     return chunks.length > 0 ? chunks : [[]];
   };
   const processChunk = async (elementIndices, groupIds) => {
+    const chunkElements = elementIndices.map((idx) => elements[idx].element);
+    const chunkInputStr = JSON.stringify(chunkElements);
+    const examples = taskId && ctx.adapter ? await ctx.adapter.getExamples({
+      input: chunkInputStr.slice(0, 1e3),
+      // Limit search string length
+      taskType,
+      taskId
+    }) : [];
+    const key = fastHash(
+      stringify({
+        taskId,
+        taskType,
+        input: chunkInputStr,
+        instructions: options.instructions ?? "",
+        groupIds: groupIds.join(",")
+      })
+    );
+    const exactMatch = examples.find((x) => x.key === key);
+    if (exactMatch && exactMatch.output) {
+      return exactMatch.output;
+    }
     const elementsText = elementIndices.map((idx, i) => {
       const elem = elements[idx];
       const truncated = tokenizer.truncate(elem.stringified, options.tokensPerElement);
@@ -102,6 +125,40 @@ const group = async (input, _options, ctx) => {
 ${groupsList.map((l) => `- ${l}`).join("\n")}
 
 ` : "";
+    const exampleMessages = [];
+    for (const example of examples.slice(0, 5)) {
+      try {
+        const exampleInput = JSON.parse(example.input);
+        const exampleElements = Array.isArray(exampleInput) ? exampleInput : [exampleInput];
+        const exampleElementsText = exampleElements.map((el, i) => `\u25A0${i}: ${stringify(el, false).slice(0, 200)}\u25A0`).join("\n");
+        exampleMessages.push({
+          type: "text",
+          role: "user",
+          content: `Expert Example - Elements to group:
+${exampleElementsText}
+
+Group each element.`
+        });
+        const exampleOutput = example.output;
+        if (Array.isArray(exampleOutput) && exampleOutput.length > 0) {
+          const formattedAssignments = exampleOutput.map((assignment) => `\u25A0${assignment.elementIndex}:${assignment.label}\u25A0`).join("\n");
+          exampleMessages.push({
+            type: "text",
+            role: "assistant",
+            content: `${formattedAssignments}
+${END}`
+          });
+          if (example.explanation) {
+            exampleMessages.push({
+              type: "text",
+              role: "assistant",
+              content: `Reasoning: ${example.explanation}`
+            });
+          }
+        }
+      } catch {
+      }
+    }
     const systemPrompt = `You are grouping elements into cohesive groups.
 
 ${options.instructions ? `**Instructions:** ${options.instructions}
@@ -125,7 +182,7 @@ ${END}`.trim();
     const { extracted } = await ctx.generateContent({
       systemPrompt,
       stopSequences: [END],
-      messages: [{ type: "text", role: "user", content: userPrompt }],
+      messages: [...exampleMessages, { type: "text", role: "user", content: userPrompt }],
       transform: (text) => {
         const assignments = [];
         const regex = /■(\d+):([^■]+)■/g;
@@ -255,6 +312,40 @@ ${END}`.trim();
       });
     }
   }
+  if (taskId && ctx.adapter && !ctx.controller.signal.aborted) {
+    const key = fastHash(
+      stringify({
+        taskId,
+        taskType,
+        input: JSON.stringify(input),
+        instructions: options.instructions ?? ""
+      })
+    );
+    const outputAssignments = [];
+    for (const [groupId, elementIndices] of groupElements.entries()) {
+      const groupInfo = groups.get(groupId);
+      for (const idx of elementIndices) {
+        outputAssignments.push({
+          elementIndex: idx,
+          label: groupInfo.label
+        });
+      }
+    }
+    await ctx.adapter.saveExample({
+      key,
+      taskType,
+      taskId,
+      input: JSON.stringify(input),
+      output: result,
+      instructions: options.instructions ?? "",
+      metadata: {
+        cost: { input: 0, output: 0 },
+        latency: 0,
+        model: ctx.modelId,
+        tokens: { input: 0, output: 0 }
+      }
+    });
+  }
   return result;
 };
 Zai.prototype.group = function(input, _options) {