contextpress 0.5.2__tar.gz → 0.5.3__tar.gz

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

@@ -4,6 +4,12 @@ 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.5.2
+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+):

{contextpress-0.5.2 → 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+):

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

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

{contextpress-0.5.2 → 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.2 → 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.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.2 → contextpress-0.5.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "contextpress"
-version = "0.5.2"
+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_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