contextpress 0.1.0__py3-none-any.whl

contextpress/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+from contextpress._bootstrap import bootstrap_nltk
+from contextpress.models import ContentBlock, Conversation, Turn
+
+bootstrap_nltk()
+
+__all__ = ["ContextManager", "Turn", "Conversation", "ContentBlock"]
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy import: ContextManager -> core -> pipeline -> strategies (sumy, etc.)
+    if name == "ContextManager":
+        from contextpress.core import ContextManager
+
+        return ContextManager
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

contextpress/_bootstrap.py

@@ -0,0 +1,34 @@
+"""One-time NLTK data download.
+
+Runs on first import; writes a flag file so later imports stay silent.
+Offline installs will hit the network here — set the flag manually
+(``touch ~/.contextpress/nltk_ready``) or pre-populate NLTK_DATA to skip.
+"""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+
+import nltk
+
+
+def bootstrap_nltk() -> None:
+    flag = Path.home() / ".contextpress" / "nltk_ready"
+    if flag.exists():
+        return
+    packages = ["punkt", "stopwords", "averaged_perceptron_tagger"]
+    failed: list[str] = []
+    for pkg in packages:
+        try:
+            nltk.download(pkg, quiet=True)
+        except Exception:
+            failed.append(pkg)
+    if failed:
+        warnings.warn(
+            f"contextpress: could not download NLTK data {failed}; "
+            "resolution/recency may degrade. Check network or set NLTK_DATA.",
+            stacklevel=2,
+        )
+    flag.parent.mkdir(parents=True, exist_ok=True)
+    flag.touch()

contextpress/compression.py

@@ -0,0 +1,101 @@
+"""Presets (low/medium/high), explicit ``stages=``, and budget toggling."""
+
+from __future__ import annotations
+
+from contextpress.profiles import Profile
+
+STAGE_ORDER: tuple[str, ...] = (
+    "filler",
+    "repetition",
+    "resolution",
+    "recency",
+    "budget",
+)
+
+VALID_STAGES = frozenset(STAGE_ORDER)
+
+_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)
+_COMPRESSION_PRESETS: dict[str, frozenset[str]] = {
+    "low": frozenset({"filler", "repetition"}),
+    "medium": frozenset({"filler", "repetition", "recency"}),
+    "high": frozenset({"filler", "repetition", "resolution", "recency"}),
+}
+
+_COMPRESSION_ALIASES: dict[str, str] = {
+    "low": "low",
+    "light": "low",
+    "medium": "medium",
+    "med": "medium",
+    "mid": "medium",
+    "high": "high",
+    "max": "high",
+}
+
+
+__all__ = [
+    "STAGE_ORDER",
+    "VALID_STAGES",
+    "apply_stage_selection",
+    "normalize_compression_level",
+]
+
+
+def normalize_compression_level(level: str) -> str:
+    key = level.strip().lower()
+    if key not in _COMPRESSION_ALIASES:
+        raise ValueError(
+            f"unknown compression level {level!r}; "
+            f"use one of: low, medium, high (aliases: light, med, max)"
+        )
+    return _COMPRESSION_ALIASES[key]
+
+
+def apply_stage_selection(
+    profile: Profile,
+    *,
+    base_profile: Profile,
+    compression: str,
+    stages: list[str] | None,
+    disable: list[str] | None,
+    token_budget: int | None,
+) -> None:
+    """
+    Mutates ``profile`` in place: sets each stage's ``enabled`` from explicit
+    ``stages``, or from a compression preset merged with ``base_profile`` for
+    non-budget stages, then applies ``disable``. Budget is set last from
+    ``token_budget`` / ``stages`` / ``disable``.
+    """
+    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]
+        if unknown:
+            raise ValueError(f"unknown stage name(s): {unknown}; valid: {sorted(VALID_STAGES)}")
+        want = frozenset(stages)
+        for name in _NON_BUDGET_ORDER:
+            getattr(profile, name).enabled = name in want
+    else:
+        level = normalize_compression_level(compression)
+        preset = _COMPRESSION_PRESETS[level]
+        for name in _NON_BUDGET_ORDER:
+            base_on = getattr(base_profile, name).enabled
+            getattr(profile, name).enabled = (name in preset) and base_on
+
+    if disable:
+        for name in disable:
+            if not hasattr(profile, name):
+                continue
+            getattr(profile, name).enabled = False
+
+    # Budget: token cap enforcement (pipeline still skips if token_budget is None)
+    if token_budget is None:
+        profile.budget.enabled = False
+    elif stages is not None:
+        profile.budget.enabled = "budget" in want
+    else:
+        if disable and "budget" in disable:
+            profile.budget.enabled = False
+        else:
+            profile.budget.enabled = getattr(base_profile, "budget").enabled

contextpress/core.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import copy
+import warnings
+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.profiles import PROFILES, Profile, StageConfig
+
+if TYPE_CHECKING:
+    from contextpress.llm.base import LLMBackend
+
+
+def _validate_token_budget(token_budget: int | None) -> None:
+    if token_budget is None:
+        return
+    if isinstance(token_budget, bool) or not isinstance(token_budget, int):
+        raise TypeError("token_budget must be a positive int or None (bools are not allowed)")
+    if token_budget < 1:
+        raise ValueError("token_budget must be >= 1 when set")
+
+
+class ContextManager:
+    """Main API: ``compress()`` runs Tier 1 (and Tier 2 if ``llm_backend`` is set).
+
+    ``model`` is only for tiktoken when enforcing ``token_budget``. It does not call that model
+    unless you pass an ``llm_backend`` that uses it.
+    """
+
+    def __init__(
+        self,
+        type: str = "chat",
+        model: str | None = None,
+        llm_backend: LLMBackend | None = None,
+        *,
+        compression: str = "medium",
+        llm_min_input_chars: int = 1500,
+        llm_max_summary_tokens: int = 2048,
+    ):
+        if type not in PROFILES:
+            raise ValueError(f"unknown context type {type!r}")
+        self._type = type
+        self._profile: Profile = copy.deepcopy(PROFILES[type])
+        self._compression: str = normalize_compression_level(compression)
+        self.model = model
+        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)
+
+    def compress(
+        self,
+        messages: Any,
+        token_budget: int | None = None,
+        *,
+        compression: str | None = None,
+        stages: list[str] | None = None,
+        disable: list[str] | None = None,
+    ) -> Any:
+        """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.
+        """
+        _validate_token_budget(token_budget)
+        profile = copy.deepcopy(self._profile)
+        apply_stage_selection(
+            profile,
+            base_profile=self._profile,
+            compression=compression if compression is not None else self._compression,
+            stages=stages,
+            disable=disable,
+            token_budget=token_budget,
+        )
+
+        conv, ctx = normalize_messages(messages, context_type=self._type)
+        pipeline = Pipeline(
+            profile,
+            token_budget=token_budget,
+            model=self.model,
+            llm_backend=self.llm_backend,
+            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)
+
+    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``)."""
+        if not hasattr(self._profile, stage):
+            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)
+        unknown = [k for k in kwargs if not hasattr(sc, k)]
+        if unknown:
+            warnings.warn(
+                f"contextpress: configure({stage!r}) ignored unknown key(s): {unknown}",
+                stacklevel=2,
+            )

contextpress/llm/__init__.py

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

contextpress/llm/adapters.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+
+from contextpress.llm.base import LLMBackend
+
+
+def _ollama_response_text(resp: Any) -> str:
+    """Normalize ollama chat response (object or dict) to a string."""
+    if resp is None:
+        return ""
+    if isinstance(resp, dict):
+        msg = resp.get("message") or {}
+        if isinstance(msg, dict):
+            return str(msg.get("content") or "").strip()
+        return str(getattr(msg, "content", "") or "").strip()
+    msg = getattr(resp, "message", None)
+    if msg is not None:
+        c = getattr(msg, "content", None)
+        if c is not None:
+            return str(c).strip()
+    return ""
+
+
+class OpenAIBackend(LLMBackend):
+    """
+    Adapter for OpenAI-compatible APIs.
+    Requires: pip install openai
+    User must pass their own client instance.
+
+    Usage:
+        from openai import OpenAI
+        from contextpress.llm.adapters import OpenAIBackend
+
+        backend = OpenAIBackend(client=OpenAI(), model="gpt-4o-mini")
+        cm = ContextManager(type="chat", llm_backend=backend)
+    """
+
+    def __init__(self, client: Any, model: str = "gpt-4o-mini"):
+        self.client = client
+        self.model = model
+
+    def summarize(self, text: str, max_tokens: int) -> str:
+        try:
+            resp = self.client.chat.completions.create(
+                model=self.model,
+                messages=[
+                    {"role": "system", "content": "Summarize the following text concisely."},
+                    {"role": "user", "content": text},
+                ],
+                max_tokens=max_tokens,
+            )
+            choice = resp.choices[0]
+            content = choice.message.content
+            return content if content is not None else text
+        except Exception as exc:
+            warnings.warn(f"contextpress OpenAIBackend.summarize failed: {exc}", stacklevel=2)
+            raise
+
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        return list(range(len(turns)))
+
+
+class AnthropicBackend(LLMBackend):
+    """
+    Adapter for Anthropic Claude APIs.
+    Requires: pip install anthropic
+    User must pass their own client instance.
+
+    Usage:
+        import anthropic
+        from contextpress.llm.adapters import AnthropicBackend
+
+        backend = AnthropicBackend(client=anthropic.Anthropic(), model="claude-haiku-4-5")
+        cm = ContextManager(type="chat", llm_backend=backend)
+    """
+
+    def __init__(self, client: Any, model: str = "claude-haiku-4-5"):
+        self.client = client
+        self.model = model
+
+    def summarize(self, text: str, max_tokens: int) -> str:
+        try:
+            msg = self.client.messages.create(
+                model=self.model,
+                max_tokens=max_tokens,
+                messages=[{"role": "user", "content": f"Summarize concisely:\n\n{text}"}],
+            )
+            parts = []
+            for b in msg.content:
+                if hasattr(b, "text"):
+                    parts.append(b.text)
+            return "".join(parts) if parts else text
+        except Exception as exc:
+            warnings.warn(f"contextpress AnthropicBackend.summarize failed: {exc}", stacklevel=2)
+            raise
+
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        return list(range(len(turns)))
+
+
+class OllamaBackend(LLMBackend):
+    """
+    Adapter for **Ollama** (local or remote) using the official ``ollama`` Python library.
+
+    Requires: ``pip install ollama``
+
+    Ollama must be installed and running (see https://ollama.com). Pull a model first, e.g.::
+
+        ollama pull llama3.2
+
+    Usage::
+
+        from contextpress import ContextManager
+        from contextpress.llm.adapters import OllamaBackend
+
+        backend = OllamaBackend(model="llama3.2")
+        cm = ContextManager(type="chat", llm_backend=backend, llm_min_input_chars=500)
+
+    Remote server::
+
+        backend = OllamaBackend(model="mistral", host="http://192.168.1.10:11434")
+
+    Custom client (advanced)::
+
+        from ollama import Client
+        backend = OllamaBackend(client=Client(host="http://localhost:11434"), model="llama3.2")
+    """
+
+    def __init__(
+        self,
+        model: str = "llama3.2",
+        *,
+        host: str | None = None,
+        client: Any | None = None,
+    ):
+        self.model = model
+        if client is not None:
+            self._client = client
+            return
+        try:
+            from ollama import Client as OllamaClient
+        except ImportError as exc:
+            raise ImportError(
+                "OllamaBackend requires the 'ollama' package. Install with: pip install ollama"
+            ) from exc
+        self._client = OllamaClient(host=host) if host else OllamaClient()
+
+    def summarize(self, text: str, max_tokens: int) -> str:
+        try:
+            resp = self._client.chat(
+                model=self.model,
+                messages=[
+                    {
+                        "role": "system",
+                        "content": (
+                            "Summarize the following conversation transcript concisely. "
+                            "Preserve important facts, names, and decisions."
+                        ),
+                    },
+                    {"role": "user", "content": text},
+                ],
+                options={"num_predict": max(64, int(max_tokens))},
+            )
+            content = _ollama_response_text(resp)
+            return content if content.strip() else text
+        except Exception as exc:
+            warnings.warn(f"contextpress OllamaBackend.summarize failed: {exc}", stacklevel=2)
+            raise
+
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        return list(range(len(turns)))

contextpress/llm/base.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class LLMBackend(ABC):
+    """
+    Interface for optional Tier 2 LLM processing.
+    Users implement this to connect their preferred LLM provider.
+    contextpress never imports any LLM SDK directly.
+    """
+
+    @abstractmethod
+    def summarize(self, text: str, max_tokens: int) -> str:
+        """
+        Abstractively summarize text to fit within max_tokens.
+        Must return a plain string.
+        """
+        ...
+
+    @abstractmethod
+    def deduplicate(self, turns: list[str]) -> list[int]:
+        """
+        Given a list of turn texts, return indices of turns to KEEP.
+        The backend decides which are semantically redundant.
+        """
+        ...

contextpress/models.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class ContentBlock:
+    """
+    A single block of content within a turn.
+    Used when content is multimodal (text + image, tool call, etc.)
+    """
+
+    type: str  # "text" | "image" | "tool_use" | "tool_result"
+    content: str  # text content or reference string
+    mime_type: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class Turn:
+    """
+    A single message in a conversation.
+    This is the canonical unit the entire pipeline operates on.
+    """
+
+    role: str  # "user" | "assistant" | "system"
+    content: str | list[ContentBlock]  # string for simple, list for multimodal
+    timestamp: datetime | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+    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
+
+
+@dataclass
+class Conversation:
+    """
+    An ordered list of turns with a declared context type.
+    This is the primary object passed into the pipeline.
+    """
+
+    turns: list[Turn]
+    type: str = "chat"  # "chat" | "rag_doc" | "agent"
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def text_turns(self) -> list[Turn]:
+        """Returns only turns that contain extractable text content."""
+        return [t for t in self.turns if self._has_text(t)]
+
+    def non_system_turns(self) -> list[Turn]:
+        """Returns all turns except system turns."""
+        return [t for t in self.turns if t.role != "system"]
+
+    @staticmethod
+    def _has_text(turn: Turn) -> bool:
+        if isinstance(turn.content, str):
+            return bool(turn.content.strip())
+        return any(b.type == "text" for b in turn.content)