contextpress 0.2.0__tar.gz → 0.4.0__tar.gz

{contextpress-0.2.0 → contextpress-0.4.0}/.gitignore

@@ -29,3 +29,6 @@ htmlcov/
 *.swp
 .DS_Store
 Thumbs.db
+
+# Secrets (never commit)
+.env

contextpress-0.4.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+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).
+- **Stage registry** — `ContextManager.register_stage()` for custom `BaseStrategy` stages in `stages=[...]`.
+- **Tier 2 `llm_mode`** — `replace_all` (default), `dedupe_only`, or `summarize_only`.
+- Example: `examples/estimate_and_stats.py`.
+
+## [0.2.0] - 2026-05-24
+
+- **`return_stats=True`** on `ContextManager.compress()` returns a `CompressionResult` with token/turn counts, stages run, and per-stage turn deltas.
+- **Tier 2 deduplication** implemented in OpenAI, Anthropic, and Ollama adapters (LLM selects indices to keep).
+- **GitHub Actions CI** runs `pytest` on Python 3.10–3.13.
+- Added **`CONTRIBUTING.md`** with contribution and review expectations.
+
+## [0.1.0] - 2026-04-19
+
+- Initial release by Taha Azizi.
+- Tier 1 pipeline (filler, repetition, resolution, recency, budget) and optional Tier 2 `LLMBackend` (OpenAI, Anthropic, Ollama adapters).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.2.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
@@ -290,6 +290,38 @@ print(result.stats.tokens_saved, result.stats.stages_run)
 compressed = result.messages
 ```
 
+Check token count **before** compressing:
+
+```python
+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=`:
+
+```python
+from contextpress.strategies.base import BaseStrategy
+
+class MyStage(BaseStrategy):
+    def process(self, conversation):
+        ...
+
+cm.register_stage("my_stage", MyStage)
+out = cm.compress(messages, stages=["filler", "my_stage", "budget"], token_budget=500)
+```
+
 ### Minimal examples
 
 ```python
@@ -405,7 +437,9 @@ After **Tier 1** finishes, you can attach an **`LLMBackend`** for semantic compr
 2. If the combined transcript is long enough (default **1500** characters; set **`llm_min_input_chars=0`** to always run), calls **`summarize(transcript, max_tokens)`**.
 3. **System turns are unchanged** in order and content. **All other turns are replaced** by a **single assistant** message whose content is the LLM summary (metadata includes `source: contextpress_llm_tier`). If the LLM call fails, the Tier 1 conversation is returned and a **warning** is emitted.
 
-Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens`**.
+Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens`**, **`llm_mode`**.
+
+**`llm_mode`** (0.3+): `replace_all` (default — dedupe then one summary turn), `dedupe_only` (dedupe, keep turns), `summarize_only` (append summary, keep turns).
 
 **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.
 
@@ -468,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.2.0 → contextpress-0.4.0}/README.md

@@ -50,6 +50,38 @@ print(result.stats.tokens_saved, result.stats.stages_run)
 compressed = result.messages
 ```
 
+Check token count **before** compressing:
+
+```python
+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=`:
+
+```python
+from contextpress.strategies.base import BaseStrategy
+
+class MyStage(BaseStrategy):
+    def process(self, conversation):
+        ...
+
+cm.register_stage("my_stage", MyStage)
+out = cm.compress(messages, stages=["filler", "my_stage", "budget"], token_budget=500)
+```
+
 ### Minimal examples
 
 ```python
@@ -165,7 +197,9 @@ After **Tier 1** finishes, you can attach an **`LLMBackend`** for semantic compr
 2. If the combined transcript is long enough (default **1500** characters; set **`llm_min_input_chars=0`** to always run), calls **`summarize(transcript, max_tokens)`**.
 3. **System turns are unchanged** in order and content. **All other turns are replaced** by a **single assistant** message whose content is the LLM summary (metadata includes `source: contextpress_llm_tier`). If the LLM call fails, the Tier 1 conversation is returned and a **warning** is emitted.
 
-Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens`**.
+Optional constructor knobs: **`llm_min_input_chars`**, **`llm_max_summary_tokens`**, **`llm_mode`**.
+
+**`llm_mode`** (0.3+): `replace_all` (default — dedupe then one summary turn), `dedupe_only` (dedupe, keep turns), `summarize_only` (append summary, keep turns).
 
 **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.
 
@@ -228,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.2.0 → contextpress-0.4.0}/contextpress/__init__.py

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

{contextpress-0.2.0 → contextpress-0.4.0}/contextpress/compression.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from contextpress.profiles import Profile
+from contextpress.profiles import Profile, StageConfig
 
 STAGE_ORDER: tuple[str, ...] = (
     "filler",
@@ -14,6 +14,14 @@ STAGE_ORDER: tuple[str, ...] = (
 
 VALID_STAGES = frozenset(STAGE_ORDER)
 
+
+def known_stages() -> frozenset[str]:
+    """Built-in plus registered custom stage names."""
+    from contextpress.registry import registered_stage_names
+
+    return VALID_STAGES | registered_stage_names()
+
+
 _NON_BUDGET_ORDER: tuple[str, ...] = tuple(s for s in STAGE_ORDER if s != "budget")
 
 # NLP stages only; budget is toggled from token_budget (see apply_stage_selection)
@@ -38,6 +46,7 @@ __all__ = [
     "STAGE_ORDER",
     "VALID_STAGES",
     "apply_stage_selection",
+    "known_stages",
     "normalize_compression_level",
 ]
 
@@ -60,6 +69,7 @@ def apply_stage_selection(
     stages: list[str] | None,
     disable: list[str] | None,
     token_budget: int | None,
+    custom_stages: dict[str, StageConfig] | None = None,
 ) -> None:
     """
     Mutates ``profile`` in place: sets each stage's ``enabled`` from explicit
@@ -70,12 +80,15 @@ def apply_stage_selection(
     if stages is not None:
         if not stages:
             raise ValueError("stages= must list at least one stage name when provided")
-        unknown = [s for s in stages if s not in VALID_STAGES]
+        unknown = [s for s in stages if s not in known_stages()]
         if unknown:
-            raise ValueError(f"unknown stage name(s): {unknown}; valid: {sorted(VALID_STAGES)}")
+            raise ValueError(f"unknown stage name(s): {unknown}; valid: {sorted(known_stages())}")
         want = frozenset(stages)
         for name in _NON_BUDGET_ORDER:
             getattr(profile, name).enabled = name in want
+        if custom_stages:
+            for name, cfg in custom_stages.items():
+                cfg.enabled = name in want
     else:
         level = normalize_compression_level(compression)
         preset = _COMPRESSION_PRESETS[level]
@@ -85,6 +98,9 @@ def apply_stage_selection(
 
     if disable:
         for name in disable:
+            if custom_stages and name in custom_stages:
+                custom_stages[name].enabled = False
+                continue
             if not hasattr(profile, name):
                 continue
             getattr(profile, name).enabled = False

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

@@ -6,12 +6,17 @@ 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 Pipeline
+from contextpress.pipeline import VALID_LLM_MODES, Pipeline, clone_conversation
 from contextpress.profiles import PROFILES, Profile, StageConfig
-from contextpress.stats import CompressionResult, CompressionStats
+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
+
     from contextpress.llm.base import LLMBackend
+    from contextpress.strategies.base import BaseStrategy
 
 
 def _validate_token_budget(token_budget: int | None) -> None:
@@ -39,9 +44,14 @@ class ContextManager:
         compression: str = "medium",
         llm_min_input_chars: int = 1500,
         llm_max_summary_tokens: int = 2048,
+        llm_mode: str = "replace_all",
     ):
         if type not in PROFILES:
             raise ValueError(f"unknown context type {type!r}")
+        if llm_mode not in VALID_LLM_MODES:
+            raise ValueError(
+                f"unknown llm_mode {llm_mode!r}; use one of: {sorted(VALID_LLM_MODES)}"
+            )
         self._type = type
         self._profile: Profile = copy.deepcopy(PROFILES[type])
         self._compression: str = normalize_compression_level(compression)
@@ -49,6 +59,64 @@ class ContextManager:
         self.llm_backend = llm_backend
         self.llm_min_input_chars = int(llm_min_input_chars)
         self.llm_max_summary_tokens = int(llm_max_summary_tokens)
+        self.llm_mode = llm_mode
+        self._custom_stages: dict[str, StageConfig] = {}
+
+    def estimate_tokens(self, messages: Any, *, model: str | None = None) -> int:
+        """Count tokens for ``messages`` using the same encoding as the budget stage."""
+        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,
+        factory: Callable[..., BaseStrategy],
+        *,
+        before: str = "budget",
+        aggressiveness: float = 0.5,
+    ) -> None:
+        """Register a custom pipeline stage (see ``contextpress.registry``)."""
+        _register_stage(name, factory, before=before)
+        self._custom_stages[name] = StageConfig(enabled=False, aggressiveness=aggressiveness)
 
     def compress(
         self,
@@ -59,15 +127,20 @@ 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)
+        custom_stages = copy.deepcopy(self._custom_stages)
         apply_stage_selection(
             profile,
             base_profile=self._profile,
@@ -75,6 +148,7 @@ class ContextManager:
             stages=stages,
             disable=disable,
             token_budget=token_budget,
+            custom_stages=custom_stages,
         )
 
         conv, ctx = normalize_messages(messages, context_type=self._type)
@@ -86,9 +160,17 @@ class ContextManager:
             llm_backend=self.llm_backend,
             llm_min_input_chars=self.llm_min_input_chars,
             llm_max_summary_tokens=self.llm_max_summary_tokens,
+            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)
@@ -100,9 +182,12 @@ class ContextManager:
 
     def configure(self, stage: str, **kwargs: Any) -> None:
         """Patch ``StageConfig`` fields on the live profile (e.g. aggressiveness, enabled)."""
-        if not hasattr(self._profile, stage):
+        if stage in self._custom_stages:
+            sc = self._custom_stages[stage]
+        elif hasattr(self._profile, stage):
+            sc = getattr(self._profile, stage)
+        else:
             raise ValueError(f"unknown stage {stage!r}")
-        sc: StageConfig = getattr(self._profile, stage)
         for k, v in kwargs.items():
             if hasattr(sc, k):
                 setattr(sc, k, v)

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.2.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.2.0 → contextpress-0.4.0}/contextpress/pipeline.py

@@ -27,6 +27,11 @@ from contextpress.compression import STAGE_ORDER
 from contextpress.models import Conversation, Turn
 from contextpress.normalizer import extract_text_for_processing
 from contextpress.profiles import Profile, StageConfig
+from contextpress.registry import (
+    build_custom_strategy,
+    effective_stage_order,
+    registered_stage_names,
+)
 from contextpress.stats import CompressionStats, count_conversation_tokens
 from contextpress.strategies.base import BaseStrategy
 from contextpress.strategies.budget import BudgetStrategy
@@ -38,6 +43,8 @@ from contextpress.strategies.resolution import ResolutionStrategy
 if TYPE_CHECKING:
     from contextpress.llm.base import LLMBackend
 
+VALID_LLM_MODES = frozenset({"replace_all", "dedupe_only", "summarize_only"})
+
 
 def clone_turn(t: Turn) -> Turn:
     if isinstance(t.content, str):
@@ -80,6 +87,8 @@ class Pipeline:
         *,
         llm_min_input_chars: int = 1500,
         llm_max_summary_tokens: int = 2048,
+        llm_mode: str = "replace_all",
+        custom_stages: dict[str, StageConfig] | None = None,
     ):
         self.profile = profile
         self.token_budget = token_budget
@@ -87,24 +96,34 @@ class Pipeline:
         self.llm_backend = llm_backend  # None = Tier 1 only
         self.llm_min_input_chars = max(0, int(llm_min_input_chars))
         self.llm_max_summary_tokens = max(64, int(llm_max_summary_tokens))
+        if llm_mode not in VALID_LLM_MODES:
+            raise ValueError(
+                f"unknown llm_mode {llm_mode!r}; use one of: {sorted(VALID_LLM_MODES)}"
+            )
+        self.llm_mode = llm_mode
+        self.custom_stages = custom_stages or {}
 
     def run(
         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)
-        for stage_name in self.STAGE_ORDER:
+        stage_order = effective_stage_order()
+        for stage_name in stage_order:
             if stage_name == "budget" and self.token_budget is None:
                 continue
-            stage_config = getattr(self.profile, stage_name)
-            if not stage_config.enabled:
+            stage_config = self._stage_config(stage_name)
+            if stage_config is None or not stage_config.enabled:
                 continue
             before_turns = len(result.turns)
             strategy = self._build_strategy(stage_name, stage_config)
@@ -115,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:
@@ -124,12 +143,26 @@ class Pipeline:
 
         return result
 
+    def _stage_config(self, name: str) -> StageConfig | None:
+        if name in self.custom_stages:
+            return self.custom_stages[name]
+        if hasattr(self.profile, name):
+            return getattr(self.profile, name)
+        return None
+
     def _build_strategy(self, name: str, config: StageConfig) -> BaseStrategy:
         kwargs: dict[str, Any] = {
             "aggressiveness": config.aggressiveness,
             "conv_type": self.profile.name,
             "role_aware": self.profile.role_aware,
         }
+        if name in registered_stage_names():
+            return build_custom_strategy(
+                name,
+                config,
+                conv_type=self.profile.name,
+                role_aware=self.profile.role_aware,
+            )
         if name == "filler":
             return FillerStrategy(**kwargs)
         if name == "repetition":
@@ -166,25 +199,36 @@ class Pipeline:
             stats.llm_dedup_turns_before = len(ns_turns)
 
         texts = [extract_text_for_processing(t) for t in ns_turns]
-        try:
-            keep_idx = self.llm_backend.deduplicate(texts)
-        except Exception:
-            keep_idx = list(range(len(ns_turns)))
-        valid = sorted(
-            {
-                i
-                for i in keep_idx
-                if type(i) is int and not isinstance(i, bool) and 0 <= i < len(ns_turns)
-            }
-        )
-        if not valid:
-            valid = list(range(len(ns_turns)))
-        if len(valid) < len(ns_turns):
-            ns_turns = [ns_turns[i] for i in valid]
-            texts = [texts[i] for i in valid]
+        if self.llm_mode in ("replace_all", "dedupe_only"):
+            try:
+                keep_idx = self.llm_backend.deduplicate(texts)
+            except Exception:
+                keep_idx = list(range(len(ns_turns)))
+            valid = sorted(
+                {
+                    i
+                    for i in keep_idx
+                    if type(i) is int and not isinstance(i, bool) and 0 <= i < len(ns_turns)
+                }
+            )
+            if not valid:
+                valid = list(range(len(ns_turns)))
+            if len(valid) < len(ns_turns):
+                ns_turns = [ns_turns[i] for i in valid]
+                texts = [texts[i] for i in valid]
 
-        if stats is not None:
-            stats.llm_dedup_turns_after = len(ns_turns)
+            if stats is not None:
+                stats.llm_dedup_turns_after = len(ns_turns)
+
+            if self.llm_mode == "dedupe_only":
+                new_turns = list(system_turns) + [clone_turn(t) for t in ns_turns]
+                if stats is not None:
+                    stats.llm_tier_applied = True
+                return Conversation(
+                    turns=new_turns,
+                    type=conversation.type,
+                    metadata=copy.deepcopy(conversation.metadata),
+                )
 
         lines = [f"{t.role}: {txt}" for t, txt in zip(ns_turns, texts, strict=True)]
         combined = "\n\n".join(lines)
@@ -207,6 +251,22 @@ class Pipeline:
         if stats is not None:
             stats.llm_tier_applied = True
 
+        if self.llm_mode == "summarize_only":
+            new_turns = list(system_turns) + [clone_turn(t) for t in ns_turns]
+            new_turns.append(
+                Turn(
+                    role="assistant",
+                    content=summary,
+                    metadata={"source": "contextpress_llm_tier", "mode": "summarize_only"},
+                    compressed=True,
+                )
+            )
+            return Conversation(
+                turns=new_turns,
+                type=conversation.type,
+                metadata=copy.deepcopy(conversation.metadata),
+            )
+
         new_turns: list[Turn] = list(system_turns)
         new_turns.append(
             Turn(

contextpress-0.4.0/contextpress/registry.py

@@ -0,0 +1,85 @@
+"""Register custom pipeline stages without subclassing ``Pipeline``."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from contextpress.profiles import StageConfig
+from contextpress.strategies.base import BaseStrategy
+
+# (name, factory, insert_before)
+_CustomEntry = tuple[str, Callable[..., BaseStrategy], str]
+_REGISTRY: list[_CustomEntry] = []
+
+
+def _builtin_stages() -> tuple[str, ...]:
+    from contextpress.compression import STAGE_ORDER
+
+    return STAGE_ORDER
+
+
+def register_stage(
+    name: str,
+    factory: Callable[..., BaseStrategy],
+    *,
+    before: str = "budget",
+) -> None:
+    """Register a custom stage factory.
+
+    ``factory`` receives ``aggressiveness``, ``conv_type``, ``role_aware``, and
+    optional ``**kwargs`` — same as built-in strategies. Custom stages run when
+    named in ``stages=`` on ``compress()``.
+
+    Parameters
+    ----------
+    name:
+        Unique stage name (must not collide with a built-in stage).
+    before:
+        Built-in or custom stage name to insert before (default: ``budget``).
+    """
+    if not name or name in _builtin_stages():
+        raise ValueError(f"cannot register stage {name!r}: name invalid or reserved")
+    if any(e[0] == name for e in _REGISTRY):
+        raise ValueError(f"stage {name!r} is already registered")
+    _REGISTRY.append((name, factory, before))
+
+
+def registered_stage_names() -> frozenset[str]:
+    return frozenset(name for name, _, _ in _REGISTRY)
+
+
+def clear_registry() -> None:
+    """Remove all custom stages (for tests)."""
+    _REGISTRY.clear()
+
+
+def effective_stage_order() -> list[str]:
+    """Built-in ``STAGE_ORDER`` with registered custom stages inserted."""
+    order = list(_builtin_stages())
+    for name, _, before in _REGISTRY:
+        if before not in order:
+            raise RuntimeError(f"custom stage {name!r}: anchor {before!r} not in stage order")
+        order.insert(order.index(before), name)
+    return order
+
+
+def build_custom_strategy(
+    name: str,
+    config: StageConfig,
+    *,
+    conv_type: str,
+    role_aware: bool,
+    extra_kwargs: dict[str, Any] | None = None,
+) -> BaseStrategy:
+    for reg_name, factory, _ in _REGISTRY:
+        if reg_name == name:
+            kwargs: dict[str, Any] = {
+                "aggressiveness": config.aggressiveness,
+                "conv_type": conv_type,
+                "role_aware": role_aware,
+            }
+            if extra_kwargs:
+                kwargs.update(extra_kwargs)
+            return factory(**kwargs)
+    raise ValueError(f"no registered factory for custom stage {name!r}")

{contextpress-0.2.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.4.0/examples/estimate_and_stats.py

@@ -0,0 +1,21 @@
+"""Estimate tokens before compressing, then inspect stats after."""
+
+from contextpress import ContextManager
+
+messages = [
+    {"role": "system", "content": "You are helpful."},
+    {"role": "user", "content": "Old topic: " + "blah " * 50},
+    {"role": "assistant", "content": "Basically, honestly, " + "yak " * 50},
+    {"role": "user", "content": "What is 2+2?"},
+    {"role": "assistant", "content": "Four."},
+]
+
+cm = ContextManager(type="chat", compression="medium")
+before = cm.estimate_tokens(messages)
+print("tokens before:", before)
+
+result = cm.compress(messages, token_budget=200, return_stats=True)
+print("tokens after:", result.stats.tokens_after)
+print("saved:", result.stats.tokens_saved)
+print("stages:", result.stats.stages_run)
+print("turns:", result.stats.turns_before, "->", result.stats.turns_after)

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

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

@@ -0,0 +1,128 @@
+import copy
+
+import pytest
+
+from contextpress import ContextManager
+from contextpress.compression import known_stages
+from contextpress.models import Conversation, Turn
+from contextpress.pipeline import Pipeline
+from contextpress.profiles import PROFILES
+from contextpress.registry import clear_registry, register_stage
+from contextpress.strategies.base import BaseStrategy
+
+
+class _DropMarkedStrategy(BaseStrategy):
+    def process(self, conversation: Conversation) -> Conversation:
+        kept = [
+            copy.deepcopy(t)
+            for t in conversation.turns
+            if t.role == "system"
+            or "DROP" not in (t.content if isinstance(t.content, str) else str(t.content))
+        ]
+        return Conversation(
+            turns=kept,
+            type=conversation.type,
+            metadata=copy.deepcopy(conversation.metadata),
+        )
+
+
+@pytest.fixture(autouse=True)
+def _reset_registry():
+    clear_registry()
+    yield
+    clear_registry()
+
+
+def test_estimate_tokens_dict_list():
+    cm = ContextManager(type="chat")
+    messages = [
+        {"role": "user", "content": "Hello world"},
+        {"role": "assistant", "content": "Hi there"},
+    ]
+    n = cm.estimate_tokens(messages)
+    assert isinstance(n, int) and n > 0
+
+
+def test_register_stage_and_run():
+    cm = ContextManager(type="chat")
+    cm.register_stage("drop_marked", _DropMarkedStrategy)
+    assert "drop_marked" in known_stages()
+    messages = [
+        {"role": "user", "content": "keep me"},
+        {"role": "assistant", "content": "DROP this turn"},
+    ]
+    out = cm.compress(messages, stages=["drop_marked"])
+    assert len(out) == 1
+    assert out[0]["content"] == "keep me"
+
+
+def test_register_stage_reserved_name_raises():
+    with pytest.raises(ValueError):
+        register_stage("filler", _DropMarkedStrategy)
+
+
+def test_configure_custom_stage():
+    cm = ContextManager(type="chat")
+    cm.register_stage("drop_marked", _DropMarkedStrategy, aggressiveness=0.2)
+    cm.configure("drop_marked", aggressiveness=0.9)
+    assert cm._custom_stages["drop_marked"].aggressiveness == 0.9
+
+
+class _DedupOnlyBackend:
+    def summarize(self, text: str, max_tokens: int) -> str:
+        raise AssertionError("summarize should not run in dedupe_only mode")
+
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        return [0]
+
+
+class _SummarizeOnlyBackend:
+    def summarize(self, text: str, max_tokens: int) -> str:
+        return "summary appended"
+
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        raise AssertionError("deduplicate should not run in summarize_only mode")
+
+
+def test_llm_mode_dedupe_only():
+    conv = Conversation(
+        turns=[
+            Turn(role="user", content="hello"),
+            Turn(role="user", content="hello again"),
+        ],
+        type="chat",
+    )
+    p = Pipeline(
+        PROFILES["chat"],
+        token_budget=None,
+        llm_backend=_DedupOnlyBackend(),
+        llm_mode="dedupe_only",
+        llm_min_input_chars=0,
+    )
+    out = p.run(conv)
+    assert len(out.turns) == 1
+    assert out.turns[0].content == "hello"
+
+
+def test_llm_mode_summarize_only():
+    conv = Conversation(
+        turns=[Turn(role="user", content="hello " * 200)],
+        type="chat",
+    )
+    p = Pipeline(
+        PROFILES["chat"],
+        token_budget=None,
+        llm_backend=_SummarizeOnlyBackend(),
+        llm_mode="summarize_only",
+        llm_min_input_chars=0,
+    )
+    out = p.run(conv)
+    assert len(out.turns) == 2
+    assert out.turns[0].role == "user"
+    assert out.turns[1].content == "summary appended"
+    assert out.turns[1].metadata.get("mode") == "summarize_only"
+
+
+def test_invalid_llm_mode_raises():
+    with pytest.raises(ValueError):
+        ContextManager(llm_mode="invalid")

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.2.0/CHANGELOG.md

@@ -1,17 +0,0 @@
-# Changelog
-
-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.2.0] - 2026-05-24
-
-- **`return_stats=True`** on `ContextManager.compress()` returns a `CompressionResult` with token/turn counts, stages run, and per-stage turn deltas.
-- **Tier 2 deduplication** implemented in OpenAI, Anthropic, and Ollama adapters (LLM selects indices to keep).
-- **GitHub Actions CI** runs `pytest` on Python 3.10–3.13.
-- Added **`CONTRIBUTING.md`** with contribution and review expectations.
-
-## [0.1.0] - 2026-04-19
-
-- Initial release by Taha Azizi.
-- Tier 1 pipeline (filler, repetition, resolution, recency, budget) and optional Tier 2 `LLMBackend` (OpenAI, Anthropic, Ollama adapters).

contextpress-0.2.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"]