@ax-llm/ax 22.0.0 → 22.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "22.0.0",
+  "version": "22.0.2",
   "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.0"
+version: "22.0.2"
 ---
 
 # 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.0"
+version: "22.0.2"
 ---
 
 # 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.0"
+version: "22.0.2"
 ---
 
 # 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(...), recursionOptions, or long-running agent runtime behavior.
-version: "22.0.0"
+version: "22.0.2"
 ---
 
 # 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.0"
+version: "22.0.2"
 ---
 
 # 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/HuggingFace/Reka/Grok with @ax-llm/ax.
-version: "22.0.0"
+version: "22.0.2"
 ---
 
 # 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.0"
+version: "22.0.2"
 ---
 
 # 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.0"
+version: "22.0.2"
 ---
 
 # 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, streaming guards, field processors, step hooks, self-tuning, or structured outputs.
-version: "22.0.0"
+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.2"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)
@@ -14,8 +14,9 @@ Use this skill to generate `AxGen` code. Prefer short, modern, copyable patterns
 - Always pass an AI instance from `ai(...)` as the first argument to `forward()`.
 - Streaming uses `streamingForward()`, not `forward()` with a stream option.
 - Use schema validation for field shape and constraints.
+- Use `addAssert(...)` for whole-output hard invariants with correction retries.
+- Use `addStreamingAssert(...)` for partial streaming hard invariants with fail-fast per-attempt correction retries.
 - Use `bestOfN(...)` / `refine(...)` for reward-scored complete outputs.
-- Streaming guards abort unsafe partial output; they do not retry or refine.
 - Step hook mutations are applied at the next step boundary (pending pattern).
 - `stopFunction` accepts a string or string[] for multiple stop functions.
 - Multi-step continues until: all outputs filled, stop function called, or `maxSteps` reached.
@@ -195,8 +196,13 @@ const selected = bestOfN(gen, {
   rewardFn: ({ prediction }) => prediction.summary.length,
 });
 
-// Streaming guards: fail fast on unsafe partial output.
-gen.addStreamingGuard(
+// Whole-output assertion: retries with correction feedback.
+gen.addAssert(
+  (output) => output.summary.includes(topic) || 'Summary must mention the topic.'
+);
+
+// Streaming assertion: fail fast on unsafe partial output.
+gen.addStreamingAssert(
   'summary',
   (text) => !text.includes('forbidden'),
   'Output contains forbidden text'
@@ -206,11 +212,11 @@ gen.addStreamingGuard(
 Rules:
 
 - Schema validation retries with parser/constraint feedback.
+- `addAssert(...)` checks the complete parsed output after validation/processors and retries with correction feedback on failure.
 - `bestOfN(...)` scores complete candidates and returns the highest reward or first threshold hit.
 - `refine(...)` runs rounds and can feed reward-derived advice into instruction components between rounds.
-- `addStreamingGuard(...)` targets a string/code output field and receives partial text so far.
-- Streaming guards only abort the stream by throwing `AxStreamingGuardError`.
-- Breaking migration: do not generate removed `addAssert(...)` or `addStreamingAssert(...)` APIs.
+- `addStreamingAssert(...)` targets a string/code output field and receives partial text so far.
+- Streaming assertions abort the current stream attempt by throwing `AxStreamingAssertionError`, then feed correction feedback into AxGen retries.
 
 ## Field Processors
 
@@ -471,7 +477,7 @@ Fetch these for full working code:
 - [Streaming](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming.ts) — field-by-field streaming
 - [Best Of N](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/best-of-n.ts) — reward-scored sample selection
 - [Refine](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/refine.ts) — retry rounds with generated feedback
-- [Streaming Guard](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming-guard.ts) — fail-fast partial-output safety
+- [Streaming Assert](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/streaming-asserts.ts) — fail-fast partial-output correction
 - [Structured Output](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/structured_output.ts) — fluent API with validation
 - [Debug Logging](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/debug-logging.ts) — debug mode and step hooks
 - [Stop Function](https://raw.githubusercontent.com/ax-llm/ax/refs/heads/main/src/examples/stop-function.ts) — stop functions
@@ -484,6 +490,6 @@ Fetch these for full working code:
 - Do not use `new AxGen(...)` for new code unless explicitly required.
 - Do not pass raw API keys or config objects where an `ai(...)` instance is expected.
 - Do not use `forward()` for streaming; use `streamingForward()`.
-- Do not use streaming guards as retry/refine mechanisms; they only abort unsafe partial output.
+- Do not use streaming assertions as reward/refine mechanisms; they enforce hard partial-output invariants and retry with correction.
 - Do not mutate step hook context expecting immediate effect; mutations are pending until the next step.
 - Do not assume multi-step stops after one LLM call; it continues until outputs are filled, a stop function fires, or `maxSteps` is reached.

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.0"
+version: "22.0.2"
 ---
 
 # AxGEPA 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: "22.0.0"
+version: "22.0.2"
 ---
 
 # Ax Library (@ax-llm/ax) Quick Reference
@@ -308,7 +308,8 @@ class AxGen<IN, OUT> {
   forward(ai: AxAIService, values: IN, options?: AxProgramForwardOptions): Promise<OUT>;
   streamingForward(ai: AxAIService, values: IN, options?: AxProgramStreamingForwardOptions): AsyncGenerator<{ delta: Partial<OUT> }>;
   setExamples(examples: Array<Partial<IN & OUT>>): void;
-  addStreamingGuard(field: keyof OUT, fn: (chunk: string, done?: boolean) => boolean | string | undefined, message?: string): void;
+  addAssert(fn: (output: OUT) => boolean | string | undefined | Promise<boolean | string | undefined>, message?: string): void;
+  addStreamingAssert(field: keyof OUT, fn: (chunk: string, done?: boolean) => boolean | string | undefined | Promise<boolean | string | undefined>, message?: string): void;
   addFieldProcessor(field: keyof OUT, fn: (value: any) => any): void;
   addStreamingFieldProcessor(field: keyof OUT, fn: (chunk: string, ctx: any) => void): void;
   stop(): void;

package/skills/ax-refine.md

@@ -1,22 +1,22 @@
 ---
 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.0"
+version: "22.0.2"
 ---
 
 # Ax Refine And BestOfN
 
 Use `bestOfN(...)` when you can score complete outputs independently. Use `refine(...)` when failed rounds should produce feedback that changes the next attempt.
 
-## Breaking Migration
+## Validation And Assertions
 
-Treat this as a breaking API change:
+Keep reward scoring, whole-output assertions, and streaming assertions separate:
 
-- Do not generate `addAssert(...)` or `addStreamingAssert(...)`; they are removed.
-- Use schema validation for shape and field validity.
+- Use schema validation for shape, types, and field-level constraints.
+- Use `addAssert(...)` for whole-output hard invariants. Failed assertions feed correction text into the normal retry loop.
+- Use `addStreamingAssert(...)` for partial streaming hard invariants. It aborts the current stream attempt as soon as the partial field fails, then feeds correction text into the normal retry loop.
 - Use `bestOfN(...)` for complete-candidate selection.
-- Use `refine(...)` for retry rounds with generated feedback.
-- Use `addStreamingGuard(...)` only for fail-fast streaming safety.
+- Use `refine(...)` for reward-scored retry rounds with generated feedback.
 
 ## APIs
 
@@ -78,4 +78,4 @@ Rules:
 
 ## Streaming
 
-Do not use `refine(...)` for streaming. For partial-output safety, use `addStreamingGuard(fieldName, fn, message?)` on `AxGen`. Guards fail fast with `AxStreamingGuardError`; they do not retry, refine, or feed correction text back to the model.
+Do not use `refine(...)` for streaming. For partial-output safety, use `addStreamingAssert(fieldName, fn, message?)` on `AxGen`. Streaming assertions fail fast within the current attempt with `AxStreamingAssertionError`, then retry with correction feedback when retries remain.

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