codex-meter 0.3.0__tar.gz

codex_meter-0.3.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+htmlcov/
+.coverage
+.codex-meter.toml
+docs/

codex_meter-0.3.0/CHANGELOG.md

@@ -0,0 +1,130 @@
+# Changelog
+
+## 0.3.0 - 2026-05-13
+
+### Added
+- `insights` command for cache-savings, service-tier confidence, spend concentration,
+  and usage acceleration hints.
+- `tail` command for recent usage events/sessions.
+- Sidecar parse cache with `--no-parse-cache` bypass for parser debugging.
+- Live TUI hotkeys (`q`, `?`, `r`, `p`) and `--max-ticks` for headless tests.
+- Forecast API-dollar projection and sparkline output.
+- Default `overview` invocation now accepts data-source, tier, rate-card, cache,
+  format, output, compact, and width options.
+- `rates refresh --allow-network` now writes a pricing-source audit snapshot
+  with embedded rates, observed rates, and discrepancies instead of an empty
+  placeholder.
+- Release automation now builds checked wheel/sdist artifacts, publishes through
+  PyPI Trusted Publishing, and attaches release assets on GitHub.
+- Dependabot configuration now covers `uv` dependencies and GitHub Actions.
+
+### Changed
+- Cost reporting now uses exact decimal arithmetic internally, exposes exact
+  decimal strings in JSON output, and marks partial or estimated pricing when
+  rates or service tiers are not source-verified.
+- `rates refresh --allow-network` audits fast-mode multipliers and long-context
+  rules in addition to per-token rates.
+- GPT-5.4 now carries the official `>272K` long-context rule.
+- GPT-5.1-Codex-Max remains API-priced, but Codex credit totals are marked
+  partial unless a local `--rates-file` supplies credit rates.
+- Table rendering now honors terminal/`--width` instead of collapsing to 80 columns.
+- Grouped reports accept `--top` as an alias for `--top-threads`.
+- Doctor, rates, forecast, compare, what-if, and budgets now support CSV/Markdown
+  alongside table/JSON.
+- GPT-5.1-Codex-Max now has API-equivalent rates in the embedded card.
+- Receipts include cache savings, tier-source breakdowns, warning counts, and top
+  insights, and redact full local labels by default. Use `--show-sensitive` for
+  private/local receipts with full session/project labels.
+- `init` scaffolds the full config surface.
+- Parse-cache entries are independent of the requested report window, so normal
+  rolling `now` invocations can reuse parsed sessions. Cache payloads now use
+  JSON instead of pickle.
+- Source distributions are trimmed to release-relevant files.
+- Install documentation now leads with public PyPI, `uvx`, `pipx`, and Homebrew
+  paths instead of source-checkout installation.
+
+### Fixed
+- Reasoning tokens are no longer double-counted when Codex logs already include
+  them in `output_tokens`.
+- Literal `[budgets]` text no longer disappears in Rich output.
+- Doctor clock-skew output uses directional wording instead of signed seconds.
+- What-if no-op scenarios now say there is no change.
+- Compare warns when one window is too sparse to be representative.
+- GPT-5.3-Codex-Spark stays unpriced/research-preview instead of being
+  normalized to GPT-5.3-Codex.
+- Rate-limit samples are retained for burn-rate math and only truncated at
+  render/report time.
+- SQLite connections are closed explicitly, making warning-as-error test runs
+  clean on Python 3.13.
+- Monthly receipts include events through the final sub-second before the next
+  month starts.
+
+## 0.2.0
+
+### Added
+- **Live TUI** (`codex-meter live`): full-window dashboard with today's credits, 7-day
+  total, 5-hour primary + weekly secondary countdowns, burn rate, ETA to 100%.
+  Border turns red at >= 80% used. `--interval` to tune refresh, graceful SIGINT.
+- **Window math** (`windows.py`): `WindowState` decoded from rate-limit samples;
+  Unix-epoch `resets_at` handled correctly; burn rate requires >= 3 samples in
+  a 6-hour lookback; ETA projection only when burn rate is positive.
+- **Analytics suite**:
+  - `forecast`: month-end credit projection with linear + EWMA estimators
+    and a ±1σ band. Optional `--cap` reports days-to-depletion.
+  - `compare --a --b`: side-by-side credit, dollar, and token deltas
+    between two windows (`last 7 days`, `previous 7 days`, ISO ranges, etc.).
+  - `whatif --tier --model`: re-cost the trailing window under a hypothetical
+    tier or model swap; rejects unknown models with the rate-card list.
+- **Budgets** (`budgets check`): TOML `[budgets]` table (flat keys,
+  nested-by-period, or `items = [...]` list). Severity ladder ok/warn/breach
+  drives the exit code so CI can gate on it.
+- **Rate card subcommands**:
+  - `rates show` (table + JSON) with age + stale-after-90d flag.
+  - `rates refresh` stub reserved for the network-opt-in flow.
+- **Exporters**:
+  - `export grafana`: dashboard JSON wired to codex-meter Prometheus metrics.
+  - `export receipt --month YYYY-MM --format markdown|html`: totals, models,
+    top sessions, top projects. HTML escapes user-supplied labels.
+  - `export prometheus --host --port`: stdlib `/metrics` endpoint serving
+    `codex_meter_credits_used`, `burn_per_hour`,
+    `window_used_percent{window}`, `tokens_total{model,tier,kind}`,
+    `events_total`, `long_context_events_total`. Binds 127.0.0.1 by default.
+  - `[prom]` optional extra installs `prometheus-client`.
+- **`init`** subcommand: scaffolds `.codex-meter.toml` with commented defaults;
+  refuses overwrite without `--force`.
+- **`doctor` v2**: Python version, session root + file count, state DB, Codex
+  config, `codex --version` (best-effort), rate-card age, clock skew vs latest
+  event, parser warnings. JSON output for CI. Exit code reflects worst check.
+- **Intervals** (`intervals.py`): `today`, `yesterday`, `last N days`,
+  `previous N days`, `last N hours`, `this/last week`, `this/last month`,
+  ISO date, `YYYY-MM-DD..YYYY-MM-DD` range.
+- **JSON Schemas**: `schemas/rates.schema.json`, `schemas/tier-overrides.schema.json`
+  (Draft 2020-12) for editor autocomplete + validation.
+
+### Pricing accuracy
+- `Rates` gains `reasoning_output` (defaults to `output` rate). Pricing now
+  accounts for reasoning tokens, which were previously invisible.
+- `LongContextRule` lives on `ModelCard`; only `gpt-5.5` carries the
+  272K-token, ×2/×1.5 rule today. Other models do not get the multiplier.
+
+### Refactor
+- `cli.py` deduplicated: subcommands share `Annotated` Option type aliases.
+- `ModelCard` replaces parallel rate dicts.
+- `RateCard` loads any local override file exactly once per run.
+- `Usage` frozen dataclass replaces ad-hoc `dict[str, int]` usage shapes
+  across events, aggregation, and pricing.
+- `humanize.py` carved out for `format_int`, `redact`, `REDACTION_LIMIT`.
+- `limits` command participates in the unified render pipeline and
+  supports `--format table|json|csv|markdown` with decoded reset times.
+
+### Packaging
+- `__version__` resolves through `importlib.metadata` with a local fallback.
+- `py.typed` marker shipped (PEP 561).
+- `pytest-cov` wired up; line+branch coverage at >= 82%.
+
+## 0.1.0
+
+- Initial open-source-ready CLI scaffold.
+- Added Codex JSONL parsing, SQLite metadata joins, token aggregation, Codex
+  credit estimates, API-equivalent dollar estimates, service-tier inference,
+  and table/JSON/CSV/Markdown output.

codex_meter-0.3.0/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.

codex_meter-0.3.0/PKG-INFO

@@ -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