@ax-llm/ax 11.0.67 → 12.0.1

package/index.js

@@ -1098,6 +1098,7 @@ var AxBaseAI = class {
     if (chatReq.functions && chatReq.functions.length > 0) {
       functions = chatReq.functions.map((fn2) => this.cleanupFunctionSchema(fn2));
     }
+    validateChatPrompt(chatReq.chatPrompt);
     const req = {
       ...chatReq,
       model,
@@ -1439,6 +1440,31 @@ function setChatResponseEvents(res, span, excludeContentFromTrace) {
     });
   }
 }
+function validateAxMessageArray(values) {
+  for (let i = 0; i < values.length; i++) {
+    const message = values[i];
+    if (!message || typeof message !== "object") {
+      throw new Error(
+        `AxMessage array validation failed: Item at index ${i} is not a valid message object`
+      );
+    }
+    if ("content" in message && typeof message.content === "string" && message.content.trim() === "") {
+      throw new Error(
+        `AxMessage array validation failed: Item at index ${i} has empty content`
+      );
+    }
+  }
+}
+function validateChatPrompt(chatPrompt) {
+  for (let i = 0; i < chatPrompt.length; i++) {
+    const message = chatPrompt[i];
+    if (message && "content" in message && typeof message.content === "string" && message.content.trim() === "") {
+      throw new Error(
+        `Chat prompt validation failed: Message at index ${i} has empty content`
+      );
+    }
+  }
+}
 function validateModels(models) {
   const keys = /* @__PURE__ */ new Set();
   for (const model of models) {
@@ -3215,7 +3241,9 @@ var AxAIGoogleGeminiImpl = class {
     const contents = req.chatPrompt.filter((p) => p.role !== "system").map((msg, i) => {
       switch (msg.role) {
         case "user": {
-          const parts = Array.isArray(msg.content) ? msg.content.map((c, i2) => {
+          const parts = Array.isArray(
+            msg.content
+          ) ? msg.content.map((c, i2) => {
             switch (c.type) {
               case "text":
                 return { text: c.text };
@@ -3276,12 +3304,14 @@ var AxAIGoogleGeminiImpl = class {
             }
           ];
           return {
-            role: "function",
+            role: "model",
             parts
           };
         }
         default:
-          throw new Error("Invalid role");
+          throw new Error(
+            `Invalid role: ${JSON.stringify(msg)} (index: ${i})`
+          );
       }
     });
     let tools = [];
@@ -6560,6 +6590,11 @@ var extractValues = (sig, values, content) => {
   const xstate = { extractedFields: [], streamedIndex: {}, s: -1 };
   streamingExtractValues(sig, values, xstate, content);
   streamingExtractFinalValue(sig, values, xstate, content);
+  for (const field of sig.getOutputFields()) {
+    if (field.isInternal) {
+      delete values[field.name];
+    }
+  }
 };
 var checkMissingRequiredFields = (xstate, values, currentIndex) => {
   const missingFields = [];
@@ -7285,93 +7320,218 @@ var AxInstanceRegistry = class {
 // dsp/sig.ts
 import { createHash } from "crypto";
 
+// dsp/globals.ts
+var axGlobals = {
+  signatureStrict: true
+  // Controls reservedNames enforcement in signature parsing/validation
+};
+
 // dsp/parser.ts
+var SignatureValidationError = class extends Error {
+  constructor(message, position, context3, suggestion) {
+    super(message);
+    this.position = position;
+    this.context = context3;
+    this.suggestion = suggestion;
+    this.name = "SignatureValidationError";
+  }
+};
 var SignatureParser = class {
   input;
   position;
   currentFieldName = null;
+  currentSection = "description";
   constructor(input) {
-    this.input = input;
+    this.input = input.trim();
     this.position = 0;
+    if (!this.input) {
+      throw new SignatureValidationError(
+        "Empty signature provided",
+        0,
+        "",
+        'A signature must contain at least input and output fields separated by "->". Example: "userQuery:string -> aiResponse:string"'
+      );
+    }
   }
   parse() {
     try {
       this.skipWhitespace();
       const optionalDesc = this.parseParsedString();
       this.skipWhitespace();
+      this.currentSection = "inputs";
       const inputs = this.parseFieldList(
         this.parseInputField.bind(this),
         "input"
       );
       this.skipWhitespace();
       if (this.position >= this.input.length) {
-        throw new Error(
-          'Incomplete signature: Missing output section. Expected "->" followed by output fields'
+        throw new SignatureValidationError(
+          "Incomplete signature: Missing output section",
+          this.position,
+          this.getErrorContext(),
+          'Add "->" followed by output fields. Example: "-> responseText:string"'
         );
       }
-      this.expect("->");
+      this.expectArrow();
       this.skipWhitespace();
       if (this.position >= this.input.length) {
-        throw new Error(
-          'Incomplete signature: No output fields specified after "->"'
+        throw new SignatureValidationError(
+          'Incomplete signature: No output fields specified after "->"',
+          this.position,
+          this.getErrorContext(),
+          'Add at least one output field. Example: "-> responseText:string"'
         );
       }
+      this.currentSection = "outputs";
       const outputs = this.parseFieldList(
         this.parseOutputField.bind(this),
         "output"
       );
+      this.skipWhitespace();
+      if (this.position < this.input.length) {
+        const remaining = this.input.slice(this.position);
+        throw new SignatureValidationError(
+          `Unexpected content after signature: "${remaining}"`,
+          this.position,
+          this.getErrorContext(),
+          "Remove any extra content after the output fields"
+        );
+      }
+      this.validateParsedSignature({
+        desc: optionalDesc?.trim(),
+        inputs,
+        outputs
+      });
       return {
         desc: optionalDesc?.trim(),
         inputs,
         outputs
       };
     } catch (error) {
+      if (error instanceof SignatureValidationError) {
+        throw error;
+      }
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      const context3 = this.getErrorContext();
-      throw new Error(`${errorMessage}
-${context3}`);
+      throw new SignatureValidationError(
+        errorMessage,
+        this.position,
+        this.getErrorContext()
+      );
+    }
+  }
+  validateParsedSignature(signature) {
+    const inputNames = /* @__PURE__ */ new Set();
+    for (const field of signature.inputs) {
+      if (inputNames.has(field.name)) {
+        throw new SignatureValidationError(
+          `Duplicate input field name: "${field.name}"`,
+          0,
+          "",
+          "Each field name must be unique within the signature"
+        );
+      }
+      inputNames.add(field.name);
+    }
+    const outputNames = /* @__PURE__ */ new Set();
+    for (const field of signature.outputs) {
+      if (outputNames.has(field.name)) {
+        throw new SignatureValidationError(
+          `Duplicate output field name: "${field.name}"`,
+          0,
+          "",
+          "Each field name must be unique within the signature"
+        );
+      }
+      outputNames.add(field.name);
+    }
+    for (const outputField of signature.outputs) {
+      if (inputNames.has(outputField.name)) {
+        throw new SignatureValidationError(
+          `Field name "${outputField.name}" appears in both inputs and outputs`,
+          0,
+          "",
+          "Use different names for input and output fields to avoid confusion"
+        );
+      }
+    }
+    if (signature.inputs.length === 0) {
+      throw new SignatureValidationError(
+        "Signature must have at least one input field",
+        0,
+        "",
+        'Add an input field before "->". Example: "userInput:string -> ..."'
+      );
+    }
+    if (signature.outputs.length === 0) {
+      throw new SignatureValidationError(
+        "Signature must have at least one output field",
+        0,
+        "",
+        'Add an output field after "->". Example: "... -> responseText:string"'
+      );
     }
   }
   getErrorContext() {
-    const start = Math.max(0, this.position - 20);
-    const end = Math.min(this.input.length, this.position + 20);
+    const start = Math.max(0, this.position - 25);
+    const end = Math.min(this.input.length, this.position + 25);
     const before = this.input.slice(start, this.position);
     const after = this.input.slice(this.position, end);
     const pointer = " ".repeat(before.length) + "^";
-    return `Near position ${this.position}:
-${before}${after}
-${pointer}`;
+    const lines = [
+      `Position ${this.position} in signature:`,
+      `"${before}${after}"`,
+      ` ${pointer}`
+    ];
+    return lines.join("\n");
   }
   parseFieldList(parseFieldFn, section) {
     const fields = [];
     this.skipWhitespace();
     if (this.position >= this.input.length) {
-      throw new Error(`Empty ${section} section: Expected at least one field`);
+      throw new SignatureValidationError(
+        `Empty ${section} section: Expected at least one field`,
+        this.position,
+        this.getErrorContext(),
+        `Add a ${section} field. Example: ${section === "input" ? "userInput:string" : "responseText:string"}`
+      );
     }
     try {
       fields.push(parseFieldFn());
     } catch (error) {
-      throw new Error(
-        `Invalid first ${section} field: ${error instanceof Error ? error.message : "Unknown error"}`
+      if (error instanceof SignatureValidationError) {
+        throw error;
+      }
+      throw new SignatureValidationError(
+        `Invalid first ${section} field: ${error instanceof Error ? error.message : "Unknown error"}`,
+        this.position,
+        this.getErrorContext()
       );
     }
     this.skipWhitespace();
     while (this.position < this.input.length) {
-      if (this.input[this.position] === "-" && this.input[this.position + 1] === ">") {
+      if (this.input[this.position] === "-" && this.position + 1 < this.input.length && this.input[this.position + 1] === ">") {
         break;
       }
       if (this.match(",")) {
         this.skipWhitespace();
         if (this.position >= this.input.length) {
-          throw new Error(
-            `Unexpected end of input after comma in ${section} section`
+          throw new SignatureValidationError(
+            `Unexpected end of input after comma in ${section} section`,
+            this.position,
+            this.getErrorContext(),
+            `Add another ${section} field after the comma`
           );
         }
         try {
           fields.push(parseFieldFn());
         } catch (error) {
-          throw new Error(
-            `Invalid ${section} field after comma: ${error instanceof Error ? error.message : "Unknown error"}`
+          if (error instanceof SignatureValidationError) {
+            throw error;
+          }
+          throw new SignatureValidationError(
+            `Invalid ${section} field after comma: ${error instanceof Error ? error.message : "Unknown error"}`,
+            this.position,
+            this.getErrorContext()
           );
         }
         this.skipWhitespace();
@@ -7388,6 +7548,7 @@ ${pointer}`;
     this.skipWhitespace();
     const name = this.parseParsedIdentifier();
     this.currentFieldName = name;
+    this.validateFieldName(name, "input");
     let isOptional = void 0;
     while (true) {
       if (this.match("?")) {
@@ -7395,8 +7556,11 @@ ${pointer}`;
         continue;
       }
       if (this.match("!")) {
-        throw new Error(
-          `Input field "${name}" does not support the internal marker "!"`
+        throw new SignatureValidationError(
+          `Input field "${name}" cannot use the internal marker "!"`,
+          this.position - 1,
+          this.getErrorContext(),
+          "Internal markers (!) are only allowed on output fields"
         );
       }
       break;
@@ -7406,17 +7570,33 @@ ${pointer}`;
     if (this.match(":")) {
       this.skipWhitespace();
       if (/^class\b/.test(this.input.slice(this.position))) {
-        throw new Error(
-          `Input field "${name}" does not support the "class" type`
+        throw new SignatureValidationError(
+          `Input field "${name}" cannot use the "class" type`,
+          this.position,
+          this.getErrorContext(),
+          'Class types are only allowed on output fields. Use "string" type for input classifications'
         );
       } else {
         try {
           const typeName = this.parseTypeNotClass();
           const isArray = this.match("[]");
           type = { name: typeName, isArray };
+          if ((typeName === "image" || typeName === "audio") && isArray) {
+            throw new SignatureValidationError(
+              `Input field "${name}": Arrays of ${typeName} are not supported`,
+              this.position,
+              this.getErrorContext(),
+              `Use a single ${typeName} type instead: "${typeName}"`
+            );
+          }
         } catch (error) {
-          throw new Error(
-            `Input field "${name}": ${error instanceof Error ? error.message : "Unknown error"}`
+          if (error instanceof SignatureValidationError) {
+            throw error;
+          }
+          throw new SignatureValidationError(
+            `Input field "${name}": ${error instanceof Error ? error.message : "Unknown error"}`,
+            this.position,
+            this.getErrorContext()
           );
         }
       }
@@ -7437,6 +7617,7 @@ ${pointer}`;
     this.skipWhitespace();
     const name = this.parseParsedIdentifier();
     this.currentFieldName = name;
+    this.validateFieldName(name, "output");
     let isOptional = false;
     let isInternal = false;
     while (true) {
@@ -7459,25 +7640,86 @@ ${pointer}`;
         this.skipWhitespace();
         const classNamesString = this.parseParsedString();
         if (!classNamesString) {
-          throw new Error(
-            `Output field "${name}": Expected class names in quotes after "class" type. Example: class "MyClass1, MyClass2"`
+          throw new SignatureValidationError(
+            `Output field "${name}": Missing class options after "class" type`,
+            this.position,
+            this.getErrorContext(),
+            'Add class names in quotes. Example: class "positive, negative, neutral"'
           );
         }
         const options = classNamesString.split(/[,\s]+/).map((s2) => s2.trim()).filter((s2) => s2.length > 0);
         if (options.length === 0) {
-          throw new Error(
-            `Output field "${name}": Empty class list provided. At least one class name is required`
+          throw new SignatureValidationError(
+            `Output field "${name}": Empty class list provided`,
+            this.position,
+            this.getErrorContext(),
+            'Provide at least one class option. Example: "positive, negative"'
           );
         }
+        if (options.length === 1) {
+          throw new SignatureValidationError(
+            `Output field "${name}": Class type needs at least 2 options`,
+            this.position,
+            this.getErrorContext(),
+            'Add more class options or use "string" type instead. Example: "positive, negative, neutral"'
+          );
+        }
+        for (const option of options) {
+          if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(option)) {
+            throw new SignatureValidationError(
+              `Output field "${name}": Invalid class option "${option}"`,
+              this.position,
+              this.getErrorContext(),
+              "Class options must start with a letter and contain only letters, numbers, underscores, or hyphens"
+            );
+          }
+        }
         type = { name: "class", isArray, options };
       } else {
         try {
           const typeName = this.parseTypeNotClass();
           const isArray = this.match("[]");
           type = { name: typeName, isArray };
+          if (typeName === "image" && isArray) {
+            throw new SignatureValidationError(
+              `Output field "${name}": Arrays of images are not supported`,
+              this.position,
+              this.getErrorContext(),
+              'Use a single image type instead: "image"'
+            );
+          }
+          if (typeName === "audio" && isArray) {
+            throw new SignatureValidationError(
+              `Output field "${name}": Arrays of audio are not supported`,
+              this.position,
+              this.getErrorContext(),
+              'Use a single audio type instead: "audio"'
+            );
+          }
+          if (typeName === "image") {
+            throw new SignatureValidationError(
+              `Output field "${name}": Image type is not supported in output fields`,
+              this.position,
+              this.getErrorContext(),
+              "Image types can only be used in input fields"
+            );
+          }
+          if (typeName === "audio") {
+            throw new SignatureValidationError(
+              `Output field "${name}": Audio type is not supported in output fields`,
+              this.position,
+              this.getErrorContext(),
+              "Audio types can only be used in input fields"
+            );
+          }
         } catch (error) {
-          throw new Error(
-            `Output field "${name}": ${error instanceof Error ? error.message : "Unknown error"}`
+          if (error instanceof SignatureValidationError) {
+            throw error;
+          }
+          throw new SignatureValidationError(
+            `Output field "${name}": ${error instanceof Error ? error.message : "Unknown error"}`,
+            this.position,
+            this.getErrorContext()
           );
         }
       }
@@ -7492,6 +7734,69 @@ ${pointer}`;
       isInternal
     };
   }
+  validateFieldName(name, fieldType) {
+    if (axGlobals.signatureStrict) {
+      const reservedNames = [
+        "text",
+        "object",
+        "image",
+        "string",
+        "number",
+        "boolean",
+        "json",
+        "array",
+        "datetime",
+        "date",
+        "time",
+        "type",
+        "class",
+        "input",
+        "output",
+        "data",
+        "value",
+        "result",
+        "response",
+        "request",
+        "item",
+        "element"
+      ];
+      if (reservedNames.includes(name.toLowerCase())) {
+        const suggestions = fieldType === "input" ? ["userInput", "questionText", "documentContent", "messageText"] : ["responseText", "analysisResult", "categoryType", "summaryText"];
+        throw new SignatureValidationError(
+          `Field name "${name}" is too generic`,
+          this.position,
+          this.getErrorContext(),
+          `Use a more descriptive name. Examples: ${suggestions.join(", ")}`
+        );
+      }
+    }
+    const camelCaseRegex = /^[a-z][a-zA-Z0-9]*$/;
+    const snakeCaseRegex = /^[a-z]+(_[a-z0-9]+)*$/;
+    if (!camelCaseRegex.test(name) && !snakeCaseRegex.test(name)) {
+      throw new SignatureValidationError(
+        `Invalid field name "${name}"`,
+        this.position,
+        this.getErrorContext(),
+        'Field names must be in camelCase (e.g., "userInput") or snake_case (e.g., "user_input")'
+      );
+    }
+    if (name.length < 2) {
+      throw new SignatureValidationError(
+        `Field name "${name}" is too short`,
+        this.position,
+        this.getErrorContext(),
+        "Field names must be at least 2 characters long"
+      );
+    }
+    if (name.length > 50) {
+      throw new SignatureValidationError(
+        `Field name "${name}" is too long (${name.length} characters)`,
+        this.position,
+        this.getErrorContext(),
+        "Field names should be 50 characters or less"
+      );
+    }
+  }
   parseTypeNotClass() {
     const types = [
       "string",
@@ -7506,13 +7811,42 @@ ${pointer}`;
     ];
     const foundType = types.find((type) => this.match(type));
     if (!foundType) {
-      const currentWord = this.input.slice(this.position).match(/^\w+/)?.[0] || "empty";
-      throw new Error(
-        `Invalid type "${currentWord}". Expected one of: ${types.join(", ")}`
+      const currentWord = this.input.slice(this.position).match(/^\w+/)?.[0] || "";
+      const suggestion = this.suggestType(currentWord);
+      const baseMessage = `Invalid type "${currentWord || "empty"}"`;
+      const suggestionPart = suggestion ? `. Did you mean "${suggestion}"?` : "";
+      const fullMessage = `${baseMessage}${suggestionPart}`;
+      throw new SignatureValidationError(
+        fullMessage,
+        this.position,
+        this.getErrorContext(),
+        `Expected one of: ${types.join(", ")}`
       );
     }
     return foundType;
   }
+  suggestType(input) {
+    const suggestions = {
+      str: "string",
+      text: "string",
+      int: "number",
+      integer: "number",
+      float: "number",
+      double: "number",
+      bool: "boolean",
+      object: "json",
+      dict: "json",
+      timestamp: "datetime",
+      time: "datetime",
+      img: "image",
+      picture: "image",
+      sound: "audio",
+      voice: "audio",
+      classification: "class",
+      category: "class"
+    };
+    return suggestions[input.toLowerCase()] || null;
+  }
   parseParsedIdentifier() {
     this.skipWhitespace();
     const match = /^[a-zA-Z_][a-zA-Z_0-9]*/.exec(
@@ -7523,9 +7857,28 @@ ${pointer}`;
       return match[0];
     }
     const invalidMatch = /^\S+/.exec(this.input.slice(this.position));
-    const invalidId = invalidMatch ? invalidMatch[0] : "empty";
-    throw new Error(
-      `Invalid identifier "${invalidId}". Identifiers must start with a letter or underscore and contain only letters, numbers, or underscores`
+    const invalidId = invalidMatch ? invalidMatch[0] : "";
+    if (invalidId === "") {
+      throw new SignatureValidationError(
+        "Expected field name but found end of input",
+        this.position,
+        this.getErrorContext(),
+        "Add a field name. Field names must start with a letter or underscore"
+      );
+    }
+    if (/^\d/.test(invalidId)) {
+      throw new SignatureValidationError(
+        `Invalid field name "${invalidId}" - cannot start with a number`,
+        this.position,
+        this.getErrorContext(),
+        'Field names must start with a letter or underscore. Example: "userInput" or "_internal"'
+      );
+    }
+    throw new SignatureValidationError(
+      `Invalid field name "${invalidId}"`,
+      this.position,
+      this.getErrorContext(),
+      "Field names must start with a letter or underscore and contain only letters, numbers, or underscores"
     );
   }
   parseParsedString() {
@@ -7534,7 +7887,7 @@ ${pointer}`;
       if (this.match(quoteChar)) {
         let content = "";
         let escaped = false;
-        let startPos = this.position;
+        const startPos = this.position - 1;
         while (this.position < this.input.length) {
           const char = this.input[this.position];
           this.position++;
@@ -7549,9 +7902,15 @@ ${pointer}`;
             content += char;
           }
         }
-        const partialString = this.input.slice(startPos, this.position);
-        throw new Error(
-          `Unterminated string starting at position ${startPos}: "${partialString}..."`
+        const partialString = this.input.slice(
+          startPos,
+          Math.min(this.position, startPos + 20)
+        );
+        throw new SignatureValidationError(
+          `Unterminated string starting at position ${startPos}`,
+          startPos,
+          this.getErrorContext(),
+          `Add closing ${quoteChar} to complete the string: ${partialString}${quoteChar}`
         );
       }
     }
@@ -7579,11 +7938,15 @@ ${pointer}`;
     }
     return false;
   }
-  expect(str) {
-    if (!this.match(str)) {
+  expectArrow() {
+    if (!this.match("->")) {
       const found = this.input.slice(this.position, this.position + 10);
-      throw new Error(
-        `Expected "${str}" but found "${found}..." at position ${this.position}`
+      const suggestion = found.includes(">") ? 'Use "->" (dash followed by greater-than)' : found.includes("-") ? 'Add ">" after the dash' : 'Add "->" to separate input and output fields';
+      throw new SignatureValidationError(
+        `Expected "->" but found "${found}..."`,
+        this.position,
+        this.getErrorContext(),
+        suggestion
       );
     }
   }
@@ -7594,6 +7957,14 @@ function parseSignature(input) {
 }
 
 // dsp/sig.ts
+var AxSignatureValidationError = class extends Error {
+  constructor(message, fieldName, suggestion) {
+    super(message);
+    this.fieldName = fieldName;
+    this.suggestion = suggestion;
+    this.name = "AxSignatureValidationError";
+  }
+};
 var AxSignature = class _AxSignature {
   description;
   inputFields;
@@ -7613,8 +7984,18 @@ var AxSignature = class _AxSignature {
       try {
         sig = parseSignature(signature);
       } catch (e) {
-        throw new Error(
-          `Invalid Signature: ${e.message} (${signature})`
+        if (e instanceof Error) {
+          const suggestion = "suggestion" in e && typeof e.suggestion === "string" ? e.suggestion : 'Please check the signature format. Example: "userInput:string -> responseText:string"';
+          throw new AxSignatureValidationError(
+            `Invalid Signature: ${e.message}`,
+            void 0,
+            suggestion
+          );
+        }
+        throw new AxSignatureValidationError(
+          `Invalid Signature: ${signature}`,
+          void 0,
+          'Please check the signature format. Example: "userInput:string -> responseText:string"'
         );
       }
       this.description = sig.desc;
@@ -7632,12 +8013,20 @@ var AxSignature = class _AxSignature {
       this.sigHash = signature.hash();
       this.sigString = signature.toString();
     } else {
-      throw new Error("invalid signature argument: " + signature);
+      throw new AxSignatureValidationError(
+        "Invalid signature argument type",
+        void 0,
+        "Signature must be a string or another AxSignature instance"
+      );
     }
   }
   parseParsedField = (field) => {
     if (!field.name || field.name.length === 0) {
-      throw new Error("Field name is required.");
+      throw new AxSignatureValidationError(
+        "Field name is required",
+        field.name,
+        'Every field must have a descriptive name. Example: "userInput", "responseText"'
+      );
     }
     const title = this.toTitle(field.name);
     return {
@@ -7652,29 +8041,106 @@ var AxSignature = class _AxSignature {
   parseField = (field) => {
     const title = !field.title || field.title.length === 0 ? this.toTitle(field.name) : field.title;
     if (field.type && (!field.type.name || field.type.name.length === 0)) {
-      throw new Error("Field type name is required: " + field.name);
+      throw new AxSignatureValidationError(
+        "Field type name is required",
+        field.name,
+        "Specify a valid type. Available types: string, number, boolean, json, image, audio, date, datetime, class, code"
+      );
     }
     return { ...field, title };
   };
   setDescription = (desc) => {
+    if (typeof desc !== "string") {
+      throw new AxSignatureValidationError(
+        "Description must be a string",
+        void 0,
+        "Provide a string description for the signature"
+      );
+    }
     this.description = desc;
     this.updateHash();
   };
   addInputField = (field) => {
-    this.inputFields.push(this.parseField(field));
-    this.updateHash();
+    try {
+      const parsedField = this.parseField(field);
+      validateField(parsedField, "input");
+      this.inputFields.push(parsedField);
+      this.updateHash();
+    } catch (error) {
+      if (error instanceof AxSignatureValidationError) {
+        throw error;
+      }
+      throw new AxSignatureValidationError(
+        `Failed to add input field "${field.name}": ${error instanceof Error ? error.message : "Unknown error"}`,
+        field.name
+      );
+    }
   };
   addOutputField = (field) => {
-    this.outputFields.push(this.parseField(field));
-    this.updateHash();
+    try {
+      const parsedField = this.parseField(field);
+      validateField(parsedField, "output");
+      this.outputFields.push(parsedField);
+      this.updateHash();
+    } catch (error) {
+      if (error instanceof AxSignatureValidationError) {
+        throw error;
+      }
+      throw new AxSignatureValidationError(
+        `Failed to add output field "${field.name}": ${error instanceof Error ? error.message : "Unknown error"}`,
+        field.name
+      );
+    }
   };
   setInputFields = (fields) => {
-    this.inputFields = fields.map((v) => this.parseField(v));
-    this.updateHash();
+    if (!Array.isArray(fields)) {
+      throw new AxSignatureValidationError(
+        "Input fields must be an array",
+        void 0,
+        "Provide an array of field objects"
+      );
+    }
+    try {
+      const parsedFields = fields.map((v) => {
+        const parsed = this.parseField(v);
+        validateField(parsed, "input");
+        return parsed;
+      });
+      this.inputFields = parsedFields;
+      this.updateHash();
+    } catch (error) {
+      if (error instanceof AxSignatureValidationError) {
+        throw error;
+      }
+      throw new AxSignatureValidationError(
+        `Failed to set input fields: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
   };
   setOutputFields = (fields) => {
-    this.outputFields = fields.map((v) => this.parseField(v));
-    this.updateHash();
+    if (!Array.isArray(fields)) {
+      throw new AxSignatureValidationError(
+        "Output fields must be an array",
+        void 0,
+        "Provide an array of field objects"
+      );
+    }
+    try {
+      const parsedFields = fields.map((v) => {
+        const parsed = this.parseField(v);
+        validateField(parsed, "output");
+        return parsed;
+      });
+      this.outputFields = parsedFields;
+      this.updateHash();
+    } catch (error) {
+      if (error instanceof AxSignatureValidationError) {
+        throw error;
+      }
+      throw new AxSignatureValidationError(
+        `Failed to set output fields: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
   };
   getInputFields = () => this.inputFields;
   getOutputFields = () => this.outputFields;
@@ -7716,23 +8182,77 @@ var AxSignature = class _AxSignature {
     return schema;
   };
   updateHash = () => {
-    this.getInputFields().forEach((field) => {
-      validateField(field);
-    });
-    this.getOutputFields().forEach((field) => {
-      validateField(field);
-      if (field.type?.name === "image") {
-        throw new Error("Image type is not supported in output fields.");
+    try {
+      this.getInputFields().forEach((field) => {
+        validateField(field, "input");
+      });
+      this.getOutputFields().forEach((field) => {
+        validateField(field, "output");
+      });
+      this.validateSignatureConsistency();
+      this.sigHash = createHash("sha256").update(this.description ?? "").update(JSON.stringify(this.inputFields)).update(JSON.stringify(this.outputFields)).digest("hex");
+      this.sigString = renderSignature(
+        this.description,
+        this.inputFields,
+        this.outputFields
+      );
+      return [this.sigHash, this.sigString];
+    } catch (error) {
+      if (error instanceof AxSignatureValidationError) {
+        throw error;
       }
-    });
-    this.sigHash = createHash("sha256").update(this.description ?? "").update(JSON.stringify(this.inputFields)).update(JSON.stringify(this.outputFields)).digest("hex");
-    this.sigString = renderSignature(
-      this.description,
-      this.inputFields,
-      this.outputFields
-    );
-    return [this.sigHash, this.sigString];
+      throw new AxSignatureValidationError(
+        `Signature validation failed: ${error instanceof Error ? error.message : "Unknown error"}`
+      );
+    }
   };
+  validateSignatureConsistency() {
+    const inputNames = /* @__PURE__ */ new Set();
+    for (const field of this.inputFields) {
+      if (inputNames.has(field.name)) {
+        throw new AxSignatureValidationError(
+          `Duplicate input field name: "${field.name}"`,
+          field.name,
+          "Each field name must be unique within the signature"
+        );
+      }
+      inputNames.add(field.name);
+    }
+    const outputNames = /* @__PURE__ */ new Set();
+    for (const field of this.outputFields) {
+      if (outputNames.has(field.name)) {
+        throw new AxSignatureValidationError(
+          `Duplicate output field name: "${field.name}"`,
+          field.name,
+          "Each field name must be unique within the signature"
+        );
+      }
+      outputNames.add(field.name);
+    }
+    for (const outputField of this.outputFields) {
+      if (inputNames.has(outputField.name)) {
+        throw new AxSignatureValidationError(
+          `Field name "${outputField.name}" appears in both inputs and outputs`,
+          outputField.name,
+          "Use different names for input and output fields to avoid confusion"
+        );
+      }
+    }
+    if (this.inputFields.length === 0) {
+      throw new AxSignatureValidationError(
+        "Signature must have at least one input field",
+        void 0,
+        'Add an input field. Example: "userInput:string -> ..."'
+      );
+    }
+    if (this.outputFields.length === 0) {
+      throw new AxSignatureValidationError(
+        "Signature must have at least one output field",
+        void 0,
+        'Add an output field. Example: "... -> responseText:string"'
+      );
+    }
+  }
   hash = () => this.sigHash;
   toString = () => this.sigString;
   toJSON = () => {
@@ -7749,54 +8269,194 @@ function renderField(field) {
   if (field.isOptional) {
     result += "?";
   }
+  if (field.isInternal) {
+    result += "!";
+  }
   if (field.type) {
     result += ":" + field.type.name;
     if (field.type.isArray) {
       result += "[]";
     }
+    if (field.type.name === "class" && field.type.options) {
+      result += ` "${field.type.options.join(", ")}"`;
+    }
   }
-  if (field.description) {
+  if (field.description && field.type?.name !== "class") {
     result += ` "${field.description}"`;
   }
   return result;
 }
 function renderSignature(description, inputFields, outputFields) {
-  const descriptionPart = description ? `"${description}"` : "";
+  const descriptionPart = description ? `"${description}" ` : "";
   const inputFieldsRendered = inputFields.map(renderField).join(", ");
   const outputFieldsRendered = outputFields.map(renderField).join(", ");
-  return `${descriptionPart} ${inputFieldsRendered} -> ${outputFieldsRendered}`;
+  return `${descriptionPart}${inputFieldsRendered} -> ${outputFieldsRendered}`;
 }
 function isValidCase(inputString) {
   const camelCaseRegex = /^[a-z][a-zA-Z0-9]*$/;
   const snakeCaseRegex = /^[a-z]+(_[a-z0-9]+)*$/;
   return camelCaseRegex.test(inputString) || snakeCaseRegex.test(inputString);
 }
-function validateField(field) {
+function validateField(field, context3) {
   if (!field.name || field.name.length === 0) {
-    throw new Error("Field name cannot be blank");
+    throw new AxSignatureValidationError(
+      "Field name cannot be blank",
+      field.name,
+      "Every field must have a descriptive name"
+    );
   }
   if (!isValidCase(field.name)) {
-    throw new Error(
-      `Invalid field name '${field.name}', it must be camel case or snake case: `
+    throw new AxSignatureValidationError(
+      `Invalid field name '${field.name}' - must be camelCase or snake_case`,
+      field.name,
+      'Use camelCase (e.g., "userInput") or snake_case (e.g., "user_input")'
     );
   }
-  if ([
-    "text",
-    "object",
-    "image",
-    "string",
-    "number",
-    "boolean",
-    "json",
-    "array",
-    "datetime",
-    "date",
-    "time",
-    "type",
-    "class"
-  ].includes(field.name)) {
-    throw new Error(
-      `Invalid field name '${field.name}', please make it more descriptive (eg. companyDescription)`
+  if (axGlobals.signatureStrict) {
+    const reservedNames = [
+      "text",
+      "object",
+      "image",
+      "string",
+      "number",
+      "boolean",
+      "json",
+      "array",
+      "datetime",
+      "date",
+      "time",
+      "type",
+      "class",
+      "input",
+      "output",
+      "data",
+      "value",
+      "result",
+      "response",
+      "request",
+      "item",
+      "element"
+    ];
+    if (reservedNames.includes(field.name.toLowerCase())) {
+      const suggestions = context3 === "input" ? [
+        "userInput",
+        "questionText",
+        "documentContent",
+        "messageText",
+        "queryString"
+      ] : [
+        "responseText",
+        "analysisResult",
+        "categoryType",
+        "summaryText",
+        "outputData"
+      ];
+      throw new AxSignatureValidationError(
+        `Field name '${field.name}' is too generic`,
+        field.name,
+        `Use a more descriptive name. Examples for ${context3} fields: ${suggestions.join(", ")}`
+      );
+    }
+  }
+  if (field.name.length < 2) {
+    throw new AxSignatureValidationError(
+      `Field name '${field.name}' is too short`,
+      field.name,
+      "Field names must be at least 2 characters long"
+    );
+  }
+  if (field.name.length > 50) {
+    throw new AxSignatureValidationError(
+      `Field name '${field.name}' is too long (${field.name.length} characters)`,
+      field.name,
+      "Field names should be 50 characters or less"
+    );
+  }
+  if (field.type) {
+    validateFieldType(field, context3);
+  }
+}
+function validateFieldType(field, context3) {
+  if (!field.type) return;
+  const { type } = field;
+  if (type.name === "image" || type.name === "audio") {
+    if (context3 === "output") {
+      throw new AxSignatureValidationError(
+        `${type.name} type is not supported in output fields`,
+        field.name,
+        `${type.name} types can only be used in input fields`
+      );
+    }
+    if (type.isArray) {
+      throw new AxSignatureValidationError(
+        `Arrays of ${type.name} are not supported`,
+        field.name,
+        `Use a single ${type.name} type instead`
+      );
+    }
+  }
+  if (type.name === "class") {
+    if (context3 === "input") {
+      throw new AxSignatureValidationError(
+        "Class type is not supported in input fields",
+        field.name,
+        'Class types are only allowed on output fields. Use "string" type for input classifications'
+      );
+    }
+    if (!type.options || type.options.length === 0) {
+      throw new AxSignatureValidationError(
+        "Class type requires options",
+        field.name,
+        'Provide class options. Example: class "positive, negative, neutral"'
+      );
+    }
+    if (type.options.length === 1) {
+      throw new AxSignatureValidationError(
+        "Class type needs at least 2 options",
+        field.name,
+        'Add more class options or use "string" type instead'
+      );
+    }
+    for (const option of type.options) {
+      if (!option || option.trim().length === 0) {
+        throw new AxSignatureValidationError(
+          "Empty class option found",
+          field.name,
+          "All class options must be non-empty strings"
+        );
+      }
+      const trimmedOption = option.trim();
+      if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(trimmedOption)) {
+        throw new AxSignatureValidationError(
+          `Invalid class option "${trimmedOption}"`,
+          field.name,
+          "Class options must start with a letter and contain only letters, numbers, underscores, or hyphens"
+        );
+      }
+    }
+    const uniqueOptions = new Set(
+      type.options.map((opt) => opt.trim().toLowerCase())
+    );
+    if (uniqueOptions.size !== type.options.length) {
+      throw new AxSignatureValidationError(
+        "Duplicate class options found",
+        field.name,
+        "Each class option must be unique (case-insensitive)"
+      );
+    }
+  }
+  if (type.name === "code" && type.isArray) {
+    throw new AxSignatureValidationError(
+      "Arrays of code are not commonly supported",
+      field.name,
+      "Consider using a single code field or an array of strings instead"
+    );
+  }
+  if (field.isInternal && context3 === "input") {
+    throw new AxSignatureValidationError(
+      "Internal marker (!) is not allowed on input fields",
+      field.name,
+      "Internal markers are only allowed on output fields"
     );
   }
 }
@@ -8387,6 +9047,7 @@ Content: ${result.content}`
     }
     let prompt;
     if (Array.isArray(values)) {
+      validateAxMessageArray(values);
       prompt = this.promptTemplate.render(values, {
         examples: this.examples,
         demos: this.demos
@@ -11529,13 +12190,18 @@ var AxMockAIService = class {
     }
   };
   getLastUsedChatModel() {
-    throw new Error("Method not implemented.");
+    return this.config.modelInfo?.name ?? "mock-model";
   }
   getLastUsedEmbedModel() {
-    throw new Error("Method not implemented.");
+    return this.config.embedModelInfo?.name ?? "mock-embed-model";
   }
   getLastUsedModelConfig() {
-    throw new Error("Method not implemented.");
+    return this.config.modelInfo ? {
+      maxTokens: this.config.modelInfo.maxTokens,
+      temperature: 0.7,
+      // Default temperature
+      stream: this.config.features?.streaming ?? false
+    } : void 0;
   }
   getName() {
     return this.config.name ?? "mock-ai-service";
@@ -13938,6 +14604,7 @@ export {
   axAITogetherDefaultConfig,
   axBaseAIDefaultConfig,
   axBaseAIDefaultCreativeConfig,
+  axGlobals,
   axModelInfoAnthropic,
   axModelInfoCohere,
   axModelInfoDeepSeek,