@amitdeshmukh/ax-crew 4.1.2 → 6.0.0

package/CHANGELOG.md

@@ -1,3 +1,46 @@
+# Changelog
+
+## [6.0.0] - 2025-10-22
+
+### Breaking
+- Config is now object-only to be browser-safe. File-path based configs are no longer supported. Load JSON yourself and pass `{ crew: [...] }`.
+
+### Added
+- Runtime API key resolution via `providerKeyName`. Keys are read from `process.env[providerKeyName]` in Node or `globalThis[providerKeyName]` in the browser.
+- Updated examples to use `dotenv/config` to ensure keys are available at runtime.
+
+### Changed
+- Removed reliance on a hardcoded `PROVIDER_API_KEYS` map; providers read secrets using the user-supplied env var name.
+- `providerArgs` are forwarded unchanged to Ax; validation and semantics are handled by Ax provider implementations.
+- Docs updated: object-only config, env resolution behavior, providerArgs guidance.
+
+### Removed
+- Hardcoded provider lists/registries and the old `providers.ts` list file.
+- Temporary removal of router/balancer helpers and related examples to simplify this refactor.
+
+### Migration notes
+- If you previously passed a config file path, read the file yourself and pass the parsed object to `new AxCrew(config)`.
+- Set `providerKeyName` to the exact environment variable name holding the API key. Ensure env is loaded before constructing the crew (e.g., `import 'dotenv/config'`).
+
+## [5.0.0] - 2025-10-16
+
+### Added
+- Provider-specific arguments via `providerArgs` in `AgentConfig` to pass through typed provider params to the underlying Ax factory.
+- Typed forwarding for common providers in `parseAgentConfig`:
+  - azure-openai: `resourceName`, `deploymentName`, `version` (falls back to `apiURL` as `resourceName` if provided)
+  - anthropic: `projectId`, `region` (on Vertex AI)
+  - google-gemini: `projectId`, `region`, `endpointId`
+  - openrouter: `referer`, `title`
+  - ollama: `url`
+- Example `examples/providerArgs.ts` demonstrating `providerArgs` with Azure OpenAI.
+- JSDoc function hints for cost/usage APIs (`getMetrics`, `resetMetrics`, `resetCosts`, `getCrewMetrics`, `resetCrewMetrics`, and metrics registry helpers).
+
+### Docs
+- README section documenting `providerArgs` usage, supported providers, and Azure configuration examples.
+
+### Notes
+- Existing configs continue to work. For Azure, you can still set `apiURL`; when `resourceName` is omitted, the code uses `apiURL` as the `resourceName` (full endpoint) for convenience.
+
 # Changelog
 ## [4.1.2] - 2025-10-14
 

package/README.md

@@ -33,34 +33,17 @@ ANTHROPIC_API_KEY=...
 OPENAI_API_KEY=...
 AZURE_OPENAI_API_KEY=...
 ```
-In each agent config, set `providerKeyName` to the env var name.
+In each agent config, set `providerKeyName` to the env var name. AxCrew resolves the key at runtime by reading `process.env[providerKeyName]` in Node or `globalThis[providerKeyName]` in the browser. Ensure your env is loaded (for example, import `dotenv/config` in Node) before creating the crew.
 
-#### Azure OpenAI
-- Use provider `azure-openai`.
-- Set `providerKeyName` to `AZURE_OPENAI_API_KEY`.
-- Set `apiURL` to your Azure endpoint (e.g., `https://your-resource.openai.azure.com`).
-
-Minimal example agent config:
-```json
-{
-  "name": "Writer",
-  "description": "Writes concise summaries",
-  "signature": "topic:string -> summary:string",
-  "provider": "azure-openai",
-  "providerKeyName": "AZURE_OPENAI_API_KEY",
-  "ai": { "model": "gpt-4o-mini", "temperature": 0 },
-  "apiURL": "https://your-resource.openai.azure.com"
-}
-```
+#### Provider-specific arguments (`providerArgs`)
+Some providers require extra top-level configuration beyond `ai.model` (for example, Azure deployment details or Vertex AI project/region). Pass these via `providerArgs`. AxCrew forwards `providerArgs` to Ax unchanged; validation and semantics are handled by Ax. Refer to Ax provider docs for supported fields.
 
 ### Quickstart
-This package includes TypeScript declarations and provides type safety.
 
 ```typescript
 import { AxCrew, AxCrewFunctions, FunctionRegistryType, StateInstance } from '@amitdeshmukh/ax-crew';
 import type { AxFunction } from '@ax-llm/ax';
 
-// Type-safe configuration
 const config = {
   crew: [{
     name: "Planner",
@@ -147,25 +130,7 @@ Key TypeScript features:
 ## Usage
 
 ### Initializing a Crew
-A Crew is a team of agents that work together to achieve a common goal. You can configure your crew in two ways:
-
-1. Using a JSON configuration file that defines the agents in the crew, along with their individual configurations.
-2. Directly passing a JSON object with the crew configuration.
-
-#### Using a Configuration File
-See [agentConfig.json](agentConfig.json) for an example configuration file.
-
-```javascript
-// Import the AxCrew class
-import { AxCrew } from '@amitdeshmukh/ax-crew';
-
-// Create a new instance of AxCrew using a config file
-const configFilePath = './agentConfig.json';
-const crew = new AxCrew(configFilePath);
-```
-
-#### Using a Direct Configuration Object
-You can also pass the configuration directly as a JSON object:
+Pass a JSON object to the `AxCrew` constructor:
 
 ```javascript
 // Import the AxCrew class
@@ -196,15 +161,7 @@ const config = {
 const crew = new AxCrew(config);
 ```
 
-Both methods support the same configuration structure and options. Choose the one that best fits your use case:
-- Use a configuration file when you want to:
-  - Keep your configuration separate from your code
-  - Share configurations across different projects
-  - Version control your configurations
-- Use a direct configuration object when you want to:
-  - Generate configurations dynamically
-  - Modify configurations at runtime
-  - Keep everything in one file for simpler projects
+AxCrew no longer supports reading from a configuration file to remain browser-compatible.
 
 ### Agent Persona: definition and prompt
 
@@ -408,7 +365,7 @@ An example of how to complete a task using the agents is shown below. The `Plann
 import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
 
 // Create a new instance of AxCrew
-const crew = new AxCrew('./agentConfig.json', AxCrewFunctions);
+const crew = new AxCrew(config, AxCrewFunctions);
 crew.addAgentsToCrew(['Planner', 'Calculator', 'Manager']);
 
 // Get agent instances
@@ -440,7 +397,7 @@ The package supports streaming responses from agents, allowing you to receive an
 import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
 
 // Create and initialize crew as shown above
-const crew = new AxCrew('./agentConfig.json', AxCrewFunctions);
+const crew = new AxCrew(config, AxCrewFunctions);
 await crew.addAgentsToCrew(['Planner']);
 
 const planner = crew.agents.get("Planner");
@@ -657,7 +614,7 @@ MCP functions are automatically available to agents once the servers are configu
 import { AxCrew } from '@amitdeshmukh/ax-crew';
 
 // Create crew with MCP-enabled agents
-const crew = new AxCrew('./agentConfig.json');
+const crew = new AxCrew(config);
 await crew.addAgent('DataAnalyst'); // Agent with MCP servers configured
 
 const analyst = crew.agents.get('DataAnalyst');

package/dist/agents/agentConfig.d.ts

@@ -1,16 +1,16 @@
 import { AxDefaultCostTracker } from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig } from '../types.js';
+import type { AgentConfig, AxCrewConfig, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig } from '../types.js';
 export declare function isStdioTransport(config: MCPTransportConfig): config is MCPStdioTransportConfig;
 export declare function isHTTPSSETransport(config: MCPTransportConfig): config is MCPHTTPSSETransportConfig;
 export declare function isStreambleHTTPTransport(config: MCPTransportConfig): config is MCPStreamableHTTPTransportConfig;
 /**
- * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
- * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.
+ * Returns the AxCrew config from a direct JSON object. Browser-safe.
+ * @param {CrewConfig} input - A JSON object with crew configuration.
  * @returns {Object} The parsed crew config.
  * @throws Will throw an error if reading/parsing fails.
  */
-declare const parseCrewConfig: (input: CrewConfigInput) => {
+declare const parseCrewConfig: (input: AxCrewConfig) => {
     crew: AgentConfig[];
 };
 /**
@@ -18,14 +18,14 @@ declare const parseCrewConfig: (input: CrewConfigInput) => {
  * and creates an instance of the Agent with the appropriate settings.
  *
  * @param {string} agentName - The identifier for the AI agent to be initialized.
- * @param {CrewConfigInput} crewConfig - Either a file path to the JSON configuration or a JSON object with crew configuration.
+ * @param {AxCrewConfig} crewConfig - A JSON object with crew configuration.
  * @param {FunctionRegistryType} functions - The functions available to the agent.
  * @param {Object} state - The state object for the agent.
  * @returns {Object} An object containing the Agents AI instance, its name, description, signature, functions and subAgentList.
  * @throws {Error} Throws an error if the agent configuration is missing, the provider is unsupported,
  * the API key is not found, or the provider key name is not specified in the configuration.
  */
-declare const parseAgentConfig: (agentName: string, crewConfig: CrewConfigInput, functions: FunctionRegistryType, state: Record<string, any>) => Promise<{
+declare const parseAgentConfig: (agentName: string, crewConfig: AxCrewConfig, functions: FunctionRegistryType, state: Record<string, any>) => Promise<{
     ai: import("@ax-llm/ax").AxAI<string>;
     name: string;
     description: string;

package/dist/agents/agentConfig.js

@@ -1,27 +1,7 @@
-import fs from 'fs';
-// Import Ax factory and MCP transports (as exported by current package)
+// Import Ax factory and MCP transports
 import { ai, AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport, AxDefaultCostTracker } from '@ax-llm/ax';
 // STDIO transport from tools package
 import { AxMCPStdioTransport } from '@ax-llm/ax-tools';
-import { PROVIDER_API_KEYS } from '../config/index.js';
-// Canonical provider slugs supported by ai() factory
-const PROVIDER_CANONICAL = new Set([
-    'openai',
-    'anthropic',
-    'google-gemini',
-    'mistral',
-    'groq',
-    'cohere',
-    'together',
-    'deepseek',
-    'ollama',
-    'huggingface',
-    'openrouter',
-    'azure-openai',
-    'reka',
-    'x-grok'
-]);
-// Provider type lives in src/types.ts
 // Type guard to check if config is stdio transport
 export function isStdioTransport(config) {
     return 'command' in config;
@@ -44,48 +24,7 @@ export function isStreambleHTTPTransport(config) {
 function isConstructor(func) {
     return typeof func === 'function' && 'prototype' in func && 'toFunction' in func.prototype;
 }
-/**
- * Provides a user-friendly error message for JSON parsing errors
- */
-const getFormattedJSONError = (error, fileContents) => {
-    if (error instanceof SyntaxError) {
-        const match = error.message.match(/position (\d+)/);
-        const position = match ? parseInt(match[1]) : -1;
-        if (position !== -1) {
-            const lines = fileContents.split('\n');
-            let currentPos = 0;
-            let errorLine = 0;
-            let errorColumn = 0;
-            // Find the line and column of the error
-            for (let i = 0; i < lines.length; i++) {
-                if (currentPos + lines[i].length >= position) {
-                    errorLine = i + 1;
-                    errorColumn = position - currentPos + 1;
-                    break;
-                }
-                currentPos += lines[i].length + 1; // +1 for the newline character
-            }
-            const contextLines = lines.slice(Math.max(0, errorLine - 3), errorLine + 2)
-                .map((line, idx) => `${errorLine - 2 + idx}:  ${line}`).join('\n');
-            return `JSON Parse Error in your agent configuration:
-      
-Error near line ${errorLine}, column ${errorColumn}
-
-Context:
-${contextLines}
-
-Common issues to check:
-- Missing or extra commas between properties
-- Missing quotes around property names
-- Unmatched brackets or braces
-- Invalid JSON values
-- Trailing commas (not allowed in JSON)
-
-Original error: ${error.message}`;
-        }
-    }
-    return `Error parsing agent configuration: ${error.message}`;
-};
+// Removed file/JSON parse helpers to keep browser-safe
 const initializeMCPServers = async (agentConfigData) => {
     const mcpServers = agentConfigData.mcpServers;
     if (!mcpServers || Object.keys(mcpServers).length === 0) {
@@ -126,41 +65,23 @@ const initializeMCPServers = async (agentConfigData) => {
     }
 };
 /**
- * Parses and returns the AxCrew config from either a JSON config file or a direct JSON object.
- * @param {CrewConfigInput} input - Either a path to the agent config json file or a JSON object with crew configuration.
+ * Returns the AxCrew config from a direct JSON object. Browser-safe.
+ * @param {CrewConfig} input - A JSON object with crew configuration.
  * @returns {Object} The parsed crew config.
  * @throws Will throw an error if reading/parsing fails.
  */
 const parseCrewConfig = (input) => {
-    try {
-        if (typeof input === 'string') {
-            // Handle file path input
-            const fileContents = fs.readFileSync(input, 'utf8');
-            const parsedConfig = JSON.parse(fileContents);
-            return parsedConfig;
-        }
-        else {
-            // Handle direct JSON object input
-            return input;
-        }
-    }
-    catch (e) {
-        if (e instanceof Error) {
-            if (typeof input === 'string') {
-                const formattedError = getFormattedJSONError(e, fs.readFileSync(input, 'utf8'));
-                throw new Error(formattedError);
-            }
-            throw new Error(`Error parsing agent configuration: ${e.message}`);
-        }
-        throw e;
+    if (!input || typeof input !== 'object' || !Array.isArray(input.crew)) {
+        throw new Error('Invalid crew configuration: expected an object with a crew array');
     }
+    return input;
 };
 /**
  * Parses the agent's configuration, validates the presence of the necessary API key,
  * and creates an instance of the Agent with the appropriate settings.
  *
  * @param {string} agentName - The identifier for the AI agent to be initialized.
- * @param {CrewConfigInput} crewConfig - Either a file path to the JSON configuration or a JSON object with crew configuration.
+ * @param {AxCrewConfig} crewConfig - A JSON object with crew configuration.
  * @param {FunctionRegistryType} functions - The functions available to the agent.
  * @param {Object} state - The state object for the agent.
  * @returns {Object} An object containing the Agents AI instance, its name, description, signature, functions and subAgentList.
@@ -174,18 +95,16 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         if (!agentConfigData) {
             throw new Error(`AI agent with name ${agentName} is not configured`);
         }
-        // Enforce canonical provider slug
-        const lower = agentConfigData.provider.toLowerCase();
-        if (!PROVIDER_CANONICAL.has(lower)) {
-            throw new Error(`AI provider ${agentConfigData.provider} is not supported. Use one of: ${Array.from(PROVIDER_CANONICAL).join(', ')}`);
-        }
+        // Normalize provider slug to lowercase and validate via Ax factory
+        const lower = String(agentConfigData.provider).toLowerCase();
         const provider = lower;
-        // If an API Key property is present, get the API key for the AI agent from the environment variables
+        // Resolve API key from user-supplied environment variable name
         let apiKey = '';
         if (agentConfigData.providerKeyName) {
-            apiKey = PROVIDER_API_KEYS[agentConfigData.providerKeyName] || '';
+            const keyName = agentConfigData.providerKeyName;
+            apiKey = resolveApiKey(keyName) || '';
             if (!apiKey) {
-                throw new Error(`API key for provider ${agentConfigData.provider} is not set in environment variables`);
+                throw new Error(`API key '${keyName}' for provider ${agentConfigData.provider} is not set in environment`);
             }
         }
         else {
@@ -214,7 +133,20 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
                 throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
             }
         }
-        const aiInstance = ai(aiArgs);
+        // Forward provider-specific arguments as-is; let Ax validate/ignore as needed
+        const providerArgs = agentConfigData.providerArgs;
+        if (providerArgs && typeof providerArgs === 'object') {
+            Object.assign(aiArgs, providerArgs);
+        }
+        // Validate provider by attempting instantiation; Ax will throw on unknown providers
+        let aiInstance;
+        try {
+            aiInstance = ai(aiArgs);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Unsupported provider '${provider}': ${msg}`);
+        }
         // If an mcpServers config is provided in the agent config, convert to functions
         const mcpFunctions = await initializeMCPServers(agentConfigData);
         // Prepare functions for the AI agent
@@ -254,3 +186,20 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
     }
 };
 export { parseAgentConfig, parseCrewConfig };
+function resolveApiKey(varName) {
+    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?.[varName];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/agents/agentUseCosts.d.ts

@@ -5,8 +5,22 @@ import type { StateInstance, ModelUsage, ModelInfo, UsageCost, AggregatedCosts }
  */
 export declare class StateFulAxAgentUsage {
     static STATE_KEY_PREFIX: string;
+    /**
+     * Compute usage costs given a model usage record and model pricing info.
+     * Returns null if inputs are invalid. Token-based costs are computed with high precision.
+     */
     static calculateCost(modelUsage: ModelUsage, modelInfo: ModelInfo): UsageCost | null;
+    /**
+     * Persist or aggregate the cost for an agent in the shared crew state.
+     * No-op if cost is null.
+     */
     static trackCostInState(agentName: string, cost: UsageCost | null, state: StateInstance): void;
+    /**
+     * Aggregate and return total costs across all agents from the shared crew state.
+     */
     static getAggregatedCosts(state: StateInstance): AggregatedCosts;
+    /**
+     * Remove all stored per-agent costs from the shared crew state.
+     */
     static resetCosts(state: StateInstance): void;
 }

package/dist/agents/agentUseCosts.js

@@ -5,6 +5,10 @@ import { Decimal } from 'decimal.js';
  */
 export class StateFulAxAgentUsage {
     static STATE_KEY_PREFIX = 'agent_usage_';
+    /**
+     * Compute usage costs given a model usage record and model pricing info.
+     * Returns null if inputs are invalid. Token-based costs are computed with high precision.
+     */
     static calculateCost(modelUsage, modelInfo) {
         // Handle both direct properties and nested tokens structure
         const promptTokens = modelUsage.tokens?.promptTokens ?? modelUsage.promptTokens;
@@ -44,6 +48,10 @@ export class StateFulAxAgentUsage {
             return null;
         }
     }
+    /**
+     * Persist or aggregate the cost for an agent in the shared crew state.
+     * No-op if cost is null.
+     */
     static trackCostInState(agentName, cost, state) {
         // If cost is null, skip tracking
         if (!cost)
@@ -75,6 +83,9 @@ export class StateFulAxAgentUsage {
             state.set(stateKey, cost);
         }
     }
+    /**
+     * Aggregate and return total costs across all agents from the shared crew state.
+     */
     static getAggregatedCosts(state) {
         const allState = state.getAll();
         const agentCosts = {};
@@ -108,6 +119,9 @@ export class StateFulAxAgentUsage {
             }
         };
     }
+    /**
+     * Remove all stored per-agent costs from the shared crew state.
+     */
     static resetCosts(state) {
         const allState = state.getAll();
         Object.keys(allState).forEach(key => {

package/dist/agents/compose.d.ts

@@ -0,0 +1,15 @@
+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 declare function instantiateProvider({ provider, apiKey, config, apiURL, providerArgs, options, }: BuildProviderArgs): AxAI<any>;
+export declare function buildProvidersFromConfig(cfg: AxCrewConfig): AxAI<any>[];
+export declare function discoverProvidersFromConfig(cfg: AxCrewConfig): string[];
+export declare function listSelectableProviders(cfg: AxCrewConfig): string[];
+export {};

package/dist/agents/compose.js

@@ -0,0 +1,58 @@
+import { ai } from '@ax-llm/ax';
+export function instantiateProvider({ provider, apiKey, config, apiURL, providerArgs, options, }) {
+    const args = { name: provider, apiKey, config, options };
+    if (apiURL)
+        args.apiURL = apiURL;
+    if (providerArgs && typeof providerArgs === 'object')
+        Object.assign(args, providerArgs);
+    return ai(args);
+}
+export function buildProvidersFromConfig(cfg) {
+    const services = [];
+    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.providerArgs,
+            options: agent.options,
+        });
+        services.push(service);
+    }
+    return services;
+}
+// Provider discovery helpers consolidated here (previously in src/providers.ts)
+export function discoverProvidersFromConfig(cfg) {
+    const providers = new Set();
+    for (const agent of cfg.crew) {
+        providers.add(String(agent.provider).toLowerCase());
+    }
+    return Array.from(providers);
+}
+export function listSelectableProviders(cfg) {
+    return discoverProvidersFromConfig(cfg);
+}
+function resolveApiKey(varName) {
+    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?.[varName];
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/agents/index.d.ts

@@ -1,6 +1,6 @@
 import { AxAgent, AxAI } from "@ax-llm/ax";
 import type { AxSignature, AxAgentic, AxFunction, AxProgramForwardOptions, AxProgramStreamingForwardOptions, AxGenStreamingOut } from "@ax-llm/ax";
-import type { StateInstance, FunctionRegistryType, UsageCost, CrewConfigInput, MCPTransportConfig } from "../types.js";
+import type { StateInstance, FunctionRegistryType, UsageCost, AxCrewConfig, MCPTransportConfig } from "../types.js";
 declare class StatefulAxAgent extends AxAgent<any, any> {
     state: StateInstance;
     axai: any;
@@ -25,11 +25,37 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
     streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
     getLastUsageCost(): UsageCost | null;
     getAccumulatedCosts(): UsageCost | null;
+    /**
+     * Get the current metrics snapshot for this agent.
+     * Includes request counts, error rates, token usage, estimated USD cost, and function call stats.
+     *
+     * @returns A metrics snapshot scoped to this agent within its crew.
+     */
     getMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    /**
+     * Reset all tracked metrics for this agent (does not affect other agents).
+     * Call this to start fresh measurement windows for the agent.
+     */
     resetMetrics(): void;
 }
 /**
- * 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
  */
 declare class AxCrew {
     private crewConfig;
@@ -39,11 +65,11 @@ declare class AxCrew {
     state: StateInstance;
     /**
      * 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, functionsRegistry?: FunctionRegistryType, crewId?: string);
+    constructor(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, crewId?: string);
     /**
      * Factory function for creating an agent.
      * @param {string} agentName - The name of the agent to create.
@@ -70,10 +96,21 @@ declare class AxCrew {
      */
     destroy(): void;
     /**
-     * Resets all cost tracking for the crew
+     * Resets all cost and usage tracking for the entire crew.
+     * Also calls each agent's `resetUsage` (if available) and clears crew-level metrics.
      */
     resetCosts(): void;
+    /**
+     * Get an aggregate metrics snapshot for the entire crew.
+     * Sums requests, errors, tokens, and estimated cost across all agents in the crew.
+     *
+     * @returns Crew-level metrics snapshot.
+     */
     getCrewMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    /**
+     * Reset all tracked metrics for the entire crew.
+     * Use to clear totals before a new measurement period.
+     */
     resetCrewMetrics(): void;
 }
 export { AxCrew };