Provider Economics

The Economics Layer makes every provider decision financially transparent. It tracks real costs, simulates alternative scenarios, computes savings attribution, and protects budgets before they break.

Core Economics Functions

Function	Purpose	File
Cost Tracking	Records actual spend per provider, model, and workspace	`economics/attribution/engine.ts`
Savings Attribution	Computes how much Layerr saved vs. baseline	`economics/attribution/engine.ts`
Budget Protection	Enforces budget caps and triggers alerts	`budget/evaluator.ts`
Simulation	What-if analysis: “What would this cost on another provider?”	`economics/simulation/engine.ts`
Insights	High-level economic insights and recommendations	`economics/insights/engine.ts`

Cost Attribution

The attribution engine (economics/attribution/engine.ts) computes:

Metric	Description
Monthly Spend	Total cost this calendar month
Provider Breakdown	Cost per provider
Category Breakdown	Cost per model category (fast, balanced, reasoning)
Fallback Cost	Additional cost incurred by fallback attempts
Premium Avoidance	Amount saved by routing to cheaper capable models
Category Efficiency	Quality per dollar by category

Savings Computation

function computeSavings(
  actualTrace: Trace,
  baselineTrace: Trace
): SavingsReport {
  return {
    tokensSaved: baselineTrace.tokensOut - actualTrace.tokensOut,
    costSavedUsd: baselineTrace.costUsd - actualTrace.costUsd,
    latencySavedMs: baselineTrace.latencyMs - actualTrace.latencyMs,
    efficiencyGain: actualTrace.qualityScore / actualTrace.costUsd
  };
}

Budget Protection

The budget evaluator (budget/evaluator.ts) enforces:

Check	Action
Pre-request budget check	Block if workspace is over budget
Soft threshold alert	Notify when 80% of budget consumed
Category tier limiting	Block premium models when budget is tight
Batch job quota	Limit batch job size based on remaining budget

Simulation Engine

The simulation engine (economics/simulation/engine.ts) answers “what if” questions:

Simulation	Description
`simulateBaselineExecution()`	Cost if routed to default baseline model
`simulateAllProfiles()`	Cost if each profile (cost/speed/quality/balanced) was used
`buildSimulationInputFromReplayTrace()`	Simulate an alternative for an existing trace
`computeBalancedBaseline()`	Baseline cost for balanced strategy

Insights Heuristics

The insights engine (economics/insights/heuristics.ts) detects economic patterns:

Heuristic	What It Detects
`detectHighFallbackProviders()`	Providers that frequently trigger costly fallbacks
`detectSlowProviders()`	Providers whose latency suggests poor value
`detectFallbackCostEscalation()`	Situations where fallback costs spiral
`detectHighFleetFallbackRate()`	Workspace-wide fallback rate trends
`detectSimulationSavings()`	Potential savings from simulation results
`detectPremiumAvoidance()`	Successful routing away from premium models

Frontend Components

Component	File	Purpose
`ProviderEconomicsOverlay`	`src/features/providers/economics/`	Provider-level cost dashboard
`EconomicComparisonInspector`	`src/features/evaluation/`	Compare costs across providers
`TraceEconomicPanel`	`src/traces/TraceEconomicPanel.tsx`	Cost analysis per trace
`BudgetProtectionPanel`	Budget UI with alerts and controls

File Reference

File	What It Does
`economics/attribution/engine.ts`	Cost tracking and savings computation
`economics/attribution/queries.ts`	SQL queries for cost aggregation
`economics/simulation/engine.ts`	What-if cost simulation
`economics/insights/engine.ts`	Economic insight generation
`economics/insights/heuristics.ts`	Pattern detection heuristics
`budget/evaluator.ts`	Budget enforcement and impact evaluation
`src/features/providers/economics/`	Frontend economics dashboards

Integration

Execution Engine → provides token counts and actual costs
Replay → provides traces for savings computation
Simulation → simulates alternatives using provider pricing metadata
Workspace Profiles → reads budget constraints
Quality Evaluation → correlates cost with quality for efficiency metrics