codex-ledger 0.1.0__tar.gz

codex_ledger-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+.DS_Store
+.coverage
+__pycache__/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+.python-version
+build/
+dist/
+htmlcov/
+*.egg-info/
+*.py[cod]
+*.sqlite
+*.sqlite3
+*.db
+uv.lock
+codex-ledger-implementation-brief.md
+codex-ledger-implementation-brief-v2.md
+codex-ledger-implementation-brief-v3.md
+codex-ledger-implementation-brief-v4.md
+codex-ledger-implementation-brief-v5.md
+codex-ledger-implementation-brief-v6.md
+codex-ledger-implementation-brief-v7.md

codex_ledger-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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_ledger-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: codex-ledger
+Version: 0.1.0
+Summary: Local-first, auditable usage ledger for Codex session artifacts.
+Author: Mark Hardy
+License: MIT
+License-File: LICENSE
+Keywords: cli,codex,ledger,sqlite,usage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: pillow>=10.4
+Description-Content-Type: text/markdown
+
+# Codex Ledger
+
+Codex Ledger is a local-first, auditable CLI for importing Codex session artifacts into
+an event-level SQLite ledger, deriving deterministic reports, estimating reference USD
+cost at the event level, and rendering privacy-safe delivery artifacts from saved report
+JSON.
+
+## Status
+
+The repository now includes the full v1 delivery layer:
+
+- immutable raw artifact archiving and canonical event ledger
+- workspace resolution with redaction, alias, and full-path modes
+- agent and subagent lineage plus observability diagnostics
+- deterministic event-level reference USD pricing
+- aggregate, workspace, agent, and explain report surfaces
+- deterministic report JSON artifact writing
+- offline schema validation for saved report JSON
+- PNG heatmap and static workspace HTML rendering from saved report JSON
+- read-only verify and reconcile diagnostics
+- release workflow scaffolding and release-readiness docs
+
+## Install
+
+Local development uses `uv` and Python 3.12+.
+
+```bash
+uv sync --group dev
+uv run codex-ledger --help
+```
+
+For local wheel validation before publication:
+
+```bash
+uv build
+pipx install ./dist/codex_ledger-0.1.0-py3-none-any.whl
+```
+
+After the package is actually published, the intended install surface is:
+
+```bash
+pipx install codex-ledger
+```
+
+## Quickstart
+
+Inspect the current environment and migration status:
+
+```bash
+codex-ledger doctor
+```
+
+Import locally persisted rollout files:
+
+```bash
+codex-ledger sync
+```
+
+Import an explicit Codex JSON file:
+
+```bash
+codex-ledger import codex-json --input ./sample-report.json
+```
+
+Recalculate reference USD pricing:
+
+```bash
+codex-ledger price recalc --rule-set reference_usd_openai_standard_2026_04_07
+```
+
+Write a deterministic aggregate report JSON artifact:
+
+```bash
+codex-ledger report aggregate \
+  --period month \
+  --as-of 2026-04-30 \
+  --output ./artifacts/aggregate.json
+```
+
+Render a heatmap from the saved report JSON:
+
+```bash
+codex-ledger render heatmap \
+  --report ./artifacts/aggregate.json \
+  --output ./artifacts/aggregate.png
+```
+
+Render static workspace HTML from a workspace report JSON artifact:
+
+```bash
+codex-ledger report workspace \
+  --period month \
+  --as-of 2026-04-30 \
+  --output ./artifacts/workspaces.json
+
+codex-ledger render workspace-html \
+  --report ./artifacts/workspaces.json \
+  --output ./artifacts/workspaces.html
+```
+
+Run read-only verification:
+
+```bash
+codex-ledger verify ledger
+codex-ledger verify reports
+```
+
+Compare a reference summary against current derived totals:
+
+```bash
+codex-ledger reconcile reference --input ./reference-summary.json
+```
+
+## Privacy Defaults
+
+The ledger keeps raw provenance locally, including original source paths in SQLite.
+Default outward-facing report, explain, and render output stays redacted unless you
+explicitly request `--redaction-mode alias` or `--redaction-mode full`.
+
+Rendered PNG and HTML artifacts are traced by sidecar JSON manifests that record report
+schema version, generator version, pricing rule-set selection, redaction mode, and
+source-report hashes without leaking absolute source paths by default.
+
+## Verification
+
+The standard local verification suite is:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+uv run ruff format --check .
+```
+
+Release-readiness details live in [docs/RELEASE_READINESS.md](docs/RELEASE_READINESS.md).
+
+## Scope
+
+The v1 scope is a Python CLI with deterministic local storage, pricing, reporting,
+rendering, explainability, and verification. Interactive web UI work is out of scope.

codex_ledger-0.1.0/README.md

@@ -0,0 +1,141 @@
+# Codex Ledger
+
+Codex Ledger is a local-first, auditable CLI for importing Codex session artifacts into
+an event-level SQLite ledger, deriving deterministic reports, estimating reference USD
+cost at the event level, and rendering privacy-safe delivery artifacts from saved report
+JSON.
+
+## Status
+
+The repository now includes the full v1 delivery layer:
+
+- immutable raw artifact archiving and canonical event ledger
+- workspace resolution with redaction, alias, and full-path modes
+- agent and subagent lineage plus observability diagnostics
+- deterministic event-level reference USD pricing
+- aggregate, workspace, agent, and explain report surfaces
+- deterministic report JSON artifact writing
+- offline schema validation for saved report JSON
+- PNG heatmap and static workspace HTML rendering from saved report JSON
+- read-only verify and reconcile diagnostics
+- release workflow scaffolding and release-readiness docs
+
+## Install
+
+Local development uses `uv` and Python 3.12+.
+
+```bash
+uv sync --group dev
+uv run codex-ledger --help
+```
+
+For local wheel validation before publication:
+
+```bash
+uv build
+pipx install ./dist/codex_ledger-0.1.0-py3-none-any.whl
+```
+
+After the package is actually published, the intended install surface is:
+
+```bash
+pipx install codex-ledger
+```
+
+## Quickstart
+
+Inspect the current environment and migration status:
+
+```bash
+codex-ledger doctor
+```
+
+Import locally persisted rollout files:
+
+```bash
+codex-ledger sync
+```
+
+Import an explicit Codex JSON file:
+
+```bash
+codex-ledger import codex-json --input ./sample-report.json
+```
+
+Recalculate reference USD pricing:
+
+```bash
+codex-ledger price recalc --rule-set reference_usd_openai_standard_2026_04_07
+```
+
+Write a deterministic aggregate report JSON artifact:
+
+```bash
+codex-ledger report aggregate \
+  --period month \
+  --as-of 2026-04-30 \
+  --output ./artifacts/aggregate.json
+```
+
+Render a heatmap from the saved report JSON:
+
+```bash
+codex-ledger render heatmap \
+  --report ./artifacts/aggregate.json \
+  --output ./artifacts/aggregate.png
+```
+
+Render static workspace HTML from a workspace report JSON artifact:
+
+```bash
+codex-ledger report workspace \
+  --period month \
+  --as-of 2026-04-30 \
+  --output ./artifacts/workspaces.json
+
+codex-ledger render workspace-html \
+  --report ./artifacts/workspaces.json \
+  --output ./artifacts/workspaces.html
+```
+
+Run read-only verification:
+
+```bash
+codex-ledger verify ledger
+codex-ledger verify reports
+```
+
+Compare a reference summary against current derived totals:
+
+```bash
+codex-ledger reconcile reference --input ./reference-summary.json
+```
+
+## Privacy Defaults
+
+The ledger keeps raw provenance locally, including original source paths in SQLite.
+Default outward-facing report, explain, and render output stays redacted unless you
+explicitly request `--redaction-mode alias` or `--redaction-mode full`.
+
+Rendered PNG and HTML artifacts are traced by sidecar JSON manifests that record report
+schema version, generator version, pricing rule-set selection, redaction mode, and
+source-report hashes without leaking absolute source paths by default.
+
+## Verification
+
+The standard local verification suite is:
+
+```bash
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+uv run ruff format --check .
+```
+
+Release-readiness details live in [docs/RELEASE_READINESS.md](docs/RELEASE_READINESS.md).
+
+## Scope
+
+The v1 scope is a Python CLI with deterministic local storage, pricing, reporting,
+rendering, explainability, and verification. Interactive web UI work is out of scope.

codex_ledger-0.1.0/pricing/README.md

@@ -0,0 +1,31 @@
+# Pricing Rules
+
+Phase 3 adds repo-tracked, offline pricing rules under `pricing/rules/`.
+
+The pricing layer in this phase is intentionally narrow:
+
+- event-level only
+- deterministic and reproducible
+- based on observed execution models
+- labeled as `reference_usd`, not invoice parity
+
+Rule files are versioned JSON documents. Each rule set declares:
+
+- `rule_set_id`
+- `pricing_plane`
+- `currency`
+- effective date windows
+- token-field mapping
+- provider/model match rules
+- provenance metadata
+- confidence and stability flags
+
+The seeded rule set is conservative and only covers explicitly configured models. Unknown
+or preview models remain unsupported until a rule file opts into a rate.
+
+Use:
+
+```bash
+codex-ledger price recalc --rule-set reference_usd_openai_standard_2026_04_07
+codex-ledger price coverage --rule-set reference_usd_openai_standard_2026_04_07
+```

codex_ledger-0.1.0/pricing/rules/README.md

@@ -0,0 +1,19 @@
+# Pricing Rule Files
+
+Each file in this directory is a versioned pricing rule snapshot.
+
+Current schema:
+
+- `pricing-rule-set-v1`
+
+Each file should define:
+
+- rule-set identity and pricing plane
+- effective date window
+- token-field mapping
+- provider/model match rules
+- provenance metadata
+- confidence and stability labels
+
+Rules are loaded offline from the local repository. They are validated before use, and
+invalid or overlapping rule windows fail fast.

codex_ledger-0.1.0/pricing/rules/reference_usd_openai_standard_2026_04_07.json

@@ -0,0 +1,59 @@
+{
+  "schema_version": "pricing-rule-set-v1",
+  "rule_set_id": "reference_usd_openai_standard_2026_04_07",
+  "pricing_plane": "reference_usd",
+  "currency": "USD",
+  "version": "2026-04-07",
+  "effective_from_utc": "2026-03-05T00:00:00Z",
+  "effective_to_utc": null,
+  "stability": "reference",
+  "confidence": "high",
+  "token_mapping": {
+    "input_tokens_field": "input_tokens",
+    "cached_input_tokens_field": "cached_input_tokens",
+    "output_tokens_field": "output_tokens",
+    "cached_input_behavior": "subtract_from_input"
+  },
+  "provenance": {
+    "source_urls": [
+      "https://openai.com/api/pricing/",
+      "https://developers.openai.com/api/docs/models/gpt-5.4",
+      "https://developers.openai.com/api/docs/models/gpt-5.4-mini"
+    ],
+    "notes": "Reference USD estimate using public OpenAI standard token pricing for observed execution models only."
+  },
+  "rules": [
+    {
+      "rule_id": "gpt-5.4-standard-2026-03-05",
+      "provider": "codex",
+      "model_id": "gpt-5.4",
+      "effective_from_utc": "2026-03-05T00:00:00Z",
+      "effective_to_utc": null,
+      "input_usd_per_1m": "2.50",
+      "cached_input_usd_per_1m": "0.25",
+      "output_usd_per_1m": "15.00",
+      "stability": "reference",
+      "confidence": "high",
+      "provenance": {
+        "source_url": "https://developers.openai.com/api/docs/models/gpt-5.4",
+        "notes": "GPT-5.4 model page lists standard input, cached input, and output token pricing."
+      }
+    },
+    {
+      "rule_id": "gpt-5.4-mini-standard-2026-03-17",
+      "provider": "codex",
+      "model_id": "gpt-5.4-mini",
+      "effective_from_utc": "2026-03-17T00:00:00Z",
+      "effective_to_utc": null,
+      "input_usd_per_1m": "0.75",
+      "cached_input_usd_per_1m": "0.075",
+      "output_usd_per_1m": "4.50",
+      "stability": "reference",
+      "confidence": "high",
+      "provenance": {
+        "source_url": "https://developers.openai.com/api/docs/models/gpt-5.4-mini",
+        "notes": "GPT-5.4 mini model page lists standard input, cached input, and output token pricing."
+      }
+    }
+  ]
+}

codex_ledger-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "codex-ledger"
+version = "0.1.0"
+description = "Local-first, auditable usage ledger for Codex session artifacts."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+authors = [
+  { name = "Mark Hardy" },
+]
+keywords = ["codex", "cli", "ledger", "sqlite", "usage"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Utilities",
+]
+dependencies = [
+  "Pillow>=10.4",
+]
+
+[project.scripts]
+codex-ledger = "codex_ledger.cli.main:main"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.18",
+  "pytest>=8.4",
+  "ruff>=0.13",
+]
+
+[tool.hatch.build]
+include = [
+  "src/codex_ledger/**/*.py",
+  "src/codex_ledger/migrations/*.sql",
+  "src/codex_ledger/pricing/rules_data/*.json",
+  "src/codex_ledger/reports/schemas_data/*.json",
+  "pricing/README.md",
+  "pricing/rules/*.json",
+  "pricing/rules/README.md",
+  "schemas/reports/*.json",
+  "schemas/reports/README.md",
+  "README.md",
+  "LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/codex_ledger"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

codex_ledger-0.1.0/schemas/reports/README.md

@@ -0,0 +1,15 @@
+# Report Schemas
+
+Phase 4 adds lightweight JSON Schema documents for the stable report and explain payloads.
+
+Current schema files:
+
+- `aggregate-report-v1.schema.json`
+- `workspace-report-v1.schema.json`
+- `agent-diagnostics-v1.schema.json`
+- `explain-report-v1.schema.json`
+
+The schemas intentionally validate the stable top-level contract and major blocks rather
+than every nested analytic detail.
+
+Saved report JSON artifacts are validated against these schemas before render time.

codex_ledger-0.1.0/schemas/reports/agent-diagnostics-v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Agent Diagnostics",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at_utc",
+    "generator_version",
+    "filters",
+    "timezone",
+    "pricing",
+    "summary"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "phase2.1-agent-diagnostics-v1"
+    },
+    "generated_at_utc": {
+      "type": "string"
+    },
+    "generator_version": {
+      "type": "string"
+    },
+    "filters": {
+      "type": "object"
+    },
+    "timezone": {
+      "const": "UTC"
+    },
+    "pricing": {
+      "type": "object"
+    },
+    "summary": {
+      "type": "object"
+    }
+  }
+}

codex_ledger-0.1.0/schemas/reports/aggregate-report-v1.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Aggregate Report",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at_utc",
+    "generator_version",
+    "filters",
+    "timezone",
+    "pricing",
+    "data"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "phase4-aggregate-report-v1"
+    },
+    "generated_at_utc": {
+      "type": "string"
+    },
+    "generator_version": {
+      "type": "string"
+    },
+    "filters": {
+      "type": "object"
+    },
+    "timezone": {
+      "const": "UTC"
+    },
+    "pricing": {
+      "type": "object"
+    },
+    "data": {
+      "type": "object"
+    }
+  }
+}

codex_ledger-0.1.0/schemas/reports/explain-report-v1.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Explain Report",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "generated_at_utc",
+    "generator_version",
+    "filters",
+    "timezone",
+    "pricing",
+    "summary"
+  ],
+  "properties": {
+    "schema_version": {
+      "enum": [
+        "phase4-explain-report-v1",
+        "phase2.1-agent-diagnostics-v1"
+      ]
+    },
+    "generated_at_utc": {
+      "type": "string"
+    },
+    "generator_version": {
+      "type": "string"
+    },
+    "filters": {
+      "type": "object"
+    },
+    "timezone": {
+      "const": "UTC"
+    },
+    "pricing": {
+      "type": "object"
+    },
+    "summary": {
+      "type": "object"
+    }
+  }
+}