awecompress 0.2.0__py3-none-any.whl

awecompress/__init__.py

@@ -0,0 +1,14 @@
+"""awecompress: local context compression for coding agents.
+
+Sits between the harness (Claude Code, OpenCode, ...) and its upstream, or
+runs inside awerouter beside odcp/rtk. When a session's history crosses a
+token threshold, the oldest whole turns are replaced by one frozen LLM
+summary — cached, so every later request reuses the same bytes.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("awecompress")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.2.0"

awecompress/cli.py

@@ -0,0 +1,127 @@
+"""CLI: serve / status / config / clear.
+
+`serve` runs in the foreground (Ctrl-C stops it). Backgrounding is the
+user's process manager — v1 ships no daemon machinery.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from pathlib import Path
+
+import aiohttp
+import click
+
+from awecompress import __version__
+from awecompress.config import config_path, load_config
+from awecompress.integrate import Compressor
+from awecompress.server import serve as serve_proxy
+
+
+@click.group(name="awecompress", context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, "-v", "--version", message="awecompress %(version)s")
+def cli() -> None:
+    """Compress long coding-agent context before it reaches your provider."""
+
+
+@cli.command()
+@click.option("--port", type=int, default=None, help="Listen port (default: config port or 8808).")
+@click.option("--host", default=None, help="Listen address (default: 127.0.0.1).")
+@click.option("--upstream", default=None, help="Upstream base URL (default: config upstream).")
+@click.option("--config", "config_file", type=click.Path(), default=None,
+              help="Config file path (default: ~/.config/awecompress/config.json).")
+def serve(port: int, host: str, upstream: str, config_file: str) -> None:
+    """Run the compression proxy in the foreground."""
+    cfg = load_config(Path(config_file).expanduser() if config_file else None)
+    if upstream:
+        cfg = replace(cfg, upstream=upstream)
+    compressor = Compressor(cfg.db_path)
+    try:
+        asyncio.run(serve_proxy(cfg, compressor, port, host))
+    except KeyboardInterrupt:
+        pass
+
+
+@cli.command()
+@click.option("--config", "config_file", type=click.Path(), default=None,
+              help="Config file path (default: ~/.config/awecompress/config.json).")
+def status(config_file: str) -> None:
+    """Show running state, config, and compression stats."""
+    cfg = load_config(Path(config_file).expanduser() if config_file else None)
+    url = f"http://{cfg.host}:{cfg.port}/"
+    running = False
+    try:
+        async def probe():
+            async with aiohttp.ClientSession() as session:
+                async with session.get(url, timeout=aiohttp.ClientTimeout(total=2)) as resp:
+                    return await resp.json(content_type=None)
+        running = asyncio.run(probe()).get("service") == "awecompress"
+    except Exception:
+        pass
+
+    compressor = Compressor(cfg.db_path)
+    stats = compressor.stats()
+    compressor.close()
+    click.echo(f"awecompress {__version__}")
+    click.echo(f"  proxy     : {'running at ' + url if running else 'not running'}")
+    click.echo(f"  upstream  : {cfg.upstream}")
+    click.echo(f"  compress  : above {cfg.threshold_tokens} est. tokens, "
+               f"keep last {cfg.keep_recent_turns} turns, min span {cfg.min_span_tokens}")
+    click.echo(f"  protected : {len(cfg.protected_tools)} tools"
+               + (f", {len(cfg.protected_file_patterns)} file patterns"
+                  if cfg.protected_file_patterns else ""))
+    click.echo(f"  summaries : {stats['sessions']} sessions, {stats['calls']} summary calls, "
+               f"~{stats['saved_tokens']} tokens saved")
+    click.echo(f"  store     : {cfg.db_path}")
+
+
+@cli.group()
+def config() -> None:
+    """Show the config file."""
+
+
+@config.command("path")
+def config_path_cmd() -> None:
+    """Print the config file path."""
+    click.echo(str(config_path()))
+
+
+@config.command("show")
+def config_show() -> None:
+    """Print the config file contents."""
+    path = config_path()
+    if not path.exists():
+        click.echo(f"(no config file at {path} — defaults apply; run 'awecompress serve' to write one)")
+        return
+    click.echo(path.read_text().rstrip())
+
+
+@cli.command()
+@click.option("--config", "config_file", type=click.Path(), default=None,
+              help="Config file path (default: ~/.config/awecompress/config.json).")
+@click.option("--yes", is_flag=True, help="Delete without asking.")
+def clear(yes: bool, config_file: str) -> None:
+    """Delete stored summaries (sessions start uncompressed)."""
+    cfg = load_config(Path(config_file).expanduser() if config_file else None)
+    path = Path(cfg.db_path)
+    if not path.exists():
+        click.echo("nothing to clear — no summary store yet")
+        return
+    if not yes:
+        click.confirm(f"clear {path} (all frozen summaries)?", abort=True)
+    # Clear rows rather than unlink the file: through WAL this also empties
+    # the store a running proxy sees, instead of leaving it on a deleted file.
+    compressor = Compressor(path)
+    sessions = compressor.stats()["sessions"]
+    compressor.clear()
+    compressor.close()
+    click.echo(f"cleared {sessions} session(s) from {path}")
+
+
+def main() -> None:
+    cli()
+
+
+if __name__ == "__main__":
+    main()

awecompress/compress.py

@@ -0,0 +1,260 @@
+"""Compression planning over a request body: pure functions, no I/O. The
+integrate/server layers turn a Plan into one LLM call (summarize.py) and a
+frozen replacement (store.py).
+
+Model: a session's oldest whole turns are replaced by a single summary
+message. A cut may only land on a turn boundary — a message a human actually
+sent — so a tool call is never separated from its result and upstream pairing
+validation never sees a half pair. History shapes are per-protocol
+(protocols.py); this module only plans.
+
+Protected content (DCP's Compress idea, proxy-shaped): tool calls whose name
+is in protectedTools, or whose path-ish arguments match protectedFilePatterns,
+render into the summarizer transcript uncapped and marked [protected]; the
+summary prompt demands their content survive compression verbatim — todo
+lists, plans, and task/skill outcomes are live planning state, not history
+noise.
+
+Summaries are frozen: every later request reuses the same stored bytes for
+the same covered prefix, so the provider prompt cache sees a stable prefix.
+Growing the covered span rewrites the summary once — a one-time cache miss.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from fnmatch import fnmatch
+
+from awecompress.protocols import (
+    ENDPOINT_PATHS,  # noqa: F401  (re-export: standalone server relays by it)
+    PROTOCOLS,
+    canonical,
+    estimate_tokens,  # noqa: F401  (re-export: callers import it from here)
+)
+
+# Marks the synthetic message we inject, in place of the covered prefix.
+SUMMARY_MARKER = "[awecompress: summary of earlier turns — original messages removed]"
+
+# Per-tool-input cap when flattening history for the summarizer: the summary
+# needs what a call did, not every byte of its arguments.
+TOOL_INPUT_CAP = 2000
+
+# Protected by default: planning-state tools whose trace must survive
+# compression intact (same convention as DCP's compress.protectedTools).
+DEFAULT_PROTECTED_TOOLS = ("task", "skill", "todowrite", "todoread", "updateplan")
+
+# Argument keys treated as file paths for protectedFilePatterns matching.
+_PATH_KEYS = ("file_path", "path", "filepath", "notebook_path")
+
+
+def _norm_tool(name: str) -> str:
+    """Tool-name identity: lowercase with separators stripped, so TodoWrite
+    == todo_write == todowrite (same convention as awerouter's odcp)."""
+    return name.lower().replace("_", "").replace("-", "")
+
+
+def is_protected(name, args, protected_tools, patterns) -> bool:
+    """One tool call's protection verdict. Name match is on the normalized
+    form; pattern match tests the call's path-ish argument values."""
+    if _norm_tool(name or "") in protected_tools:
+        return True
+    if patterns and isinstance(args, dict):
+        for key in _PATH_KEYS:
+            value = args.get(key)
+            if isinstance(value, str) and any(fnmatch(value, p) for p in patterns):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Turn boundaries
+# ---------------------------------------------------------------------------
+
+def _is_turn_start(msg) -> bool:
+    """Anthropic-shaped turn test (kept for direct callers/tests)."""
+    return PROTOCOLS["anthropic"].is_turn_start(msg)
+
+
+def safe_cut(messages: list, keep_recent_turns: int, protocol: str = "anthropic") -> int:
+    """Index where the compressed span may end: the start of the
+    keep_recent_turns-th-from-last genuine user turn, or 0 when the history
+    is too short to cut anything."""
+    adapter = PROTOCOLS[protocol]
+    boundaries = [i for i, m in enumerate(messages) if adapter.is_turn_start(m)]
+    if len(boundaries) <= keep_recent_turns:
+        return 0
+    return boundaries[-keep_recent_turns]
+
+
+# ---------------------------------------------------------------------------
+# Identity and change detection
+# ---------------------------------------------------------------------------
+
+def session_key(body: dict, protocol: str = "anthropic") -> str:
+    """Stable identity across one session's requests: the protocol's standing
+    instructions plus the first message (coding agents resend both
+    byte-identical every turn). Empty string when there is nothing stable to
+    hold on to."""
+    adapter = PROTOCOLS[protocol]
+    messages = adapter.message_list(body)
+    if not messages:
+        return ""
+    return hashlib.sha256(canonical([adapter.system_identity(body),
+                                      messages[0]]).encode()).hexdigest()[:16]
+
+
+def prefix_hash(messages: list, upto: int) -> str:
+    """Fingerprint of messages[:upto] — detects a session rewound to a
+    checkpoint or forked under a stored summary."""
+    return hashlib.sha256(canonical(messages[:upto]).encode()).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Token estimates
+# ---------------------------------------------------------------------------
+
+def estimate_messages_tokens(messages: list, protocol: str = "anthropic") -> int:
+    adapter = PROTOCOLS[protocol]
+    return sum(adapter.item_tokens(m) for m in messages)
+
+
+def estimate_body_tokens(body: dict, messages: list, protocol: str = "anthropic") -> int:
+    """Rough size of the request as sent: standing instructions plus messages.
+    Tool definitions are constant per session and deliberately excluded."""
+    return PROTOCOLS[protocol].system_tokens(body) \
+        + estimate_messages_tokens(messages, protocol)
+
+
+# ---------------------------------------------------------------------------
+# Transcript rendering (input to the summarizer)
+# ---------------------------------------------------------------------------
+
+def render_transcript(messages: list, cfg, protocol: str = "anthropic") -> str:
+    """Flatten messages to compact text for the summarizer, applying the
+    protection rules. Protected calls render uncapped and carry the
+    [protected] marker; everything else is capped (result cap from cfg,
+    TOOL_INPUT_CAP for arguments). Thinking/reasoning never renders — the
+    assistant's visible text restates whatever mattered."""
+    adapter = PROTOCOLS[protocol]
+    tools = {_norm_tool(t) for t in (getattr(cfg, "protected_tools", None) or ())}
+    patterns = tuple(getattr(cfg, "protected_file_patterns", None) or ())
+    lines = []
+    for seg in adapter.segments(messages):
+        kind = seg[0]
+        if kind == "text":
+            _, role, text = seg
+            if text.strip():
+                lines.append(f"{role}: {text}")
+        elif kind == "call":
+            _, name, args = seg
+            protected = is_protected(name, args, tools, patterns)
+            text = canonical(args)
+            if not protected and len(text) > TOOL_INPUT_CAP:
+                text = text[:TOOL_INPUT_CAP] + f" [... {len(text) - TOOL_INPUT_CAP} chars truncated]"
+            mark = " [protected]" if protected else ""
+            lines.append(f"assistant calls {name}{mark}: {text}")
+        else:  # result
+            _, name, args, text, errored = seg
+            protected = is_protected(name, args, tools, patterns)
+            cap = cfg.transcript_result_cap
+            if not protected and len(text) > cap:
+                text = text[:cap] + f" [... {len(text) - cap} chars truncated]"
+            if errored:
+                text = f"[error] {text}"
+            mark = " [protected]" if protected else ""
+            lines.append(f"tool (result){mark}: {text}")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# The synthetic summary message
+# ---------------------------------------------------------------------------
+
+def summary_message(summary: str, protocol: str = "anthropic") -> dict:
+    return PROTOCOLS[protocol].summary_message(f"{SUMMARY_MARKER}\n\n{summary}")
+
+
+def apply_summary(body: dict, summary: str, upto: int, protocol: str) -> list:
+    """The rewritten history: protected preamble (openai-chat standing
+    instructions), the summary message, then everything from `upto` on."""
+    adapter = PROTOCOLS[protocol]
+    items = adapter.message_list(body) or []
+    return list(items[:adapter.preamble(items)]) \
+        + [summary_message(summary, protocol)] + list(items[upto:])
+
+
+# ---------------------------------------------------------------------------
+# Planning
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Plan:
+    action: str                    # "passthrough" | "reuse" | "init" | "extend"
+    key: str = ""                  # session key (empty when unusable)
+    base_upto: int = 0             # messages already covered by a stored summary
+    upto: int = 0                  # messages covered once the plan runs
+    prev_summary: str = ""         # stored summary to merge into ("" when fresh)
+    span_tokens: int = 0           # estimate of the compressible new span
+    body_tokens: int = 0           # estimate of the body as it would be sent now
+    raw_tokens: int = 0            # estimate of the body with no compression
+    saved_tokens: int = 0          # raw_tokens - body_tokens (reuse path)
+
+
+def plan(body, stored, cfg, protocol: str = "anthropic") -> Plan:
+    """Decide what to do with this request body.
+
+    passthrough — nothing to do (session small, or nothing new to cover).
+    reuse       — stored summary still covers the prefix; apply it, no LLM call.
+    init/extend — over threshold with a new compressible span; summarize
+                  messages[base_upto:cut] and freeze the result.
+
+    A stored record whose prefix no longer hashes right (session rewound to a
+    checkpoint, or forked) is ignored: the honest reading of a changed
+    history is to start over, never to splice an old summary onto it.
+    """
+    if not isinstance(body, dict):
+        return Plan("passthrough")
+    adapter = PROTOCOLS[protocol]
+    messages = adapter.message_list(body)
+    if not messages:
+        return Plan("passthrough")
+    key = session_key(body, protocol)
+    if not key:
+        return Plan("passthrough")
+    start = adapter.preamble(messages)   # standing instructions stay messages
+
+    if stored is not None and stored.prefix_hash != prefix_hash(messages, min(stored.upto, len(messages))):
+        stored = None
+    base = stored.upto if stored is not None else 0
+
+    raw_tokens = estimate_body_tokens(body, messages, protocol)
+    if stored is not None:
+        summary_item = summary_message(stored.summary, protocol)
+        body_tokens = adapter.system_tokens(body) \
+            + estimate_messages_tokens(messages[:start], protocol) \
+            + adapter.item_tokens(summary_item) \
+            + estimate_messages_tokens(messages[base:], protocol)
+    else:
+        body_tokens = raw_tokens
+
+    def reuse() -> Plan:
+        return Plan("reuse", key, base, base, stored.summary, 0,
+                    body_tokens, raw_tokens, max(0, raw_tokens - body_tokens))
+
+    cut = safe_cut(messages, cfg.keep_recent_turns, protocol)
+    if cut <= max(base, start):
+        return reuse() if stored is not None else Plan("passthrough", key, raw_tokens=raw_tokens)
+    if body_tokens <= cfg.threshold_tokens:
+        return reuse() if stored is not None else Plan("passthrough", key, raw_tokens=raw_tokens)
+
+    span_tokens = estimate_messages_tokens(messages[max(base, start):cut], protocol)
+    if span_tokens < cfg.min_span_tokens:
+        # Over threshold but the new span is crumbs — wait for more history
+        # rather than burn a summary call on nothing.
+        return reuse() if stored is not None else Plan("passthrough", key, raw_tokens=raw_tokens)
+
+    action = "extend" if base > 0 else "init"
+    return Plan(action, key, base, cut,
+                stored.summary if stored is not None else "",
+                span_tokens, body_tokens, raw_tokens)

awecompress/config.py

@@ -0,0 +1,161 @@
+"""Config: one JSON file, written with defaults on first run.
+
+Location: $AWECOMPRESS_CONFIG_DIR or ~/.config/awecompress/config.json
+(same convention as awerouter). The summary store lives beside it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, replace
+from pathlib import Path
+from urllib.parse import urlparse
+
+from awecompress.compress import DEFAULT_PROTECTED_TOOLS
+
+DEFAULT_PORT = 8808
+DEFAULT_UPSTREAM = "http://127.0.0.1:20128"  # awerouter's default listen port
+
+# Rough token estimates (chars/4 heuristic) — a 200k-token model's usable
+# history comfortably crosses 60k long before the hard limit; compressing
+# early keeps the summary small relative to what it replaces.
+DEFAULT_THRESHOLD_TOKENS = 60000
+DEFAULT_KEEP_RECENT_TURNS = 4
+DEFAULT_MIN_SPAN_TOKENS = 8000
+DEFAULT_TRANSCRIPT_RESULT_CAP = 4000
+DEFAULT_SUMMARY_MAX_TOKENS = 2048
+DEFAULT_SUMMARY_TIMEOUT_SECONDS = 60
+
+def die(message: str) -> "SystemExit":
+    raise SystemExit(f"awecompress: {message}")
+
+
+def config_dir() -> Path:
+    return Path(os.environ.get("AWECOMPRESS_CONFIG_DIR", "~/.config/awecompress")).expanduser()
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def db_path() -> Path:
+    return config_dir() / "summaries.db"
+
+
+@dataclass
+class Config:
+    port: int = DEFAULT_PORT
+    host: str = "127.0.0.1"
+    upstream: str = DEFAULT_UPSTREAM
+    threshold_tokens: int = DEFAULT_THRESHOLD_TOKENS
+    keep_recent_turns: int = DEFAULT_KEEP_RECENT_TURNS
+    min_span_tokens: int = DEFAULT_MIN_SPAN_TOKENS
+    transcript_result_cap: int = DEFAULT_TRANSCRIPT_RESULT_CAP
+    # Empty = summarize with the request's own model, which the upstream
+    # (awerouter) then routes like any other request — usually flash.
+    summary_model: str = ""
+    summary_max_tokens: int = DEFAULT_SUMMARY_MAX_TOKENS
+    summary_timeout_seconds: int = DEFAULT_SUMMARY_TIMEOUT_SECONDS
+    # Protected content (see compress.py): these tools' calls and results
+    # render into the summarizer transcript uncapped and must survive the
+    # summary verbatim; file patterns protect path-matching calls the same way.
+    protected_tools: tuple = DEFAULT_PROTECTED_TOOLS
+    protected_file_patterns: tuple = ()
+    db_path: str = ""  # empty = db_path() default
+
+
+def _default_file() -> dict:
+    return {
+        "port": DEFAULT_PORT,
+        "upstream": DEFAULT_UPSTREAM,
+        "thresholdTokens": DEFAULT_THRESHOLD_TOKENS,
+        "keepRecentTurns": DEFAULT_KEEP_RECENT_TURNS,
+        "minSpanTokens": DEFAULT_MIN_SPAN_TOKENS,
+        "summaryModel": "",
+        "summaryMaxTokens": DEFAULT_SUMMARY_MAX_TOKENS,
+        "protectedTools": list(DEFAULT_PROTECTED_TOOLS),
+        "protectedFilePatterns": [],
+    }
+
+
+# File keys are camelCase (hand-edited like awerouter's routing.json);
+# dataclass fields stay snake_case.
+_KEY_MAP = {
+    "port": "port",
+    "host": "host",
+    "upstream": "upstream",
+    "thresholdTokens": "threshold_tokens",
+    "keepRecentTurns": "keep_recent_turns",
+    "minSpanTokens": "min_span_tokens",
+    "transcriptResultCap": "transcript_result_cap",
+    "summaryModel": "summary_model",
+    "summaryMaxTokens": "summary_max_tokens",
+    "summaryTimeoutSeconds": "summary_timeout_seconds",
+    "protectedTools": "protected_tools",
+    "protectedFilePatterns": "protected_file_patterns",
+    "dbPath": "db_path",
+}
+
+_INT_FIELDS = {
+    "port", "threshold_tokens", "keep_recent_turns", "min_span_tokens",
+    "transcript_result_cap", "summary_max_tokens", "summary_timeout_seconds",
+}
+_STR_FIELDS = {"host", "upstream", "summary_model", "db_path"}
+_LIST_FIELDS = {"protected_tools", "protected_file_patterns"}
+
+
+def load_config(path: "Path | None" = None) -> Config:
+    """Load config, creating the default file on first run. Dies on unknown
+    keys or invalid values — a typo must not silently become a default."""
+    path = path or config_path()
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(_default_file(), indent=2) + "\n")
+        print(f"awecompress: wrote default config to {path}")
+        cfg = Config()
+    else:
+        try:
+            raw = json.loads(path.read_text())
+        except json.JSONDecodeError as exc:
+            die(f"{path}: invalid JSON ({exc})")
+        if not isinstance(raw, dict):
+            die(f"{path}: expected a JSON object")
+
+        cfg = Config()
+        for key, val in raw.items():
+            if key not in _KEY_MAP:
+                die(f"{path}: unknown key '{key}' (see README for the full list)")
+            field = _KEY_MAP[key]
+            if field in _INT_FIELDS:
+                if not isinstance(val, int) or isinstance(val, bool):
+                    die(f"{path}: '{key}' must be an integer")
+            elif field in _STR_FIELDS:
+                if not isinstance(val, str):
+                    die(f"{path}: '{key}' must be a string")
+            elif field in _LIST_FIELDS:
+                if not isinstance(val, list) or not all(isinstance(v, str) for v in val):
+                    die(f"{path}: '{key}' must be an array of strings")
+                val = tuple(val)
+            setattr(cfg, field, val)
+
+    _validate(cfg)
+    return replace(cfg, db_path=cfg.db_path or str(db_path()))
+
+
+def _validate(cfg: Config) -> None:
+    if not (1 <= cfg.port <= 65535):
+        die(f"port must be 1..65535, got {cfg.port}")
+    parsed = urlparse(cfg.upstream)
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        die(f"upstream must be an http(s) URL, got '{cfg.upstream}'")
+    if cfg.threshold_tokens < 1000:
+        die(f"thresholdTokens must be >= 1000, got {cfg.threshold_tokens}")
+    if cfg.keep_recent_turns < 1:
+        die(f"keepRecentTurns must be >= 1, got {cfg.keep_recent_turns}")
+    if cfg.min_span_tokens < 1000:
+        die(f"minSpanTokens must be >= 1000, got {cfg.min_span_tokens}")
+    if cfg.summary_max_tokens < 256:
+        die(f"summaryMaxTokens must be >= 256, got {cfg.summary_max_tokens}")
+    if not (10 <= cfg.summary_timeout_seconds <= 600):
+        die(f"summaryTimeoutSeconds must be 10..600, got {cfg.summary_timeout_seconds}")