@amitdeshmukh/ax-crew 3.11.3 → 4.1.1

package/CHANGELOG.md

@@ -1,4 +1,38 @@
 # Changelog
+## [4.1.0] - 2025-08-25
+
+### Added
+- Agent persona support via `definition` with validation (>= 100 chars).
+- `prompt` alias for persona; `definition` takes precedence when both provided.
+
+### Changed
+- README updated to document `definition`/`prompt` usage with example.
+- Example `examples/mcp-agent.ts` demonstrates `prompt` in agent config.
+
+## [4.0.1] - 2025-08-24
+
+### Added
+- Dependency: `big.js` for precise accumulation of estimated costs.
+- Dev Dependency: `@types/big.js` for TypeScript support.
+
+### Changed
+- Switched crew cost reporting to metrics-based API. Use `agent.getMetrics()` and `crew.getCrewMetrics()` instead of legacy cost getters.
+- Estimated cost (`estimatedCostUSD`) is now accumulated with Big.js and reported rounded to 5 decimal places.
+- Tests updated to use metrics assertions; added dummy `ANTHROPIC_API_KEY` in test setup to avoid env failures.
+- Test agent signatures updated to new DSL (`query:string -> queryResponse:string`).
+- Aligned with new `@ax-llm/ax` `ai()` and `agent()` factory methods: enforce canonical provider slugs, pass cost tracker via `options.trackers`, and validate `apiURL` when provided.
+- Updated package versions for `@ax-llm/ax` and `@ax-llm/ax-tools`.
+
+### Deprecated
+- Legacy cost APIs (`getLastUsageCost`, `getAccumulatedCosts`, `getAggregatedCosts`) are deprecated in favor of metrics.
+
+### Removed
+- Tests no longer use `getAggregatedCosts`; replaced with metrics assertions.
+
+### Updated
+- README now documents metrics usage and 5-decimal cost rounding, de-emphasizing legacy cost APIs.
+- README Features now includes "Metrics and Cost Tracking"; examples updated to use metrics (`getMetrics`, `getCrewMetrics`).
+
 
 This Changelog format is based on [Keep a Changelog]
 (https://keepachangelog.com/en/1.0.0/), and this project 

package/README.md

@@ -1,19 +1,18 @@
 ![image](axcrew.png)
 
-# AxCrew - A Crew of AI Agents (built with AxLLM)
+### AxCrew — build a crew of AI agents with shared state (powered by AxLLM)
 
-This repo simplifies development of [AxLLM](https://axllm.dev) AI Agents by using config to instantiate agents. This means you can write a library of functions, and quickly invoke AI agents to use them using a simple configuration file.
+AxCrew lets you define a team of AI agents in config and run them together with shared state, tools, streaming, MCP, and built‑in metrics/cost tracking. Bring your own functions or use the provided registry.
 
-## Features
-- **Crew Configuration**: Define a crew of agents in a JSON file. (see [agentConfig.json](agentConfig.json) as an example)
-- **State Management**: Share state across agents in a crew, as well as with functions used by those agents.
-- **Task Execution**: Plan and execute tasks using agents in the crew.
-- **Streaming Support**: Stream agent responses in real-time for better user experience and faster feedback.
-- **Model Context Protocol (MCP)**: Support for MCP to allow agents to use MCP servers.
+### Why AxCrew
+- **Config-first crews**: Declare agents once; instantiate on demand.
+- **Shared state**: Simple key/value state all agents can read/write.
+- **Sub‑agents and tools**: Compose agents and functions cleanly.
+- **Streaming**: Real‑time token streaming for responsive UX.
+- **MCP**: Connect agents to MCP servers (STDIO, HTTP SSE, Streamable HTTP).
+- **Metrics & costs**: Per‑agent and crew snapshots, with estimated USD.
 
-## Getting Started
-
-### Installation
+### Install
 Install this package:
 ```bash
 npm install @amitdeshmukh/ax-crew
@@ -21,11 +20,22 @@ npm install @amitdeshmukh/ax-crew
 AxLLM is a peer dependency, so you will need to install it separately. 
 
 ```bash
-npm install @ax-llm/ax
+npm install @ax-llm/ax @ax-llm/ax-tools
 ```
 
-### TypeScript Support
-This package includes TypeScript declarations and provides full type safety. Here's how to use it with TypeScript:
+Requirements: Node.js >= 21.
+
+### Environment
+Set provider keys in your environment. Example `.env`:
+```bash
+GEMINI_API_KEY=...
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+```
+In each agent config, set `providerKeyName` to the env var name.
+
+### Quickstart
+This package includes TypeScript declarations and provides type safety.
 
 ```typescript
 import { AxCrew, AxCrewFunctions, FunctionRegistryType, StateInstance } from '@amitdeshmukh/ax-crew';
@@ -81,23 +91,20 @@ crew.state.set('key', 'value');
 const value: string = crew.state.get('key');
 
 // Add agents to the crew
-const agents = crew.addAgentsToCrew(['Planner']);
-const planner = agents?.get('Planner');
+await crew.addAgentsToCrew(['Planner']);
+const planner = crew.agents?.get('Planner');
 
 if (planner) {
-  // Agent usage with function overloads
-  // Direct usage - AI config from agent construction is used
   const response = await planner.forward({ task: "Plan something" });
   
   // Sub-agent usage - when used by another agent (AI is ignored and agent's own config is used)
   const subAgentResponse = await planner.forward(ai, { task: "Plan something" });
   
-  const cost = planner.getUsageCost();
-  
-  if (cost) {
-    console.log(`Total cost: $${cost.totalCost}`);
-    console.log(`Total tokens: ${cost.tokenMetrics.totalTokens}`);
-  }
+  // Metrics (per-agent and per-crew)
+  const agentMetrics = (planner as any).getMetrics?.();
+  const crewMetrics = crew.getCrewMetrics();
+  console.log('Agent metrics:', agentMetrics);
+  console.log('Crew metrics:', crewMetrics);
 }
 ```
 
@@ -109,8 +116,14 @@ Key TypeScript features:
 - Comprehensive type safety for agent operations and responses
 - Usage cost tracking with proper types
 
-### Environment Setup
-Refer to the [.env.example](.env.example) file for the required environment variables. These will need to be set in the environment where the agents are run.
+### Concepts at a glance
+- **Agent**: An LLM program with a `signature`, `provider`, `ai` model config, optional `examples`, and optional `mcpServers`.
+- **Sub‑agents**: List other agent names in `agents` to compose behaviors.
+- **Functions (tools)**: Register callable functions via a registry and reference by name in agent `functions`.
+- **State**: `crew.state.set/get/getAll()` shared across all agents.
+- **Persona**: Use `definition` (preferred) or `prompt` to set the system program. If both are present, `definition` wins.
+- **Streaming**: Use `streamingForward()` for token streams.
+- **Metrics**: Per‑agent `getMetrics()` + crew‑level `getCrewMetrics()` snapshots.
 
 ## Usage
 
@@ -174,6 +187,25 @@ Both methods support the same configuration structure and options. Choose the on
   - Modify configurations at runtime
   - Keep everything in one file for simpler projects
 
+### Agent Persona: definition and prompt
+
+- **definition**: Detailed persona/program description used as the system prompt. Recommended for precise control. Must be at least 100 characters.
+- **prompt**: An alias for `definition`. If both are provided, **definition** takes precedence.
+
+Add either field to any agent config. The chosen value becomes the Ax agent's underlying program description (system prompt).
+
+```json
+{
+  "name": "Planner",
+  "description": "Creates a plan to complete a task",
+  "prompt": "You are a meticulous planning assistant. Produce concise, executable step-by-step plans with clear justifications, constraints, and assumptions. Prefer brevity, avoid fluff, and ask for missing critical details before proceeding when necessary.",
+  "signature": "task:string -> plan:string",
+  "provider": "google-gemini",
+  "providerKeyName": "GEMINI_API_KEY",
+  "ai": { "model": "gemini-1.5-flash", "temperature": 0 }
+}
+```
+
 ### Agent Examples
 You can provide examples to guide the behavior of your agents using the `examples` field in the agent configuration. Examples help the agent understand the expected input/output format and improve its responses.
 
@@ -514,7 +546,7 @@ For MCP servers that support streamable HTTP communication:
       "mcpEndpoint": "http://localhost:3002/stream",
       "options": {
         "authorization": "Bearer ey.JhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..-1234567890.1234567890",
-        "headers": { // Custom headers to include with all HTTP requests Note: Content-Type, Accept, and Mcp-Session-Id are managed automatically
+        "headers": { 
           "X-Custom-Header": "custom-value"
         }
       }
@@ -667,76 +699,45 @@ For new streamable HTTP servers, use:
 
 ### Tracking Usage Costs
 
-The package provides precise cost tracking capabilities for monitoring API usage across individual agents and the entire crew. Costs are calculated using high-precision decimal arithmetic to ensure accuracy.
+The package provides metrics for monitoring API usage across individual agents and the entire crew. Estimated costs are accumulated precisely and rounded to 5 decimal places for reporting.
 
 ```javascript
 // After running an agent's forward method
-const response = await Planner.forward({ task: userQuery });
+await Planner.forward({ task: userQuery });
 
-// Get individual agent costs
-const agentCost = Planner.getLastUsageCost();
-console.log(agentCost);
-/* Output example:
+// Per-agent metrics
+const agentMetrics = (Planner as any).getMetrics?.();
+console.log(agentMetrics);
+/* Example:
 {
-  promptCost: "0.0003637500000",
-  completionCost: "0.0006100000000",
-  totalCost: "0.0009737500000",
-  tokenMetrics: {
-    promptTokens: 291,
-    completionTokens: 122,
-    totalTokens: 413
-  }
+  provider: "anthropic",
+  model: "claude-3-haiku-20240307",
+  requests: { totalRequests, totalErrors, errorRate, totalStreamingRequests, durationMsSum, durationCount },
+  tokens: { promptTokens, completionTokens, totalTokens },
+  estimatedCostUSD: 0.00091, // rounded to 5 decimals
+  functions: { totalFunctionCalls, totalFunctionLatencyMs }
 }
 */
 
-// Get cumulative costs for the agent
-const cumulativeCost = Planner.getAccumulatedCosts();
-console.log(cumulativeCost);
-/* Output example:
+// Crew metrics
+const crewMetrics = crew.getCrewMetrics();
+console.log(crewMetrics);
+/* Example:
 {
-  promptCost: "0.0003637500000",
-  completionCost: "0.0006100000000",
-  totalCost: "0.0009737500000",
-  tokenMetrics: {
-    promptTokens: 291,
-    completionTokens: 122,
-    totalTokens: 413
-  }
-}
-*/
-
-// Get aggregated costs for all agents in the crew
-const crewCosts = crew.getAggregatedCosts();
-console.log(crewCosts);
-/* Output example:
-{
-  totalCost: "0.0025482500000",
-  byAgent: {
-    "Planner": { ... },
-    "Calculator": { ... },
-    "Manager": { ... }
-  },
-  aggregatedMetrics: {
-    promptTokens: 850,
-    completionTokens: 324,
-    totalTokens: 1174,
-    promptCost: "0.0010625000000",
-    completionCost: "0.0014857500000"
-  }
+  requests: { ... },
+  tokens: { promptTokens, completionTokens, totalTokens },
+  estimatedCostUSD: 0.00255, // rounded to 5 decimals
+  functions: { ... }
 }
 */
 
-// Reset cost tracking if needed
+// Reset tracked metrics
 crew.resetCosts();
 ```
 
-Cost tracking features:
-- High-precision decimal calculations using decimal.js
-- Per-agent cost breakdown
-- Aggregated crew-wide metrics
-- Token usage statistics
-- Support for different pricing tiers per model
-- Persistent cost tracking across multiple agent runs
+Notes:
+- Legacy cost APIs (`getLastUsageCost`, `getAccumulatedCosts`, `getAggregatedCosts`) are superseded by metrics methods.
+- Estimated cost values are numbers rounded to 5 decimal places.
 
 ## Changelog
 

package/dist/agents/agentConfig.d.ts

@@ -1,10 +1,9 @@
+import { AxDefaultCostTracker } from '@ax-llm/ax';
 import type { AxFunction } from '@ax-llm/ax';
-import type { AgentConfig, CrewConfigInput, FunctionRegistryType, MCPTransportConfig, MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreambleHTTPTransportConfig } from '../types.js';
-declare const AIConstructors: Record<string, any>;
-export type Provider = keyof typeof AIConstructors;
+import type { AgentConfig, CrewConfigInput, 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 MCPStreambleHTTPTransportConfig;
+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.
@@ -27,12 +26,14 @@ declare const parseCrewConfig: (input: CrewConfigInput) => {
  * 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<{
-    ai: any;
+    ai: import("@ax-llm/ax").AxAI<string>;
     name: string;
     description: string;
-    signature: string | import("@ax-llm/ax").AxSignature;
+    definition: any;
+    signature: string | import("@ax-llm/ax").AxSignature<Record<string, any>, Record<string, any>>;
     functions: AxFunction[];
     subAgentNames: string[];
     examples: Record<string, any>[];
+    tracker: AxDefaultCostTracker;
 }>;
 export { parseAgentConfig, parseCrewConfig };

package/dist/agents/agentConfig.js

@@ -1,26 +1,27 @@
 import fs from 'fs';
-// Import all the providers
-import { AxAIAnthropic, AxAIOpenAI, AxAIAzureOpenAI, AxAICohere, AxAIDeepSeek, AxAIGoogleGemini, AxAIGroq, AxAIHuggingFace, AxAIMistral, AxAIOllama, AxAITogether, AxAIReka, AxAIGrok } from '@ax-llm/ax';
-// Import the MCP client and transports
-import { AxMCPClient, AxMCPHTTPSSETransport, AxMCPStreambleHTTPTransport } from '@ax-llm/ax';
+// Import Ax factory and MCP transports (as exported by current package)
+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';
-// Define a mapping from provider names to their respective constructors
-const AIConstructors = {
-    'anthropic': AxAIAnthropic,
-    'azure-openai': AxAIAzureOpenAI,
-    'cohere': AxAICohere,
-    'deepseek': AxAIDeepSeek,
-    'google-gemini': AxAIGoogleGemini,
-    'groq': AxAIGroq,
-    'huggingFace': AxAIHuggingFace,
-    'mistral': AxAIMistral,
-    'ollama': AxAIOllama,
-    'openai': AxAIOpenAI,
-    'together': AxAITogether,
-    'reka': AxAIReka,
-    'grok': AxAIGrok
-};
+// 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;
@@ -173,11 +174,12 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         if (!agentConfigData) {
             throw new Error(`AI agent with name ${agentName} is not configured`);
         }
-        // Get the constructor for the AI agent's provider
-        const AIConstructor = AIConstructors[agentConfigData.provider];
-        if (!AIConstructor) {
-            throw new Error(`AI provider ${agentConfigData.provider} is not supported. Did you mean '${agentConfigData.provider.toLowerCase()}'?`);
+        // 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(', ')}`);
         }
+        const provider = lower;
         // If an API Key property is present, get the API key for the AI agent from the environment variables
         let apiKey = '';
         if (agentConfigData.providerKeyName) {
@@ -189,26 +191,30 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         else {
             throw new Error(`Provider key name is missing in the agent configuration`);
         }
-        // Create an instance of the AI agent and set options
-        const ai = new AIConstructor({
+        // Create a cost tracker instance and pass to ai()
+        const costTracker = new AxDefaultCostTracker((agentConfigData.options?.costTracking) || undefined);
+        // Create an instance of the AI agent via factory
+        const aiArgs = {
+            name: provider,
             apiKey,
             config: agentConfigData.ai,
             options: {
                 debug: agentConfigData.debug || false,
-                ...agentConfigData.options
+                ...agentConfigData.options,
+                // Attach default cost tracker so usage/costs are recorded by provider layer
+                trackers: [costTracker]
             }
-        });
-        // If an apiURL is provided in the agent config, set it in the AI agent
+        };
         if (agentConfigData.apiURL) {
             try {
-                // Validate apiURL format
                 new URL(agentConfigData.apiURL);
-                ai.setAPIURL(agentConfigData.apiURL);
+                aiArgs.apiURL = agentConfigData.apiURL;
             }
             catch (error) {
                 throw new Error(`Invalid apiURL provided: ${agentConfigData.apiURL}`);
             }
         }
+        const aiInstance = ai(aiArgs);
         // If an mcpServers config is provided in the agent config, convert to functions
         const mcpFunctions = await initializeMCPServers(agentConfigData);
         // Prepare functions for the AI agent
@@ -229,13 +235,15 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
         ];
         // Return AI instance and Agent parameters
         return {
-            ai,
+            ai: aiInstance,
             name: agentName,
             description: agentConfigData.description,
+            definition: agentConfigData.definition ?? agentConfigData.prompt,
             signature: agentConfigData.signature,
             functions: agentFunctions,
             subAgentNames: agentConfigData.agents || [],
             examples: agentConfigData.examples || [],
+            tracker: costTracker,
         };
     }
     catch (error) {

package/dist/agents/index.d.ts

@@ -1,26 +1,32 @@
 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 { StateFulAxAgentUsage } from "./agentUseCosts.js";
 declare class StatefulAxAgent extends AxAgent<any, any> {
     state: StateInstance;
     axai: any;
     private agentName;
+    private costTracker?;
+    private lastRecordedCostUSD;
+    private isAxAIService;
+    private isAxAIInstance;
     constructor(ai: AxAI, options: Readonly<{
         name: string;
         description: string;
+        definition?: string;
         signature: string | AxSignature;
         agents?: AxAgentic<any, any>[] | undefined;
         functions?: (AxFunction | (() => AxFunction))[] | undefined;
         examples?: Array<Record<string, any>> | undefined;
         mcpServers?: Record<string, MCPTransportConfig> | undefined;
     }>, state: StateInstance);
-    forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
-    forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions>): Promise<Record<string, any>>;
-    streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
-    streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions>): AxGenStreamingOut<any>;
+    forward(values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    forward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramForwardOptions<any>>): Promise<Record<string, any>>;
+    streamingForward(values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
+    streamingForward(ai: AxAI, values: Record<string, any>, options?: Readonly<AxProgramStreamingForwardOptions<any>>): AxGenStreamingOut<any>;
     getLastUsageCost(): UsageCost | null;
     getAccumulatedCosts(): UsageCost | null;
+    getMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetMetrics(): void;
 }
 /**
  * Represents a crew of agents with shared state functionality.
@@ -63,14 +69,12 @@ declare class AxCrew {
      * Cleans up the crew by dereferencing agents and resetting the state.
      */
     destroy(): void;
-    /**
-     * Gets aggregated costs for all agents in the crew
-     * @returns Aggregated cost information for all agents
-     */
-    getAggregatedCosts(): ReturnType<typeof StateFulAxAgentUsage.getAggregatedCosts>;
     /**
      * Resets all cost tracking for the crew
      */
     resetCosts(): void;
+    getCrewMetrics(): import("../metrics/types.js").MetricsSnapshot;
+    resetCrewMetrics(): void;
 }
 export { AxCrew };
+export type { StatefulAxAgent };