@ax-llm/ax 21.0.8 → 21.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "21.0.8",
+  "version": "21.0.10",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {

package/skills/ax-agent-memory-skills.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-memory-skills
 description: This skill helps an LLM generate correct AxAgent memory retrieval and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about onMemoriesSearch, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "21.0.8"
+version: "21.0.10"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)
@@ -138,7 +138,12 @@ import type { AxAgentSkillsSearchFn } from '@ax-llm/ax';
 // Each result is { id?: string; name: string; content: string }.
 // If id is omitted, Ax falls back to name.
 const onSkillsSearch: AxAgentSkillsSearchFn = async (searches) => {
-  return mySkillStore.searchBatch(searches, { topK: 2 });
+  return mySkillStore.resolveBatch(searches, {
+    // Recommended backend order: exact id, exact name, then broader search.
+    // This lets the actor pass one simple string and keeps lookup policy host-side.
+    strategy: ['id', 'name', 'search'],
+    topK: 2,
+  });
 };
 
 const myAgent = agent('task:string -> answer:string', {
@@ -170,6 +175,7 @@ await discover({ skills: ['release-checklist', 'incident-response'] });
 Rules:
 
 - `discover({ skills })` invokes `onSkillsSearch` with the raw search strings and returns `void`.
+- Resolve each raw string backend-side: prefer an exact `id` match, then an exact `name` match, then fuzzy/full-text search. The actor should not have to choose `id:` vs `name:` syntax.
 - Matched skills land under "Loaded Skills" for the next turn.
 - Entries are deduped by `id` (last-write-wins) and sorted by `id` for prefix-cache stability.
 - If a skill result omits `id`, its trimmed `name` is used as the id for backwards compatibility.
@@ -192,7 +198,7 @@ const releaseAgent = agent('task:string -> answer:string', {
   contextFields: [],
   skills: [
     {
-      id: 'skill:release-checklist',
+      id: 'release-checklist',
       name: 'release-checklist',
       content: '...',
     },
@@ -205,7 +211,7 @@ await releaseAgent.forward(
   {
     skills: [
       {
-        id: 'skill:incident-response',
+        id: 'incident-response',
         name: 'incident-response',
         content: '...',
       },

package/skills/ax-agent-observability.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-observability
 description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about actorTurnCallback, executorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "21.0.8"
+version: "21.0.10"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)
@@ -21,6 +21,21 @@ Use this skill when an agent needs runtime visibility, progress reporting, traci
 - Need Ax program traces -> use `getTraces()`.
 - Do not add multiple hooks unless the user clearly needs each output stream.
 
+## Global Runtime Defaults
+
+OpenTelemetry and debug defaults come from the shared Ax runtime surface:
+
+```typescript
+import { axGlobals, axCreateDefaultColorLogger } from '@ax-llm/ax';
+import { trace } from '@opentelemetry/api';
+
+axGlobals.tracer = trace.getTracer('agent-app');
+axGlobals.debug = true;
+axGlobals.logger = axCreateDefaultColorLogger();
+```
+
+These globals are live defaults for future AI, AxGen, AxFlow, and agent-internal model calls. Per-call or explicitly configured options still override `axGlobals`. Use AxAgent callbacks below when the caller needs structured agent-turn events rather than OpenTelemetry spans or debug logs.
+
 ## Actor Turn Callback
 
 Use `actorTurnCallback` when the caller needs structured telemetry for each actor turn. `executorTurnCallback` is still accepted as a deprecated alias for older code.

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.8"
+version: "21.0.10"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent-rlm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-rlm
 description: This skill helps an LLM generate correct AxAgent RLM/runtime code using @ax-llm/ax. Use when the user asks about RLM code execution, AxJSRuntime, contextFields, contextPolicy, liveRuntimeState, promptLevel, stage prompt controls, executorModelPolicy, maxRuntimeChars, agent.test(...), llmQuery(...), mode: 'advanced', recursionOptions, or long-running agent runtime behavior.
-version: "21.0.8"
+version: "21.0.10"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
-version: "21.0.8"
+version: "21.0.10"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)

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.8"
+version: "21.0.10"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)
@@ -86,6 +86,46 @@ console.log(res.results[0]?.content);
 - `functionCallMode`: `'auto'` | `'native'` | `'prompt'`
 - `debug`, `logger`, `tracer`, `rateLimiter`, `timeout`
 
+## Global Runtime Defaults
+
+Use `axGlobals` when the app wants one live default for AI requests, generator runs, flows, or metrics:
+
+```typescript
+import { ai, axGlobals, axCreateDefaultColorLogger } from '@ax-llm/ax';
+import { trace } from '@opentelemetry/api';
+
+axGlobals.tracer = trace.getTracer('my-app');
+axGlobals.debug = true;
+axGlobals.logger = axCreateDefaultColorLogger();
+axGlobals.customLabels = { service: 'api' };
+
+const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
+```
+
+Rules:
+
+- `axGlobals.tracer`, `meter`, `logger`, `debug`, `abortSignal`, and `customLabels` are live runtime defaults; future calls read the current value even if the AI instance already exists.
+- Precedence is: per-call options, then explicit AI/service options, then current `axGlobals`, then built-in defaults.
+- `customLabels` merge from globals to service to call options; later sources override earlier keys.
+- `abortSignal` values are merged, so either a global shutdown signal or a local request signal can cancel the request.
+
+## DeepSeek Notes
+
+```typescript
+import { ai, AxAIDeepSeekModel } from '@ax-llm/ax';
+
+const deepseek = ai({
+  name: 'deepseek',
+  apiKey: process.env.DEEPSEEK_APIKEY!,
+  config: { model: AxAIDeepSeekModel.DeepSeekV4Pro },
+});
+```
+
+DeepSeek V4 thinking models support tools, but reject the `tool_choice`
+request parameter. Ax omits forced/auto tool choice for `deepseek-v4-pro`,
+`deepseek-v4-flash`, and `deepseek-reasoner` while still sending tool
+definitions.
+
 ## Extended Thinking
 
 ```typescript

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 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.8"
+version: "21.0.10"
 ---
 
 # Audio I/O Codegen Rules (@ax-llm/ax)

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.8"
+version: "21.0.10"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)
@@ -343,6 +343,25 @@ const result = await wf.forward(llm, { userQuestion: 'hi' }, {
 });
 ```
 
+Flow tracing also respects live app-wide defaults:
+
+```typescript
+import { axGlobals } from '@ax-llm/ax';
+import { metrics } from '@opentelemetry/api';
+
+axGlobals.tracer = tracer;
+axGlobals.meter = metrics.getMeter('axflow');
+
+const result = await wf.forward(llm, { userQuestion: 'hi' });
+```
+
+Rules:
+
+- `wf.forward(..., { tracer, meter })` overrides flow defaults and `axGlobals`.
+- Constructor/factory flow defaults override `axGlobals`.
+- If no local tracer or meter is provided, `AxFlow` reads current `axGlobals.tracer` and `axGlobals.meter`, creates a parent flow span, and propagates tracer/meter plus trace context to node forwards.
+- `axGlobals.abortSignal` is merged with flow-level abort signals.
+
 ## Program IDs and Demos
 
 ```typescript

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.8"
+version: "21.0.10"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -114,6 +114,34 @@ const result = await gen.forward(llm, { input: '...' }, {
 });
 ```
 
+### Live Global Defaults
+
+`AxGen` respects `axGlobals` for app-wide runtime defaults:
+
+```typescript
+import { axGlobals } from '@ax-llm/ax';
+import { trace } from '@opentelemetry/api';
+
+const responseCache = new Map<string, any>();
+
+axGlobals.tracer = trace.getTracer('my-app');
+axGlobals.debug = true;
+axGlobals.cachingFunction = async (key, value?) => {
+  if (value !== undefined) {
+    responseCache.set(key, value);
+    return;
+  }
+  return responseCache.get(key);
+};
+```
+
+Rules:
+
+- Tracing/logging precedence is: forward options, then generator options, then AI service options, then current `axGlobals`, then built-in defaults.
+- `abortSignal` from `axGlobals` is merged with local forward signals.
+- `customLabels` merge from globals to AI service to forward options.
+- `cachingFunction` and `functionResultFormatter` also fall back to current `axGlobals` when local options do not provide them.
+
 ### `streamingForward()`
 
 ```typescript
@@ -264,6 +292,23 @@ Rules:
 - `thinkingTokenBudget` can be `'low'`, `'medium'`, `'high'`, or a number.
 - Set `showThoughts: true` to include the model's reasoning in `result.thought`.
 
+## Structured Outputs
+
+```typescript
+const sig = f()
+  .input('text', f.string())
+  .output('summary', f.string())
+  .output('metadata', f.json().optional())
+  .useStructured()
+  .build();
+```
+
+Rules:
+
+- `.useStructured()` asks providers with native support, including OpenAI, Anthropic, and Gemini, for schema-constrained JSON.
+- Native structured-output schemas list every object property in `required`, set `additionalProperties: false` on objects, and express optional fields as nullable types.
+- Flexible `json` fields and unshaped `object` fields are sent as JSON-encoded strings for native structured outputs, then parsed back into normal JavaScript values.
+
 ## Step Hooks
 
 ```typescript

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.8"
+version: "21.0.10"
 ---
 
 # 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.8"
+version: "21.0.10"
 ---
 
 # AxLearn Codegen Rules (@ax-llm/ax)

package/skills/ax-llm.md

@@ -1,7 +1,7 @@
 ---
 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.8"
+version: "21.0.10"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
@@ -106,6 +106,19 @@ for await (const chunk of gen.streamingForward(llm, { question: 'Tell a story' }
 | Stop function | `stopFunction` | `{ stopFunction: 'finalAnswer' }` |
 | Function mode | `functionCallMode` | `{ functionCallMode: 'auto' }` |
 
+Global runtime defaults can be set with `axGlobals` and are read live by future AI, AxGen, and AxFlow calls:
+
+```typescript
+import { axGlobals, axCreateDefaultColorLogger } from '@ax-llm/ax';
+import { trace } from '@opentelemetry/api';
+
+axGlobals.tracer = trace.getTracer('my-app');
+axGlobals.debug = true;
+axGlobals.logger = axCreateDefaultColorLogger();
+```
+
+Precedence is: per-call options, then explicit instance/program options, then current `axGlobals`, then built-in defaults. `customLabels` merge in that order, and `abortSignal` values are combined so either global or local cancellation works.
+
 ## Memory and Context
 
 ```typescript
@@ -208,7 +221,7 @@ try {
 ## Debugging
 
 ```typescript
-import { axCreateDefaultColorLogger } from '@ax-llm/ax';
+import { axCreateDefaultColorLogger, axGlobals } from '@ax-llm/ax';
 
 const result = await gen.forward(llm, { input: 'test' }, {
   debug: true,
@@ -217,6 +230,10 @@ const result = await gen.forward(llm, { input: 'test' }, {
   tracer: openTelemetryTracer,
   meter: openTelemetryMeter,
 });
+
+// Or set live app-wide defaults for future calls:
+axGlobals.tracer = openTelemetryTracer;
+axGlobals.meter = openTelemetryMeter;
 ```
 
 ## MCP Integration

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.8"
+version: "21.0.10"
 ---
 
 # Ax Signature Reference