@ax-llm/ax 14.0.0 → 14.0.2

package/index.d.cts

@@ -319,12 +319,24 @@ type AxChatRequest<TModel = string> = {
             /** Duration of audio in seconds */
             duration?: number;
         } | {
-            /** File content type */
+            /** File content type with inline data */
             type: 'file';
-            /** File data as base64 or file URL */
+            /** File data as base64 */
             data: string;
             /** Original filename */
-            filename: string;
+            filename?: string;
+            /** MIME type of the file */
+            mimeType: string;
+            cache?: boolean;
+            /** Pre-extracted text content for fallback */
+            extractedText?: string;
+        } | {
+            /** File content type with cloud storage URI */
+            type: 'file';
+            /** File URI (e.g., gs:// URL) */
+            fileUri: string;
+            /** Original filename */
+            filename?: string;
             /** MIME type of the file */
             mimeType: string;
             cache?: boolean;
@@ -1225,7 +1237,7 @@ declare class AxAIOpenAIBase<TModel, TEmbedModel, TModelKey, TChatReq extends Ax
     constructor({ apiKey, config, options, apiURL, modelInfo, models, chatReqUpdater, supportFor, }: Readonly<Omit<AxAIOpenAIBaseArgs<TModel, TEmbedModel, TModelKey, TChatReq>, 'name'>>);
 }
 declare class AxAIOpenAI<TModelKey = string> extends AxAIOpenAIBase<AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey> {
-    constructor({ apiKey, config, options, models, modelInfo, }: Readonly<Omit<AxAIOpenAIArgs<'openai', AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey>, 'name'>>);
+    constructor({ apiKey, apiURL, config, options, models, modelInfo, }: Readonly<Omit<AxAIOpenAIArgs<'openai', AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey>, 'name'>>);
 }
 
 declare const axAIAzureOpenAIDefaultConfig: () => AxAIOpenAIConfig<AxAIOpenAIModel, AxAIOpenAIEmbedModel>;
@@ -3707,7 +3719,14 @@ declare class AxMemory implements AxAIMemory {
         } | {
             type: "file";
             data: string;
-            filename: string;
+            filename?: string;
+            mimeType: string;
+            cache?: boolean;
+            extractedText?: string;
+        } | {
+            type: "file";
+            fileUri: string;
+            filename?: string;
             mimeType: string;
             cache?: boolean;
             extractedText?: string;
@@ -3828,7 +3847,14 @@ declare class AxPromptTemplate {
     } | {
         type: "file";
         data: string;
-        filename: string;
+        filename?: string;
+        mimeType: string;
+        cache?: boolean;
+        extractedText?: string;
+    } | {
+        type: "file";
+        fileUri: string;
+        filename?: string;
         mimeType: string;
         cache?: boolean;
         extractedText?: string;
@@ -3869,6 +3895,9 @@ interface TypeMap {
     file: {
         mimeType: string;
         data: string;
+    } | {
+        mimeType: string;
+        fileUri: string;
     };
     url: string;
     code: string;
@@ -4025,6 +4054,15 @@ type AxGenIn = {
 type AxGenOut = {
     [key: string]: AxFieldValue;
 };
+/**
+ * @deprecated AxMessage will be updated to a new design within this major version.
+ * The current structure will be replaced in v15.0.0.
+ *
+ * Migration timeline:
+ * - v14.0.0+: Deprecation warnings (current)
+ * - v14.x: New message design introduced alongside existing
+ * - v15.0.0: Complete replacement with new design
+ */
 type AxMessage<IN> = {
     role: 'user';
     values: IN;
@@ -4075,6 +4113,7 @@ type AxProgramForwardOptions<MODEL> = AxAIServiceOptions & {
     functionResultFormatter?: (result: unknown) => string;
     fastFail?: boolean;
     showThoughts?: boolean;
+    functionCallMode?: 'auto' | 'native' | 'prompt';
     traceLabel?: string;
     description?: string;
     thoughtFieldName?: string;
@@ -4229,12 +4268,18 @@ type InferFieldValueType<T> = T extends AxFieldType | AxFluentFieldType ? T['typ
 }[] : {
     format?: 'wav';
     data: string;
-} : T['type'] extends 'file' ? T['isArray'] extends true ? {
+} : T['type'] extends 'file' ? T['isArray'] extends true ? ({
     mimeType: string;
     data: string;
-}[] : {
+} | {
+    mimeType: string;
+    fileUri: string;
+})[] : {
     mimeType: string;
     data: string;
+} | {
+    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> {
     readonly type: TType;
@@ -4256,12 +4301,18 @@ type InferFluentType<T extends AxFluentFieldInfo<any, any, any, any> | AxFluentF
 }[] : {
     format?: 'wav';
     data: string;
-} : T['type'] extends 'file' ? T['isArray'] extends true ? {
+} : T['type'] extends 'file' ? T['isArray'] extends true ? ({
     mimeType: string;
     data: string;
-}[] : {
+} | {
+    mimeType: string;
+    fileUri: string;
+})[] : {
     mimeType: string;
     data: string;
+} | {
+    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;
 interface AxSignatureConfig {
     description?: string;
@@ -4319,6 +4370,26 @@ declare class AxSignature<_TInput extends Record<string, any> = Record<string, a
     validate: () => boolean;
     hash: () => string;
     toString: () => string;
+    /**
+     * Inject tool schemas as optional output fields for signature tool calling
+     * Uses dot notation for nested parameters (jq-like syntax)
+     */
+    injectToolFields(tools: readonly AxFunction[]): AxSignature<_TInput, _TOutput>;
+    /**
+     * Generate signature fields for tool parameters using dot notation
+     */
+    private generateToolParameterFields;
+    /**
+     * Infer signature field type from JSON Schema parameter
+     */
+    private inferParameterType;
+    /**
+     * Format parameter title for display
+     */
+    private formatParameterTitle;
+    private sanitizeFieldName;
+    private formatTitle;
+    private inferToolFieldType;
     toJSON: () => {
         id: string;
         description: string | undefined;
@@ -4430,6 +4501,7 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
     private streamingFieldProcessors;
     private excludeContentFromTrace;
     private thoughtFieldName;
+    private signatureToolCallingManager?;
     constructor(signature: NonNullable<ConstructorParameters<typeof AxSignature>[0]> | AxSignature<any, any>, options?: Readonly<AxProgramForwardOptions<any>>);
     private getSignatureName;
     private getMetricsInstruments;
@@ -5516,6 +5588,7 @@ declare const AxStringUtil: {
 
 declare function s<const T extends string>(signature: T): AxSignature<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
 declare function ax<const T extends string>(signature: T, options?: Readonly<AxProgramForwardOptions<any>>): AxGen<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
+declare function ax<TInput extends Record<string, any>, TOutput extends Record<string, any>>(signature: AxSignature<TInput, TOutput>, options?: Readonly<AxProgramForwardOptions<any>>): AxGen<TInput, TOutput>;
 
 /**
  * Analyzes mapping functions to extract state dependencies.
@@ -7113,6 +7186,7 @@ declare class AxAgent<IN extends AxGenIn, OUT extends AxGenOut> implements AxAge
     private disableSmartModelRouting?;
     private excludeFieldsFromPassthrough;
     private debug?;
+    private options?;
     private name;
     private func;
     constructor({ ai, name, description, definition, signature, agents, functions, }: Readonly<{
@@ -7189,21 +7263,30 @@ interface AxAgentConfig<IN extends AxGenIn, OUT extends AxGenOut> extends AxAgen
     functions?: AxInputFunctionType;
 }
 /**
- * Creates a strongly-typed AI agent from a string signature.
+ * Creates a strongly-typed AI agent from a signature.
  * This is the recommended way to create agents, providing better type inference and cleaner syntax.
+ * Supports both string signatures and AxSignature objects.
  *
- * @param signature - The input/output signature as a string (e.g., "userInput:string -> responseText:string")
+ * @param signature - The input/output signature as a string or AxSignature object
  * @param config - Configuration options for the agent
  * @returns A typed agent instance
  *
  * @example
  * ```typescript
+ * // Using string signature
  * const myAgent = agent('userInput:string -> responseText:string', {
  *   name: 'myAgent',
  *   description: 'An agent that processes user input and returns a response',
  *   definition: 'You are a helpful assistant that responds to user queries...'
  * });
  *
+ * // Using AxSignature object
+ * const sig = s('userInput:string -> responseText:string');
+ * const myAgent2 = agent(sig, {
+ *   name: 'myAgent2',
+ *   description: 'Same agent but using AxSignature object'
+ * });
+ *
  * // With child agents
  * const parentAgent = agent('taskDescription:string -> completedTask:string', {
  *   name: 'parentAgent',
@@ -7217,6 +7300,7 @@ interface AxAgentConfig<IN extends AxGenIn, OUT extends AxGenOut> extends AxAgen
  * ```
  */
 declare function agent<const T extends string>(signature: T, config: AxAgentConfig<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>): AxAgent<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
+declare function agent<TInput extends Record<string, any>, TOutput extends Record<string, any>>(signature: AxSignature<TInput, TOutput>, config: AxAgentConfig<TInput, TOutput>): AxAgent<TInput, TOutput>;
 
 /**
  * Advanced Multi-hop RAG with iterative query refinement, context accumulation,

package/index.d.ts

@@ -319,12 +319,24 @@ type AxChatRequest<TModel = string> = {
             /** Duration of audio in seconds */
             duration?: number;
         } | {
-            /** File content type */
+            /** File content type with inline data */
             type: 'file';
-            /** File data as base64 or file URL */
+            /** File data as base64 */
             data: string;
             /** Original filename */
-            filename: string;
+            filename?: string;
+            /** MIME type of the file */
+            mimeType: string;
+            cache?: boolean;
+            /** Pre-extracted text content for fallback */
+            extractedText?: string;
+        } | {
+            /** File content type with cloud storage URI */
+            type: 'file';
+            /** File URI (e.g., gs:// URL) */
+            fileUri: string;
+            /** Original filename */
+            filename?: string;
             /** MIME type of the file */
             mimeType: string;
             cache?: boolean;
@@ -1225,7 +1237,7 @@ declare class AxAIOpenAIBase<TModel, TEmbedModel, TModelKey, TChatReq extends Ax
     constructor({ apiKey, config, options, apiURL, modelInfo, models, chatReqUpdater, supportFor, }: Readonly<Omit<AxAIOpenAIBaseArgs<TModel, TEmbedModel, TModelKey, TChatReq>, 'name'>>);
 }
 declare class AxAIOpenAI<TModelKey = string> extends AxAIOpenAIBase<AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey> {
-    constructor({ apiKey, config, options, models, modelInfo, }: Readonly<Omit<AxAIOpenAIArgs<'openai', AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey>, 'name'>>);
+    constructor({ apiKey, apiURL, config, options, models, modelInfo, }: Readonly<Omit<AxAIOpenAIArgs<'openai', AxAIOpenAIModel, AxAIOpenAIEmbedModel, TModelKey>, 'name'>>);
 }
 
 declare const axAIAzureOpenAIDefaultConfig: () => AxAIOpenAIConfig<AxAIOpenAIModel, AxAIOpenAIEmbedModel>;
@@ -3707,7 +3719,14 @@ declare class AxMemory implements AxAIMemory {
         } | {
             type: "file";
             data: string;
-            filename: string;
+            filename?: string;
+            mimeType: string;
+            cache?: boolean;
+            extractedText?: string;
+        } | {
+            type: "file";
+            fileUri: string;
+            filename?: string;
             mimeType: string;
             cache?: boolean;
             extractedText?: string;
@@ -3828,7 +3847,14 @@ declare class AxPromptTemplate {
     } | {
         type: "file";
         data: string;
-        filename: string;
+        filename?: string;
+        mimeType: string;
+        cache?: boolean;
+        extractedText?: string;
+    } | {
+        type: "file";
+        fileUri: string;
+        filename?: string;
         mimeType: string;
         cache?: boolean;
         extractedText?: string;
@@ -3869,6 +3895,9 @@ interface TypeMap {
     file: {
         mimeType: string;
         data: string;
+    } | {
+        mimeType: string;
+        fileUri: string;
     };
     url: string;
     code: string;
@@ -4025,6 +4054,15 @@ type AxGenIn = {
 type AxGenOut = {
     [key: string]: AxFieldValue;
 };
+/**
+ * @deprecated AxMessage will be updated to a new design within this major version.
+ * The current structure will be replaced in v15.0.0.
+ *
+ * Migration timeline:
+ * - v14.0.0+: Deprecation warnings (current)
+ * - v14.x: New message design introduced alongside existing
+ * - v15.0.0: Complete replacement with new design
+ */
 type AxMessage<IN> = {
     role: 'user';
     values: IN;
@@ -4075,6 +4113,7 @@ type AxProgramForwardOptions<MODEL> = AxAIServiceOptions & {
     functionResultFormatter?: (result: unknown) => string;
     fastFail?: boolean;
     showThoughts?: boolean;
+    functionCallMode?: 'auto' | 'native' | 'prompt';
     traceLabel?: string;
     description?: string;
     thoughtFieldName?: string;
@@ -4229,12 +4268,18 @@ type InferFieldValueType<T> = T extends AxFieldType | AxFluentFieldType ? T['typ
 }[] : {
     format?: 'wav';
     data: string;
-} : T['type'] extends 'file' ? T['isArray'] extends true ? {
+} : T['type'] extends 'file' ? T['isArray'] extends true ? ({
     mimeType: string;
     data: string;
-}[] : {
+} | {
+    mimeType: string;
+    fileUri: string;
+})[] : {
     mimeType: string;
     data: string;
+} | {
+    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> {
     readonly type: TType;
@@ -4256,12 +4301,18 @@ type InferFluentType<T extends AxFluentFieldInfo<any, any, any, any> | AxFluentF
 }[] : {
     format?: 'wav';
     data: string;
-} : T['type'] extends 'file' ? T['isArray'] extends true ? {
+} : T['type'] extends 'file' ? T['isArray'] extends true ? ({
     mimeType: string;
     data: string;
-}[] : {
+} | {
+    mimeType: string;
+    fileUri: string;
+})[] : {
     mimeType: string;
     data: string;
+} | {
+    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;
 interface AxSignatureConfig {
     description?: string;
@@ -4319,6 +4370,26 @@ declare class AxSignature<_TInput extends Record<string, any> = Record<string, a
     validate: () => boolean;
     hash: () => string;
     toString: () => string;
+    /**
+     * Inject tool schemas as optional output fields for signature tool calling
+     * Uses dot notation for nested parameters (jq-like syntax)
+     */
+    injectToolFields(tools: readonly AxFunction[]): AxSignature<_TInput, _TOutput>;
+    /**
+     * Generate signature fields for tool parameters using dot notation
+     */
+    private generateToolParameterFields;
+    /**
+     * Infer signature field type from JSON Schema parameter
+     */
+    private inferParameterType;
+    /**
+     * Format parameter title for display
+     */
+    private formatParameterTitle;
+    private sanitizeFieldName;
+    private formatTitle;
+    private inferToolFieldType;
     toJSON: () => {
         id: string;
         description: string | undefined;
@@ -4430,6 +4501,7 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
     private streamingFieldProcessors;
     private excludeContentFromTrace;
     private thoughtFieldName;
+    private signatureToolCallingManager?;
     constructor(signature: NonNullable<ConstructorParameters<typeof AxSignature>[0]> | AxSignature<any, any>, options?: Readonly<AxProgramForwardOptions<any>>);
     private getSignatureName;
     private getMetricsInstruments;
@@ -5516,6 +5588,7 @@ declare const AxStringUtil: {
 
 declare function s<const T extends string>(signature: T): AxSignature<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
 declare function ax<const T extends string>(signature: T, options?: Readonly<AxProgramForwardOptions<any>>): AxGen<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
+declare function ax<TInput extends Record<string, any>, TOutput extends Record<string, any>>(signature: AxSignature<TInput, TOutput>, options?: Readonly<AxProgramForwardOptions<any>>): AxGen<TInput, TOutput>;
 
 /**
  * Analyzes mapping functions to extract state dependencies.
@@ -7113,6 +7186,7 @@ declare class AxAgent<IN extends AxGenIn, OUT extends AxGenOut> implements AxAge
     private disableSmartModelRouting?;
     private excludeFieldsFromPassthrough;
     private debug?;
+    private options?;
     private name;
     private func;
     constructor({ ai, name, description, definition, signature, agents, functions, }: Readonly<{
@@ -7189,21 +7263,30 @@ interface AxAgentConfig<IN extends AxGenIn, OUT extends AxGenOut> extends AxAgen
     functions?: AxInputFunctionType;
 }
 /**
- * Creates a strongly-typed AI agent from a string signature.
+ * Creates a strongly-typed AI agent from a signature.
  * This is the recommended way to create agents, providing better type inference and cleaner syntax.
+ * Supports both string signatures and AxSignature objects.
  *
- * @param signature - The input/output signature as a string (e.g., "userInput:string -> responseText:string")
+ * @param signature - The input/output signature as a string or AxSignature object
  * @param config - Configuration options for the agent
  * @returns A typed agent instance
  *
  * @example
  * ```typescript
+ * // Using string signature
  * const myAgent = agent('userInput:string -> responseText:string', {
  *   name: 'myAgent',
  *   description: 'An agent that processes user input and returns a response',
  *   definition: 'You are a helpful assistant that responds to user queries...'
  * });
  *
+ * // Using AxSignature object
+ * const sig = s('userInput:string -> responseText:string');
+ * const myAgent2 = agent(sig, {
+ *   name: 'myAgent2',
+ *   description: 'Same agent but using AxSignature object'
+ * });
+ *
  * // With child agents
  * const parentAgent = agent('taskDescription:string -> completedTask:string', {
  *   name: 'parentAgent',
@@ -7217,6 +7300,7 @@ interface AxAgentConfig<IN extends AxGenIn, OUT extends AxGenOut> extends AxAgen
  * ```
  */
 declare function agent<const T extends string>(signature: T, config: AxAgentConfig<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>): AxAgent<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
+declare function agent<TInput extends Record<string, any>, TOutput extends Record<string, any>>(signature: AxSignature<TInput, TOutput>, config: AxAgentConfig<TInput, TOutput>): AxAgent<TInput, TOutput>;
 
 /**
  * Advanced Multi-hop RAG with iterative query refinement, context accumulation,