@ax-llm/ax 18.0.0 → 18.0.2

package/package.json

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

package/scripts/postinstall.mjs

@@ -19,9 +19,10 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  rmSync,
   writeFileSync,
 } from 'node:fs';
-import { dirname, join, sep } from 'node:path';
+import { basename, dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -118,6 +119,20 @@ function getInstalledVersion(targetPath) {
   }
 }
 
+/**
+ * Get the skill name from YAML frontmatter, falling back to filename without .md
+ */
+function getSkillName(filePath) {
+  try {
+    const content = readFileSync(filePath, 'utf8');
+    const match = content.match(/^name:\s*["']?([^"'\n\r]+)/m);
+    if (match) return match[1].trim();
+  } catch {
+    // Fall through to fallback
+  }
+  return basename(filePath, '.md');
+}
+
 /**
  * Get the package version from the skill source file
  */
@@ -173,7 +188,7 @@ function install() {
     // Paths
     const skillsSourceDir = join(__dirname, '..', 'skills');
     const projectRoot = findProjectRoot();
-    const skillTargetDir = join(projectRoot, '.claude', 'skills', 'ax');
+    const skillsBaseDir = join(projectRoot, '.claude', 'skills');
 
     // Discover all *.md skill files
     if (!existsSync(skillsSourceDir)) {
@@ -188,11 +203,28 @@ function install() {
       return;
     }
 
+    // Clean up legacy flat file structure (.claude/skills/ax/*.md except SKILL.md)
+    const legacyDir = join(skillsBaseDir, 'ax');
+    if (existsSync(legacyDir)) {
+      try {
+        const legacyFiles = readdirSync(legacyDir).filter(
+          (f) => f.endsWith('.md') && f !== 'SKILL.md'
+        );
+        for (const f of legacyFiles) {
+          rmSync(join(legacyDir, f), { force: true });
+        }
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+
     const results = [];
 
     for (const file of skillFiles) {
       const skillSource = join(skillsSourceDir, file);
-      const skillTarget = join(skillTargetDir, file);
+      const skillName = getSkillName(skillSource);
+      const skillDir = join(skillsBaseDir, skillName);
+      const skillTarget = join(skillDir, 'SKILL.md');
 
       const packageVersion = getPackageVersion(skillSource);
       const installedVersion = getInstalledVersion(skillTarget);
@@ -218,13 +250,13 @@ function install() {
       }
 
       if (shouldInstallFile) {
-        if (!existsSync(skillTargetDir)) {
-          mkdirSync(skillTargetDir, { recursive: true });
+        if (!existsSync(skillDir)) {
+          mkdirSync(skillDir, { recursive: true });
         }
 
         const content = readFileSync(skillSource, 'utf8');
         writeFileSync(skillTarget, content, 'utf8');
-        results.push({ file, action, versionInfo });
+        results.push({ file: skillName, action, versionInfo });
       }
     }
 

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps with building AxAgent-based agents using @ax-llm/ax. Use when the user asks about agent(), AxAgent, child agents, tool functions, RLM mode, stopping agents, or composing multi-agent hierarchies.
-version: "18.0.0"
+version: "18.0.2"
 ---
 
 # AxAgent Guide (@ax-llm/ax)
@@ -11,15 +11,23 @@ AxAgent is the agent framework in Ax. It wraps AxGen with support for child agen
 ## Quick Reference
 
 ```typescript
-import { agent, ai } from '@ax-llm/ax';
+import { agent, ai, f } from '@ax-llm/ax';
 
 const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
 
 // Create and run an agent
-const myAgent = agent('userQuestion:string -> responseText:string', {
-  name: 'helpfulAgent',
-  description: 'An agent that provides helpful responses to user questions',
-});
+const myAgent = agent(
+  f()
+    .input('userQuestion', f.string())
+    .output('responseText', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'helpfulAgent',
+      description: 'An agent that provides helpful responses to user questions',
+    },
+  }
+);
 
 const result = await myAgent.forward(llm, { userQuestion: 'What is TypeScript?' });
 console.log(result.responseText);
@@ -33,70 +41,65 @@ for await (const chunk of stream) {
 
 ## Creating Agents
 
-Use the `agent()` factory function with a string signature:
+Use the `agent()` factory function with a signature built using `f()`:
 
 ```typescript
-import { agent, ai } from '@ax-llm/ax';
+import { agent, ai, f } from '@ax-llm/ax';
 
 const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
 
-const myAgent = agent('userQuestion:string -> responseText:string', {
-  name: 'helpfulAgent',
-  description: 'An agent that provides helpful responses to user questions',
-});
+const myAgent = agent(
+  f()
+    .input('userQuestion', f.string())
+    .output('responseText', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'helpfulAgent',
+      description: 'An agent that provides helpful responses to user questions',
+    },
+  }
+);
 
 const result = await myAgent.forward(llm, { userQuestion: 'What is TypeScript?' });
 console.log(result.responseText);
 ```
 
-The `agent()` function accepts both string signatures and `AxSignature` objects:
-
-```typescript
-import { agent, s } from '@ax-llm/ax';
-
-const sig = s('userQuestion:string -> responseText:string');
-const myAgent = agent(sig, {
-  name: 'helpfulAgent',
-  description: 'An agent that provides helpful responses to user questions',
-});
-```
-
 ## Agent Options
 
 The `agent()` factory accepts a configuration object:
 
 ```typescript
-const myAgent = agent('input:string -> output:string', {
-  // Required
-  name: 'myAgent',                    // Agent name (min 5 chars)
-  description: 'Does something useful and interesting with inputs',  // Min 20 chars
-
-  // Optional
-  ai: llm,                            // Bind a specific AI service
-  definition: 'You are a helpful assistant that... (detailed prompt)',  // Min 100 chars if provided
-  functions: [searchTool, calcTool],   // Tool functions
-  agents: [childAgent1, childAgent2],  // Child agents
-  maxSteps: 25,                        // Max reasoning steps (default: 25)
-  maxRetries: 3,                       // Retries on assertion failures
-  temperature: 0.7,                    // Sampling temperature
-  debug: false,                        // Debug logging
-
-  // RLM mode (see RLM section below)
-  rlm: { ... },
-});
-```
-
-### `name`
-
-The agent's name, used as the function name when called as a child agent. Minimum 5 characters. Converted to camelCase automatically (e.g. `'Physics Researcher'` becomes `physicsResearcher`).
-
-### `description`
+const myAgent = agent(
+  f()
+    .input('input', f.string())
+    .output('output', f.string())
+    .build(),
+  {
+    // Agent identity (required when used as a child agent)
+    agentIdentity: {
+      name: 'myAgent',                  // Agent name (converted to camelCase)
+      description: 'Does something useful and interesting with inputs',
+    },
 
-A short description of what the agent does. Minimum 20 characters. This is shown to parent agents when they decide which child to call.
+    // Optional
+    ai: llm,                            // Bind a specific AI service
+    functions: [searchTool, calcTool],   // Tool functions
+    agents: [childAgent1, childAgent2],  // Child agents
+    maxSteps: 25,                        // Max reasoning steps (default: 25)
+    maxRetries: 3,                       // Retries on assertion failures
+    temperature: 0.7,                    // Sampling temperature
+    debug: false,                        // Debug logging
+
+    // RLM mode (see RLM section below)
+    rlm: { ... },
+  }
+);
+```
 
-### `definition`
+### `agentIdentity`
 
-An optional detailed system prompt for the LLM. Minimum 100 characters if provided. If omitted, the `description` is used as the prompt.
+Required when the agent is used as a child agent. Contains `name` (converted to camelCase for the function name, e.g. `'Physics Researcher'` becomes `physicsResearcher`) and `description` (shown to parent agents when they decide which child to call).
 
 ### `functions`
 
@@ -120,11 +123,19 @@ console.log(result.responseText);
 If the agent was created with `ai` bound, the parent AI is used as fallback:
 
 ```typescript
-const myAgent = agent('input:string -> output:string', {
-  name: 'myAgent',
-  description: 'An agent that processes inputs reliably',
-  ai: llm,
-});
+const myAgent = agent(
+  f()
+    .input('input', f.string())
+    .output('output', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'myAgent',
+      description: 'An agent that processes inputs reliably',
+    },
+    ai: llm,
+  }
+);
 
 // Can also pass a different AI to override
 const result = await myAgent.forward(differentLlm, { input: 'test' });
@@ -168,10 +179,18 @@ const result = await myAgent.forward(llm, values, {
 Call `stop()` from any context — a timer, event handler, or another async task — to halt the multi-step loop. `stop()` aborts all in-flight calls started by the same `AxAgent` instance (including retry backoff waits):
 
 ```typescript
-const myAgent = agent('question:string -> answer:string', {
-  name: 'myAgent',
-  description: 'An agent that answers questions thoroughly',
-});
+const myAgent = agent(
+  f()
+    .input('question', f.string())
+    .output('answer', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'myAgent',
+      description: 'An agent that answers questions thoroughly',
+    },
+  }
+);
 
 const timer = setTimeout(() => myAgent.stop(), 5_000);
 
@@ -192,7 +211,12 @@ try {
 `stop()` is also available on `AxGen` and `AxFlow` instances:
 
 ```typescript
-const gen = ax('topic:string -> summary:string');
+const gen = ax(
+  f()
+    .input('topic', f.string())
+    .output('summary', f.string())
+    .build()
+);
 setTimeout(() => gen.stop(), 3_000);
 
 try {
@@ -240,7 +264,7 @@ try {
 Define tool functions with a name, description, JSON Schema parameters, and implementation:
 
 ```typescript
-import { ai, agent } from '@ax-llm/ax';
+import { ai, agent, f } from '@ax-llm/ax';
 
 const getCurrentWeather = {
   name: 'getCurrentWeather',
@@ -258,11 +282,19 @@ const getCurrentWeather = {
   }
 };
 
-const weatherAgent = agent('query:string -> response:string', {
-  name: 'weatherAssistant',
-  description: 'An assistant that helps with weather queries',
-  functions: [getCurrentWeather]
-});
+const weatherAgent = agent(
+  f()
+    .input('query', f.string())
+    .output('response', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'weatherAssistant',
+      description: 'An assistant that helps with weather queries',
+    },
+    functions: [getCurrentWeather]
+  }
+);
 
 const llm = ai({ name: 'openai', apiKey: process.env.OPENAI_APIKEY! });
 const result = await weatherAgent.forward(llm, { query: 'Weather in Tokyo?' });
@@ -274,27 +306,47 @@ Agents can compose other agents as children. The parent agent sees each child as
 
 ```typescript
 const researcher = agent(
-  'question:string, physicsQuestion:string -> answer:string',
+  f()
+    .input('question', f.string())
+    .input('physicsQuestion', f.string())
+    .output('answer', f.string())
+    .build(),
   {
-    name: 'Physics Researcher',
-    description: 'Researcher for physics questions can answer questions about advanced physics',
+    agentIdentity: {
+      name: 'Physics Researcher',
+      description: 'Researcher for physics questions can answer questions about advanced physics',
+    },
   }
 );
 
 const summarizer = agent(
-  'answer:string -> shortSummary:string',
+  f()
+    .input('answer', f.string())
+    .output('shortSummary', f.string())
+    .build(),
   {
-    name: 'Science Summarizer',
-    description: 'Summarizer can write short summaries of advanced science topics',
-    definition: 'You are a science summarizer. You can write short summaries of advanced science topics. Use numbered bullet points to summarize the answer in order of importance.',
+    agentIdentity: {
+      name: 'Science Summarizer',
+      description: 'Summarizer can write short summaries of advanced science topics',
+    },
   }
 );
 
-const scientist = agent('question:string -> answer:string', {
-  name: 'Scientist',
-  description: 'An agent that can answer advanced science questions',
-  agents: [researcher, summarizer],
-});
+summarizer.setActorDescription('You are a science summarizer. You can write short summaries of advanced science topics. Use numbered bullet points to summarize the answer in order of importance.');
+
+const scientist = agent(
+  f()
+    .input('question', f.string())
+    .output('answer', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'Scientist',
+      description: 'An agent that can answer advanced science questions',
+    },
+    agents: [researcher, summarizer],
+  }
+);
 
 const result = await scientist.forward(llm, {
   question: 'Why is gravity not a real force?',
@@ -326,13 +378,20 @@ The Actor writes JavaScript code to inspect, filter, and iterate over the docume
 ### Configuration
 
 ```typescript
-import { agent, ai } from '@ax-llm/ax';
+import { agent, ai, f } from '@ax-llm/ax';
 
 const analyzer = agent(
-  'context:string, query:string -> answer:string, evidence:string[]',
+  f()
+    .input('context', f.string())
+    .input('query', f.string())
+    .output('answer', f.string())
+    .output('evidence', f.string().array())
+    .build(),
   {
-    name: 'documentAnalyzer',
-    description: 'Analyzes long documents using code interpreter and sub-LM queries',
+    agentIdentity: {
+      name: 'documentAnalyzer',
+      description: 'Analyzes long documents using code interpreter and sub-LM queries',
+    },
     rlm: {
       contextFields: ['context'],                // Fields to load into runtime session
       runtime: new AxJSRuntime(),                // Code runtime (default: AxJSRuntime)
@@ -383,19 +442,25 @@ Available permissions:
 Context fields aren't limited to plain strings. You can pass structured data — objects and arrays with typed sub-fields:
 
 ```typescript
-import { agent, f, s } from '@ax-llm/ax';
+import { agent, f } from '@ax-llm/ax';
 import { AxJSRuntime } from '@ax-llm/ax';
 
-const sig = s('query:string -> answer:string, evidence:string[]')
-  .appendInputField('documents', f.object({
+const sig = f()
+  .input('query', f.string())
+  .input('documents', f.object({
     id: f.number('Document ID'),
     title: f.string('Document title'),
     content: f.string('Document body'),
-  }).array('Source documents'));
+  }).array('Source documents'))
+  .output('answer', f.string())
+  .output('evidence', f.string().array())
+  .build();
 
 const analyzer = agent(sig, {
-  name: 'structuredAnalyzer',
-  description: 'Analyzes structured document collections using RLM',
+  agentIdentity: {
+    name: 'structuredAnalyzer',
+    description: 'Analyzes structured document collections using RLM',
+  },
   rlm: {
     contextFields: ['documents'],
     runtime: new AxJSRuntime(),
@@ -448,8 +513,17 @@ By default, all output fields from the signature go to the Responder. Use `actor
 
 ```typescript
 const analyzer = agent(
-  'context:string, query:string -> answer:string, reasoning:string',
+  f()
+    .input('context', f.string())
+    .input('query', f.string())
+    .output('answer', f.string())
+    .output('reasoning', f.string())
+    .build(),
   {
+    agentIdentity: {
+      name: 'reasoningAnalyzer',
+      description: 'Analyzes context with explicit reasoning steps',
+    },
     rlm: {
       contextFields: ['context'],
       actorFields: ['reasoning'],   // Actor produces 'reasoning', Responder produces 'answer'
@@ -463,14 +537,25 @@ const analyzer = agent(
 Use `actorCallback` to observe each Actor turn. It receives the full Actor result (including `javascriptCode` and any `actorFields`) and fires every turn, including the done() turn.
 
 ```typescript
-const analyzer = agent('context:string, query:string -> answer:string', {
-  rlm: {
-    contextFields: ['context'],
-    actorCallback: async (result) => {
-      console.log('Actor code:', result.javascriptCode);
+const analyzer = agent(
+  f()
+    .input('context', f.string())
+    .input('query', f.string())
+    .output('answer', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'callbackAnalyzer',
+      description: 'Analyzes context with observable actor turns',
     },
-  },
-});
+    rlm: {
+      contextFields: ['context'],
+      actorCallback: async (result) => {
+        console.log('Actor code:', result.javascriptCode);
+      },
+    },
+  }
+);
 ```
 
 ### Actor/Responder Forward Options
@@ -478,20 +563,96 @@ const analyzer = agent('context:string, query:string -> answer:string', {
 Use `actorOptions` and `responderOptions` to set different forward options (model, thinking budget, etc.) for the Actor and Responder sub-programs. These are set at construction time and act as defaults that can still be overridden at forward time.
 
 ```typescript
-const analyzer = agent('context:string, query:string -> answer:string', {
-  rlm: { contextFields: ['context'] },
-  actorOptions: {
-    model: 'fast-model',
-    thinkingTokenBudget: 1024,
+const analyzer = agent(
+  f()
+    .input('context', f.string())
+    .input('query', f.string())
+    .output('answer', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'dualModelAnalyzer',
+      description: 'Analyzes context using different models for actor and responder',
+    },
+    rlm: { contextFields: ['context'] },
+    actorOptions: {
+      model: 'fast-model',
+      thinkingTokenBudget: 1024,
+    },
+    responderOptions: {
+      model: 'smart-model',
+      thinkingTokenBudget: 4096,
+    },
+  }
+);
+```
+
+Priority order (low to high): constructor base options < `actorOptions`/`responderOptions` < forward-time options.
+
+### Actor/Responder Descriptions
+
+Use `setActorDescription()` and `setResponderDescription()` to append additional instructions to the Actor or Responder system prompts. The base RLM prompts are preserved; your text is appended after them.
+
+```typescript
+const analyzer = agent(
+  f()
+    .input('context', f.string())
+    .input('query', f.string())
+    .output('answer', f.string())
+    .build(),
+  {
+    agentIdentity: {
+      name: 'customAnalyzer',
+      description: 'Analyzes context with custom actor and responder instructions',
+    },
+    rlm: { contextFields: ['context'] },
+  }
+);
+
+// Add domain-specific instructions to the Actor (code generation agent)
+analyzer.setActorDescription('Focus on numerical data. Use precise calculations.');
+
+// Add domain-specific instructions to the Responder (answer synthesis agent)
+analyzer.setResponderDescription('Format answers as bullet points. Cite evidence.');
+```
+
+> **Note:** Signature-level descriptions (via `.description()` on the signature) are not supported on `AxAgent`. Use these methods instead to customize each sub-program independently.
+
+### Few-Shot Demos
+
+Use `setDemos()` to provide few-shot examples that guide the Actor and Responder. Demos are keyed by program ID — use `namedPrograms()` to discover available IDs.
+
+Each demo trace must include at least one input field AND one output field. The Actor's input fields are `contextMetadata`, `actionLog`, and any non-context inputs from the original signature. The Responder's input fields are the same.
+
+```typescript
+analyzer.setDemos([
+  {
+    programId: 'root.actor',
+    traces: [
+      {
+        actionLog: '(no actions yet)',
+        javascriptCode: 'console.log(context.slice(0, 200))',
+      },
+      {
+        actionLog: 'Step 1 | console.log(context.slice(0, 200))\n→ Chapter 1: ...',
+        javascriptCode: 'done()',
+      },
+    ],
   },
-  responderOptions: {
-    model: 'smart-model',
-    thinkingTokenBudget: 4096,
+  {
+    programId: 'root.responder',
+    traces: [
+      {
+        query: 'What are the main arguments?',
+        answer: 'The document presents arguments about distributed systems.',
+        evidence: ['Chapter 1 discusses scalability'],
+      },
+    ],
   },
-});
+]);
 ```
 
-Priority order (low to high): constructor base options < `actorOptions`/`responderOptions` < forward-time options.
+Demo values are validated against the target program's signature. Invalid values or missing input/output fields throw an error at `setDemos()` time.
 
 ### Available APIs in the Sandbox
 
@@ -639,9 +800,7 @@ interface AxCodeSession {
 ```typescript
 interface AxAgentConfig<IN, OUT> extends AxAgentOptions {
   ai?: AxAIService;
-  name: string;
-  description: string;
-  definition?: string;
+  agentIdentity?: { name: string; description: string };
   agents?: AxAgentic<IN, OUT>[];
   functions?: AxInputFunctionType;
 }
@@ -660,6 +819,22 @@ Extends `AxProgramForwardOptions` (without `functions`) with:
 }
 ```
 
+### `setActorDescription()`
+
+```typescript
+public setActorDescription(additionalText: string): void
+```
+
+Appends additional text to the Actor's RLM system prompt. The base prompt is preserved; the additional text is appended after it.
+
+### `setResponderDescription()`
+
+```typescript
+public setResponderDescription(additionalText: string): void
+```
+
+Appends additional text to the Responder's RLM system prompt. The base prompt is preserved; the additional text is appended after it.
+
 ### `stop()`
 
 ```typescript