Usage and AI Consumption Tracking

Overview

The MECLABS AI platform tracks AI token consumption across all interactions to enable accurate billing, usage monitoring, and resource management. The system uses OpenMeter for real-time metering and converts raw token usage into MECLABS Credits (MLC) for billing purposes.

Core Components

1. Usage Tracking Module (server/core/usage.ts)

The primary module responsible for tracking AI token consumption:

• Integration: OpenMeter SDK for event ingestion
• Attribution: Tracks usage at organization, team, and user levels
• Provider Support: OpenAI, Anthropic Claude, Google Vertex AI models
• Real-time Processing: Asynchronous event ingestion with error handling

2. MLC Credit System

Billing Unit: 1 MLC = $0.01 raw compute cost

Pricing Model:

• Top-up Rate: $0.0135 per MLC (35% markup)
• Credit Expiry: 90 days for all credits (plans, Customer Kits, top-ups)
• Overage: Draws from pooled credits at standard $0.0135/MLC rate

Usage Attribution Hierarchy

The system determines subject attribution in the following order:

1. Organization Level (org:organizationId): Primary billing entity
2. Team Level (team:teamId): Secondary attribution when no organization
3. User Level (user:userId): Individual attribution
4. Anonymous (user:anonymous): Fallback for unauthenticated usage

Token Tracking Implementation

Event Structure

Each AI interaction generates two OpenMeter events:

{
  type: "prompt",
  subject: "org:org-123",  // or team:team-123 or user:user-123
  data: {
    provider: "openai",
    model: "gpt-4o",
    organization_id: "org-123",
    widget_id: "cfd-456",
    team_id: "team-789",
    user_id: "user-000",
    type: "input" | "output",
    tokens: 1000
  }
}

Integration Points

1. Chat API (server/api/chat.ts): Primary integration point

   • Tracks tokens on stream completion
   • Captures provider, model, and attribution metadata
   • Handles both input (prompt) and output (completion) tokens

2. Widget Context: CFD (Consumer Facing Device) interactions include:

   • widgetId: Identifies the specific embedded widget
   • organizationId: Parent organization for billing
   • teamId: Team-level attribution
   • userId: Individual user tracking

Plan Inclusions and Limits

Platform Plans

Plan	Monthly Price	Annual Price	Pooled Credits (MLC)	Org Members	Customer Kits
Build	$585	$495/mo ($5,940/yr)	6,000	5	0
Sell	$1,170	$995/mo ($11,940/yr)	18,000	12	10
Scale	$3,525	$2,995/mo ($35,940/yr)	75,000	30	45

Customer Kits

• Price: $20/month per Kit
• Includes: 1 login + 1,000 MLC credits
• Purpose: Re-sellable external seats for ADS deployment
• Economics: ~45% gross margin for MECLABS

Add-ons

• Org Seat: $80/seat/month (draws from pooled credits)
• Credit Top-ups: $0.0135/MLC (90-day expiry)
• Customer Kit: $20/kit/month (includes 1,000 MLC)

Model Cost Examples

Per 1M tokens at $0.0135 flat rate:

Model	Raw Cost	MLC Burned	Customer Pays	Effective Markup
Gemini 1.5 Flash-Lite	$0.375	38	$0.51	35%
GPT-4o mini	$0.75	75	$1.01	35%
GPT-4o	$12.50	1,250	$16.88	35%
Claude 3 Opus	$90.00	9,000	$121.50	35%

Error Handling

The tracking system implements graceful error handling:

1. Validation: Ensures required fields (provider, model, tokens) are present
2. Async Processing: Non-blocking event ingestion
3. Error Logging: Captures and logs failed tracking attempts
4. Fallback: Continues service operation even if tracking fails

Testing Coverage

Comprehensive test suite (server/core/usage.test.ts) validates:

• Field validation and error handling
• Attribution hierarchy logic
• Event structure and metadata
• OpenMeter integration (integration tests)
• Graceful failure scenarios

Future Enhancements

Planned Features

1. Usage Dashboard: Real-time credit consumption visualization
2. Alerts: Threshold notifications for credit depletion
3. Analytics: Usage patterns and model preference insights
4. Bulk Operations: Batch event ingestion for efficiency
5. Credit Rollover: Configurable credit expiry policies

API Endpoints (To Be Implemented)

• GET /api/usage/current: Current period consumption
• GET /api/usage/history: Historical usage data
• GET /api/usage/credits: Available credit balance
• POST /api/usage/top-up: Add credits to account

Technical Architecture

Dependencies

• OpenMeter SDK (@openmeter/sdk): Usage metering platform
• Environment Config: OPENMETER_API_TOKEN for authentication
• Firebase Auth: Token verification for user attribution

Data Flow

1. User initiates chat interaction
2. AI model processes request
3. Token usage captured in onFinish callback
4. Usage events sent to OpenMeter
5. OpenMeter aggregates for billing
6. Stripe integration for payment processing

Best Practices

Implementation Guidelines

1. Always track both input and output tokens separately for accurate billing
2. Include complete attribution metadata for proper cost allocation
3. Handle tracking failures gracefully without disrupting service
4. Test with multiple provider/model combinations to ensure compatibility
5. Monitor credit expiry to prevent unexpected service interruptions

Security Considerations

• Never expose raw API tokens in tracking events
• Validate widget ownership before attribution
• Implement rate limiting to prevent abuse
• Audit usage patterns for anomaly detection

Partner Economics

Customer Kit Resale Model

• Partner Cost: $20/Kit/month
• Suggested Resale: $49/month
• Partner Margin: ~59% gross margin
• Value Add: Support, onboarding, premium content

Lifetime Commission Structure

• Certified Partners: 40% lifetime commission on referred revenue
• Attribution: Tracked via partner metadata in usage events
• Reporting: Monthly partner revenue reports