ctxoptimizer 0.4.1__tar.gz

ctxoptimizer-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed
+
+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.

ctxoptimizer-0.4.1/NOTICE

@@ -0,0 +1,13 @@
+ctxoptimizer
+Copyright (c) 2026 Ahmed
+
+ctxoptimizer is free and open-source software licensed under the MIT License.
+See LICENSE.
+
+Provider names (Anthropic, OpenAI, Google Gemini, Ollama, DeepSeek, OpenRouter,
+OpenCode, Claude Code, Codex, Cursor, Aider, Cline and others) are trademarks of
+their respective owners and are used only for descriptive compatibility. This
+project is not affiliated with or endorsed by any provider.
+
+Third-party components are distributed under their own licenses. See
+THIRD_PARTY_LICENSES.md and the installed package metadata.

ctxoptimizer-0.4.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: ctxoptimizer
+Version: 0.4.1
+Summary: Local, deterministic cost optimizer for AI coding agents
+Author: ahmed
+License-Expression: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: httpx[http2]>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: orjson>=3.10
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic>=2.7
+Requires-Dist: starlette>=0.37
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: coverage>=7 ; extra == 'dev'
+Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: pip-audit ; extra == 'dev'
+Requires-Dist: pytest>=8 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5 ; extra == 'dev'
+Requires-Dist: respx>=0.21 ; extra == 'dev'
+Requires-Dist: ruff>=0.5 ; extra == 'dev'
+Requires-Dist: google-re2>=1.1 ; extra == 're2'
+Requires-Dist: tiktoken>=0.7 ; extra == 'tokens'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/ahmed-dev25/ctxoptimizer
+Project-URL: Repository, https://github.com/ahmed-dev25/ctxoptimizer
+Project-URL: Issues, https://github.com/ahmed-dev25/ctxoptimizer/issues
+Project-URL: Changelog, https://github.com/ahmed-dev25/ctxoptimizer/blob/main/CHANGELOG.md
+Provides-Extra: dev
+Provides-Extra: re2
+Provides-Extra: tokens
+Description-Content-Type: text/markdown
+
+# ctxoptimizer
+
+A local, deterministic cost optimizer for AI coding agents. It sits between your
+agent and the LLM provider, measures real token usage and spend, explains why
+prompt caching missed, and applies cache-safe payload reductions.
+
+- **Local only** — binds to loopback; no telemetry leaves the machine.
+- **Deterministic** — no LLM calls inside the proxy; every decision is a hash,
+  regex, counter or threshold.
+- **Honest numbers** — provider-reported usage is ground truth; everything else
+  is labelled `est.` or `sim.`.
+- **Fail-open** — invalid transforms retry with the original bytes; the proxy
+  never blocks traffic.
+
+## Install
+
+```powershell
+uv tool install ctxoptimizer
+# or: pipx install ctxoptimizer
+ctxoptimizer run
+```
+
+If PyPI does not have the release yet, install from GitHub:
+
+```powershell
+uv tool install "git+https://github.com/ahmed-dev25/ctxoptimizer.git"
+# or: pipx install "git+https://github.com/ahmed-dev25/ctxoptimizer.git"
+ctxoptimizer run
+```
+
+From a checkout:
+
+```powershell
+uv sync --extra dev
+uv run ctxoptimizer run
+```
+
+The startup banner prints the dashboard URL with a per-run admin token:
+
+```text
+dashboard: http://127.0.0.1:8787/_ctxoptimizer/?token=...
+```
+
+Open that URL once; the token is stored as an `HttpOnly; SameSite=Strict`
+cookie. The dashboard is also protected by a Host allowlist and CSRF checks.
+
+## Quickstart
+
+```powershell
+ctxoptimizer env --shell powershell   # bash | zsh | fish | powershell
+ctxoptimizer status                   # health + counters
+ctxoptimizer stats                    # recorded usage and cost
+```
+
+Point a client at the printed base URL. See
+[`docs/client-setup.md`](docs/client-setup.md) for Claude Code, OpenCode,
+DeepSeek, OpenRouter, Gemini, Ollama, Codex and the other supported clients.
+
+Default mode is `shadow`: everything is measured and simulated, while the
+client's bytes are forwarded unchanged. Switch to `active` from the dashboard
+(Settings), with `ctxoptimizer run --mode active`, or with
+`x-ctxoptimizer-mode: active` per request.
+
+## What it does
+
+- Measures provider usage and cost for Anthropic, OpenAI Chat/Responses,
+  native Gemini, native Ollama and named OpenAI-compatible upstreams
+  (DeepSeek, OpenRouter, Gemini/Ollama compatibility, and custom gateways).
+- Detects drift (tools/system/history/TTL/config/model) and waste W1–W8:
+  redundant re-reads, identical outputs, unbatched fan-out, runaway sessions,
+  recurring/param drift, edit churn and unused tool schemas.
+- Applies deterministic transforms: ANSI/progress cleanup, line dedupe,
+  whitespace trim, signal-aware truncation, duplicate back-references,
+  byte-true `cache_serve`, opt-in stale-result elision, Anthropic
+  `cache_control` hints and OpenAI `prompt_cache_key`.
+- Auto-quarantines a transform per session when fallback/drift guard counters
+  trip; the dashboard shows the history and lets you re-enable it.
+- Provides `ctxoptimizer_expand` over MCP so an agent can retrieve any omitted
+  original from the local blob store.
+- Serves a local dashboard: Overview, Live (SSE), Sessions, Requests + diff
+  viewer, Waste Opportunities with status controls, Transforms with hot
+  toggles/stats, Pricing editor, Settings and Doctor.
+
+## Privacy
+
+Payload capture defaults to `changed_blocks`; set it to `off` to store nothing.
+Captured text stays in the per-user data directory, is redacted, and is bounded
+by retention. `ctxoptimizer purge --all` wipes telemetry, blobs and findings. See
+[`docs/privacy.md`](docs/privacy.md).
+
+## Service
+
+```powershell
+ctxoptimizer service install        # launchd / systemd --user / Windows scheduled task
+ctxoptimizer service install --dry-run
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup and gates. Report
+vulnerabilities privately via [`SECURITY.md`](SECURITY.md); do not open a public
+issue for a security problem.
+
+## License
+
+ctxoptimizer is free and open-source software licensed under the **MIT License**.
+See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
+
+## Updating
+
+Use the package manager that installed ctxoptimizer:
+
+```powershell
+uv tool upgrade ctxoptimizer
+# or
+pipx upgrade ctxoptimizer
+```
+
+There is no built-in self-update command. PyPI releases are published with
+Trusted Publishing and PEP 740 attestations. Source installs follow the GitHub
+repository; downloaded wheels must be replaced manually. See
+[`docs/updating.md`](docs/updating.md).
+
+## Documentation
+
+- [`SPEC.md`](SPEC.md) — authoritative specification
+- [`docs/client-setup.md`](docs/client-setup.md) — per-client recipes
+- [`docs/how-to-use.md`](docs/how-to-use.md) — complete install/run/update guide
+- [`docs/provider-notes.md`](docs/provider-notes.md) — dated provider behavior
+- [`docs/architecture.md`](docs/architecture.md) — component overview
+- [`docs/privacy.md`](docs/privacy.md) — data handling and purge
+- [`docs/faq.md`](docs/faq.md) — cache, savings, troubleshooting
+- [`docs/test-report.md`](docs/test-report.md) — gates and test coverage summary
+- [`docs/updating.md`](docs/updating.md) — package-manager upgrades and release artifacts
+- [`docs/pypi-release.md`](docs/pypi-release.md) — PyPI Trusted Publishing setup
+- [`docs/release-checklist.md`](docs/release-checklist.md) — release checklist
+- [`docs/progress.md`](docs/progress.md) — build status and handoff notes
+- [`CHANGELOG.md`](CHANGELOG.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- [`SECURITY.md`](SECURITY.md)
+- [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)
+- [`docs/decisions/`](docs/decisions/) — architecture decision records
+- [`AGENTS.md`](AGENTS.md) — coding and git workflow rules
+
+## Development
+
+```powershell
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy --strict src
+uv run pytest -q
+uv build --wheel
+```
+
+Supported Python: 3.11+. The package is built with `uv_build`; the test suite
+uses a real fake upstream and recorded/documented fixtures. Live provider tests
+are opt-in (`pytest -m live`) and require keys.

ctxoptimizer-0.4.1/README.md

@@ -0,0 +1,157 @@
+# ctxoptimizer
+
+A local, deterministic cost optimizer for AI coding agents. It sits between your
+agent and the LLM provider, measures real token usage and spend, explains why
+prompt caching missed, and applies cache-safe payload reductions.
+
+- **Local only** — binds to loopback; no telemetry leaves the machine.
+- **Deterministic** — no LLM calls inside the proxy; every decision is a hash,
+  regex, counter or threshold.
+- **Honest numbers** — provider-reported usage is ground truth; everything else
+  is labelled `est.` or `sim.`.
+- **Fail-open** — invalid transforms retry with the original bytes; the proxy
+  never blocks traffic.
+
+## Install
+
+```powershell
+uv tool install ctxoptimizer
+# or: pipx install ctxoptimizer
+ctxoptimizer run
+```
+
+If PyPI does not have the release yet, install from GitHub:
+
+```powershell
+uv tool install "git+https://github.com/ahmed-dev25/ctxoptimizer.git"
+# or: pipx install "git+https://github.com/ahmed-dev25/ctxoptimizer.git"
+ctxoptimizer run
+```
+
+From a checkout:
+
+```powershell
+uv sync --extra dev
+uv run ctxoptimizer run
+```
+
+The startup banner prints the dashboard URL with a per-run admin token:
+
+```text
+dashboard: http://127.0.0.1:8787/_ctxoptimizer/?token=...
+```
+
+Open that URL once; the token is stored as an `HttpOnly; SameSite=Strict`
+cookie. The dashboard is also protected by a Host allowlist and CSRF checks.
+
+## Quickstart
+
+```powershell
+ctxoptimizer env --shell powershell   # bash | zsh | fish | powershell
+ctxoptimizer status                   # health + counters
+ctxoptimizer stats                    # recorded usage and cost
+```
+
+Point a client at the printed base URL. See
+[`docs/client-setup.md`](docs/client-setup.md) for Claude Code, OpenCode,
+DeepSeek, OpenRouter, Gemini, Ollama, Codex and the other supported clients.
+
+Default mode is `shadow`: everything is measured and simulated, while the
+client's bytes are forwarded unchanged. Switch to `active` from the dashboard
+(Settings), with `ctxoptimizer run --mode active`, or with
+`x-ctxoptimizer-mode: active` per request.
+
+## What it does
+
+- Measures provider usage and cost for Anthropic, OpenAI Chat/Responses,
+  native Gemini, native Ollama and named OpenAI-compatible upstreams
+  (DeepSeek, OpenRouter, Gemini/Ollama compatibility, and custom gateways).
+- Detects drift (tools/system/history/TTL/config/model) and waste W1–W8:
+  redundant re-reads, identical outputs, unbatched fan-out, runaway sessions,
+  recurring/param drift, edit churn and unused tool schemas.
+- Applies deterministic transforms: ANSI/progress cleanup, line dedupe,
+  whitespace trim, signal-aware truncation, duplicate back-references,
+  byte-true `cache_serve`, opt-in stale-result elision, Anthropic
+  `cache_control` hints and OpenAI `prompt_cache_key`.
+- Auto-quarantines a transform per session when fallback/drift guard counters
+  trip; the dashboard shows the history and lets you re-enable it.
+- Provides `ctxoptimizer_expand` over MCP so an agent can retrieve any omitted
+  original from the local blob store.
+- Serves a local dashboard: Overview, Live (SSE), Sessions, Requests + diff
+  viewer, Waste Opportunities with status controls, Transforms with hot
+  toggles/stats, Pricing editor, Settings and Doctor.
+
+## Privacy
+
+Payload capture defaults to `changed_blocks`; set it to `off` to store nothing.
+Captured text stays in the per-user data directory, is redacted, and is bounded
+by retention. `ctxoptimizer purge --all` wipes telemetry, blobs and findings. See
+[`docs/privacy.md`](docs/privacy.md).
+
+## Service
+
+```powershell
+ctxoptimizer service install        # launchd / systemd --user / Windows scheduled task
+ctxoptimizer service install --dry-run
+```
+
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development setup and gates. Report
+vulnerabilities privately via [`SECURITY.md`](SECURITY.md); do not open a public
+issue for a security problem.
+
+## License
+
+ctxoptimizer is free and open-source software licensed under the **MIT License**.
+See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
+
+## Updating
+
+Use the package manager that installed ctxoptimizer:
+
+```powershell
+uv tool upgrade ctxoptimizer
+# or
+pipx upgrade ctxoptimizer
+```
+
+There is no built-in self-update command. PyPI releases are published with
+Trusted Publishing and PEP 740 attestations. Source installs follow the GitHub
+repository; downloaded wheels must be replaced manually. See
+[`docs/updating.md`](docs/updating.md).
+
+## Documentation
+
+- [`SPEC.md`](SPEC.md) — authoritative specification
+- [`docs/client-setup.md`](docs/client-setup.md) — per-client recipes
+- [`docs/how-to-use.md`](docs/how-to-use.md) — complete install/run/update guide
+- [`docs/provider-notes.md`](docs/provider-notes.md) — dated provider behavior
+- [`docs/architecture.md`](docs/architecture.md) — component overview
+- [`docs/privacy.md`](docs/privacy.md) — data handling and purge
+- [`docs/faq.md`](docs/faq.md) — cache, savings, troubleshooting
+- [`docs/test-report.md`](docs/test-report.md) — gates and test coverage summary
+- [`docs/updating.md`](docs/updating.md) — package-manager upgrades and release artifacts
+- [`docs/pypi-release.md`](docs/pypi-release.md) — PyPI Trusted Publishing setup
+- [`docs/release-checklist.md`](docs/release-checklist.md) — release checklist
+- [`docs/progress.md`](docs/progress.md) — build status and handoff notes
+- [`CHANGELOG.md`](CHANGELOG.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- [`SECURITY.md`](SECURITY.md)
+- [`THIRD_PARTY_LICENSES.md`](THIRD_PARTY_LICENSES.md)
+- [`docs/decisions/`](docs/decisions/) — architecture decision records
+- [`AGENTS.md`](AGENTS.md) — coding and git workflow rules
+
+## Development
+
+```powershell
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy --strict src
+uv run pytest -q
+uv build --wheel
+```
+
+Supported Python: 3.11+. The package is built with `uv_build`; the test suite
+uses a real fake upstream and recorded/documented fixtures. Live provider tests
+are opt-in (`pytest -m live`) and require keys.

ctxoptimizer-0.4.1/pyproject.toml

@@ -0,0 +1,100 @@
+[project]
+name = "ctxoptimizer"
+version = "0.4.1"
+description = "Local, deterministic cost optimizer for AI coding agents"
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+    "NOTICE",
+]
+requires-python = ">=3.11"
+classifiers = ["Programming Language :: Python :: 3"]
+dependencies = [
+    "httpx[http2]>=0.27",
+    "jinja2>=3.1",
+    "orjson>=3.10",
+    "platformdirs>=4.2",
+    "pydantic>=2.7",
+    "starlette>=0.37",
+    "typer>=0.12",
+    "uvicorn>=0.30",
+]
+
+[[project.authors]]
+name = "ahmed"
+
+[project.optional-dependencies]
+tokens = ["tiktoken>=0.7"]
+re2 = ["google-re2>=1.1"]
+dev = [
+    "coverage>=7",
+    "hypothesis>=6.100",
+    "mypy>=1.10",
+    "pip-audit",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-benchmark>=4",
+    "pytest-cov>=5",
+    "respx>=0.21",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+ctxoptimizer = "ctxoptimizer.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/ahmed-dev25/ctxoptimizer"
+Repository = "https://github.com/ahmed-dev25/ctxoptimizer"
+Issues = "https://github.com/ahmed-dev25/ctxoptimizer/issues"
+Changelog = "https://github.com/ahmed-dev25/ctxoptimizer/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["SPEC.md"]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "S",
+    "ASYNC",
+    "PERF",
+    "RUF",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "S104",
+]
+"scripts/**" = ["S101"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+files = ["src"]
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["live: hits real provider APIs (needs keys)"]
+addopts = "-m 'not live'"
+
+[tool.coverage.run]
+branch = true
+source = ["ctxoptimizer"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

ctxoptimizer-0.4.1/pyproject.toml.orig

@@ -0,0 +1,86 @@
+[project]
+name = "ctxoptimizer"
+version = "0.4.1"
+description = "Local, deterministic cost optimizer for AI coding agents"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "NOTICE"]
+requires-python = ">=3.11"
+authors = [{ name = "ahmed" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "httpx[http2]>=0.27",
+    "jinja2>=3.1",
+    "orjson>=3.10",
+    "platformdirs>=4.2",
+    "pydantic>=2.7",
+    "starlette>=0.37",
+    "typer>=0.12",
+    "uvicorn>=0.30",
+]
+
+[project.optional-dependencies]
+tokens = ["tiktoken>=0.7"]
+re2 = ["google-re2>=1.1"]
+dev = [
+    "coverage>=7",
+    "hypothesis>=6.100",
+    "mypy>=1.10",
+    "pip-audit",
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-benchmark>=4",
+    "pytest-cov>=5",
+    "respx>=0.21",
+    "ruff>=0.5",
+]
+
+[project.scripts]
+ctxoptimizer = "ctxoptimizer.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/ahmed-dev25/ctxoptimizer"
+Repository = "https://github.com/ahmed-dev25/ctxoptimizer"
+Issues = "https://github.com/ahmed-dev25/ctxoptimizer/issues"
+Changelog = "https://github.com/ahmed-dev25/ctxoptimizer/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.13.1,<0.14.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+# SPEC.md is authoritative and must never be reformatted. Ruff formats Python
+# code blocks inside Markdown files, which would rewrite it.
+extend-exclude = ["SPEC.md"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S", "ASYNC", "PERF", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S104"]
+"scripts/**" = ["S101"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+mypy_path = "src"
+files = ["src"]
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["live: hits real provider APIs (needs keys)"]
+addopts = "-m 'not live'"
+
+[tool.coverage.run]
+branch = true
+source = ["ctxoptimizer"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true

ctxoptimizer-0.4.1/src/ctxoptimizer/__init__.py

@@ -0,0 +1,5 @@
+"""ctxoptimizer: a local, deterministic cost optimizer for AI coding agents."""
+
+from __future__ import annotations
+
+__version__ = "0.4.1"

ctxoptimizer-0.4.1/src/ctxoptimizer/__main__.py

@@ -0,0 +1,14 @@
+"""Module entry point for ``python -m ctxoptimizer``."""
+
+from __future__ import annotations
+
+from ctxoptimizer.cli import app
+
+
+def main() -> None:
+    """Run the command line interface."""
+    app()
+
+
+if __name__ == "__main__":
+    main()