caliper-ai 0.4.0__tar.gz

caliper_ai-0.4.0/.gitignore

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

caliper_ai-0.4.0/CHANGELOG.md

@@ -0,0 +1,195 @@
+# Changelog
+
+Caliper follows **[Semantic Versioning](https://semver.org/)** with a
+deliberately conservative pre-1.0 cadence:
+
+- `0.x.y` — public API may still move between minor versions while the
+  cross-vendor surface stabilizes. Every release documents breakage in this
+  changelog and provides a one-step upgrade path.
+- `1.0.0` — reserved for the release where the CLI surface, the
+  vendor-neutral record format, and the multi-vendor parser set are all
+  considered frozen. Caliper will not reach `1.0` until at least three
+  vendor parsers (Codex, Claude Code, Cursor) ship together.
+
+## 0.4.0 - 2026-05-13
+
+### Caliper — rebrand and vendor-neutral foundation
+
+This release rebrands the project from `codex-meter` to **Caliper**, lays
+down the vendor-neutral record that the next milestones build on, and ships
+under a new PyPI distribution name. Existing users see a stable upgrade:
+every command, option, output field, and exit code is preserved.
+
+### Added
+- New CLI entry point: `caliper`. The original `codex-meter` command is
+  retained as a permanent alias and dispatches to the same Typer app.
+- Compatibility Python package: legacy `codex_meter.*` imports lazily alias
+  to the canonical `caliper.*` modules, including private helper imports used
+  by older downstream tests.
+- Vendor-neutral record: `UsageEvent` and `RateLimitSample` now carry a
+  `vendor` field. Today's parser populates `openai-codex`; planned parsers
+  (`claude-code`, `cursor`, `aider`, `copilot`) will populate the same shape
+  so reports, pricing, budgets, forecasts, and exports work cross-vendor
+  without restructuring.
+- Vendor constants exposed via `caliper.models`: `VENDOR_OPENAI_CODEX`,
+  `VENDOR_CLAUDE_CODE`, `VENDOR_CURSOR`, `VENDOR_AIDER`, `VENDOR_COPILOT`,
+  `VENDOR_UNKNOWN`, plus the `KNOWN_VENDORS` frozenset.
+
+### Changed
+- Distribution name: `codex-meter` → `caliper-ai` on PyPI. Install with
+  `pip install caliper-ai`, `pipx install caliper-ai`, or
+  `uvx --from caliper-ai caliper`. Python import path is `caliper`.
+- Internal package: `src/codex_meter/` → `src/caliper/`. All public Python
+  imports now use `from caliper import ...`; `codex_meter` remains available
+  for compatibility.
+- Local config file: `.codex-meter.toml` → `.caliper.toml`.
+- User config directory: `~/.config/codex-meter/` → `~/.config/caliper/`.
+- Parse-cache and rate-audit sidecar directories migrated from
+  `codex-meter` to `caliper` under XDG cache/data dirs.
+- README rewritten for the Caliper product narrative; roadmap publishes the
+  cross-vendor and ROI sequence ahead of 1.0.
+- Release CI smoke-tests both `caliper` and `codex-meter` entry points from
+  the built wheel; PyPI environment URL now points at `caliper-ai`.
+
+### Upgrade notes
+- Reinstall: `uv tool install caliper-ai` (or `pipx install caliper-ai`).
+  The `codex-meter` command still works after the upgrade.
+- Existing `.codex-meter.toml` files: rename to `.caliper.toml` (same
+  schema). Existing parse caches under `~/.cache/codex-meter/` can be
+  deleted; Caliper rebuilds them on first run under `~/.cache/caliper/`.
+- `--cov=src/codex_meter` becomes `--cov=src/caliper` for downstream
+  tooling.
+
+## 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.
+- Reports now expose normalized Codex subscription-plan metadata while preserving
+  the raw plan strings seen in local logs.
+- Added `statusline` for a compact prompt/hook-friendly usage snapshot.
+
+### 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.
+- Rate-limit window math now prefers the main `codex` subscription bucket when
+  logs also include model-specific preview buckets.
+- `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.

caliper_ai-0.4.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.