@ax-llm/ax 16.0.6 → 16.0.8

package/index.d.cts

@@ -680,6 +680,16 @@ type AxAIServiceOptions = {
      * Currently supported by: Google Gemini/Vertex AI
      */
     contextCache?: AxContextCacheOptions;
+    /**
+     * When true, examples/demos are embedded in system prompt (legacy).
+     * When false (default), they are rendered as alternating user/assistant message pairs.
+     */
+    examplesInSystem?: boolean;
+    /**
+     * Custom labels to include in OpenTelemetry metrics.
+     * These labels are merged with axGlobals.customLabels (service-level overrides global).
+     */
+    customLabels?: Record<string, string>;
 };
 interface AxAIService<TModel = unknown, TEmbedModel = unknown, TModelKey = string> {
     getId(): string;
@@ -813,14 +823,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, any, any> | AxFluentFieldType<any, 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, any> | AxFluentFieldType<any, 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, any, any> | AxFluentFieldType<any, 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, any> | AxFluentFieldType<any, 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
@@ -835,13 +845,14 @@ 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, TFields extends Record<string, AxFluentFieldInfo | AxFluentFieldType> | undefined = undefined> 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, TIsCached extends boolean = false> implements AxFieldType {
     readonly type: TType;
     readonly isArray: TIsArray;
     readonly options?: TOptions;
     readonly description?: string;
     readonly isOptional: TIsOptional;
     readonly isInternal: TIsInternal;
+    readonly isCached: TIsCached;
     readonly fields?: any;
     readonly minLength?: number;
     readonly maxLength?: number;
@@ -859,6 +870,7 @@ declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType[
         itemDescription?: string;
         isOptional: TIsOptional;
         isInternal: TIsInternal;
+        isCached: TIsCached;
         fields?: TFields;
         minLength?: number;
         maxLength?: number;
@@ -868,39 +880,45 @@ declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType[
         patternDescription?: string;
         format?: string;
     });
-    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>;
+    optional(): AxFluentFieldType<TType, TIsArray, TOptions, true, TIsInternal, TFields, TIsCached>;
+    array(desc?: string): AxFluentFieldType<TType, true, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
+    internal(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, true, TFields, TIsCached>;
+    /**
+     * Mark this input field for caching. When contextCache is enabled,
+     * cached fields are rendered in a separate user message with cache: true,
+     * allowing them to be cached by the LLM provider.
+     */
+    cache(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, true>;
     /**
      * Set minimum value for numbers or minimum length for strings
      */
-    min(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    min(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set maximum value for numbers or maximum length for strings
      */
-    max(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    max(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set email format validation for strings
      */
-    email(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    email(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set URL/URI format validation for strings
      */
-    url(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    url(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * 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>;
+    regex(pattern: string, description: string): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set date format validation for strings
      */
-    date(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    date(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set datetime format validation for strings
      */
-    datetime(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    datetime(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
 }
 type ValidateNoMediaTypes<TFields> = {
     [K in keyof TFields]: TFields[K] extends {
@@ -915,20 +933,20 @@ type ValidateNoMediaTypes<TFields> = {
     } : TFields[K] : TFields[K] : TFields[K];
 };
 declare const f: (() => AxSignatureBuilder) & {
-    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>;
+    string: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    number: (desc?: string) => AxFluentFieldType<"number", false, undefined, false, false, undefined, false>;
+    boolean: (desc?: string) => AxFluentFieldType<"boolean", false, undefined, false, false, undefined, false>;
+    json: (desc?: string) => AxFluentFieldType<"json", false, undefined, false, false, undefined, false>;
+    datetime: (desc?: string) => AxFluentFieldType<"datetime", false, undefined, false, false, undefined, false>;
+    date: (desc?: string) => AxFluentFieldType<"date", false, undefined, false, false, undefined, false>;
+    class: <const TOptions extends readonly string[]>(options: TOptions, desc?: string) => AxFluentFieldType<"class", false, TOptions, false, false, undefined, false>;
+    image: (desc?: string) => AxFluentFieldType<"image", false, undefined, false, false, undefined, false>;
+    audio: (desc?: string) => AxFluentFieldType<"audio", false, undefined, false, false, undefined, false>;
+    file: (desc?: string) => AxFluentFieldType<"file", false, undefined, false, false, undefined, false>;
+    url: (desc?: string) => AxFluentFieldType<"url", false, undefined, false, false, undefined, false>;
+    email: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    code: (language?: string, desc?: string) => AxFluentFieldType<"code", false, undefined, false, false, undefined, false>;
+    object: <TFields extends Record<string, AxFluentFieldInfo<any, any, any, any, any, any, any> | AxFluentFieldType<any, any, any, any, any, any, any>>>(fields: TFields & ValidateNoMediaTypes<TFields>, desc?: string) => AxFluentFieldType<"object", false, undefined, false, false, TFields, false>;
 };
 interface AxField {
     name: string;
@@ -950,6 +968,7 @@ interface AxField {
     };
     isOptional?: boolean;
     isInternal?: boolean;
+    isCached?: boolean;
 }
 type AxIField = Omit<AxField, 'title'> & {
     title: string;
@@ -985,7 +1004,7 @@ type InferFieldValueType<T> = T extends AxFieldType | AxFluentFieldType ? T['typ
 }[] : {
     [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> {
+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, _TIsCached extends boolean = false> {
     readonly type: TType;
     readonly isArray?: TIsArray;
     readonly options?: TOptions;
@@ -994,6 +1013,7 @@ interface AxFluentFieldInfo<TType extends AxFieldType['type'] = AxFieldType['typ
     readonly itemDescription?: string;
     readonly isOptional?: TIsOptional;
     readonly isInternal?: boolean;
+    readonly isCached?: boolean;
     readonly minLength?: number;
     readonly maxLength?: number;
     readonly minimum?: number;
@@ -1509,6 +1529,11 @@ interface AxCompileOptions {
     skipPerfectScore?: boolean;
     perfectScore?: number;
     maxMetricCalls?: number;
+    /**
+     * Custom labels to include in OpenTelemetry metrics.
+     * These labels are merged with axGlobals.customLabels and AI service customLabels.
+     */
+    customLabels?: Record<string, string>;
 }
 
 interface AxOptimizerMetricsConfig {
@@ -1780,6 +1805,11 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     protected readonly metricsInstruments?: AxOptimizerMetricsInstruments;
     private resultExplainer?;
     constructor(args: Readonly<AxOptimizerArgs>);
+    /**
+     * Get merged custom labels from globals, AI services, and compile options.
+     * Labels are merged with later sources overriding earlier ones.
+     */
+    protected getMergedCustomLabels(options?: AxCompileOptions): Record<string, string>;
     /**
      * Initialize the result explanation generator
      * FIXME: Disabled due to circular dependency with ax() function
@@ -1808,7 +1838,7 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     /**
      * Trigger early stopping with appropriate callbacks
      */
-    protected triggerEarlyStopping(reason: string, bestScoreRound: number): void;
+    protected triggerEarlyStopping(reason: string, bestScoreRound: number, options?: AxCompileOptions): void;
     /**
      * Validate that examples meet minimum requirements for optimization
      * @param examples Examples to validate
@@ -1934,35 +1964,35 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     /**
      * Record optimization start metrics
      */
-    protected recordOptimizationStart(optimizerType: string, programSignature?: string): void;
+    protected recordOptimizationStart(optimizerType: string, programSignature?: string, options?: AxCompileOptions): void;
     /**
      * Record optimization completion metrics
      */
-    protected recordOptimizationComplete(duration: number, success: boolean, optimizerType: string, programSignature?: string): void;
+    protected recordOptimizationComplete(duration: number, success: boolean, optimizerType: string, programSignature?: string, options?: AxCompileOptions): void;
     /**
      * Record convergence metrics
      */
-    protected recordConvergenceMetrics(rounds: number, currentScore: number, improvement: number, stagnationRounds: number, optimizerType: string): void;
+    protected recordConvergenceMetrics(rounds: number, currentScore: number, improvement: number, stagnationRounds: number, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record early stopping metrics
      */
-    protected recordEarlyStoppingMetrics(reason: string, optimizerType: string): void;
+    protected recordEarlyStoppingMetrics(reason: string, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record teacher-student interaction metrics
      */
-    protected recordTeacherStudentMetrics(latency: number, scoreImprovement: number, optimizerType: string): void;
+    protected recordTeacherStudentMetrics(latency: number, scoreImprovement: number, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record checkpoint metrics
      */
-    protected recordCheckpointMetrics(operation: 'save' | 'load', latency: number, success: boolean, optimizerType: string): void;
+    protected recordCheckpointMetrics(operation: 'save' | 'load', latency: number, success: boolean, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record Pareto optimization metrics
      */
-    protected recordParetoMetrics(frontSize: number, solutionsGenerated: number, optimizerType: string, hypervolume?: number): void;
+    protected recordParetoMetrics(frontSize: number, solutionsGenerated: number, optimizerType: string, hypervolume?: number, options?: AxCompileOptions): void;
     /**
      * Record performance metrics
      */
-    protected recordPerformanceMetrics(metricType: 'evaluation' | 'demo_generation' | 'metric_computation', duration: number, optimizerType: string): void;
+    protected recordPerformanceMetrics(metricType: 'evaluation' | 'demo_generation' | 'metric_computation', duration: number, optimizerType: string, options?: AxCompileOptions): void;
     protected isOptimizerLoggingEnabled(options?: AxCompileOptions): boolean;
     protected getOptimizerLogger(options?: AxCompileOptions): AxOptimizerLoggerFunction | undefined;
     getStats(): AxOptimizationStats;
@@ -2055,6 +2085,7 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
     getInstruction(): string | undefined;
     private getSignatureName;
     private getMetricsInstruments;
+    private getMergedCustomLabels;
     updateMeter(meter?: Meter): void;
     private createStates;
     addAssert: (fn: AxAssertion<OUT>["fn"], message?: string) => void;
@@ -2118,6 +2149,8 @@ interface AxPromptTemplateOptions {
     contextCache?: AxContextCacheOptions;
     /** When true, examples/demos are embedded in system prompt (legacy). When false (default), they are rendered as alternating user/assistant message pairs. */
     examplesInSystem?: boolean;
+    /** When true, cacheBreakpoint is ignored and cache is applied to all positions (for providers with auto-lookback like Anthropic) */
+    ignoreBreakpoints?: boolean;
 }
 type AxChatRequestChatPrompt = Writeable<AxChatRequest['chatPrompt'][0]>;
 type ChatRequestUserMessage = Exclude<Extract<AxChatRequestChatPrompt, {
@@ -2135,7 +2168,13 @@ declare class AxPromptTemplate {
     private readonly functions?;
     private readonly contextCache?;
     private readonly examplesInSystem;
+    private readonly ignoreBreakpoints;
     constructor(sig: Readonly<AxSignature>, options?: Readonly<AxPromptTemplateOptions>, fieldTemplates?: Record<string, AxFieldTemplateFn>);
+    /**
+     * Sort fields so that cached fields come first.
+     * Uses stable sort to preserve relative order among cached and non-cached fields.
+     */
+    private sortFieldsCachedFirst;
     /**
      * Build legacy prompt format (backward compatible)
      */
@@ -2627,6 +2666,8 @@ interface AxAIFeatures {
         supported: boolean;
         /** Types of caching available */
         types: ('ephemeral' | 'persistent')[];
+        /** Whether explicit cache breakpoints are needed. If false, provider has automatic lookback and cache_control is always applied to system and last tool when caching is detected. Defaults to true. */
+        cacheBreakpoints?: boolean;
     };
     /** Whether the provider supports thinking/reasoning modes */
     thinking: boolean;
@@ -2662,6 +2703,7 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     private logger;
     private corsProxy?;
     private retry?;
+    private customLabels?;
     private modelInfo;
     private modelUsage?;
     private embedModelUsage?;
@@ -2685,6 +2727,7 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     setOptions(options: Readonly<AxAIServiceOptions>): void;
     getOptions(): Readonly<AxAIServiceOptions>;
     getLogger(): AxLoggerFunction;
+    private getMergedCustomLabels;
     getModelList(): ({
         readonly key: TModelKey;
         readonly description: string;
@@ -6138,6 +6181,7 @@ declare const axGlobals: {
     optimizerLogger: AxOptimizerLoggerFunction | undefined;
     debug: boolean | undefined;
     abortSignal: AbortSignal | undefined;
+    customLabels: Record<string, string> | undefined;
     cachingFunction: ((key: string, value?: AxGenOut) => AxGenOut | undefined | Promise<AxGenOut | undefined>) | undefined;
     functionResultFormatter: AxFunctionResultFormatter;
 };

package/index.d.ts

@@ -680,6 +680,16 @@ type AxAIServiceOptions = {
      * Currently supported by: Google Gemini/Vertex AI
      */
     contextCache?: AxContextCacheOptions;
+    /**
+     * When true, examples/demos are embedded in system prompt (legacy).
+     * When false (default), they are rendered as alternating user/assistant message pairs.
+     */
+    examplesInSystem?: boolean;
+    /**
+     * Custom labels to include in OpenTelemetry metrics.
+     * These labels are merged with axGlobals.customLabels (service-level overrides global).
+     */
+    customLabels?: Record<string, string>;
 };
 interface AxAIService<TModel = unknown, TEmbedModel = unknown, TModelKey = string> {
     getId(): string;
@@ -813,14 +823,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, any, any> | AxFluentFieldType<any, 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, any> | AxFluentFieldType<any, 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, any, any> | AxFluentFieldType<any, 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, any> | AxFluentFieldType<any, 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
@@ -835,13 +845,14 @@ 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, TFields extends Record<string, AxFluentFieldInfo | AxFluentFieldType> | undefined = undefined> 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, TIsCached extends boolean = false> implements AxFieldType {
     readonly type: TType;
     readonly isArray: TIsArray;
     readonly options?: TOptions;
     readonly description?: string;
     readonly isOptional: TIsOptional;
     readonly isInternal: TIsInternal;
+    readonly isCached: TIsCached;
     readonly fields?: any;
     readonly minLength?: number;
     readonly maxLength?: number;
@@ -859,6 +870,7 @@ declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType[
         itemDescription?: string;
         isOptional: TIsOptional;
         isInternal: TIsInternal;
+        isCached: TIsCached;
         fields?: TFields;
         minLength?: number;
         maxLength?: number;
@@ -868,39 +880,45 @@ declare class AxFluentFieldType<TType extends AxFieldType['type'] = AxFieldType[
         patternDescription?: string;
         format?: string;
     });
-    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>;
+    optional(): AxFluentFieldType<TType, TIsArray, TOptions, true, TIsInternal, TFields, TIsCached>;
+    array(desc?: string): AxFluentFieldType<TType, true, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
+    internal(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, true, TFields, TIsCached>;
+    /**
+     * Mark this input field for caching. When contextCache is enabled,
+     * cached fields are rendered in a separate user message with cache: true,
+     * allowing them to be cached by the LLM provider.
+     */
+    cache(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, true>;
     /**
      * Set minimum value for numbers or minimum length for strings
      */
-    min(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    min(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set maximum value for numbers or maximum length for strings
      */
-    max(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    max(value: number): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set email format validation for strings
      */
-    email(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    email(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set URL/URI format validation for strings
      */
-    url(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    url(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * 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>;
+    regex(pattern: string, description: string): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set date format validation for strings
      */
-    date(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    date(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
     /**
      * Set datetime format validation for strings
      */
-    datetime(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields>;
+    datetime(): AxFluentFieldType<TType, TIsArray, TOptions, TIsOptional, TIsInternal, TFields, TIsCached>;
 }
 type ValidateNoMediaTypes<TFields> = {
     [K in keyof TFields]: TFields[K] extends {
@@ -915,20 +933,20 @@ type ValidateNoMediaTypes<TFields> = {
     } : TFields[K] : TFields[K] : TFields[K];
 };
 declare const f: (() => AxSignatureBuilder) & {
-    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>;
+    string: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    number: (desc?: string) => AxFluentFieldType<"number", false, undefined, false, false, undefined, false>;
+    boolean: (desc?: string) => AxFluentFieldType<"boolean", false, undefined, false, false, undefined, false>;
+    json: (desc?: string) => AxFluentFieldType<"json", false, undefined, false, false, undefined, false>;
+    datetime: (desc?: string) => AxFluentFieldType<"datetime", false, undefined, false, false, undefined, false>;
+    date: (desc?: string) => AxFluentFieldType<"date", false, undefined, false, false, undefined, false>;
+    class: <const TOptions extends readonly string[]>(options: TOptions, desc?: string) => AxFluentFieldType<"class", false, TOptions, false, false, undefined, false>;
+    image: (desc?: string) => AxFluentFieldType<"image", false, undefined, false, false, undefined, false>;
+    audio: (desc?: string) => AxFluentFieldType<"audio", false, undefined, false, false, undefined, false>;
+    file: (desc?: string) => AxFluentFieldType<"file", false, undefined, false, false, undefined, false>;
+    url: (desc?: string) => AxFluentFieldType<"url", false, undefined, false, false, undefined, false>;
+    email: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    code: (language?: string, desc?: string) => AxFluentFieldType<"code", false, undefined, false, false, undefined, false>;
+    object: <TFields extends Record<string, AxFluentFieldInfo<any, any, any, any, any, any, any> | AxFluentFieldType<any, any, any, any, any, any, any>>>(fields: TFields & ValidateNoMediaTypes<TFields>, desc?: string) => AxFluentFieldType<"object", false, undefined, false, false, TFields, false>;
 };
 interface AxField {
     name: string;
@@ -950,6 +968,7 @@ interface AxField {
     };
     isOptional?: boolean;
     isInternal?: boolean;
+    isCached?: boolean;
 }
 type AxIField = Omit<AxField, 'title'> & {
     title: string;
@@ -985,7 +1004,7 @@ type InferFieldValueType<T> = T extends AxFieldType | AxFluentFieldType ? T['typ
 }[] : {
     [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> {
+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, _TIsCached extends boolean = false> {
     readonly type: TType;
     readonly isArray?: TIsArray;
     readonly options?: TOptions;
@@ -994,6 +1013,7 @@ interface AxFluentFieldInfo<TType extends AxFieldType['type'] = AxFieldType['typ
     readonly itemDescription?: string;
     readonly isOptional?: TIsOptional;
     readonly isInternal?: boolean;
+    readonly isCached?: boolean;
     readonly minLength?: number;
     readonly maxLength?: number;
     readonly minimum?: number;
@@ -1509,6 +1529,11 @@ interface AxCompileOptions {
     skipPerfectScore?: boolean;
     perfectScore?: number;
     maxMetricCalls?: number;
+    /**
+     * Custom labels to include in OpenTelemetry metrics.
+     * These labels are merged with axGlobals.customLabels and AI service customLabels.
+     */
+    customLabels?: Record<string, string>;
 }
 
 interface AxOptimizerMetricsConfig {
@@ -1780,6 +1805,11 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     protected readonly metricsInstruments?: AxOptimizerMetricsInstruments;
     private resultExplainer?;
     constructor(args: Readonly<AxOptimizerArgs>);
+    /**
+     * Get merged custom labels from globals, AI services, and compile options.
+     * Labels are merged with later sources overriding earlier ones.
+     */
+    protected getMergedCustomLabels(options?: AxCompileOptions): Record<string, string>;
     /**
      * Initialize the result explanation generator
      * FIXME: Disabled due to circular dependency with ax() function
@@ -1808,7 +1838,7 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     /**
      * Trigger early stopping with appropriate callbacks
      */
-    protected triggerEarlyStopping(reason: string, bestScoreRound: number): void;
+    protected triggerEarlyStopping(reason: string, bestScoreRound: number, options?: AxCompileOptions): void;
     /**
      * Validate that examples meet minimum requirements for optimization
      * @param examples Examples to validate
@@ -1934,35 +1964,35 @@ declare abstract class AxBaseOptimizer implements AxOptimizer {
     /**
      * Record optimization start metrics
      */
-    protected recordOptimizationStart(optimizerType: string, programSignature?: string): void;
+    protected recordOptimizationStart(optimizerType: string, programSignature?: string, options?: AxCompileOptions): void;
     /**
      * Record optimization completion metrics
      */
-    protected recordOptimizationComplete(duration: number, success: boolean, optimizerType: string, programSignature?: string): void;
+    protected recordOptimizationComplete(duration: number, success: boolean, optimizerType: string, programSignature?: string, options?: AxCompileOptions): void;
     /**
      * Record convergence metrics
      */
-    protected recordConvergenceMetrics(rounds: number, currentScore: number, improvement: number, stagnationRounds: number, optimizerType: string): void;
+    protected recordConvergenceMetrics(rounds: number, currentScore: number, improvement: number, stagnationRounds: number, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record early stopping metrics
      */
-    protected recordEarlyStoppingMetrics(reason: string, optimizerType: string): void;
+    protected recordEarlyStoppingMetrics(reason: string, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record teacher-student interaction metrics
      */
-    protected recordTeacherStudentMetrics(latency: number, scoreImprovement: number, optimizerType: string): void;
+    protected recordTeacherStudentMetrics(latency: number, scoreImprovement: number, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record checkpoint metrics
      */
-    protected recordCheckpointMetrics(operation: 'save' | 'load', latency: number, success: boolean, optimizerType: string): void;
+    protected recordCheckpointMetrics(operation: 'save' | 'load', latency: number, success: boolean, optimizerType: string, options?: AxCompileOptions): void;
     /**
      * Record Pareto optimization metrics
      */
-    protected recordParetoMetrics(frontSize: number, solutionsGenerated: number, optimizerType: string, hypervolume?: number): void;
+    protected recordParetoMetrics(frontSize: number, solutionsGenerated: number, optimizerType: string, hypervolume?: number, options?: AxCompileOptions): void;
     /**
      * Record performance metrics
      */
-    protected recordPerformanceMetrics(metricType: 'evaluation' | 'demo_generation' | 'metric_computation', duration: number, optimizerType: string): void;
+    protected recordPerformanceMetrics(metricType: 'evaluation' | 'demo_generation' | 'metric_computation', duration: number, optimizerType: string, options?: AxCompileOptions): void;
     protected isOptimizerLoggingEnabled(options?: AxCompileOptions): boolean;
     protected getOptimizerLogger(options?: AxCompileOptions): AxOptimizerLoggerFunction | undefined;
     getStats(): AxOptimizationStats;
@@ -2055,6 +2085,7 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
     getInstruction(): string | undefined;
     private getSignatureName;
     private getMetricsInstruments;
+    private getMergedCustomLabels;
     updateMeter(meter?: Meter): void;
     private createStates;
     addAssert: (fn: AxAssertion<OUT>["fn"], message?: string) => void;
@@ -2118,6 +2149,8 @@ interface AxPromptTemplateOptions {
     contextCache?: AxContextCacheOptions;
     /** When true, examples/demos are embedded in system prompt (legacy). When false (default), they are rendered as alternating user/assistant message pairs. */
     examplesInSystem?: boolean;
+    /** When true, cacheBreakpoint is ignored and cache is applied to all positions (for providers with auto-lookback like Anthropic) */
+    ignoreBreakpoints?: boolean;
 }
 type AxChatRequestChatPrompt = Writeable<AxChatRequest['chatPrompt'][0]>;
 type ChatRequestUserMessage = Exclude<Extract<AxChatRequestChatPrompt, {
@@ -2135,7 +2168,13 @@ declare class AxPromptTemplate {
     private readonly functions?;
     private readonly contextCache?;
     private readonly examplesInSystem;
+    private readonly ignoreBreakpoints;
     constructor(sig: Readonly<AxSignature>, options?: Readonly<AxPromptTemplateOptions>, fieldTemplates?: Record<string, AxFieldTemplateFn>);
+    /**
+     * Sort fields so that cached fields come first.
+     * Uses stable sort to preserve relative order among cached and non-cached fields.
+     */
+    private sortFieldsCachedFirst;
     /**
      * Build legacy prompt format (backward compatible)
      */
@@ -2627,6 +2666,8 @@ interface AxAIFeatures {
         supported: boolean;
         /** Types of caching available */
         types: ('ephemeral' | 'persistent')[];
+        /** Whether explicit cache breakpoints are needed. If false, provider has automatic lookback and cache_control is always applied to system and last tool when caching is detected. Defaults to true. */
+        cacheBreakpoints?: boolean;
     };
     /** Whether the provider supports thinking/reasoning modes */
     thinking: boolean;
@@ -2662,6 +2703,7 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     private logger;
     private corsProxy?;
     private retry?;
+    private customLabels?;
     private modelInfo;
     private modelUsage?;
     private embedModelUsage?;
@@ -2685,6 +2727,7 @@ declare class AxBaseAI<TModel, TEmbedModel, TChatRequest, TEmbedRequest, TChatRe
     setOptions(options: Readonly<AxAIServiceOptions>): void;
     getOptions(): Readonly<AxAIServiceOptions>;
     getLogger(): AxLoggerFunction;
+    private getMergedCustomLabels;
     getModelList(): ({
         readonly key: TModelKey;
         readonly description: string;
@@ -6138,6 +6181,7 @@ declare const axGlobals: {
     optimizerLogger: AxOptimizerLoggerFunction | undefined;
     debug: boolean | undefined;
     abortSignal: AbortSignal | undefined;
+    customLabels: Record<string, string> | undefined;
     cachingFunction: ((key: string, value?: AxGenOut) => AxGenOut | undefined | Promise<AxGenOut | undefined>) | undefined;
     functionResultFormatter: AxFunctionResultFormatter;
 };