✨ feat(analytics): Build complete usage analytics dashboard and API

Summary

Following the implementation of basic usage snapshot querying (#128), this issue tracks the full analytics capability that would make zae-limiter stand out as a comprehensive rate limiting solution with built-in observability.

Background

The basic get_usage_snapshots() and get_usage_summary() APIs are now implemented, providing:

• Raw snapshot queries with filtering
• Basic aggregation (sum, average)
• Both entity-centric and resource-centric views

However, a complete analytics solution requires additional capabilities to make usage data actionable.

Proposed Features

1. Time-Series Aggregation API

# Get usage trends over time
trends = await limiter.get_usage_trends(
    entity_id="user-123",
    resource="gpt-4",
    window="hourly",  # or "daily"
    periods=24,  # last 24 hours/days
    metrics=["sum", "avg", "max", "p95"]
)

2. Capacity Forecasting

# Predict when limits will be exhausted
forecast = await limiter.forecast_capacity(
    entity_id="user-123",
    resource="gpt-4",
    hours_ahead=24
)
# Returns: estimated exhaustion time, recommended limit increase

3. Anomaly Detection

# Detect unusual usage patterns
anomalies = await limiter.detect_anomalies(
    entity_id="user-123",
    threshold_stddev=3.0,
    window="hourly"
)

4. Cost Attribution (for LLM workloads)

# Calculate costs per entity/resource
costs = await limiter.get_cost_attribution(
    entity_id="project-abc",
    start_time="2024-01-01",
    end_time="2024-01-31",
    price_per_token={"gpt-4": 0.00003, "gpt-4o": 0.000005}
)

5. CLI Dashboard

# Interactive TUI dashboard
zae-limiter dashboard --entity user-123

# Export reports
zae-limiter usage export --format csv --output report.csv
zae-limiter usage export --format json --output report.json

6. CloudWatch Integration

• Pre-built CloudWatch dashboard template
• Custom metrics from aggregated usage
• Alarm templates for quota warnings

Marketing & Documentation

Blog Post Ideas

1. "Why Rate Limiters Should Have Built-in Analytics"

   • Problem: Most rate limiters are black boxes
   • Solution: Observable rate limiting with usage trends
   • Comparison with other solutions

2. "Cost Attribution for LLM Applications with zae-limiter"

   • Track token consumption per user/project
   • Forecast costs before they spiral
   • Integration with billing systems

3. "From Reactive to Proactive: Rate Limiting with Forecasting"

   • Move beyond "limit exceeded" errors
   • Warn users before they hit limits
   • Auto-scaling based on usage patterns

Competitive Differentiators

Feature	zae-limiter	Redis-based	In-memory
Usage History	✅ 90 days	❌ None	❌ None
Time-series	✅ Hourly/Daily	❌	❌
Cost Attribution	✅	❌	❌
Forecasting	✅	❌	❌
Anomaly Detection	✅	❌	❌
Zero Infrastructure	✅ Serverless	❌ Redis cluster	✅

Implementation Notes

• Build on top of existing UsageSnapshot infrastructure
• Consider adding "monthly" window type for longer retention
• May need additional GSIs for time-range queries across entities
• Consider Pandas/NumPy for statistical calculations (optional dependency)

Related

• Closes after #128 is merged
• Related to observability goals in milestone planning

/cc @sodre

Start with the existing UsageSnapshot infrastructure and the get_usage_snapshots() and get_usage_summary() APIs described in #128. Before implementation, narrow the proposal to a defined capability and identify its API, storage/query, CLI, or CloudWatch scope. Done should be an agreed, tested subset rather than all forecasting, anomaly detection, cost attribution, dashboard, and export features.