@ax-llm/ax 12.0.16 → 12.0.17

package/index.js

@@ -1,71 +1,3 @@
-// ai/base.ts
-import crypto2 from "crypto";
-import { context, SpanKind } from "@opentelemetry/api";
-
-// trace/trace.ts
-var axSpanAttributes = {
-  // LLM
-  LLM_SYSTEM: "gen_ai.system",
-  LLM_OPERATION_NAME: "gen_ai.operation.name",
-  LLM_REQUEST_MODEL: "gen_ai.request.model",
-  LLM_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
-  LLM_REQUEST_TEMPERATURE: "gen_ai.request.temperature",
-  LLM_REQUEST_TOP_K: "gen_ai.request.top_k",
-  LLM_REQUEST_FREQUENCY_PENALTY: "gen_ai.request.frequency_penalty",
-  LLM_REQUEST_PRESENCE_PENALTY: "gen_ai.request.presence_penalty",
-  LLM_REQUEST_STOP_SEQUENCES: "gen_ai.request.stop_sequences",
-  LLM_REQUEST_LLM_IS_STREAMING: "gen_ai.request.llm_is_streaming",
-  LLM_REQUEST_TOP_P: "gen_ai.request.top_p",
-  LLM_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
-  LLM_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
-  LLM_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens",
-  LLM_USAGE_THOUGHTS_TOKENS: "gen_ai.usage.thoughts_tokens",
-  // Vector DB
-  DB_SYSTEM: "db.system",
-  DB_TABLE: "db.table",
-  DB_NAMESPACE: "db.namespace",
-  DB_ID: "db.id",
-  DB_QUERY_TEXT: "db.query.text",
-  DB_VECTOR: "db.vector",
-  DB_OPERATION_NAME: "db.operation.name",
-  DB_VECTOR_QUERY_TOP_K: "db.vector.query.top_k",
-  DB_QUERY_EMBEDDINGS: "db.query.embeddings",
-  DB_QUERY_RESULT: "db.query.result",
-  // Query Embeddings
-  DB_QUERY_EMBEDDINGS_VECTOR: "db.query.embeddings.vector",
-  // Query Result (canonical format)
-  DB_QUERY_RESULT_ID: "db.query.result.id",
-  DB_QUERY_RESULT_SCORE: "db.query.result.score",
-  DB_QUERY_RESULT_DISTANCE: "db.query.result.distance",
-  DB_QUERY_RESULT_METADATA: "db.query.result.metadata",
-  DB_QUERY_RESULT_VECTOR: "db.query.result.vector",
-  DB_QUERY_RESULT_DOCUMENT: "db.query.result.document"
-};
-var axSpanEvents = {
-  GEN_AI_USER_MESSAGE: "gen_ai.user.message",
-  GEN_AI_SYSTEM_MESSAGE: "gen_ai.system.message",
-  GEN_AI_ASSISTANT_MESSAGE: "gen_ai.assistant.message",
-  GEN_AI_TOOL_MESSAGE: "gen_ai.tool.message",
-  // For tool messages in request & response tool calls
-  GEN_AI_CHOICE: "gen_ai.choice",
-  GEN_AI_USAGE: "gen_ai.usage"
-};
-var AxLLMRequestTypeValues = /* @__PURE__ */ ((AxLLMRequestTypeValues2) => {
-  AxLLMRequestTypeValues2["COMPLETION"] = "completion";
-  AxLLMRequestTypeValues2["CHAT"] = "chat";
-  AxLLMRequestTypeValues2["RERANK"] = "rerank";
-  AxLLMRequestTypeValues2["UNKNOWN"] = "unknown";
-  return AxLLMRequestTypeValues2;
-})(AxLLMRequestTypeValues || {});
-var AxSpanKindValues = /* @__PURE__ */ ((AxSpanKindValues2) => {
-  AxSpanKindValues2["WORKFLOW"] = "workflow";
-  AxSpanKindValues2["TASK"] = "task";
-  AxSpanKindValues2["AGENT"] = "agent";
-  AxSpanKindValues2["TOOL"] = "tool";
-  AxSpanKindValues2["UNKNOWN"] = "unknown";
-  return AxSpanKindValues2;
-})(AxSpanKindValues || {});
-
 // util/apicall.ts
 import crypto from "crypto";
 import {
@@ -320,6 +252,33 @@ var AxAIServiceAuthenticationError = class extends AxAIServiceError {
     this.name = this.constructor.name;
   }
 };
+var AxAIRefusalError = class extends Error {
+  constructor(refusalMessage, model, requestId) {
+    super(`Model refused to fulfill request: ${refusalMessage}`);
+    this.refusalMessage = refusalMessage;
+    this.model = model;
+    this.requestId = requestId;
+    this.name = "AxAIRefusalError";
+    this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    this.errorId = crypto.randomUUID();
+  }
+  timestamp;
+  errorId;
+  toString() {
+    return [
+      `${this.name}: ${this.message}`,
+      `Refusal: ${this.refusalMessage}`,
+      this.model ? `Model: ${this.model}` : "",
+      this.requestId ? `Request ID: ${this.requestId}` : "",
+      `Timestamp: ${this.timestamp}`,
+      `Error ID: ${this.errorId}`
+    ].filter(Boolean).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();
+  }
+};
 async function safeReadResponseBody(response) {
   try {
     if (response.headers.get("content-type")?.includes("application/json")) {
@@ -623,6 +582,74 @@ var apiCall = async (api, json) => {
   }
 };
 
+// ai/base.ts
+import crypto2 from "crypto";
+import { context, SpanKind } from "@opentelemetry/api";
+
+// trace/trace.ts
+var axSpanAttributes = {
+  // LLM
+  LLM_SYSTEM: "gen_ai.system",
+  LLM_OPERATION_NAME: "gen_ai.operation.name",
+  LLM_REQUEST_MODEL: "gen_ai.request.model",
+  LLM_REQUEST_MAX_TOKENS: "gen_ai.request.max_tokens",
+  LLM_REQUEST_TEMPERATURE: "gen_ai.request.temperature",
+  LLM_REQUEST_TOP_K: "gen_ai.request.top_k",
+  LLM_REQUEST_FREQUENCY_PENALTY: "gen_ai.request.frequency_penalty",
+  LLM_REQUEST_PRESENCE_PENALTY: "gen_ai.request.presence_penalty",
+  LLM_REQUEST_STOP_SEQUENCES: "gen_ai.request.stop_sequences",
+  LLM_REQUEST_LLM_IS_STREAMING: "gen_ai.request.llm_is_streaming",
+  LLM_REQUEST_TOP_P: "gen_ai.request.top_p",
+  LLM_USAGE_INPUT_TOKENS: "gen_ai.usage.input_tokens",
+  LLM_USAGE_OUTPUT_TOKENS: "gen_ai.usage.output_tokens",
+  LLM_USAGE_TOTAL_TOKENS: "gen_ai.usage.total_tokens",
+  LLM_USAGE_THOUGHTS_TOKENS: "gen_ai.usage.thoughts_tokens",
+  // Vector DB
+  DB_SYSTEM: "db.system",
+  DB_TABLE: "db.table",
+  DB_NAMESPACE: "db.namespace",
+  DB_ID: "db.id",
+  DB_QUERY_TEXT: "db.query.text",
+  DB_VECTOR: "db.vector",
+  DB_OPERATION_NAME: "db.operation.name",
+  DB_VECTOR_QUERY_TOP_K: "db.vector.query.top_k",
+  DB_QUERY_EMBEDDINGS: "db.query.embeddings",
+  DB_QUERY_RESULT: "db.query.result",
+  // Query Embeddings
+  DB_QUERY_EMBEDDINGS_VECTOR: "db.query.embeddings.vector",
+  // Query Result (canonical format)
+  DB_QUERY_RESULT_ID: "db.query.result.id",
+  DB_QUERY_RESULT_SCORE: "db.query.result.score",
+  DB_QUERY_RESULT_DISTANCE: "db.query.result.distance",
+  DB_QUERY_RESULT_METADATA: "db.query.result.metadata",
+  DB_QUERY_RESULT_VECTOR: "db.query.result.vector",
+  DB_QUERY_RESULT_DOCUMENT: "db.query.result.document"
+};
+var axSpanEvents = {
+  GEN_AI_USER_MESSAGE: "gen_ai.user.message",
+  GEN_AI_SYSTEM_MESSAGE: "gen_ai.system.message",
+  GEN_AI_ASSISTANT_MESSAGE: "gen_ai.assistant.message",
+  GEN_AI_TOOL_MESSAGE: "gen_ai.tool.message",
+  // For tool messages in request & response tool calls
+  GEN_AI_CHOICE: "gen_ai.choice",
+  GEN_AI_USAGE: "gen_ai.usage"
+};
+var AxLLMRequestTypeValues = /* @__PURE__ */ ((AxLLMRequestTypeValues2) => {
+  AxLLMRequestTypeValues2["COMPLETION"] = "completion";
+  AxLLMRequestTypeValues2["CHAT"] = "chat";
+  AxLLMRequestTypeValues2["RERANK"] = "rerank";
+  AxLLMRequestTypeValues2["UNKNOWN"] = "unknown";
+  return AxLLMRequestTypeValues2;
+})(AxLLMRequestTypeValues || {});
+var AxSpanKindValues = /* @__PURE__ */ ((AxSpanKindValues2) => {
+  AxSpanKindValues2["WORKFLOW"] = "workflow";
+  AxSpanKindValues2["TASK"] = "task";
+  AxSpanKindValues2["AGENT"] = "agent";
+  AxSpanKindValues2["TOOL"] = "tool";
+  AxSpanKindValues2["UNKNOWN"] = "unknown";
+  return AxSpanKindValues2;
+})(AxSpanKindValues || {});
+
 // util/transform.ts
 import {
   TransformStream as TransformStream4
@@ -1988,7 +2015,13 @@ var AxAIAnthropicImpl = class {
   };
   createChatResp = (resp) => {
     if (resp.type === "error") {
-      throw new Error(`Anthropic Chat API Error: ${resp.error.message}`);
+      throw new AxAIRefusalError(
+        resp.error.message,
+        void 0,
+        // model not specified in error response
+        void 0
+        // requestId not specified in error response
+      );
     }
     const finishReason = mapFinishReason(resp.stop_reason);
     const showThoughts = this.currentPromptConfig?.thinkingTokenBudget !== "none" && this.currentPromptConfig?.showThoughts !== false;
@@ -2044,7 +2077,13 @@ var AxAIAnthropicImpl = class {
     }
     if (resp.type === "error") {
       const { error } = resp;
-      throw new Error(error.message);
+      throw new AxAIRefusalError(
+        error.message,
+        void 0,
+        // model not specified in error event
+        void 0
+        // requestId not specified in error event
+      );
     }
     const index = 0;
     if (resp.type === "message_start") {
@@ -2672,6 +2711,9 @@ var AxAIOpenAIImpl = class {
       totalTokens: usage.total_tokens
     } : void 0;
     const results = choices.map((choice) => {
+      if (choice.message.refusal) {
+        throw new AxAIRefusalError(choice.message.refusal, resp.model, resp.id);
+      }
       const finishReason = mapFinishReason2(choice.finish_reason);
       const functionCalls = choice.message.tool_calls?.map(
         ({ id: id2, function: { arguments: params, name } }) => ({
@@ -2683,8 +2725,9 @@ var AxAIOpenAIImpl = class {
       return {
         index: choice.index,
         id: `${choice.index}`,
-        content: choice.message.content,
+        content: choice.message.content ?? void 0,
         thought: choice.message.reasoning_content,
+        annotations: choice.message.annotations,
         functionCalls,
         finishReason
       };
@@ -2711,11 +2754,16 @@ var AxAIOpenAIImpl = class {
         delta: {
           content,
           role,
+          refusal,
           tool_calls: toolCalls,
-          reasoning_content: thought
+          reasoning_content: thought,
+          annotations
         },
         finish_reason: oaiFinishReason
       }) => {
+        if (refusal) {
+          throw new AxAIRefusalError(refusal, void 0, id);
+        }
         const finishReason = mapFinishReason2(oaiFinishReason);
         const functionCalls = toolCalls?.map(({ id: _id, index: index2, function: { name, arguments: params } }) => {
           if (typeof _id === "string" && typeof index2 === "number" && !sstate.indexIdMap[index2]) {
@@ -2733,9 +2781,10 @@ var AxAIOpenAIImpl = class {
         }).filter((v) => v !== null);
         return {
           index,
-          content,
+          content: content ?? void 0,
           role,
           thought,
+          annotations,
           functionCalls,
           finishReason,
           id
@@ -3832,11 +3881,29 @@ var AxAIGoogleGeminiImpl = class {
             result.finishReason = "stop";
             break;
           case "SAFETY":
-            throw new Error("Finish reason: SAFETY");
+            throw new AxAIRefusalError(
+              "Content was blocked due to safety settings",
+              void 0,
+              // model not available in candidate
+              void 0
+              // requestId not available
+            );
           case "RECITATION":
-            throw new Error("Finish reason: RECITATION");
+            throw new AxAIRefusalError(
+              "Content was blocked due to recitation policy",
+              void 0,
+              // model not available in candidate
+              void 0
+              // requestId not available
+            );
           case "MALFORMED_FUNCTION_CALL":
-            throw new Error("Finish reason: MALFORMED_FUNCTION_CALL");
+            throw new AxAIRefusalError(
+              "Function call was malformed and blocked",
+              void 0,
+              // model not available in candidate
+              void 0
+              // requestId not available
+            );
         }
         if (!candidate.content || !candidate.content.parts) {
           return result;
@@ -4714,7 +4781,7 @@ var AxAIOpenAIResponsesImpl = class {
       switch (item.type) {
         case "message":
           currentResult.id = item.id;
-          currentResult.content = contentToText(item.content);
+          currentResult.content = contentToText(item.content, id);
           currentResult.finishReason = item.status === "completed" ? "stop" : "content_filter";
           break;
         case "reasoning":
@@ -4887,7 +4954,10 @@ var AxAIOpenAIResponsesImpl = class {
         switch (event.item.type) {
           case "message":
             baseResult.id = event.item.id;
-            baseResult.content = contentToText(event.item.content);
+            baseResult.content = contentToText(
+              event.item.content,
+              event.item.id
+            );
             break;
           case "function_call":
             baseResult.id = event.item.id;
@@ -5057,7 +5127,7 @@ var AxAIOpenAIResponsesImpl = class {
         break;
       case "response.content_part.added":
         baseResult.id = event.item_id;
-        baseResult.content = contentToText([event.part]);
+        baseResult.content = contentToText([event.part], event.item_id);
         break;
       case "response.output_text.delta":
         baseResult.id = event.item_id;
@@ -5242,11 +5312,13 @@ var AxAIOpenAIResponsesImpl = class {
     return [apiConfig, reqValue];
   }
 };
-var contentToText = (content) => {
-  return [
-    ...content.filter((c) => c.type === "output_text").map((c) => c.text),
-    ...content.filter((c) => c.type === "refusal").map((c) => c.refusal)
-  ].join("\n");
+var contentToText = (content, responseId) => {
+  const refusalContent = content.filter((c) => c.type === "refusal");
+  if (refusalContent.length > 0) {
+    const refusalMessage = refusalContent.map((c) => c.refusal).join("\n");
+    throw new AxAIRefusalError(refusalMessage, void 0, responseId);
+  }
+  return content.filter((c) => c.type === "output_text").map((c) => c.text).join("\n");
 };
 
 // ai/openai/responses_api_base.ts
@@ -5834,213 +5906,279 @@ import {
 
 // ai/validate.ts
 function axValidateChatRequestMessage(item) {
+  const value = (v) => JSON.stringify(v, null, 2);
   if (!item) {
-    throw new Error("Chat request message item cannot be null or undefined");
+    throw new Error(
+      `Chat request message item cannot be null or undefined, received: ${value(item)}`
+    );
   }
-  if (!item.role) {
-    throw new Error("Chat request message must have a role");
+  const role = item?.role;
+  if (!role) {
+    throw new Error(
+      `Chat request message must have a role, received: ${value(role)}`
+    );
   }
-  switch (item.role) {
-    case "system":
-      if (!item.content || item.content.trim() === "") {
+  switch (role) {
+    case "system": {
+      const systemItem = item;
+      if (!systemItem.content || systemItem.content.trim() === "") {
         throw new Error(
-          "System message content cannot be empty or whitespace-only"
+          `System message content cannot be empty or whitespace-only, received: ${value(systemItem.content)}`
         );
       }
       break;
-    case "user":
-      if (!item.content) {
-        throw new Error("User message content cannot be undefined");
+    }
+    case "user": {
+      const userItem = item;
+      if (!userItem.content) {
+        throw new Error(
+          `User message content cannot be undefined, received: ${value(userItem.content)}`
+        );
       }
-      if (typeof item.content === "string") {
-        if (item.content.trim() === "") {
+      if (typeof userItem.content === "string") {
+        if (userItem.content.trim() === "") {
           throw new Error(
-            "User message content cannot be empty or whitespace-only"
+            `User message content cannot be empty or whitespace-only, received: ${value(userItem.content)}`
           );
         }
-      } else if (Array.isArray(item.content)) {
-        if (item.content.length === 0) {
-          throw new Error("User message content array cannot be empty");
+      } else if (Array.isArray(userItem.content)) {
+        if (userItem.content.length === 0) {
+          throw new Error(
+            `User message content array cannot be empty, received: ${value(userItem.content)}`
+          );
         }
-        for (let index = 0; index < item.content.length; index++) {
-          const contentItem = item.content[index];
+        for (let index = 0; index < userItem.content.length; index++) {
+          const contentItem = userItem.content[index];
           if (!contentItem || typeof contentItem !== "object") {
             throw new Error(
-              `User message content item at index ${index} must be an object`
+              `User message content item at index ${index} must be an object, received: ${value(contentItem)}`
             );
           }
-          if (!contentItem.type) {
+          const contentType = contentItem?.type;
+          if (!contentType) {
             throw new Error(
-              `User message content item at index ${index} must have a type`
+              `User message content item at index ${index} must have a type, received: ${value(contentType)}`
             );
           }
-          switch (contentItem.type) {
-            case "text":
-              if (!contentItem.text || contentItem.text.trim() === "") {
+          switch (contentType) {
+            case "text": {
+              const textItem = contentItem;
+              if (!textItem.text || textItem.text.trim() === "") {
                 throw new Error(
-                  `User message text content at index ${index} cannot be empty or whitespace-only`
+                  `User message text content at index ${index} cannot be empty or whitespace-only, received: ${value(textItem.text)}`
                 );
               }
               break;
-            case "image":
-              if (!contentItem.image || contentItem.image.trim() === "") {
+            }
+            case "image": {
+              const imageItem = contentItem;
+              if (!imageItem.image || imageItem.image.trim() === "") {
                 throw new Error(
-                  `User message image content at index ${index} cannot be empty`
+                  `User message image content at index ${index} cannot be empty, received: ${value(imageItem.image)}`
                 );
               }
-              if (!contentItem.mimeType || contentItem.mimeType.trim() === "") {
+              if (!imageItem.mimeType || imageItem.mimeType.trim() === "") {
                 throw new Error(
-                  `User message image content at index ${index} must have a mimeType`
+                  `User message image content at index ${index} must have a mimeType, received: ${value(imageItem.mimeType)}`
                 );
               }
               break;
-            case "audio":
-              if (!contentItem.data || contentItem.data.trim() === "") {
+            }
+            case "audio": {
+              const audioItem = contentItem;
+              if (!audioItem.data || audioItem.data.trim() === "") {
                 throw new Error(
-                  `User message audio content at index ${index} cannot be empty`
+                  `User message audio content at index ${index} cannot be empty, received: ${value(audioItem.data)}`
                 );
               }
               break;
+            }
             default:
               throw new Error(
-                `User message content item at index ${index} has unsupported type: ${contentItem.type}`
+                `User message content item at index ${index} has unsupported type: ${value(contentType)}`
               );
           }
         }
       } else {
         throw new Error(
-          "User message content must be a string or array of content objects"
+          `User message content must be a string or array of content objects, received: ${value(userItem.content)}`
         );
       }
       break;
-    case "assistant":
-      if (!item.content && !item.functionCalls) {
+    }
+    case "assistant": {
+      const assistantItem = item;
+      if (!assistantItem.content && !assistantItem.functionCalls) {
         throw new Error(
-          "Assistant message must have either content or function calls"
+          `Assistant message must have either content or function calls, received content: ${value(assistantItem.content)}, functionCalls: ${value(assistantItem.functionCalls)}`
         );
       }
-      if (item.content && typeof item.content !== "string") {
-        throw new Error("Assistant message content must be a string");
+      if (assistantItem.content && typeof assistantItem.content !== "string") {
+        throw new Error(
+          `Assistant message content must be a string, received: ${value(assistantItem.content)}`
+        );
       }
-      if (item.functionCalls && !Array.isArray(item.functionCalls)) {
-        throw new Error("Assistant message function calls must be an array");
+      if (assistantItem.functionCalls && !Array.isArray(assistantItem.functionCalls)) {
+        throw new Error(
+          `Assistant message function calls must be an array, received: ${value(assistantItem.functionCalls)}`
+        );
       }
       break;
-    case "function":
-      if (!item.functionId || item.functionId.trim() === "") {
-        throw new Error("Function message must have a non-empty functionId");
+    }
+    case "function": {
+      const functionItem = item;
+      if (!functionItem.functionId || functionItem.functionId.trim() === "") {
+        throw new Error(
+          `Function message must have a non-empty functionId, received: ${value(functionItem.functionId)}`
+        );
       }
-      if (item.result === void 0 || item.result === null) {
-        throw new Error("Function message must have a result");
+      if (functionItem.result === void 0 || functionItem.result === null) {
+        throw new Error(
+          `Function message must have a result, received: ${value(functionItem.result)}`
+        );
       }
-      if (typeof item.result !== "string") {
-        throw new Error("Function message result must be a string");
+      if (typeof functionItem.result !== "string") {
+        throw new Error(
+          `Function message result must be a string, received: ${value(functionItem.result)}`
+        );
       }
       break;
+    }
     default:
-      throw new Error(
-        `Unsupported message role: ${item.role}`
-      );
+      throw new Error(`Unsupported message role: ${value(role)}`);
   }
 }
 function axValidateChatResponseResult(results) {
+  const value = (v) => JSON.stringify(v, null, 2);
   const resultsArray = Array.isArray(results) ? results : [results];
   if (resultsArray.length === 0) {
-    throw new Error("Chat response results cannot be empty");
+    throw new Error(
+      `Chat response results cannot be empty, received: ${value(resultsArray)}`
+    );
   }
   for (let arrayIndex = 0; arrayIndex < resultsArray.length; arrayIndex++) {
     const result = resultsArray[arrayIndex];
     if (!result) {
       throw new Error(
-        `Chat response result at index ${arrayIndex} cannot be null or undefined`
+        `Chat response result at index ${arrayIndex} cannot be null or undefined, received: ${value(result)}`
       );
     }
     if (typeof result.index !== "number") {
       throw new Error(
-        `Chat response result at index ${arrayIndex} must have a numeric index`
+        `Chat response result at index ${arrayIndex} must have a numeric index, received: ${value(result.index)}`
       );
     }
     if (result.index < 0) {
       throw new Error(
-        `Chat response result at index ${arrayIndex} must have a non-negative index`
+        `Chat response result at index ${arrayIndex} must have a non-negative index, received: ${value(result.index)}`
       );
     }
     if (!result.content && !result.thought && !result.functionCalls && !result.finishReason) {
       throw new Error(
-        `Chat response result at index ${arrayIndex} must have at least one of: content, thought, functionCalls, or finishReason`
+        `Chat response result at index ${arrayIndex} must have at least one of: content, thought, functionCalls, or finishReason, received: ${value({ content: result.content, thought: result.thought, functionCalls: result.functionCalls, finishReason: result.finishReason })}`
       );
     }
     if (result.content !== void 0 && typeof result.content !== "string") {
       throw new Error(
-        `Chat response result content at index ${arrayIndex} must be a string`
+        `Chat response result content at index ${arrayIndex} must be a string, received: ${value(result.content)}`
       );
     }
     if (result.thought !== void 0 && typeof result.thought !== "string") {
       throw new Error(
-        `Chat response result thought at index ${arrayIndex} must be a string`
+        `Chat response result thought at index ${arrayIndex} must be a string, received: ${value(result.thought)}`
       );
     }
     if (result.name !== void 0) {
       if (typeof result.name !== "string") {
         throw new Error(
-          `Chat response result name at index ${arrayIndex} must be a string`
+          `Chat response result name at index ${arrayIndex} must be a string, received: ${value(result.name)}`
         );
       }
       if (result.name.trim() === "") {
         throw new Error(
-          `Chat response result name at index ${arrayIndex} cannot be empty or whitespace-only`
+          `Chat response result name at index ${arrayIndex} cannot be empty or whitespace-only, received: ${value(result.name)}`
         );
       }
     }
+    if (result.annotations !== void 0) {
+      if (!Array.isArray(result.annotations)) {
+        throw new Error(
+          `Chat response result annotations at index ${arrayIndex} must be an array, received: ${value(result.annotations)}`
+        );
+      }
+      for (let i = 0; i < result.annotations.length; i++) {
+        const annotation = result.annotations[i];
+        if (!annotation || typeof annotation !== "object") {
+          throw new Error(
+            `Chat response result annotation at index ${arrayIndex}[${i}] must be an object, received: ${value(annotation)}`
+          );
+        }
+        if (annotation.type !== "url_citation") {
+          throw new Error(
+            `Chat response result annotation at index ${arrayIndex}[${i}] must have type 'url_citation', received: ${value(annotation.type)}`
+          );
+        }
+        if (!annotation.url_citation || typeof annotation.url_citation !== "object") {
+          throw new Error(
+            `Chat response result annotation at index ${arrayIndex}[${i}] must have a valid url_citation object, received: ${value(annotation.url_citation)}`
+          );
+        }
+        if (typeof annotation.url_citation.url !== "string") {
+          throw new Error(
+            `Chat response result annotation at index ${arrayIndex}[${i}] url_citation.url must be a string, received: ${value(annotation.url_citation.url)}`
+          );
+        }
+      }
+    }
     if (result.id !== void 0) {
       if (typeof result.id !== "string") {
         throw new Error(
-          `Chat response result id at index ${arrayIndex} must be a string`
+          `Chat response result id at index ${arrayIndex} must be a string, received: ${value(result.id)}`
         );
       }
       if (result.id.trim() === "") {
         throw new Error(
-          `Chat response result id at index ${arrayIndex} cannot be empty or whitespace-only`
+          `Chat response result id at index ${arrayIndex} cannot be empty or whitespace-only, received: ${value(result.id)}`
         );
       }
     }
     if (result.functionCalls !== void 0) {
       if (!Array.isArray(result.functionCalls)) {
         throw new Error(
-          `Chat response result functionCalls at index ${arrayIndex} must be an array`
+          `Chat response result functionCalls at index ${arrayIndex} must be an array, received: ${value(result.functionCalls)}`
         );
       }
       for (let callIndex = 0; callIndex < result.functionCalls.length; callIndex++) {
         const functionCall = result.functionCalls[callIndex];
         if (!functionCall) {
           throw new Error(
-            `Function call at index ${callIndex} in result ${arrayIndex} cannot be null or undefined`
+            `Function call at index ${callIndex} in result ${arrayIndex} cannot be null or undefined, received: ${value(functionCall)}`
           );
         }
         if (!functionCall.id || typeof functionCall.id !== "string" || functionCall.id.trim() === "") {
           throw new Error(
-            `Function call at index ${callIndex} in result ${arrayIndex} must have a non-empty string id`
+            `Function call at index ${callIndex} in result ${arrayIndex} must have a non-empty string id, received: ${value(functionCall.id)}`
           );
         }
         if (functionCall.type !== "function") {
           throw new Error(
-            `Function call at index ${callIndex} in result ${arrayIndex} must have type 'function'`
+            `Function call at index ${callIndex} in result ${arrayIndex} must have type 'function', received: ${value(functionCall.type)}`
           );
         }
         if (!functionCall.function) {
           throw new Error(
-            `Function call at index ${callIndex} in result ${arrayIndex} must have a function object`
+            `Function call at index ${callIndex} in result ${arrayIndex} must have a function object, received: ${value(functionCall.function)}`
           );
         }
         if (!functionCall.function.name || typeof functionCall.function.name !== "string" || functionCall.function.name.trim() === "") {
           throw new Error(
-            `Function call at index ${callIndex} in result ${arrayIndex} must have a non-empty function name`
+            `Function call at index ${callIndex} in result ${arrayIndex} must have a non-empty function name, received: ${value(functionCall.function.name)}`
           );
         }
         if (functionCall.function.params !== void 0) {
           if (typeof functionCall.function.params !== "string" && typeof functionCall.function.params !== "object") {
             throw new Error(
-              `Function call params at index ${callIndex} in result ${arrayIndex} must be a string or object`
+              `Function call params at index ${callIndex} in result ${arrayIndex} must be a string or object, received: ${value(functionCall.function.params)}`
             );
           }
         }
@@ -6056,7 +6194,7 @@ function axValidateChatResponseResult(results) {
       ];
       if (!validFinishReasons.includes(result.finishReason)) {
         throw new Error(
-          `Chat response result finishReason at index ${arrayIndex} must be one of: ${validFinishReasons.join(", ")}`
+          `Chat response result finishReason at index ${arrayIndex} must be one of: ${validFinishReasons.join(", ")}, received: ${value(result.finishReason)}`
         );
       }
     }
@@ -16113,6 +16251,198 @@ var AxEvalUtil = {
   novelF1ScoreOptimized
 };
 
+// flow/flow.ts
+var AxFlow = class extends AxProgramWithSignature {
+  nodes = /* @__PURE__ */ new Map();
+  flowDefinition = [];
+  nodeGenerators = /* @__PURE__ */ new Map();
+  loopStack = [];
+  constructor(signature = "userInput:string -> flowOutput:string") {
+    super(signature);
+  }
+  /**
+   * Declares a reusable computational node and its input/output signature.
+   *
+   * @param name - The name of the node
+   * @param signature - An object where the key is a string representation of inputs
+   *                   and the value is an object representing outputs
+   * @returns this (for chaining)
+   *
+   * @example
+   * ```typescript
+   * flow.node('summarizer', { 'text:string': { summary: f.string() } })
+   * ```
+   */
+  node(name, signature) {
+    const [inputSignature, outputSignature] = Object.entries(signature)[0] ?? [
+      "",
+      {}
+    ];
+    if (!inputSignature || !outputSignature) {
+      throw new Error(
+        `Invalid signature for node '${name}': signature must have at least one input->output mapping`
+      );
+    }
+    const outputFields = Object.entries(outputSignature).map(([key, value]) => {
+      if (typeof value === "object" && value !== null && "type" in value) {
+        const fieldType = value;
+        let fieldString = `${key}:`;
+        if (fieldType.isOptional) {
+          const colonIndex = fieldString.lastIndexOf(":");
+          fieldString = fieldString.slice(0, colonIndex) + "?" + fieldString.slice(colonIndex);
+        }
+        if (fieldType.isInternal) {
+          const colonIndex = fieldString.lastIndexOf(":");
+          fieldString = fieldString.slice(0, colonIndex) + "!" + fieldString.slice(colonIndex);
+        }
+        fieldString += fieldType.type;
+        if (fieldType.isArray) {
+          fieldString += "[]";
+        }
+        if (fieldType.type === "class" && fieldType.options) {
+          fieldString += ` "${fieldType.options.join(", ")}"`;
+        }
+        if (fieldType.description && (fieldType.type !== "class" || !fieldType.options)) {
+          fieldString += ` "${fieldType.description}"`;
+        }
+        return fieldString;
+      }
+      return `${key}:string`;
+    }).join(", ");
+    const signatureString = `${inputSignature} -> ${outputFields}`;
+    this.nodes.set(name, {
+      inputs: { [inputSignature]: true },
+      outputs: outputSignature
+    });
+    this.nodeGenerators.set(name, new AxGen(signatureString));
+    return this;
+  }
+  /**
+   * Applies a synchronous transformation to the state object.
+   *
+   * @param transform - Function that takes the current state and returns a new state
+   * @returns this (for chaining)
+   *
+   * @example
+   * ```typescript
+   * flow.map(state => ({ ...state, processedText: state.text.toLowerCase() }))
+   * ```
+   */
+  map(transform) {
+    this.flowDefinition.push((state) => {
+      return transform(state);
+    });
+    return this;
+  }
+  /**
+   * Executes a previously defined node.
+   *
+   * @param nodeName - The name of the node to execute (must exist in the nodes map)
+   * @param mapping - Function that takes the current state and returns the input object required by the node
+   * @param dynamicContext - Optional object to override the AI service or options for this specific step
+   * @returns this (for chaining)
+   *
+   * @example
+   * ```typescript
+   * flow.execute('summarizer', state => ({ text: state.originalText }), { ai: cheapAI })
+   * ```
+   */
+  execute(nodeName, mapping, dynamicContext) {
+    if (!this.nodes.has(nodeName)) {
+      throw new Error(
+        `Node '${nodeName}' not found. Make sure to define it with .node() first.`
+      );
+    }
+    const nodeGenerator = this.nodeGenerators.get(nodeName);
+    if (!nodeGenerator) {
+      throw new Error(`Node generator for '${nodeName}' not found.`);
+    }
+    this.flowDefinition.push(async (state, context3) => {
+      const ai = dynamicContext?.ai ?? context3.mainAi;
+      const options = dynamicContext?.options ?? context3.mainOptions;
+      const nodeInputs = mapping(state);
+      const result = await nodeGenerator.forward(ai, nodeInputs, options);
+      return {
+        ...state,
+        [`${nodeName}Result`]: result
+      };
+    });
+    return this;
+  }
+  /**
+   * Marks the beginning of a loop block.
+   *
+   * @param condition - Function that takes the current state and returns a boolean
+   * @returns this (for chaining)
+   *
+   * @example
+   * ```typescript
+   * flow.while(state => state.iterations < 3)
+   *   .map(state => ({ ...state, iterations: (state.iterations || 0) + 1 }))
+   *   .endWhile()
+   * ```
+   */
+  while(condition) {
+    const loopStartIndex = this.flowDefinition.length;
+    this.loopStack.push(loopStartIndex);
+    const placeholderStep = Object.assign(
+      (state) => state,
+      {
+        _condition: condition,
+        _isLoopStart: true
+      }
+    );
+    this.flowDefinition.push(placeholderStep);
+    return this;
+  }
+  /**
+   * Marks the end of a loop block.
+   *
+   * @returns this (for chaining)
+   */
+  endWhile() {
+    if (this.loopStack.length === 0) {
+      throw new Error("endWhile() called without matching while()");
+    }
+    const loopStartIndex = this.loopStack.pop();
+    const placeholderStep = this.flowDefinition[loopStartIndex];
+    if (!placeholderStep || !("_isLoopStart" in placeholderStep)) {
+      throw new Error("Loop start step not found or invalid");
+    }
+    const condition = placeholderStep._condition;
+    const loopBodySteps = this.flowDefinition.splice(loopStartIndex + 1);
+    this.flowDefinition[loopStartIndex] = async (state, context3) => {
+      let currentState = state;
+      while (condition(currentState)) {
+        for (const step of loopBodySteps) {
+          currentState = await step(currentState, context3);
+        }
+      }
+      return currentState;
+    };
+    return this;
+  }
+  /**
+   * Executes the flow with the given AI service and input values.
+   *
+   * @param ai - The AI service to use as the default for all steps
+   * @param values - The input values for the flow
+   * @param options - Optional forward options to use as defaults
+   * @returns Promise that resolves to the final output
+   */
+  async forward(ai, values, options) {
+    let state = { ...values };
+    const context3 = {
+      mainAi: ai,
+      mainOptions: options
+    };
+    for (const step of this.flowDefinition) {
+      state = await step(state, context3);
+    }
+    return state;
+  }
+};
+
 // ../../node_modules/uuid/dist/esm-node/rng.js
 import crypto4 from "crypto";
 var rnds8Pool = new Uint8Array(256);
@@ -16649,6 +16979,7 @@ export {
   AxAIOpenAIResponsesBase,
   AxAIOpenAIResponsesImpl,
   AxAIOpenAIResponsesModel,
+  AxAIRefusalError,
   AxAIReka,
   AxAIRekaModel,
   AxAIServiceAbortedError,
@@ -16680,6 +17011,7 @@ export {
   AxDockerSession,
   AxEmbeddingAdapter,
   AxEvalUtil,
+  AxFlow,
   AxFunctionError,
   AxFunctionProcessor,
   AxGen,