codex-meter 0.3.0__py3-none-any.whl

codex_meter/config.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import datetime as dt
+import tomllib
+from pathlib import Path
+
+from codex_meter.models import RuntimeOptions
+from codex_meter.pricing import normalize_service_tier
+from codex_meter.timeutil import load_timezone, local_timezone, parse_datetime
+
+DEFAULT_SESSION_ROOT = Path.home() / ".codex" / "sessions"
+DEFAULT_STATE_DB = Path.home() / ".codex" / "state_5.sqlite"
+DEFAULT_CODEX_CONFIG = Path.home() / ".codex" / "config.toml"
+USER_CONFIG = Path.home() / ".config" / "codex-meter" / "config.toml"
+LOCAL_CONFIG = Path(".codex-meter.toml")
+
+
+def load_config(explicit_path: Path | None = None) -> dict:
+    paths = [USER_CONFIG, LOCAL_CONFIG]
+    if explicit_path:
+        paths.append(explicit_path)
+    loaded: dict = {}
+    for path in paths:
+        if path is None:
+            continue
+        expanded = path.expanduser()
+        if not expanded.exists():
+            continue
+        try:
+            loaded |= tomllib.loads(expanded.read_text())
+        except (OSError, tomllib.TOMLDecodeError) as exc:
+            raise ValueError(f"Could not load config {expanded}: {exc}") from exc
+    return loaded
+
+
+def cfg(config: dict, key: str, value, default):
+    if value != default:
+        return value
+    return config.get(key, default)
+
+
+def cfg_path(config: dict, key: str, value: Path | None, default: Path) -> Path:
+    if value is not None:
+        return Path(value).expanduser()
+    return Path(config.get(key, default)).expanduser()
+
+
+def cfg_optional_path(config: dict, key: str, value: Path | None) -> Path | None:
+    if value is not None:
+        return Path(value).expanduser()
+    configured = config.get(key)
+    return Path(configured).expanduser() if configured else None
+
+
+def cfg_bool(config: dict, key: str, value: bool, default: bool) -> bool:
+    if value != default:
+        return bool(value)
+    return bool(config.get(key, default))
+
+
+def validate_choice(name: str, value: str, allowed: set[str]) -> str:
+    if value not in allowed:
+        choices = ", ".join(sorted(allowed))
+        raise ValueError(f"{name} must be one of: {choices}")
+    return value
+
+
+def build_options(
+    *,
+    since: str | None = None,
+    until: str | None = None,
+    days: float | None = None,
+    timezone: str = "local",
+    session_root: Path | None = None,
+    state_db: Path | None = None,
+    codex_config: Path | None = None,
+    config: Path | None = None,
+    pricing_mode: str = "model",
+    service_tier: str = "auto",
+    unknown_service_tier: str = "current-config",
+    tier_overrides: Path | None = None,
+    rates_file: Path | None = None,
+    no_dedupe: bool = False,
+    no_parse_cache: bool = False,
+    default_model: str = "gpt-5.5",
+    show_prompts: bool = False,
+    offline: bool = True,
+    compact: bool = False,
+    width: int | None = None,
+    top_threads: int = 10,
+) -> RuntimeOptions:
+    loaded = load_config(config)
+    end = parse_datetime(until, dt.datetime.now(tz=local_timezone()))
+    if since:
+        start = parse_datetime(since)
+    elif days is not None:
+        if days <= 0:
+            raise ValueError("--days must be greater than 0")
+        start = end - dt.timedelta(days=days)
+    else:
+        default_days = float(loaded.get("default_days", 30))
+        if default_days <= 0:
+            raise ValueError("default_days must be greater than 0")
+        start = end - dt.timedelta(days=default_days)
+    if start >= end:
+        raise ValueError("--since/--start must be before --until/--end")
+
+    timezone_value = str(cfg(loaded, "timezone", timezone, "local"))
+    load_timezone(timezone_value)
+    pricing_mode_value = validate_choice(
+        "--pricing-mode",
+        str(cfg(loaded, "pricing_mode", pricing_mode, "model")),
+        {"flat", "model"},
+    )
+    service_tier_value = str(cfg(loaded, "service_tier", service_tier, "auto"))
+    if service_tier_value != "auto":
+        service_tier_value = normalize_service_tier(service_tier_value)
+    service_tier_value = validate_choice(
+        "--service-tier",
+        service_tier_value,
+        {"auto", "fast", "standard"},
+    )
+    unknown_service_tier_value = str(
+        cfg(loaded, "unknown_service_tier", unknown_service_tier, "current-config")
+    )
+    if unknown_service_tier_value != "current-config":
+        unknown_service_tier_value = normalize_service_tier(unknown_service_tier_value)
+    unknown_service_tier_value = validate_choice(
+        "--unknown-service-tier",
+        unknown_service_tier_value,
+        {"current-config", "fast", "standard"},
+    )
+    top_threads_value = int(cfg(loaded, "top_threads", top_threads, 10))
+    if top_threads_value <= 0:
+        raise ValueError("--top-threads must be greater than 0")
+    width_value = cfg(loaded, "width", width, None)
+    if width_value is not None:
+        width_value = int(width_value)
+        if width_value <= 0:
+            raise ValueError("--width must be greater than 0")
+    no_dedupe_value = cfg_bool(loaded, "no_dedupe", no_dedupe, False)
+    no_parse_cache_value = cfg_bool(loaded, "no_parse_cache", no_parse_cache, False)
+
+    return RuntimeOptions(
+        session_root=cfg_path(loaded, "session_root", session_root, DEFAULT_SESSION_ROOT),
+        state_db=cfg_path(loaded, "state_db", state_db, DEFAULT_STATE_DB),
+        config_path=cfg_path(loaded, "codex_config", codex_config, DEFAULT_CODEX_CONFIG),
+        start=start,
+        end=end,
+        timezone=timezone_value,
+        pricing_mode=pricing_mode_value,
+        service_tier=service_tier_value,
+        unknown_service_tier=unknown_service_tier_value,
+        tier_overrides=cfg_optional_path(loaded, "tier_overrides", tier_overrides),
+        rates_file=cfg_optional_path(loaded, "rates_file", rates_file),
+        dedupe=not no_dedupe_value,
+        parse_cache=not no_parse_cache_value,
+        default_model=str(cfg(loaded, "default_model", default_model, "gpt-5.5")),
+        show_prompts=cfg_bool(loaded, "show_prompts", show_prompts, False),
+        offline=cfg_bool(loaded, "offline", offline, True),
+        compact=cfg_bool(loaded, "compact", compact, False),
+        width=width_value,
+        top_threads=top_threads_value,
+    )

codex_meter/exporters.py

@@ -0,0 +1,339 @@
+"""Export formats: monthly receipts (markdown/html) and Grafana dashboard JSON."""
+
+from __future__ import annotations
+
+import datetime as dt
+import html
+import json
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+from codex_meter.models import Aggregate
+
+DEFAULT_DASHBOARD_TITLE = "Codex Meter"
+
+
+@dataclass(frozen=True)
+class ReceiptInputs:
+    month: str  # YYYY-MM
+    totals: Aggregate
+    by_model: list[Aggregate]
+    top_sessions: list[Aggregate]
+    top_projects: list[Aggregate]
+    generated_at: dt.datetime
+    tier_sources: dict[str, int] | None = None
+    insights: list[str] | None = None
+    warning_count: int = 0
+    pricing_status: str = "exact"
+    pricing_warnings: list[str] | None = None
+
+
+def month_bounds(month: str, tz: dt.tzinfo) -> tuple[dt.datetime, dt.datetime]:
+    """Parse 'YYYY-MM' into [start, end) local-tz datetimes."""
+    try:
+        year, month_num = month.split("-")
+        year_int = int(year)
+        month_int = int(month_num)
+    except ValueError as exc:
+        raise ValueError(f"Invalid --month {month!r}; expected YYYY-MM") from exc
+    if not 1 <= month_int <= 12:
+        raise ValueError(f"Month must be 1..12, got {month_int}")
+    start = dt.datetime(year_int, month_int, 1, tzinfo=tz)
+    if month_int == 12:
+        end = dt.datetime(year_int + 1, 1, 1, tzinfo=tz)
+    else:
+        end = dt.datetime(year_int, month_int + 1, 1, tzinfo=tz)
+    return start, end
+
+
+def _format_money(value: float) -> str:
+    return f"${value:,.2f}"
+
+
+def _format_credits(value: float) -> str:
+    return f"{value:,.2f}"
+
+
+def _format_int(value: int) -> str:
+    return f"{value:,}"
+
+
+def render_receipt_markdown(payload: ReceiptInputs) -> str:
+    lines: list[str] = []
+    lines.append(f"# Codex Meter Receipt — {payload.month}")
+    lines.append("")
+    lines.append(f"Generated: {payload.generated_at.isoformat()}")
+    lines.append("")
+    lines.append("## Totals")
+    lines.append("")
+    lines.append("| Metric | Value |")
+    lines.append("| --- | ---: |")
+    lines.append(f"| Credits | {_format_credits(payload.totals.costs.adjusted_credits)} |")
+    lines.append(f"| API $ | {_format_money(payload.totals.costs.api_dollars)} |")
+    cache_savings = _format_credits(payload.totals.cache_savings.adjusted_credits)
+    lines.append(
+        f"| Cache savings | {cache_savings} credits / "
+        f"{_format_money(payload.totals.cache_savings.api_dollars)} |"
+    )
+    lines.append(f"| Events | {_format_int(payload.totals.totals.events)} |")
+    lines.append(f"| Tokens | {_format_int(payload.totals.totals.total_tokens)} |")
+    lines.append(
+        f"| Input tokens | {_format_int(payload.totals.totals.input_tokens)} (cached "
+        f"{_format_int(payload.totals.totals.cached_input_tokens)}) |"
+    )
+    lines.append(f"| Output tokens | {_format_int(payload.totals.totals.output_tokens)} |")
+    lines.append(
+        f"| Reasoning tokens | {_format_int(payload.totals.totals.reasoning_output_tokens)} |"
+    )
+    if payload.tier_sources:
+        sources = ", ".join(
+            f"{key}={value:,}" for key, value in sorted(payload.tier_sources.items())
+        )
+        lines.append(f"| Tier sources | {sources} |")
+    if payload.warning_count:
+        lines.append(f"| Parser warnings | {_format_int(payload.warning_count)} |")
+    if payload.pricing_status != "exact" or payload.pricing_warnings:
+        warnings = "; ".join(payload.pricing_warnings or []) or payload.pricing_status
+        lines.append(f"| Pricing status | {payload.pricing_status}: {warnings} |")
+    lines.append("")
+    if payload.insights:
+        lines.append("## Insights")
+        lines.append("")
+        for insight in payload.insights:
+            lines.append(f"- {insight}")
+        lines.append("")
+    lines.extend(_section_table("Models", payload.by_model))
+    lines.extend(_section_table("Top sessions", payload.top_sessions))
+    lines.extend(_section_table("Top projects", payload.top_projects))
+    return "\n".join(lines) + "\n"
+
+
+def _section_table(title: str, rows: Iterable[Aggregate]) -> list[str]:
+    rendered = list(rows)
+    if not rendered:
+        return [f"## {title}", "", "_No data for this month._", ""]
+    lines: list[str] = [f"## {title}", ""]
+    lines.append("| Label | Credits | API $ | Events | Tokens |")
+    lines.append("| --- | ---: | ---: | ---: | ---: |")
+    for row in rendered:
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    row.label.replace("|", "\\|"),
+                    _format_credits(row.costs.adjusted_credits),
+                    _format_money(row.costs.api_dollars),
+                    _format_int(row.totals.events),
+                    _format_int(row.totals.total_tokens),
+                ]
+            )
+            + " |"
+        )
+    lines.append("")
+    return lines
+
+
+def render_receipt_html(payload: ReceiptInputs) -> str:
+    sections: list[str] = []
+    sections.append(f"<h1>Codex Meter Receipt — {html.escape(payload.month)}</h1>")
+    sections.append(f"<p><em>Generated: {payload.generated_at.isoformat()}</em></p>")
+    sections.append("<h2>Totals</h2>")
+    sections.append(
+        "<table><thead><tr><th>Metric</th><th>Value</th></tr></thead><tbody>"
+        + "".join(
+            f"<tr><td>{name}</td><td>{value}</td></tr>"
+            for name, value in (
+                ("Credits", _format_credits(payload.totals.costs.adjusted_credits)),
+                ("API $", _format_money(payload.totals.costs.api_dollars)),
+                (
+                    "Cache savings",
+                    f"{_format_credits(payload.totals.cache_savings.adjusted_credits)} credits / "
+                    f"{_format_money(payload.totals.cache_savings.api_dollars)}",
+                ),
+                ("Events", _format_int(payload.totals.totals.events)),
+                ("Tokens", _format_int(payload.totals.totals.total_tokens)),
+                ("Input tokens", _format_int(payload.totals.totals.input_tokens)),
+                ("Cached input", _format_int(payload.totals.totals.cached_input_tokens)),
+                ("Output tokens", _format_int(payload.totals.totals.output_tokens)),
+                ("Reasoning tokens", _format_int(payload.totals.totals.reasoning_output_tokens)),
+                (
+                    "Tier sources",
+                    ", ".join(
+                        f"{key}={value:,}"
+                        for key, value in sorted((payload.tier_sources or {}).items())
+                    )
+                    or "—",
+                ),
+                ("Parser warnings", _format_int(payload.warning_count)),
+                (
+                    "Pricing status",
+                    (f"{payload.pricing_status}: {'; '.join(payload.pricing_warnings or [])}")
+                    if payload.pricing_status != "exact" or payload.pricing_warnings
+                    else "exact",
+                ),
+            )
+        )
+        + "</tbody></table>"
+    )
+    if payload.insights:
+        sections.append(
+            "<h2>Insights</h2><ul>"
+            + "".join(f"<li>{html.escape(item)}</li>" for item in payload.insights)
+            + "</ul>"
+        )
+    sections.append(_html_section("Models", payload.by_model))
+    sections.append(_html_section("Top sessions", payload.top_sessions))
+    sections.append(_html_section("Top projects", payload.top_projects))
+    body = "\n".join(sections)
+    return (
+        '<!doctype html><html><head><meta charset="utf-8">'
+        f"<title>Codex Meter Receipt — {html.escape(payload.month)}</title>"
+        "<style>"
+        "body{font-family:system-ui,sans-serif;max-width:920px;margin:2rem auto;padding:0 1rem;}"
+        "table{border-collapse:collapse;width:100%;margin-bottom:1.5rem;}"
+        "th,td{border:1px solid #ddd;padding:.4rem .6rem;}"
+        "th{background:#f5f5f5;text-align:left;}"
+        "td:last-child,th:last-child{text-align:right;}"
+        "</style></head><body>"
+        f"{body}"
+        "</body></html>"
+    )
+
+
+def _html_section(title: str, rows: Iterable[Aggregate]) -> str:
+    rendered = list(rows)
+    if not rendered:
+        return f"<h2>{html.escape(title)}</h2><p><em>No data for this month.</em></p>"
+    body = "".join(
+        "<tr>"
+        f"<td>{html.escape(row.label)}</td>"
+        f"<td>{_format_credits(row.costs.adjusted_credits)}</td>"
+        f"<td>{_format_money(row.costs.api_dollars)}</td>"
+        f"<td>{_format_int(row.totals.events)}</td>"
+        f"<td>{_format_int(row.totals.total_tokens)}</td>"
+        "</tr>"
+        for row in rendered
+    )
+    return (
+        f"<h2>{html.escape(title)}</h2>"
+        "<table><thead><tr>"
+        "<th>Label</th><th>Credits</th><th>API $</th><th>Events</th><th>Tokens</th>"
+        "</tr></thead><tbody>"
+        f"{body}"
+        "</tbody></table>"
+    )
+
+
+def grafana_dashboard(title: str = DEFAULT_DASHBOARD_TITLE, datasource: str = "Prometheus") -> dict:
+    """Generate a Grafana dashboard JSON tied to codex-meter Prometheus metrics."""
+    return {
+        "annotations": {"list": []},
+        "editable": True,
+        "schemaVersion": 39,
+        "tags": ["codex-meter"],
+        "title": title,
+        "timezone": "",
+        "time": {"from": "now-24h", "to": "now"},
+        "refresh": "30s",
+        "panels": [
+            _stat_panel(
+                id_=1,
+                title="Credits used (current 5h)",
+                expr="codex_meter_credits_used",
+                unit="none",
+                datasource=datasource,
+                grid={"h": 5, "w": 6, "x": 0, "y": 0},
+            ),
+            _stat_panel(
+                id_=2,
+                title="Burn rate (credits/hour)",
+                expr="codex_meter_burn_per_hour",
+                unit="none",
+                datasource=datasource,
+                grid={"h": 5, "w": 6, "x": 6, "y": 0},
+            ),
+            _gauge_panel(
+                id_=3,
+                title="Primary window %",
+                expr='codex_meter_window_used_percent{window="primary"}',
+                datasource=datasource,
+                grid={"h": 5, "w": 6, "x": 12, "y": 0},
+            ),
+            _gauge_panel(
+                id_=4,
+                title="Secondary window %",
+                expr='codex_meter_window_used_percent{window="secondary"}',
+                datasource=datasource,
+                grid={"h": 5, "w": 6, "x": 18, "y": 0},
+            ),
+            _timeseries_panel(
+                id_=5,
+                title="Tokens by model / tier / kind",
+                expr="sum by (model, tier, kind) (codex_meter_tokens_total)",
+                datasource=datasource,
+                grid={"h": 10, "w": 24, "x": 0, "y": 5},
+            ),
+        ],
+    }
+
+
+def _stat_panel(
+    *,
+    id_: int,
+    title: str,
+    expr: str,
+    unit: str,
+    datasource: str,
+    grid: dict,
+) -> dict:
+    return {
+        "id": id_,
+        "type": "stat",
+        "title": title,
+        "gridPos": grid,
+        "datasource": datasource,
+        "fieldConfig": {"defaults": {"unit": unit, "decimals": 2}},
+        "targets": [{"expr": expr, "refId": "A"}],
+    }
+
+
+def _gauge_panel(*, id_: int, title: str, expr: str, datasource: str, grid: dict) -> dict:
+    return {
+        "id": id_,
+        "type": "gauge",
+        "title": title,
+        "gridPos": grid,
+        "datasource": datasource,
+        "fieldConfig": {
+            "defaults": {
+                "unit": "percent",
+                "min": 0,
+                "max": 100,
+                "thresholds": {
+                    "mode": "absolute",
+                    "steps": [
+                        {"value": 0, "color": "green"},
+                        {"value": 80, "color": "orange"},
+                        {"value": 100, "color": "red"},
+                    ],
+                },
+            }
+        },
+        "targets": [{"expr": expr, "refId": "A"}],
+    }
+
+
+def _timeseries_panel(*, id_: int, title: str, expr: str, datasource: str, grid: dict) -> dict:
+    return {
+        "id": id_,
+        "type": "timeseries",
+        "title": title,
+        "gridPos": grid,
+        "datasource": datasource,
+        "fieldConfig": {"defaults": {"unit": "none"}},
+        "targets": [{"expr": expr, "refId": "A"}],
+    }
+
+
+def render_grafana_dashboard(title: str = DEFAULT_DASHBOARD_TITLE) -> str:
+    return json.dumps(grafana_dashboard(title=title), indent=2) + "\n"

codex_meter/forecasts.py

@@ -0,0 +1,92 @@
+"""Forecast helpers: linear and EWMA projection, confidence band.
+
+Pure functions over a list of per-day numeric samples (credits, dollars, tokens —
+unit-agnostic). I/O lives in the CLI layer.
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import dataclass
+
+DEFAULT_EWMA_ALPHA = 0.3
+
+
+@dataclass(frozen=True)
+class Projection:
+    unit: str
+    days_analyzed: int
+    daily_mean: float
+    daily_stdev: float
+    days_remaining: int
+    linear_total: float
+    ewma_total: float
+    linear_low: float
+    linear_high: float
+    cap: float | None
+    days_to_cap: float | None
+
+
+def daily_mean(daily_values: list[float]) -> float:
+    if not daily_values:
+        return 0.0
+    return statistics.fmean(daily_values)
+
+
+def daily_stdev(daily_values: list[float]) -> float:
+    if len(daily_values) < 2:
+        return 0.0
+    return statistics.pstdev(daily_values)
+
+
+def ewma(daily_values: list[float], alpha: float = DEFAULT_EWMA_ALPHA) -> float:
+    """Exponentially-weighted moving average. Newer days weighted more heavily."""
+    if not daily_values:
+        return 0.0
+    if not 0 < alpha <= 1:
+        raise ValueError("ewma alpha must be in (0, 1]")
+    smoothed = daily_values[0]
+    for value in daily_values[1:]:
+        smoothed = alpha * value + (1 - alpha) * smoothed
+    return smoothed
+
+
+def project(
+    daily_values: list[float],
+    days_remaining: int,
+    *,
+    unit: str = "credits",
+    cap: float | None = None,
+    alpha: float = DEFAULT_EWMA_ALPHA,
+) -> Projection:
+    """Project the rolling-sum total `days_remaining` days into the future.
+
+    `linear_total` uses the simple mean; `ewma_total` uses an exponentially
+    weighted mean that reacts faster to recent acceleration.
+    """
+    if days_remaining < 0:
+        raise ValueError("days_remaining must be non-negative")
+    mean = daily_mean(daily_values)
+    sigma = daily_stdev(daily_values)
+    ewma_rate = ewma(daily_values, alpha)
+    linear_total = mean * days_remaining
+    ewma_total = ewma_rate * days_remaining
+    # 1σ band scales with sqrt(N) under iid assumption.
+    band = sigma * math.sqrt(days_remaining) if days_remaining > 0 else 0.0
+    days_to_cap: float | None = None
+    if cap is not None and mean > 0:
+        days_to_cap = max(0.0, cap / mean)
+    return Projection(
+        unit=unit,
+        days_analyzed=len(daily_values),
+        daily_mean=mean,
+        daily_stdev=sigma,
+        days_remaining=days_remaining,
+        linear_total=linear_total,
+        ewma_total=ewma_total,
+        linear_low=max(0.0, linear_total - band),
+        linear_high=linear_total + band,
+        cap=cap,
+        days_to_cap=days_to_cap,
+    )

codex_meter/humanize.py

@@ -0,0 +1,38 @@
+"""Small humanization helpers — formatting and redaction."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+REDACTION_LIMIT = 72
+
+
+def format_int(value: int) -> str:
+    return f"{value:,}"
+
+
+def compact_number(value: float, prefix: str = "") -> str:
+    sign = "-" if value < 0 else ""
+    amount = abs(float(value))
+    for threshold, suffix in ((1_000_000_000, "B"), (1_000_000, "M"), (1_000, "K")):
+        if amount >= threshold:
+            return f"{sign}{prefix}{amount / threshold:.3g}{suffix}"
+    if amount.is_integer():
+        return f"{sign}{prefix}{int(amount):,}"
+    return f"{sign}{prefix}{amount:,.2f}"
+
+
+def redact(text: str, show: bool, limit: int = REDACTION_LIMIT) -> str:
+    """Collapse whitespace; truncate with ellipsis when `show` is False."""
+    clean = " ".join(str(text).split())
+    if show or not clean or len(clean) <= limit:
+        return clean
+    return clean[: limit - 3] + "..."
+
+
+def short_table_label(text: str) -> str:
+    """Prefer scannable labels for dense terminal tables."""
+    clean = " ".join(str(text).split())
+    if clean.startswith(("/", "~")):
+        return Path(clean).name or clean
+    return clean