contextpress 0.1.0__tar.gz → 0.2.0__tar.gz

contextpress-0.2.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# 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/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to contextpress
+
+Thank you for your interest in contributing. This project is maintained by [Taha Azizi](https://github.com/Taha-azizi) at a **low cadence**. Bug fixes are welcome; large feature work may be better suited to a fork if you need it quickly.
+
+## Before you start
+
+- Read the [Project Status](README.md#project-status) section in the README.
+- Search [existing issues](https://github.com/Taha-azizi/contextpress/issues) before opening a duplicate.
+- Expect a **2–4 week** review cycle for pull requests.
+
+## Branches
+
+| Branch | Purpose |
+|--------|---------|
+| **`dev`** | Active development — **branch from here, open PRs here** |
+| **`main`** | Stable releases (merged from `dev` at release time) |
+
+After cloning:
+
+```bash
+git checkout dev
+```
+
+## How to contribute
+
+1. **Fork** the repository and create a feature branch from **`dev`** (not `main`).
+2. **Set up** a local environment:
+   ```bash
+   pip install -e ".[dev]"
+   pytest tests -q
+   ```
+3. **Make focused changes** — one logical change per PR when possible.
+4. **Add or update tests** for behavior you change. Tier 1 tests must stay deterministic (no live LLM calls in `tests/`).
+5. **Open a pull request** targeting **`dev`** with:
+   - A short summary of *why* the change is needed
+   - How you tested it (`pytest tests -q`, etc.)
+   - A note if you changed public API (update `CHANGELOG.md`)
+
+## Code guidelines
+
+- Match existing style in the file you edit.
+- Do not break the [behavior contract](contextpress/pipeline.py) at the top of `pipeline.py`.
+- System turns stay protected; input is never mutated in place.
+- Keep Tier 1 deterministic — mock LLM backends in tests.
+
+## Reporting bugs
+
+Open a [GitHub issue](https://github.com/Taha-azizi/contextpress/issues) with:
+
+- Python version
+- `contextpress` version (`pip show contextpress`)
+- Minimal input that reproduces the problem
+- Expected vs actual behavior
+
+## Feature requests
+
+Feature requests may be accepted, deferred, or closed with a suggestion to fork. That is not a rejection of the idea — it reflects limited maintenance bandwidth.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the [Apache License 2.0](LICENSE).

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextpress
-Version: 0.1.0
+Version: 0.2.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
@@ -282,6 +282,14 @@ compressed = cm.compress(messages, token_budget=2000)
 
 No API keys are required for Tier 1. Passing **`token_budget`** turns on the **budget** stage; other stages follow the chosen **compression** preset (`low` / `medium` / `high`).
 
+Pass **`return_stats=True`** to get a `CompressionResult` with `messages` and compression stats (token counts, stages run, turn deltas):
+
+```python
+result = cm.compress(messages, token_budget=2000, return_stats=True)
+print(result.stats.tokens_saved, result.stats.stages_run)
+compressed = result.messages
+```
+
 ### Minimal examples
 
 ```python

{contextpress-0.1.0 → contextpress-0.2.0}/README.md

@@ -42,6 +42,14 @@ compressed = cm.compress(messages, token_budget=2000)
 
 No API keys are required for Tier 1. Passing **`token_budget`** turns on the **budget** stage; other stages follow the chosen **compression** preset (`low` / `medium` / `high`).
 
+Pass **`return_stats=True`** to get a `CompressionResult` with `messages` and compression stats (token counts, stages run, turn deltas):
+
+```python
+result = cm.compress(messages, token_budget=2000, return_stats=True)
+print(result.stats.tokens_saved, result.stats.stages_run)
+compressed = result.messages
+```
+
 ### Minimal examples
 
 ```python

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/__init__.py

@@ -4,15 +4,22 @@ from typing import Any
 
 from contextpress._bootstrap import bootstrap_nltk
 from contextpress.models import ContentBlock, Conversation, Turn
+from contextpress.stats import CompressionResult, CompressionStats
 
 bootstrap_nltk()
 
-__all__ = ["ContextManager", "Turn", "Conversation", "ContentBlock"]
-__version__ = "0.1.0"
+__all__ = [
+    "ContextManager",
+    "Turn",
+    "Conversation",
+    "ContentBlock",
+    "CompressionResult",
+    "CompressionStats",
+]
+__version__ = "0.2.0"
 
 
 def __getattr__(name: str) -> Any:
-    # Lazy import: ContextManager -> core -> pipeline -> strategies (sumy, etc.)
     if name == "ContextManager":
         from contextpress.core import ContextManager
 

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

@@ -98,4 +98,4 @@ def apply_stage_selection(
         if disable and "budget" in disable:
             profile.budget.enabled = False
         else:
-            profile.budget.enabled = getattr(base_profile, "budget").enabled
+            profile.budget.enabled = base_profile.budget.enabled

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

@@ -8,6 +8,7 @@ from contextpress.compression import apply_stage_selection, normalize_compressio
 from contextpress.normalizer import denormalize_output, normalize_messages
 from contextpress.pipeline import Pipeline
 from contextpress.profiles import PROFILES, Profile, StageConfig
+from contextpress.stats import CompressionResult, CompressionStats
 
 if TYPE_CHECKING:
     from contextpress.llm.base import LLMBackend
@@ -57,23 +58,27 @@ class ContextManager:
         compression: str | None = None,
         stages: list[str] | None = None,
         disable: list[str] | None = None,
-    ) -> Any:
+        return_stats: 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``.
         """
         _validate_token_budget(token_budget)
+        level = compression if compression is not None else self._compression
         profile = copy.deepcopy(self._profile)
         apply_stage_selection(
             profile,
             base_profile=self._profile,
-            compression=compression if compression is not None else self._compression,
+            compression=level,
             stages=stages,
             disable=disable,
             token_budget=token_budget,
         )
 
         conv, ctx = normalize_messages(messages, context_type=self._type)
+        stats = CompressionStats(compression_level=level) if return_stats else None
         pipeline = Pipeline(
             profile,
             token_budget=token_budget,
@@ -82,15 +87,19 @@ class ContextManager:
             llm_min_input_chars=self.llm_min_input_chars,
             llm_max_summary_tokens=self.llm_max_summary_tokens,
         )
-        out = pipeline.run(conv)
-        return denormalize_output(out, ctx)
+        out = pipeline.run(conv, stats=stats)
+        messages_out = denormalize_output(out, ctx)
+        if return_stats:
+            assert stats is not None
+            return CompressionResult(messages=messages_out, stats=stats)
+        return messages_out
 
     def set_compression(self, compression: str) -> None:
         """Change the default preset for subsequent ``compress()`` calls (low / medium / high)."""
         self._compression = normalize_compression_level(compression)
 
     def configure(self, stage: str, **kwargs: Any) -> None:
-        """Patch ``StageConfig`` fields on the live profile (e.g. ``aggressiveness``, ``enabled``)."""
+        """Patch ``StageConfig`` fields on the live profile (e.g. aggressiveness, enabled)."""
         if not hasattr(self._profile, stage):
             raise ValueError(f"unknown stage {stage!r}")
         sc: StageConfig = getattr(self._profile, stage)

contextpress-0.2.0/contextpress/llm/_helpers.py

@@ -0,0 +1,57 @@
+"""Shared helpers for Tier 2 LLM adapters."""
+
+from __future__ import annotations
+
+import json
+import re
+
+
+def parse_keep_indices(raw: str, n: int) -> list[int]:
+    """Parse an LLM response into sorted unique turn indices to keep."""
+    if n <= 0:
+        return []
+    if n == 1:
+        return [0]
+
+    text = (raw or "").strip()
+    if not text:
+        return list(range(n))
+
+    # JSON array: [0, 2, 4]
+    if text.startswith("["):
+        try:
+            data = json.loads(text)
+            if isinstance(data, list):
+                return _validate_indices(data, n)
+        except json.JSONDecodeError:
+            pass
+
+    # Comma / space separated: 0, 2, 4
+    nums = re.findall(r"\d+", text)
+    if nums:
+        return _validate_indices([int(x) for x in nums], n)
+
+    return list(range(n))
+
+
+def _validate_indices(values: list[int], n: int) -> list[int]:
+    valid = sorted({i for i in values if isinstance(i, int) and 0 <= i < n})
+    return valid if valid else list(range(n))
+
+
+def format_numbered_turns(turns: list[str], *, max_chars: int = 800) -> str:
+    lines: list[str] = []
+    for i, text in enumerate(turns):
+        snippet = text.strip().replace("\n", " ")
+        if len(snippet) > max_chars:
+            snippet = snippet[: max_chars - 3] + "..."
+        lines.append(f"{i}: {snippet}")
+    return "\n".join(lines)
+
+
+DEDUP_SYSTEM_PROMPT = (
+    "You deduplicate conversation turns. Given numbered turns, return ONLY the 0-based "
+    "indices of turns to KEEP as a comma-separated list (example: 0,2,5). "
+    "When turns repeat the same idea, keep the most recent index. "
+    "Always keep at least one turn. Output nothing else."
+)

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/llm/adapters.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import warnings
 from typing import Any
 
-
+from contextpress.llm._helpers import DEDUP_SYSTEM_PROMPT, format_numbered_turns, parse_keep_indices
 from contextpress.llm.base import LLMBackend
 
 
@@ -60,7 +60,24 @@ class OpenAIBackend(LLMBackend):
             raise
 
     def deduplicate(self, turns: list[str]) -> list[int]:
-        return list(range(len(turns)))
+        if len(turns) <= 1:
+            return list(range(len(turns)))
+        prompt = format_numbered_turns(turns)
+        try:
+            resp = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": DEDUP_SYSTEM_PROMPT},
+                    {"role": "user", "content": prompt},
+                ],
+                max_tokens=128,
+                temperature=0,
+            )
+            content = resp.choices[0].message.content or ""
+            return parse_keep_indices(content, len(turns))
+        except Exception as exc:
+            warnings.warn(f"contextpress OpenAIBackend.deduplicate failed: {exc}", stacklevel=2)
+            return list(range(len(turns)))
 
 
 class AnthropicBackend(LLMBackend):
@@ -98,7 +115,24 @@ class AnthropicBackend(LLMBackend):
             raise
 
     def deduplicate(self, turns: list[str]) -> list[int]:
-        return list(range(len(turns)))
+        if len(turns) <= 1:
+            return list(range(len(turns)))
+        prompt = format_numbered_turns(turns)
+        try:
+            msg = self.client.messages.create(
+                model=self.model,
+                max_tokens=128,
+                system=DEDUP_SYSTEM_PROMPT,
+                messages=[{"role": "user", "content": prompt}],
+            )
+            parts = []
+            for b in msg.content:
+                if hasattr(b, "text"):
+                    parts.append(b.text)
+            return parse_keep_indices("".join(parts), len(turns))
+        except Exception as exc:
+            warnings.warn(f"contextpress AnthropicBackend.deduplicate failed: {exc}", stacklevel=2)
+            return list(range(len(turns)))
 
 
 class OllamaBackend(LLMBackend):
@@ -171,4 +205,19 @@ class OllamaBackend(LLMBackend):
             raise
 
     def deduplicate(self, turns: list[str]) -> list[int]:
-        return list(range(len(turns)))
+        if len(turns) <= 1:
+            return list(range(len(turns)))
+        prompt = format_numbered_turns(turns)
+        try:
+            resp = self._client.chat(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": DEDUP_SYSTEM_PROMPT},
+                    {"role": "user", "content": prompt},
+                ],
+                options={"num_predict": 128, "temperature": 0},
+            )
+            return parse_keep_indices(_ollama_response_text(resp), len(turns))
+        except Exception as exc:
+            warnings.warn(f"contextpress OllamaBackend.deduplicate failed: {exc}", stacklevel=2)
+            return list(range(len(turns)))

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/models.py

@@ -32,7 +32,9 @@ class Turn:
     importance: float = 1.0  # set by pipeline stages, 0.0–1.0
     resolved: bool = False  # True when flagged by resolution detector
     compressed: bool = False  # True if content was modified by pipeline
-    original_content: str | list[ContentBlock] | None = None  # preserves original before compression
+    original_content: str | list[ContentBlock] | None = (
+        None  # preserves original before compression
+    )
 
 
 @dataclass

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/normalizer.py

@@ -52,8 +52,14 @@ def _blocks_from_openai_style(items: list[dict[str, Any]]) -> list[ContentBlock]
             url = ""
             if "image_url" in item:
                 iu = item["image_url"]
-                url = iu if isinstance(iu, str) else (iu.get("url", "") if isinstance(iu, dict) else "")
-            blocks.append(ContentBlock(type="image", content=url or str(item), metadata=copy.deepcopy(item)))
+                url = (
+                    iu
+                    if isinstance(iu, str)
+                    else (iu.get("url", "") if isinstance(iu, dict) else "")
+                )
+            blocks.append(
+                ContentBlock(type="image", content=url or str(item), metadata=copy.deepcopy(item))
+            )
         else:
             blocks.append(
                 ContentBlock(
@@ -83,12 +89,13 @@ def _blocks_to_openai_style(blocks: list[ContentBlock]) -> list[dict[str, Any]]:
             else:
                 out.append({"type": "image_url", "image_url": {"url": b.content}})
         else:
-            out.append(copy.deepcopy(b.metadata) if b.metadata else {"type": b.type, "content": b.content})
+            out.append(
+                copy.deepcopy(b.metadata) if b.metadata else {"type": b.type, "content": b.content}
+            )
     return out
 
 
 def _get_lc_role_and_content(obj: Any) -> tuple[str, str | list[ContentBlock], dict[str, Any]]:
-    meta: dict[str, Any] = {}
     role = None
     if hasattr(obj, "type") and obj.type is not None:
         role = _LC_TYPE_MAP.get(str(obj.type).lower(), str(obj.type).lower())
@@ -101,7 +108,11 @@ def _get_lc_role_and_content(obj: Any) -> tuple[str, str | list[ContentBlock], d
         blocks = []
         for part in content:
             if isinstance(part, dict) and part.get("type") == "text":
-                blocks.append(ContentBlock(type="text", content=part.get("text", ""), metadata=copy.deepcopy(part)))
+                blocks.append(
+                    ContentBlock(
+                        type="text", content=part.get("text", ""), metadata=copy.deepcopy(part)
+                    )
+                )
             elif isinstance(part, str):
                 blocks.append(ContentBlock(type="text", content=part))
             else:
@@ -176,7 +187,9 @@ def normalize_messages(
         turns = []
         for i, raw in enumerate(messages):
             if not isinstance(raw, dict):
-                warnings.warn(f"contextpress: unknown message shape at index {i}, skipping", stacklevel=2)
+                warnings.warn(
+                    f"contextpress: unknown message shape at index {i}, skipping", stacklevel=2
+                )
                 continue
             d = copy.deepcopy(raw)
             role = str(d.get("role", "user")).lower()
@@ -292,7 +305,9 @@ def apply_text_to_turn(turn: Turn, new_text: str) -> Turn:
             importance=turn.importance,
             resolved=turn.resolved,
             compressed=True,
-            original_content=turn.original_content if turn.original_content is not None else turn.content,
+            original_content=(
+                turn.original_content if turn.original_content is not None else turn.content
+            ),
         )
     new_blocks: list[ContentBlock] = []
     text_assigned = False
@@ -304,7 +319,9 @@ def apply_text_to_turn(turn: Turn, new_text: str) -> Turn:
             new_blocks.append(copy.deepcopy(b))
     if not text_assigned:
         new_blocks.insert(0, ContentBlock(type="text", content=new_text))
-    orig = turn.original_content if turn.original_content is not None else copy.deepcopy(turn.content)
+    orig = (
+        turn.original_content if turn.original_content is not None else copy.deepcopy(turn.content)
+    )
     return Turn(
         role=turn.role,
         content=new_blocks,

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/pipeline.py

@@ -11,8 +11,10 @@ CONTEXTPRESS BEHAVIOR CONTRACT
 8. Tier 1 (no LLM) behavior is ALWAYS deterministic. Tests must pass consistently.
 9. LLM backend failures fall back to Tier 1 and emit a warning.
 10. token_budget=None means run all stages but skip budget enforcement.
-11. Compression presets (low/medium/high) select non-budget stages; budget runs when token_budget is set unless opted out.
-12. Tier 2 (when enabled) may dedupe non-system turns, then replace them with one assistant summary; system turns stay unchanged.
+11. Compression presets (low/medium/high) select non-budget stages; budget runs when
+    token_budget is set unless opted out.
+12. Tier 2 (when enabled) may dedupe non-system turns, then replace them with one assistant
+    summary; system turns stay unchanged.
 """
 
 from __future__ import annotations
@@ -25,6 +27,7 @@ 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.stats import CompressionStats, count_conversation_tokens
 from contextpress.strategies.base import BaseStrategy
 from contextpress.strategies.budget import BudgetStrategy
 from contextpress.strategies.filler import FillerStrategy
@@ -49,9 +52,9 @@ def clone_turn(t: Turn) -> Turn:
         importance=t.importance,
         resolved=t.resolved,
         compressed=t.compressed,
-        original_content=copy.deepcopy(t.original_content)
-        if t.original_content is not None
-        else None,
+        original_content=(
+            copy.deepcopy(t.original_content) if t.original_content is not None else None
+        ),
     )
 
 
@@ -85,7 +88,17 @@ class Pipeline:
         self.llm_min_input_chars = max(0, int(llm_min_input_chars))
         self.llm_max_summary_tokens = max(64, int(llm_max_summary_tokens))
 
-    def run(self, conversation: Conversation) -> Conversation:
+    def run(
+        self,
+        conversation: Conversation,
+        stats: CompressionStats | None = None,
+    ) -> 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
+
         result = clone_conversation(conversation)
         for stage_name in self.STAGE_ORDER:
             if stage_name == "budget" and self.token_budget is None:
@@ -93,11 +106,21 @@ class Pipeline:
             stage_config = getattr(self.profile, stage_name)
             if not stage_config.enabled:
                 continue
+            before_turns = len(result.turns)
             strategy = self._build_strategy(stage_name, stage_config)
             result = strategy.process(result)
+            if stats is not None:
+                stats.stages_run.append(stage_name)
+                delta = len(result.turns) - before_turns
+                if delta != 0:
+                    stats.turn_delta_by_stage[stage_name] = delta
 
         if self.llm_backend is not None:
-            result = self._run_llm_tier(result)
+            result = self._run_llm_tier(result, stats=stats)
+
+        if stats is not None:
+            stats.turns_after = len(result.turns)
+            stats.tokens_after = count_conversation_tokens(result, self.model)
 
         return result
 
@@ -125,7 +148,11 @@ class Pipeline:
             )
         raise ValueError(f"unknown stage {name!r}")
 
-    def _run_llm_tier(self, conversation: Conversation) -> Conversation:
+    def _run_llm_tier(
+        self,
+        conversation: Conversation,
+        stats: CompressionStats | None = None,
+    ) -> Conversation:
         if self.llm_backend is None:
             return conversation
 
@@ -135,13 +162,20 @@ class Pipeline:
         if not ns_turns:
             return conversation
 
+        if stats is not None:
+            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)}
+            {
+                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)))
@@ -149,6 +183,9 @@ class Pipeline:
             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)
+
         lines = [f"{t.role}: {txt}" for t, txt in zip(ns_turns, texts, strict=True)]
         combined = "\n\n".join(lines)
         if self.llm_min_input_chars > 0 and len(combined) < self.llm_min_input_chars:
@@ -167,6 +204,9 @@ class Pipeline:
         if not summary:
             return conversation
 
+        if stats is not None:
+            stats.llm_tier_applied = True
+
         new_turns: list[Turn] = list(system_turns)
         new_turns.append(
             Turn(

contextpress-0.2.0/contextpress/stats.py

@@ -0,0 +1,67 @@
+"""Compression statistics returned when ``return_stats=True``."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import tiktoken
+
+from contextpress.models import Conversation, Turn
+from contextpress.normalizer import extract_text_for_processing
+
+
+def get_encoding(model: str | None) -> tiktoken.Encoding:
+    if model:
+        try:
+            return tiktoken.encoding_for_model(model)
+        except KeyError:
+            pass
+    return tiktoken.get_encoding("cl100k_base")
+
+
+def count_turn_tokens(turn: Turn, encoding: tiktoken.Encoding) -> int:
+    if isinstance(turn.content, str):
+        body = turn.content
+    else:
+        body = extract_text_for_processing(turn)
+    return len(encoding.encode(f"{turn.role}\n{body}"))
+
+
+def count_conversation_tokens(conversation: Conversation, model: str | None) -> int:
+    enc = get_encoding(model)
+    return sum(count_turn_tokens(t, enc) for t in conversation.turns)
+
+
+@dataclass
+class CompressionStats:
+    """Observed effects of a single ``compress()`` call."""
+
+    turns_before: int = 0
+    turns_after: int = 0
+    tokens_before: int = 0
+    tokens_after: int = 0
+    stages_run: list[str] = field(default_factory=list)
+    turn_delta_by_stage: dict[str, int] = field(default_factory=dict)
+    llm_tier_applied: bool = False
+    llm_dedup_turns_before: int = 0
+    llm_dedup_turns_after: int = 0
+    compression_level: str | None = None
+    context_type: str = "chat"
+    token_budget: int | None = None
+
+    @property
+    def turns_removed(self) -> int:
+        return max(0, self.turns_before - self.turns_after)
+
+    @property
+    def tokens_saved(self) -> int:
+        return max(0, self.tokens_before - self.tokens_after)
+
+
+@dataclass
+class CompressionResult:
+    """Messages plus stats when ``return_stats=True``."""
+
+    messages: Any
+    stats: CompressionStats

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/strategies/filler.py

@@ -94,7 +94,7 @@ def _build_filler_pattern() -> re.Pattern[str]:
 
 _FILLER_RE = _build_filler_pattern()
 
-# "actually" at start of "actually, no" — keep if followed by comma and negation? Spec: "actually, no"
+# Keep "actually" when it starts a phrase like "actually, no" (per spec).
 _ACTUALLY_NO = re.compile(r"^\s*actually\s*,\s*no\b", re.IGNORECASE)
 
 

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/strategies/recency.py

@@ -114,14 +114,16 @@ class RecencyStrategy(BaseStrategy):
             else:
                 processed_by_ns.append(copy.deepcopy(t))
 
-        by_idx = dict(zip(ns_indices, processed_by_ns))
+        by_idx = dict(zip(ns_indices, processed_by_ns, strict=True))
         out: list[Turn] = []
         for i, t in enumerate(conversation.turns):
             if i in by_idx:
                 out.append(by_idx[i])
             else:
                 out.append(copy.deepcopy(t))
-        return Conversation(turns=out, type=conversation.type, metadata=copy.deepcopy(conversation.metadata))
+        return Conversation(
+            turns=out, type=conversation.type, metadata=copy.deepcopy(conversation.metadata)
+        )
 
     def _relevance_score(self, query: str, chunk: str) -> float:
         if not query.strip() or not chunk.strip():

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/strategies/repetition.py

@@ -38,7 +38,9 @@ class RepetitionStrategy(BaseStrategy):
         indices_to_drop: set[int] = set()
 
         # Positions of non-system turns with their global index
-        nst: list[tuple[int, Turn]] = [(i, t) for i, t in enumerate(turns) if not self._is_protected(t)]
+        nst: list[tuple[int, Turn]] = [
+            (i, t) for i, t in enumerate(turns) if not self._is_protected(t)
+        ]
 
         def run_group(group: list[tuple[int, Turn]]) -> None:
             if len(group) < 2:

{contextpress-0.1.0 → contextpress-0.2.0}/contextpress/strategies/resolution.py

@@ -166,14 +166,15 @@ class ResolutionStrategy(BaseStrategy):
         res_text = extract_text_for_processing(turns[res_idx])
 
         if self.conv_type == "chat":
-            # Include one trailing turn so an assistant acknowledgement after a user's resolution still counts
+            # Include one trailing turn so an assistant ack after a user's resolution still counts.
             scan_end = min(len(turns) - 1, res_idx + 1)
             has_user = any(
                 turns[i].role == "user" and _has_signal_any(extract_text_for_processing(turns[i]))
                 for i in range(thread_start, scan_end + 1)
             )
             has_asst = any(
-                turns[i].role == "assistant" and _has_signal_any(extract_text_for_processing(turns[i]))
+                turns[i].role == "assistant"
+                and _has_signal_any(extract_text_for_processing(turns[i]))
                 for i in range(thread_start, scan_end + 1)
             )
             if not (has_user and has_asst):

{contextpress-0.1.0 → contextpress-0.2.0}/examples/llm_tier_openai.py

@@ -31,7 +31,7 @@ def main() -> None:
     messages = [
         {"role": "system", "content": "You are a concise assistant."},
         {"role": "user", "content": "What is Python? " + ("Explain briefly. " * 200)},
-        {"role": "assistant", "content": "Python is a programming language. " *150},
+        {"role": "assistant", "content": "Python is a programming language. " * 150},
         {"role": "user", "content": "And numpy? " * 80},
     ]
 

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "contextpress"
-version = "0.1.0"
+version = "0.2.0"
 description = "Deterministic context compression for LLM chat, RAG, and agent pipelines"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -59,4 +59,15 @@ packages = ["contextpress"]
 "contextpress/py.typed" = "contextpress/py.typed"
 
 [tool.hatch.build.targets.sdist]
-include = ["/contextpress", "/tests", "/examples", "/README.md", "/LICENSE", "/NOTICE", "/CHANGELOG.md", "/CITATION.cff"]
+include = ["/contextpress", "/tests", "/examples", "/README.md", "/LICENSE", "/NOTICE", "/CHANGELOG.md", "/CITATION.cff", "/CONTRIBUTING.md"]
+
+[tool.black]
+line-length = 100
+target-version = ["py310", "py311", "py312", "py313"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "B"]

{contextpress-0.1.0 → contextpress-0.2.0}/tests/test_filler.py

@@ -48,7 +48,7 @@ def test_just_in_time_preserved():
 
 
 def test_empty_conversation():
-    out = _run()( []).turns
+    out = _run()([]).turns
     assert out == []
 
 

contextpress-0.2.0/tests/test_llm_helpers.py

@@ -0,0 +1,65 @@
+from unittest.mock import MagicMock
+
+import pytest
+
+from contextpress.llm._helpers import parse_keep_indices
+from contextpress.llm.adapters import AnthropicBackend, OllamaBackend, OpenAIBackend
+
+
+def test_parse_keep_indices_comma_separated():
+    assert parse_keep_indices("0, 2, 4", 6) == [0, 2, 4]
+
+
+def test_parse_keep_indices_json_array():
+    assert parse_keep_indices("[1, 3]", 4) == [1, 3]
+
+
+def test_parse_keep_indices_empty_falls_back_to_all():
+    assert parse_keep_indices("", 3) == [0, 1, 2]
+
+
+def test_parse_keep_indices_invalid_falls_back_to_all():
+    assert parse_keep_indices("keep everything please", 2) == [0, 1]
+
+
+def test_openai_deduplicate_parses_response():
+    client = MagicMock()
+    client.chat.completions.create.return_value = MagicMock(
+        choices=[MagicMock(message=MagicMock(content="0, 2"))]
+    )
+    b = OpenAIBackend(client=client)
+    assert b.deduplicate(["a", "b", "c", "d"]) == [0, 2]
+    client.chat.completions.create.assert_called_once()
+
+
+def test_openai_deduplicate_single_turn_skips_llm():
+    client = MagicMock()
+    b = OpenAIBackend(client=client)
+    assert b.deduplicate(["only one"]) == [0]
+    client.chat.completions.create.assert_not_called()
+
+
+def test_openai_deduplicate_error_keeps_all():
+    client = MagicMock()
+    client.chat.completions.create.side_effect = RuntimeError("network")
+    b = OpenAIBackend(client=client)
+    with pytest.warns(UserWarning):
+        assert b.deduplicate(["a", "b", "c"]) == [0, 1, 2]
+
+
+def test_anthropic_deduplicate_parses_response():
+    client = MagicMock()
+    block = MagicMock()
+    block.text = "0,1"
+    msg = MagicMock()
+    msg.content = [block]
+    client.messages.create.return_value = msg
+    b = AnthropicBackend(client=client)
+    assert b.deduplicate(["x", "y", "z"]) == [0, 1]
+
+
+def test_ollama_deduplicate_parses_response():
+    client = MagicMock()
+    client.chat.return_value = {"message": {"content": "0, 2"}}
+    b = OllamaBackend(client=client, model="llama3.2")
+    assert b.deduplicate(["a", "b", "c"]) == [0, 2]

{contextpress-0.1.0 → contextpress-0.2.0}/tests/test_models.py

@@ -1,4 +1,4 @@
-from datetime import UTC, datetime
+from datetime import datetime, timezone
 
 from contextpress.models import ContentBlock, Conversation, Turn
 
@@ -22,5 +22,5 @@ def test_non_system_turns():
 
 
 def test_timestamp_optional():
-    t = Turn(role="user", content="x", timestamp=datetime.now(UTC))
+    t = Turn(role="user", content="x", timestamp=datetime.now(timezone.utc))
     assert t.timestamp is not None

{contextpress-0.1.0 → contextpress-0.2.0}/tests/test_pipeline.py

@@ -40,7 +40,10 @@ def test_disable_resolution():
 
 def test_system_survives():
     cm = ContextManager(type="chat")
-    messages = [{"role": "system", "content": "You are helpful."}, {"role": "user", "content": "hi"}]
+    messages = [
+        {"role": "system", "content": "You are helpful."},
+        {"role": "user", "content": "hi"},
+    ]
     r = cm.compress(messages, token_budget=500)
     assert r[0]["role"] == "system"
     assert r[0]["content"] == "You are helpful."
@@ -216,11 +219,12 @@ def test_anthropic_backend_summarize_warns_on_error():
             b.summarize("x", 10)
 
 
-def test_adapter_deduplicate_defaults():
+def test_adapter_deduplicate_single_turn():
     client = MagicMock()
-    assert OpenAIBackend(client=client).deduplicate(["a", "b"]) == [0, 1]
+    assert OpenAIBackend(client=client).deduplicate(["a"]) == [0]
     assert AnthropicBackend(client=client).deduplicate(["a"]) == [0]
-    assert OllamaBackend(client=client, model="x").deduplicate(["a", "b"]) == [0, 1]
+    assert OllamaBackend(client=client, model="x").deduplicate(["a"]) == [0]
+    client.chat.completions.create.assert_not_called()
 
 
 def test_ollama_backend_summarize_dict_response():

contextpress-0.2.0/tests/test_stats.py

@@ -0,0 +1,40 @@
+from contextpress import CompressionResult, ContextManager
+
+
+def test_compress_without_stats_returns_list():
+    cm = ContextManager(type="chat")
+    messages = [{"role": "user", "content": "hello basically there"}]
+    out = cm.compress(messages, token_budget=500)
+    assert isinstance(out, list)
+
+
+def test_compress_with_stats_returns_result():
+    cm = ContextManager(type="chat")
+    messages = [
+        {"role": "system", "content": "You are helpful."},
+        {"role": "user", "content": "Old question: " + "blah " * 80},
+        {"role": "assistant", "content": "Basically, honestly, " + "yak " * 80},
+        {"role": "user", "content": "What is 2+2?"},
+        {"role": "assistant", "content": "Four."},
+    ]
+    result = cm.compress(messages, token_budget=120, return_stats=True)
+    assert isinstance(result, CompressionResult)
+    assert isinstance(result.messages, list)
+    assert result.stats.turns_before == 5
+    assert result.stats.turns_after <= result.stats.turns_before
+    assert result.stats.tokens_before >= result.stats.tokens_after
+    assert result.stats.tokens_saved >= 0
+    assert result.stats.compression_level == "medium"
+    assert result.stats.context_type == "chat"
+    assert result.stats.token_budget == 120
+    assert "filler" in result.stats.stages_run
+
+
+def test_stats_turn_delta_by_stage():
+    cm = ContextManager(type="chat", compression="low")
+    messages = [
+        {"role": "user", "content": "hello basically"},
+        {"role": "assistant", "content": "sounds good"},
+    ]
+    result = cm.compress(messages, token_budget=None, return_stats=True)
+    assert isinstance(result.stats.turn_delta_by_stage, dict)

contextpress-0.1.0/CHANGELOG.md

@@ -1,10 +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.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).