leancontext 2.0.0__py3-none-any.whl

leancontext/__init__.py

@@ -0,0 +1,104 @@
+"""LeanContext — keep agent context lean (drop redundant boilerplate, keep the signal).
+
+Deterministic, type-aware reduction of agent tool outputs *at the source*.
+Cut LLM token cost without making the agent do less.
+
+Quick start::
+
+    from leancontext import reduce
+
+    # 1) manual
+    payload = reduce(tool_output).text
+
+    # 2) decorator (one line per tool)
+    @reduce
+    def search_logs(q: str) -> str:
+        ...
+
+    # 3) bulk wrap (one line for all tools, any framework)
+    tools = reduce(tools)            # or leancontext.wrap(tools)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .core import (
+    CONFIG,
+    Reduction,
+    clear_cache,
+    clear_reduction_hooks,
+    detect_kind,
+    disable,
+    enable,
+    is_disabled,
+    on_reduction,
+    reduce_text,
+    remove_reduction_hook,
+)
+from .cost import CostTracker, estimate_savings, set_price
+from .integrations import (
+    wrap,
+    wrap_agno,
+    wrap_anthropic,
+    wrap_callable,
+    wrap_gemini,
+    wrap_langchain,
+    wrap_openai,
+)
+from .messages import detect_format, reduce_messages
+from .tokens import active_tokenizer, count_tokens, set_token_counter, use_tiktoken
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "reduce",
+    "reduce_text",
+    "reduce_messages",
+    "detect_format",
+    "Reduction",
+    "wrap",
+    "wrap_callable",
+    "wrap_openai",
+    "wrap_anthropic",
+    "wrap_gemini",
+    "wrap_agno",
+    "wrap_langchain",
+    "detect_kind",
+    "disable",
+    "enable",
+    "is_disabled",
+    "on_reduction",
+    "remove_reduction_hook",
+    "clear_reduction_hooks",
+    "clear_cache",
+    "count_tokens",
+    "set_token_counter",
+    "use_tiktoken",
+    "active_tokenizer",
+    "estimate_savings",
+    "CostTracker",
+    "set_price",
+    "CONFIG",
+    "__version__",
+]
+
+
+def reduce(content: Any = None, /, **opts) -> Any:
+    """Polymorphic entry point.
+
+    - ``reduce(text)`` -> :class:`Reduction`
+    - ``reduce(callable)`` -> wrapped tool (decorator form: ``@reduce``)
+    - ``reduce(list_of_tools)`` / ``reduce(tool_obj)`` -> wrapped tools
+    - ``reduce(**opts)`` -> a decorator/partial carrying those options
+    """
+    if content is None:
+        def deferred(target: Any) -> Any:
+            return reduce(target, **opts)
+        return deferred
+
+    if isinstance(content, str):
+        return reduce_text(content, **opts)
+
+    # callable, tool, list of tools, or SDK client -> best-effort wrap (fail open)
+    return wrap(content, **opts)

leancontext/cli.py

@@ -0,0 +1,36 @@
+"""`leancontext reduce <file>` — see the saving on any payload from the terminal."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import reduce_text
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="leancontext", description="Reduce a tool-output payload.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("reduce", help="reduce a file (or stdin) and report the saving")
+    p.add_argument("file", nargs="?", help="path to read; omit to read stdin")
+    p.add_argument("--kind", default="auto", help="force a content kind (default: auto)")
+    p.add_argument("--show", action="store_true", help="print the reduced payload")
+
+    args = parser.parse_args(argv)
+    text = sys.stdin.read() if not args.file else open(args.file, encoding="utf-8").read()
+
+    r = reduce_text(text, kind=args.kind)
+    print(f"kind        : {r.kind}", file=sys.stderr)
+    print(f"tokens      : {r.tokens_before} -> {r.tokens_after}", file=sys.stderr)
+    print(f"saved       : {r.ratio:.0%}", file=sys.stderr)
+    print(f"fidelity    : {r.fidelity:.0%}", file=sys.stderr)
+    for note in r.notes:
+        print(f"note        : {note}", file=sys.stderr)
+    if args.show:
+        print(r.text)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

leancontext/core.py

@@ -0,0 +1,214 @@
+"""Dispatch, type detection, the Reduction result, and the fail-open guard.
+
+LeanContext never breaks the caller. If the content type is unknown, a reducer
+raises, or the saving or fidelity falls below the configured threshold, we return
+the original text unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from .fidelity import fidelity_score
+from .reducers import REGISTRY
+from .tokens import content_ref, count_tokens
+
+# --- configuration -----------------------------------------------------------
+
+
+@dataclass
+class _Config:
+    min_saving: float = 0.10      # require at least this fractional saving to apply
+    min_fidelity: float = 0.85    # require at least this signal preservation to apply
+    min_tokens: int = 50          # below this, not worth touching
+    max_input_chars: int = 0      # if >0, payloads larger than this pass through untouched
+    disabled: bool = False
+    cache_size: int = 2048        # max cached reductions; 0 disables the cache
+    hooks: list = field(default_factory=list)
+
+
+CONFIG = _Config()
+
+# A tool output is re-sent on every turn, so we reduce each unique payload once and
+# reuse the result. Keyed by content hash + options; deterministic, so this is safe.
+_CACHE: OrderedDict[tuple, Reduction] = OrderedDict()
+
+
+def clear_cache() -> None:
+    """Drop all cached reductions."""
+    _CACHE.clear()
+
+
+def disable() -> None:
+    CONFIG.disabled = True
+
+
+def enable() -> None:
+    CONFIG.disabled = False
+
+
+def is_disabled() -> bool:
+    return CONFIG.disabled or os.environ.get("LEANCONTEXT_DISABLED", "") == "1"
+
+
+def on_reduction(callback: Callable[[Reduction], None]) -> Callable[[Reduction], None]:
+    """Register a telemetry hook called after each *applied* reduction.
+
+    Composable: multiple hooks may be registered. Returns the callback so it can
+    later be passed to :func:`remove_reduction_hook`.
+    """
+    CONFIG.hooks.append(callback)
+    return callback
+
+
+def remove_reduction_hook(callback: Callable[[Reduction], None]) -> None:
+    try:
+        CONFIG.hooks.remove(callback)
+    except ValueError:
+        pass
+
+
+def clear_reduction_hooks() -> None:
+    CONFIG.hooks.clear()
+
+
+def _emit(reduction: Reduction) -> None:
+    for callback in list(CONFIG.hooks):
+        try:
+            callback(reduction)
+        except Exception:
+            pass  # telemetry must never break the agent
+
+
+# --- result ------------------------------------------------------------------
+
+
+@dataclass
+class Reduction:
+    text: str            # the string to send to the model
+    kind: str            # detected/used content kind ("log", "json", "passthrough", ...)
+    tokens_before: int
+    tokens_after: int
+    fidelity: float      # 0..1 signal preserved
+    ref: str             # content hash of the ORIGINAL (handle for paging/restore)
+    original: str
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def ratio(self) -> float:
+        if self.tokens_before == 0:
+            return 0.0
+        return 1.0 - self.tokens_after / self.tokens_before
+
+    @property
+    def tokens_saved(self) -> int:
+        return max(0, self.tokens_before - self.tokens_after)
+
+    @property
+    def applied(self) -> bool:
+        return self.kind != "passthrough"
+
+    def __str__(self) -> str:  # so `str(reduction)` / f-strings give the payload
+        return self.text
+
+
+# --- detection & dispatch ----------------------------------------------------
+
+REDUCERS: dict[str, Callable[[str], tuple[str, list[str]]]] = {r.kind: r.reduce for r in REGISTRY}
+
+
+def detect_kind(text: str) -> str:
+    """Return the kind of ``text`` by asking each reducer's detector, in priority order."""
+    for reducer in REGISTRY:
+        if reducer.detect(text):
+            return reducer.kind
+    return "text"
+
+
+def _to_text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, (dict, list)):
+        return json.dumps(content, ensure_ascii=False)
+    return str(content)
+
+
+def _passthrough(original: str, before: int, ref: str, notes: list[str]) -> Reduction:
+    return Reduction(original, "passthrough", before, before, 1.0, ref, original, notes)
+
+
+def reduce_text(
+    content: object,
+    *,
+    kind: str = "auto",
+    min_saving: float | None = None,
+    min_fidelity: float | None = None,
+) -> Reduction:
+    """Reduce a single piece of content. Always safe: worst case is a no-op.
+
+    Deterministic results are cached by content hash, so a tool output that is
+    re-sent across turns is computed only once. Telemetry still fires on every
+    call (cache hit or miss), so per-turn savings are recorded as before.
+    """
+    min_saving = CONFIG.min_saving if min_saving is None else min_saving
+    min_fidelity = CONFIG.min_fidelity if min_fidelity is None else min_fidelity
+
+    original = _to_text(content)
+    before = count_tokens(original)
+    ref = content_ref(original)
+
+    if is_disabled():  # global toggle; never cached so re-enabling takes effect at once
+        return _passthrough(original, before, ref, ["disabled"])
+
+    key = (ref, kind, min_saving, min_fidelity, CONFIG.min_tokens, CONFIG.max_input_chars)
+    use_cache = CONFIG.cache_size > 0
+
+    if use_cache and key in _CACHE:
+        result = _CACHE[key]
+        _CACHE.move_to_end(key)
+    else:
+        result = _compute(original, before, ref, kind, min_saving, min_fidelity)
+        if use_cache:
+            _CACHE[key] = result
+            if len(_CACHE) > CONFIG.cache_size:
+                _CACHE.popitem(last=False)  # evict least-recently-used
+
+    if result.applied:
+        _emit(result)
+    return result
+
+
+def _compute(original: str, before: int, ref: str, kind: str,
+             min_saving: float, min_fidelity: float) -> Reduction:
+    """Run detection + the typed reducer. Fail-open: any problem returns the original."""
+    def passthrough(notes: list[str]) -> Reduction:
+        return _passthrough(original, before, ref, notes)
+
+    if CONFIG.max_input_chars and len(original) > CONFIG.max_input_chars:
+        return passthrough(["above max_input_chars"])
+    if before < CONFIG.min_tokens:
+        return passthrough(["below min_tokens"])
+
+    detected = detect_kind(original) if kind == "auto" else kind
+    reducer = REDUCERS.get(detected)
+    if reducer is None:
+        return passthrough([f"no reducer for kind={detected!r}"])
+
+    try:
+        text, notes = reducer(original)
+    except Exception as exc:  # fail open on any reducer bug
+        return passthrough([f"reducer error: {exc!r}"])
+
+    after = count_tokens(text)
+    saving = 0.0 if before == 0 else 1.0 - after / before
+    fid = fidelity_score(original, text, detected)
+
+    if saving < min_saving or fid < min_fidelity:
+        notes.append(f"reverted: saving={saving:.0%}, fidelity={fid:.0%} (below threshold)")
+        return passthrough(notes)
+
+    return Reduction(text, detected, before, after, fid, ref, original, notes)

leancontext/cost.py

@@ -0,0 +1,104 @@
+"""Cost accounting: turn token savings into dollars.
+
+Reports two things:
+1. Dollars saved, from the input-token price (input dominates agent cost).
+2. ``cache_safe = True``: reductions are deterministic and content-addressed, so a
+   reduced block serialises to the same bytes every turn and the provider's
+   prompt-cache prefix stays intact.
+
+Prices change often, so the built-in table is small and overridable: pass an
+explicit ``input_price_per_mtok`` or register prices with :func:`set_price`. With
+no known price, token savings are still reported and ``usd_saved`` is ``None``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+#: USD per 1M tokens (input, output). Indicative — override via set_price().
+PRICING: dict[str, tuple[float, float | None]] = {
+    "claude-sonnet-4-6": (3.0, 15.0),  # verified 2026-06; others: register your own
+}
+
+
+def set_price(model: str, input_per_mtok: float, output_per_mtok: float | None = None) -> None:
+    PRICING[model] = (input_per_mtok, output_per_mtok)
+
+
+def _input_price(model: str | None, override: float | None) -> float | None:
+    if override is not None:
+        return override
+    if model:
+        if model in PRICING:
+            return PRICING[model][0]
+        for key, (inp, _out) in PRICING.items():
+            if model.startswith(key):
+                return inp
+    return None
+
+
+def estimate_savings(reduction, model: str | None = None,
+                     input_price_per_mtok: float | None = None) -> dict:
+    """Estimate token + USD savings for a single reduction."""
+    saved = reduction.tokens_saved
+    price = _input_price(model, input_price_per_mtok)
+    usd = None if price is None else round(saved / 1_000_000 * price, 6)
+    return {
+        "kind": reduction.kind,
+        "tokens_before": reduction.tokens_before,
+        "tokens_after": reduction.tokens_after,
+        "tokens_saved": saved,
+        "usd_saved": usd,
+        "cache_safe": True,  # deterministic + content-addressed → prefix preserved
+    }
+
+
+class CostTracker:
+    """Accumulate savings across many reductions. Install as a reduction hook.
+
+        tracker = CostTracker(model="claude-sonnet-4-6").install()
+        ... run your agent ...
+        print(tracker.report())
+    """
+
+    def __init__(self, model: str | None = None, input_price_per_mtok: float | None = None):
+        self.model = model
+        self.price = input_price_per_mtok
+        self.reductions = 0
+        self.tokens_before = 0
+        self.tokens_after = 0
+        self.tokens_saved = 0
+        self.usd_saved = 0.0
+        self.has_price = _input_price(model, input_price_per_mtok) is not None
+        self._hook: Callable | None = None
+
+    def _on(self, r) -> None:
+        self.reductions += 1
+        self.tokens_before += r.tokens_before
+        self.tokens_after += r.tokens_after
+        self.tokens_saved += r.tokens_saved
+        if self.has_price:
+            self.usd_saved += estimate_savings(r, self.model, self.price)["usd_saved"]
+
+    def install(self) -> CostTracker:
+        from .core import on_reduction
+        self._hook = on_reduction(self._on)
+        return self
+
+    def uninstall(self) -> None:
+        from .core import remove_reduction_hook
+        if self._hook is not None:
+            remove_reduction_hook(self._hook)
+            self._hook = None
+
+    def report(self) -> dict:
+        ratio = 0.0 if self.tokens_before == 0 else 1.0 - self.tokens_after / self.tokens_before
+        return {
+            "reductions": self.reductions,
+            "tokens_before": self.tokens_before,
+            "tokens_after": self.tokens_after,
+            "tokens_saved": self.tokens_saved,
+            "ratio": round(ratio, 4),
+            "usd_saved": round(self.usd_saved, 4) if self.has_price else None,
+            "cache_safe": True,
+        }

leancontext/fidelity.py

@@ -0,0 +1,108 @@
+"""Fidelity scoring: did the signal survive the reduction?
+
+The score is per content type. For logs and text we check that error/anomaly
+lines and the values on them are kept. For JSON, diff, and stack traces we check
+the type-specific invariants that make those reductions safe (all values, all
+change lines, the exception). If the score falls below the threshold, the core
+reverts to the original.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_SEVERITY = re.compile(r"(?i)\b(error|fatal|critical|exception|panic|traceback|warn|warning)\b")
+_UUID = re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b")
+_HEX = re.compile(r"0x[0-9a-fA-F]+")
+_PATH = re.compile(r"(?:/[\w.\-]+){2,}")
+_NUM = re.compile(r"\d+(?:\.\d+)?")
+_QUOTE = re.compile(r'"[^"]*"')
+
+_VALUE_PATTERNS = (_UUID, _HEX, _PATH, _NUM, _QUOTE)
+
+
+def _norm(line: str) -> str:
+    return " ".join(line.split())
+
+
+def salient_items(text: str) -> set[str]:
+    """The must-not-lose items in logs/text: error lines and the values on them."""
+    items: set[str] = set()
+    for line in text.splitlines():
+        if _SEVERITY.search(line):
+            items.add(_norm(line))
+            for rx in _VALUE_PATTERNS:
+                items.update(rx.findall(line))
+    return items
+
+
+def _signal_score(original: str, reduced: str) -> float:
+    """Fraction of the original's salient items still present (logs/text/html)."""
+    items = salient_items(original)
+    if not items:
+        return 1.0
+    reduced_lines = {_norm(line) for line in reduced.splitlines()}
+    kept = sum(1 for item in items if item in reduced_lines or item in reduced)
+    return kept / len(items)
+
+
+def _iter_scalars(data: Any):
+    if isinstance(data, dict):
+        for value in data.values():
+            yield from _iter_scalars(value)
+    elif isinstance(data, list):
+        for item in data:
+            yield from _iter_scalars(item)
+    elif isinstance(data, (str, int, float)) and not isinstance(data, bool):
+        yield data
+
+
+def _json_fidelity(original: str, reduced: str) -> float:
+    """Fraction of JSON scalar values (strings and numbers) preserved in the output."""
+    try:
+        data = json.loads(original)
+    except Exception:
+        return 1.0
+    values = [str(v) for v in _iter_scalars(data) if str(v)]
+    if not values:
+        return 1.0
+    kept = sum(1 for v in values if v in reduced)
+    return kept / len(values)
+
+
+def _diff_fidelity(original: str, reduced: str) -> float:
+    """Fraction of changed (+/-) lines preserved verbatim."""
+    changes = [
+        ln for ln in original.splitlines()
+        if ln[:1] in "+-" and not ln.startswith(("+++", "---"))
+    ]
+    if not changes:
+        return 1.0
+    reduced_lines = set(reduced.splitlines())
+    kept = sum(1 for ln in changes if ln in reduced_lines)
+    return kept / len(changes)
+
+
+def _stacktrace_fidelity(original: str, reduced: str) -> float:
+    """The exception line (the last non-empty line) must be preserved."""
+    lines = [ln for ln in original.splitlines() if ln.strip()]
+    if not lines:
+        return 1.0
+    return 1.0 if lines[-1] in reduced else 0.0
+
+
+_TYPED = {
+    "json": _json_fidelity,
+    "diff": _diff_fidelity,
+    "stacktrace": _stacktrace_fidelity,
+}
+
+
+def fidelity_score(original: str, reduced: str, kind: str = "text") -> float:
+    """Score how well the reduction preserved the signal, using a per-type check."""
+    scorer = _TYPED.get(kind)
+    if scorer is not None:
+        return scorer(original, reduced)
+    return _signal_score(original, reduced)

leancontext/integrations/__init__.py

@@ -0,0 +1,8 @@
+from .clients import wrap_anthropic, wrap_gemini, wrap_openai
+from .decorator import wrap, wrap_callable
+from .frameworks import wrap_agno, wrap_langchain
+
+__all__ = [
+    "wrap", "wrap_callable", "wrap_openai", "wrap_anthropic", "wrap_gemini",
+    "wrap_agno", "wrap_langchain",
+]

leancontext/integrations/_common.py

@@ -0,0 +1,62 @@
+"""Shared plumbing for integration wrappers.
+
+One place for the fail-open "wrap a ``create(**kwargs)`` callable, reduce its
+``messages``, and mark it so we don't double-wrap" pattern, reused by the OpenAI/
+Anthropic client wrappers, the Anthropic-native wrapper, and LiteLLM.
+"""
+
+from __future__ import annotations
+
+import functools
+from collections.abc import Callable
+from typing import Any
+
+from ..messages import reduce_messages
+
+_MARKER = "__leancontext_wrapped__"
+
+
+def is_wrapped(fn: Any) -> bool:
+    return getattr(fn, _MARKER, False)
+
+
+def mark(fn: Callable) -> Callable:
+    setattr(fn, _MARKER, True)
+    return fn
+
+
+def reduce_messages_in(mapping: Any, fmt: str, opts: dict, key: str = "messages") -> None:
+    """Fail-open, in-place reduction of ``mapping[key]`` (dict-like).
+
+    ``key`` is ``messages`` for OpenAI/Anthropic, ``contents`` for Gemini.
+    """
+    if isinstance(mapping, dict) and isinstance(mapping.get(key), list):
+        try:
+            mapping[key] = reduce_messages(mapping[key], fmt=fmt, **opts)
+        except Exception:
+            pass  # fail open
+
+
+def wrap_messages_create(create: Callable, *, fmt: str, opts: dict, key: str = "messages",
+                         reduce: bool = True,
+                         before: Callable[[dict], None] | None = None) -> Callable:
+    """Wrap a ``create(**kwargs)`` callable to reduce its messages before calling through.
+
+    ``before`` runs after reduction (e.g. to inject provider params/headers).
+    Idempotent: an already-wrapped callable is returned unchanged.
+    """
+    if is_wrapped(create):
+        return create
+
+    @functools.wraps(create)
+    def wrapper(*args, **kwargs):
+        if reduce:
+            reduce_messages_in(kwargs, fmt, opts, key=key)
+        if before is not None:
+            try:
+                before(kwargs)
+            except Exception:
+                pass  # fail open
+        return create(*args, **kwargs)
+
+    return mark(wrapper)