acm-context-management 0.2.0__py3-none-any.whl

acm_context_management-0.2.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: acm-context-management
+Version: 0.2.0
+Summary: Context-management gateway + MCP server that brings the ACM techniques (trimming, summarisation, image-recall, memory) into any IDE
+Project-URL: Homepage, https://github.com/HarishanA21/agentic_context_management
+Project-URL: Repository, https://github.com/HarishanA21/agentic_context_management
+Author: ACM
+License: MIT
+Keywords: claude-code,context-management,cursor,gateway,ides,llm,mcp,vscode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain>=0.3
+Requires-Dist: mcp>=1.2
+Requires-Dist: pillow>=10
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ACM Extension — context management for any IDE
+
+This folder is **self-contained**. It turns the context-management engine that
+already powers the website (in [`../backend`](../backend)) into something usable
+from VSCode, Cursor, Antigravity, Claude Code, and Windsurf — **without changing
+a single line of the website's code.**
+
+It reaches the IDEs through three surfaces (see
+[`../EXTENSION_PLAN.md`](../EXTENSION_PLAN.md) for the why):
+
+| Folder | Surface | What it is |
+|---|---|---|
+| `acm_gateway/` | **Gateway** | A local OpenAI/Anthropic-compatible proxy. The IDE talks to it as if it were the AI; it applies every technique on the wire, then forwards to the real provider. Full feature parity. |
+| `acm_mcp/` | **MCP** | An MCP server exposing `remember` / `recall` / `compact` / `set_profile` tools. Works in *every* MCP-capable IDE. |
+| `adapters/` | **Hooks + config** | Per-IDE glue: Claude Code hooks, Cursor `mcp.json`, VSCode notes. |
+| `acm_engine/` | — | Thin bridge that imports the techniques from `../backend` so there is **one** source of truth. |
+
+## How it reuses the website's engine
+
+`acm_engine/` puts `../backend` on `sys.path` and re-exports the pure technique
+functions (`trim_tool_results`, `summarise_old_messages`,
+`sliding_window_trim`, `evict_stale_images`, `annotate_cache_breakpoints`) plus
+the `Profile` schema. Nothing in `../backend` is edited. The website and the
+extension share the same code; fix a bug once, both benefit.
+
+## Quick start (gateway)
+
+```bash
+cd extension
+uv venv --python 3.11
+source .venv/bin/activate
+uv pip install -e .
+
+# point it at any OpenAI-compatible upstream (OpenRouter shown)
+export ACM_UPSTREAM_BASE_URL=https://openrouter.ai/api/v1
+export ACM_UPSTREAM_API_KEY=sk-or-v1-...
+
+acm-gateway            # serves http://127.0.0.1:8807
+```
+
+Then tell the IDE the AI lives at `http://127.0.0.1:8807/v1` (Cursor: custom
+OpenAI base URL; Claude Code: `ANTHROPIC_BASE_URL`).
+
+## Config
+
+A single [`config/acm.config.example.json`](config/acm.config.example.json)
+holds the active profile (which techniques are on). Copy it to
+`config/acm.config.json` and edit, or set `ACM_CONFIG` to its path. The schema
+is the website's `Profile` model — same presets (`minimal`, `long_chat`,
+`power_research`, `cheap_long`, `visual_recall`).
+
+## Status
+
+- **Gateway** — runnable. OpenAI (`/v1/chat/completions`) **and** Anthropic
+  (`/v1/messages`) surfaces; full technique pipeline (trim / summarise / sliding
+  window / image-evict / cache breakpoints / **visual method** — rasterise big
+  tool outputs to images); **manual message removal** (cascade-safe drop-list,
+  persisted to `~/.acm/dropped.json`); **multi-provider routing** (OpenAI /
+  OpenRouter / Google / Azure on the OpenAI surface, Anthropic native; creds in
+  `~/.acm/providers.json`; route by `x-acm-provider` header, `slug/model`
+  prefix, or default — Bedrock via OpenRouter since it needs AWS SigV4); control
+  plane (`/status`, `/profile`, `/memory`, `/compact`, `/conversations`,
+  `/messages*`, `/providers*`).
+- **MCP server** — runnable: memory (`remember`/`recall`), `compact`,
+  `set_profile`/`status`, manual removal (`list_messages`/`drop_message`/
+  `restore_message`), providers (`list_providers`/`add_provider`/
+  `set_default_provider`), **sub-agent** (`spawn_subagent`), and **JIT retrieval**
+  (`find_files`/`read_slice`/`grep_files`).
+- **Claude Code** — gateway + hooks (trim + memory) + MCP. Done.
+- **Cursor** — gateway + hooks (capture + **compact-on-stop**) + MCP. Done.
+- **VSCode** — full extension (Language Model Tools + `@acm` chat participant +
+  webview settings) talking to the gateway; MCP drop-in for Antigravity /
+  Windsurf. TypeScript is written but not yet `tsc`-compiled here (needs
+  `npm install` with `@types/vscode`).
+
+Remaining work is marked with `# TODO(acm)` / `TODO(acm)`: orphan-`tool_use`
+pruning on the Anthropic path, React components in the VSCode webview, and
+auto-starting the gateway from the extension.

acm_context_management-0.2.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+acm_engine/__init__.py,sha256=sbBeugN4NF3NDkRm_N4rUe2lkWVRZv_jOWMkflnSmsQ,4167
+acm_engine/_vendor/cache_layout.py,sha256=R5QTIudjbb4hE_JxXMFmXwEy49rMgmc9cYhDbdElWTs,9004
+acm_engine/_vendor/context_editing.py,sha256=VG1EgNazNTrKxy_v6ZKtAOI3GPgvQc6bem-5Cstw2Mg,33463
+acm_engine/_vendor/context_profiles.py,sha256=UYyqBT4n82KXzdjLP_WqWcnREz3fCVb3ulPqbL5raLM,21699
+acm_engine/_vendor/relevance.py,sha256=_jmO4r3VHybkh3jp7IcW0vIaeM7jeEKKtE29WhEqwjs,24931
+acm_engine/_vendor/relevance_encoder.py,sha256=6eVtzbv5U8HEwkpbYvdoSO_FQ1ywmCnH3nBAadm6Lcw,9377
+acm_engine/_vendor/visual_tool/__init__.py,sha256=HjQMBbuMAITqaMDjHbDAl5U_iwjsAUUbYXC5vujuamk,379
+acm_engine/_vendor/visual_tool/indexer.py,sha256=Y8fiVwYGAW491b_fKXs6LSJDmEVY2rZGpuTm0YzfxFY,4518
+acm_engine/_vendor/visual_tool/rasterizer.py,sha256=PlrYhGpARasA82RWlEtRcsxf4dczPXcTYTZg2k7Fruo,8082
+acm_gateway/__init__.py,sha256=g8Q4-CcprvonNmxH2D42Sk5NbEIbzTm7q3AmAT_2vuk,204
+acm_gateway/__main__.py,sha256=6v5YKAOOLgtC-v0_g_SRyo7fqB8Vtf4KoUpjUK-a4Sk,485
+acm_gateway/app.py,sha256=rcjMA4__AQKzSAlDPPVD2uv6fXbJmdO7zKtttHBolC8,48025
+acm_gateway/config.py,sha256=SGVrqSHifiocJdN1tTBs9VKzONlvZB_3lEn6BbxX1bo,6756
+acm_gateway/context_windows.py,sha256=FiqK4nplhJWRkSS0mpjl5hrkYx3Oq4UxzuuTkgMnb44,8533
+acm_gateway/droplist.py,sha256=IOI6gH9MpZ5NTK5WC7S6SfLVbCFsm4sUp6VlhLC-yr4,20237
+acm_gateway/events.py,sha256=le7PaKs7oGOThL8JgYJ7_JbvRM_8jkQmT_Xc-DGp6h8,3248
+acm_gateway/pipeline.py,sha256=emI2SGfYiv6SVzAgySpKk1Lk29oMZNPSXBOO87-zekc,7252
+acm_gateway/providers_store.py,sha256=8uouaxwIjB9xZaABKXtfKwiGHIgc720sG6jLMFxFTus,8273
+acm_gateway/translate.py,sha256=B0UyKMJpZ4J5_FHGJr5_ezdN5PQrKxIFa55sJa5MalU,4364
+acm_gateway/translate_anthropic.py,sha256=knMrQX3OBhQGHWiaNeNBONxEOvnFo9pRhnXnkBLMLzo,10875
+acm_gateway/upstream.py,sha256=h15BsE9OmSGLU0BrjrAmTbr-2n2ZU5HGx9iX2fi14AQ,12246
+acm_gateway/visualizer.py,sha256=meEemUCfsM82lTlTEpckbedyLVk6OeXCa6g95Ec-zuw,4940
+acm_mcp/__init__.py,sha256=2OMuGY08Q_QKB1CZRjqNoeq73uJ9qYn3At8p-1-2s8M,213
+acm_mcp/jit.py,sha256=kWaVZOLmv2wfRGLvKMBYYQR-vbhHvjkMPF9pgu4MHKk,3897
+acm_mcp/memory_store.py,sha256=RmbXAFip1tkR60Vw1ylcTrwJbfR-APkNnEJpS16A5Z4,1835
+acm_mcp/server.py,sha256=nszX5lntSMIoYQPJgmJZfeL72At5lxz4x_oqjuSCQ4E,10107
+acm_context_management-0.2.0.dist-info/METADATA,sha256=mhLiY1MtoAS9LJ0MuTyUgJR1IsUQ1tVtMond_1pPUTw,5364
+acm_context_management-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+acm_context_management-0.2.0.dist-info/entry_points.txt,sha256=ddyNG1InNz_GZKa9Cq5udixszCy1YZ10hCqsSOgFmag,88
+acm_context_management-0.2.0.dist-info/RECORD,,

acm_context_management-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

acm_context_management-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+acm-gateway = acm_gateway.__main__:main
+acm-mcp = acm_mcp.server:main

acm_engine/__init__.py

@@ -0,0 +1,124 @@
+"""Bridge to the website's context-management engine.
+
+This is the *one* place the extension reaches into ``../backend``. It puts the
+backend directory on ``sys.path`` and re-exports the **pure** technique
+functions plus the ``Profile`` schema, so the gateway and the website run the
+exact same code. Nothing in ``../backend`` is edited.
+
+Why only the pure functions? ``context_editing.apply_context_edits`` is
+LangGraph-specific — it calls ``agent.get_state`` / ``agent.update_state``. The
+gateway has no LangGraph agent; it has a plain list of messages off the wire.
+So we import the lower-level building blocks (which operate on a
+``List[BaseMessage]``) and the gateway's own ``pipeline.py`` orchestrates them
+in the same fixed order ``apply_context_edits`` uses.
+
+If an import here ever fails, it's almost always because ``../backend`` moved or
+a dependency in ``backend/requirements.txt`` isn't installed in this venv.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Two ways to find the engine, in priority order:
+#   1. The **vendored** copy shipped inside the wheel (acm_engine/_vendor/) —
+#      this is what an end user who `pip install`ed the package gets. Refresh it
+#      from backend with `python scripts/sync_engine.py`.
+#   2. The repo's ../backend tree — used during local dev so a checkout runs the
+#      live engine without a sync step.
+# Whichever wins is put on sys.path so the engine's flat imports
+# (`import context_profiles`, `from context_editing import ...`) resolve.
+_VENDOR = Path(__file__).resolve().parent / "_vendor"
+_BACKEND = Path(__file__).resolve().parents[2] / "backend"
+
+if (_VENDOR / "context_profiles.py").is_file():
+    _ENGINE_DIR = _VENDOR
+elif (_BACKEND / "context_profiles.py").is_file():
+    _ENGINE_DIR = _BACKEND
+else:  # pragma: no cover - defensive
+    raise ImportError(
+        "acm_engine found neither a vendored engine (acm_engine/_vendor/) nor "
+        f"the repo backend at {_BACKEND}. Run `python scripts/sync_engine.py`."
+    )
+
+_engine_str = str(_ENGINE_DIR)
+if _engine_str not in sys.path:
+    sys.path.insert(0, _engine_str)
+
+# Re-export the schema (pure pydantic, zero app coupling).
+from context_profiles import (  # noqa: E402
+    BUILTIN_PRESETS,
+    DEFAULT_PRESET_NAME,
+    PRESET_SUMMARY,
+    Profile,
+    parse_profile,
+)
+
+# Re-export the pure, message-list-level techniques. None of these touch the
+# database, FastAPI, or a LangGraph agent — they take a list of messages and
+# return rewrites.
+from context_editing import (  # noqa: E402
+    _DEFAULT_SUMMARY_SYSTEM as DEFAULT_SUMMARY_SYSTEM,
+    evict_stale_images,
+    sliding_window_trim,
+    summarise_old_messages,
+    trim_tool_results,
+)
+from cache_layout import (  # noqa: E402
+    annotate_cache_breakpoints,
+    read_cache_tokens,
+)
+
+# Task-aware relevance pruning (suggest-only; judge engine ships now, encoder
+# seam ready for Phase 2). Pure, message-list-level like the rest.
+from relevance import (  # noqa: E402
+    Episode,
+    JudgeSuggester,
+    Suggestion,
+    active_task,
+    build_audit_rows,
+    load_audits,
+    load_feedback,
+    record_audit,
+    record_feedback,
+    segment_into_episodes,
+    suggest_removals,
+)
+
+# Local encoder engine (no LLM call). Heavy ML libs load lazily, so importing
+# the class here stays cheap even on a minimal install.
+from relevance_encoder import EncoderSuggester  # noqa: E402
+
+# Where the engine was actually loaded from (vendored copy or repo backend).
+ENGINE_DIR = _ENGINE_DIR
+BACKEND_DIR = _ENGINE_DIR  # back-compat alias
+
+__all__ = [
+    "ENGINE_DIR",
+    "BACKEND_DIR",
+    "BUILTIN_PRESETS",
+    "DEFAULT_PRESET_NAME",
+    "PRESET_SUMMARY",
+    "Profile",
+    "parse_profile",
+    "DEFAULT_SUMMARY_SYSTEM",
+    "trim_tool_results",
+    "summarise_old_messages",
+    "sliding_window_trim",
+    "evict_stale_images",
+    "annotate_cache_breakpoints",
+    "read_cache_tokens",
+    "Episode",
+    "Suggestion",
+    "JudgeSuggester",
+    "segment_into_episodes",
+    "active_task",
+    "suggest_removals",
+    "record_feedback",
+    "load_feedback",
+    "build_audit_rows",
+    "record_audit",
+    "load_audits",
+    "EncoderSuggester",
+]

acm_engine/_vendor/cache_layout.py

@@ -0,0 +1,218 @@
+"""Provider-agnostic image-recall middleware (cache + eviction at call time).
+
+This is the *common* solution for the image-recall techniques — it works for
+every model the app can route to, because it leans on the one thing all
+caching backends share: **a stable, append-only prefix**.
+
+  * OpenAI / Azure (and OpenAI models via OpenRouter): caching is automatic.
+    Keeping the prefix stable is all that's needed; the cache_control hints
+    we add are simply ignored.
+  * Anthropic / Bedrock-Claude / Gemini (incl. via OpenRouter): caching is
+    explicit. OpenRouter forwards the ``cache_control`` markers we put on
+    content blocks straight through to the upstream provider.
+
+The middleware does both halves of "visual recall", gated by the profile's
+``image_recall.mode``:
+
+  * eviction (``evict`` / ``cache_evict``) — inside ``wrap_model_call`` we
+    drop the pixels of all but the most-recent K image tool-results from the
+    request the model sees, replacing them with their REFERENCES + a digest.
+    Doing it here (not just between turns) means it also fires inside a single
+    agent tool-loop — which is what the single-shot demo needs.
+  * caching (``cache`` / ``cache_evict``) — mark the stable prefix with an
+    ephemeral breakpoint so re-reading the frozen history is cheap/fast.
+    Caching never changes the model's output.
+
+Gotchas baked in:
+  * Breakpoints go on a *text* block, never an image/tool block (Anthropic
+    rejects ``cache_control`` there — langchain issue #34920).
+  * String content is widened to a one-element list so we can hang a marker.
+  * Everything is defensive: an image-recall hiccup must never break a turn.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage
+
+log = logging.getLogger("image_recall")
+
+
+# ─── cache-token reader (used by demo + chat to surface cache details) ───
+
+
+def read_cache_tokens(msg: BaseMessage) -> Dict[str, int]:
+    """Pull cache hit/write counts off an AIMessage, provider-agnostic.
+
+    Returns ``{cache_read, cache_write}``. Anthropic/Gemini expose these via
+    ``usage_metadata.input_token_details`` (cache_read / cache_creation);
+    OpenAI exposes a ``cache_read`` only. Falls back to ``response_metadata``
+    when the normalised field is absent. All-zero when nothing cached.
+    """
+    out = {"cache_read": 0, "cache_write": 0}
+    um = getattr(msg, "usage_metadata", None) or {}
+    details = um.get("input_token_details") or {}
+    if isinstance(details, dict):
+        out["cache_read"] = int(details.get("cache_read") or 0)
+        out["cache_write"] = int(
+            details.get("cache_creation") or details.get("cache_write") or 0
+        )
+    if out["cache_read"] == 0 and out["cache_write"] == 0:
+        # OpenAI-style raw usage on response_metadata.
+        rm = getattr(msg, "response_metadata", None) or {}
+        usage = rm.get("usage") or rm.get("token_usage") or {}
+        ptd = (usage.get("prompt_tokens_details") or {}) if isinstance(usage, dict) else {}
+        if isinstance(ptd, dict):
+            out["cache_read"] = int(ptd.get("cached_tokens") or 0)
+    return out
+
+
+# ─── cache breakpoint placement ──────────────────────────────────────────
+
+
+def _last_stable_index(messages: List[BaseMessage]) -> Optional[int]:
+    """Index of the last message in the *settled* prefix (just before the
+    final HumanMessage). The newest turn stays dynamic / reprocessed fresh."""
+    if len(messages) < 2:
+        return None
+    last_human = None
+    for i in range(len(messages) - 1, -1, -1):
+        if isinstance(messages[i], HumanMessage):
+            last_human = i
+            break
+    boundary = (last_human - 1) if last_human is not None else (len(messages) - 1)
+    return boundary if boundary >= 0 else None
+
+
+def _mark_block(msg: BaseMessage, ttl: str) -> bool:
+    """Attach an ephemeral cache_control marker to a *text* block of ``msg``.
+    Skips image / non-text blocks. Returns True if a marker was placed."""
+    cc: Dict[str, Any] = {"type": "ephemeral"}
+    if ttl == "1h":
+        cc["ttl"] = "1h"
+    content = getattr(msg, "content", None)
+    if isinstance(content, str):
+        if not content.strip():
+            return False
+        msg.content = [{"type": "text", "text": content, "cache_control": cc}]
+        return True
+    if isinstance(content, list):
+        for block in reversed(content):
+            if isinstance(block, dict) and block.get("type") == "text":
+                block["cache_control"] = cc
+                return True
+    return False
+
+
+def annotate_cache_breakpoints(
+    messages: List[BaseMessage],
+    *,
+    system: Optional[BaseMessage] = None,
+    ttl: str = "5m",
+) -> int:
+    """Place ephemeral breakpoints on the stable prefix (system + last settled
+    message). Mutates in place; returns how many breakpoints were set."""
+    placed = 0
+    if isinstance(system, SystemMessage) and _mark_block(system, ttl):
+        placed += 1
+    idx = _last_stable_index(messages)
+    if idx is not None:
+        target = messages[idx]
+        if target.__class__.__name__ == "ToolMessage":
+            # Don't mark a bare tool block; walk back to an AI/System text block.
+            for j in range(idx, -1, -1):
+                if isinstance(messages[j], (AIMessage, SystemMessage)):
+                    target = messages[j]
+                    break
+        if _mark_block(target, ttl):
+            placed += 1
+    return placed
+
+
+# ─── the middleware ──────────────────────────────────────────────────────
+
+
+class ImageRecallMiddleware(AgentMiddleware):
+    """Applies the selected image-recall technique on every model call.
+
+    ``mode`` ∈ {off, cache, evict, cache_evict}. Provider-agnostic: caching is
+    a no-op effect for auto-caching backends and active for explicit ones.
+    Attach only when ``mode != off``.
+    """
+
+    def __init__(
+        self,
+        *,
+        mode: str = "off",
+        keep_recent_images: int = 3,
+        ttl: str = "5m",
+    ) -> None:
+        super().__init__()
+        self.mode = mode if mode in {"off", "cache", "evict", "cache_evict"} else "off"
+        self.keep_recent_images = max(1, int(keep_recent_images or 3))
+        self.ttl = ttl if ttl in {"5m", "1h"} else "5m"
+
+    @property
+    def caching_enabled(self) -> bool:
+        return self.mode in {"cache", "cache_evict"}
+
+    @property
+    def eviction_enabled(self) -> bool:
+        return self.mode in {"evict", "cache_evict"}
+
+    def _apply(self, request) -> None:
+        """Mutate request.messages in place: evict stale images, then mark
+        cache breakpoints. Order matters — eviction first so the breakpoint
+        lands on the de-imaged prefix."""
+        msgs = getattr(request, "messages", None)
+        if not msgs:
+            return
+        if self.eviction_enabled:
+            # Lazy import avoids a context_editing <-> cache_layout cycle.
+            from context_editing import evict_stale_images
+
+            replacements, info = evict_stale_images(
+                msgs, keep_recent_images=self.keep_recent_images
+            )
+            if replacements:
+                by_id = {getattr(r, "id", None): r for r in replacements}
+                request.messages = [
+                    by_id.get(getattr(m, "id", None), m) for m in msgs
+                ]
+                msgs = request.messages
+                log.info(
+                    "[image_recall] evicted %d stale image(s), kept %d as pixels, freed ~%d tokens",
+                    info["evicted"], info["kept_recent"], info["freed_tokens"],
+                )
+        if self.caching_enabled:
+            placed = annotate_cache_breakpoints(
+                msgs,
+                system=getattr(request, "system_message", None),
+                ttl=self.ttl,
+            )
+            if placed:
+                log.info(
+                    "[image_recall] placed %d cache breakpoint(s) (ttl=%s) on the stable prefix",
+                    placed, self.ttl,
+                )
+
+    def wrap_model_call(self, request, handler):  # type: ignore[override]
+        try:
+            self._apply(request)
+        except Exception as e:  # never break the turn over image-recall
+            log.warning("[image_recall] apply failed: %r", e)
+        return handler(request)
+
+    async def awrap_model_call(self, request, handler):  # type: ignore[override]
+        try:
+            self._apply(request)
+        except Exception as e:
+            log.warning("[image_recall] apply failed: %r", e)
+        return await handler(request)
+
+
+# Back-compat alias (earlier name during development).
+CachePrefixMiddleware = ImageRecallMiddleware