cortex-rs-stats 0.2.0

# relay-stats

[![license](https://img.shields.io/badge/license-MIT-green)](../../LICENSE)

Usage and cost dashboard from Anthropic/OpenAI org API or local log scraper.

## Overview

relay-stats fetches rolling cost and token usage data from provider APIs (Anthropic, OpenAI) if admin keys are configured, with fallback to scraping local `~/.claude/` session files. It computes per-model costs using cortex.yaml pricing and calculates routing savings by comparing chosen model cost against baseline model cost.

## Usage

Add as a dependency:

```toml
[dependencies]
relay-stats = { path = "../relay-stats" }
relay-core = { path = "../relay-core" }
tokio = { version = "1" }
```

Example:

```rust,no_run
use cortex_rs_stats::StatsEngine;
use cortex_rs_core::CortexConfig;
use std::path::Path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = CortexConfig::load(Path::new("/Users/me/.cortex/cortex.yaml"))?;
    let engine = StatsEngine::new(config);
    
    // Fetch 7-day summary (tries provider API, falls back to log scraper)
    let summary = engine.fetch_summary(7).await?;
    println!("Total cost: ${:.2}", summary.total_cost_usd);
    println!("Routing savings: ${:.2}", summary.routing_savings_usd);
    println!("Source: {:?}", summary.source);
    
    for model_usage in &summary.by_model {
        println!("{}: {} tokens, ${:.2}", model_usage.model, model_usage.input_tokens, model_usage.cost_usd);
    }
    
    Ok(())
}
```

## Public API

- `StatsEngine::new(config)` - initialize from CortexConfig
- `StatsEngine::fetch_summary(days)` - fetch rolling usage (async)
- `UsageSummary` - contains by_model vec, total_cost_usd, routing_savings_usd, source
- `ModelUsage` - per-model breakdown with token counts and cost
- `StatsSource` - enum: ProviderApi, LocalLogScraper, or Unavailable

## Dependencies

- `relay-core` - config, database, types
- `rusqlite` - query routing decisions for savings
- `tokio` / `reqwest` - async HTTP for provider APIs
- `chrono` - date range calculations
- `keyring` - OS keychain access for provider admin keys

## Part of Relay

relay-stats is one of six MIT-licensed pillar crates. It tracks usage alongside relay-memory (tiered storage), relay-notes (wikilinks), relay-router (task classification), and relay-miner (pattern mining). Three architecture crates (relay-mcp, relay-daemon, relay-cli) assemble all pillars into the MCP server.

See the workspace README and LICENSING.md for details.

## License

MIT. See LICENSE.