@ax-llm/ax 16.0.11 → 16.0.12

package/index.d.cts

@@ -30,6 +30,8 @@ interface AxAPIConfig extends AxAPI, RequestValidation, ResponseValidation {
     retry?: Partial<RetryConfig>;
     abortSignal?: AbortSignal;
     corsProxy?: string;
+    /** Whether to include request body in error messages. Defaults to true. Set to false when request may contain sensitive data or large base64 content. */
+    includeRequestBodyInErrors?: boolean;
 }
 declare class AxAIServiceError extends Error {
     readonly url: string;
@@ -38,36 +40,37 @@ declare class AxAIServiceError extends Error {
     readonly timestamp: string;
     readonly errorId: string;
     readonly context: Record<string, unknown>;
-    constructor(message: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>);
+    readonly includeRequestBodyInErrors: boolean;
+    constructor(message: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
     toString(): string;
 }
 declare class AxAIServiceStatusError extends AxAIServiceError {
     readonly status: number;
     readonly statusText: string;
-    constructor(status: number, statusText: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, retryCount?: number);
+    constructor(status: number, statusText: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, retryCount?: number, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceNetworkError extends AxAIServiceError {
     readonly originalError: Error;
-    constructor(originalError: Error, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>);
+    constructor(originalError: Error, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceResponseError extends AxAIServiceError {
-    constructor(message: string, url: string, requestBody?: unknown, context?: Record<string, unknown>);
+    constructor(message: string, url: string, requestBody?: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceStreamTerminatedError extends AxAIServiceError {
     readonly lastChunk?: unknown | undefined;
-    constructor(url: string, requestBody?: unknown, lastChunk?: unknown | undefined, context?: Record<string, unknown>);
+    constructor(url: string, requestBody?: unknown, lastChunk?: unknown | undefined, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceTimeoutError extends AxAIServiceError {
-    constructor(url: string, timeoutMs: number, requestBody?: unknown, context?: Record<string, unknown>);
+    constructor(url: string, timeoutMs: number, requestBody?: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxTokenLimitError extends AxAIServiceStatusError {
-    constructor(status: number, statusText: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>);
+    constructor(status: number, statusText: string, url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceAbortedError extends AxAIServiceError {
-    constructor(url: string, reason?: string, requestBody?: unknown, context?: Record<string, unknown>);
+    constructor(url: string, reason?: string, requestBody?: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIServiceAuthenticationError extends AxAIServiceError {
-    constructor(url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>);
+    constructor(url: string, requestBody: unknown, responseBody: unknown, context?: Record<string, unknown>, includeRequestBodyInErrors?: boolean);
 }
 declare class AxAIRefusalError extends Error {
     readonly refusalMessage: string;
@@ -210,16 +213,126 @@ type AxTokenUsage = {
     cacheReadTokens?: number;
     serviceTier?: 'standard' | 'priority' | 'batch';
 };
+/**
+ * Configuration options for AI model behavior.
+ *
+ * These settings control how the model generates responses. They can be set
+ * as defaults when creating an AI instance, or overridden per-request.
+ *
+ * @example
+ * ```typescript
+ * const config: AxModelConfig = {
+ *   maxTokens: 2000,
+ *   temperature: 0.7,
+ *   topP: 0.9
+ * };
+ * ```
+ */
 type AxModelConfig = {
+    /**
+     * Maximum number of tokens to generate in the response.
+     *
+     * **Token estimation guide:**
+     * - ~750 tokens ≈ 1 page of English text
+     * - ~100 tokens ≈ 75 words
+     * - ~4 characters ≈ 1 token (English)
+     *
+     * Set higher for long-form content (articles, code), lower for concise
+     * responses (classifications, short answers).
+     *
+     * @example 500 for short responses, 2000 for detailed explanations, 4000+ for long-form content
+     */
     maxTokens?: number;
+    /**
+     * Controls randomness in generation. Range: 0 to 2.
+     *
+     * **Use case guide:**
+     * - `0` - Deterministic, always picks most likely token. Best for factual Q&A,
+     *   classification, code generation where consistency matters.
+     * - `0.3-0.5` - Low creativity. Good for structured outputs, summaries.
+     * - `0.7` - Balanced (default for most models). Good for general conversation.
+     * - `1.0` - High creativity. Good for brainstorming, creative writing.
+     * - `1.5-2.0` - Very high randomness. Often produces incoherent output.
+     *
+     * @default Varies by provider, typically 0.7-1.0
+     */
     temperature?: number;
+    /**
+     * Nucleus sampling: only consider tokens with cumulative probability >= topP.
+     * Range: 0 to 1.
+     *
+     * Lower values make output more focused and deterministic. Alternative to
+     * temperature for controlling randomness.
+     *
+     * **Recommendation:** Adjust either temperature OR topP, not both.
+     *
+     * @example 0.1 for focused output, 0.9 for diverse output
+     */
     topP?: number;
+    /**
+     * Only consider the top K most likely tokens at each step.
+     *
+     * Lower values (e.g., 10-40) make output more focused. Not supported by all
+     * providers (OpenAI doesn't support this; Anthropic, Google do).
+     *
+     * @example 40 for focused output, 100 for more variety
+     */
     topK?: number;
+    /**
+     * Penalizes tokens that have already appeared in the output.
+     * Range: -2.0 to 2.0.
+     *
+     * Positive values reduce repetition by penalizing tokens that have appeared
+     * at all, regardless of frequency. Useful for encouraging diverse vocabulary.
+     *
+     * - `0` - No penalty (default)
+     * - `0.5-1.0` - Mild penalty, reduces obvious repetition
+     * - `1.5-2.0` - Strong penalty, may hurt coherence
+     *
+     * @example 0.6 to reduce repetitive phrasing
+     */
     presencePenalty?: number;
+    /**
+     * Penalizes tokens based on how frequently they've appeared.
+     * Range: -2.0 to 2.0.
+     *
+     * Unlike presencePenalty, this scales with frequency: tokens that appear many
+     * times get penalized more. Useful for preventing the model from repeating
+     * the same phrases verbatim.
+     *
+     * @example 0.5 to discourage word/phrase repetition
+     */
     frequencyPenalty?: number;
+    /**
+     * Sequences that will stop generation when encountered.
+     *
+     * The model stops generating as soon as any stop sequence is produced.
+     * The stop sequence itself is NOT included in the output.
+     *
+     * @example ['\\n\\n', 'END', '---'] to stop at double newlines or markers
+     */
     stopSequences?: string[];
+    /**
+     * Similar to stopSequences, but the sequence IS included in the output.
+     *
+     * @example ['</answer>'] to include closing tag in output
+     */
     endSequences?: string[];
+    /**
+     * Enable streaming responses for real-time output.
+     *
+     * When true, the response is returned as a stream of chunks, allowing
+     * you to display partial results as they're generated.
+     */
     stream?: boolean;
+    /**
+     * Number of completions to generate for each prompt.
+     *
+     * Generates multiple independent responses. Useful with result pickers
+     * to select the best response. Increases cost proportionally.
+     *
+     * @example 3 to generate three alternatives and pick the best
+     */
     n?: number;
 };
 type AxFunctionHandler = (args?: any, extra?: Readonly<{
@@ -652,42 +765,168 @@ type AxContextCacheInfo = {
     /** Hash of the cached content for validation */
     contentHash?: string;
 };
+/**
+ * Runtime options for AI service requests.
+ *
+ * These options control how requests are made to the AI service, including
+ * debugging, rate limiting, streaming, function calling, and extended thinking.
+ *
+ * @example
+ * ```typescript
+ * const options: AxAIServiceOptions = {
+ *   stream: true,
+ *   thinkingTokenBudget: 'medium',
+ *   debug: true
+ * };
+ * await gen.forward(ai, values, options);
+ * ```
+ */
 type AxAIServiceOptions = {
+    /**
+     * Enable debug logging for troubleshooting.
+     *
+     * When true, logs detailed information about prompts, responses, and
+     * the generation pipeline. Useful for understanding AI behavior.
+     */
     debug?: boolean;
+    /**
+     * Enable low-level HTTP request/response logging.
+     *
+     * More verbose than `debug`. Shows raw HTTP traffic including headers.
+     * Useful for debugging API issues.
+     */
     verbose?: boolean;
+    /** Custom rate limiter function to control request throughput. */
     rateLimiter?: AxRateLimiterFunction;
+    /** Custom fetch implementation (useful for proxies or custom HTTP handling). */
     fetch?: typeof fetch;
+    /** OpenTelemetry tracer for distributed tracing. */
     tracer?: Tracer;
+    /** OpenTelemetry meter for metrics collection. */
     meter?: Meter;
+    /**
+     * Request timeout in milliseconds.
+     *
+     * @default 300000 (5 minutes)
+     */
     timeout?: number;
+    /** Exclude message content from OpenTelemetry traces (for privacy). */
     excludeContentFromTrace?: boolean;
+    /** AbortSignal for cancelling in-flight requests. */
     abortSignal?: AbortSignal;
+    /** Custom logger function for debug output. */
     logger?: AxLoggerFunction;
+    /** Session identifier for conversation tracking and memory isolation. */
     sessionId?: string;
+    /** Hide system prompt in debug output (for cleaner logs). */
     debugHideSystemPrompt?: boolean;
+    /** OpenTelemetry trace context for distributed tracing. */
     traceContext?: Context;
+    /**
+     * Enable streaming responses.
+     *
+     * When true, the AI returns responses as a stream of chunks, enabling
+     * real-time display of generated text.
+     */
     stream?: boolean;
+    /**
+     * How to handle function/tool calling.
+     *
+     * - `'auto'` - Let the provider decide the best approach (default)
+     * - `'native'` - Use the provider's native function calling API. Fails if
+     *   the model doesn't support it.
+     * - `'prompt'` - Simulate function calling via prompt engineering. Works with
+     *   any model but may be less reliable.
+     *
+     * @default 'auto'
+     */
     functionCallMode?: 'auto' | 'native' | 'prompt';
+    /**
+     * Token budget for extended thinking (chain-of-thought reasoning).
+     *
+     * Extended thinking allows models to "think through" complex problems before
+     * responding. Higher budgets allow deeper reasoning but cost more.
+     *
+     * **Approximate token allocations:**
+     * - `'none'` - Disabled (default)
+     * - `'minimal'` - ~1,000 tokens (~750 words of thinking)
+     * - `'low'` - ~4,000 tokens
+     * - `'medium'` - ~10,000 tokens
+     * - `'high'` - ~20,000 tokens
+     * - `'highest'` - ~32,000+ tokens (provider maximum)
+     *
+     * **Provider support:**
+     * - Anthropic Claude: Full support with `claude-sonnet-4` and above
+     * - OpenAI: Supported with o1/o3 models (uses `reasoning_effort`)
+     * - Google: Supported with Gemini 2.0 Flash Thinking
+     * - DeepSeek: Supported with DeepSeek-R1
+     *
+     * @example
+     * ```typescript
+     * // Enable medium thinking for complex reasoning
+     * await gen.forward(ai, values, { thinkingTokenBudget: 'medium' });
+     * ```
+     */
     thinkingTokenBudget?: 'minimal' | 'low' | 'medium' | 'high' | 'highest' | 'none';
+    /**
+     * Include the model's thinking/reasoning in the output.
+     *
+     * When true and `thinkingTokenBudget` is set, the model's internal reasoning
+     * is included in the response. Useful for debugging and understanding AI behavior.
+     *
+     * @default false
+     */
     showThoughts?: boolean;
+    /**
+     * Hint to use a more capable (and expensive) model for complex tasks.
+     *
+     * Some providers offer tiered models. Setting this to 'yes' requests the
+     * higher-capability tier when available.
+     */
     useExpensiveModel?: 'yes';
+    /** Internal: Current step index for multi-step operations. */
     stepIndex?: number;
+    /**
+     * CORS proxy URL for browser environments.
+     *
+     * When running in a browser, API calls may be blocked by CORS. Specify a
+     * proxy URL to route requests through.
+     *
+     * @example 'https://cors-anywhere.herokuapp.com/'
+     */
     corsProxy?: string;
+    /**
+     * Retry configuration for failed requests.
+     *
+     * Controls automatic retry behavior for transient errors (rate limits,
+     * timeouts, server errors).
+     */
     retry?: Partial<RetryConfig>;
     /**
-     * Explicit context caching options.
-     * When enabled, large prompt prefixes can be cached for cost savings and lower latency.
-     * Currently supported by: Google Gemini/Vertex AI
+     * Context caching options for large prompt prefixes.
+     *
+     * When enabled, large prompt prefixes can be cached for cost savings and
+     * lower latency on subsequent requests.
+     *
+     * **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.
+     * Render examples/demos in the system prompt instead of as message pairs.
+     *
+     * - `false` (default) - Examples rendered as alternating user/assistant messages
+     * - `true` - Examples embedded in system prompt (legacy behavior)
+     *
+     * Message pair rendering generally produces better results.
      */
     examplesInSystem?: boolean;
     /**
-     * Custom labels to include in OpenTelemetry metrics.
-     * These labels are merged with axGlobals.customLabels (service-level overrides global).
+     * Custom labels for OpenTelemetry metrics.
+     *
+     * These labels are merged with `axGlobals.customLabels` (service-level
+     * options override global settings).
+     *
+     * @example { environment: 'production', feature: 'search' }
      */
     customLabels?: Record<string, string>;
 };
@@ -932,20 +1171,364 @@ type ValidateNoMediaTypes<TFields> = {
         fields: ValidateNoMediaTypes<TNestedFields>;
     } : TFields[K] : TFields[K] : TFields[K];
 };
+/**
+ * Fluent field builder for creating type-safe signature fields.
+ *
+ * The `f` object provides factory methods for all supported field types, each returning
+ * a chainable builder that allows adding constraints and modifiers.
+ *
+ * **Basic Usage:**
+ * When called as a function, `f()` returns a new `AxSignatureBuilder` for programmatic
+ * signature construction. More commonly, use its type methods directly.
+ *
+ * **Type Methods:**
+ * - `f.string(desc?)` - Text content
+ * - `f.number(desc?)` - Numeric values
+ * - `f.boolean(desc?)` - True/false values
+ * - `f.json(desc?)` - Arbitrary JSON objects
+ * - `f.datetime(desc?)` - ISO 8601 datetime strings
+ * - `f.date(desc?)` - Date in YYYY-MM-DD format
+ * - `f.class(options, desc?)` - Classification with predefined choices
+ * - `f.image(desc?)` - Image input (multimodal)
+ * - `f.audio(desc?)` - Audio input
+ * - `f.file(desc?)` - File input
+ * - `f.url(desc?)` - URL strings
+ * - `f.email(desc?)` - Email addresses
+ * - `f.code(language?, desc?)` - Code blocks
+ * - `f.object(fields, desc?)` - Nested object with typed fields
+ *
+ * **Modifier Methods (chainable):**
+ * - `.optional()` - Mark field as optional
+ * - `.array(desc?)` - Convert to array of this type
+ * - `.internal()` - Hide from final output (for intermediate reasoning)
+ * - `.cache()` - Mark for context caching
+ * - `.min(value)` - Minimum length (strings) or value (numbers)
+ * - `.max(value)` - Maximum length (strings) or value (numbers)
+ * - `.regex(pattern, desc)` - Regex validation for strings
+ * - `.email()` - Email format validation for strings
+ * - `.url()` - URL format validation for strings
+ *
+ * @example Basic field types
+ * ```typescript
+ * const sig = f()
+ *   .input('name', f.string('User name'))
+ *   .input('age', f.number('Age in years'))
+ *   .output('greeting', f.string('Personalized greeting'))
+ *   .build();
+ * ```
+ *
+ * @example With constraints
+ * ```typescript
+ * const sig = f()
+ *   .input('email', f.string().email())
+ *   .input('score', f.number('Score between 0-100').min(0).max(100))
+ *   .input('tags', f.string('Tag').array('List of tags'))
+ *   .output('isValid', f.boolean())
+ *   .build();
+ * ```
+ *
+ * @example Classification
+ * ```typescript
+ * const sig = f()
+ *   .input('text', f.string('Text to classify'))
+ *   .output('sentiment', f.class(['positive', 'negative', 'neutral'] as const))
+ *   .output('confidence', f.number().min(0).max(1))
+ *   .build();
+ * ```
+ *
+ * @example Nested objects
+ * ```typescript
+ * const sig = f()
+ *   .input('query', f.string())
+ *   .output('result', f.object({
+ *     title: f.string('Article title'),
+ *     score: f.number('Relevance score'),
+ *     metadata: f.object({
+ *       author: f.string().optional(),
+ *       date: f.date()
+ *     })
+ *   }))
+ *   .build();
+ * ```
+ *
+ * @example Optional and internal fields
+ * ```typescript
+ * const sig = f()
+ *   .input('context', f.string().optional())
+ *   .input('question', f.string())
+ *   .output('reasoning', f.string('Step-by-step thinking').internal())
+ *   .output('answer', f.string())
+ *   .build();
+ * ```
+ */
 declare const f: (() => AxSignatureBuilder) & {
+    /**
+     * Creates a string field type.
+     *
+     * Strings are the default and most common field type. Use modifiers to add
+     * validation constraints.
+     *
+     * @param desc - Optional description explaining the field's purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.string('User question')
+     * f.string().min(10).max(1000)  // Length constraints
+     * f.string().email()             // Email format
+     * f.string().regex('^[A-Z]', 'Must start with uppercase')
+     * ```
+     */
     string: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a number field type.
+     *
+     * Numbers can be integers or floats. Use `.min()` and `.max()` to constrain the range.
+     *
+     * @param desc - Optional description explaining the field's purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.number('Age in years')
+     * f.number().min(0).max(100)     // Constrained range
+     * f.number('Rating').min(1).max(5)
+     * ```
+     */
     number: (desc?: string) => AxFluentFieldType<"number", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a boolean field type.
+     *
+     * Booleans represent true/false values. Useful for yes/no questions,
+     * flags, and binary decisions.
+     *
+     * @param desc - Optional description explaining what true/false means
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.boolean('Whether the text contains personally identifiable information')
+     * f.boolean('Is the sentiment positive')
+     * ```
+     */
     boolean: (desc?: string) => AxFluentFieldType<"boolean", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a JSON field type for arbitrary structured data.
+     *
+     * Use this when you need flexible object output without a predefined schema.
+     * For structured data with known fields, prefer `f.object()` for type safety.
+     *
+     * @param desc - Optional description of the expected JSON structure
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.json('Extracted entities as key-value pairs')
+     * f.json('Configuration object')
+     * ```
+     */
     json: (desc?: string) => AxFluentFieldType<"json", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a datetime field type for ISO 8601 timestamps.
+     *
+     * Values are formatted as full ISO 8601 datetime strings (e.g., "2024-01-15T14:30:00Z").
+     * For date-only values, use `f.date()` instead.
+     *
+     * @param desc - Optional description explaining the datetime's purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.datetime('When the event occurred')
+     * f.datetime('Appointment start time')
+     * ```
+     */
     datetime: (desc?: string) => AxFluentFieldType<"datetime", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a date field type for YYYY-MM-DD formatted dates.
+     *
+     * Values are formatted as date strings without time components (e.g., "2024-01-15").
+     * For datetime values with time, use `f.datetime()` instead.
+     *
+     * @param desc - Optional description explaining the date's purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.date('Date of birth')
+     * f.date('Publication date')
+     * ```
+     */
     date: (desc?: string) => AxFluentFieldType<"date", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a classification field type with predefined options.
+     *
+     * The AI will always return exactly one of the provided options.
+     * Use `as const` for the options array to get literal type inference.
+     *
+     * @param options - Array of allowed values (use `as const` for type safety)
+     * @param desc - Optional description of the classification task
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.class(['positive', 'negative', 'neutral'] as const, 'Sentiment')
+     * f.class(['bug', 'feature', 'question', 'docs'] as const, 'Issue type')
+     * f.class(['low', 'medium', 'high', 'critical'] as const).optional()
+     * ```
+     */
     class: <const TOptions extends readonly string[]>(options: TOptions, desc?: string) => AxFluentFieldType<"class", false, TOptions, false, false, undefined, false>;
+    /**
+     * Creates an image field type for multimodal inputs.
+     *
+     * Pass images as base64-encoded data URLs or URLs to external images.
+     * Only supported as input fields with multimodal models (GPT-4V, Claude 3, Gemini, etc.).
+     *
+     * **Note:** Cannot be used in nested `f.object()` fields - only as top-level inputs.
+     *
+     * @param desc - Optional description of what the image contains or its purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.image('Product photo to analyze')
+     * f.image('Screenshot of the UI bug')
+     * f.image().array('Multiple images to compare')
+     * ```
+     */
     image: (desc?: string) => AxFluentFieldType<"image", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates an audio field type for audio inputs.
+     *
+     * Pass audio as base64-encoded data or URLs. Only supported as input fields
+     * with models that support audio processing.
+     *
+     * **Note:** Cannot be used in nested `f.object()` fields - only as top-level inputs.
+     *
+     * @param desc - Optional description of the audio content
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.audio('Voice recording to transcribe')
+     * f.audio('Audio clip for analysis')
+     * ```
+     */
     audio: (desc?: string) => AxFluentFieldType<"audio", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a file field type for document inputs.
+     *
+     * Pass files as base64-encoded data or file references. Only supported as input
+     * fields with models that support file processing (PDFs, documents, etc.).
+     *
+     * **Note:** Cannot be used in nested `f.object()` fields - only as top-level inputs.
+     *
+     * @param desc - Optional description of the expected file content
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.file('PDF document to summarize')
+     * f.file('Resume to parse')
+     * ```
+     */
     file: (desc?: string) => AxFluentFieldType<"file", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a URL field type with URI format validation.
+     *
+     * The AI will be instructed to return a valid URL. Use for outputs that
+     * should be clickable links or API endpoints.
+     *
+     * @param desc - Optional description of what the URL should point to
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.url('Link to the source')
+     * f.url('API endpoint URL')
+     * f.url().optional()
+     * ```
+     */
     url: (desc?: string) => AxFluentFieldType<"url", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates an email field type with email format validation.
+     *
+     * Shorthand for `f.string().email()`. The AI will be instructed to return
+     * a valid email address format.
+     *
+     * @param desc - Optional description of whose email or for what purpose
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.email('Contact email address')
+     * f.email().optional()
+     * ```
+     */
     email: (desc?: string) => AxFluentFieldType<"string", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a code field type for source code blocks.
+     *
+     * Code fields preserve formatting and are rendered in code blocks.
+     * Optionally specify a language for syntax highlighting context.
+     *
+     * @param language - Optional programming language (e.g., 'typescript', 'python')
+     * @param desc - Optional description of what the code should do
+     * @returns A chainable field builder
+     *
+     * @example
+     * ```typescript
+     * f.code('typescript', 'Generated TypeScript function')
+     * f.code('python', 'Python script to solve the problem')
+     * f.code()  // Language-agnostic code
+     * ```
+     */
     code: (language?: string, desc?: string) => AxFluentFieldType<"code", false, undefined, false, false, undefined, false>;
+    /**
+     * Creates a nested object field type with typed properties.
+     *
+     * Use this when you need structured output with known fields. Each property
+     * in the fields object should be created using `f.string()`, `f.number()`, etc.
+     *
+     * Objects can be nested to create complex hierarchical structures.
+     *
+     * **Restrictions:**
+     * - Media types (`image`, `audio`, `file`) cannot be used in nested objects
+     * - Deep nesting may reduce AI output quality
+     *
+     * @param fields - Object mapping field names to field types created with `f.*` methods
+     * @param desc - Optional description of what the object represents
+     * @returns A chainable field builder
+     *
+     * @example Simple object
+     * ```typescript
+     * f.object({
+     *   name: f.string('Person name'),
+     *   age: f.number('Age in years'),
+     *   isActive: f.boolean()
+     * }, 'User profile')
+     * ```
+     *
+     * @example Nested objects
+     * ```typescript
+     * f.object({
+     *   title: f.string(),
+     *   author: f.object({
+     *     name: f.string(),
+     *     email: f.email().optional()
+     *   }),
+     *   tags: f.string().array()
+     * })
+     * ```
+     *
+     * @example Array of objects
+     * ```typescript
+     * f.object({
+     *   item: f.string(),
+     *   quantity: f.number().min(1)
+     * }).array('List of order items')
+     * ```
+     */
     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 {
@@ -1662,14 +2245,104 @@ interface AxParetoResult<OUT = any> extends AxOptimizerResult<OUT> {
     paretoFrontSize: number;
     convergenceMetrics?: Record<string, number>;
 }
+/**
+ * Interface for optimizing AI programs through automated prompt tuning.
+ *
+ * Optimizers improve program performance by finding optimal demonstrations (few-shot examples)
+ * that guide the AI toward better outputs. The optimization process:
+ *
+ * 1. Runs the program on training examples
+ * 2. Evaluates outputs using the metric function
+ * 3. Selects high-scoring input/output pairs as demonstrations
+ * 4. Iterates to find the best demonstration set
+ *
+ * @example Basic optimization
+ * ```typescript
+ * const optimizer = new AxBootstrapFewShot({ maxBootstrappedDemos: 4 });
+ *
+ * const result = await optimizer.compile(
+ *   program,
+ *   trainingExamples,
+ *   ({ prediction, example }) => prediction.answer === example.expectedAnswer ? 1 : 0
+ * );
+ *
+ * // Apply optimized demos to program
+ * program.setDemos(result.demos);
+ * ```
+ */
 interface AxOptimizer {
     /**
-     * Optimize a program using the provided metric function
-     * @param program The program to optimize
-     * @param examples Training examples (typed based on the program) - will be auto-split into train/validation
-     * @param metricFn Evaluation metric function to assess program performance
-     * @param options Optional configuration options
-     * @returns Optimization result containing demos, stats, and configuration
+     * Optimize a program using the provided training examples and metric function.
+     *
+     * The optimizer runs the program on examples, scores the outputs, and builds
+     * a set of demonstrations that improve program performance. The process is
+     * automatic - you provide the data and metric, the optimizer does the rest.
+     *
+     * **Metric Function:**
+     * The metric function evaluates how well the program's output matches expectations.
+     * It receives the prediction and original example, and should return a score
+     * between 0 (worst) and 1 (best).
+     *
+     * @param program - The AxGen program to optimize. The optimizer will call
+     *   `.forward()` on this program during training.
+     *
+     * @param examples - Training examples with input values. Examples are automatically
+     *   split into training and validation sets. Each example should have the input
+     *   fields required by the program's signature.
+     *
+     * @param metricFn - Function that scores program outputs. Called with:
+     *   - `prediction`: The program's output for this example
+     *   - `example`: The original input example (useful if it contains expected outputs)
+     *   - Returns: Number between 0 (bad) and 1 (perfect)
+     *
+     * @param options - Optional configuration:
+     *   - `ai`: AI service to use (required if not set on program)
+     *   - `valSet`: Custom validation set (otherwise auto-split from examples)
+     *   - `trainSplit`: Fraction of examples for training (default: 0.8)
+     *
+     * @returns Promise resolving to optimization results including:
+     *   - `demos`: Optimized demonstrations to use with the program
+     *   - `stats`: Training/validation scores and iteration counts
+     *
+     * @example Exact match metric
+     * ```typescript
+     * const result = await optimizer.compile(
+     *   qa,
+     *   examples,
+     *   ({ prediction, example }) => {
+     *     return prediction.answer.toLowerCase() === example.expectedAnswer.toLowerCase() ? 1 : 0;
+     *   }
+     * );
+     * ```
+     *
+     * @example Semantic similarity metric
+     * ```typescript
+     * const result = await optimizer.compile(
+     *   summarizer,
+     *   examples,
+     *   async ({ prediction, example }) => {
+     *     const similarity = await computeCosineSimilarity(
+     *       await embed(prediction.summary),
+     *       await embed(example.referenceSummary)
+     *     );
+     *     return similarity; // 0-1 based on embedding similarity
+     *   }
+     * );
+     * ```
+     *
+     * @example Partial credit metric
+     * ```typescript
+     * const result = await optimizer.compile(
+     *   extractor,
+     *   examples,
+     *   ({ prediction, example }) => {
+     *     const expectedKeywords = example.keywords;
+     *     const foundKeywords = prediction.keywords;
+     *     const matches = expectedKeywords.filter(k => foundKeywords.includes(k));
+     *     return matches.length / expectedKeywords.length; // Fraction found
+     *   }
+     * );
+     * ```
      */
     compile<IN, OUT extends AxGenOut>(program: Readonly<AxGen<IN, OUT>>, examples: readonly AxTypedExample<IN>[], metricFn: AxMetricFn, options?: AxCompileOptions): Promise<AxOptimizerResult<OUT>>;
     /**
@@ -2114,6 +2787,97 @@ declare class AxGen<IN = any, OUT extends AxGenOut = any> extends AxProgram<IN,
      */
     private validateObjectFields;
     _forward1(ai: Readonly<AxAIService>, values: IN | AxMessage<IN>[], options: Readonly<AxProgramForwardOptions<any>>): AxGenStreamingOut<OUT>;
+    /**
+     * Executes the generator with the given AI service and input values.
+     *
+     * This is the main entry point for running an AI generation. The execution pipeline:
+     * 1. **Validate** - Check input values match the signature
+     * 2. **Render** - Build the prompt from signature, examples, and inputs
+     * 3. **Call** - Send the request to the AI service
+     * 4. **Parse** - Extract structured outputs from the response
+     * 5. **Assert** - Validate outputs and retry with error correction if needed
+     *
+     * @param ai - The AI service instance to use (created via `ai()` factory)
+     * @param values - Input values matching the signature's input fields, or an array of
+     *   `AxMessage` objects for multi-turn conversations
+     * @param options - Optional execution configuration
+     *
+     * @param options.model - Override the default model for this request
+     * @param options.maxTokens - Maximum tokens in the response. Rule of thumb: ~750 tokens ≈ 1 page
+     *   of English text. Set higher for long-form content, lower for concise responses.
+     * @param options.temperature - Controls randomness in generation (0-2):
+     *   - `0` - Deterministic, always picks most likely token (best for factual tasks)
+     *   - `0.3-0.7` - Balanced creativity (good for most tasks)
+     *   - `1.0+` - High creativity (good for brainstorming, creative writing)
+     *   - `2.0` - Maximum randomness (often incoherent)
+     * @param options.thinkingTokenBudget - Enable extended thinking for complex reasoning:
+     *   - `'none'` - Disabled (default)
+     *   - `'minimal'` - ~1K tokens of thinking
+     *   - `'low'` - ~4K tokens
+     *   - `'medium'` - ~10K tokens
+     *   - `'high'` - ~20K tokens
+     *   - `'highest'` - ~32K+ tokens (provider maximum)
+     * @param options.stream - Enable streaming responses for real-time output
+     * @param options.functions - Array of function tools the AI can call
+     * @param options.functionCallMode - How to handle function calling:
+     *   - `'auto'` - Let the provider decide (default)
+     *   - `'native'` - Force native function calling (if supported)
+     *   - `'prompt'` - Simulate via prompt engineering (for models without native support)
+     * @param options.mem - Memory instance for conversation history
+     * @param options.sessionId - Session identifier for memory isolation
+     * @param options.maxRetries - Maximum error correction attempts (default: 3)
+     * @param options.maxSteps - Maximum function call iterations (default: 10)
+     * @param options.debug - Enable debug logging
+     *
+     * @returns Promise resolving to the output values matching the signature's output fields
+     *
+     * @throws {AxValidationError} When input values don't match the signature
+     * @throws {AxAssertionError} When output parsing/validation fails after all retries
+     * @throws {AxAIServiceError} When the AI service request fails
+     *
+     * @example Basic usage
+     * ```typescript
+     * const gen = ax('question: string -> answer: string');
+     * const result = await gen.forward(ai, { question: 'What is 2+2?' });
+     * console.log(result.answer); // "4"
+     * ```
+     *
+     * @example With configuration
+     * ```typescript
+     * const result = await gen.forward(ai, { question: 'Explain quantum computing' }, {
+     *   maxTokens: 2000,
+     *   temperature: 0.3,
+     *   stream: true
+     * });
+     * ```
+     *
+     * @example Multi-turn conversation
+     * ```typescript
+     * const mem = new AxMemory();
+     * const chat = ax('message: string -> reply: string');
+     *
+     * await chat.forward(ai, { message: 'Hi, my name is Alice' }, { mem });
+     * const result = await chat.forward(ai, { message: 'What is my name?' }, { mem });
+     * // result.reply will reference "Alice" from conversation history
+     * ```
+     *
+     * @example With function calling
+     * ```typescript
+     * const result = await gen.forward(ai, values, {
+     *   functions: [{
+     *     name: 'getWeather',
+     *     description: 'Get current weather for a city',
+     *     parameters: {
+     *       type: 'object',
+     *       properties: { city: { type: 'string', description: 'City name' } },
+     *       required: ['city']
+     *     },
+     *     func: async ({ city }) => fetchWeather(city)
+     *   }],
+     *   maxSteps: 5
+     * });
+     * ```
+     */
     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>;
     setExamples(examples: Readonly<AxProgramExamples<IN, OUT>>, options?: Readonly<AxSetExamplesOptions>): void;
@@ -5807,17 +6571,80 @@ type InferTModelKey<T> = T extends {
     models: infer M;
 } ? ExtractModelKeysAndValues<M> : string;
 /**
- * Factory function for creating AxAI instances with type safety.
- * This is the recommended way to create AxAI instances instead of using the constructor.
+ * Factory function for creating AI service instances with full type safety.
  *
- * @param options - Configuration options for the AI service
- * @returns A properly typed AxAI instance
+ * This is the recommended way to create AI instances. It automatically selects
+ * the appropriate provider implementation based on the `name` field and provides
+ * type-safe access to provider-specific models.
  *
- * @example
+ * **Supported Providers:**
+ * - `'openai'` - OpenAI (GPT-4, GPT-4o, o1, o3, etc.)
+ * - `'openai-responses'` - OpenAI Responses API (for web search, file search)
+ * - `'anthropic'` - Anthropic (Claude 3.5 Sonnet, Claude 3 Opus, etc.)
+ * - `'google-gemini'` - Google (Gemini 1.5 Pro, Gemini 2.0 Flash, etc.)
+ * - `'azure-openai'` - Azure OpenAI Service
+ * - `'groq'` - Groq (Llama, Mixtral with fast inference)
+ * - `'cohere'` - Cohere (Command R+, embeddings)
+ * - `'mistral'` - Mistral AI (Mistral Large, Codestral)
+ * - `'deepseek'` - DeepSeek (DeepSeek-V3, DeepSeek-R1)
+ * - `'together'` - Together AI (various open models)
+ * - `'openrouter'` - OpenRouter (unified API for many providers)
+ * - `'ollama'` - Ollama (local models)
+ * - `'huggingface'` - Hugging Face Inference API
+ * - `'reka'` - Reka AI
+ * - `'grok'` - xAI Grok
+ * - `'webllm'` - WebLLM (browser-based inference)
+ *
+ * @param options - Provider-specific configuration. Must include `name` to identify the provider.
+ * @param options.name - The provider identifier (see list above)
+ * @param options.apiKey - API key for the provider (not needed for Ollama/WebLLM)
+ * @param options.config - Optional default model configuration (maxTokens, temperature, etc.)
+ * @param options.models - Optional custom model aliases for type-safe model selection
+ *
+ * @returns A configured AI service instance ready for chat completions and embeddings
+ *
+ * @see {@link AxModelConfig} for model configuration options
+ * @see {@link AxAIServiceOptions} for runtime options like streaming and function calling
+ *
+ * @example Basic OpenAI setup
  * ```typescript
  * const ai = ai({
  *   name: 'openai',
- *   apiKey: process.env.OPENAI_APIKEY!
+ *   apiKey: process.env.OPENAI_API_KEY
+ * });
+ * ```
+ *
+ * @example Anthropic with custom defaults
+ * ```typescript
+ * const ai = ai({
+ *   name: 'anthropic',
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   config: {
+ *     model: 'claude-sonnet-4-20250514',
+ *     maxTokens: 4096,
+ *     temperature: 0.7
+ *   }
+ * });
+ * ```
+ *
+ * @example Google Gemini with model aliases
+ * ```typescript
+ * const ai = ai({
+ *   name: 'google-gemini',
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   models: [
+ *     { key: 'fast', model: 'gemini-2.0-flash' },
+ *     { key: 'smart', model: 'gemini-1.5-pro' }
+ *   ]
+ * });
+ * // Now use ai with model: 'fast' or model: 'smart'
+ * ```
+ *
+ * @example Local models with Ollama
+ * ```typescript
+ * const ai = ai({
+ *   name: 'ollama',
+ *   config: { model: 'llama3.2' }
  * });
  * ```
  */
@@ -7246,7 +8073,105 @@ declare const AxStringUtil: {
     batchArray: <T>(arr: readonly T[], size: number) => T[][];
 };
 
+/**
+ * Creates a type-safe signature from a string template.
+ *
+ * @param signature - The signature string in the format `"inputFields -> outputFields"`
+ * @returns A typed AxSignature instance
+ *
+ * @example
+ * ```typescript
+ * const sig = s('question: string -> answer: string');
+ * ```
+ */
 declare function s<const T extends string>(signature: T): AxSignature<ParseSignature<T>['inputs'], ParseSignature<T>['outputs']>;
+/**
+ * Creates a type-safe AI generator from a signature string or AxSignature object.
+ *
+ * This is the primary way to define AI-powered functions in Ax. The signature string
+ * declares input and output fields with their types, which are then used to generate
+ * prompts and parse responses.
+ *
+ * **Signature String Format:**
+ * ```
+ * "inputField1: type, inputField2: type -> outputField1: type, outputField2: type"
+ * ```
+ *
+ * **Supported Field Types:**
+ * - `string` - Text content (default if no type specified)
+ * - `number` - Numeric values (integers or floats)
+ * - `boolean` - True/false values
+ * - `json` - Arbitrary JSON objects
+ * - `date` - Date in YYYY-MM-DD format
+ * - `datetime` - ISO 8601 datetime
+ * - `code` - Code blocks (preserves formatting)
+ * - `image` - Image input (for multimodal models)
+ * - `audio` - Audio input
+ * - `class` - Classification with predefined options: `class(option1, option2, option3)`
+ *
+ * **Type Modifiers:**
+ * - `[]` suffix - Array of values: `tags: string[]`
+ * - `?` suffix - Optional field: `context?: string`
+ * - `!` prefix - Internal field (hidden from output): `!reasoning: string`
+ *
+ * **Field Descriptions:**
+ * Add descriptions after the type using a string literal:
+ * ```
+ * "question: string 'The user question' -> answer: string 'A helpful response'"
+ * ```
+ *
+ * @param signature - Either a signature string or a pre-built AxSignature object
+ * @param options - Optional configuration for the generator
+ * @param options.thoughtFieldName - Custom name for chain-of-thought field (default: 'thought')
+ *
+ * @returns An AxGen instance that can be executed with `.forward(ai, inputs)`
+ *
+ * @example Simple question-answering
+ * ```typescript
+ * const qa = ax('question: string -> answer: string');
+ * const result = await qa.forward(ai, { question: 'What is TypeScript?' });
+ * console.log(result.answer);
+ * ```
+ *
+ * @example Classification with predefined options
+ * ```typescript
+ * const classifier = ax('text: string -> sentiment: class(positive, negative, neutral)');
+ * const result = await classifier.forward(ai, { text: 'I love this!' });
+ * console.log(result.sentiment); // 'positive'
+ * ```
+ *
+ * @example Multiple outputs with arrays
+ * ```typescript
+ * const extractor = ax(`
+ *   document: string ->
+ *   summary: string,
+ *   keywords: string[],
+ *   wordCount: number
+ * `);
+ * const result = await extractor.forward(ai, { document: longText });
+ * ```
+ *
+ * @example With chain-of-thought reasoning
+ * ```typescript
+ * const solver = ax('problem: string -> solution: string', {
+ *   thoughtFieldName: 'reasoning'
+ * });
+ * // Enable thinking in forward options to get step-by-step reasoning
+ * ```
+ *
+ * @example Using function tools
+ * ```typescript
+ * const agent = ax('query: string -> response: string');
+ * const result = await agent.forward(ai, { query: 'What is 25 * 4?' }, {
+ *   functions: [{
+ *     name: 'calculate',
+ *     description: 'Perform math calculations',
+ *     parameters: { type: 'object', properties: { expression: { type: 'string' } } },
+ *     func: ({ expression }) => eval(expression)
+ *   }]
+ * });
+ * ```
+ */
 declare function ax<const T extends string, ThoughtKey extends string = 'thought'>(signature: T, options?: Readonly<AxProgramForwardOptions<any> & {
     thoughtFieldName?: ThoughtKey;
 }>): AxGen<ParseSignature<T>['inputs'], ParseSignature<T>['outputs'] & (string extends ThoughtKey ? {