@amitdeshmukh/ax-crew 8.6.0 → 8.7.0

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

@@ -0,0 +1,286 @@
+---
+name: ax-crew-patterns
+version: __VERSION__
+description: "AxCrew multi-agent patterns: pipeline, delegation, fan-out, orchestrator, sequential workflows, and agent coordination."
+tags: [patterns, workflow, pipeline, multi-agent, orchestrator, delegation, sequential, fan-out]
+---
+
+# Multi-Agent Patterns
+
+## Pipeline Pattern (A -> B -> C)
+
+Sequential agent calls where each agent's output feeds the next. Each agent is independent -- the orchestration happens in your code.
+
+```ts
+import { AxCrew } from "ax-crew";
+import type { AxCrewConfig, Provider } from "ax-crew";
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Planner",
+      description: "Generates search queries for a topic",
+      signature: 'topic:string, guidance:string -> queries:string[]',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 1 },
+    },
+    {
+      name: "Searcher",
+      description: "Searches the web for a query",
+      signature: 'query:string -> searchResult:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-1.5-pro", temperature: 0.5 },
+      options: {
+        googleSearchRetrieval: { mode: "MODE_UNSPECIFIED" },
+      },
+    },
+    {
+      name: "Writer",
+      description: "Writes a blog post from research",
+      signature: 'topic:string, guidance:string, searchResults:string[] -> title:string, content:string',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 1 },
+    },
+    {
+      name: "Publisher",
+      description: "Publishes a post to WordPress",
+      signature: 'title:string, content:string, status:string -> postResponse:string',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0 },
+      functions: ["WordPressPost"],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config, customFunctions);
+  const agents = await crew.addAgentsToCrew([
+    "Planner", "Searcher", "Writer", "Publisher",
+  ]);
+
+  const planner = agents!.get("Planner")!;
+  const searcher = agents!.get("Searcher")!;
+  const writer = agents!.get("Writer")!;
+  const publisher = agents!.get("Publisher")!;
+
+  const topic = "How to tell what your dog is thinking";
+  const guidance = "Fun, engaging, under 500 words.";
+
+  // Step 1: Plan
+  const { queries } = await planner.forward({ topic, guidance });
+
+  // Step 2: Research (sequential to avoid rate limits)
+  const searchResults: string[] = [];
+  for (const query of queries) {
+    const { searchResult } = await searcher.forward({ query });
+    searchResults.push(searchResult);
+  }
+
+  // Step 3: Write
+  const { title, content } = await writer.forward({ topic, guidance, searchResults });
+
+  // Step 4: Publish
+  const { postResponse } = await publisher.forward({ title, content, status: "draft" });
+  console.log(postResponse);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Delegation Pattern (Sub-Agents)
+
+Use `agents[]` in config to give one agent access to other agents as tools. The parent agent decides when to delegate. Sub-agents must be added to the crew **before** the parent.
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "MathAgent",
+      description: "Solves math problems using Python code execution",
+      signature: 'mathProblem:string -> solution:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", temperature: 0 },
+      options: { codeExecution: true },
+    },
+    {
+      name: "ManagerAgent",
+      description: "Answers questions, delegating math to MathAgent",
+      signature: 'question:string -> answer:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 1000, temperature: 0 },
+      agents: ["MathAgent"],  // <-- delegation
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+
+  // Order matters: sub-agents first, then parent
+  await crew.addAgentsToCrew(["MathAgent"]);
+  await crew.addAgentsToCrew(["ManagerAgent"]);
+
+  const manager = crew.agents!.get("ManagerAgent")!;
+  const result = await manager.forward({
+    question: "What is the 7th root of 1955?",
+  });
+  console.log(result.answer);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+Note: `addAgentsToCrew(["MathAgent", "ManagerAgent"])` also works -- it resolves dependencies automatically.
+
+## Fan-Out Pattern (Parallel Agents)
+
+Run multiple agents concurrently with `Promise.all`:
+
+```ts
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const analyst = crew.agents!.get("Analyst")!;
+  const reviewer = crew.agents!.get("Reviewer")!;
+  const factChecker = crew.agents!.get("FactChecker")!;
+
+  const input = { document: "..." };
+
+  // Fan-out: run all three in parallel
+  const [analysis, review, facts] = await Promise.all([
+    analyst.forward(input),
+    reviewer.forward(input),
+    factChecker.forward(input),
+  ]);
+
+  // Merge results downstream
+  const synthesizer = crew.agents!.get("Synthesizer")!;
+  const final = await synthesizer.forward({
+    analysis: analysis.result,
+    review: review.result,
+    facts: facts.result,
+  });
+
+  crew.destroy();
+}
+```
+
+## Orchestrator Pattern
+
+A manager agent with multiple specialist sub-agents. The manager decides which specialist(s) to invoke based on the query.
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "CodeAgent",
+      description: "Writes and reviews code",
+      signature: "task:string -> code:string",
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0 },
+    },
+    {
+      name: "ResearchAgent",
+      description: "Researches technical topics",
+      signature: "topic:string -> findings:string",
+      provider: "openai" as Provider,
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o", temperature: 0.5 },
+    },
+    {
+      name: "Orchestrator",
+      description: "Routes tasks to the right specialist and synthesizes results",
+      signature: "request:string -> response:string",
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0.3 },
+      agents: ["CodeAgent", "ResearchAgent"],  // can delegate to either
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAgentsToCrew(["CodeAgent", "ResearchAgent", "Orchestrator"]);
+
+  const orchestrator = crew.agents!.get("Orchestrator")!;
+  const result = await orchestrator.forward({
+    request: "Research WebSocket best practices and write a TypeScript echo server",
+  });
+  console.log(result.response);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## definition / prompt for System Prompts
+
+Use `definition` (or its alias `prompt`) to provide a detailed system prompt. Must be at least 100 characters. If both are set, `definition` takes precedence.
+
+```ts
+{
+  name: "Writer",
+  description: "Short description (used as tool description for sub-agent delegation)",
+  definition: `You are a senior technical writer specializing in developer documentation.
+Follow the Divio documentation framework: tutorials, how-to guides, reference, explanation.
+Always include code examples. Use active voice. Keep paragraphs under 4 sentences.
+Target audience: intermediate developers familiar with TypeScript.`,
+  signature: "topic:string -> documentation:string",
+  provider: "anthropic" as Provider,
+  providerKeyName: "ANTHROPIC_API_KEY",
+  ai: { model: "claude-3-5-sonnet-20240620", temperature: 0.7 },
+}
+```
+
+## Shared State Across Agents
+
+All agents in a crew share a mutable `state` object for out-of-band data passing:
+
+```ts
+crew.state.set("env", { WORDPRESS_URL: "http://...", WORDPRESS_USERNAME: "..." });
+crew.state.set("context", { userId: "abc-123" });
+
+// Inside a custom function, state is accessible via the constructor:
+class MyTool {
+  constructor(private state: Record<string, any>) {}
+  toFunction() {
+    return {
+      name: "myTool",
+      description: "...",
+      parameters: { ... },
+      func: async () => {
+        const env = this.state.env;  // access shared state
+        // ...
+      },
+    };
+  }
+}
+```
+
+## Do Not Generate
+
+- Do NOT add a parent agent before its sub-agents -- `addAgentsToCrew` resolves dependencies but `addAgent` does not.
+- Do NOT use `agents: ["SelfName"]` -- an agent cannot be its own sub-agent (circular dependency error).
+- Do NOT assume agents share conversation context -- they share `state` but each `forward()` call is independent. Pass data explicitly via signatures.
+- Do NOT use `definition` shorter than 100 characters -- Ax requires minimum length for program definitions.
+- Do NOT confuse `description` (used as the tool description when this agent is a sub-agent) with `definition` (the system prompt).
+
+## References
+
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts) (4-agent pipeline)
+- [solve-math-problem.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/solve-math-problem.ts) (delegation)
+- [search-tweets.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/search-tweets.ts) (streaming)

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

@@ -0,0 +1,204 @@
+---
+name: ax-crew-providers
+version: __VERSION__
+description: "AxCrew provider configuration: openai, anthropic, google-gemini, azure-openai, groq, ollama, mistral, cohere, grok/xAI, perplexity, and model setup."
+tags: [provider, openai, anthropic, google-gemini, azure, groq, ollama, mistral, cohere, model, grok, perplexity]
+---
+
+# Providers
+
+AxCrew delegates provider instantiation to the Ax `ai()` factory. The `Provider` type is derived from Ax's `AxAIArgs['name']`, so any provider Ax supports is available.
+
+## Provider Type
+
+```ts
+type Provider = AxAIArgs<any>['name'];
+// Known values: "openai", "anthropic", "google-gemini", "azure-openai",
+// "groq", "ollama", "mistral", "cohere", "grok", "deepseek", "huggingface", etc.
+```
+
+## AgentConfig Provider Fields
+
+```ts
+interface AgentConfig {
+  provider: Provider;              // e.g. "openai"
+  providerKeyName?: string;        // env var name, e.g. "OPENAI_API_KEY"
+  ai: AxModelConfig & { model: string }; // model name + temperature, maxTokens, etc.
+  apiURL?: string;                 // custom endpoint (ollama, proxies)
+  providerArgs?: Record<string, unknown>; // provider-specific args (azure, etc.)
+  options?: Partial<AxProgramForwardOptions<any>> & Record<string, any>; // searchParameters, codeExecution, etc.
+}
+```
+
+## Provider-Specific Configuration
+
+### Azure OpenAI
+
+Use `providerArgs` for Azure-specific fields:
+
+```ts
+{
+  name: "AzureAgent",
+  provider: "azure-openai",
+  providerKeyName: "AZURE_OPENAI_API_KEY",
+  ai: { model: "gpt-5-mini", temperature: 0 },
+  providerArgs: {
+    resourceName: "your-resource-name",
+    deploymentName: "your-deployment-name",
+    version: "2025-01-01-preview",
+  },
+}
+```
+
+### Ollama (Local)
+
+Set `apiURL` to point at the local Ollama endpoint:
+
+```ts
+{
+  name: "LocalAgent",
+  provider: "ollama",
+  providerKeyName: "OLLAMA_API_KEY", // can be any non-empty value
+  apiURL: "http://localhost:11434",
+  ai: { model: "llama3", temperature: 0.7 },
+}
+```
+
+### Grok / xAI
+
+Use provider `"grok"` with a Grok API key:
+
+```ts
+{
+  name: "XSearchAgent",
+  provider: "grok",
+  providerKeyName: "GROK_API_KEY",
+  ai: { model: "grok-3-latest", temperature: 0.1 },
+  options: {
+    stream: true,
+    searchParameters: {
+      mode: "on",
+      returnCitations: true,
+      maxSearchResults: 10,
+      sources: [
+        { type: "x" },
+        { type: "web" },
+        { type: "news" },
+      ],
+    },
+  },
+}
+```
+
+### Perplexity (via MCP)
+
+Use any provider as the agent's LLM and attach Perplexity as an MCP server:
+
+```ts
+{
+  name: "DeepResearchAgent",
+  provider: "google-gemini",
+  providerKeyName: "GEMINI_API_KEY",
+  ai: { model: "gemini-2.5-flash-lite", temperature: 0.1 },
+  mcpServers: {
+    "perplexity-mcp": {
+      command: "uvx",
+      args: ["perplexity-mcp"],
+      env: {
+        PERPLEXITY_API_KEY: process.env.PERPLEXITY_API_KEY,
+        PERPLEXITY_MODEL: "sonar-deep-research",
+      },
+    },
+  },
+}
+```
+
+## Mixed Providers in One Crew
+
+Each agent can use a different provider. The `providerKeyName` maps to an environment variable read at runtime.
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Planner",
+      provider: "anthropic",
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 1 },
+      signature: "topic:string -> queries:string[]",
+      description: "Generates search queries",
+    },
+    {
+      name: "Searcher",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-1.5-pro", temperature: 0.5 },
+      signature: "query:string -> results:string",
+      description: "Searches the web",
+    },
+    {
+      name: "Writer",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o", temperature: 0.8 },
+      signature: "topic:string, results:string[] -> post:string",
+      description: "Writes content from research",
+    },
+  ],
+};
+```
+
+## Canonical Pattern
+
+```ts
+import { AxCrew } from "ax-crew";
+import type { AxCrewConfig } from "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 },
+      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);
+```
+
+## Do Not Generate
+
+- Do NOT hardcode API keys in config -- always use `providerKeyName` which reads from `process.env`.
+- Do NOT use `providerArgs` for non-Azure providers unless the Ax factory documents it -- standard providers only need `provider`, `providerKeyName`, `ai`, and optionally `apiURL`.
+- Do NOT confuse `options.searchParameters` (Grok-specific forward option) with `mcpServers` (external tool servers).
+- Do NOT set `provider: "perplexity"` -- Perplexity is accessed via an MCP server, not as a native Ax provider.
+- Do NOT omit `providerKeyName` -- the crew will throw at initialization if the env var is missing.
+
+## References
+
+- [providerArgs.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/providerArgs.ts) (Azure OpenAI)
+- [search-tweets.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/search-tweets.ts) (Grok/xAI)
+- [perplexityDeepSearch.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/perplexityDeepSearch.ts) (Perplexity MCP)
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts) (mixed providers)
+- [src/agents/compose.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/compose.ts)

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

@@ -0,0 +1,169 @@
+---
+name: ax-crew-signatures
+description: AxCrew DSPy-style signature format for defining agent inputs/outputs. Covers signature syntax, types (string, number, boolean, class, string[], json, image, audio, date), optional fields (?), field descriptions, and AxSignature builder alternative.
+version: "__VERSION__"
+---
+
+# AxCrew Signatures
+
+DSPy-style string format: `"input1:type, input2:type -> output1:type, output2:type"`
+
+## Supported Types
+
+| Type | Description |
+|------|-------------|
+| `string` | Text (default if omitted) |
+| `number` | Numeric |
+| `boolean` | True/false |
+| `string[]` | Array of strings |
+| `json` | Arbitrary JSON object |
+| `class` | Classification label |
+| `image` | Image input |
+| `audio` | Audio input |
+| `date` | Date value |
+
+## Signature Syntax
+
+```typescript
+// Minimal — types default to string
+"question -> answer"
+
+// Explicit types
+"question:string -> answer:string"
+
+// Multiple inputs and outputs
+"question:string, context:string -> answer:string, confidence:number"
+
+// Optional fields use ? suffix
+"query:string, context?:string -> answer:string"
+
+// Field descriptions in quotes
+'question:string "The user question", context:string "Reference text" -> answer:string "Final answer", confidence:number "0-1 score"'
+
+// Array output
+'context:string, query:string -> answer:string, keyFindings:string[] "Analyzes context and returns findings"'
+
+// Classification
+"text:string -> sentiment:class"
+
+// Multi-modal
+"image:image, question:string -> caption:string"
+
+// JSON output
+"query:string -> result:json"
+```
+
+## Full Examples in AgentConfig
+
+```typescript
+import { AxCrew } from 'ax-crew';
+import type { AxCrewConfig } from 'ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    // Simple Q&A
+    {
+      name: "QA",
+      description: "Answers questions",
+      signature: "question:string -> answer:string",
+      provider: "openai",
+      ai: { model: "gpt-4o", temperature: 0 },
+    },
+    // Multi-field with descriptions
+    {
+      name: "Analyst",
+      description: "Analyzes data and returns structured findings",
+      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 },
+    },
+    // Optional input field
+    {
+      name: "Summarizer",
+      description: "Summarizes text with optional style",
+      signature: "text:string, style?:string -> summary:string",
+      provider: "openai",
+      ai: { model: "gpt-4o-mini" },
+    },
+    // Classification
+    {
+      name: "Classifier",
+      description: "Classifies sentiment",
+      signature: 'question:string -> sentiment:string "positive, negative, or neutral"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+    },
+    // Multi-output with confidence
+    {
+      name: "Extractor",
+      description: "Extracts entities from text",
+      signature: "text:string -> entities:string[], confidence:number",
+      provider: "openai",
+      ai: { model: "gpt-4o" },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const qa = crew.agents?.get("QA");
+  const result = await qa?.forward({ question: "What is TypeScript?" });
+  console.log(result?.answer);
+
+  const analyst = crew.agents?.get("Analyst");
+  const analysis = await analyst?.forward({
+    context: "Q1 revenue: $10M, Q2: $15M, Q3: $12M",
+    query: "What is the revenue trend?",
+  });
+  console.log(analysis?.answer, analysis?.keyFindings);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## AxSignature Builder Alternative
+
+The `signature` field also accepts an `AxSignature` object from `@ax-llm/ax`:
+
+```typescript
+import { AxSignature } from '@ax-llm/ax';
+import type { AxCrewConfig } from 'ax-crew';
+
+const sig = new AxSignature(
+  "question:string, context:string -> answer:string, confidence:number"
+);
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Agent",
+      description: "Uses AxSignature object",
+      signature: sig, // AxSignature instance accepted
+      provider: "openai",
+      ai: { model: "gpt-4o" },
+    },
+  ],
+};
+```
+
+## Do Not Generate
+
+- Do NOT omit the `->` separator between inputs and outputs
+- Do NOT use unsupported types (e.g., `int`, `float`, `array`, `object` -- use `number`, `string[]`, `json`)
+- Do NOT put field descriptions outside quotes: use `'field:type "desc"'` not `field:type desc`
+- Do NOT use `|` or union types in signatures -- use `class` type for enums
+- Do NOT confuse `string[]` (array of strings) with `json` (arbitrary object)
+- Do NOT wrap the signature string in `AxSignature()` when passing to config -- raw strings work directly
+
+## References
+
+- [rlm-long-task.ts](../examples/rlm-long-task.ts) -- array output in signature
+- [rlm-shared-fields.ts](../examples/rlm-shared-fields.ts) -- field descriptions in quotes
+- [ace-customer-support.ts](../examples/ace-customer-support.ts) -- multi-output signature