@ax-llm/ax 21.0.0 → 21.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "21.0.0",
+  "version": "21.0.3",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {
@@ -14,8 +14,7 @@
   "keywords": [],
   "types": "./index.d.ts",
   "dependencies": {
-    "@opentelemetry/api": "^1.9.0",
-    "dayjs": "^1.11.13"
+    "@opentelemetry/api": "^1.9.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"

package/skills/ax-agent-optimize.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-optimize
 description: This skill helps an LLM generate correct AxAgent tuning and evaluation code using @ax-llm/ax. Use when the user asks about agent.optimize(...), judgeOptions, eval datasets, optimization targets, saved optimizedProgram artifacts, or recursive optimization guidance.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps an LLM generate correct AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, shared fields, llmQuery(...), RLM code execution, recursionOptions, or agent runtime behavior. For tuning and eval with agent.optimize(...), use ax-agent-optimize.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -462,7 +462,7 @@ const dbTool = fn('queryUsers')
 
 const myAgent = agent('query:string -> answer:string', {
   contextFields: [],
-  functions: { local: [dbTool] },
+  functions: [dbTool],
   bubbleErrors: [DatabaseError, AuthError],
 });
 
@@ -535,11 +535,8 @@ const analyst = agent('context:string, query:string -> answer:string', {
     namespace: 'team',
   },
   contextFields: ['context'],
-  agents: { local: [writer] },
-  functions: {
-    discovery: true,
-    local: tools,
-  },
+  functions: [writer, ...tools],
+  functionDiscovery: true,
 });
 ```
 
@@ -720,7 +717,7 @@ const tools = [
 const harness = agent('query:string -> answer:string', {
   contextFields: ['query'],
   runtime,
-  functions: { local: tools },
+  functions: tools,
   contextPolicy: { preset: 'checkpointed', budget: 'balanced' },
 });
 
@@ -893,8 +890,7 @@ Use `onFunctionCall` when the caller wants to observe every function call the ac
 const supportAgent = agent('query:string -> answer:string', {
   contextFields: ['query'],
   runtime,
-  agents: [helperAgent],
-  functions: [{ name: 'lookupOrder', namespace: 'tools', /* ... */ }],
+  functions: [helperAgent, { name: 'lookupOrder', namespace: 'tools', /* ... */ }],
   onFunctionCall: ({ name, qualifiedName, args, kind }) => {
     console.log(`[${kind}] ${qualifiedName}`, args);
   },
@@ -1211,9 +1207,9 @@ await final("Summarize severity findings", { snippets });
 
 Reason: this mixes observation and follow-up work in one turn.
 
-## Shared Fields
+## Threading Parent Fields Into Child Agents
 
-If a child agent requires a parent field such as `audience`, prefer shared fields:
+If a child agent requires a parent field such as `audience`, declare it on the child's signature and pass it explicitly when calling the child from the actor:
 
 ```typescript
 const writingCoach = agent(
@@ -1222,6 +1218,7 @@ const writingCoach = agent(
     agentIdentity: {
       name: 'Writing Coach',
       description: 'Polishes summaries for a target audience',
+      namespace: 'team',
     },
     contextFields: [],
   }
@@ -1230,50 +1227,55 @@ const writingCoach = agent(
 const analyst = agent(
   'context:string, audience:string, query:string -> answer:string',
   {
-    agents: { local: [writingCoach] },
-    fields: { shared: ['audience'] },
+    functions: [writingCoach],
     contextFields: ['context'],
   }
 );
 ```
 
-Generated runtime call:
+Generated runtime call (note: namespace comes from the child's `agentIdentity.namespace`; falls back to `utils` if unset):
 
 ```javascript
-const polished = await agents.writingCoach({ draft: summary });
+const polished = await team.writingCoach({
+  draft: summary,
+  audience: inputs.audience,
+});
 ```
 
 Rules:
 
-- Use `fields.shared` for direct children.
-- Use `fields.globallyShared` for all descendants.
-- Do not manually thread a parent field on every child call when shared fields fit the use case.
+- Pass parent fields explicitly via the call site — `inputs.<field>`.
+- If many children need the same field on every call, use `inputUpdateCallback` to inject the value before each executor turn.
+- Do not assume any auto-propagation: child agents receive only the args the actor passes.
 
-## Shared Agents And Shared Functions
+## Grouped Function Modules
 
-Use grouped config:
+For discovery mode, you can group functions into modules using the `AxAgentFunctionGroup` shape — handy when you want a clean `kb.find(...)`, `metrics.score(...)` namespace tree without setting `namespace` on every individual `fn(...)`:
 
 ```typescript
 const parent = agent('query:string -> answer:string', {
-  agents: {
-    local: [worker],
-    shared: [logger],
-    globallyShared: [auditor],
-  },
-  functions: {
-    local: [searchTool],
-    shared: [scoreTool],
-    globallyShared: [traceTool],
-  },
+  functions: [
+    {
+      namespace: 'kb',
+      description: 'Knowledge base lookups',
+      functions: [findSnippetsFn, searchPagesFn],
+    },
+    {
+      namespace: 'metrics',
+      description: 'Scoring and coverage helpers',
+      functions: [scoreCoverageFn],
+    },
+  ],
+  functionDiscovery: true,
   contextFields: [],
 });
 ```
 
 Rules:
 
-- `agents.shared` and `functions.shared` propagate one level down.
-- `agents.globallyShared` and `functions.globallyShared` propagate to all descendants.
-- Use `excluded` when a child should not receive a propagated field, agent, or function.
+- A group is `{ namespace, description, functions: [...] }`. The group's `namespace` and `description` show up in `discoverModules(...)` markdown.
+- Mix groups and ungrouped entries freely in `functions: [...]` — child agents and `fn(...)` tools sit alongside group entries.
+- There is no `local` / `shared` / `globallyShared` propagation. Each agent owns its own `functions: [...]`; pass shared tools to children explicitly.
 
 ## Tuning Hand-off
 

package/skills/ax-ai.md

@@ -1,7 +1,7 @@
 ---
 name: ax-ai
 description: This skill helps an LLM generate correct AI provider setup and configuration code using @ax-llm/ax. Use when the user asks about ai(), providers, models, presets, embeddings, extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/Groq/DeepSeek/Mistral/Cohere/Together/Ollama/HuggingFace/Reka/OpenRouter with @ax-llm/ax.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)
@@ -26,7 +26,7 @@ const openrouter = ai({ name: 'openrouter', apiKey: 'your-key' });
 const ollama = ai({ name: 'ollama', url: 'http://localhost:11434' });
 const hf = ai({ name: 'huggingface', apiKey: 'hf_...' });
 const reka = ai({ name: 'reka', apiKey: 'your-key' });
-const grok = ai({ name: 'x-grok', apiKey: 'your-key' });
+const grok = ai({ name: 'grok', apiKey: 'your-key' });
 ```
 
 ## Model Presets
@@ -47,6 +47,25 @@ const gemini = ai({
 await gemini.chat({ model: 'tiny', chatPrompt: [{ role: 'user', content: 'Hi' }] });
 ```
 
+## Model Catalog
+
+```typescript
+import { axGetSupportedAIModels } from '@ax-llm/ax';
+
+const providers = axGetSupportedAIModels();
+const openai = providers.find((provider) => provider.name === 'openai');
+console.log(openai?.models[0]?.promptTokenCostPer1M);
+
+const textProviders = axGetSupportedAIModels({ type: 'text' });
+const embeddingProviders = axGetSupportedAIModels({ type: 'embeddings' });
+```
+
+Use `axGetSupportedAIModels()` to build provider/model selectors before creating an `ai(...)` instance. It returns bundled static metadata: provider names, display names, default models, raw `AxModelInfo` pricing/details, model type (`'text'`, `'embeddings'`, `'code'`, or `'audio'`), and normalized capability flags for thinking, thoughts, structured outputs, audio, temperature, and top-p support. Provider groups and models are sorted cheapest to most expensive based on bundled input + output token pricing; unpriced models sort last.
+
+Filter with `{ type: 'all' | 'text' | 'embeddings' | 'code' | 'audio' }` or an array of those values. The `'text'` filter includes code-capable models; use `'code'` to show only code-first models.
+
+Dynamic providers such as Azure OpenAI deployments, OpenRouter, Ollama, and Hugging Face are marked with `isDynamic: true` and may have an empty or static-limited model list.
+
 ## Chat
 
 ```typescript
@@ -210,7 +229,7 @@ const client = new AxMCPClient(transport);
 ## Critical Rules
 
 - Use `ai()` factory for all providers.
-- Provider names: `'openai'`, `'anthropic'`, `'google-gemini'`, `'azure-openai'`, `'mistral'`, `'groq'`, `'cohere'`, `'together'`, `'deepseek'`, `'ollama'`, `'huggingface'`, `'openrouter'`, `'reka'`, `'x-grok'`
+- Provider names: `'openai'`, `'anthropic'`, `'google-gemini'`, `'azure-openai'`, `'mistral'`, `'groq'`, `'cohere'`, `'together'`, `'deepseek'`, `'ollama'`, `'huggingface'`, `'openrouter'`, `'reka'`, `'grok'`
 - Thinking constraints on Anthropic: `temperature` and `topK` are ignored; `topP` only sent if >= 0.95.
 - Bedrock uses `new AxAIBedrock()`, not `ai()`.
 - Vercel AI SDK uses `AxAIProvider` wrapper.

package/skills/ax-audio.md

@@ -0,0 +1,251 @@
+---
+name: ax-audio
+description: This skill helps an LLM generate correct conversational audio I/O code with @ax-llm/ax. Use when the user asks about .chat() audio input, audio output, OpenAI gpt-audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with signatures and structured outputs.
+version: "21.0.3"
+---
+
+# Audio I/O Codegen Rules (@ax-llm/ax)
+
+Use this skill for bounded-turn conversational audio through `.chat()`. Prefer short, modern, copyable examples. Do not model generated audio as a DSPy signature output field.
+
+## Core Rule
+
+Audio output is returned on `AxChatResponseResult.audio`, not in signature fields.
+
+Signatures should keep text fields text-shaped:
+
+```typescript
+const result = await llm.chat({
+  chatPrompt: [{ role: 'user', content: 'Say hello out loud.' }],
+  modelConfig: {
+    audio: { output: { enabled: true } },
+  },
+});
+
+console.log(result.results[0]?.content);
+console.log(result.results[0]?.audio?.data);
+console.log(result.results[0]?.audio?.transcript);
+```
+
+Do not write signatures like `question:string -> audio:audio`. Use `.chat()` for conversational audio and use `audio.data` for the generated bytes.
+
+## Config Shape
+
+```typescript
+type AxChatAudioConfig = {
+  input?: {
+    format?: 'wav' | 'mp3' | 'flac' | 'opus' | 'aac' | 'pcm16' | 'pcm' | 'ogg';
+    mimeType?: string;
+    sampleRate?: number;
+    channels?: number;
+  };
+  output?: {
+    enabled?: boolean;
+    voice?: string | { id: string };
+    format?: 'wav' | 'mp3' | 'flac' | 'opus' | 'aac' | 'pcm16' | 'pcm' | 'ogg';
+    sampleRate?: number;
+    channels?: number;
+    includeTranscript?: boolean;
+  };
+  live?: {
+    turnTimeoutMs?: number;
+    enableAffectiveDialog?: boolean;
+    proactiveAudio?: boolean;
+  };
+};
+```
+
+## OpenAI Defaults
+
+Use `axAIOpenAIAudioDefaultConfig()` for OpenAI request-based audio chat:
+
+- model: `gpt-audio-mini`
+- output enabled
+- voice: `alloy`
+- output format: `wav`
+- transcript enabled
+- streaming disabled by default
+- audio input formats: `wav`, `mp3`
+- audio output formats: `wav`, `mp3`, `flac`, `opus`, `aac`, `pcm16`
+
+```typescript
+import { ai, axAIOpenAIAudioDefaultConfig } from '@ax-llm/ax';
+
+const openai = ai({
+  name: 'openai',
+  apiKey: process.env.OPENAI_APIKEY!,
+  config: axAIOpenAIAudioDefaultConfig(),
+});
+
+const res = await openai.chat({
+  chatPrompt: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'What is in this recording?' },
+        { type: 'audio', data: base64Wav, format: 'wav' },
+      ],
+    },
+  ],
+});
+
+console.log(res.results[0]?.content);
+console.log(res.results[0]?.audio?.data);
+```
+
+Use `axAIOpenAIRealtimeDefaultConfig()` for OpenAI realtime speech-to-speech:
+
+- model: `gpt-realtime-2`
+- output enabled
+- voice: `marin`
+- output format: `pcm16`
+- input default: `audio/pcm`, mono, 24000 Hz
+- turn timeout: `30000`
+- streaming disabled by default
+
+Use `axAIOpenAIRealtimeTranscriptionDefaultConfig()` for realtime transcript deltas:
+
+- model: `gpt-realtime-whisper`
+- input default: `audio/pcm`, mono, 24000 Hz
+- output audio disabled; transcript text is returned on `content`
+
+Realtime models use a one-turn WebSocket call under `.chat()`. In Node, pass a WebSocket constructor through request options:
+
+```typescript
+import WebSocket from 'ws';
+import { ai, axAIOpenAIRealtimeDefaultConfig } from '@ax-llm/ax';
+
+const openai = ai({
+  name: 'openai',
+  apiKey: process.env.OPENAI_APIKEY!,
+  config: axAIOpenAIRealtimeDefaultConfig(),
+});
+
+const stream = await openai.chat(
+  {
+    chatPrompt: [{ role: 'user', content: 'Say hello out loud.' }],
+  },
+  { stream: true, webSocket: WebSocket }
+);
+```
+
+For follow-up turns, keep the assistant audio reference in history:
+
+```typescript
+await openai.chat({
+  chatPrompt: [
+    { role: 'assistant', audio: { id: previousAudioId } },
+    { role: 'user', content: 'Repeat that more slowly.' },
+  ],
+});
+```
+
+## Gemini Live Defaults
+
+Use `axAIGoogleGeminiLiveAudioDefaultConfig()` for Gemini native audio:
+
+- model: `gemini-2.5-flash-native-audio-preview-12-2025`
+- output enabled
+- voice: `Kore`
+- output format: `pcm16`
+- output sample rate: `24000`
+- input default: `audio/pcm;rate=16000`, mono
+- transcript enabled
+- turn timeout: `30000`
+- streaming disabled by default
+
+```typescript
+import { ai, axAIGoogleGeminiLiveAudioDefaultConfig } from '@ax-llm/ax';
+
+const gemini = ai({
+  name: 'google-gemini',
+  apiKey: process.env.GOOGLE_APIKEY!,
+  config: axAIGoogleGeminiLiveAudioDefaultConfig(),
+});
+
+const res = await gemini.chat({
+  chatPrompt: [
+    {
+      role: 'user',
+      content: [
+        { type: 'text', text: 'Answer this spoken question.' },
+        {
+          type: 'audio',
+          data: base64Pcm16,
+          format: 'pcm16',
+          sampleRate: 16000,
+          channels: 1,
+        },
+      ],
+    },
+  ],
+});
+
+console.log(res.results[0]?.content);
+console.log(res.results[0]?.audio?.data);
+```
+
+Gemini Live uses a one-turn WebSocket call under `.chat()`. It expects PCM input for native audio turns; use `format: 'pcm16'` or `mimeType: 'audio/pcm;rate=16000'`.
+
+## Grok Voice Defaults
+
+Use `axAIGrokVoiceDefaultConfig()` for xAI Grok Voice Agent:
+
+- model: `grok-voice-think-fast-1.0`
+- output enabled
+- voice: `eve`
+- output format: `pcm16`
+- output sample rate: `24000`
+- input default: `audio/pcm`, mono, 24000 Hz
+- transcript enabled
+- turn timeout: `30000`
+- streaming disabled by default
+
+```typescript
+import WebSocket from 'ws';
+import { ai, axAIGrokVoiceDefaultConfig } from '@ax-llm/ax';
+
+const grok = ai({
+  name: 'grok',
+  apiKey: process.env.GROK_API_KEY!,
+  config: axAIGrokVoiceDefaultConfig(),
+});
+
+const res = await grok.chat(
+  {
+    chatPrompt: [{ role: 'user', content: 'Say hello out loud.' }],
+  },
+  { webSocket: WebSocket }
+);
+
+console.log(res.results[0]?.content);
+console.log(res.results[0]?.audio?.data);
+```
+
+Grok Voice uses a one-turn WebSocket call under `.chat()`. It expects PCM input for spoken input turns; use `format: 'pcm16'` or `mimeType: 'audio/pcm'`.
+
+## Streaming Audio
+
+OpenAI audio chat, OpenAI Realtime, Gemini Live, and Grok Voice all default to non-streaming, but each can stream deltas when you pass `{ stream: true }`.
+
+```typescript
+const stream = await llm.chat(
+  {
+    chatPrompt: [{ role: 'user', content: 'Say hello.' }],
+  },
+  { stream: true }
+);
+
+for await (const chunk of stream) {
+  const audio = chunk.results[0]?.audio;
+  if (audio?.isDelta) {
+    playAudioChunk(audio.data);
+  }
+}
+```
+
+## Structured Outputs
+
+Do not combine audio output with structured response formats. Audio chat may return a text transcript in `content`, but generated audio bytes live at `result.results[0].audio`.
+
+For structured extraction from speech, use a text-only or transcription step first, then pass the transcript into `ax(...)` or `flow(...)`.

package/skills/ax-flow.md

@@ -1,7 +1,7 @@
 ---
 name: ax-flow
 description: This skill helps an LLM generate correct AxFlow workflow code using @ax-llm/ax. Use when the user asks about flow(), AxFlow, workflow orchestration, parallel execution, DAG workflows, conditional routing, map/reduce patterns, or multi-node AI pipelines.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)

package/skills/ax-gen.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gen
 description: This skill helps an LLM generate correct AxGen code using @ax-llm/ax. Use when the user asks about ax(), AxGen, generators, forward(), streamingForward(), assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -393,7 +393,7 @@ gen.getChatLog(): readonly AxChatLogEntry[]
 
 ### getUsage()
 
-Returns token usage aggregated by `(ai, model)` across all steps. Reset with `resetUsage()`.
+Returns token usage aggregated by `(ai, model)` across all steps. When a provider reports prompt-cache usage, `promptTokens` is the uncached input portion and `cacheReadTokens` / `cacheCreationTokens` carry the cache counters. Reset with `resetUsage()`.
 
 ```typescript
 const usage = gen.getUsage(); // AxProgramUsage[]

package/skills/ax-gepa.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gepa
 description: This skill helps an LLM generate correct AxGEPA optimization code using @ax-llm/ax. Use when the user asks about AxGEPA, GEPA, Pareto optimization, multi-objective prompt tuning, reflective prompt evolution, validationExamples, maxMetricCalls, or optimizing a generator, flow, or agent tree.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxGEPA Codegen Rules (@ax-llm/ax)

package/skills/ax-learn.md

@@ -1,7 +1,7 @@
 ---
 name: ax-learn
 description: This skill helps an LLM generate correct AxLearn code using @ax-llm/ax. Use when the user asks about self-improving agents, trace-backed learning, feedback-aware updates, or AxLearn modes.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # AxLearn Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
-name: ax
+name: ax-llm
 description: This skill helps with using the @ax-llm/ax TypeScript library for building LLM applications. Use when the user asks about ax(), ai(), f(), s(), agent(), flow(), AxGen, AxAgent, AxFlow, signatures, streaming, or mentions @ax-llm/ax.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference

package/skills/ax-signature.md

@@ -1,7 +1,7 @@
 ---
 name: ax-signature
 description: This skill helps an LLM generate correct DSPy signature code using @ax-llm/ax. Use when the user asks about signatures, s(), f(), field types, string syntax, fluent builder API, validation constraints, or type-safe inputs/outputs.
-version: "21.0.0"
+version: "21.0.3"
 ---
 
 # Ax Signature Reference
@@ -22,6 +22,8 @@ version: "21.0.0"
 | JSON | `:json` | `any` | `metadata:json` |
 | Date | `:date` | `Date` | `birthDate:date` |
 | DateTime | `:datetime` | `Date` | `timestamp:datetime` |
+| DateRange | `:dateRange` | `{ start: Date; end: Date }` | `travelDates:dateRange` |
+| DateTimeRange | `:datetimeRange` | `{ start: Date; end: Date }` | `meetingWindow:datetimeRange` |
 | Image | `:image` | `{mimeType, data}` | `photo:image` (input only) |
 | Audio | `:audio` | `{format?, data}` | `recording:audio` (input only) |
 | File | `:file` | `{mimeType, data}` | `document:file` (input only) |
@@ -29,6 +31,8 @@ version: "21.0.0"
 | Code | `:code` | `string` | `pythonScript:code` |
 | Class | `:class "a, b, c"` | `"a" \| "b" \| "c"` | `mood:class "happy, sad"` |
 
+Date, datetime, and range fields are AI-friendly but strict. They accept ISO-style values, trim minor whitespace/casing issues, and parse ranges as `{ "start": "...", "end": "..." }`, `[start, end]`, `start/end`, or natural delimiters like `start to end`; invalid values and reversed ranges should fail validation rather than being silently autocorrected.
+
 ## Arrays, Optional, and Internal Fields
 
 ```typescript
@@ -177,7 +181,7 @@ const sig = s('base:string -> result:string')
 Type creators:
 - `f.string(desc)`, `f.number(desc)`, `f.boolean(desc)`, `f.json(desc)`
 - `f.image(desc)`, `f.audio(desc)`, `f.file(desc)`, `f.url(desc)`
-- `f.email(desc)`, `f.date(desc)`, `f.datetime(desc)`
+- `f.email(desc)`, `f.date(desc)`, `f.datetime(desc)`, `f.dateRange(desc)`, `f.datetimeRange(desc)`
 - `f.class(['a','b','c'], desc)`, `f.code(desc)`
 - `f.object({ field: f.string() }, desc)`
 
@@ -283,7 +287,7 @@ Bad: `text`, `data`, `input`, `output`, `a`, `x`, `val` (too generic), `1field`
 - `.internal()` / `{ internal: true }` is output-only (for chain-of-thought reasoning).
 - `.cache()` / `{ cache: true }` is input-only (for prompt caching).
 - Validation errors trigger auto-retry with correction feedback.
-- `f.email()`, `f.url()`, `f.date()`, `f.datetime()` are shorthand for `f.string().email()` etc.
+- `f.email()`, `f.url()`, `f.date()`, `f.datetime()` are shorthand for `f.string().email()` etc.; `f.dateRange()` and `f.datetimeRange()` return `{ start: Date; end: Date }`.
 - `z.enum()` maps to ax's `class` type — only valid on **output** fields.
 - For multimodal inputs (images, audio, files) use `f.image()` / `f.audio()` / `f.file()` — zod has no equivalent.