contextpress 0.5.1__tar.gz → 0.5.3__tar.gz

{contextpress-0.5.1 → contextpress-0.5.3}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `contextpress` are recorded here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.3] - 2026-07-24
+
+- **`recommend_preset()`** — pick the mildest preset (low → medium → high) that fits a token budget.
+- **`CompressionStats.token_savings_pct`** — percentage tokens saved; included in ``to_dict()``.
+- Example: `examples/pick_preset.py`.
+
+## [0.5.2] - 2026-07-22
+
+- **`OpenAIBackend`** — optional `api_key` / env (`OPENAI_API_KEY`); no manual client required.
+
 ## [0.5.1] - 2026-07-22
 
 - **`ClaudeBackend`** — shortcut for Anthropic Claude (`ANTHROPIC_API_KEY` or `api_key=`).

{contextpress-0.5.1 → contextpress-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.5.1
+Version: 0.5.3
 Summary: Deterministic context compression for LLM chat, RAG, and agent pipelines
 Project-URL: Homepage, https://github.com/Taha-azizi/contextpress
 Project-URL: Documentation, https://github.com/Taha-azizi/contextpress#readme
@@ -313,7 +313,14 @@ if cm.fits_budget(messages, 4000):
 ```python
 rows = cm.compare_presets(messages, token_budget=500)
 for preset, stats in rows.items():
-    print(preset, stats.tokens_saved)
+    print(preset, stats.tokens_saved, stats.token_savings_pct)
+```
+
+**Recommend a preset** (0.5.3+):
+
+```python
+preset = cm.recommend_preset(messages, token_budget=500)
+out = cm.compress(messages, token_budget=500, compression=preset)
 ```
 
 **Async** (0.5+):
@@ -459,11 +466,10 @@ Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens
 **Install SDKs** (not bundled): `pip install openai`, `anthropic`, and/or **`ollama`** (for local Ollama), or `pip install "contextpress[llm]"` from this repo’s `pyproject.toml` to pull all optional LLM clients.
 
 ```python
-from openai import OpenAI
 from contextpress import ContextManager
 from contextpress.llm.adapters import OpenAIBackend
 
-backend = OpenAIBackend(client=OpenAI(), model="gpt-4o-mini")
+backend = OpenAIBackend(model="gpt-4o-mini")  # uses OPENAI_API_KEY
 cm = ContextManager(
     type="chat",
     llm_backend=backend,

{contextpress-0.5.1 → contextpress-0.5.3}/README.md

@@ -72,7 +72,14 @@ if cm.fits_budget(messages, 4000):
 ```python
 rows = cm.compare_presets(messages, token_budget=500)
 for preset, stats in rows.items():
-    print(preset, stats.tokens_saved)
+    print(preset, stats.tokens_saved, stats.token_savings_pct)
+```
+
+**Recommend a preset** (0.5.3+):
+
+```python
+preset = cm.recommend_preset(messages, token_budget=500)
+out = cm.compress(messages, token_budget=500, compression=preset)
 ```
 
 **Async** (0.5+):
@@ -218,11 +225,10 @@ Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens
 **Install SDKs** (not bundled): `pip install openai`, `anthropic`, and/or **`ollama`** (for local Ollama), or `pip install "contextpress[llm]"` from this repo’s `pyproject.toml` to pull all optional LLM clients.
 
 ```python
-from openai import OpenAI
 from contextpress import ContextManager
 from contextpress.llm.adapters import OpenAIBackend
 
-backend = OpenAIBackend(client=OpenAI(), model="gpt-4o-mini")
+backend = OpenAIBackend(model="gpt-4o-mini")  # uses OPENAI_API_KEY
 cm = ContextManager(
     type="chat",
     llm_backend=backend,

{contextpress-0.5.1 → contextpress-0.5.3}/contextpress/__init__.py

@@ -16,7 +16,7 @@ __all__ = [
     "CompressionResult",
     "CompressionStats",
 ]
-__version__ = "0.5.1"
+__version__ = "0.5.3"
 
 
 def __getattr__(name: str) -> Any:

{contextpress-0.5.1 → contextpress-0.5.3}/contextpress/core.py

@@ -101,6 +101,25 @@ class ContextManager:
             results[preset] = preview.stats
         return results
 
+    def recommend_preset(
+        self,
+        messages: Any,
+        token_budget: int,
+        *,
+        presets: tuple[str, ...] = ("low", "medium", "high"),
+    ) -> str:
+        """Return the mildest preset whose dry-run output fits ``token_budget``.
+
+        Presets are tried in order (default: low → medium → high). If none fit,
+        returns the preset with the lowest ``tokens_after`` (most compression).
+        """
+        _validate_token_budget(token_budget)
+        rows = self.compare_presets(messages, token_budget=token_budget, presets=presets)
+        for preset in presets:
+            if rows[preset].tokens_after <= token_budget:
+                return preset
+        return min(presets, key=lambda name: rows[name].tokens_after)
+
     def preview(
         self,
         messages: Any,

{contextpress-0.5.1 → contextpress-0.5.3}/contextpress/llm/adapters.py

@@ -27,20 +27,45 @@ def _ollama_response_text(resp: Any) -> str:
 
 class OpenAIBackend(LLMBackend):
     """
-    Adapter for OpenAI-compatible APIs.
-    Requires: pip install openai
-    User must pass their own client instance.
+    Adapter for **OpenAI** chat APIs.
+
+    Requires: ``pip install openai``
+
+    Usage (API key from env ``OPENAI_API_KEY`` or ``api_key=``)::
 
-    Usage:
-        from openai import OpenAI
         from contextpress.llm.adapters import OpenAIBackend
 
-        backend = OpenAIBackend(client=OpenAI(), model="gpt-4o-mini")
-        cm = ContextManager(type="chat", llm_backend=backend)
+        backend = OpenAIBackend(model=\"gpt-4o-mini\")
+        cm = ContextManager(type=\"chat\", llm_backend=backend)
+
+    Or pass your own client::
+
+        from openai import OpenAI
+
+        backend = OpenAIBackend(client=OpenAI(), model=\"gpt-4o-mini\")
     """
 
-    def __init__(self, client: Any, model: str = "gpt-4o-mini"):
-        self.client = client
+    def __init__(
+        self,
+        client: Any | None = None,
+        model: str = "gpt-4o-mini",
+        *,
+        api_key: str | None = None,
+    ):
+        if client is not None:
+            self.client = client
+            self.model = model
+            return
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "OpenAIBackend requires the 'openai' package. " "Install with: pip install openai"
+            ) from exc
+        key = api_key or os.environ.get("OPENAI_API_KEY")
+        if not key:
+            raise ValueError("Set OPENAI_API_KEY or pass api_key= for OpenAIBackend")
+        self.client = OpenAI(api_key=key)
         self.model = model
 
     def summarize(self, text: str, max_tokens: int) -> str:

{contextpress-0.5.1 → contextpress-0.5.3}/contextpress/stats.py

@@ -60,6 +60,12 @@ class CompressionStats:
     def tokens_saved(self) -> int:
         return max(0, self.tokens_before - self.tokens_after)
 
+    @property
+    def token_savings_pct(self) -> float:
+        if self.tokens_before <= 0:
+            return 0.0
+        return round(100.0 * self.tokens_saved / self.tokens_before, 2)
+
     def to_dict(self) -> dict[str, Any]:
         """JSON-serializable snapshot of this run."""
         return {
@@ -69,6 +75,7 @@ class CompressionStats:
             "tokens_before": self.tokens_before,
             "tokens_after": self.tokens_after,
             "tokens_saved": self.tokens_saved,
+            "token_savings_pct": self.token_savings_pct,
             "stages_run": list(self.stages_run),
             "turn_delta_by_stage": dict(self.turn_delta_by_stage),
             "llm_tier_applied": self.llm_tier_applied,

{contextpress-0.5.1 → contextpress-0.5.3}/examples/llm_tier_openai.py

@@ -17,8 +17,6 @@ from __future__ import annotations
 import os
 import sys
 
-from openai import OpenAI
-
 from contextpress import ContextManager
 from contextpress.llm.adapters import OpenAIBackend
 
@@ -35,7 +33,7 @@ def main() -> None:
         {"role": "user", "content": "And numpy? " * 80},
     ]
 
-    backend = OpenAIBackend(client=OpenAI(), model="gpt-4o-mini")
+    backend = OpenAIBackend(model="gpt-4o-mini")
     cm = ContextManager(
         type="chat",
         llm_backend=backend,

contextpress-0.5.3/examples/pick_preset.py

@@ -0,0 +1,21 @@
+"""Pick the mildest compression preset that fits a token budget (dry run)."""
+
+from contextpress import ContextManager
+
+messages = [
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "Old topic: " + "blah " * 40},
+    {"role": "assistant", "content": "Basically, honestly, " + "yak " * 40},
+    {"role": "user", "content": "What is 2+2?"},
+    {"role": "assistant", "content": "Four."},
+]
+
+cm = ContextManager(type="chat")
+budget = 200
+preset = cm.recommend_preset(messages, token_budget=budget)
+stats = cm.compare_presets(messages, token_budget=budget)[preset]
+
+print(f"budget={budget}  recommended preset={preset!r}")
+print(
+    f"  tokens {stats.tokens_before}->{stats.tokens_after} " f"({stats.token_savings_pct}% saved)"
+)

{contextpress-0.5.1 → contextpress-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "contextpress"
-version = "0.5.1"
+version = "0.5.3"
 description = "Deterministic context compression for LLM chat, RAG, and agent pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }

contextpress-0.5.3/tests/test_v052.py

@@ -0,0 +1,32 @@
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from contextpress.llm.adapters import OpenAIBackend
+
+
+def test_openai_backend_with_client():
+    client = MagicMock()
+    backend = OpenAIBackend(client=client, model="gpt-4o-mini")
+    assert backend.client is client
+    assert backend.model == "gpt-4o-mini"
+
+
+def test_openai_backend_requires_api_key():
+    mock_openai = MagicMock()
+    with patch.dict(os.environ, {}, clear=True):
+        with patch.dict("sys.modules", {"openai": mock_openai}):
+            with pytest.raises(ValueError, match="OPENAI_API_KEY"):
+                OpenAIBackend()
+
+
+def test_openai_backend_from_api_key():
+    mock_module = MagicMock()
+    mock_client = MagicMock()
+    mock_module.OpenAI.return_value = mock_client
+    with patch.dict(os.environ, {"OPENAI_API_KEY": "sk-test"}):
+        with patch.dict("sys.modules", {"openai": mock_module}):
+            backend = OpenAIBackend(model="gpt-4o-mini")
+    assert backend.client is mock_client
+    mock_module.OpenAI.assert_called_once_with(api_key="sk-test")

contextpress-0.5.3/tests/test_v053.py

@@ -0,0 +1,44 @@
+from contextpress import ContextManager
+from contextpress.stats import CompressionStats
+
+
+def test_token_savings_pct():
+    stats = CompressionStats(tokens_before=100, tokens_after=60)
+    assert stats.token_savings_pct == 40.0
+    assert stats.to_dict()["token_savings_pct"] == 40.0
+
+
+def test_token_savings_pct_zero_when_empty():
+    stats = CompressionStats(tokens_before=0, tokens_after=0)
+    assert stats.token_savings_pct == 0.0
+
+
+def test_recommend_preset_picks_mildest_that_fits():
+    cm = ContextManager(type="chat")
+    messages = [
+        {"role": "user", "content": "hello basically there " * 5},
+        {"role": "assistant", "content": "sounds good " * 5},
+    ]
+    budget = 500
+    rows = cm.compare_presets(messages, token_budget=budget)
+    preset = cm.recommend_preset(messages, token_budget=budget)
+    assert rows[preset].tokens_after <= budget
+    fitting = [p for p in ("low", "medium", "high") if rows[p].tokens_after <= budget]
+    assert preset == fitting[0]
+
+
+def test_recommend_preset_falls_back_to_most_compression():
+    cm = ContextManager(type="chat")
+    messages = [{"role": "user", "content": "word " * 500}]
+    preset = cm.recommend_preset(messages, token_budget=10)
+    rows = cm.compare_presets(messages, token_budget=10)
+    assert preset == min(("low", "medium", "high"), key=lambda p: rows[p].tokens_after)
+
+
+def test_recommend_preset_requires_budget():
+    cm = ContextManager(type="chat")
+    try:
+        cm.recommend_preset([{"role": "user", "content": "hi"}], token_budget=0)
+        raise AssertionError("expected ValueError")
+    except ValueError:
+        pass