@amitdeshmukh/ax-crew 8.5.0 → 8.7.0

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

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

@@ -0,0 +1,168 @@
+---
+name: ax-crew-state
+version: __VERSION__
+description: "State management: shared state, StateInstance, set, get, getAll, reset, accessing state from class-based functions"
+---
+
+# State
+
+Every `AxCrew` instance has a shared `StateInstance` at `crew.state`. All agents and class-based functions in the crew can access the same state.
+
+## StateInstance API
+
+```ts
+interface StateInstance {
+  set(key: string, value: any): void;   // Set a value
+  get(key: string): any;                // Get a value
+  getAll(): Record<string, any>;        // Get all key-value pairs (shallow copy)
+  reset(): void;                        // Clear all state
+}
+```
+
+## Core Behavior
+
+- `crew.state` is created automatically when `new AxCrew(config)` is called.
+- State is keyed by `crewId` (auto-generated UUID). Each crew instance has its own isolated state.
+- State persists for the lifetime of the crew. Calling `crew.destroy()` calls `state.reset()`.
+- Values can be any type: strings, objects, arrays, etc.
+
+## Canonical Pattern
+
+```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();
+
+// Class-based function that reads from shared state
+class SendEmail {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'SendEmail',
+      description: 'Send an email using configured SMTP credentials',
+      parameters: {
+        type: 'object',
+        properties: {
+          to: { type: 'string', description: 'Recipient email' },
+          subject: { type: 'string', description: 'Email subject' },
+          body: { type: 'string', description: 'Email body' },
+        },
+        required: ['to', 'subject', 'body']
+      },
+      func: async ({ to, subject, body }: { to: string; subject: string; body: string }) => {
+        // Access env credentials set via crew.state.set("env", {...})
+        const env = this.state.env || {};
+        const smtpHost = env.SMTP_HOST;
+        const smtpUser = env.SMTP_USER;
+        const smtpPass = env.SMTP_PASS;
+        // ... send email using credentials
+        return { sent: true, to };
+      }
+    };
+  }
+}
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "notifier",
+      description: "An agent that sends email notifications",
+      signature: "task:string -> result:string",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini", temperature: 0 },
+      functions: ["SendEmail"],
+    }
+  ]
+};
+
+async function main() {
+  const functions: FunctionRegistryType = { SendEmail };
+  const crew = new AxCrew(config, functions);
+
+  // Set environment variables in shared state BEFORE adding agents
+  crew.state.set("env", {
+    SMTP_HOST: "smtp.example.com",
+    SMTP_USER: "user@example.com",
+    SMTP_PASS: "secret",
+  });
+
+  // You can also set arbitrary data
+  crew.state.set("company", "Acme Corp");
+  crew.state.set("maxRetries", 3);
+
+  await crew.addAllAgents();
+  const notifier = crew.agents?.get("notifier");
+
+  const result = await notifier?.forward({ task: "Notify user about order shipped" });
+  console.log(result?.result);
+
+  // Read state back
+  console.log("All state:", crew.state.getAll());
+  console.log("Company:", crew.state.get("company"));
+
+  // Reset state (clear all)
+  crew.state.reset();
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Setting Environment Credentials
+
+The common pattern for passing credentials to class-based functions:
+
+```ts
+crew.state.set("env", {
+  WORDPRESS_URL: "http://my-wordpress-site.com",
+  WORDPRESS_USERNAME: "my-username",
+  WORDPRESS_PASSWORD: "my-password",
+});
+```
+
+Inside the class-based function, access via `this.state.env`:
+
+```ts
+class MyFunction {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'MyFunction',
+      description: 'Does something',
+      parameters: { type: 'object', properties: {} },
+      func: () => {
+        const url = this.state.env?.WORDPRESS_URL;  // reads from shared state
+        return url;
+      }
+    };
+  }
+}
+```
+
+## Accessing State from Agents
+
+Each `StatefulAxAgent` has a `state` property that references the crew's shared state:
+
+```ts
+const agent = crew.agents?.get("myAgent");
+// agent.state is the same StateInstance as crew.state
+```
+
+## Do Not Generate
+
+- Do NOT assume state values exist without checking; always use optional chaining (e.g. `this.state.env?.KEY`).
+- Do NOT call `crew.state.set("env", ...)` after `addAllAgents()` if class-based functions read state during construction -- set state first.
+- Do NOT confuse `crew.state` (StateInstance with `set`/`get`/`getAll`/`reset`) with plain objects. The state object passed to class-based function constructors is a plain record, not the `StateInstance` interface.
+- Do NOT store sensitive credentials in state if the state object might be logged or serialized. The `getAll()` method returns all stored values.
+
+## 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/state/index.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/state/index.ts)
+- [src/types.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/types.ts)

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

@@ -0,0 +1,143 @@
+---
+name: ax-crew-streaming
+version: "__VERSION__"
+description: "ax-crew streaming patterns: streaming, streamingForward, stream, delta, real-time, chunks, async generator consumption"
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew Streaming
+
+## streamingForward() vs forward()
+
+`forward()` returns `Promise<Record<string, any>>` -- waits for full response.
+`streamingForward()` returns `AxGenStreamingOut<any>` -- an async generator yielding chunks as they arrive.
+
+Both accept the same input values object. Both work with `axgen` and `axagent` execution modes.
+
+```typescript
+// Blocking
+const result = await agent.forward({ question: "What is AI?" });
+console.log(result.answer);
+
+// Streaming
+const stream = agent.streamingForward({ question: "What is AI?" });
+for await (const chunk of stream) {
+  if (chunk.delta && 'answer' in chunk.delta) {
+    process.stdout.write(chunk.delta.answer);
+  }
+}
+```
+
+## chunk.delta Structure
+
+Each yielded chunk has a `delta` property containing partial values keyed by output field names from the agent's signature.
+
+```typescript
+// For signature: 'question:string -> answer:string'
+// chunk.delta = { answer: "partial text..." }
+
+// For signature: 'query:string -> title:string, summary:string'
+// chunk.delta may contain { title: "..." } or { summary: "..." }
+```
+
+Always check for the field's existence before accessing:
+```typescript
+if (chunk.delta && typeof chunk.delta === 'object' && 'answer' in chunk.delta) {
+  process.stdout.write(chunk.delta.answer);
+}
+```
+
+## Stream Config in Agent Config
+
+Enable streaming at the provider level via `ai.stream` or `options.stream`:
+
+```typescript
+{
+  name: "StreamAgent",
+  ai: { model: "gemini-2.5-flash", stream: true },   // provider-level
+  options: { stream: true },                           // forward options level
+}
+```
+
+## Overload Signatures
+
+```typescript
+// Without explicit AI instance (uses agent's configured AI)
+agent.streamingForward(values: Record<string, any>, options?: AxProgramStreamingForwardOptions): AxGenStreamingOut<any>;
+
+// With explicit AI instance
+agent.streamingForward(ai: AxAI, values: Record<string, any>, options?: AxProgramStreamingForwardOptions): AxGenStreamingOut<any>;
+```
+
+## Canonical Pattern
+
+```typescript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "ManagerAgent",
+      description: "Completes a user specified task",
+      signature:
+        'question:string "a question to be answered" -> answer:string "the answer to the question"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", maxTokens: 1000, temperature: 0 },
+      options: { debug: true, stream: true },
+      agents: ["MathAgent"],
+    },
+    {
+      name: "MathAgent",
+      description: "Solves math problems",
+      signature:
+        'mathProblem:string "a math problem" -> solution:string "the answer"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get("ManagerAgent");
+  if (!agent) throw new Error("Agent not found");
+
+  const stream = agent.streamingForward({
+    question: "Get me the first 5 fibonacci numbers divided by 2",
+  });
+
+  for await (const chunk of stream) {
+    if (chunk.delta && typeof chunk.delta === 'object' && 'answer' in chunk.delta) {
+      process.stdout.write(chunk.delta.answer);
+    }
+  }
+  console.log('\n');
+
+  // Metrics still available after streaming
+  console.log("Agent Metrics:", JSON.stringify(agent.getMetrics?.(), null, 2));
+  console.log("Crew Metrics:", JSON.stringify(crew.getCrewMetrics(), null, 2));
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT `await` the return of `streamingForward()` -- it returns the async generator directly, not a promise.
+- Do NOT assume `chunk.delta` is always a string -- it is an object keyed by output field names.
+- Do NOT forget to check field existence in `chunk.delta` before accessing (`'fieldName' in chunk.delta`).
+- Do NOT use `forward()` with the expectation of receiving streaming chunks -- use `streamingForward()`.
+- Do NOT skip `crew.destroy()` -- it cleans up MCP servers and resources.
+
+## References
+
+- [streaming.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/streaming.ts)
+- [Source: StatefulAxAgent.streamingForward](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/index.ts)