@ax-llm/ax 23.0.0 → 23.0.1

package/package.json

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

package/skills/ax-agent-context.md

@@ -1,7 +1,7 @@
 ---
 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # AxAgent Context Selection (@ax-llm/ax)

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, memoriesCatalog, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, skillsCatalog, AxAgentCatalogSkill, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, preloading memories at forward time, relevanceRanking hints, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "23.0.0"
+version: "23.0.1"
 ---
 
 # 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)
@@ -45,6 +45,7 @@ Pick the optimization shape from the user's need:
 - "Make the whole agent better" -> use the default actor target first; only broaden target selection when the user clearly wants that extra scope.
 - "Tune child-agent delegation" -> use tasks that exercise when to call the child agent, when to call normal tools, and when to answer directly.
 - "Compare before and after" -> include a held-out task plus artifact save/load and replay.
+- "Repair the tasks it keeps failing, without eroding what works" -> this is playbook territory, not GEPA: use `agent.playbook().evolve(dataset)` (mines failures into verified playbook bullets under a held-out gate). See `ax-playbook`. `optimize(...)` maximizes a metric by tuning instructions and demos; `evolve(...)` grows the playbook.
 
 Choose task design carefully:
 

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: "23.0.0"
+version: "23.0.1"
 ---
 
 # 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -529,6 +529,8 @@ agent(signature, {
   functions,
   functionDiscovery,
   autoUpgrade,
+  playbook,
+  citations,
   ...agentOptions,
 });
 ```
@@ -576,6 +578,13 @@ Rules:
 - Values in required non-string fields (arrays, objects, numbers, media) are never auto-promoted — declare those in `contextFields` explicitly when they can be large.
 - Each promotion emits a `field_auto_promoted` context event (`onContextEvent`) with the field name, original size, and preview size; use it to observe what was kept out of the prompt.
 
+### Learning And Citations
+
+Two optional construction-time options (TypeScript, both default off):
+
+- `playbook`: attach an ACE playbook at construction. `learn` is on by default — after each run that produced failure signals (error turns, dead-ends, failing tool calls) one bounded update curates durable avoidance rules that ride the next run's actor prompt; zero LLM cost on clean runs. Seed a prior session with `playbook: { playbook: snapshot }`, persist via `onUpdate`, read the live handle with `getPlaybook()`, gate with `learn: { minSignals, dedupe }`, or disable with `learn: false`. To grow the same playbook from a task set with a held-out verify gate, use `agent.playbook().evolve(...)` — see `ax-playbook`.
+- `citations`: add an optional `evidenceCitations: string[]` responder output listing which evidence entries (top-level keys of the curated evidence, plus memory ids) the answer relied on. Validated in-pipeline — the model cannot cite evidence it never collected (existence, not entailment). Pass `true`, or `{ field?, surface?: 'output' | 'hidden', includeMemoryIds?, onCitations? }`.
+
 ## Public Surface
 
 Use these method groups as the compact AxAgent surface map:
@@ -585,6 +594,7 @@ Use these method groups as the compact AxAgent surface map:
 - State and control: `getState()`, `setState(state?)`, `getContextMap()`, `setContextMap(map?)`, `stop()`, `getSignature()`, `setSignature(signature)`, `getFunction()`, `getId()`, and `setId(id)`. Context-map evolve policy lives on `AxAgentContextMap` (`infiniteEvolve`, `evolveSteps`, `maxChars`), not on the agent config. See [`src/examples/rlm-context-map-live.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-context-map-live.ts) for provider-backed persistence and finite-evolve usage.
 - Observability: `getChatLog()`, `getUsage()`, `getStagedUsage()`, `resetUsage()`, and `getTraces()`; use `ax-agent-observability` for details.
 - Demos and tuning: `setDemos(...)`, `namedPrograms()`, `namedProgramInstances()`, `optimize(...)`, `applyOptimization(...)`, `getOptimizableComponents()`, and `applyOptimizedComponents(...)`; use `ax-agent-optimize` for tuning details.
+- Learning: `playbook()` returns an agent-aware `AxAgentPlaybook` handle (`update(...)`, `render()`, `getState()`, `load(...)`, and `evolve(dataset, options)`); `getPlaybook()` reads the current handle. Use `ax-playbook` for details.
 
 Rules:
 

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: "23.0.0"
+version: "23.0.1"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)

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: "23.0.0"
+version: "23.0.1"
 ---
 
 # 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # 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(), validation, assertions, streaming assertions, field processors, step hooks, self-tuning, or structured outputs.
-version: "23.0.0"
+version: "23.0.1"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)

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: "23.0.0"
+version: "23.0.1"
 ---
 
 # GEPA Optimization 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference

package/skills/ax-playbook.md

@@ -1,7 +1,7 @@
 ---
 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: "23.0.0"
+version: "23.0.1"
 ---
 
 # Playbook Codegen Rules (@ax-llm/ax)
@@ -68,13 +68,23 @@ playbook(prodProgram, { studentAI }).load(snapshot).applyTo(prodProgram);
 
 ## Agents
 
+`a.playbook({ target })` returns an agent-aware `AxAgentPlaybook` (the stage `AxPlaybook` handle plus an agent-level `evolve`). The one playbook the agent renders into its prompt grows three ways:
+
+- Continuous (trust): the construction-time `playbook` option (see `ax-agent`) harvests each run's failures automatically — no dataset.
+- On-demand (trust): `apb.update({ example, prediction, feedback })`.
+- Batch verified (proof): `apb.evolve(dataset, options)` runs the full agent over a task set, mines failure clusters, and proposes one playbook bullet per weakness; with `verify` (default on) it keeps a bullet only if held-in improves AND the `validation` held-out set does not regress, else exact rollback. `verify: false` = trust-batch. Bullets-only.
+
 ```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
+const apb = a.playbook({ target: 'actor' }); // agent-aware handle; 'actor' (default) or 'responder'
+await apb.update({ example, prediction, feedback }); // online: injected into the live stage prompt
+const result = await apb.evolve(
+  { train, validation }, // AxAgentEvalDataset
+  { metric, runsPerTask: 2 }, // verify:true by default
+);
 ```
 
-Offline `evolve(...)` on an agent stage scores that stage in isolation; for full-pipeline tuning of agent instructions and demos use `agent.optimize(...)` (GEPA).
+The agent-level `evolve(dataset, options)` is distinct from the program-level `pb.evolve(examples, metric)` above: it takes an `AxAgentEvalDataset` plus options, runs the whole pipeline, and returns baseline/final held-in & held-out with per-bullet outcomes (no `{ bestScore }`). For full-pipeline tuning of agent instructions and demos (not the playbook) use `agent.optimize(...)` (GEPA).
 
 ## Playbook vs optimize()
 

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