contextpress 0.3.0__tar.gz → 0.4.0__tar.gz

{contextpress-0.3.0 → contextpress-0.4.0}/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.4.0] - 2026-07-20
+
+- **`preview()` / `dry_run=True`** — simulate compression and get stats without changing messages (Tier 1 only; no LLM calls).
+- **`fits_budget()`** — check whether messages would fit a token budget after compression.
+- **`CompressionStats.warnings_emitted`** — pipeline warnings collected during a run.
+- **`OpenAICompatibleBackend`** — vLLM, LM Studio, LocalAI, and other OpenAI-compatible servers.
+- Example: `examples/dry_run_preview.py`.
+
 ## [0.3.0] - 2026-07-14
 
 - **`estimate_tokens(messages)`** — count tokens before compressing (same tiktoken encoding as budget).

{contextpress-0.3.0 → contextpress-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.3.0
+Version: 0.4.0
 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
@@ -296,6 +296,17 @@ Check token count **before** compressing:
 before = cm.estimate_tokens(messages)
 ```
 
+**Preview without changing messages** (0.4+):
+
+```python
+preview = cm.preview(messages, token_budget=500)
+print(preview.stats.tokens_saved, preview.stats.warnings_emitted)
+assert preview.messages == messages  # unchanged
+
+if cm.fits_budget(messages, 4000):
+    ...
+```
+
 ### Custom stages (0.3+)
 
 Register a `BaseStrategy` and include it in `stages=`:
@@ -491,7 +502,7 @@ Long chat histories inflate token usage, bury important facts (lost-in-the-middl
 
 ## Research and citing
 
-For academic use, cite this package in your paper’s software or methods section. A machine-readable citation file is provided as [`CITATION.cff`](CITATION.cff) (GitHub and Zenodo can ingest it). Replace the placeholder repository URL in that file with your fork’s URL when you publish.
+For academic use, cite this package in your paper’s software or methods section. A machine-readable citation file is provided as [`CITATION.cff`](CITATION.cff).
 
 ## Extension and growth
 

{contextpress-0.3.0 → contextpress-0.4.0}/README.md

@@ -56,6 +56,17 @@ Check token count **before** compressing:
 before = cm.estimate_tokens(messages)
 ```
 
+**Preview without changing messages** (0.4+):
+
+```python
+preview = cm.preview(messages, token_budget=500)
+print(preview.stats.tokens_saved, preview.stats.warnings_emitted)
+assert preview.messages == messages  # unchanged
+
+if cm.fits_budget(messages, 4000):
+    ...
+```
+
 ### Custom stages (0.3+)
 
 Register a `BaseStrategy` and include it in `stages=`:
@@ -251,7 +262,7 @@ Long chat histories inflate token usage, bury important facts (lost-in-the-middl
 
 ## Research and citing
 
-For academic use, cite this package in your paper’s software or methods section. A machine-readable citation file is provided as [`CITATION.cff`](CITATION.cff) (GitHub and Zenodo can ingest it). Replace the placeholder repository URL in that file with your fork’s URL when you publish.
+For academic use, cite this package in your paper’s software or methods section. A machine-readable citation file is provided as [`CITATION.cff`](CITATION.cff).
 
 ## Extension and growth
 

{contextpress-0.3.0 → contextpress-0.4.0}/contextpress/__init__.py

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

{contextpress-0.3.0 → contextpress-0.4.0}/contextpress/core.py

@@ -6,10 +6,11 @@ from typing import TYPE_CHECKING, Any
 
 from contextpress.compression import apply_stage_selection, normalize_compression_level
 from contextpress.normalizer import denormalize_output, normalize_messages
-from contextpress.pipeline import VALID_LLM_MODES, Pipeline
+from contextpress.pipeline import VALID_LLM_MODES, Pipeline, clone_conversation
 from contextpress.profiles import PROFILES, Profile, StageConfig
 from contextpress.registry import register_stage as _register_stage
 from contextpress.stats import CompressionResult, CompressionStats, count_conversation_tokens
+from contextpress.warnings_capture import capture_warnings
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -66,6 +67,45 @@ class ContextManager:
         conv, _ = normalize_messages(messages, context_type=self._type)
         return count_conversation_tokens(conv, model if model is not None else self.model)
 
+    def fits_budget(
+        self,
+        messages: Any,
+        token_budget: int,
+        *,
+        compression: str | None = None,
+        stages: list[str] | None = None,
+        disable: list[str] | None = None,
+    ) -> bool:
+        """Return True if ``messages`` would fit ``token_budget`` after compression (dry run)."""
+        preview = self.preview(
+            messages,
+            token_budget=token_budget,
+            compression=compression,
+            stages=stages,
+            disable=disable,
+        )
+        return preview.stats.tokens_after <= token_budget
+
+    def preview(
+        self,
+        messages: Any,
+        token_budget: int | None = None,
+        *,
+        compression: str | None = None,
+        stages: list[str] | None = None,
+        disable: list[str] | None = None,
+    ) -> CompressionResult:
+        """Dry-run compression: stats only, original ``messages`` returned unchanged."""
+        return self.compress(
+            messages,
+            token_budget=token_budget,
+            compression=compression,
+            stages=stages,
+            disable=disable,
+            return_stats=True,
+            dry_run=True,
+        )
+
     def register_stage(
         self,
         name: str,
@@ -87,12 +127,16 @@ class ContextManager:
         stages: list[str] | None = None,
         disable: list[str] | None = None,
         return_stats: bool = False,
+        dry_run: bool = False,
     ) -> Any | CompressionResult:
         """Run the pipeline; return value matches input shape (dict list, tuples, strings, etc.).
 
         ``token_budget`` must be a positive int or None. Unknown keys in ``disable`` are ignored.
         With ``return_stats=True``, returns a ``CompressionResult`` with ``messages`` and ``stats``.
+        With ``dry_run=True``, runs Tier 1 only (no LLM calls) and returns the original messages.
         """
+        if dry_run:
+            return_stats = True
         _validate_token_budget(token_budget)
         level = compression if compression is not None else self._compression
         profile = copy.deepcopy(self._profile)
@@ -119,8 +163,14 @@ class ContextManager:
             llm_mode=self.llm_mode,
             custom_stages=custom_stages,
         )
-        out = pipeline.run(conv, stats=stats)
-        messages_out = denormalize_output(out, ctx)
+        with capture_warnings() as captured:
+            out = pipeline.run(conv, stats=stats, dry_run=dry_run)
+        if stats is not None:
+            stats.warnings_emitted = captured
+        if dry_run:
+            messages_out = denormalize_output(clone_conversation(conv), ctx)
+        else:
+            messages_out = denormalize_output(out, ctx)
         if return_stats:
             assert stats is not None
             return CompressionResult(messages=messages_out, stats=stats)

contextpress-0.4.0/contextpress/llm/__init__.py

@@ -0,0 +1,15 @@
+from contextpress.llm.adapters import (
+    AnthropicBackend,
+    OllamaBackend,
+    OpenAIBackend,
+    OpenAICompatibleBackend,
+)
+from contextpress.llm.base import LLMBackend
+
+__all__ = [
+    "LLMBackend",
+    "OpenAIBackend",
+    "OpenAICompatibleBackend",
+    "AnthropicBackend",
+    "OllamaBackend",
+]

{contextpress-0.3.0 → contextpress-0.4.0}/contextpress/llm/adapters.py

@@ -221,3 +221,44 @@ class OllamaBackend(LLMBackend):
         except Exception as exc:
             warnings.warn(f"contextpress OllamaBackend.deduplicate failed: {exc}", stacklevel=2)
             return list(range(len(turns)))
+
+
+class OpenAICompatibleBackend(OpenAIBackend):
+    """
+    Adapter for **OpenAI-compatible HTTP APIs** (vLLM, LM Studio, LocalAI, etc.).
+
+    Requires: ``pip install openai``
+
+    Usage::
+
+        from contextpress.llm.adapters import OpenAICompatibleBackend
+
+        backend = OpenAICompatibleBackend(
+            base_url="http://localhost:8000/v1",
+            model="mistral",
+        )
+        cm = ContextManager(type="chat", llm_backend=backend)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        model: str,
+        *,
+        api_key: str = "not-needed",
+        client: Any | None = None,
+    ):
+        if client is not None:
+            super().__init__(client=client, model=model)
+            return
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise ImportError(
+                "OpenAICompatibleBackend requires the 'openai' package. "
+                "Install with: pip install openai"
+            ) from exc
+        super().__init__(
+            client=OpenAI(base_url=base_url, api_key=api_key),
+            model=model,
+        )

{contextpress-0.3.0 → contextpress-0.4.0}/contextpress/pipeline.py

@@ -107,12 +107,15 @@ class Pipeline:
         self,
         conversation: Conversation,
         stats: CompressionStats | None = None,
+        *,
+        dry_run: bool = False,
     ) -> Conversation:
         if stats is not None:
             stats.turns_before = len(conversation.turns)
             stats.tokens_before = count_conversation_tokens(conversation, self.model)
             stats.context_type = conversation.type
             stats.token_budget = self.token_budget
+            stats.dry_run = dry_run
 
         result = clone_conversation(conversation)
         stage_order = effective_stage_order()
@@ -131,7 +134,7 @@ class Pipeline:
                 if delta != 0:
                     stats.turn_delta_by_stage[stage_name] = delta
 
-        if self.llm_backend is not None:
+        if self.llm_backend is not None and not dry_run:
             result = self._run_llm_tier(result, stats=stats)
 
         if stats is not None:

{contextpress-0.3.0 → contextpress-0.4.0}/contextpress/stats.py

@@ -49,6 +49,8 @@ class CompressionStats:
     compression_level: str | None = None
     context_type: str = "chat"
     token_budget: int | None = None
+    dry_run: bool = False
+    warnings_emitted: list[str] = field(default_factory=list)
 
     @property
     def turns_removed(self) -> int:

contextpress-0.4.0/contextpress/warnings_capture.py

@@ -0,0 +1,16 @@
+"""Capture warnings emitted during compression into ``CompressionStats``."""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Generator
+from contextlib import contextmanager
+
+
+@contextmanager
+def capture_warnings() -> Generator[list[str], None, None]:
+    captured: list[str] = []
+    with warnings.catch_warnings(record=True) as caught:
+        warnings.simplefilter("always")
+        yield captured
+    captured.extend(str(item.message) for item in caught)

contextpress-0.4.0/examples/dry_run_preview.py

@@ -0,0 +1,23 @@
+"""Dry-run preview: see compression stats without changing messages."""
+
+from __future__ import annotations
+
+from contextpress import ContextManager
+
+messages = [
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "Old topic: " + "blah " * 60},
+    {"role": "assistant", "content": "Basically, honestly, " + "yak " * 60},
+    {"role": "user", "content": "What is 2+2?"},
+    {"role": "assistant", "content": "Four."},
+]
+
+cm = ContextManager(type="chat", compression="medium")
+preview = cm.preview(messages, token_budget=150)
+
+print("dry_run:", preview.stats.dry_run)
+print("tokens:", preview.stats.tokens_before, "->", preview.stats.tokens_after)
+print("would fit budget 150:", cm.fits_budget(messages, 150))
+print("messages unchanged:", preview.messages == messages)
+if preview.stats.warnings_emitted:
+    print("warnings:", preview.stats.warnings_emitted)

{contextpress-0.3.0 → contextpress-0.4.0}/pyproject.toml

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

contextpress-0.4.0/tests/test_v04.py

@@ -0,0 +1,51 @@
+from unittest.mock import MagicMock
+
+from contextpress import ContextManager
+from contextpress.llm.adapters import OpenAICompatibleBackend
+
+
+def test_preview_returns_original_messages():
+    cm = ContextManager(type="chat")
+    messages = [
+        {"role": "user", "content": "hello basically there"},
+        {"role": "assistant", "content": "hi"},
+    ]
+    preview = cm.preview(messages, token_budget=500)
+    assert preview.messages == messages
+    assert preview.stats.dry_run is True
+    assert preview.stats.tokens_before >= preview.stats.tokens_after
+
+
+def test_dry_run_skips_llm_backend():
+    backend = MagicMock()
+    cm = ContextManager(type="chat", llm_backend=backend, llm_min_input_chars=0)
+    messages = [{"role": "user", "content": "hello " * 500}]
+    preview = cm.preview(messages, token_budget=100)
+    backend.deduplicate.assert_not_called()
+    backend.summarize.assert_not_called()
+    assert preview.stats.llm_tier_applied is False
+
+
+def test_fits_budget():
+    cm = ContextManager(type="chat", compression="low")
+    messages = [{"role": "user", "content": "short"}]
+    assert cm.fits_budget(messages, 500) is True
+
+
+def test_warnings_captured_on_budget_truncation():
+    cm = ContextManager(type="chat")
+    messages = [
+        {"role": "user", "content": "word " * 200},
+        {"role": "assistant", "content": "reply " * 200},
+        {"role": "user", "content": "recent"},
+        {"role": "assistant", "content": "ok"},
+    ]
+    preview = cm.preview(messages, token_budget=20, compression="low")
+    assert any("token budget" in w.lower() for w in preview.stats.warnings_emitted)
+
+
+def test_openai_compatible_backend_init():
+    client = MagicMock()
+    backend = OpenAICompatibleBackend(base_url="http://localhost:8000/v1", model="x", client=client)
+    assert backend.model == "x"
+    assert backend.client is client

contextpress-0.3.0/contextpress/llm/__init__.py

@@ -1,4 +0,0 @@
-from contextpress.llm.adapters import AnthropicBackend, OllamaBackend, OpenAIBackend
-from contextpress.llm.base import LLMBackend
-
-__all__ = ["LLMBackend", "OpenAIBackend", "AnthropicBackend", "OllamaBackend"]