@ax-llm/ax 22.0.7 → 22.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "22.0.7",
+  "version": "22.0.9",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {
@@ -43,12 +43,12 @@
       "import": "./index.js",
       "require": "./index.cjs"
     },
-    "./index.global.js": "./index.global.js",
     "./*": {
       "types": "./*.d.ts",
       "import": "./*.js",
       "require": "./*.cjs"
-    }
+    },
+    "./index.global.js": "./index.global.js"
   },
   "bin": {
     "ax": "./cli/index.mjs"

package/skills/ax-agent-context.md

@@ -0,0 +1,42 @@
+---
+name: ax-agent-context
+description: This skill helps an LLM pick the right AxAgent context tool for a job - contextMap for recurring corpora, contextPolicy presets for within-run trajectory compaction, agent.optimize for offline GEPA instruction/demo tuning, agent.playbook for an evolving context playbook (offline evolve + online update), and recall/memories + skills for per-turn retrieval. Use when the user asks "which context feature should I use", confuses contextMap with contextPolicy or memory, or wants a decision guide for long-context agents. For contextPolicy/contextMap codegen use ax-agent-rlm; for recall/skills use ax-agent-memory-skills; for agent.optimize or agent.playbook use ax-agent-optimize.
+version: "22.0.9"
+---
+
+# AxAgent Context Selection (@ax-llm/ax)
+
+Use this skill to route a context-management need to the right AxAgent tool, then open the matching codegen skill. AxAgent manages four distinct context objects; choosing the wrong one is the usual mistake. Do not write tutorial prose; pick the tool and hand off.
+
+## Pick The Right Context Tool
+
+| Need | Object | Scope | Use | Next skill |
+| --- | --- | --- | --- | --- |
+| Many tasks over the same large corpus (repo, doc set, dataset) | Context map | recurring corpus, persists across runs | `contextMap` | `ax-agent-rlm` |
+| One long run whose own history must stay under control | Trajectory compaction | this run only | `contextPolicy: { preset, budget }` | `ax-agent-rlm` |
+| Evolve task strategy from examples or live feedback | Context playbook | a stage, offline + online | `agent.playbook(...)` | `ax-agent-optimize` |
+| Tune the prompt/instructions/demos offline | Instruction text | a program, offline | `agent.optimize(...)` (GEPA) | `ax-agent-optimize` |
+| Pull task-relevant facts or guides for a turn | Retrieval | one turn | `recall(...)` / skills | `ax-agent-memory-skills` |
+
+## Defaults
+
+- Recurring corpus + many different questions -> `contextMap` (persistent orientation cache).
+- One long multi-turn run with prompt pressure -> `contextPolicy: { preset: 'checkpointed', budget: 'balanced' }`; move to `lean` for very long runs with strong models, `full` for short tasks or weak models.
+- Evolve a context playbook -> `agent.playbook(...)` (offline from examples, or online from live feedback).
+- Tune instructions/demos offline -> `agent.optimize(...)` (GEPA).
+- Fetch facts or guides on demand -> `recall(...)` for memories, `discover({ skills })` for skill guides.
+
+## Anti-Patterns
+
+- Do not use `contextMap` to compress a single run's history. That is `contextPolicy`.
+- Do not use `contextPolicy` to carry knowledge across runs. That is `contextMap`.
+- Do not hand-build a strategy playbook in the prompt. Evolve it with `agent.playbook(...)`.
+- Do not stuff a whole corpus into the prompt every run. Use a context map plus on-demand `recall(...)`.
+- Do not confuse runtime skills (`discover({ skills })` guides) with these installable codegen skills.
+
+## See Also
+
+- `ax-agent-rlm` - contextPolicy presets, context maps, and runtime sessions.
+- `ax-agent-memory-skills` - recall, memories, and dynamic skill loading.
+- `ax-agent-optimize` - GEPA via `agent.optimize(...)` and the context playbook via `agent.playbook(...)`.
+- `ax-agent` - core agent shape and the final/clarification protocol.

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, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)

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, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)

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 agent optimization guidance.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)
@@ -136,13 +136,13 @@ const tools = [
 const studentAI = ai({
   name: 'google-gemini',
   apiKey: process.env.GOOGLE_APIKEY!,
-  config: { model: AxAIGoogleGeminiModel.Gemini25FlashLite, temperature: 0.2 },
+  config: { model: AxAIGoogleGeminiModel.Gemini31FlashLite, temperature: 0.2 },
 });
 
 const judgeAI = ai({
   name: 'google-gemini',
   apiKey: process.env.GOOGLE_APIKEY!,
-  config: { model: AxAIGoogleGeminiModel.Gemini3Pro, temperature: 1.0 },
+  config: { model: AxAIGoogleGeminiModel.Gemini35Flash, temperature: 1.0 },
 });
 
 const assistant = agent('query:string -> answer:string', {
@@ -246,7 +246,7 @@ Use this when the agent behavior needs holistic review:
 const result = await assistant.optimize(tasks, {
   judgeAI,
   judgeOptions: {
-    model: AxAIGoogleGeminiModel.Gemini3Pro,
+    model: AxAIGoogleGeminiModel.Gemini35Flash,
     description:
       'Be strict about unnecessary child-agent calls, weak clarifications, and incorrect tool choices.',
   },

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(...), recursionOptions, or long-running agent runtime behavior.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # 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: "22.0.7"
+version: "22.0.9"
 ---
 
 # 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, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/DeepSeek/Mistral/Cohere/Reka/Grok with @ax-llm/ax.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)
@@ -16,7 +16,7 @@ import { ai } from '@ax-llm/ax';
 const openai = ai({ name: 'openai', apiKey: 'sk-...' });
 const claude = ai({ name: 'anthropic', apiKey: 'sk-ant-...' });
 const gemini = ai({ name: 'google-gemini', apiKey: 'AIza...' });
-const azure = ai({ name: 'azure-openai', apiKey: 'your-key', resourceName: 'your-resource', deploymentName: 'gpt-4' });
+const azure = ai({ name: 'azure-openai', apiKey: 'your-key', resourceName: 'your-resource', deploymentName: 'gpt-5-4-mini' });
 const deepseek = ai({ name: 'deepseek', apiKey: 'sk-...' });
 const mistral = ai({ name: 'mistral', apiKey: 'your-key' });
 const cohere = ai({ name: 'cohere', apiKey: 'your-key' });
@@ -31,6 +31,28 @@ const grok = ai({ name: 'grok', apiKey: 'your-key' });
 const compatible = ai({ name: 'openai', apiKey: 'key', apiURL: 'https://api.example.com/v1', config: { model: 'provider/model' } });
 ```
 
+<!-- axir-nonportable:start webllm -->
+WebLLM is browser-only and requires a host-created WebLLM engine. The host
+loads or reloads models with WebLLM APIs such as `CreateMLCEngine(...)`; Ax
+only forwards chat requests to that loaded engine. Do not present WebLLM as a
+portable AxIR provider or a server-side default.
+
+```typescript
+import { ai, AxAIWebLLMModel } from '@ax-llm/ax';
+
+const engine = await CreateMLCEngine(AxAIWebLLMModel.Llama32_3B_Instruct);
+const llm = ai({
+  name: 'webllm',
+  engine,
+  config: {
+    model: AxAIWebLLMModel.Llama32_3B_Instruct,
+    stream: false,
+    supportsFunctions: false,
+  },
+});
+```
+<!-- axir-nonportable:end webllm -->
+
 ## Model Presets
 
 ```typescript
@@ -41,8 +63,8 @@ const gemini = ai({
   apiKey: process.env.GOOGLE_APIKEY!,
   config: { model: 'simple' },
   models: [
-    { key: 'tiny', model: AxAIGoogleGeminiModel.Gemini20FlashLite, description: 'Fast + cheap', config: { maxTokens: 1024, temperature: 0.3 } },
-    { key: 'simple', model: AxAIGoogleGeminiModel.Gemini20Flash, description: 'Balanced', config: { temperature: 0.6 } },
+    { key: 'tiny', model: AxAIGoogleGeminiModel.Gemini31FlashLite, description: 'Fast + cheap', config: { maxTokens: 1024, temperature: 0.3 } },
+    { key: 'simple', model: AxAIGoogleGeminiModel.Gemini35Flash, description: 'Balanced', config: { temperature: 0.6 } },
   ],
 });
 
@@ -284,22 +306,26 @@ import { AxAIBedrock, AxAIBedrockModel } from '@ax-llm/ax-ai-aws-bedrock';
 const bedrock = new AxAIBedrock({
   region: 'us-east-2',
   fallbackRegions: ['us-west-2'],
-  config: { model: AxAIBedrockModel.ClaudeSonnet4 },
+  config: { model: AxAIBedrockModel.ClaudeOpus45 },
 });
 ```
 
 ## Vercel AI SDK Integration
 
 ```typescript
+import { generateText } from 'ai';
 import { ai } from '@ax-llm/ax';
 import { AxAIProvider } from '@ax-llm/ax-ai-sdk-provider';
-import { generateText } from 'ai';
 
-const axAI = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
+const axAI = ai({
+  name: 'openai',
+  apiKey: process.env.OPENAI_APIKEY ?? '',
+});
 const model = new AxAIProvider(axAI);
+
 const result = await generateText({
   model,
-  messages: [{ role: 'user', content: 'Hello!' }],
+  prompt: 'Hello!',
 });
 ```
 

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct audio code with @ax-llm/ax. Use when the user asks about ai.transcribe(), ai.speak(), signature audio inputs or outputs, agent audio behavior, .chat() conversational audio, OpenAI audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with structured outputs.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # 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: "22.0.7"
+version: "22.0.9"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)
@@ -305,7 +305,7 @@ const wf = flow<{ items: string[] }, { processed: string[] }>({ batchSize: 3 })
 Route nodes to different AI providers:
 
 ```typescript
-const fast = ai({ name: 'openai', apiKey: '...', config: { model: 'gpt-5-mini' } });
+const fast = ai({ name: 'openai', apiKey: '...', config: { model: 'gpt-5.4-mini' } });
 const smart = ai({ name: 'anthropic', apiKey: '...' });
 
 const wf = flow<{ text: string }, { out: string }>()

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(), validation, assertions, streaming assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -111,7 +111,7 @@ const result = await gen.forward(llm, { input: '...' });
 // With options
 const result = await gen.forward(llm, { input: '...' }, {
   maxRetries: 5,
-  model: 'gpt-4.1',
+  model: 'gpt-5.4-mini',
   modelConfig: { temperature: 0.9, maxTokens: 1000 },
   debug: true,
 });

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: "22.0.7"
+version: "22.0.9"
 ---
 
 # GEPA Optimization Codegen Rules (@ax-llm/ax)
@@ -57,13 +57,13 @@ import { ai, ax, optimize, AxAIOpenAIModel } from '@ax-llm/ax';
 const student = ai({
   name: 'openai',
   apiKey: process.env.OPENAI_APIKEY!,
-  config: { model: AxAIOpenAIModel.GPT4OMini },
+  config: { model: AxAIOpenAIModel.GPT54Mini },
 });
 
 const teacher = ai({
   name: 'openai',
   apiKey: process.env.OPENAI_APIKEY!,
-  config: { model: AxAIOpenAIModel.GPT4O },
+  config: { model: AxAIOpenAIModel.GPT54 },
 });
 
 const classifier = ax(
@@ -107,13 +107,13 @@ import { ai, flow, optimize, AxAIOpenAIModel } from '@ax-llm/ax';
 const student = ai({
   name: 'openai',
   apiKey: process.env.OPENAI_APIKEY!,
-  config: { model: AxAIOpenAIModel.GPT4OMini },
+  config: { model: AxAIOpenAIModel.GPT54Mini },
 });
 
 const teacher = ai({
   name: 'openai',
   apiKey: process.env.OPENAI_APIKEY!,
-  config: { model: AxAIOpenAIModel.GPT4O },
+  config: { model: AxAIOpenAIModel.GPT54 },
 });
 
 const wf = flow<{ emailText: string }>()

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: "22.0.7"
+version: "22.0.9"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
@@ -90,7 +90,7 @@ for await (const chunk of gen.streamingForward(llm, { question: 'Tell a story' }
 
 | Goal | Option | Example |
 |------|--------|---------|
-| Model override | `model` | `{ model: 'gpt-4o-mini' }` |
+| Model override | `model` | `{ model: 'gpt-5.4-mini' }` |
 | Temperature | `modelConfig.temperature` | `{ modelConfig: { temperature: 0.8 } }` |
 | Max tokens | `modelConfig.maxTokens` | `{ modelConfig: { maxTokens: 500 } }` |
 | Retry on failure | `maxRetries` | `{ maxRetries: 3 }` |

package/skills/ax-playbook.md

@@ -0,0 +1,95 @@
+---
+name: ax-playbook
+description: This skill helps an LLM generate correct playbook code using @ax-llm/ax. Use when the user asks about playbook(), AxPlaybook, context playbooks, evolving context, ACE / Agentic Context Engineering, agent.playbook(), or growing/applying task knowledge offline and online with evolve() and update().
+version: "22.0.9"
+---
+
+# Playbook Codegen Rules (@ax-llm/ax)
+
+Use this skill to generate context-playbook code. A playbook grows an evolving body of task knowledge and renders it into a program's context. The evolution engine (ACE — Agentic Context Engineering) is hidden behind `playbook(...)`, exactly as `optimize(...)` hides its optimizer. Prefer the `playbook(...)` concept; only reach for `AxACE` directly when the user explicitly wants the low-level engine.
+
+## Use These Defaults
+
+- Create with `playbook(program, { studentAI, teacherAI? })`; it returns an `AxPlaybook` handle.
+- Grow offline with `await pb.evolve(examples, metric)` — returns `{ bestScore, playbook }`.
+- Grow online with `await pb.update({ example, prediction, feedback })` — no metric needed.
+- Apply with `pb.applyTo(program)` (defaults to the bound program).
+- Persist with `pb.toJSON()` and restore with `playbook(program, opts).load(snapshot)`.
+- Inspect with `pb.render()` (markdown) and `pb.getState()` (`{ playbook, artifact }`).
+- For agents use `agent.playbook({ target: 'actor' | 'responder' })`; default target is `'actor'`.
+- Use a cheaper `studentAI` to run the program and an optional stronger `teacherAI` to reflect/curate.
+- Prefer `ai()`, `ax()`, and `agent()` for new code.
+
+## Critical Rules
+
+- `playbook(...)` binds to an `AxGen` program; `evolve`/`update` need that program's signature.
+- `evolve()` returns only `{ bestScore, playbook }`. There is no Pareto front and no `optimizedProgram` — that is `optimize(...)`'s shape, not a playbook's.
+- `update({ example, prediction, feedback })` requires the full `{ example, prediction }`; `example` must match the program's input fields (plus any expected output). Do not pass bare input fields at the top level.
+- `update()` works without a prior `evolve()`/`load()` — the handle hydrates lazily on first use.
+- `applyTo()` injects a `## Context Playbook` block into the program description; calling it repeatedly recomposes from the original base (no stacking).
+- Keep the offline `metric` deterministic and cheap, like a GEPA metric.
+- A playbook is plain JSON. Persist `pb.toJSON()` and `load(...)` it into a fresh program for production.
+- This is a TypeScript feature; do not suggest it for the generated (Python/Go/Rust/Java/C++) packages yet.
+
+## Offline Pattern (evolve)
+
+```typescript
+import { type AxMetricFn, ai, ax, playbook } from '@ax-llm/ax';
+
+const program = ax('review:string -> sentiment:class "positive, negative"');
+const studentAI = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
+const metric: AxMetricFn = ({ prediction, example }) =>
+  (prediction as any).sentiment === (example as any).sentiment ? 1 : 0;
+
+const pb = playbook(program, { studentAI, maxEpochs: 2 });
+const { bestScore } = await pb.evolve(train, metric);
+pb.applyTo(program);
+```
+
+## Online Pattern (update)
+
+```typescript
+// After a real run, feed the outcome back so the playbook keeps learning.
+await pb.update({
+  example: { review: 'Five stars, would buy again.' },
+  prediction: { sentiment: 'negative' },
+  feedback: 'WRONG: enthusiastic praise is positive.',
+});
+pb.applyTo(program);
+```
+
+## Persist And Restore
+
+```typescript
+const snapshot = pb.toJSON(); // { playbook, artifact } — plain JSON
+// later, in another process / a production program instance:
+playbook(prodProgram, { studentAI }).load(snapshot).applyTo(prodProgram);
+```
+
+## Agents
+
+```typescript
+const a = agent('ticket:string -> reply:string', { ai });
+const apb = a.playbook({ target: 'actor' }); // 'actor' (default) or 'responder'
+await apb.update({ example, prediction, feedback }); // injected into the live stage prompt
+```
+
+Offline `evolve(...)` on an agent stage scores that stage in isolation; for full-pipeline tuning of agent instructions and demos use `agent.optimize(...)` (GEPA).
+
+## Playbook vs optimize()
+
+- `playbook(...)` — accumulate reusable, evolving task knowledge; the only path that also learns online via `update(...)`.
+- `optimize(...)` / `agent.optimize(...)` — tune instruction text and few-shot demos offline to a best/Pareto result.
+- They are complementary; a project can use both.
+
+## Troubleshooting
+
+- "Cannot convert undefined or null to object" from `update()` → you passed input fields at the top level; wrap them in `example: { ... }`.
+- Empty playbook after `evolve()` → the model already scored well, so nothing was curated; use harder/ambiguous examples or a weaker `studentAI` to surface lessons.
+- Playbook not affecting an agent's behavior → ensure `apply` is not `false` and you used `agent.playbook(...)` (not a bare `playbook()` on an internal program).
+
+## See Also
+
+- `ax-gepa` - `optimize(...)` and `AxGEPA` for instruction/demo tuning.
+- `ax-agent-context` - choosing between contextMap, contextPolicy, `agent.playbook(...)`, and recall.
+- `ax-agent-optimize` - `agent.optimize(...)` GEPA tuning for agents.

package/skills/ax-refine.md

@@ -1,7 +1,7 @@
 ---
 name: ax-refine
 description: Use this skill when writing or reviewing Ax bestOfN/refine code, reward functions, thresholds, native sample selection, serial attempts, generated advice, and attempt diagnostics.
-version: "22.0.7"
+version: "22.0.9"
 ---
 
 # Ax Refine And BestOfN

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: "22.0.7"
+version: "22.0.9"
 ---
 
 # Ax Signature Reference