contextpress 0.5.2__tar.gz → 0.5.4__tar.gz

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

@@ -4,6 +4,17 @@ 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.4] - 2026-07-25
+
+- **`compress_many()`** — batch ``compress()`` over a list of conversations.
+- Example: `examples/agent_pipeline.py` for ``type="agent"`` tool/task threads.
+
+## [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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.5.2
+Version: 0.5.4
 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,20 @@ 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)
+```
+
+**Batch compress** (0.5.4+):
+
+```python
+results = cm.compress_many(list_of_conversations, token_budget=2000, return_stats=True)
 ```
 
 **Async** (0.5+):
@@ -384,6 +397,8 @@ ContextManager(type="rag_doc")
 ContextManager(type="agent")
 ```
 
+Runnable agent example: [`examples/agent_pipeline.py`](examples/agent_pipeline.py).
+
 ## Pipeline stages
 
 1. **Filler** — Removes low-semantic filler words and (in chat/agent) drops acknowledgement-only assistant turns.

{contextpress-0.5.2 → contextpress-0.5.4}/README.md

@@ -72,7 +72,20 @@ 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)
+```
+
+**Batch compress** (0.5.4+):
+
+```python
+results = cm.compress_many(list_of_conversations, token_budget=2000, return_stats=True)
 ```
 
 **Async** (0.5+):
@@ -143,6 +156,8 @@ ContextManager(type="rag_doc")
 ContextManager(type="agent")
 ```
 
+Runnable agent example: [`examples/agent_pipeline.py`](examples/agent_pipeline.py).
+
 ## Pipeline stages
 
 1. **Filler** — Removes low-semantic filler words and (in chat/agent) drops acknowledgement-only assistant turns.

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

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

{contextpress-0.5.2 → contextpress-0.5.4}/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,
@@ -191,6 +210,33 @@ class ContextManager:
             return CompressionResult(messages=messages_out, stats=stats)
         return messages_out
 
+    def compress_many(
+        self,
+        conversations: list[Any],
+        token_budget: int | None = None,
+        *,
+        compression: str | None = None,
+        stages: list[str] | None = None,
+        disable: list[str] | None = None,
+        return_stats: bool = False,
+        dry_run: bool = False,
+    ) -> list[Any] | list[CompressionResult]:
+        """Run ``compress()`` on each conversation in ``conversations``."""
+        if not isinstance(conversations, list):
+            raise TypeError("conversations must be a list")
+        return [
+            self.compress(
+                messages,
+                token_budget=token_budget,
+                compression=compression,
+                stages=stages,
+                disable=disable,
+                return_stats=return_stats,
+                dry_run=dry_run,
+            )
+            for messages in conversations
+        ]
+
     async def compress_async(
         self,
         messages: Any,

{contextpress-0.5.2 → contextpress-0.5.4}/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.4/examples/agent_pipeline.py

@@ -0,0 +1,29 @@
+"""Agent thread compression — ``type=\"agent\"`` for tool-using pipelines."""
+
+from __future__ import annotations
+
+from contextpress import ContextManager
+
+messages = [
+    {"role": "system", "content": "You are a task agent with tools."},
+    {"role": "user", "content": "Check whether api-v2 is deployed to staging."},
+    {
+        "role": "assistant",
+        "content": "Checking deploy status <tool_call> get_deploy_status(api-v2)",
+    },
+    {"role": "user", "content": "We've decided on using the new pipeline for deploy."},
+    {"role": "assistant", "content": "Confirmed — staging deploy is scheduled."},
+    {"role": "user", "content": "What's the current status?"},
+    {"role": "assistant", "content": "Basically, honestly, " + "still rolling out " * 30},
+]
+
+cm = ContextManager(type="agent", compression="high")
+result = cm.compress(messages, token_budget=300, return_stats=True)
+
+print("context type:", result.stats.context_type)
+print("turns:", result.stats.turns_before, "->", result.stats.turns_after)
+print("tokens:", result.stats.tokens_before, "->", result.stats.tokens_after)
+print("stages:", result.stats.stages_run)
+for i, m in enumerate(result.messages):
+    preview = str(m.get("content", ""))[:120]
+    print(i, m["role"] + ":", preview)

contextpress-0.5.4/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.4}/pyproject.toml

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

contextpress-0.5.4/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

contextpress-0.5.4/tests/test_v054.py

@@ -0,0 +1,53 @@
+import pytest
+
+from contextpress import CompressionResult, ContextManager
+
+
+def test_compress_many_returns_list():
+    cm = ContextManager(type="chat")
+    batches = [
+        [{"role": "user", "content": "hello basically"}],
+        [{"role": "user", "content": "thanks basically"}],
+    ]
+    out = cm.compress_many(batches, token_budget=200)
+    assert isinstance(out, list)
+    assert len(out) == 2
+    assert all(isinstance(item, list) for item in out)
+
+
+def test_compress_many_with_stats():
+    cm = ContextManager(type="chat")
+    batches = [
+        [{"role": "user", "content": "hello basically there"}],
+        [{"role": "assistant", "content": "sounds good"}],
+    ]
+    results = cm.compress_many(batches, token_budget=500, return_stats=True)
+    assert len(results) == 2
+    assert all(isinstance(r, CompressionResult) for r in results)
+    assert results[0].stats.turns_before == 1
+    assert results[1].stats.turns_before == 1
+
+
+def test_compress_many_empty():
+    cm = ContextManager(type="chat")
+    assert cm.compress_many([], token_budget=100) == []
+
+
+def test_compress_many_requires_list():
+    cm = ContextManager(type="chat")
+    with pytest.raises(TypeError, match="conversations must be a list"):
+        cm.compress_many("not a list")  # type: ignore[arg-type]
+
+
+def test_agent_pipeline_compresses():
+    cm = ContextManager(type="agent", compression="high")
+    messages = [
+        {"role": "system", "content": "Agent."},
+        {"role": "user", "content": "Deploy api-v2?"},
+        {"role": "assistant", "content": "Using pipeline <tool_call> deploy"},
+        {"role": "user", "content": "We've decided on using the new pipeline for deploy."},
+        {"role": "assistant", "content": "Confirmed."},
+    ]
+    result = cm.compress(messages, token_budget=200, return_stats=True)
+    assert result.stats.context_type == "agent"
+    assert result.stats.tokens_after <= result.stats.tokens_before