@amitdeshmukh/ax-crew 5.0.0 → 6.0.0

package/src/agents/compose.ts

@@ -0,0 +1,80 @@
+import { ai } from '@ax-llm/ax';
+import type { AxAI } from '@ax-llm/ax';
+import type { AxCrewConfig } from '../types.js';
+
+type BuildProviderArgs = {
+  provider: string;
+  apiKey: string;
+  config: any;
+  apiURL?: string;
+  providerArgs?: Record<string, unknown>;
+  options?: Record<string, unknown>;
+};
+
+export function instantiateProvider({
+  provider,
+  apiKey,
+  config,
+  apiURL,
+  providerArgs,
+  options,
+}: BuildProviderArgs): AxAI<any> {
+  const args: any = { name: provider as any, apiKey, config, options };
+  if (apiURL) args.apiURL = apiURL;
+  if (providerArgs && typeof providerArgs === 'object') Object.assign(args, providerArgs);
+  return ai(args) as unknown as AxAI<any>;
+}
+
+export function buildProvidersFromConfig(cfg: AxCrewConfig): AxAI<any>[] {
+  const services: AxAI<any>[] = [];
+  for (const agent of cfg.crew) {
+    const apiKeyName = agent.providerKeyName;
+    if (!apiKeyName) throw new Error(`Provider key name is missing for agent ${agent.name}`);
+    const apiKey = resolveApiKey(apiKeyName) || '';
+    if (!apiKey) throw new Error(`API key '${apiKeyName}' not set for agent ${agent.name}`);
+
+    const service = instantiateProvider({
+      provider: String(agent.provider).toLowerCase(),
+      apiKey,
+      config: agent.ai,
+      apiURL: agent.apiURL,
+      providerArgs: (agent as any).providerArgs,
+      options: agent.options,
+    });
+    services.push(service);
+  }
+  return services;
+}
+
+
+// Provider discovery helpers consolidated here (previously in src/providers.ts)
+export function discoverProvidersFromConfig(cfg: AxCrewConfig): string[] {
+  const providers = new Set<string>();
+  for (const agent of cfg.crew) {
+    providers.add(String(agent.provider).toLowerCase());
+  }
+  return Array.from(providers);
+}
+
+export function listSelectableProviders(cfg: AxCrewConfig): string[] {
+  return discoverProvidersFromConfig(cfg);
+}
+
+function resolveApiKey(varName: string): string | undefined {
+  try {
+    // Prefer Node env when available
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    if (typeof process !== 'undefined' && process?.env) {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      // @ts-ignore
+      return process.env[varName];
+    }
+    // Fallback: allow global exposure in browser builds (e.g., injected at runtime)
+    return (globalThis as any)?.[varName];
+  } catch {
+    return undefined;
+  }
+}
+
+

package/src/agents/index.ts

@@ -14,7 +14,7 @@ import type {
    StateInstance, 
    FunctionRegistryType, 
    UsageCost, 
-   CrewConfigInput, 
+   AxCrewConfig,
    MCPTransportConfig,
 } from "../types.js";
 
@@ -260,10 +260,26 @@ class StatefulAxAgent extends AxAgent<any, any> {
 }
 
 /**
- * Represents a crew of agents with shared state functionality.
+ * AxCrew orchestrates a set of Ax agents that share state,
+ * tools (functions), optional MCP servers, streaming, and a built-in metrics
+ * registry for tokens, requests, and estimated cost.
+ *
+ * Typical usage:
+ *  const crew = new AxCrew(config, AxCrewFunctions)
+ *  await crew.addAllAgents()
+ *  const planner = crew.agents?.get("Planner")
+ *  const res = await planner?.forward({ task: "Plan something" })
+ *
+ * Key behaviors:
+ * - Validates and instantiates agents from a config-first model
+ * - Shares a mutable state object across all agents in the crew
+ * - Supports sub-agents and a function registry per agent
+ * - Tracks per-agent and crew-level metrics via MetricsRegistry
+ * - Provides helpers to add agents (individually, a subset, or all) and
+ *   to reset metrics/costs when needed
  */
 class AxCrew {
-  private crewConfig: CrewConfigInput;
+  private crewConfig: AxCrewConfig;
   functionsRegistry: FunctionRegistryType = {};
   crewId: string;
   agents: Map<string, StatefulAxAgent> | null;
@@ -271,12 +287,12 @@ class AxCrew {
 
   /**
    * Creates an instance of AxCrew.
-   * @param {CrewConfigInput} crewConfig - Either a path to the agent config file or a JSON object with crew configuration.
+   * @param {AxCrewConfig} crewConfig - JSON object with crew configuration.
    * @param {FunctionRegistryType} [functionsRegistry={}] - The registry of functions to use in the crew.
    * @param {string} [crewId=uuidv4()] - The unique identifier for the crew.
    */
   constructor(
-    crewConfig: CrewConfigInput,
+    crewConfig: AxCrewConfig,
     functionsRegistry: FunctionRegistryType = {},
     crewId: string = uuidv4()
   ) {
@@ -286,7 +302,7 @@ class AxCrew {
     }
 
     // Validate each agent in the crew
-    crewConfig.crew.forEach(agent => {
+    crewConfig.crew.forEach((agent: any) => {
       if (!agent.name || agent.name.trim() === '') {
         throw new Error('Agent name cannot be empty');
       }

package/src/functions/index.ts

@@ -1,6 +1,16 @@
 import { CurrentDateTime, DaysBetweenDates } from './dateTime.js';
 
-// Built-in functions
+/**
+ * Built-in function registry for AxCrew agents.
+ *
+ * Contains common utility tools/functions that can be referenced by name from
+ * agent configs (e.g., "functions": ["CurrentDateTime", "DaysBetweenDates"]).
+ * You can pass this object to the AxCrew constructor or merge with your
+ * own registry.
+ * Example:
+ * const crew = new AxCrew(config, AxCrewFunctions); or
+ * const crew = new AxCrew(config, { ...AxCrewFunctions, ...myFunctions });
+ */
 const AxCrewFunctions = {
   CurrentDateTime,
   DaysBetweenDates

package/src/index.ts

@@ -1,6 +1,6 @@
 import { AxCrew } from './agents/index.js';
 import { AxCrewFunctions } from './functions/index.js';
-import type { CrewConfigInput, AgentConfig } from './types.js';
+import type { AxCrewConfig, AgentConfig } from './types.js';
 
 import type { 
   UsageCost, 
@@ -9,28 +9,42 @@ import type {
   StateInstance, 
   FunctionRegistryType 
 } from './types.js';
+/**
+ * Metrics types and helpers for request counts, token usage, and estimated cost.
+ *
+ * Re-exports the metrics module for convenience:
+ *  - Types: TokenUsage, MetricsSnapshot, etc.
+ *  - Namespace: MetricsRegistry (record/snapshot/reset helpers)
+ */
 export * from './metrics/index.js';
+/**
+ * MetricsRegistry provides functions to record requests, tokens, and cost,
+ * and to snapshot/reset metrics at agent or crew granularity.
+ */
 export { MetricsRegistry } from './metrics/index.js';
 
-// Main AxCrew configuration interface
 /**
- * The configuration for an AxCrew.
- * 
- * @property {AgentConfig[]} crew - The agents that make up the crew.
+ * Create and manage a crew of Ax agents that share state and metrics.
+ * See the `AxCrew` class for full documentation.
+ */
+const _AxCrew: typeof AxCrew = AxCrew;
+
+/**
+ * Built-in function registry with common tools that can be referenced by name
+ * from agent configs, or extended with your own functions.
  */
-interface AxCrewConfig {
-  crew: AgentConfig[];
-}
+const _AxCrewFunctions: typeof AxCrewFunctions = AxCrewFunctions;
 
 export { 
-  AxCrew,
-  AxCrewFunctions,
+  /** See class JSDoc on the `AxCrew` implementation. */
+  _AxCrew as AxCrew,
+  /** Built-in function registry; see file docs in `src/functions/index.ts`. */
+  _AxCrewFunctions as AxCrewFunctions,
   FunctionRegistryType,
   // Type exports
   type AggregatedMetrics,
   type AggregatedCosts,
   type AgentConfig,
-  type CrewConfigInput,
   type AxCrewConfig,
   type StateInstance,
   type UsageCost,

package/src/types.ts

@@ -3,26 +3,13 @@ import type {
   AxSignature, 
   AxModelConfig,
   AxMCPStreamableHTTPTransportOptions,
-  AxProgramForwardOptions
+  AxProgramForwardOptions,
+  AxAIArgs
 } from '@ax-llm/ax';
 
-// Canonical provider slugs supported by ai() factory
-export type Provider =
-  // Canonical slugs per docs
-  | 'openai'
-  | 'anthropic'
-  | 'google-gemini'
-  | 'mistral'
-  | 'groq'
-  | 'cohere'
-  | 'together'
-  | 'deepseek'
-  | 'ollama'
-  | 'huggingface'
-  | 'openrouter'
-  | 'azure-openai'
-  | 'reka'
-  | 'x-grok'
+// Provider ids are derived from Ax's factory arg type so new providers added in Ax
+// are picked up at compile time without updating AxCrew.
+export type Provider = AxAIArgs<any>['name'];
 
 /**
  * A state instance that is shared between agents.
@@ -209,13 +196,49 @@ interface AgentConfig {
 }
 
 /**
- * The input type for the agent config. This can be a path to a JSON file or a JSON object.
+ * The configuration object for an AxCrew instance.
+ * 
+ * @property {AgentConfig[]} crew - The agents that make up the crew.
+ * @example
+ * const config: AxCrewConfig = {
+ *   crew: [
+ *     {
+ *       name: "Agent1",
+ *       description: "Agent 1 description",
+ *       signature: "signature",
+ *       provider: "provider",
+ *       providerKeyName: "providerKeyName",
+ *       ai: {
+ *         model: "model",
+ *         temperature: 0,
+ *       },
+ *       options: {
+ *         debug: true,
+ *       },
+ *       functions: ["function1", "function2"],
+ *       agents: ["agent2"],
+ *     },
+ *     {
+ *       name: "Agent2",
+ *       description: "Agent 2 description",
+ *       signature: "signature",
+ *       provider: "provider",
+ *       providerKeyName: "providerKeyName",
+ *       ai: {
+ *         model: "model",
+ *         temperature: 0,
+ *       }
+ *   ]
+ * }
+ * const crew = new AxCrew(config);
  */
-type CrewConfigInput = string | { crew: AgentConfig[] };
+interface AxCrewConfig {
+  crew: AgentConfig[]
+}
 
 export {
   type AgentConfig,
-  type CrewConfigInput,
+  type AxCrewConfig,
   type AggregatedMetrics,
   type StateInstance,
   type FunctionRegistryType,

package/dist/config/index.d.ts

@@ -1,5 +0,0 @@
-interface ProviderApiKeys {
-    [key: string]: string | undefined;
-}
-declare const PROVIDER_API_KEYS: ProviderApiKeys;
-export { PROVIDER_API_KEYS, };

package/dist/config/index.js

@@ -1,30 +0,0 @@
-import dotenv from 'dotenv';
-dotenv.config();
-// AI API keys
-const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
-const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
-const AZURE_OPENAI_API_KEY = process.env.AZURE_OPENAI_API_KEY;
-const COHERE_API_KEY = process.env.COHERE_API_KEY;
-const DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY;
-const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
-const GROQ_API_KEY = process.env.GROQ_API_KEY;
-const TOGETHER_API_KEY = process.env.TOGETHER_API_KEY;
-const MISTRAL_API_KEY = process.env.MISTRAL_API_KEY;
-const HUGGINGFACE_API_KEY = process.env.HUGGINGFACE_API_KEY;
-const REKA_API_KEY = process.env.REKA_API_KEY;
-const GROK_API_KEY = process.env.GROK_API_KEY;
-const PROVIDER_API_KEYS = {
-    COHERE_API_KEY,
-    GEMINI_API_KEY,
-    OPENAI_API_KEY,
-    AZURE_OPENAI_API_KEY,
-    ANTHROPIC_API_KEY,
-    DEEPSEEK_API_KEY,
-    GROQ_API_KEY,
-    TOGETHER_API_KEY,
-    MISTRAL_API_KEY,
-    HUGGINGFACE_API_KEY,
-    REKA_API_KEY,
-    GROK_API_KEY
-};
-export { PROVIDER_API_KEYS, };

package/src/config/index.ts

@@ -1,40 +0,0 @@
-import dotenv from 'dotenv';
-dotenv.config();
-
-// AI API keys
-const ANTHROPIC_API_KEY: string | undefined = process.env.ANTHROPIC_API_KEY;
-const OPENAI_API_KEY: string | undefined = process.env.OPENAI_API_KEY;
-const AZURE_OPENAI_API_KEY: string | undefined = process.env.AZURE_OPENAI_API_KEY;
-const COHERE_API_KEY: string | undefined = process.env.COHERE_API_KEY;
-const DEEPSEEK_API_KEY: string | undefined = process.env.DEEPSEEK_API_KEY;
-const GEMINI_API_KEY: string | undefined = process.env.GEMINI_API_KEY;
-const GROQ_API_KEY: string | undefined = process.env.GROQ_API_KEY;
-const TOGETHER_API_KEY: string | undefined = process.env.TOGETHER_API_KEY;
-const MISTRAL_API_KEY: string | undefined = process.env.MISTRAL_API_KEY;
-const HUGGINGFACE_API_KEY: string | undefined = process.env.HUGGINGFACE_API_KEY;
-const REKA_API_KEY: string | undefined = process.env.REKA_API_KEY;
-const GROK_API_KEY: string | undefined = process.env.GROK_API_KEY;
-// Note: Ollama typically doesn't require an API key for local usage
-
-interface ProviderApiKeys {
-  [key: string]: string | undefined;
-}
-
-const PROVIDER_API_KEYS: ProviderApiKeys = {
-  COHERE_API_KEY,
-  GEMINI_API_KEY,
-  OPENAI_API_KEY,
-  AZURE_OPENAI_API_KEY,
-  ANTHROPIC_API_KEY,
-  DEEPSEEK_API_KEY,
-  GROQ_API_KEY,
-  TOGETHER_API_KEY,
-  MISTRAL_API_KEY,
-  HUGGINGFACE_API_KEY,
-  REKA_API_KEY,
-  GROK_API_KEY
-};
-
-export {
-  PROVIDER_API_KEYS,
-};