@amitdeshmukh/ax-crew 8.5.0 → 8.7.0

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

@@ -0,0 +1,287 @@
+---
+name: ax-crew-execution-modes
+version: "__VERSION__"
+description: "ax-crew execution modes: execution mode, axgen, axagent, RLM, runtime, contextFields, AxJSRuntime, contextManagement, fields, shared, globallyShared, excluded, maxTurns, maxSubAgentCalls"
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew Execution Modes
+
+## axgen (default)
+
+Uses `AxGen` for structured generation. Single-pass, deterministic. Sub-agents become callable tool functions. Best for straightforward input-to-output tasks.
+
+```typescript
+{
+  name: "SimpleAgent",
+  executionMode: "axgen",  // default, can be omitted
+  signature: "query:string -> answer:string",
+  // ...
+}
+```
+
+## axagent
+
+Uses `AxAgent` with RLM (Runtime Language Model). Multi-step agentic reasoning loop. Supports context management, tombstoning, and state inspection.
+
+```typescript
+{
+  name: "ReasoningAgent",
+  executionMode: "axagent",
+  signature: "context:string, query:string -> answer:string",
+  // ...
+  axAgentOptions: {
+    contextFields: ["context"],  // required for axagent (can be empty [])
+    runtime: new AxJSRuntime({ permissions: [AxJSRuntimePermission.TIMING] }),
+  },
+}
+```
+
+Both modes use the same `forward()` / `streamingForward()` API.
+
+## axAgentOptions Full Reference
+
+Type: `AxCrewAxAgentOptions` (extends `Partial<AxAgentOptions>`)
+
+```typescript
+axAgentOptions: {
+  // Required: which input fields contain context for RLM processing
+  contextFields: string[],
+
+  // Runtime for code execution in RLM
+  runtime?: AxJSRuntime,
+
+  // Max reasoning turns before stopping
+  maxTurns?: number,
+
+  // Max sub-agent delegations
+  maxSubAgentCalls?: number,
+
+  // RLM mode
+  mode?: "simple" | "full",
+
+  // Context management strategies
+  contextManagement?: {
+    errorPruning?: boolean,          // prune context on errors
+    hindsightEvaluation?: boolean,   // evaluate context relevance
+    pruneRank?: number,              // ranking threshold for pruning
+    tombstoning?: {                  // summarize pruned context
+      model: string,
+      modelConfig?: { maxTokens?: number },
+    },
+    stateInspection?: {
+      contextThreshold?: number,     // token count threshold
+    },
+  },
+
+  // Sub-agents and functions (can also be set via top-level agents/functions)
+  agents?: AxAgentOptions['agents'],
+  functions?: AxAgentOptions['functions'],
+
+  // Field sharing between parent and sub-agents
+  fields?: {
+    shared?: string[],          // fields shared with sub-agents
+    globallyShared?: string[],  // fields shared with all descendants
+    excluded?: string[],        // opt out of parent's shared fields
+  },
+}
+```
+
+## fields: shared, globallyShared, excluded
+
+Control how input/output fields propagate between parent and sub-agents in `axagent` mode.
+
+```typescript
+// Parent agent shares knowledgeBase and userId with sub-agents
+{
+  name: "CustomerSupportAgent",
+  executionMode: "axagent",
+  signature: "query:string, knowledgeBase:string, userId:string -> answer:string",
+  agents: ["PolicyLookupAgent", "BillingHelperAgent", "SentimentClassifierAgent"],
+  axAgentOptions: {
+    contextFields: ["knowledgeBase"],
+    fields: { shared: ["knowledgeBase", "userId"] },
+    runtime,
+  },
+}
+
+// Sub-agent that opts OUT of receiving shared fields
+{
+  name: "SentimentClassifierAgent",
+  executionMode: "axagent",
+  signature: 'question:string -> sentiment:string "positive, negative, or neutral"',
+  axAgentOptions: {
+    contextFields: [],
+    fields: { excluded: ["knowledgeBase", "userId"] },  // won't receive these
+    runtime,
+  },
+}
+```
+
+## Canonical Pattern: RLM with Context Management
+
+From `rlm-long-task.ts`:
+
+```typescript
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const runtime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+});
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Analyzer",
+      description: "Analyzes a large dataset with semantic context management.",
+      executionMode: "axagent",
+      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"],
+        runtime,
+        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,Product,Units,Revenue\nNorth,Jan,Widget-A,1200,48000\n...",
+      query: "Which region has the highest revenue growth from Jan to Mar?",
+    });
+
+    console.log("Answer:", result.answer);
+    console.log("Key Findings:", result.keyFindings);
+
+    console.log("Agent Metrics:", JSON.stringify(analyzer.getMetrics?.(), null, 2));
+    console.log("Crew Metrics:", JSON.stringify(crew.getCrewMetrics(), null, 2));
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Canonical Pattern: Shared Fields Between Agents
+
+From `rlm-shared-fields.ts`:
+
+```typescript
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const runtime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+});
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "PolicyLookupAgent",
+      description: "Looks up policy details in the provided knowledge base.",
+      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: "SentimentClassifierAgent",
+      description: "Classifies customer message sentiment.",
+      executionMode: "axagent",
+      signature: 'question:string -> sentiment:string "positive, negative, or neutral"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: {
+        contextFields: [],
+        fields: { excluded: ["knowledgeBase", "userId"] },
+        runtime,
+      },
+    },
+    {
+      name: "CustomerSupportAgent",
+      description: "Routes queries to specialists and returns a final answer.",
+      executionMode: "axagent",
+      signature: "query:string, knowledgeBase:string, userId:string -> answer:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      agents: ["PolicyLookupAgent", "SentimentClassifierAgent"],
+      axAgentOptions: {
+        contextFields: ["knowledgeBase"],
+        fields: { shared: ["knowledgeBase", "userId"] },
+        runtime,
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  try {
+    await crew.addAllAgents();
+
+    const supportAgent = crew.agents?.get("CustomerSupportAgent");
+    if (!supportAgent) throw new Error("Failed to initialize");
+
+    const result = await supportAgent.forward({
+      query: "I want to return the Smart Lamp. Am I eligible for a full refund?",
+      knowledgeBase: "REFUND POLICY: Full refund within 30 days...",
+      userId: "cust-42",
+    });
+
+    console.log("Answer:", result.answer);
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT use `axAgentOptions` without setting `executionMode: "axagent"` -- it is ignored in `axgen` mode.
+- Do NOT omit `contextFields` when using `axagent` mode -- it is required (use `[]` if no context fields).
+- Do NOT omit `runtime` when using RLM features -- `AxJSRuntime` is required for code execution.
+- Do NOT confuse `fields.shared` with `contextFields` -- `shared` controls field propagation to sub-agents, `contextFields` identifies which fields contain context for RLM processing.
+- Do NOT set `fields.excluded` on a parent agent -- it is for sub-agents opting out of the parent's shared fields.
+- Do NOT use `axAgentOptions.agents` or `axAgentOptions.functions` unless you need the AxAgent-native format -- prefer the top-level `agents` and `functions` config fields.
+
+## References
+
+- [rlm-long-task.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/rlm-long-task.ts)
+- [rlm-shared-fields.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/rlm-shared-fields.ts)
+- [Source: AxCrewAxAgentOptions type](https://github.com/amitdeshmukh/ax-crew/blob/main/src/types.ts)
+- [Source: StatefulAxAgent execution mode handling](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/index.ts)

package/src/skills/ax-crew-few-shot.md

@@ -0,0 +1,165 @@
+---
+name: ax-crew-few-shot
+description: AxCrew few-shot examples via examples[] field in AgentConfig. Covers in-context learning, demonstration structure, input/output field matching, setExamplesCompat() for dynamic updates, and when to use examples vs definition/prompt.
+version: "__VERSION__"
+---
+
+# AxCrew Few-Shot Examples
+
+The `examples[]` field in `AgentConfig` provides DSPy-style few-shot demonstrations. Each example contains input AND output field values matching the agent's signature.
+
+## Basic Structure
+
+```typescript
+{
+  name: "Agent",
+  signature: "question:string -> answer:string",
+  // ...
+  examples: [
+    { question: "What is 2+2?", answer: "4" },
+    { question: "Capital of France?", answer: "Paris" },
+  ],
+}
+```
+
+Every key in the example object must match a field name from the signature (inputs and/or outputs).
+
+## Full Example
+
+```typescript
+import { AxCrew } from 'ax-crew';
+import type { AxCrewConfig } from 'ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "SupportAgent",
+      description: "Customer support agent that follows company tone",
+      signature:
+        "ticket:string, standardPolicies:string[] -> politeSupportResponse:string, decision:string, policyApplied:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0.7 },
+      examples: [
+        {
+          ticket: "I want to return my laptop purchased 10 days ago.",
+          standardPolicies: ["Returns within 30 days only"],
+          politeSupportResponse:
+            "Of course! Your laptop is within our 30-day return window. I'll process that right away.",
+          decision: "approved",
+          policyApplied: "Returns within 30 days only",
+        },
+        {
+          ticket: "Refund my sale item please.",
+          standardPolicies: ["Sale items: no returns, no refunds"],
+          politeSupportResponse:
+            "I understand your frustration. Unfortunately, sale items are final sale per our policy. I'd be happy to help with an exchange instead.",
+          decision: "denied",
+          policyApplied: "Sale items: no returns, no refunds",
+        },
+      ],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get("SupportAgent");
+  const result = await agent!.forward({
+    ticket: "I bought headphones 15 days ago and they broke.",
+    standardPolicies: ["Returns within 30 days only", "Defective items replaced free"],
+  });
+
+  console.log(result.politeSupportResponse);
+  console.log(result.decision);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Multi-Field Examples
+
+```typescript
+{
+  name: "Planner",
+  description: "Creates execution plans",
+  signature: "task:string, context:string -> plan:string, steps:string[]",
+  provider: "openai",
+  ai: { model: "gpt-4o" },
+  examples: [
+    {
+      task: "Deploy new API version",
+      context: "Kubernetes cluster, 3 environments",
+      plan: "Blue-green deployment with canary rollout",
+      steps: [
+        "Run integration tests",
+        "Deploy to staging",
+        "Canary 10% traffic",
+        "Full rollout",
+      ],
+    },
+    {
+      task: "Migrate database",
+      context: "PostgreSQL 14 to 16, 500GB data",
+      plan: "Logical replication with minimal downtime",
+      steps: [
+        "Set up PG16 replica",
+        "Enable logical replication",
+        "Sync and verify",
+        "Switch over",
+      ],
+    },
+  ],
+}
+```
+
+## Dynamic Example Updates (setExamplesCompat)
+
+Update examples at runtime after agent initialization:
+
+```typescript
+const crew = new AxCrew(config);
+await crew.addAllAgents();
+
+const agent = crew.agents?.get("SupportAgent");
+
+// Update examples dynamically
+(agent as any).setExamplesCompat([
+  {
+    ticket: "My order never arrived.",
+    standardPolicies: ["Reship if not delivered in 14 days"],
+    politeSupportResponse: "I'm sorry about that! Let me reship your order immediately.",
+    decision: "approved",
+    policyApplied: "Reship if not delivered in 14 days",
+  },
+]);
+```
+
+`setExamplesCompat()` replaces all current examples. It is preferred over `setExamples()` (deprecated) for compatibility across Ax runtime versions.
+
+## When to Use examples[] vs definition/prompt
+
+| Use `examples[]` | Use `definition` / `prompt` |
+|---|---|
+| Structured output consistency | System persona / role description |
+| Demonstrate tone, format, style | Complex multi-paragraph instructions |
+| Classification patterns | Domain context / background knowledge |
+| Input-output mappings | Behavioral constraints |
+
+Best practice: use `definition`/`prompt` for WHO the agent is, `examples[]` for HOW it should respond.
+
+## Do Not Generate
+
+- Do NOT embed examples as text in `definition` or `prompt` -- use the `examples[]` field for structured few-shot learning
+- Do NOT include fields in examples that are not in the signature -- keys must match signature field names
+- Do NOT provide only input fields in examples -- include BOTH input and output fields to demonstrate expected behavior
+- Do NOT use `setExamples()` directly -- use `setExamplesCompat()` for cross-version compatibility
+- Do NOT add excessive examples (2-5 is typical) -- too many increase token usage without proportional quality gain
+
+## References
+
+- [ace-customer-support.ts](../examples/ace-customer-support.ts) -- agent with structured examples and ACE feedback
+- [basic-researcher-writer.ts](../examples/basic-researcher-writer.ts) -- simple agent config

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

@@ -0,0 +1,218 @@
+---
+name: ax-crew-functions
+version: __VERSION__
+description: "Functions and tools: FunctionRegistryType, AxFunction, toFunction, custom functions, AxCrewFunctions, class-based functions with state"
+---
+
+# Functions
+
+Agents call tools via a `FunctionRegistryType` -- a map of function names to either plain `AxFunction` objects or class-based constructors that receive shared state.
+
+## Two Patterns
+
+### Object-based (plain AxFunction)
+
+```ts
+import type { AxFunction } from '@ax-llm/ax';
+
+const MyTool: AxFunction = {
+  name: 'MyTool',
+  description: 'Does something useful',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: 'The input value' }
+    },
+    required: ['input']
+  },
+  func: ({ input }: { input: string }) => {
+    return `Processed: ${input}`;
+  }
+};
+```
+
+### Class-based (with state access)
+
+Constructor receives shared state. Must implement `toFunction()` returning an `AxFunction`.
+
+```ts
+import type { AxFunction } from '@ax-llm/ax';
+
+class WordPressPost {
+  private state: Record<string, any>;
+
+  constructor(state: Record<string, any>) {
+    this.state = state;
+  }
+
+  toFunction(): AxFunction {
+    return {
+      name: 'WordPressPost',
+      description: 'Creates a post on WordPress',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'Post title' },
+          content: { type: 'string', description: 'Post content' },
+          status: { type: 'string', description: 'Post status (draft, publish, private)' }
+        },
+        required: ['title', 'content', 'status']
+      },
+      func: async ({ title, content, status }: { title: string; content: string; status: string }) => {
+        const env = this.state.env || {};
+        const url = env.WORDPRESS_URL;
+        const username = env.WORDPRESS_USERNAME;
+        const password = env.WORDPRESS_PASSWORD;
+        // ... make API call using credentials from state
+        return { id: 123, link: `${url}/?p=123` };
+      }
+    };
+  }
+}
+```
+
+## FunctionRegistryType
+
+```ts
+type FunctionRegistryType = {
+  [key: string]: AxFunction | { new(state: Record<string, any>): { toFunction: () => AxFunction } };
+};
+```
+
+The registry key must match the name used in `AgentConfig.functions[]`.
+
+## Built-in AxCrewFunctions
+
+```ts
+import { AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+// Contains: { CurrentDateTime, DaysBetweenDates }
+```
+
+**CurrentDateTime** -- returns current date/time in `iso`, `datetime`, or `date` format.
+
+**DaysBetweenDates** -- calculates days between two ISO date strings. Parameters: `startDate`, `endDate`.
+
+## Merging Registries
+
+```ts
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { FunctionRegistryType } from '@amitdeshmukh/ax-crew';
+
+const myFunctions: FunctionRegistryType = {
+  MyTool: MyTool,
+  WordPressPost: WordPressPost,  // class-based
+};
+
+// Merge built-in + custom
+const crew = new AxCrew(config, { ...AxCrewFunctions, ...myFunctions });
+```
+
+Then reference by name in agent config:
+
+```ts
+{
+  name: "poster",
+  functions: ["CurrentDateTime", "WordPressPost"],
+  // ...
+}
+```
+
+## Canonical Pattern
+
+Full runnable example adapted from the WordPress example:
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig, FunctionRegistryType } from '@amitdeshmukh/ax-crew';
+import type { AxFunction } from '@ax-llm/ax';
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Plain AxFunction
+const Summarize: AxFunction = {
+  name: 'Summarize',
+  description: 'Summarize text to a given length',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to summarize' },
+      maxWords: { type: 'number', description: 'Maximum words' }
+    },
+    required: ['text']
+  },
+  func: ({ text, maxWords }: { text: string; maxWords?: number }) => {
+    const limit = maxWords ?? 50;
+    return text.split(' ').slice(0, limit).join(' ') + '...';
+  }
+};
+
+// Class-based function with state access
+class FetchFromAPI {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'FetchFromAPI',
+      description: 'Fetch data from a configured API endpoint',
+      parameters: {
+        type: 'object',
+        properties: {
+          endpoint: { type: 'string', description: 'API endpoint path' }
+        },
+        required: ['endpoint']
+      },
+      func: async ({ endpoint }: { endpoint: string }) => {
+        const baseUrl = this.state.env?.API_BASE_URL || 'https://api.example.com';
+        const resp = await fetch(`${baseUrl}${endpoint}`);
+        return await resp.json();
+      }
+    };
+  }
+}
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "assistant",
+      description: "An assistant that can summarize text and fetch data",
+      signature: "request:string -> response:string",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini", temperature: 0.5 },
+      functions: ["Summarize", "FetchFromAPI"],
+    }
+  ]
+};
+
+async function main() {
+  const customFunctions: FunctionRegistryType = {
+    Summarize,
+    FetchFromAPI,
+  };
+  const crew = new AxCrew(config, customFunctions);
+
+  // Set state for class-based functions
+  crew.state.set("env", { API_BASE_URL: "https://api.example.com" });
+
+  await crew.addAllAgents();
+  const assistant = crew.agents?.get("assistant");
+  const result = await assistant?.forward({ request: "Summarize the latest news" });
+  console.log(result?.response);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT define functions inline in AgentConfig; always use a `FunctionRegistryType` registry passed to the `AxCrew` constructor.
+- Do NOT forget that class-based function constructors receive `state: Record<string, any>`, not `StateInstance`. Access values directly (e.g. `this.state.env`), since the state object is a plain record populated via `crew.state.set()`.
+- Do NOT use a registry key that differs from the function name used in `AgentConfig.functions[]` -- they must match.
+- Do NOT import `AxCrewFunctions` from `@ax-llm/ax`; import from `@amitdeshmukh/ax-crew`.
+
+## References
+
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts)
+- [src/functions/dateTime.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/functions/dateTime.ts)
+- [src/functions/index.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/functions/index.ts)