@ax-llm/ax 14.0.39 → 14.0.41

package/index.d.cts

@@ -231,6 +231,8 @@ type AxFunctionJSONSchema = {
     }>;
     required?: string[];
     items?: AxFunctionJSONSchema;
+    title?: string;
+    additionalProperties?: boolean;
 };
 type AxFunction = {
     name: string;
@@ -428,6 +430,10 @@ type AxChatRequest<TModel = string> = {
             name: string;
         };
     };
+    responseFormat?: {
+        type: 'json_object' | 'json_schema';
+        schema?: any;
+    };
     modelConfig?: AxModelConfig;
     model?: TModel;
 };
@@ -607,12 +613,20 @@ interface AxAIMemory {
 }
 
 interface AxFieldType {
-    readonly type: 'string' | 'number' | 'boolean' | 'json' | 'image' | 'audio' | 'file' | 'url' | 'date' | 'datetime' | 'class' | 'code';
+    readonly type: 'string' | 'number' | 'boolean' | 'json' | 'image' | 'audio' | 'file' | 'url' | 'date' | 'datetime' | 'class' | 'code' | 'object';
     readonly isArray?: boolean;
     readonly options?: readonly string[];
+    readonly fields?: Record<string, AxFieldType>;
     readonly description?: string;
     readonly isOptional?: boolean;
     readonly isInternal?: boolean;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly pattern?: string;
+    readonly patternDescription?: string;
+    readonly format?: string;
 }
 declare class AxSignatureBuilder<_TInput extends Record<string, any> = {}, _TOutput extends Record<string, any> = {}> {
     private inputFields;
@@ -624,14 +638,14 @@ declare class AxSignatureBuilder<_TInput extends Record<string, any> = {}, _TOut
      * @param fieldInfo - Field type created with f.string(), f.number(), etc.
      * @param prepend - If true, adds field to the beginning of input fields
      */
-    input<K extends string, T extends AxFluentFieldInfo<any, any, any, any> | AxFluentFieldType<any, any, any, any, any>>(name: K, fieldInfo: T, prepend?: boolean): AxSignatureBuilder<AddFieldToShape<_TInput, K, T>, _TOutput>;
+    input<K extends string, T extends AxFluentFieldInfo<any, any, any, any, any, any> | AxFluentFieldType<any, any, any, any, any, any>>(name: K, fieldInfo: T, prepend?: boolean): AxSignatureBuilder<AddFieldToShape<_TInput, K, T>, _TOutput>;
     /**
      * Add an output field to the signature
      * @param name - Field name
      * @param fieldInfo - Field type created with f.string(), f.number(), etc.
      * @param prepend - If true, adds field to the beginning of output fields
      */
-    output<K extends string, T extends AxFluentFieldInfo<any, any, any, any> | AxFluentFieldType<any, any, any, any, any>>(name: K, fieldInfo: T, prepend?: boolean): AxSignatureBuilder<_TInput, AddFieldToShape<_TOutput, K, T>>;
+    output<K extends string, T extends AxFluentFieldInfo<any, any, any, any, any, any> | AxFluentFieldType<any, any, any, any, any, any>>(name: K, fieldInfo: T, prepend?: boolean): AxSignatureBuilder<_TInput, AddFieldToShape<_TOutput, K, T>>;
     /**
      * Set the description for the signature
      * @param description - Description text
@@ -642,13 +656,21 @@ declare class AxSignatureBuilder<_TInput extends Record<string, any> = {}, _TOut
      */
     build(): AxSignature<_TInput, _TOutput>;
 }
-declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType['type'], TIsArray extends boolean = false, TOptions extends readonly string[] | undefined = undefined, TIsOptional extends boolean = false, TIsInternal extends boolean = false> implements AxFieldType {
+declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType['type'], TIsArray extends boolean = false, TOptions extends readonly string[] | undefined = undefined, TIsOptional extends boolean = false, TIsInternal extends boolean = false, TFields extends Record<string, AxFluentFieldInfo | AxFluentFieldType> | undefined = undefined> implements AxFieldType {
     readonly type: TType;
     readonly isArray: TIsArray;
     readonly options?: TOptions;
     readonly description?: string;
     readonly isOptional: TIsOptional;
     readonly isInternal: TIsInternal;
+    readonly fields?: any;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly pattern?: string;
+    readonly patternDescription?: string;
+    readonly format?: string;
     constructor(fieldType: {
         type: TType;
         isArray: TIsArray;
@@ -656,33 +678,93 @@ declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType[
         description?: string;
         isOptional: TIsOptional;
         isInternal: TIsInternal;
+        fields?: TFields;
+        minLength?: number;
+        maxLength?: number;
+        minimum?: number;
+        maximum?: number;
+        pattern?: string;
+        patternDescription?: string;
+        format?: string;
     });
-    optional(): AxFluentFieldType<TType, TIsArray, TOptions, true, TIsInternal>;
-    array(): AxFluentFieldType<TType, true, TOptions, TIsOptional, TIsInternal>;
-    internal(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, true>;
+    optional(): AxFluentFieldType<TType, TIsArray, TOptions, true, TIsInternal, TFields>;
+    array(desc?: string): AxFluentFieldType<TType, true, TOptions, TIsOptional, TIsInternal, TFields>;
+    internal(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, true, TFields>;
+    /**
+     * Set minimum value for numbers or minimum length for strings
+     */
+    min(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set maximum value for numbers or maximum length for strings
+     */
+    max(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set email format validation for strings
+     */
+    email(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set URL/URI format validation for strings
+     */
+    url(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set regex pattern validation for strings
+     * @param pattern - Regular expression pattern to match
+     * @param description - Human-readable description of what the pattern validates (e.g., "Must be a valid username with only lowercase letters, numbers, and underscores")
+     */
+    regex(pattern: string, description: string): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set date format validation for strings
+     */
+    date(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    /**
+     * Set datetime format validation for strings
+     */
+    datetime(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
 }
+type ValidateNoMediaTypes<TFields> = {
+    [K in keyof TFields]: TFields[K] extends {
+        type: infer T;
+    } ? T extends 'image' | 'audio' | 'file' ? {
+        __error: `Type '${T extends string ? T : never}' cannot be used in f.object(). Media types (image, audio, file) are only allowed as top-level input fields, not within nested objects.`;
+        __suggestion: 'Use string, number, boolean, or nested f.object() instead.';
+    } : TFields[K] extends {
+        fields: infer TNestedFields;
+    } ? TNestedFields extends Record<string, any> ? TFields[K] & {
+        fields: ValidateNoMediaTypes<TNestedFields>;
+    } : TFields[K] : TFields[K] : TFields[K];
+};
 declare const f: (() => AxSignatureBuilder) & {
-    string: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false>;
-    number: (desc?: string) => AxFluentFieldType<"number", false, undefined, false, false>;
-    boolean: (desc?: string) => AxFluentFieldType<"boolean", false, undefined, false, false>;
-    json: (desc?: string) => AxFluentFieldType<"json", false, undefined, false, false>;
-    datetime: (desc?: string) => AxFluentFieldType<"datetime", false, undefined, false, false>;
-    date: (desc?: string) => AxFluentFieldType<"date", false, undefined, false, false>;
-    class: <const TOptions extends readonly string[]>(options: TOptions, desc?: string) => AxFluentFieldType<"class", false, TOptions, false, false>;
-    image: (desc?: string) => AxFluentFieldType<"image", false, undefined, false, false>;
-    audio: (desc?: string) => AxFluentFieldType<"audio", false, undefined, false, false>;
-    file: (desc?: string) => AxFluentFieldType<"file", false, undefined, false, false>;
-    url: (desc?: string) => AxFluentFieldType<"url", false, undefined, false, false>;
-    code: (language?: string, desc?: string) => AxFluentFieldType<"code", false, undefined, false, false>;
+    string: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined>;
+    number: (desc?: string) => AxFluentFieldType<"number", false, undefined, false, false, undefined>;
+    boolean: (desc?: string) => AxFluentFieldType<"boolean", false, undefined, false, false, undefined>;
+    json: (desc?: string) => AxFluentFieldType<"json", false, undefined, false, false, undefined>;
+    datetime: (desc?: string) => AxFluentFieldType<"datetime", false, undefined, false, false, undefined>;
+    date: (desc?: string) => AxFluentFieldType<"date", false, undefined, false, false, undefined>;
+    class: <const TOptions extends readonly string[]>(options: TOptions, desc?: string) => AxFluentFieldType<"class", false, TOptions, false, false, undefined>;
+    image: (desc?: string) => AxFluentFieldType<"image", false, undefined, false, false, undefined>;
+    audio: (desc?: string) => AxFluentFieldType<"audio", false, undefined, false, false, undefined>;
+    file: (desc?: string) => AxFluentFieldType<"file", false, undefined, false, false, undefined>;
+    url: (desc?: string) => AxFluentFieldType<"url", false, undefined, false, false, undefined>;
+    email: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined>;
+    code: (language?: string, desc?: string) => AxFluentFieldType<"code", false, undefined, false, false, undefined>;
+    object: <TFields extends Record<string, AxFluentFieldInfo<any, any, any, any, any, any> | AxFluentFieldType<any, any, any, any, any, any>>>(fields: TFields & ValidateNoMediaTypes<TFields>, desc?: string) => AxFluentFieldType<"object", false, undefined, false, false, TFields>;
 };
 interface AxField {
     name: string;
     title?: string;
     description?: string;
     type?: {
-        name: 'string' | 'number' | 'boolean' | 'json' | 'image' | 'audio' | 'file' | 'url' | 'date' | 'datetime' | 'class' | 'code';
+        name: 'string' | 'number' | 'boolean' | 'json' | 'image' | 'audio' | 'file' | 'url' | 'date' | 'datetime' | 'class' | 'code' | 'object';
         isArray?: boolean;
         options?: string[];
+        fields?: Record<string, AxFieldType>;
+        minLength?: number;
+        maxLength?: number;
+        minimum?: number;
+        maximum?: number;
+        pattern?: string;
+        patternDescription?: string;
+        format?: string;
     };
     isOptional?: boolean;
     isInternal?: boolean;
@@ -714,14 +796,28 @@ type InferFieldValueType<T> = T extends AxFieldType | AxFluentFieldType ? T['typ
 } | {
     mimeType: string;
     fileUri: string;
-} : T['type'] extends 'url' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'code' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'class' ? T['options'] extends readonly (infer U)[] ? T['isArray'] extends true ? U[] : U : T['isArray'] extends true ? string[] : string : any : any;
-interface AxFluentFieldInfo<TType extends AxFieldType['type'] = AxFieldType['type'], TIsArray extends boolean = false, TOptions extends readonly string[] = readonly string[], TIsOptional extends boolean = false> {
+} : T['type'] extends 'url' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'code' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'class' ? T['options'] extends readonly (infer U)[] ? T['isArray'] extends true ? U[] : U : T['isArray'] extends true ? string[] : string : T['type'] extends 'object' ? T extends {
+    fields: infer F;
+} ? F extends Record<string, any> ? T['isArray'] extends true ? {
+    [K in keyof F]: InferFluentType<F[K]>;
+}[] : {
+    [K in keyof F]: InferFluentType<F[K]>;
+} : any : any : any : any;
+interface AxFluentFieldInfo<TType extends AxFieldType['type'] = AxFieldType['type'], TIsArray extends boolean = false, TOptions extends readonly string[] = readonly string[], TIsOptional extends boolean = false, _TIsInternal extends boolean = false, TFields extends Record<string, AxFluentFieldInfo | AxFluentFieldType> | undefined = undefined> {
     readonly type: TType;
     readonly isArray?: TIsArray;
     readonly options?: TOptions;
+    readonly fields?: TFields;
     readonly description?: string;
     readonly isOptional?: TIsOptional;
     readonly isInternal?: boolean;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly pattern?: string;
+    readonly patternDescription?: string;
+    readonly format?: string;
 }
 type InferFluentType<T extends AxFluentFieldInfo<any, any, any, any> | AxFluentFieldType> = T['type'] extends 'string' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'number' ? T['isArray'] extends true ? number[] : number : T['type'] extends 'boolean' ? T['isArray'] extends true ? boolean[] : boolean : T['type'] extends 'json' ? T['isArray'] extends true ? any[] : any : T['type'] extends 'date' ? T['isArray'] extends true ? Date[] : Date : T['type'] extends 'datetime' ? T['isArray'] extends true ? Date[] : Date : T['type'] extends 'image' ? T['isArray'] extends true ? {
     mimeType: string;
@@ -747,7 +843,13 @@ type InferFluentType<T extends AxFluentFieldInfo<any, any, any, any> | AxFluentF
 } | {
     mimeType: string;
     fileUri: string;
-} : T['type'] extends 'url' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'code' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'class' ? T['options'] extends readonly (infer U)[] ? T['isArray'] extends true ? U[] : U : T['isArray'] extends true ? string[] : string : any;
+} : T['type'] extends 'url' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'code' ? T['isArray'] extends true ? string[] : string : T['type'] extends 'class' ? T['options'] extends readonly (infer U)[] ? T['isArray'] extends true ? U[] : U : T['isArray'] extends true ? string[] : string : T['type'] extends 'object' ? T extends {
+    fields: infer F;
+} ? F extends Record<string, any> ? T['isArray'] extends true ? {
+    [K in keyof F]: InferFluentType<F[K]>;
+}[] : {
+    [K in keyof F]: InferFluentType<F[K]>;
+} : any : any : any;
 type _IsInternal<T> = T extends {
     readonly isInternal: true;
 } ? true : false;
@@ -808,7 +910,6 @@ declare class AxSignature<_TInput extends Record<string, any> = Record<string, a
     prependOutputField: <K extends string, T extends AxFieldType>(name: K, fieldType: T) => AxSignature<_TInput, Record<K, InferFieldValueType<T>> & _TOutput>;
     private invalidateValidationCache;
     private toTitle;
-    toJSONSchema: () => AxFunctionJSONSchema;
     private updateHashLight;
     private updateHash;
     private validateSignatureConsistency;
@@ -821,6 +922,7 @@ declare class AxSignature<_TInput extends Record<string, any> = Record<string, a
         inputFields: AxIField[];
         outputFields: AxIField[];
     };
+    toJSONSchema: () => AxFunctionJSONSchema;
 }
 
 interface AxAssertion<T = Record<string, unknown>> {
@@ -1777,6 +1879,15 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
     private forwardSendRequest;
     private forwardCore;
     private _forward2;
+    /**
+     * Validate input values against field constraints
+     * @throws ValidationError if any input value fails validation
+     */
+    private validateInputs;
+    /**
+     * Recursively validate object field values
+     */
+    private validateObjectFields;
     _forward1(ai: Readonly<AxAIService>, values: IN | AxMessage<IN>[], options: Readonly<AxProgramForwardOptions<any>>): AxGenStreamingOut<OUT>;
     forward<T extends Readonly<AxAIService>>(ai: T, values: IN | AxMessage<IN>[], options?: Readonly<AxProgramForwardOptionsWithModels<T>>): Promise<OUT>;
     streamingForward<T extends Readonly<AxAIService>>(ai: T, values: IN | AxMessage<IN>[], options?: Readonly<AxProgramStreamingForwardOptionsWithModels<T>>): AxGenStreamingOut<OUT>;
@@ -1884,6 +1995,15 @@ declare class AxPromptTemplate {
 /**
  * A map of string type names to their corresponding TypeScript types.
  * Maps signature type strings to actual TypeScript types for type inference.
+ *
+ * IMPORTANT: The 'object' type is NOT included in this map because string signatures
+ * cannot define structured object types. When 'object' appears in a string signature,
+ * it's treated the same as 'json' and inferred as 'any'.
+ *
+ * For structured object types with proper type inference, use the fluent API:
+ * f().output('user', f.object({ name: f.string(), age: f.number() }))
+ *
+ * See: STRING_SIGNATURE_LIMITATIONS.md
  */
 interface TypeMap {
     string: string;
@@ -2161,6 +2281,7 @@ type AxGenDeltaOut<OUT> = {
     version: number;
     index: number;
     delta: Partial<OUT>;
+    partial?: OUT;
 };
 type AxGenStreamingOut<OUT> = AsyncGenerator<AxGenDeltaOut<OUT>, void, unknown>;
 type AxSetExamplesOptions = {};
@@ -2502,6 +2623,10 @@ type AxAIAnthropicChatRequest = {
     top_p?: number;
     top_k?: number;
     thinking?: AxAIAnthropicThinkingConfig;
+    output_format?: {
+        type: 'json_schema';
+        schema: object;
+    };
     metadata?: {
         user_id: string;
     };
@@ -2558,6 +2683,8 @@ interface AxAIAnthropicMessageStartEvent {
         usage: {
             input_tokens: number;
             output_tokens: number;
+            cache_creation_input_tokens?: number;
+            cache_read_input_tokens?: number;
         };
     };
 }
@@ -2819,6 +2946,9 @@ type AxAIOpenAIChatRequest<TModel> = {
     };
     response_format?: {
         type: string;
+    } | {
+        type: 'json_schema';
+        json_schema: any;
     };
     max_completion_tokens?: number;
     temperature?: number;
@@ -3490,11 +3620,15 @@ declare class AxAIDeepSeek<TModelKey> extends AxAIOpenAIBase<AxAIDeepSeekModel,
 declare const axModelInfoDeepSeek: AxModelInfo[];
 
 declare enum AxAIGoogleGeminiModel {
+    Gemini3ProPreview = "gemini-3-pro-preview",
+    Gemini3ProImagePreview = "gemini-3-pro-image-preview",
     Gemini25Pro = "gemini-2.5-pro",
     Gemini25Flash = "gemini-2.5-flash",
     Gemini25FlashLite = "gemini-2.5-flash-lite",
     Gemini20Flash = "gemini-2.0-flash",
     Gemini20FlashLite = "gemini-2.0-flash-lite",
+    Gemini20ProExp = "gemini-2.0-pro-exp-02-05",
+    Gemini20FlashThinkingExp = "gemini-2.0-flash-thinking-exp-01-21",
     Gemini1Pro = "gemini-1.0-pro",
     Gemini15Flash = "gemini-1.5-flash",
     Gemini15Flash002 = "gemini-1.5-flash-002",
@@ -3539,11 +3673,15 @@ type AxAIGoogleGeminiContent = {
 };
 type AxAIGoogleGeminiContentPart = {
     thought?: boolean;
+    thoughtSignature?: string;
     metadata?: {
         videoMetadata: object;
     };
 } & ({
     text: string;
+    thought?: boolean;
+} | {
+    thought: string;
 } | {
     inlineData: {
         mimeType: string;
@@ -3607,8 +3745,10 @@ type AxAIGoogleGeminiGenerationConfig = {
     maxOutputTokens?: number;
     stopSequences?: readonly string[];
     responseMimeType?: string;
+    responseSchema?: object;
     thinkingConfig?: {
         thinkingBudget?: number;
+        thinkingLevel?: 'low' | 'high';
         includeThoughts?: boolean;
     };
 };
@@ -3668,6 +3808,7 @@ type AxAIGoogleGeminiChatResponse = {
 type AxAIGoogleGeminiChatResponseDelta = AxAIGoogleGeminiChatResponse;
 type AxAIGoogleGeminiThinkingConfig = {
     thinkingTokenBudget?: number;
+    thinkingLevel?: 'low' | 'high';
     includeThoughts?: boolean;
 };
 type AxAIGoogleGeminiThinkingTokenBudgetLevels = {
@@ -3690,6 +3831,7 @@ type AxAIGoogleGeminiConfig = AxModelConfig & {
     thinking?: AxAIGoogleGeminiThinkingConfig;
     thinkingTokenBudgetLevels?: AxAIGoogleGeminiThinkingTokenBudgetLevels;
     urlContext?: string;
+    responseFormat?: 'json_object';
 };
 /**
  * AxAIGoogleGeminiEmbedRequest: Structure for making an embedding request to the Google Gemini API.
@@ -7293,13 +7435,13 @@ TState extends AxFlowState = IN> implements AxFlowable<IN, OUT> {
      * // Create a chain-of-thought node
      * flow.nodeExtended('reasoner', 'question:string -> answer:string', {
      *   prependOutputs: [
-     *     { name: 'reasoning', type: f.internal(f.string('Step-by-step reasoning')) }
+     *     { name: 'reasoning', type: f.string('Step-by-step reasoning').internal() }
      *   ]
      * })
      *
      * // Create a node with context and confidence
      * flow.nodeExtended('analyzer', 'input:string -> output:string', {
-     *   appendInputs: [{ name: 'context', type: f.optional(f.string('Context')) }],
+     *   appendInputs: [{ name: 'context', type: f.string('Context').optional() }],
      *   appendOutputs: [{ name: 'confidence', type: f.number('Confidence score') }]
      * })
      * ```