contpress 0.1.5__py3-none-any.whl

contextpress/__init__.py

@@ -0,0 +1,33 @@
+from contpress.budgets import TokenBudget
+from contpress.builder import PromptBuilder
+from contpress.compressors.extractive import ExtractiveCompressor
+from contpress.contracts import OutputContract
+from contpress.core import ContextPress, OptimizedPrompt
+from contpress.formatters import compact_json, compact_table, drop_nulls, json_to_csv_if_tabular, shorten_keys
+from contpress.memory.conversation import ConversationPruner
+from contpress.prompt_cache import PromptCacheLayout
+from contpress.rag.filter import ContextFilter
+from contpress.reports import UsageReport
+from contpress.tokenizer import TokenCounter
+from contpress.tools import AgentTraceCompactor, ToolSchemaCompactor
+
+__all__ = [
+    "ContextFilter",
+    "ContextPress",
+    "ConversationPruner",
+    "ExtractiveCompressor",
+    "OptimizedPrompt",
+    "OutputContract",
+    "PromptBuilder",
+    "PromptCacheLayout",
+    "TokenBudget",
+    "TokenCounter",
+    "ToolSchemaCompactor",
+    "UsageReport",
+    "AgentTraceCompactor",
+    "compact_json",
+    "compact_table",
+    "drop_nulls",
+    "json_to_csv_if_tabular",
+    "shorten_keys",
+]

contextpress/budgets.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from contpress.tokenizer import TokenCounter
+
+
+MODEL_CONTEXT_WINDOWS = {
+    "gpt-4o": 128_000,
+    "gpt-4o-mini": 128_000,
+    "gpt-4.1": 1_047_576,
+    "gpt-4.1-mini": 1_047_576,
+    "gpt-4.1-nano": 1_047_576,
+    "o3": 200_000,
+    "o4-mini": 200_000,
+}
+
+
+@dataclass(slots=True)
+class TokenBudget:
+    model: str = "gpt-4o-mini"
+    max_input_tokens: int | None = None
+    reserve_output_tokens: int = 0
+    system_prompt: str = ""
+    tool_schema: str = ""
+    rag_context_ratio: float = 0.6
+    history_ratio: float = 0.3
+    counter: TokenCounter = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if self.reserve_output_tokens < 0:
+            raise ValueError("reserve_output_tokens must be >= 0")
+        if self.max_input_tokens is not None and self.max_input_tokens < 0:
+            raise ValueError("max_input_tokens must be >= 0")
+        if not 0 <= self.rag_context_ratio <= 1:
+            raise ValueError("rag_context_ratio must be between 0 and 1")
+        if not 0 <= self.history_ratio <= 1:
+            raise ValueError("history_ratio must be between 0 and 1")
+        self.counter = TokenCounter(self.model)
+
+    @property
+    def context_window(self) -> int:
+        return MODEL_CONTEXT_WINDOWS.get(self.model, 128_000)
+
+    @property
+    def overhead_tokens(self) -> int:
+        return self.counter.count(self.system_prompt) + self.counter.count(self.tool_schema)
+
+    @property
+    def input_budget(self) -> int:
+        ceiling = self.max_input_tokens if self.max_input_tokens is not None else self.context_window
+        return max(0, ceiling - self.reserve_output_tokens - self.overhead_tokens)
+
+    @property
+    def rag_context_budget(self) -> int:
+        return int(self.input_budget * self.rag_context_ratio)
+
+    @property
+    def conversation_history_budget(self) -> int:
+        return int(self.input_budget * self.history_ratio)
+
+    def enforce(self, text: str) -> str:
+        return self.counter.trim(text, self.input_budget)

contextpress/builder.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+
+def _bullets(items: Iterable[str]) -> str:
+    return "\n".join(f"- {item}" for item in items if str(item).strip())
+
+
+@dataclass
+class PromptBuilder:
+    _blocks: list[tuple[str, str]] = field(default_factory=list)
+
+    def role(self, value: str) -> "PromptBuilder":
+        return self._add("Role", value)
+
+    def task(self, value: str) -> "PromptBuilder":
+        return self._add("Task", value)
+
+    def constraints(self, values: Iterable[str]) -> "PromptBuilder":
+        return self._add("Constraints", _bullets(values))
+
+    def instructions(self, values: Iterable[str]) -> "PromptBuilder":
+        return self._add("Instructions", _bullets(values))
+
+    def context(self, value: str) -> "PromptBuilder":
+        return self._add("Context", value)
+
+    def output(self, values: Iterable[str] | str) -> "PromptBuilder":
+        if isinstance(values, str):
+            return self._add("Output", values)
+        return self._add("Output", _bullets(values))
+
+    def block(self, title: str, value: str | Iterable[str]) -> "PromptBuilder":
+        if isinstance(value, str):
+            body = value
+        else:
+            body = _bullets(value)
+        return self._add(title, body)
+
+    def build(self) -> str:
+        return "\n".join(f"{title}:\n{body}" if "\n" in body else f"{title}: {body}" for title, body in self._blocks if body)
+
+    def _add(self, title: str, body: str) -> "PromptBuilder":
+        clean = (body or "").strip()
+        if clean:
+            self._blocks.append((title.strip(), clean))
+        return self

contextpress/cache/__init__.py

@@ -0,0 +1,5 @@
+from contpress.cache.exact import ExactPromptCache
+from contpress.cache.semantic import SemanticCache
+from contpress.cache.stores import InMemoryStore, RedisStore
+
+__all__ = ["ExactPromptCache", "InMemoryStore", "RedisStore", "SemanticCache"]

contextpress/cache/exact.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ExactPromptCache:
+    namespace: str = "contpress"
+    _data: dict[str, Any] = field(default_factory=dict)
+
+    def lookup(self, prompt: str) -> Any:
+        return self._data.get(self._key(prompt))
+
+    def add(self, prompt: str, value: Any) -> None:
+        self._data[self._key(prompt)] = value
+
+    def _key(self, prompt: str) -> str:
+        digest = hashlib.sha256((prompt or "").encode("utf-8")).hexdigest()
+        return f"{self.namespace}:{digest}"

contextpress/cache/semantic.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+
+class SemanticCache:
+    def __init__(self, *args, **kwargs) -> None:
+        try:
+            import diskcache  # noqa: F401
+            import faiss  # noqa: F401
+            from sentence_transformers import SentenceTransformer  # noqa: F401
+        except ImportError as exc:
+            raise ImportError("Install with: pip install contpress[semantic]") from exc
+        raise NotImplementedError("SemanticCache requires a vector store implementation; install extras and configure a store.")

contextpress/cache/stores.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class InMemoryStore:
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def get(self, key: str) -> Any:
+        return self.data.get(key)
+
+    def set(self, key: str, value: Any) -> None:
+        self.data[key] = value
+
+
+class RedisStore:
+    def __init__(self, url: str = "redis://localhost:6379/0", prefix: str = "contpress") -> None:
+        try:
+            import redis
+        except ImportError as exc:
+            raise ImportError("Install redis separately to use RedisStore: pip install redis") from exc
+        self.client = redis.Redis.from_url(url)
+        self.prefix = prefix
+
+    def get(self, key: str) -> bytes | None:
+        return self.client.get(f"{self.prefix}:{key}")
+
+    def set(self, key: str, value: bytes | str) -> None:
+        self.client.set(f"{self.prefix}:{key}", value)

contextpress/cli.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from rich.console import Console
+
+from contpress.core import ContextPress
+from contpress.formatters import compact_json
+from contpress.reports import UsageReport
+from contpress.tokenizer import TokenCounter
+
+
+console = Console()
+
+
+def _read(path: str) -> str:
+    return Path(path).read_text(encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="contpress")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    count = sub.add_parser("count")
+    count.add_argument("file")
+    count.add_argument("--model", default="gpt-4o-mini")
+    count.add_argument("--budget", type=int, default=8_000)
+
+    trim = sub.add_parser("trim")
+    trim.add_argument("file")
+    trim.add_argument("--model", default="gpt-4o-mini")
+    trim.add_argument("--max-tokens", type=int, required=True)
+
+    compress = sub.add_parser("compress")
+    compress.add_argument("file")
+    compress.add_argument("--model", default="gpt-4o-mini")
+    compress.add_argument("--target-tokens", type=int, default=1_000)
+    compress.add_argument("--task", default="")
+
+    compact = sub.add_parser("compact")
+    compact.add_argument("file")
+
+    report = sub.add_parser("report")
+    report.add_argument("file")
+    report.add_argument("--model", default="gpt-4o-mini")
+    report.add_argument("--budget", type=int, default=8_000)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "count":
+        counter = TokenCounter(args.model)
+        tokens = counter.count(_read(args.file))
+        console.print(f"File: {args.file}")
+        console.print(f"Model: {args.model}")
+        console.print(f"Tokens: {tokens:,}")
+        console.print(f"Fits {args.budget // 1000}k: {'yes' if tokens <= args.budget else 'no'}")
+        return 0
+
+    if args.command == "trim":
+        console.print(TokenCounter(args.model).trim(_read(args.file), args.max_tokens))
+        return 0
+
+    if args.command == "compress":
+        cp = ContextPress(model=args.model, max_input_tokens=args.target_tokens)
+        console.print(cp.optimize(task=args.task or "Compress this prompt.", context=_read(args.file)).text)
+        return 0
+
+    if args.command == "compact":
+        console.print(compact_json(json.loads(_read(args.file))))
+        return 0
+
+    if args.command == "report":
+        counter = TokenCounter(args.model)
+        text = _read(args.file)
+        before = counter.count(text)
+        after = min(before, args.budget)
+        console.print(UsageReport(args.model, before, after).summary())
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

contextpress/compressors/__init__.py

@@ -0,0 +1,15 @@
+from contpress.compressors.base import BaseCompressor
+from contpress.compressors.extractive import ExtractiveCompressor
+from contpress.compressors.llmlingua import LLMLinguaCompressor
+from contpress.compressors.reports import CompressionReport, compression_diff, compression_report
+from contpress.compressors.sentence_filter import SentenceFilterCompressor
+
+__all__ = [
+    "BaseCompressor",
+    "CompressionReport",
+    "ExtractiveCompressor",
+    "LLMLinguaCompressor",
+    "SentenceFilterCompressor",
+    "compression_diff",
+    "compression_report",
+]

contextpress/compressors/base.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class BaseCompressor(Protocol):
+    def compress(self, text: str, query: str = "", max_tokens: int = 1_000) -> str:
+        ...

contextpress/compressors/extractive.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from contpress.tokenizer import TokenCounter
+
+
+_SENTENCE_RE = re.compile(r"(?<=[.!?])\s+|\n+")
+_WORD_RE = re.compile(r"[A-Za-z0-9_#./:-]+")
+
+
+@dataclass(slots=True)
+class ExtractiveCompressor:
+    model: str = "gpt-4o-mini"
+    counter: TokenCounter = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        self.counter = TokenCounter(self.model)
+
+    def compress(self, text: str, query: str = "", max_tokens: int = 1_000) -> str:
+        if max_tokens < 0:
+            raise ValueError("max_tokens must be >= 0")
+        if self.counter.fits(text, max_tokens):
+            return text
+
+        sentences = [part.strip() for part in _SENTENCE_RE.split(text or "") if part.strip()]
+        scored = [(self._score(sentence, query), index, sentence) for index, sentence in enumerate(sentences)]
+        scored.sort(key=lambda item: (-item[0], item[1]))
+
+        chosen: list[tuple[int, str]] = []
+        used = 0
+        for score, index, sentence in scored:
+            sentence_tokens = self.counter.count(sentence)
+            if sentence_tokens == 0 or used + sentence_tokens > max_tokens:
+                continue
+            if score > 0 or not chosen:
+                chosen.append((index, sentence))
+                used += sentence_tokens
+
+        chosen.sort(key=lambda item: item[0])
+        result = " ".join(sentence for _, sentence in chosen)
+        return result if self.counter.fits(result, max_tokens) else self.counter.trim(result, max_tokens)
+
+    def _score(self, sentence: str, query: str) -> float:
+        lower = sentence.lower()
+        sentence_terms = set(_WORD_RE.findall(lower))
+        query_terms = set(_WORD_RE.findall((query or "").lower()))
+        score = len(sentence_terms & query_terms) * 3
+
+        if re.search(r"\d", sentence):
+            score += 2
+        if re.search(r"https?://|www\.", lower):
+            score += 2
+        if re.search(r"\b[A-Za-z_][A-Za-z0-9_]*\(", sentence) or re.search(r"\b[A-Z][A-Za-z0-9]+[A-Z][A-Za-z0-9]*\b", sentence):
+            score += 1.5
+        if sentence.endswith(":") or sentence.startswith(("#", "-", "*")):
+            score += 1.5
+        if re.search(r"\b(must|should|required|preserve|constraint|risk|warning|error|security)\b", lower):
+            score += 2
+        if re.search(r"\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)+\b", sentence):
+            score += 1
+        return score

contextpress/compressors/llmlingua.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+
+class LLMLinguaCompressor:
+    def __init__(self, *args, **kwargs) -> None:
+        try:
+            from llmlingua import PromptCompressor
+        except ImportError as exc:
+            raise ImportError("Install with: pip install contpress[compress]") from exc
+        self._compressor = PromptCompressor(*args, **kwargs)
+
+    def compress(
+        self,
+        prompt: str | None = None,
+        instruction: str = "Preserve code, numbers, entities, requirements, and constraints.",
+        target_tokens: int = 1_000,
+        **kwargs,
+    ) -> str:
+        source = prompt if prompt is not None else kwargs.pop("text", "")
+        result = self._compressor.compress_prompt(
+            source,
+            instruction=instruction,
+            target_token=target_tokens,
+            **kwargs,
+        )
+        if isinstance(result, dict):
+            return result.get("compressed_prompt", "")
+        return str(result)

contextpress/compressors/reports.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+
+from contpress.tokenizer import TokenCounter
+
+
+@dataclass(slots=True)
+class CompressionReport:
+    original_tokens: int
+    compressed_tokens: int
+    method: str
+
+    @property
+    def saved_tokens(self) -> int:
+        return max(0, self.original_tokens - self.compressed_tokens)
+
+    @property
+    def compression_ratio(self) -> float:
+        if self.original_tokens == 0:
+            return 1.0
+        return self.compressed_tokens / self.original_tokens
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "original_tokens": self.original_tokens,
+            "compressed_tokens": self.compressed_tokens,
+            "saved_tokens": self.saved_tokens,
+            "compression_ratio": round(self.compression_ratio, 3),
+            "method": self.method,
+        }
+
+
+def compression_report(original: str, compressed: str, method: str = "extractive", model: str = "gpt-4o-mini") -> CompressionReport:
+    counter = TokenCounter(model)
+    return CompressionReport(counter.count(original), counter.count(compressed), method)
+
+
+def compression_diff(original: str, compressed: str) -> str:
+    return "\n".join(
+        difflib.unified_diff(
+            original.splitlines(),
+            compressed.splitlines(),
+            fromfile="original",
+            tofile="compressed",
+            lineterm="",
+        )
+    )

contextpress/compressors/sentence_filter.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from contpress.compressors.extractive import ExtractiveCompressor
+
+
+class SentenceFilterCompressor(ExtractiveCompressor):
+    pass

contextpress/contracts.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from contpress.formatters import compact_json
+
+
+@dataclass(slots=True)
+class OutputContract:
+    fields: dict[str, str]
+    format: str = "json"
+    required: list[str] = field(default_factory=list)
+    additional_instructions: list[str] = field(default_factory=list)
+
+    def prompt(self) -> str:
+        if self.format == "json":
+            schema = {
+                "format": "json",
+                "required": self.required or list(self.fields),
+                "fields": self.fields,
+            }
+            body = compact_json(schema)
+        else:
+            body = f"Format: {self.format}\nFields: {', '.join(self.fields)}"
+        extras = "\n".join(f"- {item}" for item in self.additional_instructions)
+        return f"Output contract:\n{body}" + (f"\n{extras}" if extras else "")

contextpress/core.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any
+
+from contpress.budgets import TokenBudget
+from contpress.builder import PromptBuilder
+from contpress.compressors.extractive import ExtractiveCompressor
+from contpress.formatters import compact_json
+from contpress.rag.filter import ContextFilter
+from contpress.reports import UsageReport
+from contpress.tokenizer import TokenCounter
+
+
+@dataclass(slots=True)
+class OptimizedPrompt:
+    text: str
+    report: dict[str, Any]
+
+
+class ContextPress:
+    def __init__(
+        self,
+        model: str = "gpt-4o-mini",
+        max_input_tokens: int = 4_000,
+        max_output_tokens: int | None = None,
+        reserve_output_tokens: int | None = None,
+        compression: str = "extractive",
+    ) -> None:
+        self.model = model
+        self.max_input_tokens = max_input_tokens
+        self.max_output_tokens = max_output_tokens if max_output_tokens is not None else reserve_output_tokens or 0
+        self.compression = compression
+        self.counter = TokenCounter(model)
+        self.budget = TokenBudget(
+            model=model,
+            max_input_tokens=max_input_tokens,
+            reserve_output_tokens=self.max_output_tokens,
+        )
+
+    def optimize(
+        self,
+        task: str,
+        context: str | Sequence[str] | dict[str, Any] | list[Any] = "",
+        instructions: Iterable[str] | None = None,
+        output: Iterable[str] | str | None = None,
+        role: str | None = None,
+    ) -> OptimizedPrompt:
+        methods: list[str] = []
+        original_context = self._stringify_context(context)
+        original_prompt = self._build_prompt(task, original_context, instructions, output, role)
+        original_tokens = self.counter.count(original_prompt)
+
+        context_budget = max(0, int(self.budget.input_budget * 0.75))
+        optimized_context = original_context
+        if isinstance(context, Sequence) and not isinstance(context, (str, bytes, dict)) and all(isinstance(item, str) for item in context):
+            optimized_context = ContextFilter(self.model).filter(task, list(context), max_tokens=context_budget)
+            methods.append("context_filter")
+        elif self.compression in {"extractive", "sentence_filter"} and not self.counter.fits(original_prompt, self.budget.input_budget):
+            optimized_context = ExtractiveCompressor(self.model).compress(original_context, query=task, max_tokens=context_budget)
+            methods.append("sentence_filter")
+
+        prompt = self._build_prompt(task, optimized_context, instructions, output, role)
+        methods.append("compact_format")
+        if not self.counter.fits(prompt, self.budget.input_budget):
+            prompt = self.counter.trim(prompt, self.budget.input_budget)
+            methods.append("trim")
+
+        optimized_tokens = self.counter.count(prompt)
+        report = UsageReport(
+            model=self.model,
+            input_tokens_before=original_tokens,
+            input_tokens_after=optimized_tokens,
+            output_tokens_limit=self.max_output_tokens,
+            methods=list(dict.fromkeys(methods)),
+        ).as_dict()
+        return OptimizedPrompt(text=prompt, report=report)
+
+    def _build_prompt(
+        self,
+        task: str,
+        context: str,
+        instructions: Iterable[str] | None,
+        output: Iterable[str] | str | None,
+        role: str | None,
+    ) -> str:
+        builder = PromptBuilder()
+        if role:
+            builder.role(role)
+        builder.task(task)
+        if instructions:
+            builder.instructions(instructions)
+        if context:
+            builder.context(context)
+        if output:
+            builder.output(output)
+        return builder.build()
+
+    def _stringify_context(self, context: str | Sequence[str] | dict[str, Any] | list[Any]) -> str:
+        if isinstance(context, str):
+            return context
+        if isinstance(context, dict):
+            return compact_json(context)
+        if isinstance(context, list) and (not context or not all(isinstance(item, str) for item in context)):
+            return compact_json(context)
+        if isinstance(context, Sequence):
+            return "\n\n".join(str(item) for item in context)
+        return str(context)

contextpress/formatters.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import csv
+import io
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def compact_json(data: Any, ensure_ascii: bool = False) -> str:
+    return json.dumps(data, separators=(",", ":"), ensure_ascii=ensure_ascii)
+
+
+def drop_nulls(data: Any) -> Any:
+    if isinstance(data, Mapping):
+        return {key: drop_nulls(value) for key, value in data.items() if value is not None}
+    if isinstance(data, list):
+        return [drop_nulls(item) for item in data if item is not None]
+    return data
+
+
+def shorten_keys(data: Any, mapping: Mapping[str, str]) -> Any:
+    if isinstance(data, Mapping):
+        return {mapping.get(str(key), key): shorten_keys(value, mapping) for key, value in data.items()}
+    if isinstance(data, list):
+        return [shorten_keys(item, mapping) for item in data]
+    return data
+
+
+def json_to_csv_if_tabular(data: Any) -> str | None:
+    if not isinstance(data, Sequence) or isinstance(data, (str, bytes)) or not data:
+        return None
+    if not all(isinstance(row, Mapping) for row in data):
+        return None
+
+    headers: list[str] = []
+    for row in data:
+        for key in row:
+            if str(key) not in headers:
+                headers.append(str(key))
+
+    output = io.StringIO()
+    writer = csv.DictWriter(output, fieldnames=headers, lineterminator="\n", extrasaction="ignore")
+    writer.writeheader()
+    writer.writerows(data)
+    return output.getvalue().strip()
+
+
+def compact_table(rows: Sequence[Mapping[str, Any]], headers: Sequence[str] | None = None) -> str:
+    if not rows:
+        return ""
+    selected_headers = list(headers or rows[0].keys())
+    lines = ["|".join(str(header) for header in selected_headers)]
+    for row in rows:
+        lines.append("|".join("" if row.get(header) is None else str(row.get(header)) for header in selected_headers))
+    return "\n".join(lines)