leancontext 2.0.0__py3-none-any.whl

leancontext/integrations/anthropic_native.py

@@ -0,0 +1,83 @@
+"""Run LeanContext's reduction alongside Anthropic's native context editing.
+
+LeanContext reduces tool outputs by content on the way in; Anthropic's context
+editing clears old tool results by age as the window grows. They're complementary,
+and this module turns both on for one client:
+
+    from leancontext.integrations.anthropic_native import wrap_anthropic_native
+    client = wrap_anthropic_native(anthropic.Anthropic(),
+                                   trigger_input_tokens=30000, keep_tool_uses=3)
+    # every messages.create now: (1) LeanContext-reduces tool_result blocks,
+    #                            (2) enables clear_tool_uses_20250919,
+    #                            (3) sends the context-management beta header.
+
+Schema verified against platform.claude.com/docs (context-editing), 2026-06.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ._common import wrap_messages_create
+
+#: Beta header required to enable context management on the Messages API.
+BETA_HEADER = "context-management-2025-06-27"
+
+#: Tool-result clearing strategy identifier (verbatim from the API).
+CLEAR_TOOL_USES = "clear_tool_uses_20250919"
+
+
+def context_management(
+    *,
+    trigger_input_tokens: int | None = None,
+    keep_tool_uses: int | None = None,
+    clear_at_least_input_tokens: int | None = None,
+    exclude_tools: Iterable[str] | None = None,
+    clear_tool_inputs: bool | None = None,
+) -> dict:
+    """Build the ``context_management`` request param for tool-result clearing.
+
+    Omitted fields fall back to the API defaults. With no args this returns the
+    minimal ``{"edits": [{"type": "clear_tool_uses_20250919"}]}``.
+    """
+    edit: dict[str, Any] = {"type": CLEAR_TOOL_USES}
+    if trigger_input_tokens is not None:
+        edit["trigger"] = {"type": "input_tokens", "value": int(trigger_input_tokens)}
+    if keep_tool_uses is not None:
+        edit["keep"] = {"type": "tool_uses", "value": int(keep_tool_uses)}
+    if clear_at_least_input_tokens is not None:
+        edit["clear_at_least"] = {"type": "input_tokens", "value": int(clear_at_least_input_tokens)}
+    if exclude_tools is not None:
+        edit["exclude_tools"] = list(exclude_tools)
+    if clear_tool_inputs is not None:
+        edit["clear_tool_inputs"] = bool(clear_tool_inputs)
+    return {"edits": [edit]}
+
+
+def beta_headers(extra: dict | None = None) -> dict:
+    """Return headers enabling context management, merged with ``extra``."""
+    headers = dict(extra or {})
+    headers.setdefault("anthropic-beta", BETA_HEADER)
+    return headers
+
+
+def wrap_anthropic_native(client: Any, *, reduce: bool = True, send_beta: bool = True, **cm) -> Any:
+    """Wrap an Anthropic client so messages.create composes reduction + native clearing.
+
+    ``cm`` kwargs are forwarded to :func:`context_management`. Fail-open.
+    """
+    cm_config = context_management(**cm)
+
+    def inject(kwargs: dict) -> None:
+        kwargs.setdefault("context_management", cm_config)
+        if send_beta:
+            kwargs["extra_headers"] = beta_headers(kwargs.get("extra_headers"))
+
+    try:
+        client.messages.create = wrap_messages_create(
+            client.messages.create, fmt="anthropic", opts={}, reduce=reduce, before=inject
+        )
+    except Exception:
+        pass  # fail open
+    return client

leancontext/integrations/clients.py

@@ -0,0 +1,58 @@
+"""SDK client wrappers for OpenAI, Anthropic, and Gemini.
+
+Wraps the provider's call (OpenAI ``chat.completions.create``, Anthropic
+``messages.create``, Gemini ``models.generate_content``) so tool outputs in the
+outbound request are reduced before they're sent. Contract-preserving and
+fail-open: anything unexpected leaves the original call untouched. Reductions are
+deterministic, so the prompt-cache prefix stays stable.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._common import wrap_messages_create
+
+
+def wrap_openai(client: Any, **opts) -> Any:
+    """Reduce tool outputs on an OpenAI client's chat.completions.create."""
+    try:
+        comp = client.chat.completions
+        comp.create = wrap_messages_create(comp.create, fmt="openai", opts=opts)
+    except Exception:
+        pass  # fail open
+    return client
+
+
+def wrap_anthropic(client: Any, **opts) -> Any:
+    """Reduce tool_result blocks on an Anthropic client's messages.create."""
+    try:
+        client.messages.create = wrap_messages_create(client.messages.create, fmt="anthropic", opts=opts)
+    except Exception:
+        pass  # fail open
+    return client
+
+
+def wrap_gemini(client: Any, **opts) -> Any:
+    """Reduce functionResponse tool outputs on a google-genai client's generate_content."""
+    try:
+        models = client.models
+        models.generate_content = wrap_messages_create(
+            models.generate_content, fmt="gemini", opts=opts, key="contents"
+        )
+    except Exception:
+        pass  # fail open
+    return client
+
+
+def looks_like_openai(obj: Any) -> bool:
+    return hasattr(obj, "chat") and hasattr(obj.chat, "completions")
+
+
+def looks_like_anthropic(obj: Any) -> bool:
+    return hasattr(obj, "messages") and hasattr(obj.messages, "create") \
+        and not looks_like_openai(obj)
+
+
+def looks_like_gemini(obj: Any) -> bool:
+    return hasattr(obj, "models") and hasattr(obj.models, "generate_content")

leancontext/integrations/decorator.py

@@ -0,0 +1,103 @@
+"""Framework-agnostic integration surfaces.
+
+These never change a tool's contract: a tool that returns ``str`` still returns
+``str``; anything non-string is passed through untouched. The agent cannot tell
+LeanContext is present. See AGENTS.md §5B/§5D.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from ..core import reduce_text
+from ._common import is_wrapped, mark
+
+
+def _reduced(result: Any, opts: dict) -> Any:
+    return reduce_text(result, **opts).text if isinstance(result, str) else result
+
+
+def wrap_callable(fn: Callable, **opts) -> Callable:
+    """Wrap a tool callable so its string return value is reduced at the source.
+
+    Works for sync and async tools; non-string returns pass through untouched.
+    """
+    if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def awrapper(*args, **kwargs):
+            return _reduced(await fn(*args, **kwargs), opts)
+
+        return mark(awrapper)
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        return _reduced(fn(*args, **kwargs), opts)
+
+    return mark(wrapper)
+
+
+def wrap(target: Any, **opts) -> Any:
+    """Best-effort universal wrap.
+
+    Accepts a plain callable, a list/tuple of tools, an OpenAI/Anthropic SDK client,
+    or a framework tool object exposing its callable on a known attribute. Anything
+    it doesn't recognise is returned unchanged — fail open.
+    """
+    if isinstance(target, (list, tuple)):
+        return type(target)(wrap(t, **opts) for t in target)
+
+    # Framework tool objects first. Several are callable themselves, so they must
+    # be wrapped in place (keeping their schema) before the plain-callable path.
+    try:
+        from .frameworks import (
+            looks_like_agno_tool,
+            looks_like_langchain_tool,
+            wrap_agno,
+            wrap_langchain,
+        )
+
+        if looks_like_langchain_tool(target):
+            return wrap_langchain(target, **opts)
+        if looks_like_agno_tool(target):
+            return wrap_agno(target, **opts)
+    except Exception:
+        pass  # fail open
+
+    # SDK clients (OpenAI / Anthropic / Gemini): reduce messages on the call.
+    try:
+        from .clients import (
+            looks_like_anthropic,
+            looks_like_gemini,
+            looks_like_openai,
+            wrap_anthropic,
+            wrap_gemini,
+            wrap_openai,
+        )
+
+        if looks_like_openai(target):
+            return wrap_openai(target, **opts)
+        if looks_like_anthropic(target):
+            return wrap_anthropic(target, **opts)
+        if looks_like_gemini(target):
+            return wrap_gemini(target, **opts)
+    except Exception:
+        pass  # fail open
+
+    # Plain callable tools.
+    if callable(target) and not isinstance(target, type):
+        return target if is_wrapped(target) else wrap_callable(target, **opts)
+
+    # Fallback for other tool objects: wrap the user callable in place. These are
+    # the attribute names frameworks expose their tool function on (LlamaIndex .fn,
+    # Pydantic AI .function, OpenAI Agents SDK .on_invoke_tool, etc.).
+    for attr in ("func", "coroutine", "entrypoint", "fn", "function", "on_invoke_tool"):
+        inner = getattr(target, attr, None)
+        if callable(inner) and not is_wrapped(inner):
+            try:
+                setattr(target, attr, wrap_callable(inner, **opts))
+            except Exception:
+                pass  # immutable attr -> leave as-is (fail open)
+    return target

leancontext/integrations/frameworks.py

@@ -0,0 +1,58 @@
+"""Framework adapters: reduce a framework's tool outputs.
+
+Each framework wraps a tool differently, and several tool objects are themselves
+callable, so we wrap the underlying user function *in place* and return the same
+object (keeping its name, schema, and metadata).
+
+Covered:
+- LangChain  (``StructuredTool``/``Tool`` via ``.func`` / ``.coroutine``)
+- LangGraph  (uses LangChain tools, so the LangChain adapter applies)
+- Agno       (``Function`` via ``.entrypoint``)
+
+Plain functions don't need an adapter — ``leancontext.wrap`` / ``@reduce`` handle them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._common import is_wrapped
+from .decorator import wrap_callable
+
+
+def _module_root(obj: Any) -> str:
+    return type(obj).__module__.split(".")[0]
+
+
+def looks_like_langchain_tool(obj: Any) -> bool:
+    return _module_root(obj) in ("langchain", "langchain_core") and hasattr(obj, "func")
+
+
+def looks_like_agno_tool(obj: Any) -> bool:
+    return _module_root(obj) == "agno" and hasattr(obj, "entrypoint")
+
+
+def _wrap_attr_in_place(obj: Any, attr: str, opts: dict) -> None:
+    fn = getattr(obj, attr, None)
+    if callable(fn) and not is_wrapped(fn):
+        try:
+            setattr(obj, attr, wrap_callable(fn, **opts))
+        except Exception:
+            pass  # immutable/validated field -> leave as-is (fail open)
+
+
+def wrap_langchain(tool: Any, **opts) -> Any:
+    """Reduce outputs of a LangChain or LangGraph tool, in place."""
+    if isinstance(tool, (list, tuple)):
+        return type(tool)(wrap_langchain(t, **opts) for t in tool)
+    _wrap_attr_in_place(tool, "func", opts)
+    _wrap_attr_in_place(tool, "coroutine", opts)
+    return tool
+
+
+def wrap_agno(tool: Any, **opts) -> Any:
+    """Reduce outputs of an Agno tool (Function), in place."""
+    if isinstance(tool, (list, tuple)):
+        return type(tool)(wrap_agno(t, **opts) for t in tool)
+    _wrap_attr_in_place(tool, "entrypoint", opts)
+    return tool

leancontext/integrations/litellm.py

@@ -0,0 +1,80 @@
+"""LiteLLM integration — gateway/proxy and SDK.
+
+Verified against LiteLLM docs (docs.litellm.ai/docs/proxy/call_hooks):
+a proxy callback subclasses ``CustomLogger`` and implements
+``async_pre_call_hook(self, user_api_key_dict, cache, data, call_type)``,
+mutates ``data["messages"]``, and returns ``data``.
+
+Nothing here is imported by ``leancontext`` at package load — ``litellm`` stays an
+optional dependency. Import this module explicitly only when you use LiteLLM.
+
+Proxy usage (config.yaml)::
+
+    litellm_settings:
+      callbacks: leancontext.integrations.litellm.proxy_handler_instance
+
+SDK usage::
+
+    import leancontext.integrations.litellm as ll
+    ll.patch()                      # reduce messages on every litellm.completion call
+"""
+
+from __future__ import annotations
+
+import functools
+
+from ._common import mark, reduce_messages_in, wrap_messages_create
+
+_REDUCIBLE_CALLS = ("completion", "text_completion")
+
+
+def make_handler(**opts):
+    """Build a LiteLLM proxy callback that reduces tool outputs before each call."""
+    from litellm.integrations.custom_logger import CustomLogger  # optional dependency
+
+    class LeanContextHandler(CustomLogger):
+        async def async_pre_call_hook(self, user_api_key_dict, cache, data, call_type):
+            if call_type in _REDUCIBLE_CALLS:
+                reduce_messages_in(data, "auto", opts)  # fail-open in-place
+            return data
+
+    return LeanContextHandler()
+
+
+def patch(**opts) -> None:
+    """Monkeypatch ``litellm.completion``/``acompletion`` to reduce messages. Idempotent."""
+    import litellm
+
+    if getattr(litellm, "_leancontext_patched", False):
+        return
+
+    litellm.completion = wrap_messages_create(litellm.completion, fmt="auto", opts=opts)
+
+    if hasattr(litellm, "acompletion"):
+        _orig_acompletion = litellm.acompletion
+
+        @functools.wraps(_orig_acompletion)
+        async def acompletion(*args, **kwargs):
+            reduce_messages_in(kwargs, "auto", opts)
+            return await _orig_acompletion(*args, **kwargs)
+
+        litellm.acompletion = mark(acompletion)
+
+    litellm._leancontext_patched = True
+
+
+def unpatch() -> None:
+    import litellm
+
+    for name in ("completion", "acompletion"):
+        fn = getattr(litellm, name, None)
+        orig = getattr(fn, "__wrapped__", None)
+        if orig is not None:
+            setattr(litellm, name, orig)
+    litellm._leancontext_patched = False
+
+
+try:  # convenience instance for config.yaml; only built if litellm is installed
+    proxy_handler_instance = make_handler()
+except Exception:  # pragma: no cover - litellm not installed
+    proxy_handler_instance = None

leancontext/integrations/mcp_server.py

@@ -0,0 +1,64 @@
+"""MCP server: expose LeanContext as tools any MCP client can call.
+
+Three tools:
+- ``reduce``  : shrink a tool-output payload to its signal, return the text.
+- ``expand``  : fetch the original content behind a paging reference (lc://<id>).
+- ``stats``   : report what a reduction would save, without changing anything.
+
+The handlers below are plain functions (easy to test). ``mcp`` is imported lazily
+inside ``create_server`` so this module stays import-safe without the ``mcp`` extra.
+
+Run it::
+
+    pip install "leancontext[mcp]"
+    python -m leancontext.integrations.mcp_server      # serves over stdio
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import leancontext
+from leancontext import paging
+
+
+def reduce(text: str, kind: str = "auto") -> str:
+    """Reduce a tool-output payload (log, json, diff, stack trace, html, table)."""
+    return leancontext.reduce(text, kind=kind).text
+
+
+def expand(ref: str) -> str:
+    """Return the original content for a LeanContext reference like 'lc://a1b2c3d4'."""
+    original = paging.expand(ref)
+    return original if original is not None else f"No content found for ref {ref!r}."
+
+
+def stats(text: str, kind: str = "auto") -> dict[str, Any]:
+    """Report what reducing ``text`` would save, without changing it."""
+    r = leancontext.reduce(text, kind=kind)
+    return {
+        "kind": r.kind,
+        "tokens_before": r.tokens_before,
+        "tokens_after": r.tokens_after,
+        "ratio": round(r.ratio, 4),
+        "fidelity": round(r.fidelity, 4),
+    }
+
+
+def create_server(name: str = "leancontext"):
+    """Build an MCP server exposing the tools above. Requires the ``mcp`` extra."""
+    from mcp.server.fastmcp import FastMCP
+
+    server = FastMCP(name)
+    server.tool()(reduce)
+    server.tool()(expand)
+    server.tool()(stats)
+    return server
+
+
+def main() -> None:
+    create_server().run()
+
+
+if __name__ == "__main__":
+    main()

leancontext/integrations/otel.py

@@ -0,0 +1,78 @@
+"""OpenTelemetry integration — emit reduction savings as standard telemetry.
+
+Follows the OpenTelemetry GenAI semantic-conventions posture (converged industry
+standard as of early 2026): emit **metrics** for token usage/savings, and attach a
+**content-free span event** to the active span if one is recording. We never put
+payload content in attributes (that is the documented anti-pattern — size/PII).
+
+Import-safe: ``opentelemetry`` is imported lazily inside ``instrument`` only, so it
+stays an optional dependency (``pip install leancontext[otel]``).
+
+Usage::
+
+    import leancontext.integrations.otel as lc_otel
+    lc_otel.instrument()            # uses the global MeterProvider/TracerProvider
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..core import on_reduction, remove_reduction_hook
+
+_INSTALLED: dict[str, Any] = {}
+
+
+def instrument(meter_provider: Any = None) -> Any:
+    """Register a reduction hook that records OTel metrics + span events. Idempotent."""
+    if "hook" in _INSTALLED:
+        return _INSTALLED["hook"]
+
+    from opentelemetry import metrics, trace
+
+    meter = metrics.get_meter("leancontext", meter_provider=meter_provider)
+
+    m_before = meter.create_counter("leancontext.tokens.before", unit="token",
+                                    description="Input tokens before reduction")
+    m_after = meter.create_counter("leancontext.tokens.after", unit="token",
+                                   description="Input tokens after reduction")
+    m_saved = meter.create_counter("leancontext.tokens.saved", unit="token",
+                                   description="Input tokens saved by reduction")
+    m_count = meter.create_counter("leancontext.reductions", unit="1",
+                                   description="Number of applied reductions")
+    h_ratio = meter.create_histogram("leancontext.reduction.ratio", unit="1",
+                                     description="Fraction of tokens saved (0..1)")
+    h_fidelity = meter.create_histogram("leancontext.reduction.fidelity", unit="1",
+                                        description="Signal preserved (0..1)")
+
+    def _hook(r) -> None:
+        attrs = {"leancontext.kind": r.kind}
+        saved = r.tokens_saved
+        m_before.add(r.tokens_before, attrs)
+        m_after.add(r.tokens_after, attrs)
+        m_saved.add(saved, attrs)
+        m_count.add(1, attrs)
+        h_ratio.record(r.ratio, attrs)
+        h_fidelity.record(r.fidelity, attrs)
+
+        span = trace.get_current_span()
+        if span is not None and span.is_recording():
+            # Metadata only — never the payload (GenAI semconv: no content in attributes).
+            span.add_event("leancontext.reduction", {
+                "leancontext.kind": r.kind,
+                "gen_ai.usage.input_tokens.before": r.tokens_before,
+                "gen_ai.usage.input_tokens.after": r.tokens_after,
+                "leancontext.tokens.saved": saved,
+                "leancontext.reduction.ratio": r.ratio,
+                "leancontext.reduction.fidelity": r.fidelity,
+            })
+
+    on_reduction(_hook)
+    _INSTALLED["hook"] = _hook
+    return _hook
+
+
+def uninstrument() -> None:
+    hook = _INSTALLED.pop("hook", None)
+    if hook is not None:
+        remove_reduction_hook(hook)

leancontext/integrations/proxy.py

@@ -0,0 +1,90 @@
+"""Standalone OpenAI-compatible reducing proxy (FastAPI/ASGI).
+
+Point any client's ``base_url`` at this proxy and tool outputs in ``messages`` are
+reduced before being forwarded upstream. Any language, any framework, no code change.
+
+It forwards the caller's auth headers, supports streaming responses, and turns
+upstream failures into a clean 502 instead of crashing. FastAPI is imported lazily
+inside ``create_app`` so this module stays import-safe without the proxy extra.
+
+    from leancontext.integrations.proxy import create_app
+    app = create_app()                      # forwards to $LEANCONTEXT_UPSTREAM
+    # uvicorn leancontext.integrations.proxy:app   (after `app = create_app()`)
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+from collections.abc import Callable
+from typing import Any
+
+from ._common import reduce_messages_in
+
+# Headers we pass through to the upstream provider (auth + provider version flags).
+_FORWARD = ("authorization", "api-key", "x-api-key", "anthropic-version", "anthropic-beta")
+
+
+def _forward_headers(request: Any) -> dict:
+    """Carry the caller's auth/version headers upstream; fall back to OPENAI_API_KEY."""
+    headers: dict[str, str] = {"content-type": "application/json"}
+    if request is not None:
+        for name in _FORWARD:
+            value = request.headers.get(name)
+            if value:
+                headers[name] = value
+    if not any(k.lower() == "authorization" for k in headers):
+        key = os.environ.get("OPENAI_API_KEY")
+        if key:
+            headers["Authorization"] = f"Bearer {key}"
+    return headers
+
+
+def create_app(forwarder: Callable[[dict, dict], Any] | None = None,
+               upstream: str | None = None):
+    """Build the FastAPI app. Pass a custom ``forwarder(payload, headers)`` for tests."""
+    from fastapi import Body, FastAPI, Request
+    from fastapi.responses import JSONResponse, StreamingResponse
+
+    # Make the string annotation `Request` resolvable under `from __future__ import annotations`.
+    globals()["Request"] = Request
+
+    app = FastAPI(title="LeanContext proxy")
+    url = (upstream or os.environ.get("LEANCONTEXT_UPSTREAM", "https://api.openai.com")).rstrip("/")
+    url += "/v1/chat/completions"
+
+    def _httpx_forward(payload: dict, headers: dict) -> Any:
+        import httpx
+
+        if payload.get("stream"):
+            def body():
+                with httpx.stream("POST", url, json=payload, headers=headers, timeout=120) as resp:
+                    yield from resp.iter_raw()
+            return StreamingResponse(body(), media_type="text/event-stream")
+
+        with httpx.Client(timeout=120) as client:
+            resp = client.post(url, json=payload, headers=headers)
+            return JSONResponse(resp.json(), status_code=resp.status_code)
+
+    forward = forwarder or _httpx_forward
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"ok": True}
+
+    @app.post("/v1/chat/completions")
+    async def chat_completions(request: Request, payload: dict = Body(...)):
+        reduce_messages_in(payload, "openai", {})  # fail-open, in-place
+        try:
+            result = forward(payload, _forward_headers(request))
+            if inspect.isawaitable(result):
+                result = await result
+        except Exception as exc:
+            return JSONResponse(
+                {"error": {"message": str(exc), "type": "upstream_error"}}, status_code=502
+            )
+        if isinstance(result, (JSONResponse, StreamingResponse)):
+            return result
+        return JSONResponse(result)
+
+    return app