codex-meter 0.3.0__py3-none-any.whl

codex_meter/windows.py

@@ -0,0 +1,153 @@
+"""Rate-limit window math. Pure functions, no I/O."""
+
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+
+from codex_meter.models import RateLimitSample
+
+BURN_RATE_LOOKBACK_HOURS = 6
+MIN_BURN_RATE_SAMPLES = 3
+
+
+@dataclass(frozen=True)
+class WindowState:
+    """Decoded state of a single rate-limit window at a moment in time."""
+
+    window: str  # "primary" or "secondary"
+    used_percent: float | None
+    window_minutes: int | None
+    reset_at: dt.datetime | None
+    seconds_remaining: int | None
+    burn_rate_per_hour: float | None  # percent points per hour
+    eta_to_100: dt.datetime | None
+    samples: int
+
+
+def _coerce_float(value: object) -> float | None:
+    try:
+        return float(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_int(value: object) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+def _epoch_to_datetime(value: object) -> dt.datetime | None:
+    seconds = _coerce_int(value)
+    if seconds is None:
+        return None
+    try:
+        return dt.datetime.fromtimestamp(seconds, tz=dt.UTC)
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+def _percent(sample: RateLimitSample, which: str) -> float | None:
+    return _coerce_float(getattr(sample, f"{which}_used_percent", None))
+
+
+def _window_minutes(sample: RateLimitSample, which: str) -> int | None:
+    return _coerce_int(getattr(sample, f"{which}_window_minutes", None))
+
+
+def _reset_at(sample: RateLimitSample, which: str) -> dt.datetime | None:
+    return _epoch_to_datetime(getattr(sample, f"{which}_resets_at", None))
+
+
+def compute_window_state(
+    samples: list[RateLimitSample], now: dt.datetime, which: str
+) -> WindowState:
+    """Compute a WindowState from raw RateLimitSamples. `which` is 'primary' or 'secondary'."""
+    if which not in {"primary", "secondary"}:
+        raise ValueError(f"window must be 'primary' or 'secondary', got {which!r}")
+    if not samples:
+        return WindowState(
+            window=which,
+            used_percent=None,
+            window_minutes=None,
+            reset_at=None,
+            seconds_remaining=None,
+            burn_rate_per_hour=None,
+            eta_to_100=None,
+            samples=0,
+        )
+
+    ordered = sorted(samples, key=lambda sample: sample.timestamp)
+    latest = ordered[-1]
+    used = _percent(latest, which)
+    window_minutes = _window_minutes(latest, which)
+    reset_at = _reset_at(latest, which)
+
+    seconds_remaining: int | None = None
+    if reset_at is not None:
+        seconds_remaining = max(0, int((reset_at - now).total_seconds()))
+
+    burn_rate = _compute_burn_rate(ordered, latest, which)
+    eta_to_100 = _project_to_full(used, burn_rate, now)
+
+    return WindowState(
+        window=which,
+        used_percent=used,
+        window_minutes=window_minutes,
+        reset_at=reset_at,
+        seconds_remaining=seconds_remaining,
+        burn_rate_per_hour=burn_rate,
+        eta_to_100=eta_to_100,
+        samples=len(ordered),
+    )
+
+
+def _compute_burn_rate(
+    ordered: list[RateLimitSample], latest: RateLimitSample, which: str
+) -> float | None:
+    """Burn rate in percent-points per hour, derived from samples within the lookback window."""
+    cutoff = latest.timestamp - dt.timedelta(hours=BURN_RATE_LOOKBACK_HOURS)
+    recent = [sample for sample in ordered if sample.timestamp >= cutoff]
+    if len(recent) < MIN_BURN_RATE_SAMPLES:
+        return None
+    first = recent[0]
+    first_pct = _percent(first, which)
+    last_pct = _percent(latest, which)
+    if first_pct is None or last_pct is None:
+        return None
+    elapsed_hours = (latest.timestamp - first.timestamp).total_seconds() / 3600.0
+    if elapsed_hours <= 0:
+        return None
+    return (last_pct - first_pct) / elapsed_hours
+
+
+def _project_to_full(
+    used: float | None, burn_rate: float | None, now: dt.datetime
+) -> dt.datetime | None:
+    if used is None or burn_rate is None or burn_rate <= 0 or used >= 100:
+        return None
+    hours_to_full = (100.0 - used) / burn_rate
+    return now + dt.timedelta(hours=hours_to_full)
+
+
+def format_seconds_remaining(seconds: int | None) -> str:
+    """Render seconds as `Xh YYm ZZs`, `Ym Ss`, or `—`."""
+    if seconds is None:
+        return "—"
+    seconds = max(0, int(seconds))
+    hours, rem = divmod(seconds, 3600)
+    minutes, secs = divmod(rem, 60)
+    if hours:
+        return f"{hours}h {minutes:02d}m {secs:02d}s"
+    if minutes:
+        return f"{minutes}m {secs:02d}s"
+    return f"{secs}s"
+
+
+def format_burn_rate(rate: float | None) -> str:
+    if rate is None:
+        return "—"
+    sign = "+" if rate >= 0 else ""
+    return f"{sign}{rate:.2f}%/h"

codex_meter-0.3.0.dist-info/METADATA

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: codex-meter
+Version: 0.3.0
+Summary: Local Codex usage intelligence for sessions, projects, models, cache, and rate-limit windows.
+Project-URL: Homepage, https://github.com/rajdeepmondaldotcom/codex-meter
+Project-URL: Repository, https://github.com/rajdeepmondaldotcom/codex-meter
+Project-URL: Issues, https://github.com/rajdeepmondaldotcom/codex-meter/issues
+Project-URL: Changelog, https://github.com/rajdeepmondaldotcom/codex-meter/blob/main/CHANGELOG.md
+Author: Rajdeep Mondal
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,codex,credits,openai,tokens,usage
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: prom
+Requires-Dist: prometheus-client>=0.20; extra == 'prom'
+Description-Content-Type: text/markdown
+
+# codex-meter
+
+[![CI](https://github.com/rajdeepmondaldotcom/codex-meter/actions/workflows/ci.yml/badge.svg)](https://github.com/rajdeepmondaldotcom/codex-meter/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/codex-meter.svg)](https://pypi.org/project/codex-meter/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Understand your Codex work locally.
+
+`codex-meter` turns local Codex logs into a clear record of how your coding work
+happened: sessions, projects, models, tiers, cache reuse, tokens, credits,
+API-equivalent dollars, and rate-limit windows.
+
+No cloud sync. No account login. No billing scrape. Just local evidence you can
+inspect, export, and trust.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+uvx codex-meter
+```
+
+Persistent install:
+
+```bash
+uv tool install codex-meter
+codex-meter
+```
+
+With `pipx`:
+
+```bash
+pipx install codex-meter
+codex-meter
+```
+
+With `pip`:
+
+```bash
+python -m pip install codex-meter
+codex-meter
+```
+
+Prometheus exporter:
+
+```bash
+uv tool install 'codex-meter[prom]'
+```
+
+Homebrew:
+
+```bash
+brew install rajdeepmondaldotcom/tap/codex-meter
+```
+
+## Start Here
+
+```bash
+codex-meter                         # 7 / 30 / 90 day overview
+codex-meter doctor                  # check local data and assumptions
+codex-meter live                    # watch usage while you work
+codex-meter project --days 30       # see project activity
+codex-meter models --days 30        # inspect model and tier mix
+```
+
+The first run parses local session files. Later runs use a sidecar parse cache.
+Use `--no-parse-cache` when debugging parser behavior.
+
+## Why It Exists
+
+Codex already leaves a detailed trail on your machine. The problem is that the
+trail is split across JSONL sessions, SQLite metadata, config, rate-limit
+samples, and pricing assumptions. `codex-meter` turns that trail into one local
+view.
+
+It answers:
+
+- What did I use?
+- Where did it go?
+- Which model and tier drove it?
+- How much input was cached?
+- What changed across sessions, projects, and days?
+
+This is not an OpenAI billing ledger. It is local usage intelligence.
+
+## Commands
+
+| Need | Command |
+| --- | --- |
+| Overview | `codex-meter` |
+| Daily / weekly / monthly | `codex-meter daily`, `weekly`, `monthly` |
+| Sessions | `codex-meter session --top 20` |
+| Projects | `codex-meter project --days 30` |
+| Models and tiers | `codex-meter models --days 30` |
+| Recent events | `codex-meter tail --n 20` |
+| Rate limits | `codex-meter limits` |
+| Insights | `codex-meter insights` |
+| Forecast | `codex-meter forecast --days 14` |
+| Compare windows | `codex-meter compare --a "last 7 days" --b "previous 7 days"` |
+| What-if pricing | `codex-meter whatif --tier standard` |
+| Optional budgets | `codex-meter budgets check` |
+| Receipt | `codex-meter export receipt --month 2026-05 --format html` |
+| Prometheus | `codex-meter export prometheus --port 9090` |
+| Grafana | `codex-meter export grafana > dashboard.json` |
+
+Most report commands support:
+
+```bash
+--format table|json|csv|markdown
+--output report.json
+--since 2026-05-01
+--days 30
+--top 20
+```
+
+## Live View
+
+```bash
+codex-meter live
+```
+
+Shows today's usage, trailing 7-day usage, 5-hour and weekly windows, burn rate,
+and ETA to 100% when enough samples exist.
+
+Hotkeys:
+
+| Key | Action |
+| --- | --- |
+| `q` | Quit |
+| `?` | Help |
+| `r` | Refresh |
+| `p` | Pause |
+
+## Budgets
+
+Create a config:
+
+```bash
+codex-meter init
+```
+
+Add limits:
+
+```toml
+[budgets]
+daily_credits = 25000
+weekly_credits = 100000
+monthly_credits = 400000
+weekly_api_dollars = 50.0
+```
+
+Check them:
+
+```bash
+codex-meter budgets check
+```
+
+Exit codes are built for automation:
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | ok |
+| `1` | warning |
+| `2` | breached or failed |
+
+## Exports
+
+```bash
+codex-meter export receipt --month 2026-05 --format markdown
+codex-meter export receipt --month 2026-05 --format html > receipt.html
+codex-meter export prometheus --host 127.0.0.1 --port 9090
+codex-meter export grafana > dashboard.json
+```
+
+Receipts redact local session and project labels by default. Use
+`--show-sensitive` only for private artifacts.
+
+Prometheus exposes credits, burn rate, rate-limit window percent, event count,
+long-context event count, and tokens by model/tier/kind.
+
+## Data Sources
+
+`codex-meter` reads:
+
+- `~/.codex/sessions/**/*.jsonl`
+- `~/.codex/state_5.sqlite`
+- `~/.codex/config.toml`
+
+Normal reports do not touch the network. The only networked command is explicit:
+
+```bash
+codex-meter rates refresh --allow-network
+```
+
+That writes a local pricing-source audit snapshot, including observed token
+rates, fast multipliers, long-context rules, and discrepancies. It does not
+rewrite the embedded rate card.
+
+## Accuracy
+
+The hard part is not adding tokens. It is making assumptions visible.
+
+`codex-meter` tracks cached input separately, applies per-model long-context
+rules, uses exact decimal math internally, and reports whether service tiers
+came from logs, config, overrides, or assumptions. If a model or credit rate is
+not source-verified, reports mark pricing as partial instead of silently using a
+fallback as exact.
+
+Reasoning tokens are only billed separately when the Codex token log shows they
+are not already included in output tokens. This prevents double-counting on
+current local Codex logs.
+
+Service-tier precedence:
+
+1. `--service-tier standard|fast`
+2. `--tier-overrides overrides.json`
+3. logged tier
+4. current `~/.codex/config.toml`
+5. `--unknown-service-tier`
+
+Inspect pricing:
+
+```bash
+codex-meter rates show
+codex-meter rates show --format json
+```
+
+Use local overrides when needed:
+
+```bash
+codex-meter daily --rates-file ./rates.json
+```
+
+Schemas:
+
+- [`schemas/rates.schema.json`](schemas/rates.schema.json)
+- [`schemas/tier-overrides.schema.json`](schemas/tier-overrides.schema.json)
+
+## Privacy
+
+The default posture is local and conservative.
+
+- Reports read local files.
+- Prompt and session labels are redacted unless requested.
+- Receipts hide full session IDs and project paths by default.
+- JSON, CSV, Markdown, and HTML exports may still contain local metadata.
+
+Treat exports as sensitive unless you made them for sharing.
+
+## Development
+
+```bash
+uv sync --dev
+uv run ruff check .
+uv run ruff format --check .
+PYTHONWARNINGS=error::ResourceWarning uv run pytest
+uv run pytest --cov=src/codex_meter --cov-report=term
+uv run python -m build
+```
+
+Smoke test against your own logs:
+
+```bash
+uv run codex-meter doctor
+uv run codex-meter overview
+uv run codex-meter rates show
+```
+
+## License
+
+MIT

codex_meter-0.3.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+codex_meter/__init__.py,sha256=IwovSXgnigRH64qIbBoBdQHsLUqa43qhK2tSTsmLUuA,292
+codex_meter/__main__.py,sha256=Il5u5iA1jLBTRWK1Moy2K30VdDdN5Lld6zk2DDpQqUE,70
+codex_meter/aggregation.py,sha256=ZyM0t2vz8Ceu1Jadmt6aJI30N4ju_j1QrmuQbN7eVBk,4330
+codex_meter/budgets.py,sha256=OBBIEznlb5skrSyB494zhMw8fj_rAaSIp8Xfuk11t58,4278
+codex_meter/cli.py,sha256=r9kAweIrKTsyKa_nTQqVmMNsLx1QYCLHYPA0YsrSqRk,87046
+codex_meter/config.py,sha256=E-KcV9eXafzAMHT8Rnu4e4zeE-aPwHmEcvOPj9HRorY,6164
+codex_meter/exporters.py,sha256=holZtgJPGnlNNYOT7egqUbdbYwVr8Ezoo1K9cgNho7A,12420
+codex_meter/forecasts.py,sha256=XflsG2e2JI-8eZWeZbZ3-i-oP955sg-sKHEkB0OAiJQ,2686
+codex_meter/humanize.py,sha256=h4KPo0zdugB7EjVml6_ooOyCyEg7bE3j9mG9MSfYFMs,1177
+codex_meter/insights.py,sha256=8fkzO9GyrcQp2JMakb7Drxew-F9leNWAvgfPuA0gy-4,4768
+codex_meter/intervals.py,sha256=GWtUkPftEEwUmRwTJzGIEGVLZjvkhZC8gf0qS52fqkM,4590
+codex_meter/live.py,sha256=shtXCRGm4fn4GwinDMXKv3-g77qyHocgg4291f3VBao,10184
+codex_meter/models.py,sha256=8Idl9gN0keOSho2xZdKoz6yFoi2fBNyjZKp3Qp2RxjI,8238
+codex_meter/parse_cache.py,sha256=gwHC0rqZic3KGmfc2g-I7lKLg387YFeS-gbvhE6I6ws,6143
+codex_meter/parser.py,sha256=70hLQwNBviKJcETKe2lpGU6AIIS35MWiu898zzaYvS4,18645
+codex_meter/pricing.py,sha256=OxcA3ETBZ5caHbHN2XC7MEzseuJG_3TgxZQbbm1o1YU,11547
+codex_meter/prom_export.py,sha256=jPFPplmr9AICp805wv4YhlcgiSQ4Nrp5z_4soIU0sz0,3920
+codex_meter/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codex_meter/render.py,sha256=67IyiXH-ciY347M9qhvGu6hcGWd5LoM93oYIQTgpiDY,19685
+codex_meter/timeutil.py,sha256=0Vth-CWRwCmBh0oiGA_LkP9fsjk-Nts6SaNJI2LqiR0,2266
+codex_meter/windows.py,sha256=Z2Ryst68Zu0usj3S_uvVuy_JiUFeB9vARwuryKeJq8k,4802
+codex_meter-0.3.0.dist-info/METADATA,sha256=052G0GDMGwQPCJozZfcWMPResE8YZB9MgnrYu363MnQ,7934
+codex_meter-0.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+codex_meter-0.3.0.dist-info/entry_points.txt,sha256=3i4pFl39F6QW_OJQ2Ds5wM40eqArMNkFeuLftAdB_wM,52
+codex_meter-0.3.0.dist-info/licenses/LICENSE,sha256=o5_prA7Ia_-1E726qg4ApoZOsGLloxBTq-Z6CCXMc9Y,1071
+codex_meter-0.3.0.dist-info/RECORD,,

codex_meter-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_meter-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-meter = codex_meter.cli:app

codex_meter-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rajdeep Mondal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.