codex-meter 0.3.0__py3-none-any.whl

codex_meter/insights.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+from codex_meter.aggregation import aggregate_daily, aggregate_projects, aggregate_total
+from codex_meter.models import CostTotals, LoadResult, RuntimeOptions
+from codex_meter.pricing import RateCard
+
+
+@dataclass(frozen=True)
+class Insight:
+    severity: str
+    title: str
+    detail: str
+    action: str
+
+
+def build_insights(
+    result: LoadResult,
+    options: RuntimeOptions,
+    rate_card: RateCard | None = None,
+) -> list[Insight]:
+    card = rate_card or RateCard.load(options.rates_file, options.pricing_mode)
+    insights: list[Insight] = []
+    total = aggregate_total(result, options, rate_card=card)
+
+    if total.totals.input_tokens:
+        cache_ratio = total.totals.cached_input_tokens / total.totals.input_tokens
+        savings = cache_savings(result, card)
+        if total.totals.cached_input_tokens:
+            insights.append(
+                Insight(
+                    severity="info",
+                    title="High cache reuse" if cache_ratio >= 0.5 else "Low cache reuse",
+                    detail=(
+                        f"{cache_ratio:.1%} of input tokens were served from cache, "
+                        f"saving about {savings.adjusted_credits:,.2f} credits and "
+                        f"${savings.api_dollars:,.2f}."
+                    ),
+                    action="Keep prompts and file context stable to preserve cache hits.",
+                )
+            )
+
+    if result.events:
+        assumed = result.tier_sources.get("assumed", 0) + result.tier_sources.get(
+            "current-config", 0
+        )
+        if assumed / len(result.events) >= 0.8:
+            insights.append(
+                Insight(
+                    severity="warn",
+                    title="Service tier inferred",
+                    detail=(
+                        f"{assumed:,} of {len(result.events):,} events used an inferred tier "
+                        "rather than a logged tier."
+                    ),
+                    action=(
+                        "Pin known usage with --service-tier or --tier-overrides for sharper costs."
+                    ),
+                )
+            )
+
+    projects = aggregate_projects(result, options, rate_card=card)
+    if projects and total.costs.adjusted_credits:
+        top = projects[0]
+        share = float(top.costs.adjusted_credits / total.costs.adjusted_credits)
+        if share >= 0.4:
+            insights.append(
+                Insight(
+                    severity="info",
+                    title="Spend concentrated in one project",
+                    detail=(
+                        f"{top.label} accounts for {share:.1%} of credits "
+                        f"({top.costs.adjusted_credits:,.2f})."
+                    ),
+                    action="Run codex-meter project --top 5 to inspect the largest workspaces.",
+                )
+            )
+
+    daily = aggregate_daily(result, options, rate_card=card)
+    if len(daily) >= 3:
+        midpoint = len(daily) // 2
+        earlier = sum(row.costs.adjusted_credits for row in daily[:midpoint]) / max(midpoint, 1)
+        later_count = len(daily) - midpoint
+        later = sum(row.costs.adjusted_credits for row in daily[midpoint:]) / max(later_count, 1)
+        if earlier and later / earlier >= 2:
+            insights.append(
+                Insight(
+                    severity="warn",
+                    title="Daily usage is accelerating",
+                    detail=f"Recent daily credits are {later / earlier:.1f}x the earlier average.",
+                    action="Run codex-meter forecast --cap <plan-credits> to check depletion risk.",
+                )
+            )
+
+    return insights
+
+
+def cache_savings(result: LoadResult, rate_card: RateCard) -> CostTotals:
+    savings = CostTotals()
+    for event in result.events:
+        savings.add(rate_card.cache_savings_for(event.usage, event.model, event.service_tier))
+    return savings
+
+
+def insights_payload(insights: list[Insight]) -> dict:
+    return {"insights": [asdict(item) for item in insights]}
+
+
+def render_insights_markdown(insights: list[Insight]) -> str:
+    lines = [
+        "| Severity | Insight | Detail | Action |",
+        "| --- | --- | --- | --- |",
+    ]
+    for insight in insights:
+        lines.append(
+            "| "
+            + " | ".join(
+                [
+                    insight.severity,
+                    _escape_markdown(insight.title),
+                    _escape_markdown(insight.detail),
+                    _escape_markdown(insight.action),
+                ]
+            )
+            + " |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _escape_markdown(value: str) -> str:
+    return value.replace("|", "\\|")

codex_meter/intervals.py

@@ -0,0 +1,129 @@
+"""Natural-language window expressions: 'last 7 days', 'yesterday', 'this month', etc."""
+
+from __future__ import annotations
+
+import calendar
+import datetime as dt
+import re
+from dataclasses import dataclass
+
+WINDOW_EXAMPLES = "Try: 'last 7 days', 'previous 7 days', 'this week', '2026-05-01..2026-05-12'."
+
+
+@dataclass(frozen=True)
+class Interval:
+    start: dt.datetime
+    end: dt.datetime
+    label: str
+
+
+_LAST_N_DAYS = re.compile(r"^last\s+(\d+)\s+days?$")
+_PREVIOUS_N_DAYS = re.compile(r"^previous\s+(\d+)\s+days?$")
+_LAST_N_HOURS = re.compile(r"^last\s+(\d+)\s+hours?$")
+
+
+def _start_of_day(when: dt.datetime) -> dt.datetime:
+    return when.replace(hour=0, minute=0, second=0, microsecond=0)
+
+
+def _start_of_week(when: dt.datetime) -> dt.datetime:
+    monday = when - dt.timedelta(days=when.weekday())
+    return _start_of_day(monday)
+
+
+def _start_of_month(when: dt.datetime) -> dt.datetime:
+    return _start_of_day(when.replace(day=1))
+
+
+def _end_of_month(when: dt.datetime) -> dt.datetime:
+    last_day = calendar.monthrange(when.year, when.month)[1]
+    return when.replace(day=last_day, hour=23, minute=59, second=59, microsecond=0)
+
+
+def parse_interval(expression: str, now: dt.datetime) -> Interval:
+    """Parse a window expression relative to `now`. Returns an Interval [start, end).
+
+    Supported forms (case-insensitive):
+    - "today", "yesterday"
+    - "this week", "last week", "previous week"
+    - "this month", "last month", "previous month"
+    - "last N days", "previous N days"
+    - "last N hours"
+    - ISO date "YYYY-MM-DD" (24h spanning that local day)
+    - ISO range "YYYY-MM-DD..YYYY-MM-DD" (24h spans inclusive)
+    """
+    if not expression:
+        raise ValueError("window expression must be non-empty")
+    raw = expression.strip().lower()
+
+    if raw == "today":
+        start = _start_of_day(now)
+        return Interval(start=start, end=now, label="today")
+    if raw == "yesterday":
+        start = _start_of_day(now) - dt.timedelta(days=1)
+        end = _start_of_day(now)
+        return Interval(start=start, end=end, label="yesterday")
+    if raw == "this week":
+        return Interval(start=_start_of_week(now), end=now, label="this week")
+    if raw in {"last week", "previous week"}:
+        this_week = _start_of_week(now)
+        start = this_week - dt.timedelta(days=7)
+        return Interval(start=start, end=this_week, label="last week")
+    if raw == "this month":
+        return Interval(start=_start_of_month(now), end=now, label="this month")
+    if raw in {"last month", "previous month"}:
+        this_month = _start_of_month(now)
+        prev_end = this_month
+        prev_start = (this_month - dt.timedelta(days=1)).replace(
+            day=1, hour=0, minute=0, second=0, microsecond=0
+        )
+        return Interval(start=prev_start, end=prev_end, label="last month")
+
+    match = _LAST_N_DAYS.match(raw)
+    if match:
+        days = int(match.group(1))
+        return Interval(start=now - dt.timedelta(days=days), end=now, label=raw)
+
+    match = _PREVIOUS_N_DAYS.match(raw)
+    if match:
+        days = int(match.group(1))
+        anchor = now - dt.timedelta(days=days)
+        return Interval(start=anchor - dt.timedelta(days=days), end=anchor, label=raw)
+
+    match = _LAST_N_HOURS.match(raw)
+    if match:
+        hours = int(match.group(1))
+        return Interval(start=now - dt.timedelta(hours=hours), end=now, label=raw)
+
+    if ".." in raw:
+        left, _, right = raw.partition("..")
+        return Interval(
+            start=_iso_to_dt(left, now.tzinfo, end_of_day=False),
+            end=_iso_to_dt(right, now.tzinfo, end_of_day=True),
+            label=raw,
+        )
+
+    return Interval(
+        start=_iso_to_dt(raw, now.tzinfo, end_of_day=False),
+        end=_iso_to_dt(raw, now.tzinfo, end_of_day=True),
+        label=raw,
+    )
+
+
+def _iso_to_dt(raw: str, tz: dt.tzinfo | None, *, end_of_day: bool) -> dt.datetime:
+    text = raw.strip()
+    if len(text) == 10 and text[4] == "-" and text[7] == "-":
+        text = text + (" 23:59:59" if end_of_day else " 00:00:00")
+    elif len(text) == 8 and text.isdigit():
+        head = f"{text[:4]}-{text[4:6]}-{text[6:8]}"
+        text = head + (" 23:59:59" if end_of_day else " 00:00:00")
+    try:
+        parsed = dt.datetime.fromisoformat(text)
+    except ValueError as exc:
+        raise ValueError(f"Unrecognized window expression: {raw!r}. {WINDOW_EXAMPLES}") from exc
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=tz or dt.UTC)
+    return parsed
+
+
+_MONTH_END_MIN = _end_of_month  # re-export keeps `end_of_month` discoverable

codex_meter/live.py

@@ -0,0 +1,286 @@
+"""Live TUI for codex-meter. Re-parses JSONL on each tick (cache is Phase 3)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import select
+import signal
+import sys
+import time
+from dataclasses import dataclass
+
+from rich.console import Console, RenderableType
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.progress_bar import ProgressBar
+from rich.table import Table
+from rich.text import Text
+
+from codex_meter.aggregation import aggregate_total
+from codex_meter.models import LoadResult, RuntimeOptions
+from codex_meter.parser import load_usage
+from codex_meter.pricing import RateCard
+from codex_meter.render import pricing_status, pricing_warnings
+from codex_meter.timeutil import local_timezone
+from codex_meter.windows import (
+    WindowState,
+    compute_window_state,
+    format_burn_rate,
+    format_seconds_remaining,
+)
+
+
+@dataclass(frozen=True)
+class LiveFrame:
+    now: dt.datetime
+    today_credits: float
+    today_api_dollars: float
+    week_credits: float
+    primary: WindowState
+    secondary: WindowState
+    plan_types: tuple[str, ...]
+    events_loaded: int
+    today_cache_savings: float = 0.0
+    today_sparkline: str = ""
+    refresh_ms: float = 0.0
+    pricing_status: str = "exact"
+    pricing_warnings: tuple[str, ...] = ()
+
+
+def _window_subset(events, start: dt.datetime, end: dt.datetime):
+    return [event for event in events if start <= event.timestamp < end]
+
+
+def collect_frame(options: RuntimeOptions, now: dt.datetime | None = None) -> LiveFrame:
+    """Load usage + compute one frame snapshot. Pure-ish (depends on parser + clock)."""
+    started = time.perf_counter()
+    result = load_usage(options)
+    rate_card = RateCard.load(options.rates_file, options.pricing_mode)
+    now = now or dt.datetime.now(tz=local_timezone())
+    today_start = now.replace(hour=0, minute=0, second=0, microsecond=0)
+    week_start = now - dt.timedelta(days=7)
+
+    today_events = _window_subset(result.events, today_start, now)
+    week_events = _window_subset(result.events, week_start, now)
+
+    today_result = LoadResult(
+        events=today_events,
+        duplicates=0,
+        tier_sources=result.tier_sources,
+        plan_types=result.plan_types,
+        credit_samples=[],
+        warnings=[],
+    )
+    week_result = LoadResult(
+        events=week_events,
+        duplicates=0,
+        tier_sources=result.tier_sources,
+        plan_types=result.plan_types,
+        credit_samples=[],
+        warnings=[],
+    )
+
+    today_total = aggregate_total(today_result, options, label="Today", rate_card=rate_card)
+    week_total = aggregate_total(week_result, options, label="Last 7 days", rate_card=rate_card)
+
+    primary = compute_window_state(result.credit_samples, now, "primary")
+    secondary = compute_window_state(result.credit_samples, now, "secondary")
+
+    return LiveFrame(
+        now=now,
+        today_credits=float(today_total.costs.adjusted_credits),
+        today_api_dollars=float(today_total.costs.api_dollars),
+        week_credits=float(week_total.costs.adjusted_credits),
+        primary=primary,
+        secondary=secondary,
+        plan_types=tuple(sorted(result.plan_types)),
+        events_loaded=len(result.events),
+        today_cache_savings=float(today_total.cache_savings.api_dollars),
+        today_sparkline=_sparkline(_hourly_credit_series(today_events, rate_card, now)),
+        refresh_ms=(time.perf_counter() - started) * 1000,
+        pricing_status=pricing_status(today_total),
+        pricing_warnings=tuple(pricing_warnings(today_total)),
+    )
+
+
+def _hourly_credit_series(events, rate_card: RateCard, now: dt.datetime) -> list[float]:
+    local_now = now.astimezone(local_timezone())
+    buckets = [0.0] * (local_now.hour + 1)
+    for event in events:
+        local_event = event.timestamp.astimezone(local_timezone())
+        if local_event.date() != local_now.date():
+            continue
+        costs, _, _ = rate_card.cost_for(event.usage, event.model, event.service_tier)
+        buckets[local_event.hour] += float(costs.adjusted_credits)
+    return buckets
+
+
+def _window_panel(label: str, state: WindowState, *, compact: bool = False) -> Panel:
+    grid = Table.grid(padding=(0, 1))
+    grid.add_column(no_wrap=True, justify="right", style="dim")
+    grid.add_column()
+    bar = ProgressBar(total=100, completed=state.used_percent or 0, width=14 if compact else 24)
+    grid.add_row("Used", bar)
+    grid.add_row(
+        "Percent",
+        f"{state.used_percent:.1f}%" if state.used_percent is not None else "—",
+    )
+    grid.add_row("Reset in", format_seconds_remaining(state.seconds_remaining))
+    if state.reset_at is not None:
+        local = state.reset_at.astimezone(local_timezone())
+        grid.add_row("Reset at", local.strftime("%Y-%m-%d %H:%M:%S %Z"))
+    grid.add_row("Burn rate", format_burn_rate(state.burn_rate_per_hour))
+    if state.eta_to_100 is not None:
+        eta_local = state.eta_to_100.astimezone(local_timezone())
+        grid.add_row("Hits 100% by", eta_local.strftime("%Y-%m-%d %H:%M"))
+    title = label
+    if state.window_minutes:
+        title = f"{label} ({state.window_minutes}m)"
+    border = "red" if (state.used_percent or 0) >= 80 else "cyan"
+    return Panel(grid, title=title, border_style=border)
+
+
+def _usage_panel(frame: LiveFrame) -> Panel:
+    grid = Table.grid(padding=(0, 1))
+    grid.add_column(no_wrap=True, justify="right", style="dim")
+    grid.add_column()
+    grid.add_row(
+        "Today",
+        f"{frame.today_credits:,.2f} credits  /  ${frame.today_api_dollars:,.2f}",
+    )
+    grid.add_row("Last 7d", f"{frame.week_credits:,.2f} credits")
+    grid.add_row("Events loaded", f"{frame.events_loaded:,}")
+    if frame.plan_types:
+        grid.add_row("Plan", ", ".join(frame.plan_types))
+    if frame.today_cache_savings:
+        grid.add_row("Cache saved", f"${frame.today_cache_savings:,.2f}")
+    if frame.pricing_status != "exact":
+        grid.add_row("Pricing", frame.pricing_status)
+    for warning in frame.pricing_warnings[:2]:
+        grid.add_row("Warning", warning)
+    if frame.today_sparkline:
+        grid.add_row("Today trend", frame.today_sparkline)
+    grid.add_row("Refresh", f"{frame.refresh_ms:,.0f} ms")
+    return Panel(grid, title="Usage", border_style="green")
+
+
+def render_frame(
+    frame: LiveFrame,
+    show_help: bool = False,
+    paused: bool = False,
+    width: int | None = None,
+) -> RenderableType:
+    layout = Layout()
+    layout.split_column(
+        Layout(name="header", size=3),
+        Layout(name="body"),
+    )
+    header_text = Text(
+        f"Codex Meter — {frame.now.strftime('%Y-%m-%d %H:%M:%S %Z')}    "
+        f"(q quit · ? help · r refresh · p {'resume' if paused else 'pause'})",
+        style="bold white on blue",
+    )
+    layout["header"].update(Panel(header_text, border_style="blue"))
+    body = Layout()
+    if show_help:
+        body.update(_help_panel())
+    elif (width or 120) < 110:
+        body.split_column(
+            Layout(_usage_panel(frame), name="usage", size=10),
+            Layout(_window_panel("Primary 5h", frame.primary, compact=True), name="primary"),
+            Layout(
+                _window_panel("Secondary weekly", frame.secondary, compact=True),
+                name="secondary",
+            ),
+        )
+    else:
+        body.split_row(
+            Layout(_usage_panel(frame), name="usage"),
+            Layout(_window_panel("Primary 5h", frame.primary), name="primary"),
+            Layout(_window_panel("Secondary weekly", frame.secondary), name="secondary"),
+        )
+    layout["body"].update(body)
+    return layout
+
+
+def _help_panel() -> Panel:
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold")
+    grid.add_column()
+    grid.add_row("q", "quit")
+    grid.add_row("?", "toggle this help")
+    grid.add_row("r", "refresh immediately")
+    grid.add_row("p", "pause or resume auto-refresh")
+    grid.add_row("Ctrl-C", "quit")
+    return Panel(grid, title="Live Help", border_style="blue")
+
+
+def _sparkline(values: list[float]) -> str:
+    if not values:
+        return ""
+    bars = "▁▂▃▄▅▆▇█"
+    low = min(values)
+    high = max(values)
+    if high == low:
+        return bars[0] * len(values)
+    return "".join(bars[round((value - low) / (high - low) * (len(bars) - 1))] for value in values)
+
+
+def _read_key() -> str:
+    if not sys.stdin.isatty():
+        return ""
+    readable, _, _ = select.select([sys.stdin], [], [], 0)
+    if not readable:
+        return ""
+    return sys.stdin.read(1)
+
+
+def run_live(
+    options: RuntimeOptions,
+    interval: float = 2.0,
+    console: Console | None = None,
+    max_ticks: int | None = None,
+) -> None:
+    """Start the TUI. Loops until SIGINT (or `max_ticks` for tests)."""
+    stop = {"flag": False}
+
+    def _on_signal(*_: object) -> None:
+        stop["flag"] = True
+
+    original = signal.getsignal(signal.SIGINT)
+    signal.signal(signal.SIGINT, _on_signal)
+    ticks = 0
+    show_help = False
+    paused = False
+    try:
+        target = console or Console()
+        frame = collect_frame(options)
+        width = target.size.width
+        with Live(
+            render_frame(frame, show_help=show_help, paused=paused, width=width),
+            console=target,
+            refresh_per_second=4,
+            screen=False,
+        ) as live:
+            while not stop["flag"]:
+                key = _read_key()
+                if key == "q":
+                    break
+                if key == "?":
+                    show_help = not show_help
+                if key == "p":
+                    paused = not paused
+                if key == "r" and not paused:
+                    frame = collect_frame(options)
+                time.sleep(interval)
+                ticks += 1
+                if max_ticks is not None and ticks >= max_ticks:
+                    break
+                if stop["flag"]:
+                    break
+                if not paused and not show_help:
+                    frame = collect_frame(options)
+                live.update(render_frame(frame, show_help=show_help, paused=paused, width=width))
+    finally:
+        signal.signal(signal.SIGINT, original)