@amitdeshmukh/ax-crew 8.5.0 → 8.7.0

package/src/skills/ax-crew-ace.md

@@ -0,0 +1,165 @@
+---
+name: ax-crew-ace
+version: __VERSION__
+description: "ACE (Agentic Context Engineering) for AxCrew: feedback loops, online learning, playbook persistence, and optimization."
+tags: [ace, agentic-context-engineering, feedback, learning, playbook, online-update, optimize]
+---
+
+# ACE (Agentic Context Engineering)
+
+ACE enables agents to learn from human feedback at runtime. Feedback is analyzed, categorized into playbook sections, and injected into the agent's system prompt on every subsequent `forward()` call.
+
+## ACEConfig Shape
+
+```ts
+interface ACEConfig {
+  teacher?: {
+    provider?: Provider;
+    providerKeyName?: string;
+    apiURL?: string;
+    ai?: AxModelConfig & { model: string };
+    providerArgs?: Record<string, unknown>;
+  };
+  persistence?: {
+    playbookPath?: string;
+    initialPlaybook?: Record<string, any>;
+    autoPersist?: boolean;
+    onPersist?: (pb: any) => Promise<void> | void;
+    onLoad?: () => Promise<any> | any;
+  };
+  options?: {
+    maxEpochs?: number;
+    allowDynamicSections?: boolean;
+    tokenBudget?: number;
+    reflectorPrompt?: string;
+    curatorPrompt?: string;
+  };
+  metric?: {
+    metricFnName?: string;
+    primaryOutputField?: string;
+  };
+  compileOnStart?: boolean;
+}
+```
+
+## Agent-Level ACE API
+
+```ts
+// StatefulAxAgent methods:
+await agent.initACE(aceConfig);                          // called automatically during addAgent()
+await agent.applyOnlineUpdate({ example, prediction, feedback }); // learn from feedback
+agent.getPlaybook();                                     // returns current ACEPlaybook
+agent.applyPlaybook(playbook);                           // set playbook directly
+await agent.optimizeOffline({ metric, examples });       // offline compilation
+```
+
+## Crew-Level Feedback Routing
+
+```ts
+// AxCrew tracks which agents participated in a task and routes feedback to all of them:
+crew.trackAgentExecution(taskId, agentName, input);      // automatic during forward()
+crew.recordAgentResult(taskId, agentName, result);       // automatic during forward()
+await crew.applyTaskFeedback({ taskId, feedback, strategy: "all" | "primary" | "weighted" });
+crew.getTaskAgentInvolvement(taskId);                    // inspect execution history
+crew.cleanupOldExecutions(maxAgeMs);                     // prevent memory leaks
+```
+
+## Playbook Persistence
+
+Three persistence options (checked in order):
+1. `onLoad` callback -- custom async loader
+2. `initialPlaybook` -- inline playbook object
+3. `playbookPath` -- JSON file on disk (auto-created)
+
+Auto-save: set `autoPersist: true` with `playbookPath` or `onPersist` callback.
+
+## Canonical Pattern
+
+Adapted from `examples/ace-customer-support.ts` -- an agent that learns customer support exception policies from supervisor feedback.
+
+```ts
+import { AxCrew } from "ax-crew";
+import type { AxCrewConfig, Provider } from "ax-crew";
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "SupportAgent",
+      description: "Customer support agent. Follow company policies strictly.",
+      signature: "ticket:string, policies:string[] -> response:string, decision:string",
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-flash-latest", temperature: 0.7 },
+      options: { stream: false },
+      ace: {
+        teacher: {
+          provider: "google-gemini" as Provider,
+          providerKeyName: "GEMINI_API_KEY",
+          ai: { model: "gemini-flash-latest" },
+        },
+        options: { maxEpochs: 1, allowDynamicSections: true },
+        persistence: {
+          playbookPath: "playbooks/support.json",
+          autoPersist: true,
+        },
+        metric: { primaryOutputField: "response" },
+        compileOnStart: false,
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAgentsToCrew(["SupportAgent"]);
+  const agent = crew.agents!.get("SupportAgent")!;
+
+  // Run the agent
+  const result = await agent.forward({
+    ticket: "Customer wants refund on sale item (defective on arrival)",
+    policies: ["No refunds on sale items", "Returns within 30 days only"],
+  });
+
+  console.log(result.response, result.decision);
+
+  // Apply feedback -- agent learns for future calls
+  const taskId = (result as any)._taskId;
+  if (taskId) {
+    await crew.applyTaskFeedback({
+      taskId,
+      feedback: "Defective products must always be refunded regardless of sale status",
+      strategy: "all",
+    });
+  }
+
+  // Or apply directly to agent (without task routing)
+  await (agent as any).applyOnlineUpdate({
+    example: { ticket: "..." },
+    prediction: result,
+    feedback: "Medical emergencies extend the 30-day window to 60 days",
+  });
+
+  // Inspect learned playbook
+  const playbook = (agent as any).getPlaybook();
+  console.log(JSON.stringify(playbook, null, 2));
+
+  crew.cleanupOldExecutions(60000);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT call `initACE()` manually -- it is called automatically when `addAgent()` / `addAgentsToCrew()` detects an `ace` config on the agent.
+- Do NOT set `compileOnStart: true` without providing `examples` and a `metric` -- offline compilation requires both.
+- Do NOT mutate the playbook object directly -- use `applyOnlineUpdate()` or `applyPlaybook()`.
+- Do NOT forget `autoPersist: true` if you want playbook changes saved to disk automatically.
+- Do NOT use `strategy: "weighted"` expecting differentiated weights -- it currently behaves the same as `"all"`.
+
+## References
+
+- [ace-customer-support.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/ace-customer-support.ts)
+- [src/agents/ace.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/ace.ts)
+- [AxACE upstream docs](https://axllm.dev/ace/)

package/src/skills/ax-crew-agent-config.md

@@ -0,0 +1,181 @@
+---
+name: ax-crew-agent-config
+version: __VERSION__
+description: "AgentConfig - agent configuration: provider, signature, model, temperature, definition, prompt, executionMode, axAgentOptions, providerArgs"
+---
+
+# AgentConfig
+
+Every agent in a crew is defined by an `AgentConfig` object inside `AxCrewConfig.crew[]`.
+
+## All Fields
+
+```ts
+interface AgentConfig {
+  // Required
+  name: string;                    // Unique agent name
+  description: string;             // Short description (used as default system prompt)
+  signature: string | AxSignature; // DSPy-style signature, e.g. "query:string -> answer:string"
+  provider: Provider;              // "openai" | "anthropic" | "google-gemini" | "azure-openai" | ...
+  ai: AxModelConfig & {           // Model configuration
+    model: string;                 //   model name (required)
+    temperature?: number;          //   sampling temperature
+    maxTokens?: number;            //   max output tokens
+    stream?: boolean;              //   enable streaming at AI level
+  };
+
+  // Optional
+  providerKeyName?: string;        // Env var name for API key (e.g. "OPENAI_API_KEY")
+  apiURL?: string;                 // Custom API endpoint (e.g. ollama on localhost)
+  providerArgs?: Record<string, unknown>; // Provider-specific args forwarded to Ax factory
+  definition?: string;             // Detailed system prompt (must be >= 100 chars per Ax)
+  prompt?: string;                 // Alias for definition (used if definition is omitted)
+  debug?: boolean;                 // Enable debug logging
+  options?: Partial<AxProgramForwardOptions<any>> & Record<string, any>; // Forward options + provider-specific keys
+  functions?: string[];            // Function names from the registry
+  agents?: string[];               // Sub-agent names (must be added to crew first)
+  examples?: Array<Record<string, any>>; // DSPy few-shot examples
+  mcpServers?: Record<string, MCPTransportConfig>; // MCP server configs
+  executionMode?: "axagent" | "axgen"; // Execution engine (default: "axgen")
+  axAgentOptions?: AxCrewAxAgentOptions; // AxAgent-specific options (only for executionMode: "axagent")
+  ace?: ACEConfig;                 // Optional AxACE optimization config
+}
+```
+
+## Canonical Pattern
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "analyzer",
+      description: "Analyzes user queries and provides structured responses",
+      signature: "userQuery:string -> analysis:string, confidence:number",
+      provider: "anthropic",
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: {
+        model: "claude-sonnet-4-20250514",
+        temperature: 0.5,
+        maxTokens: 2000,
+      },
+      options: { debug: true, stream: false },
+      functions: ["CurrentDateTime"],
+    }
+  ]
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+  const analyzer = crew.agents?.get("analyzer");
+  const result = await analyzer?.forward({ userQuery: "What is quantum computing?" });
+  console.log(result?.analysis, result?.confidence);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Provider Key Pattern
+
+The `providerKeyName` field specifies which environment variable holds the API key. The key is read from `process.env` at agent creation time.
+
+```ts
+{
+  provider: "openai",
+  providerKeyName: "OPENAI_API_KEY",  // reads process.env.OPENAI_API_KEY
+}
+```
+
+## Azure OpenAI Example
+
+Use `providerArgs` for provider-specific configuration:
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "TestAgent",
+      description: "Test Agent for Azure OpenAI",
+      provider: "azure-openai",
+      providerKeyName: "AZURE_OPENAI_API_KEY",
+      signature: "userQuery:string -> answer:string",
+      ai: {
+        model: "gpt-5-mini",
+        temperature: 0,
+        stream: false
+      },
+      providerArgs: {
+        resourceName: "your-resource-name",
+        deploymentName: "your-deployment-name",
+        version: "2025-01-01-preview"
+      },
+      options: { debug: true, stream: false }
+    }
+  ]
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+  const agent = crew.agents?.get("TestAgent");
+  const response = await agent?.forward({ userQuery: "What is the capital of France?" });
+  console.log(response?.answer);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Execution Mode
+
+| Mode | Engine | When to use |
+|---|---|---|
+| `"axgen"` (default) | `AxGen` | Standard prompt-response with tool calling |
+| `"axagent"` | `AxAgent` | Full agent capabilities: RLM, context fields, actor/responder split |
+
+When `executionMode: "axagent"`, use `axAgentOptions` for agent-specific settings:
+
+```ts
+{
+  executionMode: "axagent",
+  axAgentOptions: {
+    contextFields: ["conversationHistory"],
+    // agents: { ... },   // Agent graph config
+    // functions: { ... }, // Function graph config
+    // actorOptions: { description: "..." },
+    // responderOptions: { description: "..." },
+  }
+}
+```
+
+## Signature Format
+
+DSPy-style string signatures with optional field descriptions:
+
+```
+"input1:type, input2:type -> output1:type, output2:type"
+"topic:string \"The topic\" -> article:string \"The written article\""
+"query:string -> results:string[]"
+```
+
+Supported types: `string`, `number`, `boolean`, `string[]`, `number[]`, etc.
+
+## Do Not Generate
+
+- Do NOT omit `name`, `description`, `signature`, `provider`, or `ai.model` -- all are required.
+- Do NOT set `definition` to less than 100 characters if you provide it (Ax enforces this minimum).
+- Do NOT confuse `options.stream` (forward option) with `ai.stream` (AI-level streaming config).
+- Do NOT use `providerArgs` for API keys; use `providerKeyName` instead.
+- Do NOT list sub-agents in `agents` that haven't been added to the crew before the parent agent.
+
+## References
+
+- [basic-researcher-writer.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/basic-researcher-writer.ts)
+- [providerArgs.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/providerArgs.ts)

package/src/skills/ax-crew-code-execution.md

@@ -0,0 +1,166 @@
+---
+name: ax-crew-code-execution
+description: AxCrew code execution with AxJSRuntime for sandboxed JavaScript execution. Covers AxJSRuntime setup, permissions, executionMode axagent, RLM mode, and runtime configuration for autonomous code generation and execution.
+version: "__VERSION__"
+---
+
+# AxCrew Code Execution
+
+AxJSRuntime from `@ax-llm/ax` provides sandboxed JavaScript execution for agents in RLM (Reasoning Language Model) mode. The agent generates and runs code autonomously to solve tasks.
+
+## Setup
+
+```typescript
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+import { AxCrew } from 'ax-crew';
+import type { AxCrewConfig } from 'ax-crew';
+
+const runtime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+});
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Analyzer",
+      description: "Analyzes data with code execution capabilities.",
+      executionMode: "axagent", // REQUIRED for runtime
+      signature:
+        'context:string, query:string -> answer:string, keyFindings:string[] "Analyzes context and returns findings"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: {
+        contextFields: ["context"], // fields managed as RLM context
+        runtime, // AxJSRuntime instance
+        maxTurns: 20,
+        maxSubAgentCalls: 40,
+        mode: "simple",
+        contextManagement: {
+          errorPruning: true,
+          hindsightEvaluation: true,
+          pruneRank: 2,
+          tombstoning: {
+            model: "gemini-2.5-flash",
+            modelConfig: { maxTokens: 60 },
+          },
+          stateInspection: { contextThreshold: 3000 },
+        },
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  try {
+    await crew.addAllAgents();
+
+    const analyzer = crew.agents?.get("Analyzer");
+    if (!analyzer) throw new Error("Failed to initialize Analyzer");
+
+    const result = await analyzer.forward({
+      context: "Region,Month,Revenue\nNorth,Jan,48000\nNorth,Feb,54000\nSouth,Jan,39200",
+      query: "Which region has the highest total revenue?",
+    });
+
+    console.log(result.answer);
+    console.log(result.keyFindings);
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Key Requirements
+
+1. **`executionMode: "axagent"`** -- required for runtime support. The default `"axgen"` mode does not support code execution.
+2. **`axAgentOptions.runtime`** -- pass an `AxJSRuntime` instance.
+3. **`axAgentOptions.contextFields`** -- array of input field names managed as RLM context (can be empty `[]`).
+
+## Shared Runtime Across Agents
+
+A single `AxJSRuntime` instance can be shared across multiple agents:
+
+```typescript
+const runtime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+});
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "PolicyLookup",
+      description: "Looks up policies",
+      executionMode: "axagent",
+      signature: "question:string -> answer:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: { contextFields: [], runtime },
+    },
+    {
+      name: "BillingHelper",
+      description: "Handles billing queries",
+      executionMode: "axagent",
+      signature: "question:string -> answer:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: { contextFields: [], runtime },
+    },
+  ],
+};
+```
+
+## AxJSRuntimePermission
+
+Controls what the sandboxed code can access:
+
+```typescript
+import { AxJSRuntimePermission } from '@ax-llm/ax';
+
+const runtime = new AxJSRuntime({
+  permissions: [
+    AxJSRuntimePermission.TIMING, // access to Date, performance.now()
+  ],
+});
+```
+
+## Minimal RLM Agent (No Context Management)
+
+```typescript
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Coder",
+      description: "Executes JavaScript code to solve tasks",
+      executionMode: "axagent",
+      signature: "task:string -> result:string",
+      provider: "openai",
+      ai: { model: "gpt-4o", temperature: 0 },
+      axAgentOptions: {
+        contextFields: [],
+        runtime: new AxJSRuntime({
+          permissions: [AxJSRuntimePermission.TIMING],
+        }),
+      },
+    },
+  ],
+};
+```
+
+## Do Not Generate
+
+- Do NOT use `executionMode: "axgen"` with `runtime` -- code execution requires `"axagent"` mode
+- Do NOT use Google's `codeExecution` tool option -- use `AxJSRuntime` instead for sandboxed execution
+- Do NOT omit `contextFields` in `axAgentOptions` when using `executionMode: "axagent"` -- it is mandatory (use `[]` if no context fields)
+- Do NOT create a new `AxJSRuntime` per request -- reuse a single instance across agents and calls
+- Do NOT confuse `axAgentOptions.runtime` with Node.js runtime -- it is a sandboxed JS execution environment
+
+## References
+
+- [rlm-long-task.ts](../examples/rlm-long-task.ts) -- full RLM agent with context management
+- [rlm-shared-fields.ts](../examples/rlm-shared-fields.ts) -- shared runtime across sub-agents