@ax-llm/ax 11.0.15 → 11.0.17

package/index.cjs

@@ -325,28 +325,24 @@ var AxAIServiceError = class extends Error {
     this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
     this.errorId = crypto.randomUUID();
     this.context = context;
+    this.stack = this.toString();
   }
   timestamp;
   errorId;
   context;
   toString() {
-    return `${this.name} [${this.errorId}]: ${this.message}
-Timestamp: ${this.timestamp}
-URL: ${this.url}${this.requestBody ? `
-Request Body: ${JSON.stringify(this.requestBody, null, 2)}` : ""}${Object.keys(this.context).length ? `
-Context: ${JSON.stringify(this.context, null, 2)}` : ""}`;
-  }
-  toJSON() {
-    return {
-      name: this.name,
-      errorId: this.errorId,
-      message: this.message,
-      timestamp: this.timestamp,
-      url: this.url,
-      requestBody: this.requestBody,
-      context: this.context,
-      stack: this.stack
-    };
+    return [
+      `${this.name}: ${this.message}`,
+      `URL: ${this.url}`,
+      `Request Body: ${JSON.stringify(this.requestBody, null, 2)}`,
+      `Context: ${JSON.stringify(this.context, null, 2)}`,
+      `Timestamp: ${this.timestamp}`,
+      `Error ID: ${this.errorId}`
+    ].join("\n");
+  }
+  // For Node.js, override the custom inspect method so console.log shows our custom string.
+  [Symbol.for("nodejs.util.inspect.custom")](_depth, _options) {
+    return this.toString();
   }
 };
 var AxAIServiceStatusError = class extends AxAIServiceError {
@@ -664,6 +660,35 @@ var apiCall = async (api, json) => {
   }
 };
 
+// util/transform.ts
+var import_web4 = require("stream/web");
+var TypeTransformer = class {
+  buffer;
+  doneCallback;
+  transformFn;
+  constructor(transformFn, doneCallback) {
+    this.transformFn = transformFn;
+    this.doneCallback = doneCallback;
+    this.buffer = doneCallback ? [] : void 0;
+  }
+  async transform(obj, controller) {
+    const val = this.transformFn(obj);
+    if (val) {
+      controller.enqueue(val);
+      this.buffer?.push(val);
+    }
+  }
+  async flush(controller) {
+    await this.doneCallback?.(this.buffer ?? []);
+    controller.terminate();
+  }
+};
+var RespTransformStream = class extends import_web4.TransformStream {
+  constructor(transformFn, doneCallback) {
+    super(new TypeTransformer(transformFn, doneCallback));
+  }
+};
+
 // util/log.ts
 var ColorLog = class {
   // ANSI escape codes for different colors
@@ -695,42 +720,106 @@ var ColorLog = class {
   }
 };
 
-// util/transform.ts
-var import_web4 = require("stream/web");
-var TypeTransformer = class {
-  buffer;
-  doneCallback;
-  transformFn;
-  constructor(transformFn, doneCallback) {
-    this.transformFn = transformFn;
-    this.doneCallback = doneCallback;
-    this.buffer = doneCallback ? [] : void 0;
-  }
-  async transform(obj, controller) {
-    const val = this.transformFn(obj);
-    if (val) {
-      controller.enqueue(val);
-      this.buffer?.push(val);
+// ai/debug.ts
+var colorLog = new ColorLog();
+var formatChatMessage = (msg, hideContent) => {
+  switch (msg.role) {
+    case "system":
+      return `
+${colorLog.blueBright("System:")}
+${colorLog.whiteBright(msg.content)}`;
+    case "function":
+      return `
+${colorLog.blueBright("Function Result:")}
+${colorLog.whiteBright(msg.result)}`;
+    case "user": {
+      if (typeof msg.content === "string") {
+        return `
+${colorLog.blueBright("User:")}
+${colorLog.whiteBright(msg.content)}`;
+      }
+      const items = msg.content.map((v) => {
+        switch (v.type) {
+          case "text":
+            return `${colorLog.whiteBright(v.text)}`;
+          case "image":
+            return `(Image, ${v.mimeType}) ${colorLog.whiteBright(v.image.substring(0, 10))}`;
+          default:
+            throw new Error("Invalid content type");
+        }
+      });
+      return `
+${colorLog.blueBright("User:")}
+${items.join("\n")}`;
+    }
+    case "assistant": {
+      if (msg.functionCalls) {
+        const fns = msg.functionCalls?.map(({ function: fn }) => {
+          const args = typeof fn.params !== "string" ? JSON.stringify(fn.params, null, 2) : fn.params;
+          return `${fn.name}(${args})`;
+        });
+        return `
+${colorLog.blueBright("\nFunctions:")}
+${colorLog.whiteBright(fns.join("\n"))}`;
+      }
+      return `
+${colorLog.blueBright("\nAssistant:")}
+${hideContent ? "" : colorLog.whiteBright(msg.content ?? "<empty>")}`;
     }
+    default:
+      throw new Error("Invalid role");
   }
-  async flush(controller) {
-    await this.doneCallback?.(this.buffer ?? []);
-    controller.terminate();
+};
+var logChatRequestMessage = (msg) => {
+  process.stdout.write(formatChatMessage(msg) + "\n");
+  process.stdout.write(colorLog.blueBright("\nAssistant:\n"));
+};
+var logChatRequest = (chatPrompt) => {
+  const items = chatPrompt?.map((msg) => formatChatMessage(msg));
+  if (items) {
+    process.stdout.write(items.join("\n"));
+    process.stdout.write(colorLog.blueBright("\nAssistant:\n"));
   }
 };
-var RespTransformStream = class extends import_web4.TransformStream {
-  constructor(transformFn, doneCallback) {
-    super(new TypeTransformer(transformFn, doneCallback));
+var logResponseResult = (r) => {
+  if (r.content) {
+    process.stdout.write(colorLog.greenBright(r.content));
+  }
+  if (r.functionCalls) {
+    for (const [i, f] of r.functionCalls.entries()) {
+      if (f.function.name) {
+        if (i > 0) {
+          process.stdout.write("\n");
+        }
+        process.stdout.write(
+          `Function ${i + 1} -> ${colorLog.greenBright(f.function.name)}`
+        );
+      }
+      if (f.function.params) {
+        const params = typeof f.function.params === "string" ? f.function.params : JSON.stringify(f.function.params, null, 2);
+        process.stdout.write(`${colorLog.greenBright(params)}`);
+      }
+    }
+  }
+};
+var logResponse = (resp) => {
+  if (!resp.results) {
+    return;
+  }
+  for (const r of resp.results) {
+    logResponseResult(r);
   }
 };
+var logResponseDelta = (delta) => {
+  process.stdout.write(colorLog.greenBright(delta));
+};
 
 // ai/base.ts
-var colorLog = new ColorLog();
 var axBaseAIDefaultConfig = () => structuredClone({
   maxTokens: 2e3,
   temperature: 0,
   topK: 40,
-  frequencyPenalty: 0.2
+  topP: 0.9
 });
 var AxBaseAI = class {
   constructor(aiImpl, {
@@ -1010,8 +1099,8 @@ var AxBaseAI = class {
       );
       return res2;
     };
-    if (this.debug) {
-      logChatRequest(req);
+    if (options?.debug ?? this.debug) {
+      logChatRequest(req["chatPrompt"]);
     }
     const rt = options?.rateLimiter ?? this.rt;
     const rv = rt ? await rt(fn, { modelUsage: this.modelUsage }) : await fn();
@@ -1029,13 +1118,13 @@ var AxBaseAI = class {
         if (span?.isRecording()) {
           setResponseAttr(res2, span);
         }
-        if (this.debug) {
+        if (options?.debug ?? this.debug) {
           logResponse(res2);
         }
         return res2;
       };
       const doneCb = async (_values) => {
-        if (this.debug) {
+        if (options?.debug ?? this.debug) {
           process.stdout.write("\n");
         }
       };
@@ -1058,7 +1147,7 @@ var AxBaseAI = class {
     if (span?.isRecording()) {
       setResponseAttr(res, span);
     }
-    if (this.debug) {
+    if (options?.debug ?? this.debug) {
       logResponse(res);
     }
     span?.end();
@@ -1149,83 +1238,6 @@ var AxBaseAI = class {
     return { ...headers, ...await this.headers() };
   }
 };
-var logChatRequest = (req) => {
-  const hasAssistant = req.chatPrompt?.some((msg) => msg.role === "assistant");
-  const items = req.chatPrompt?.map((msg) => {
-    if (hasAssistant && msg.role === "system") {
-      return "";
-    }
-    switch (msg.role) {
-      case "system":
-        return `${colorLog.blueBright("System:")}
-${colorLog.whiteBright(msg.content)}`;
-      case "function":
-        return `${colorLog.blueBright("Function Result:")}
-${colorLog.whiteBright(msg.result)}`;
-      case "user": {
-        if (typeof msg.content === "string") {
-          return `${colorLog.blueBright("User:")}
-${colorLog.whiteBright(msg.content)}`;
-        }
-        const items2 = msg.content.map((v) => {
-          switch (v.type) {
-            case "text":
-              return `${colorLog.whiteBright(v.text)}`;
-            case "image":
-              return `(Image, ${v.mimeType}) ${colorLog.whiteBright(v.image.substring(0, 10))}`;
-            default:
-              throw new Error("Invalid content type");
-          }
-        });
-        return `${colorLog.blueBright("User:")}
-${items2.join("\n")}`;
-      }
-      case "assistant": {
-        if (msg.functionCalls) {
-          const fns = msg.functionCalls?.map(({ function: fn }) => {
-            const args = typeof fn.params !== "string" ? JSON.stringify(fn.params, null, 2) : fn.params;
-            return `${fn.name}(${args})`;
-          });
-          return `${colorLog.blueBright("\nFunctions:")}
-${colorLog.whiteBright(fns.join("\n"))}`;
-        }
-        return `${colorLog.blueBright("\nAssistant:")}
-${colorLog.whiteBright(msg.content ?? "<empty>")}`;
-      }
-      default:
-        throw new Error("Invalid role");
-    }
-  });
-  if (items) {
-    process.stdout.write("\n===\n" + items.join("\n") + "\n\n---\n");
-  }
-};
-var logResponse = (resp) => {
-  if (!resp.results) {
-    return;
-  }
-  for (const r of resp.results) {
-    if (r.content) {
-      process.stdout.write(colorLog.greenBright(r.content));
-    }
-    if (r.functionCalls) {
-      for (const [i, f] of r.functionCalls.entries()) {
-        if (f.function.name) {
-          if (i > 0) {
-            process.stdout.write("\n\n");
-          }
-          process.stdout.write(
-            `Function ${i + 1} -> ${colorLog.greenBright(f.function.name)} `
-          );
-        }
-        if (f.function.params) {
-          const params = typeof f.function.params === "string" ? f.function.params : JSON.stringify(f.function.params, null, 2);
-          process.stdout.write(`${colorLog.greenBright(params)}`);
-        }
-      }
-    }
-  }
-};
 var setResponseAttr = (res, span) => {
   if (res.modelUsage) {
     span.setAttributes({
@@ -2686,9 +2698,10 @@ var axAIGoogleGeminiDefaultConfig = () => structuredClone({
   ...axBaseAIDefaultConfig()
 });
 var AxAIGoogleGeminiImpl = class {
-  constructor(config, isVertex, apiKey, options) {
+  constructor(config, isVertex, endpoint, apiKey, options) {
     this.config = config;
     this.isVertex = isVertex;
+    this.endpoint = endpoint;
     this.apiKey = apiKey;
     this.options = options;
   }
@@ -2713,9 +2726,16 @@ var AxAIGoogleGeminiImpl = class {
     if (!req.chatPrompt || req.chatPrompt.length === 0) {
       throw new Error("Chat prompt is empty");
     }
-    const apiConfig = {
-      name: stream ? `/models/${model}:streamGenerateContent?alt=sse` : `/models/${model}:generateContent`
-    };
+    let apiConfig;
+    if (this.endpoint) {
+      apiConfig = {
+        name: stream ? `/${this.endpoint}:streamGenerateContent?alt=sse` : `/${this.endpoint}:generateContent`
+      };
+    } else {
+      apiConfig = {
+        name: stream ? `/models/${model}:streamGenerateContent?alt=sse` : `/models/${model}:generateContent`
+      };
+    }
     if (!this.isVertex) {
       const pf = stream ? "&" : "?";
       apiConfig.name += `${pf}key=${this.apiKey}`;
@@ -2841,8 +2861,10 @@ var AxAIGoogleGeminiImpl = class {
       temperature: req.modelConfig?.temperature ?? this.config.temperature,
       topP: req.modelConfig?.topP ?? this.config.topP,
       topK: req.modelConfig?.topK ?? this.config.topK,
+      frequencyPenalty: req.modelConfig?.frequencyPenalty ?? this.config.frequencyPenalty,
       candidateCount: 1,
-      stopSequences: req.modelConfig?.stopSequences ?? this.config.stopSequences
+      stopSequences: req.modelConfig?.stopSequences ?? this.config.stopSequences,
+      responseMimeType: "text/plain"
     };
     const safetySettings2 = this.config.safetySettings;
     const reqValue = {
@@ -2866,9 +2888,15 @@ var AxAIGoogleGeminiImpl = class {
     let apiConfig;
     let reqValue;
     if (this.isVertex) {
-      apiConfig = {
-        name: `/models/${model}:predict`
-      };
+      if (this.endpoint) {
+        apiConfig = {
+          name: `/${this.endpoint}:predict`
+        };
+      } else {
+        apiConfig = {
+          name: `/models/${model}:predict`
+        };
+      }
       reqValue = {
         instances: req.texts.map((text) => ({
           content: text
@@ -2966,6 +2994,7 @@ var AxAIGoogleGemini = class extends AxBaseAI {
     apiKey,
     projectId,
     region,
+    endpoint,
     config,
     options,
     models
@@ -2974,7 +3003,13 @@ var AxAIGoogleGemini = class extends AxBaseAI {
     let apiURL;
     let headers;
     if (isVertex) {
-      apiURL = `https://${region}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${region}/publishers/google/`;
+      let path;
+      if (endpoint) {
+        path = "endpoints";
+      } else {
+        path = "publishers/google";
+      }
+      apiURL = `https://${region}-aiplatform.googleapis.com/v1/projects/${projectId}/locations/${region}/${path}`;
       if (apiKey) {
         headers = async () => ({ Authorization: `Bearer ${apiKey}` });
       } else {
@@ -2994,7 +3029,13 @@ var AxAIGoogleGemini = class extends AxBaseAI {
       ...axAIGoogleGeminiDefaultConfig(),
       ...config
     };
-    const aiImpl = new AxAIGoogleGeminiImpl(_config, isVertex, apiKey, options);
+    const aiImpl = new AxAIGoogleGeminiImpl(
+      _config,
+      isVertex,
+      endpoint,
+      apiKey,
+      options
+    );
     super(aiImpl, {
       name: "GoogleGeminiAI",
       apiURL,
@@ -3768,14 +3809,15 @@ function mergeFunctionCalls(functionCalls, functionCallDeltas) {
 // mem/memory.ts
 var defaultLimit = 1e4;
 var MemoryImpl = class {
-  constructor(limit = defaultLimit) {
+  constructor(limit = defaultLimit, debug = false) {
     this.limit = limit;
+    this.debug = debug;
     if (limit <= 0) {
       throw Error("argument 'limit' must be greater than 0");
     }
   }
   data = [];
-  add(value) {
+  addMemory(value) {
     if (Array.isArray(value)) {
       this.data.push(...value.map((chat) => ({ chat: structuredClone(chat) })));
     } else {
@@ -3788,7 +3830,13 @@ var MemoryImpl = class {
       this.data.splice(0, removeCount);
     }
   }
-  addResult({
+  add(value) {
+    this.addMemory(value);
+    if (this.debug) {
+      debugRequest(value);
+    }
+  }
+  addResultMessage({
     content,
     name,
     functionCalls
@@ -3796,26 +3844,44 @@ var MemoryImpl = class {
     if (!content && (!functionCalls || functionCalls.length === 0)) {
       return;
     }
-    this.add({ content, name, role: "assistant", functionCalls });
+    this.addMemory({ content, name, role: "assistant", functionCalls });
   }
-  updateResult({
+  addResult({
     content,
     name,
     functionCalls
+  }) {
+    this.addResultMessage({ content, name, functionCalls });
+    if (this.debug) {
+      debugResponse({ content, name, functionCalls });
+    }
+  }
+  updateResult({
+    content,
+    name,
+    functionCalls,
+    delta
   }) {
     const lastItem = this.data.at(-1);
     if (!lastItem || lastItem.chat.role !== "assistant") {
-      this.addResult({ content, name, functionCalls });
-      return;
-    }
-    if ("content" in lastItem.chat && content) {
-      lastItem.chat.content = content;
-    }
-    if ("name" in lastItem.chat && name) {
-      lastItem.chat.name = name;
+      this.addResultMessage({ content, name, functionCalls });
+    } else {
+      if ("content" in lastItem.chat && content) {
+        lastItem.chat.content = content;
+      }
+      if ("name" in lastItem.chat && name) {
+        lastItem.chat.name = name;
+      }
+      if ("functionCalls" in lastItem.chat && functionCalls) {
+        lastItem.chat.functionCalls = functionCalls;
+      }
     }
-    if ("functionCalls" in lastItem.chat && functionCalls) {
-      lastItem.chat.functionCalls = functionCalls;
+    if (this.debug) {
+      if (delta) {
+        debugResponseDelta(delta);
+      } else if (lastItem) {
+        debugResponse({ content, name, functionCalls });
+      }
     }
   }
   addTag(name) {
@@ -3855,16 +3921,21 @@ var MemoryImpl = class {
   }
   getLast() {
     const lastItem = this.data.at(-1);
-    return lastItem?.chat;
+    if (!lastItem) return void 0;
+    return {
+      chat: lastItem.chat,
+      tags: lastItem.tags
+    };
   }
   reset() {
     this.data = [];
   }
 };
 var AxMemory = class {
-  constructor(limit = defaultLimit) {
+  constructor(limit = defaultLimit, debug = false) {
     this.limit = limit;
-    this.defaultMemory = new MemoryImpl(limit);
+    this.debug = debug;
+    this.defaultMemory = new MemoryImpl(limit, debug);
   }
   memories = /* @__PURE__ */ new Map();
   defaultMemory;
@@ -3906,6 +3977,19 @@ var AxMemory = class {
     }
   }
 };
+function debugRequest(value) {
+  if (Array.isArray(value)) {
+    logChatRequest(value);
+  } else {
+    logChatRequestMessage(value);
+  }
+}
+function debugResponse(value) {
+  logResponseResult(value);
+}
+function debugResponseDelta(delta) {
+  logResponseDelta(delta);
+}
 
 // dsp/asserts.ts
 var AxAssertionError = class extends Error {
@@ -3940,7 +4024,7 @@ var assertAssertions = (asserts, values) => {
     }
   }
 };
-var assertStreamingAssertions = (asserts, values, xstate, content, final) => {
+var assertStreamingAssertions = (asserts, xstate, content, final = false) => {
   if (!xstate.currField || xstate.s === -1 || !asserts || asserts.length === 0) {
     return;
   }
@@ -4143,7 +4227,8 @@ ${pointer}`;
       "image",
       "audio",
       "datetime",
-      "date"
+      "date",
+      "code"
     ];
     const foundType = types.find((type) => this.match(type));
     if (!foundType) {
@@ -4450,6 +4535,10 @@ var validateValue = (field, value) => {
   const ft = field.type ?? { name: "string", isArray: false };
   const validateSingleValue = (expectedType, val) => {
     switch (expectedType) {
+      case "code":
+        return typeof val === "string";
+      case "json":
+        return typeof val === "object";
       case "string":
         return typeof val === "string";
       case "number":
@@ -4621,7 +4710,10 @@ var LRUCache = class {
 };
 var globalPrefixCache = new LRUCache(500);
 function matchesContent(content, prefix, startIndex = 0, prefixCache = globalPrefixCache) {
-  if (/^\s*$/.test(content)) {
+  if (/^```[a-zA-Z]*\s*$/.test(content)) {
+    return -4;
+  }
+  if (/^[\s`]*$/.test(content)) {
     return -3;
   }
   const exactMatchIndex = content.indexOf(prefix, startIndex);
@@ -4833,12 +4925,11 @@ var functionCallInstructions = `
 - Call functions step-by-step, using the output of one function as input to the next.
 - Use the function results to generate the output fields.`;
 var formattingRules = `
-## Output Formatting Rules
-- Output must strictly follow the defined plain-text \`key: value\` field format.
-- Each output key, value must strictly adhere to the specified output field formatting rules.
-- No preamble, postscript, or supplementary information.
-- Do not repeat output fields.
-- Do not use JSON to format the output.`;
+## Strict Output Formatting Rules
+- Output must strictly follow the defined plain-text \`field name: value\` field format.
+- Output field, values must strictly adhere to the specified output field formatting rules.
+- Do not add any text before or after the output fields, just the field name and value.
+- Do not use code blocks.`;
 var AxPromptTemplate = class {
   sig;
   fieldTemplates;
@@ -4847,25 +4938,23 @@ var AxPromptTemplate = class {
     this.sig = sig;
     this.fieldTemplates = fieldTemplates;
     const task = [];
-    const inArgs = this.renderDescFields(this.sig.getInputFields());
-    const outArgs = this.renderDescFields(this.sig.getOutputFields());
+    const inArgs = renderDescFields(this.sig.getInputFields());
+    const outArgs = renderDescFields(this.sig.getOutputFields());
     task.push(
       `You will be provided with the following fields: ${inArgs}. Your task is to generate new fields: ${outArgs}.`
     );
     const funcs = functions?.map(
       (f) => "toFunction" in f ? f.toFunction() : f
     );
-    const funcList = funcs?.map(
-      (fn) => `- \`${fn.name}\`: ${capitalizeFirstLetter(fn.description)}.`
-    ).join("\n");
+    const funcList = funcs?.map((fn) => `- \`${fn.name}\`: ${formatDescription(fn.description)}`).join("\n");
     if (funcList && funcList.length > 0) {
       task.push(`## Available Functions
 ${funcList}`);
     }
-    const inputFields = this.renderFields(this.sig.getInputFields());
+    const inputFields = renderInputFields(this.sig.getInputFields());
     task.push(`## Input Fields
 ${inputFields}`);
-    const outputFields = this.renderFields(this.sig.getOutputFields());
+    const outputFields = renderOutputFields(this.sig.getOutputFields());
     task.push(`## Output Fields
 ${outputFields}`);
     if (funcList && funcList.length > 0) {
@@ -4874,10 +4963,8 @@ ${outputFields}`);
     task.push(formattingRules.trim());
     const desc = this.sig.getDescription();
     if (desc) {
-      const capitalized = capitalizeFirstLetter(desc.trim());
-      const text = capitalized.endsWith(".") ? capitalized : capitalized + ".";
-      task.push(`---
-${text}`);
+      const text = formatDescription(desc);
+      task.push(text);
     }
     this.task = {
       type: "text",
@@ -4900,7 +4987,7 @@ ${text}`);
     let systemContent = this.task.text;
     if (examplesInSystemPrompt) {
       const combinedItems = [
-        { type: "text", text: systemContent + "\n\n" },
+        { type: "text", text: systemContent },
         ...renderedExamples,
         ...renderedDemos
       ];
@@ -5116,17 +5203,27 @@ ${text}`);
     }
     return [{ type: "text", text: text.join("") }];
   };
-  renderDescFields = (list) => list.map((v) => `\`${v.title}\``).join(", ");
-  renderFields = (fields) => {
-    const rows = fields.map((field) => {
-      const name = field.title;
-      const type = field.type?.name ? toFieldType(field.type) : "string";
-      const required = field.isOptional ? "optional" : "required";
-      const description = field.description ? `: ${capitalizeFirstLetter(field.description)}` : "";
-      return `- \`${name}:\` (${type}, ${required}) ${description}.`.trim();
-    });
-    return rows.join("\n");
-  };
+};
+var renderDescFields = (list) => list.map((v) => `\`${v.title}\``).join(", ");
+var renderInputFields = (fields) => {
+  const rows = fields.map((field) => {
+    const name = field.title;
+    const type = field.type?.name ? toFieldType(field.type) : "string";
+    const requiredMsg = field.isOptional ? `This optional ${type} field may be omitted` : `A ${type} field`;
+    const description = field.description ? ` ${formatDescription(field.description)}` : "";
+    return `${name}: (${requiredMsg})${description}`.trim();
+  });
+  return rows.join("\n");
+};
+var renderOutputFields = (fields) => {
+  const rows = fields.map((field) => {
+    const name = field.title;
+    const type = field.type?.name ? toFieldType(field.type) : "string";
+    const requiredMsg = field.isOptional ? `Only include this ${type} field is it's value is available` : `This ${type} field must be included`;
+    const description = field.description ? ` ${formatDescription(field.description)}` : "";
+    return `${name}: (${requiredMsg})${description}`.trim();
+  });
+  return rows.join("\n");
 };
 var processValue = (field, value) => {
   if (field.type?.name === "date" && value instanceof Date) {
@@ -5167,6 +5264,8 @@ var toFieldType = (type) => {
         return "JSON object";
       case "class":
         return `classification class (allowed classes: ${type.classes?.join(", ")})`;
+      case "code":
+        return "code";
       default:
         return "string";
     }
@@ -5200,11 +5299,9 @@ var isEmptyValue = (field, value) => {
   }
   return false;
 };
-function capitalizeFirstLetter(str) {
-  if (str.length === 0) {
-    return "";
-  }
-  return `${str.charAt(0).toUpperCase()}${str.slice(1)}`;
+function formatDescription(str) {
+  const value = str.trim();
+  return value.length > 0 ? `${value.charAt(0).toUpperCase()}${value.slice(1)}${value.endsWith(".") ? "" : "."}` : "";
 }
 
 // dsp/validate.ts
@@ -5339,7 +5436,7 @@ var streamingExtractValues = (sig, values, xstate, content, streamingValidation
     let e = matchesContent(content, prefix, xstate.s + 1);
     switch (e) {
       case -1:
-        if (streamingValidation && xstate.s == -1 && !field.isOptional) {
+        if (streamingValidation && values.length == 0 && !field.isOptional) {
           throw new ValidationError({
             message: "Required field not found",
             fields: [field]
@@ -5352,6 +5449,10 @@ var streamingExtractValues = (sig, values, xstate, content, streamingValidation
       // Partial match at end, skip and gather more content
       case -3:
         return true;
+      // String is only whitespace, skip and gather more content
+      case -4:
+        xstate.inBlock = true;
+        return true;
     }
     let prefixLen = prefix.length;
     if (xstate.currField) {
@@ -5360,6 +5461,7 @@ var streamingExtractValues = (sig, values, xstate, content, streamingValidation
       if (parsedValue !== void 0) {
         values[xstate.currField.name] = parsedValue;
       }
+      xstate.lastDelta = val;
     }
     checkMissingRequiredFields(xstate, values, index);
     xstate.s = e + prefixLen;
@@ -5372,7 +5474,7 @@ var streamingExtractValues = (sig, values, xstate, content, streamingValidation
 };
 var streamingExtractFinalValue = (sig, values, xstate, content) => {
   if (xstate.currField) {
-    const val = content.substring(xstate.s).trim();
+    let val = content.substring(xstate.s).trim();
     const parsedValue = validateAndParseFieldValue(xstate.currField, val);
     if (parsedValue !== void 0) {
       values[xstate.currField.name] = parsedValue;
@@ -5383,6 +5485,8 @@ var streamingExtractFinalValue = (sig, values, xstate, content) => {
 };
 var convertValueToType = (field, val) => {
   switch (field.type?.name) {
+    case "code":
+      return extractBlock(val);
     case "string":
       return val;
     case "number": {
@@ -5421,47 +5525,79 @@ var convertValueToType = (field, val) => {
       return val;
   }
 };
-function* streamValues(sig, values, xstate, content, final = false) {
+function processStreamingDelta(content, xstate) {
   if (!xstate.currField) {
-    return;
+    return null;
   }
-  const fieldName = xstate.currField.name;
+  const { name: fieldName, type: fieldType } = xstate.currField ?? {};
+  const { isArray: fieldIsArray, name: fieldTypeName } = fieldType ?? {};
   if (!xstate.streamedIndex) {
-    xstate.streamedIndex = { [fieldName]: 0 };
-  }
-  if (!final) {
-    if (!xstate.currField.type || !xstate.currField.type.isArray && xstate.currField.type.name === "string") {
-      const pos = xstate.streamedIndex[fieldName] ?? 0;
-      const s = xstate.s + pos;
-      const v = content.substring(s);
-      const v1 = v.replace(/[\s\n\t]+$/, "");
-      const v2 = pos === 0 ? v1.trimStart() : v1;
-      if (v2.length > 0) {
-        yield { [fieldName]: v2 };
-        xstate.streamedIndex[fieldName] = pos + v1.length;
-      }
-      return;
+    xstate.streamedIndex = {};
+  }
+  if (fieldIsArray) {
+    if (xstate.streamedIndex[fieldName] === void 0) {
+      xstate.streamedIndex[fieldName] = 0;
+    }
+    return null;
+  }
+  if (fieldTypeName !== "string" && fieldTypeName !== "code") {
+    if (xstate.streamedIndex[fieldName] === void 0) {
+      xstate.streamedIndex[fieldName] = 0;
     }
+    return null;
+  }
+  const pos = xstate.streamedIndex[fieldName] ?? 0;
+  const s = xstate.s + pos;
+  const isFirstChunk = pos === 0;
+  const d1 = content.substring(s);
+  let d2 = d1.replace(/\s+$/, "");
+  if (xstate.currField?.type?.name === "code") {
+    d2 = d2.replace(/\s*```\s*$/, "");
+  }
+  let d3 = isFirstChunk ? d2.trimStart() : d2;
+  if (xstate.currField?.type?.name === "code") {
+    d3 = d3.replace(/^[ ]*```[a-zA-Z0-9]*\n\s*/, "");
+  }
+  if (d3.length > 0) {
+    xstate.streamedIndex[fieldName] = pos + d2.length;
+  }
+  return d3;
+}
+function getStreamingDelta(content, xstate) {
+  if (xstate.lastDelta) {
+    processStreamingDelta(xstate.lastDelta, xstate);
+    xstate.lastDelta = void 0;
+  }
+  return processStreamingDelta(content, xstate);
+}
+function* streamValues(sig, values, xstate, delta) {
+  if (!xstate.currField) {
+    return;
+  }
+  const fieldName = xstate.currField.name;
+  if (delta && delta.length > 0) {
+    yield { [fieldName]: delta };
+    return;
   }
   for (const key of Object.keys(values)) {
     const value = values[key];
     if (Array.isArray(value)) {
-      const s = xstate.streamedIndex[key] ?? 0;
+      if (xstate.streamedIndex?.[key] === void 0) {
+        throw new Error("Streamed index is not set for array field " + key);
+      }
+      const s = xstate.streamedIndex[key];
       const v = value.slice(s);
       if (v && v.length > 0) {
         yield { [key]: v };
         xstate.streamedIndex[key] = s + 1;
       }
-      continue;
-    }
-    if (!xstate.streamedIndex[key]) {
+    } else {
       yield { [key]: value };
-      xstate.streamedIndex[key] = 1;
     }
   }
 }
 function validateAndParseFieldValue(field, fieldValue) {
-  if (!fieldValue || fieldValue === "" || fieldValue === "null" || fieldValue === "NULL" || fieldValue === "undefined") {
+  if (!fieldValue || fieldValue === "" || /^(null|undefined)\s*$/i.test(fieldValue)) {
     if (field.isOptional) {
       return;
     }
@@ -5527,8 +5663,8 @@ function validateAndParseFieldValue(field, fieldValue) {
   return value;
 }
 var extractBlock = (input) => {
-  const jsonBlockPattern = /```([A-Za-z]+)?\s*([\s\S]*?)\s*```/g;
-  const match = jsonBlockPattern.exec(input);
+  const markdownBlockPattern = /```([A-Za-z]*)\n([\s\S]*?)\n```/g;
+  const match = markdownBlockPattern.exec(input);
   if (!match) {
     return input;
   }
@@ -5541,6 +5677,61 @@ var extractBlock = (input) => {
   return input;
 };
 
+// dsp/fieldProcessor.ts
+async function processFieldProcessors(fieldProcessors, values, mem, sessionId) {
+  for (const processor of fieldProcessors) {
+    if (values[processor.field.name] === void 0) {
+      continue;
+    }
+    const result = await processor.process(values[processor.field.name], {
+      sessionId,
+      values,
+      done: true
+    });
+    addToMemory(processor.field, mem, result, sessionId);
+  }
+}
+async function processStreamingFieldProcessors(fieldProcessors, content, xstate, mem, values, sessionId, done = false) {
+  for (const processor of fieldProcessors) {
+    if (xstate.currField?.name !== processor.field.name) {
+      continue;
+    }
+    let value = content.substring(xstate.s);
+    if (xstate.currField?.type?.name === "code") {
+      value = value.replace(/^[ ]*```[a-zA-Z0-9]*\n\s*/, "");
+      value = value.replace(/\s*```\s*$/, "");
+    }
+    const result = await processor.process(value, {
+      sessionId,
+      values,
+      done
+    });
+    addToMemory(xstate.currField, mem, result, sessionId);
+  }
+}
+var addToMemory = (field, mem, result, sessionId) => {
+  if (result === void 0 || typeof result === "string" && (result === "" || /^(null|undefined)\s*$/i.test(result))) {
+    return;
+  }
+  let resultText = JSON.stringify(
+    result,
+    (key, value) => typeof value === "bigint" ? Number(value) : value,
+    2
+  );
+  const text = getFieldProcessingMessage(field, resultText);
+  mem.add({ role: "user", content: [{ type: "text", text }] }, sessionId);
+  mem.addTag(`processor`, sessionId);
+};
+function getFieldProcessingMessage(field, resultText) {
+  const isCodeField = field.type?.name === "code";
+  const fieldTitle = field.title;
+  if (isCodeField) {
+    return `Code in the field "${fieldTitle}" was executed. The code execution produced the following output: ${resultText}`;
+  } else {
+    return `The field "${fieldTitle}" was processed. The field contents were transformed into the following output: ${resultText}`;
+  }
+}
+
 // dsp/jsonschema.ts
 var validateJSONSchema = (schema) => {
   const errors = [];
@@ -5758,6 +5949,8 @@ var AxGen = class extends AxProgramWithSignature {
   options;
   functions;
   functionsExecuted = /* @__PURE__ */ new Set();
+  fieldProcessors = [];
+  streamingFieldProcessors = [];
   constructor(signature, options) {
     super(signature, { description: options?.description });
     this.options = options;
@@ -5778,6 +5971,24 @@ var AxGen = class extends AxProgramWithSignature {
   addStreamingAssert = (fieldName, fn, message) => {
     this.streamingAsserts.push({ fieldName, fn, message });
   };
+  addFieldProcessor = (fieldName, fn, streaming = false) => {
+    const field = this.signature.getOutputFields().find((f) => f.name === fieldName);
+    if (!field) {
+      throw new Error(`addFieldProcessor: field ${fieldName} not found`);
+    }
+    if (streaming) {
+      const ft = field.type?.name;
+      const isText = !ft || ft === "string" || ft === "code";
+      if (!isText) {
+        throw new Error(
+          `addFieldProcessor: field ${fieldName} is must be a text field`
+        );
+      }
+      this.streamingFieldProcessors.push({ field, process: fn });
+    } else {
+      this.fieldProcessors.push({ field, process: fn });
+    }
+  };
   async forwardSendRequest({
     ai,
     mem,
@@ -5810,7 +6021,8 @@ var AxGen = class extends AxProgramWithSignature {
         sessionId,
         traceId,
         rateLimiter,
-        stream
+        stream,
+        debug: false
       }
     );
     return res;
@@ -5820,7 +6032,8 @@ var AxGen = class extends AxProgramWithSignature {
     mem,
     options
   }) {
-    const { sessionId, traceId, model, functions, earlyFail } = options ?? {};
+    const { sessionId, traceId, model, functions } = options ?? {};
+    const fastFail = options?.fastFail ?? this.options?.fastFail;
     const usageInfo = {
       ai: ai.getName(),
       model: ai.getModelInfo().name
@@ -5840,7 +6053,7 @@ var AxGen = class extends AxProgramWithSignature {
         traceId,
         sessionId,
         functions,
-        earlyFail
+        fastFail
       });
     } else {
       yield await this.processResponse({
@@ -5864,9 +6077,9 @@ var AxGen = class extends AxProgramWithSignature {
     sessionId,
     traceId,
     functions,
-    earlyFail
+    fastFail
   }) {
-    const streamingValidation = earlyFail ?? ai.getFeatures().functionCot !== true;
+    const streamingValidation = fastFail ?? ai.getFeatures().functionCot !== true;
     const functionCalls = [];
     const values = {};
     const xstate = {
@@ -5885,12 +6098,20 @@ var AxGen = class extends AxProgramWithSignature {
       if (result.functionCalls) {
         mergeFunctionCalls(functionCalls, result.functionCalls);
         mem.updateResult(
-          { name: result.name, content, functionCalls },
+          {
+            name: result.name,
+            content,
+            functionCalls,
+            delta: result.functionCalls?.[0]?.function?.params
+          },
           sessionId
         );
       } else if (result.content) {
         content += result.content;
-        mem.updateResult({ name: result.name, content }, sessionId);
+        mem.updateResult(
+          { name: result.name, content, delta: result.content },
+          sessionId
+        );
         const skip = streamingExtractValues(
           this.signature,
           values,
@@ -5901,15 +6122,20 @@ var AxGen = class extends AxProgramWithSignature {
         if (skip) {
           continue;
         }
-        assertStreamingAssertions(
-          this.streamingAsserts,
-          values,
-          xstate,
-          content,
-          false
-        );
+        assertStreamingAssertions(this.streamingAsserts, xstate, content);
         assertAssertions(this.asserts, values);
-        yield* streamValues(this.signature, values, xstate, content);
+        if (this.streamingFieldProcessors.length !== 0) {
+          await processStreamingFieldProcessors(
+            this.streamingFieldProcessors,
+            content,
+            xstate,
+            mem,
+            values,
+            sessionId
+          );
+        }
+        const delta = getStreamingDelta(content, xstate);
+        yield* streamValues(this.signature, values, xstate, delta);
       }
       if (result.finishReason === "length") {
         throw new Error("Max tokens reached before completion");
@@ -5931,15 +6157,29 @@ var AxGen = class extends AxProgramWithSignature {
       this.functionsExecuted = /* @__PURE__ */ new Set([...this.functionsExecuted, ...fx]);
     } else {
       streamingExtractFinalValue(this.signature, values, xstate, content);
-      assertStreamingAssertions(
-        this.streamingAsserts,
-        values,
-        xstate,
-        content,
-        true
-      );
+      assertStreamingAssertions(this.streamingAsserts, xstate, content, true);
       assertAssertions(this.asserts, values);
-      yield* streamValues(this.signature, values, xstate, content, true);
+      if (this.fieldProcessors.length) {
+        await processFieldProcessors(
+          this.fieldProcessors,
+          values,
+          mem,
+          sessionId
+        );
+      }
+      if (this.streamingFieldProcessors.length !== 0) {
+        await processStreamingFieldProcessors(
+          this.streamingFieldProcessors,
+          content,
+          xstate,
+          mem,
+          values,
+          sessionId,
+          true
+        );
+      }
+      const delta = getStreamingDelta(content, xstate);
+      yield* streamValues(this.signature, values, xstate, delta);
     }
   }
   async processResponse({
@@ -5980,6 +6220,14 @@ var AxGen = class extends AxProgramWithSignature {
       } else if (result.content) {
         extractValues(this.signature, values, result.content);
         assertAssertions(this.asserts, values);
+        if (this.fieldProcessors.length) {
+          await processFieldProcessors(
+            this.fieldProcessors,
+            values,
+            mem,
+            sessionId
+          );
+        }
       }
       if (result.finishReason === "length") {
         throw new Error("Max tokens reached before completion");
@@ -5991,7 +6239,8 @@ var AxGen = class extends AxProgramWithSignature {
     const stopFunction = (options?.stopFunction ?? this.options?.stopFunction)?.toLowerCase();
     const maxRetries = options.maxRetries ?? this.options?.maxRetries ?? 10;
     const maxSteps = options.maxSteps ?? this.options?.maxSteps ?? 10;
-    const mem = options.mem ?? this.options?.mem ?? new AxMemory();
+    const debug = options.debug ?? ai.getOptions().debug;
+    const mem = options.mem ?? this.options?.mem ?? new AxMemory(1e4, debug);
     let err;
     if (options?.functions && options.functions.length > 0) {
       const promptTemplate = this.options?.promptTemplate ?? AxPromptTemplate;
@@ -6022,6 +6271,9 @@ var AxGen = class extends AxProgramWithSignature {
           if (shouldContinue) {
             continue multiStepLoop;
           }
+          if (debug) {
+            process.stdout.write("\n");
+          }
           return;
         } catch (e) {
           let errorFields;
@@ -6054,10 +6306,12 @@ var AxGen = class extends AxProgramWithSignature {
   }
   shouldContinueSteps(lastMemItem, stopFunction) {
     const stopFunctionExecuted = stopFunction && this.functionsExecuted.has(stopFunction);
-    if (lastMemItem?.role === "function" && stopFunction && stopFunctionExecuted) {
+    const isFunction = lastMemItem?.chat?.role === "function";
+    const isProcessor = lastMemItem?.tags ? lastMemItem.tags.some((tag) => tag === "processor") : false;
+    if (isFunction && stopFunction && stopFunctionExecuted) {
       return false;
     }
-    if (lastMemItem?.role === "function") {
+    if (isFunction || isProcessor) {
       return true;
     }
     return false;
@@ -6137,17 +6391,18 @@ function processChildAgentFunction(childFunction, parentValues, parentInputKeys,
         injectionKeys
       );
       const originalFunc = processedFunction.func;
-      processedFunction.func = (childArgs, funcOptions) => {
+      processedFunction.func = async (childArgs, funcOptions) => {
         const updatedChildArgs = {
           ...childArgs,
           ...pick(parentValues, injectionKeys)
         };
         if (options.debug && injectionKeys.length > 0) {
           process.stdout.write(
-            `Function Params: ${JSON.stringify(updatedChildArgs, null, 2)}`
+            `
+Function Params: ${JSON.stringify(updatedChildArgs, null, 2)}`
           );
         }
-        return originalFunc(updatedChildArgs, funcOptions);
+        return await originalFunc(updatedChildArgs, funcOptions);
       };
     }
     return processedFunction;
@@ -6173,6 +6428,7 @@ var AxAgent = class {
   agents;
   disableSmartModelRouting;
   excludeFieldsFromPassthrough;
+  debug;
   name;
   //   private subAgentList?: string
   func;
@@ -6185,12 +6441,13 @@ var AxAgent = class {
     agents,
     functions
   }, options) {
-    const { disableSmartModelRouting, excludeFieldsFromPassthrough } = options ?? {};
+    const { disableSmartModelRouting, excludeFieldsFromPassthrough, debug } = options ?? {};
     this.ai = ai;
     this.agents = agents;
     this.functions = functions;
     this.disableSmartModelRouting = disableSmartModelRouting;
     this.excludeFieldsFromPassthrough = excludeFieldsFromPassthrough ?? [];
+    this.debug = debug;
     if (!name || name.length < 5) {
       throw new Error(
         `Agent name must be at least 10 characters (more descriptive)`
@@ -6250,10 +6507,21 @@ var AxAgent = class {
       if (!ai) {
         throw new Error("AI service is required to run the agent");
       }
+      const debug = this.getDebug(ai, options);
+      if (debug) {
+        process.stdout.write(`
+--- Agent Engaged: ${this.name} ---
+`);
+      }
       const ret = await boundFunc(ai, values, {
         ...options,
         model
       });
+      if (debug) {
+        process.stdout.write(`
+--- Agent Done: ${this.name} ---
+`);
+      }
       const sig = this.program.getSignature();
       const outFields = sig.getOutputFields();
       const result = Object.keys(ret).map((k) => {
@@ -6284,10 +6552,11 @@ var AxAgent = class {
     const mm = ai?.getModelList();
     const parentSchema = this.program.getSignature().getInputFields();
     const parentKeys = parentSchema.map((p) => p.name);
+    const debug = this.getDebug(ai, options);
     const agentFuncs = this.agents?.map((agent) => {
       const f = agent.getFeatures();
       const processOptions = {
-        debug: ai?.getOptions()?.debug ?? false,
+        debug,
         disableSmartModelRouting: !!this.disableSmartModelRouting,
         excludeFieldsFromPassthrough: f.excludeFieldsFromPassthrough,
         canConfigureSmartModelRouting: f.canConfigureSmartModelRouting
@@ -6304,16 +6573,21 @@ var AxAgent = class {
       ...options?.functions ?? this.functions ?? [],
       ...agentFuncs ?? []
     ];
-    return { ai, functions };
+    return { ai, functions, debug };
   }
   async forward(parentAi, values, options) {
-    const { ai, functions } = this.init(parentAi, values, options);
-    return await this.program.forward(ai, values, { ...options, functions });
+    const { ai, functions, debug } = this.init(parentAi, values, options);
+    return await this.program.forward(ai, values, {
+      ...options,
+      debug,
+      functions
+    });
   }
   async *streamingForward(parentAi, values, options) {
-    const { ai, functions } = this.init(parentAi, values, options);
+    const { ai, functions, debug } = this.init(parentAi, values, options);
     return yield* this.program.streamingForward(ai, values, {
       ...options,
+      debug,
       functions
     });
   }
@@ -6337,6 +6611,9 @@ var AxAgent = class {
     }
     this.program.getSignature().setDescription(definition);
   }
+  getDebug(ai, options) {
+    return options?.debug ?? this.debug ?? ai?.getOptions()?.debug ?? false;
+  }
 };
 function toCamelCase(inputString) {
   const words = inputString.split(/[^a-zA-Z0-9]/);