src.cost_tracking.token_tracker module

Token-based Cost Tracking for Marcus AI Usage.

Tracks real-time AI token consumption, spend rates, and project costs based on actual usage rather than naive hourly estimates.

class src.cost_tracking.token_tracker.TokenTracker

Bases: object

Tracks AI token usage per project with real-time cost monitoring.

Features: - Per-project token tracking - Real-time spend rate calculation - Cost projections based on current usage - Token usage history and analytics

__init__(cost_per_1k_tokens=0.03)

Initialize token tracker.

Parameters:

cost_per_1k_tokens (float) – Cost per 1000 tokens (default $0.03 for Claude)

load_historical_data()

Load historical token usage data.

Return type:

None

save_data()

Persist token usage data.

Return type:

None

async track_tokens(project_id, input_tokens, output_tokens, model='claude-3-sonnet', metadata=None)

Track token usage for a project.

Parameters:

• project_id (str) – Project identifier

• input_tokens (int) – Number of input tokens

• output_tokens (int) – Number of output tokens

• model (str) – AI model used

• metadata (Optional[Dict[str, Any]]) – Additional context (task_id, agent_id, etc.)

Returns:

Dict with usage stats and cost info

Return type:

Dict[str, Any]

get_project_stats(project_id)

Get comprehensive stats for a project.

Parameters:

project_id (str) – Project identifier

Returns:

Dict containing: - total_tokens: Total tokens used - total_cost: Total cost incurred - current_spend_rate: Tokens/hour over last 5 minutes - average_spend_rate: Overall tokens/hour - projected_cost: Estimated total cost at current rate - session_duration: Time since first token

Return type:

Dict[str, Any]

get_all_projects_summary()

Get summary of all tracked projects.

Return type:

Dict[str, Any]

async start_monitoring()

Start background monitoring task.

Return type:

None

async stop_monitoring()

Stop background monitoring.

Return type:

None