@ax-llm/ax 22.0.3 → 22.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "22.0.3",
+  "version": "22.0.4",
   "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, 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.3"
+version: "22.0.4"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)
@@ -24,7 +24,7 @@ Use this skill when an agent needs a persistent context map, task-relevant memor
 
 Use `contextMap` when repeated runs ask different questions over the same long context, document set, or repository. The map is prompt-resident orientation knowledge: structure, concepts, constants, parsing schema, reusable aggregate results, and concrete error patterns. It is not a task-specific answer cache.
 
-Runnable example: [`src/examples/rlm-context-map.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-context-map.ts) demonstrates one update, `onUpdate` snapshot persistence, finite evolve, and frozen map reuse.
+   Runnable example: [`src/examples/rlm-context-map-live.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-context-map-live.ts) demonstrates a provider-backed context-map update, `onUpdate` snapshot persistence, finite evolve, and frozen map reuse.
 
 When `contextMap` is configured:
 
@@ -325,6 +325,7 @@ skills?: readonly AxAgentSkillResult[];
 Fetch this for full working code:
 
 - [RLM Memories and Skills](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-memories-and-skills.ts) - `onMemoriesSearch` + `recall()` and `onSkillsSearch` + `discover({ skills })` with load observability and actual usage tracking via `onUsedMemories` / `onUsedSkills`
+- [Skills + Memory Ops Assistant](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/skills-and-memory-assistant.ts) - an on-call assistant that recalls past decisions from a memory store and loads the right runbook skill on demand (also ported to Python, Go, Rust, Java, and C++ under `src/examples/<lang>/long-agents/`). All six languages support the native `onMemoriesSearch` / `onSkillsSearch` host callbacks, passed in the agent options at construction (Go/Java use native function values, Rust a `agent_with_search_callbacks` constructor, C++ a `register_*_search` helper); a static `memory_search_results` / `skill_search_results` config is also available.
 
 ## Do Not Generate
 

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.3"
+version: "22.0.4"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)

package/skills/ax-agent-optimize.md

@@ -1,12 +1,12 @@
 ---
 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.3"
+version: "22.0.4"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)
 
-Use this skill for `agent.optimize(...)` workflows. Prefer short, modern, copyable patterns. Do not repeat general agent-authoring guidance unless the user needs it.
+Use this skill for `agent.optimize(...)` workflows. Prefer short, modern, copyable patterns. Do not repeat general agent-authoring guidance unless the user needs it. For generic `ax(...)` or `flow(...)` tuning with top-level `optimize(...)`, use the `ax-gepa` skill instead.
 
 Your job is to help the model choose a good optimization setup for the user's actual goal:
 
@@ -19,6 +19,7 @@ Your job is to help the model choose a good optimization setup for the user's ac
 
 - Use `agent.optimize(...)` only after the agent is already configured and runnable.
 - Prefer the built-in judge path first for normal agent tuning. Most users should start with tasks that include `input` and `criteria`, then let `agent.optimize(...)` use its default actor target and judge-based metric.
+- Keep top-level `optimize(program, train, metric, options)` for non-agent generators and flows; do not rewrite normal agent task-record examples to the generic helper.
 - Prefer a deterministic custom `metric` only when success is easy to score from the prediction and task record.
 - Add `judgeAI` plus `judgeOptions` when the judge should run on a stronger or separate model than the agent runtime model.
 - Only reach for a plain typed `AxGen` evaluator when the user needs LLM-as-judge behavior outside the built-in `agent.optimize(...)` flow.

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.3"
+version: "22.0.4"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)
@@ -470,8 +470,13 @@ Fetch these for full working code:
 - [RLM Long Task](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-long-task.ts) - RLM context policy
 - [RLM Discovery](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-discovery.ts) - discovery mode, grouped tools, child agents as functions, and semantic `llmQuery(...)`
 - [RLM Adaptive Replay](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-adaptive-replay.ts) - adaptive replay
-- [RLM Live Runtime State](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-live-runtime-state.ts) - structured runtime-state rendering
-- [RLM Clarification Resume](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-clarification-resume.ts) - clarification exception plus `getState()` / `setState(...)`
+
+Flagship real-world long-agents (also ported to Python, Go, Rust, Java, and C++ under `src/examples/<lang>/long-agents/`; run with `npm run example -- <lang> <path>`):
+
+- [Incident Log Forensics](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/incident-log-forensics.ts) - large-context log forensics over `contextFields` (Gemini)
+- [Codebase Peek Map](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/codebase-peek-map.ts) - Peek-paper context-map orientation over a large repo snapshot
+- [Data Analyst with Tools](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/data-analyst-with-tools.ts) - large data dictionary in `contextFields` + typed warehouse tools the model queries instead of inlining
+- [Self-Improving Lab](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/typescript/long-agents/self-improving-lab.ts) - many-tool agent that runs experiments, grades them with an independent verifier, and distills verified rules into memory
 
 ## Do Not Generate
 

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.3"
+version: "22.0.4"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)
@@ -558,7 +558,7 @@ Use these method groups as the compact AxAgent surface map:
 
 - Running: `forward(ai, values, options?)` and `streamingForward(ai, values, options?)`.
 - Forward-time agent options: `skills`, `onUsedMemories`, and `onUsedSkills`; use `ax-agent-memory-skills` for details.
-- 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.ts`](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/rlm-context-map.ts) for persistence and finite-evolve usage.
+- 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.
 
@@ -575,9 +575,9 @@ When the user wants `agent.optimize(...)`, judge configuration, eval datasets, s
 
 Keep this skill focused on building and running agents. For tuning work:
 
-- use eval-safe tools or in-memory mocks
+- use eval-safe tools
 - treat `judgeOptions` as part of the optimize workflow
-- choose a deterministic `metric` when scoring is objective; use the built-in judge only when run quality needs qualitative review
+- choose an objective `metric` when scoring is mechanical; use the built-in judge only when run quality needs qualitative review
 - keep runtime authoring guidance here and optimization guidance in `ax-agent-optimize`
 
 ## Examples

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.3"
+version: "22.0.4"
 ---
 
 # 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: "22.0.3"
+version: "22.0.4"
 ---
 
 # 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.3"
+version: "22.0.4"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)
@@ -386,6 +386,9 @@ wf.setDemos([{ programId: 'root.summarizer', traces: [] }]);
 wf.applyOptimization(optimizedProgram);
 ```
 
+For tuning a flow, use top-level `optimize(wf, train, metric, options)` from the
+`ax-gepa` skill. There is no separate `flow.optimize(...)` helper.
+
 ## Chat Logs
 
 `AxFlow.getChatLog()` returns a flat `readonly AxChatLogEntry[]` after `forward()`. Each child-node entry is tagged with `entry.name` so callers can filter by node:
@@ -424,7 +427,6 @@ Fetch these for full working code:
 - [Enhanced Demo](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-enhanced-demo.ts) — instance-based nodes
 - [Flow as Function](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/ax-flow-to-function.ts) — flow as callable function
 - [Fluent Builder](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/fluent-flow-example.ts) — fluent builder pattern
-- [Flow Logging](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/flow-logging-simple.ts) — flow logging
 - [Load Balancing](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/balancer.ts) — load balancing
 
 ## Do Not Generate

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.3"
+version: "22.0.4"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)

package/skills/ax-gepa.md

@@ -1,28 +1,29 @@
 ---
 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.3"
+version: "22.0.4"
 ---
 
-# AxGEPA Codegen Rules (@ax-llm/ax)
+# GEPA Optimization Codegen Rules (@ax-llm/ax)
 
-Use this skill to generate direct `AxGEPA` optimization code. Prefer short, modern, copyable patterns over long explanation.
+Use this skill to generate GEPA optimization code. Prefer the top-level `optimize(...)` helper for normal code, and use direct `AxGEPA` / `AxBootstrapFewShot` only when the user needs low-level optimizer control.
 
 ## Use These Defaults
 
-- Use `new AxGEPA({ studentAI, teacherAI, ... })`.
+- Use `optimize(program, train, metric, { studentAI, teacherAI, ... })` for normal generator and flow tuning.
 - Prefer `ai()`, `ax()`, and `flow()` for new code.
 - Use a strong `teacherAI` and a cheaper `studentAI`.
-- Always pass `validationExamples` to `compile()`.
-- Always set `maxMetricCalls` to bound optimizer cost.
+- Pass `validationExamples` when you have a holdout set.
+- Set `maxMetricCalls` to bound optimizer cost; `optimize(...)` defaults it to `100`.
 - Use scalar metrics for one objective and object metrics for Pareto optimization.
 - Apply results with `program.applyOptimization(result.optimizedProgram!)`.
 - For tree-wide runs, expect `optimizedProgram.componentMap`.
 - Persist artifacts with `axSerializeOptimizedProgram(...)` and restore them with `axDeserializeOptimizedProgram(...)` so the same flow works in browsers and Node.
+- `optimize(...)` runs `AxBootstrapFewShot -> AxGEPA` for small starter sets by default, preserving the demos in `result.optimizedProgram.demos`.
 
 ## Critical Rules
 
-- `AxGEPA.compile()` works for a single generator and for tree-aware roots such as flows or agents with registered optimizable descendants.
+- `optimize(...)` and `AxGEPA.compile()` work for a single generator and for tree-aware roots such as flows or agents with registered optimizable descendants.
 - There is no separate flow-only GEPA optimizer. Use `AxGEPA` for flows too.
 - The metric may return either `number` or `Record<string, number>`.
 - Keep metrics deterministic and cheap by default.
@@ -32,7 +33,7 @@ Use this skill to generate direct `AxGEPA` optimization code. Prefer short, mode
 - GEPA optimizes generic string components exposed by `getOptimizableComponents()`. If a tree exposes no components, optimization will fail.
 - Use held-out validation examples for selection. Do not reuse the training set as `validationExamples`.
 - `result.optimizedProgram` is the easy-to-apply best candidate. `result.paretoFront` is the full trade-off set for multi-objective runs.
-- `bootstrap: true` can seed GEPA with demos collected from successful runs on the provided training tasks.
+- Direct `AxGEPA` still has its own `bootstrap` option, but top-level `optimize(...)` composes the existing `AxBootstrapFewShot` optimizer before GEPA instead.
 
 ## Metric Selection
 
@@ -45,13 +46,13 @@ Choose the evaluation path deliberately:
 
 Rule of thumb:
 
-- `AxGEPA` on `AxGen` or flow: use a metric first, optionally a plain typed `AxGen` evaluator if needed.
+- `optimize(...)` on `AxGen` or flow: use a metric first, optionally a plain typed `AxGen` evaluator if needed.
 - `agent.optimize(...)`: use custom `metric` for crisp scoring, otherwise let the built-in judge handle scoring. Add `judgeAI` plus `judgeOptions` only when you want a stronger or separate judge model.
 
 ## Canonical Scalar Pattern
 
 ```typescript
-import { ai, ax, AxAIOpenAIModel, AxGEPA } from '@ax-llm/ax';
+import { ai, ax, optimize, AxAIOpenAIModel } from '@ax-llm/ax';
 
 const student = ai({
   name: 'openai',
@@ -82,7 +83,7 @@ const validation = [
 const metric = ({ prediction, example }: { prediction: any; example: any }) =>
   prediction?.priority === example?.priority ? 1 : 0;
 
-const optimizer = new AxGEPA({
+const result = await optimize(classifier, train, metric, {
   studentAI: student,
   teacherAI: teacher,
   numTrials: 12,
@@ -90,9 +91,6 @@ const optimizer = new AxGEPA({
   minibatchSize: 4,
   earlyStoppingTrials: 4,
   sampleCount: 1,
-});
-
-const result = await optimizer.compile(classifier, train, metric, {
   validationExamples: validation,
   maxMetricCalls: 120,
 });
@@ -104,7 +102,7 @@ console.log(result.bestScore);
 ## Canonical Pareto Pattern
 
 ```typescript
-import { ai, flow, AxAIOpenAIModel, AxGEPA } from '@ax-llm/ax';
+import { ai, flow, optimize, AxAIOpenAIModel } from '@ax-llm/ax';
 
 const student = ai({
   name: 'openai',
@@ -153,7 +151,7 @@ const metric = ({ prediction, example }: { prediction: any; example: any }) => {
   return { accuracy, brevity };
 };
 
-const result = await new AxGEPA({
+const result = await optimize(wf, train, metric, {
   studentAI: student,
   teacherAI: teacher,
   numTrials: 16,
@@ -161,7 +159,6 @@ const result = await new AxGEPA({
   minibatchSize: 6,
   earlyStoppingTrials: 5,
   sampleCount: 1,
-}).compile(wf, train, metric, {
   validationExamples: validation,
   maxMetricCalls: 240,
 });
@@ -259,6 +256,7 @@ const optimizer = new AxGEPA({
 
 ## Good Example Targets
 
+- `/Users/vr/src/ax/src/examples/optimize.ts`
 - `/Users/vr/src/ax/src/examples/gepa.ts`
 - `/Users/vr/src/ax/src/examples/gepa-flow.ts`
 - `/Users/vr/src/ax/src/examples/gepa-train-inference.ts`

package/skills/ax-llm.md

@@ -1,19 +1,19 @@
 ---
 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.3"
+version: "22.0.4"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
 
 Ax is a TypeScript library for building LLM-powered applications with type-safe signatures, streaming support, and multi-provider compatibility.
 
-> **Detailed skills available:** ax-ai (providers), ax-signature (signatures/types), ax-gen (generators), ax-agent (core agents/tools), ax-agent-rlm (agent runtime/RLM/delegation), ax-agent-observability (callbacks/logs/usage), ax-agent-memory-skills (recall and dynamic skill loading), ax-agent-optimize (agent tuning/eval), ax-flow (workflows), ax-gepa (Pareto optimization).
+> **Detailed skills available:** ax-ai (providers), ax-signature (signatures/types), ax-gen (generators), ax-agent (core agents/tools), ax-agent-rlm (agent runtime/RLM/delegation), ax-agent-observability (callbacks/logs/usage), ax-agent-memory-skills (recall and dynamic skill loading), ax-agent-optimize (agent tuning/eval), ax-flow (workflows), ax-gepa (top-level `optimize(...)`, BootstrapFewShot -> GEPA, Pareto optimization).
 
 ## Imports & Factories
 
 ```typescript
-// Prefer factory functions: ax(), ai(), agent(), flow() — not new AxGen(), new AxAI(), etc.
+// Prefer factory functions: ax(), ai(), agent(), flow(); avoid class constructors.
 import { ax, ai, f, s, fn, agent, flow, AxMemory, AxMCPClient } from '@ax-llm/ax';
 import { z } from 'zod'; // optional — any Standard Schema v1 library works
 

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