@botpress/zai 2.4.2 → 2.5.1

package/dist/index.d.ts

@@ -676,7 +676,7 @@ declare class Response<T = any, S = T> implements PromiseLike<S> {
     }>;
 }
 
-type Options$a = {
+type Options$b = {
     /** The maximum number of tokens to generate */
     length?: number;
 };
@@ -732,7 +732,7 @@ declare module '@botpress/zai' {
          * )
          * ```
          */
-        text(prompt: string, options?: Options$a): Response<string>;
+        text(prompt: string, options?: Options$b): Response<string>;
     }
 }
 
@@ -741,7 +741,7 @@ type Example$3 = {
     output: string;
     instructions?: string;
 };
-type Options$9 = {
+type Options$a = {
     /** Examples to guide the rewriting */
     examples?: Array<Example$3>;
     /** The maximum number of tokens to generate */
@@ -833,11 +833,11 @@ declare module '@botpress/zai' {
          * // Result: "If the user is active AND has permission, then allow access"
          * ```
          */
-        rewrite(original: string, prompt: string, options?: Options$9): Response<string>;
+        rewrite(original: string, prompt: string, options?: Options$a): Response<string>;
     }
 }
 
-type Options$8 = {
+type Options$9 = {
     /** What should the text be summarized to? */
     prompt?: string;
     /** How to format the example text */
@@ -930,7 +930,7 @@ declare module '@botpress/zai' {
          * const summary = await response
          * ```
          */
-        summarize(original: string, options?: Options$8): Response<string>;
+        summarize(original: string, options?: Options$9): Response<string>;
     }
 }
 
@@ -940,7 +940,7 @@ type Example$2 = {
     reason?: string;
     condition?: string;
 };
-type Options$7 = {
+type Options$8 = {
     /** Examples to check the condition against */
     examples?: Array<Example$2>;
 };
@@ -1021,7 +1021,7 @@ declare module '@botpress/zai' {
          * const followsConventions = await zai.check(code, 'Does this follow naming conventions?')
          * ```
          */
-        check(input: unknown, condition: string, options?: Options$7): Response<{
+        check(input: unknown, condition: string, options?: Options$8): Response<{
             /** Whether the condition is true or not */
             value: boolean;
             /** The explanation of the decision */
@@ -1035,7 +1035,7 @@ type Example$1 = {
     filter: boolean;
     reason?: string;
 };
-type Options$6 = {
+type Options$7 = {
     /** The maximum number of tokens per item */
     tokensPerItem?: number;
     /** Examples to filter the condition against */
@@ -1129,11 +1129,11 @@ declare module '@botpress/zai' {
          * })
          * ```
          */
-        filter<T>(input: Array<T>, condition: string, options?: Options$6): Response<Array<T>>;
+        filter<T>(input: Array<T>, condition: string, options?: Options$7): Response<Array<T>>;
     }
 }
 
-type Options$5 = {
+type Options$6 = {
     /** Instructions to guide the user on how to extract the data */
     instructions?: string;
     /** The maximum number of tokens per chunk */
@@ -1214,7 +1214,7 @@ declare module '@botpress/zai' {
          * console.log(`Extraction took ${elapsed}ms and cost $${usage.cost.total}`)
          * ```
          */
-        extract<S extends OfType<any>>(input: unknown, schema: S, options?: Options$5): Response<S['_output']>;
+        extract<S extends OfType<any>>(input: unknown, schema: S, options?: Options$6): Response<S['_output']>;
     }
 }
 
@@ -1233,7 +1233,7 @@ type Example<T extends string> = {
         explanation?: string;
     }>>;
 };
-type Options$4<T extends string> = {
+type Options$5<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 */
@@ -1363,7 +1363,7 @@ declare module '@botpress/zai' {
          * })
          * ```
          */
-        label<T extends string>(input: unknown, labels: Labels<T>, options?: Options$4<T>): Response<{
+        label<T extends string>(input: unknown, labels: Labels<T>, options?: Options$5<T>): Response<{
             [K in T]: {
                 explanation: string;
                 value: boolean;
@@ -1385,7 +1385,7 @@ type InitialGroup = {
     label: string;
     elements?: unknown[];
 };
-type Options$3 = {
+type Options$4 = {
     instructions?: string;
     tokensPerElement?: number;
     chunkLength?: number;
@@ -1543,12 +1543,12 @@ declare module '@botpress/zai' {
          * })
          * ```
          */
-        group<T>(input: Array<T>, options?: Options$3): Response<Array<Group<T>>, Record<string, T[]>>;
+        group<T>(input: Array<T>, options?: Options$4): Response<Array<Group<T>>, Record<string, T[]>>;
     }
 }
 
 type RatingInstructions = string | Record<string, string>;
-type Options$2 = {
+type Options$3 = {
     /** The maximum number of tokens per item */
     tokensPerItem?: number;
     /** The maximum number of items to rate per chunk */
@@ -1679,11 +1679,11 @@ declare module '@botpress/zai' {
          * console.log('Score breakdown:', sorted[0].rating)
          * ```
          */
-        rate<T, I extends RatingInstructions>(input: Array<T>, instructions: I, options?: Options$2): Response<Array<RatingResult<I>>, Array<SimplifiedRatingResult<I>>>;
+        rate<T, I extends RatingInstructions>(input: Array<T>, instructions: I, options?: Options$3): Response<Array<RatingResult<I>>, Array<SimplifiedRatingResult<I>>>;
     }
 }
 
-type Options$1 = {
+type Options$2 = {
     /** The maximum number of tokens per item */
     tokensPerItem?: number;
 };
@@ -1804,7 +1804,7 @@ declare module '@botpress/zai' {
          * )
          * ```
          */
-        sort<T>(input: Array<T>, instructions: string, options?: Options$1): Response<Array<T>, Array<T>>;
+        sort<T>(input: Array<T>, instructions: string, options?: Options$2): Response<Array<T>, Array<T>>;
     }
 }
 
@@ -1885,7 +1885,7 @@ type AnswerExample<T> = {
     /** The expected answer result */
     result: AnswerResult<T>;
 };
-type Options<T> = {
+type Options$1<T> = {
     /** Examples to help guide answer generation */
     examples?: AnswerExample<T>[];
     /** Additional instructions for answer generation */
@@ -1999,7 +1999,131 @@ declare module '@botpress/zai' {
          * }
          * ```
          */
-        answer<T>(documents: T[], question: string, options?: Options<T>): Response<AnswerResult<T>, AnswerResult<T>>;
+        answer<T>(documents: T[], question: string, options?: Options$1<T>): Response<AnswerResult<T>, AnswerResult<T>>;
+    }
+}
+
+/**
+ * Represents a file to be patched
+ */
+type File = {
+    /** The file path (e.g., 'src/components/Button.tsx') */
+    path: string;
+    /** The file name (e.g., 'Button.tsx') */
+    name: string;
+    /** The file content */
+    content: string;
+    /** The patch operations that were applied (only present in output) */
+    patch?: string;
+};
+type Options = {
+    /**
+     * Maximum tokens per chunk when processing large files or many files.
+     * If a single file exceeds this limit, it will be split into chunks.
+     * If all files together exceed this limit, they will be processed in batches.
+     * If not specified, all files must fit in a single prompt.
+     */
+    maxTokensPerChunk?: number;
+};
+declare module '@botpress/zai' {
+    interface Zai {
+        /**
+         * Patches files based on natural language instructions using the micropatch protocol.
+         *
+         * This operation takes an array of files and instructions, then returns the modified files.
+         * It uses a token-efficient line-based patching protocol (micropatch) that allows precise
+         * modifications without regenerating entire files.
+         *
+         * @param files - Array of files to patch, each with path, name, and content
+         * @param instructions - Natural language instructions describing what changes to make
+         * @param options - Optional configuration for patch generation
+         * @returns Response promise resolving to array of patched files
+         *
+         * @example Simple text replacement
+         * ```typescript
+         * const files = [{
+         *   path: 'src/hello.ts',
+         *   name: 'hello.ts',
+         *   content: 'console.log("Hello World")'
+         * }]
+         *
+         * const patched = await zai.patch(
+         *   files,
+         *   'change the message to say "Hi World"'
+         * )
+         * // patched[0].content contains: console.log("Hi World")
+         * // patched[0].patch contains: ◼︎=1|console.log("Hi World")
+         * ```
+         *
+         * @example Adding documentation
+         * ```typescript
+         * 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'
+         * )
+         * ```
+         *
+         * @example Patching multiple files
+         * ```typescript
+         * const files = [
+         *   { path: 'package.json', name: 'package.json', content: '...' },
+         *   { path: 'config.json', name: 'config.json', content: '...' }
+         * ]
+         *
+         * const patched = await zai.patch(
+         *   files,
+         *   'update version to 2.0.0 in all config files'
+         * )
+         * ```
+         *
+         * @example Refactoring code
+         * ```typescript
+         * const files = [{
+         *   path: 'src/api.ts',
+         *   name: 'api.ts',
+         *   content: 'function fetchUser() { ... }'
+         * }]
+         *
+         * const patched = await zai.patch(
+         *   files,
+         *   'convert fetchUser to an async function and add error handling'
+         * )
+         * ```
+         *
+         * @example Removing code
+         * ```typescript
+         * const files = [{
+         *   path: 'src/legacy.ts',
+         *   name: 'legacy.ts',
+         *   content: 'const debug = true\nconsole.log("Debug mode")\nfunction main() {...}'
+         * }]
+         *
+         * const patched = await zai.patch(
+         *   files,
+         *   'remove all debug-related code'
+         * )
+         * ```
+         *
+         * @example Inspecting applied patches
+         * ```typescript
+         * const patched = await zai.patch(files, 'add error handling')
+         *
+         * // Check what patches were applied
+         * for (const file of patched) {
+         *   if (file.patch) {
+         *     console.log(`Patches for ${file.path}:`)
+         *     console.log(file.patch)
+         *   }
+         * }
+         * ```
+         */
+        patch(files: Array<File>, instructions: string, options?: Options): Response<Array<File>>;
     }
 }
 

package/dist/index.js

@@ -10,4 +10,5 @@ import "./operations/group";
 import "./operations/rate";
 import "./operations/sort";
 import "./operations/answer";
+import "./operations/patch";
 export { Zai };

package/dist/micropatch.js

@@ -0,0 +1,273 @@
+export class Micropatch {
+  _text;
+  _eol;
+  /**
+   * Create a Micropatch instance.
+   * @param source The file contents.
+   * @param eol Line ending style. If omitted, it is auto-detected from `source` (CRLF if any CRLF is present; otherwise LF).
+   */
+  constructor(source, eol) {
+    this._text = source;
+    this._eol = eol ?? Micropatch.detectEOL(source);
+  }
+  /** Get current text. */
+  getText() {
+    return this._text;
+  }
+  /**
+   * Replace current text.
+   * Useful if you want to "load" a new snapshot without reconstructing the class.
+   */
+  setText(source, eol) {
+    this._text = source;
+    this._eol = eol ?? Micropatch.detectEOL(source);
+  }
+  /**
+   * Apply ops text to current buffer.
+   * @param opsText One or more operations in the v0.3 syntax.
+   * @returns The updated text (also stored internally).
+   * @throws If the patch contains invalid syntax (e.g., range on insert).
+   */
+  apply(opsText) {
+    const ops = Micropatch.parseOps(opsText);
+    this._text = Micropatch._applyOps(this._text, ops, this._eol);
+    return this._text;
+  }
+  /**
+   * Render a numbered view of the current buffer (token-cheap preview for models).
+   * Format: `NNN|<line>`, starting at 001.
+   */
+  renderNumberedView() {
+    const NL = this._eol === "lf" ? "\n" : "\r\n";
+    const lines = Micropatch._splitEOL(this._text);
+    return lines.map((l, i) => `${String(i + 1).padStart(3, "0")}|${l}`).join(NL);
+  }
+  // ---------------------- Static helpers ----------------------
+  /** Detect EOL style from content. */
+  static detectEOL(source) {
+    return /\r\n/.test(source) ? "crlf" : "lf";
+  }
+  /** Split text into lines, preserving empty last line if present. */
+  static _splitEOL(text) {
+    const parts = text.split(/\r?\n/);
+    return parts;
+  }
+  /** Join lines with the chosen EOL. */
+  static _joinEOL(lines, eol) {
+    const NL = eol === "lf" ? "\n" : "\r\n";
+    return lines.join(NL);
+  }
+  /** Unescape payload text: `\◼︎` → `◼︎`. */
+  static _unescapeMarker(s) {
+    return s.replace(/\\◼︎/g, "\u25FC\uFE0E");
+  }
+  /**
+   * Parse ops text (v0.3).
+   * - Ignores blank lines and lines not starting with `◼︎` (you can keep comments elsewhere).
+   * - Validates ranges for allowed ops.
+   */
+  static parseOps(opsText) {
+    const lines = opsText.split(/\r?\n/);
+    const ops = [];
+    const headerRe = /^◼︎([<>=-])(\d+)(?:-(\d+))?(?:\|(.*))?$/;
+    let i = 0;
+    while (i < lines.length) {
+      const line = lines[i];
+      if (!line) {
+        i++;
+        continue;
+      }
+      if (!line.startsWith("\u25FC\uFE0E")) {
+        i++;
+        continue;
+      }
+      const m = headerRe.exec(line);
+      if (!m || !m[1] || !m[2]) {
+        throw new Error(`Invalid op syntax at line ${i + 1}: ${line}`);
+      }
+      const op = m[1];
+      const aNum = parseInt(m[2], 10);
+      const bNum = m[3] ? parseInt(m[3], 10) : void 0;
+      const firstPayload = m[4] ?? "";
+      if (aNum < 1 || bNum !== void 0 && bNum < aNum) {
+        throw new Error(`Invalid line/range at line ${i + 1}: ${line}`);
+      }
+      if (op === "<" || op === ">") {
+        if (bNum !== void 0) {
+          throw new Error(`Insert cannot target a range (line ${i + 1})`);
+        }
+        const text = Micropatch._unescapeMarker(firstPayload);
+        ops.push({ k: op, n: aNum, s: text });
+        i++;
+        continue;
+      }
+      if (op === "-") {
+        if (firstPayload !== "") {
+          throw new Error(`Delete must not have a payload (line ${i + 1})`);
+        }
+        if (bNum === void 0) {
+          ops.push({ k: "-", n: aNum });
+        } else {
+          ops.push({ k: "--", a: aNum, b: bNum });
+        }
+        i++;
+        continue;
+      }
+      if (op === "=") {
+        const payload = [Micropatch._unescapeMarker(firstPayload)];
+        let j = i + 1;
+        while (j < lines.length) {
+          const nextLine = lines[j];
+          if (!nextLine || nextLine.startsWith("\u25FC\uFE0E")) break;
+          payload.push(Micropatch._unescapeMarker(nextLine));
+          j++;
+        }
+        if (bNum === void 0) {
+          ops.push({ k: "=", n: aNum, s: payload });
+        } else {
+          ops.push({ k: "=-", a: aNum, b: bNum, s: payload });
+        }
+        i = j;
+        continue;
+      }
+      i++;
+    }
+    return Micropatch._canonicalizeOrder(ops);
+  }
+  /** Order ops deterministically according to the spec. */
+  static _canonicalizeOrder(ops) {
+    const delS = [];
+    const delR = [];
+    const eqS = [];
+    const eqR = [];
+    const insB = [];
+    const insA = [];
+    for (const o of ops) {
+      switch (o.k) {
+        case "-":
+          delS.push(o);
+          break;
+        case "--":
+          delR.push(o);
+          break;
+        case "=":
+          eqS.push(o);
+          break;
+        case "=-":
+          eqR.push(o);
+          break;
+        case "<":
+          insB.push(o);
+          break;
+        case ">":
+          insA.push(o);
+          break;
+        default:
+          break;
+      }
+    }
+    delS.sort((a, b) => b.n - a.n);
+    delR.sort((a, b) => b.a - a.a);
+    eqS.sort((a, b) => a.n - b.n);
+    eqR.sort((a, b) => a.a - b.a);
+    insB.sort((a, b) => a.n - b.n);
+    insA.sort((a, b) => a.n - b.n);
+    return [].concat(delS, delR, eqS, eqR, insB, insA);
+  }
+  /**
+   * Apply normalized ops to given source.
+   * - Uses a live index map from ORIGINAL 1-based addresses → current positions.
+   * - Skips ops whose targets can no longer be mapped (idempotency-friendly).
+   */
+  static _applyOps(source, ops, eol) {
+    const lines = Micropatch._splitEOL(source);
+    const idx = Array.from({ length: lines.length }, (_, i) => i);
+    const map = (n) => idx[n - 1] ?? -1;
+    const bump = (from, delta) => {
+      for (let i = 0; i < idx.length; i++) {
+        const current = idx[i];
+        if (current !== void 0 && current >= from) {
+          idx[i] = current + delta;
+        }
+      }
+    };
+    for (const o of ops) {
+      switch (o.k) {
+        case "-": {
+          const i = map(o.n);
+          if (i >= 0 && i < lines.length) {
+            lines.splice(i, 1);
+            bump(i, -1);
+          }
+          break;
+        }
+        case "--": {
+          const a = map(o.a);
+          const b = map(o.b);
+          if (a >= 0 && b >= a && b < lines.length) {
+            lines.splice(a, b - a + 1);
+            bump(a, -(b - a + 1));
+          }
+          break;
+        }
+        case "=": {
+          const i = map(o.n);
+          if (i >= 0 && i < lines.length) {
+            const rep = o.s;
+            lines.splice(i, 1, ...rep);
+            bump(i + 1, rep.length - 1);
+          }
+          break;
+        }
+        case "=-": {
+          const a = map(o.a);
+          const b = map(o.b);
+          if (a >= 0 && b >= a && b < lines.length) {
+            const rep = o.s;
+            lines.splice(a, b - a + 1, ...rep);
+            bump(a + 1, rep.length - (b - a + 1));
+          }
+          break;
+        }
+        case "<": {
+          const i = Math.max(0, Math.min(map(o.n), lines.length));
+          if (i >= 0) {
+            lines.splice(i, 0, o.s);
+            bump(i, 1);
+          }
+          break;
+        }
+        case ">": {
+          const i = Math.max(0, Math.min(map(o.n) + 1, lines.length));
+          if (i >= 0) {
+            lines.splice(i, 0, o.s);
+            bump(i, 1);
+          }
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    return Micropatch._joinEOL(lines, eol);
+  }
+  // ---------------------- Convenience APIs ----------------------
+  /**
+   * Convenience: one-shot apply.
+   * @param source Text to patch.
+   * @param opsText Operations text.
+   * @param eol EOL style (auto-detected if omitted).
+   */
+  static applyText(source, opsText, eol) {
+    const inst = new Micropatch(source, eol);
+    return inst.apply(opsText);
+  }
+  /**
+   * Convenience: parse only.
+   * Useful for validation without applying.
+   */
+  static validate(opsText) {
+    const ops = Micropatch.parseOps(opsText);
+    return { ok: true, count: ops.length };
+  }
+}