proxytool 0.4.0__py3-none-any.whl

proxytool/conduit.py

@@ -0,0 +1,88 @@
+"""httpx conduit to the upstream (llama-server / mlx_lm.server / llama-swap)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+# hop-by-hop/noise headers never forwarded upstream.
+_DROP_HEADERS = {"host", "content-length", "accept-encoding", "connection"}
+
+
+def upstream_path(base_url: str, path: str) -> str:
+    """Canonical app path → path relative to the configured upstream base.
+
+    Base URLs may be bare server roots (`http://host:8080`) or OpenAI-rooted
+    (`http://host:8080/v1`, as llama-swap documents them). With an OpenAI
+    root the canonical `/v1/...` prefix is stripped, so a base of neither
+    spelling can ever produce a doubled `/v1/v1/chat/completions` upstream.
+    """
+    p = path.lstrip("/")
+    b = base_url.rstrip("/")
+    if b.endswith("/v1") and (p == "v1" or p.startswith("v1/")):
+        p = p[len("v1/"):]
+    return p
+
+
+def upstream_url(base_url: str, path: str) -> str:
+    """Absolute form of `upstream_path` — for urllib probes outside httpx."""
+    return f"{base_url.rstrip('/')}/{upstream_path(base_url, path)}"
+
+
+class UpstreamConduit:
+    def __init__(self, base_url: str,
+                 timeout: float = 300.0,
+                 api_key: str = "") -> None:
+        self._base_url = base_url
+        # SSE generations are long-lived: a single generous timeout applies to
+        # the whole request (llama-swap cold-start model loads included).
+        self._timeout = httpx.Timeout(timeout)
+        self._api_key = api_key
+
+    def client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(base_url=self._base_url, timeout=self._timeout)
+
+    def _auth_headers(self) -> dict[str, str]:
+        if self._api_key:
+            return {"Authorization": f"Bearer {self._api_key}"}
+        return {}
+
+    @staticmethod
+    def forwardable(headers: dict[str, str]) -> dict[str, str]:
+        """Client headers worth forwarding (auth, routing, trace ids)."""
+        return {
+            k: v for k, v in headers.items()
+            if k.lower() not in _DROP_HEADERS and v
+        }
+
+    async def forward_json(self, path: str, payload: dict[str, Any],
+                           headers: dict[str, str] | None = None
+                           ) -> httpx.Response:
+        async with self.client() as client:
+            return await client.post(
+                upstream_path(self._base_url, path),
+                json=payload,
+                headers={**self._auth_headers(), **self.forwardable(headers or {})},
+            )
+
+    async def forward_stream(
+        self, path: str, payload: dict[str, Any],
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        client = self.client()
+        request = client.build_request(
+            "POST",
+            upstream_path(self._base_url, path),
+            json=payload,
+            headers={**self._auth_headers(), **self.forwardable(headers or {})},
+        )
+        return await client.send(request, stream=True)
+
+    async def passthrough(self, method: str, path: str,
+                          headers: dict[str, str],
+                          content: bytes) -> httpx.Response:
+        async with self.client() as client:
+            merged = {**self._auth_headers(), **self.forwardable(headers)}
+            return await client.request(
+                method, upstream_path(self._base_url, path), headers=merged, content=content)

proxytool/config.py

@@ -0,0 +1,496 @@
+"""TOML config file support for the ``proxytool`` CLI.
+
+Precedence for every setting:
+
+    CLI flag  >  environment (PTP_*)  >  config file  >  default
+
+Config discovery: ``--config PATH``, then ``PTP_CONFIG``, then
+``./proxytool.toml``, ``./.proxytool.toml``, and finally
+``$XDG_CONFIG_HOME/proxytool/config.toml`` (default ``~/.config/...``).
+
+The config file is a *bridge*, not a parallel system: recognized values are
+exported as the same ``PTP_*`` env vars the rest of the stack already reads
+(``settings``, routing, the daemonized child), but only when neither a CLI
+flag nor the environment already expressed them. That makes the CLI stay tiny
+(``proxytool start`` finds the file and goes) while flags/env keep winning.
+
+Schema (all keys optional)::
+
+    host = "127.0.0.1"
+    port = 8180
+    log_level = "info"            # debug | info | warning | error
+    default_backend = "mlx"       # fallback route name for multi-routing
+
+    [upstream]                    # single-backend setup (llama-swap etc.)
+    url = "http://127.0.0.1:8080"
+    timeout = 600
+    api_key = "sk-..."
+
+    [routing.gguf]                # multi-backend routing table
+    url = "http://127.0.0.1:8181"
+    models = ["qwen-gguf", "qwen"]
+    default = true
+
+    [model_map]
+    "qwen-gguf" = "qwen2.5-coder-14b-instruct"
+
+    [loopguard]
+    nudge = 3
+    abort = 6
+
+    [trace]
+    enabled = false
+    file = "/tmp/proxytool-trace.log"
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from difflib import get_close_matches
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import AnyHttpUrl, BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+from proxytool.routing import RESERVED_ROUTE_SUFFIXES
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # Python 3.10 — tomli is the stdlib tomllib backport
+    import tomli as tomllib
+
+CWD_NAMES = ("proxytool.toml", ".proxytool.toml")
+
+
+def find_config(explicit: str | None = None) -> Path | None:
+    """Resolve the active config file path, or None when none exists."""
+    if explicit:
+        p = Path(explicit).expanduser()
+        if not p.is_file():
+            raise ValueError(f"config file not found: {explicit}")
+        return p
+    env = os.environ.get("PTP_CONFIG")
+    if env:
+        p = Path(env).expanduser()
+        if not p.is_file():
+            raise ValueError(f"PTP_CONFIG points to a missing file: {env}")
+        return p
+    xdg = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    cwd = Path.cwd()
+    for cand in (cwd / CWD_NAMES[0], cwd / CWD_NAMES[1],
+                 Path(xdg) / "proxytool" / "config.toml"):
+        if cand.is_file():
+            return cand
+    return None
+
+
+def load_config(path: Path | None) -> dict[str, Any]:
+    """Parse the TOML config into a dict; {} when path is None."""
+    if path is None:
+        return {}
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except OSError as e:
+        raise ValueError(f"cannot read config {path}: {e}") from e
+    except tomllib.TOMLDecodeError as e:
+        raise ValueError(f"invalid TOML in {path}: {e}") from e
+    if not isinstance(data, dict):
+        raise ValueError(f"config {path}: top level must be a table")
+    validate_config(data, label=str(path))
+    return data
+
+
+# ── strict schema validation ─────────────────────────────────────────────────
+# The bridge below is permissive by design (config only FILLS unset env vars),
+# but the file itself is validated strictly here: unknown keys/sections and
+# wrong types fail fast at startup with a pointed message instead of surfacing
+# later as an indirect runtime symptom (a typo'd port, a bad URL …).
+
+
+class _CfgModel(BaseModel):
+    """Base: forbid unknown keys so typos become config errors, not no-ops."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class _Upstream(_CfgModel):
+    url: AnyHttpUrl | None = None
+    timeout: float | None = Field(default=None, gt=0)
+    api_key: str | None = None
+    model_map_file: str | None = None
+
+
+class _Routing(_CfgModel):
+    # url presence is enforced with a friendlier message in validate_config.
+    url: AnyHttpUrl | None = None
+    models: list[str] | str | None = None
+    default: bool = False
+
+
+def _int_not_bool(v: Any) -> Any:
+    """Lax int coercion would happily turn TOML ``port = true`` into 1."""
+    if isinstance(v, bool):
+        raise ValueError("expected an integer, not a boolean")
+    return v
+
+
+class _Loopguard(_CfgModel):
+    nudge: int | None = Field(default=None, ge=0)
+    abort: int | None = Field(default=None, ge=0)
+
+
+class _Trace(_CfgModel):
+    enabled: bool = False
+    file: str | None = None
+
+
+class _Config(_CfgModel):
+    host: str | None = None
+    port: int | None = Field(default=None, ge=1, le=65535)
+    log_level: Literal["debug", "info", "warning", "error"] | None = None
+    default_backend: str | None = None
+    upstream: _Upstream | None = None
+    routing: dict[str, _Routing] | None = None
+    model_map: dict[str, str] | None = None
+    loopguard: _Loopguard | None = None
+    trace: _Trace | None = None
+
+    @field_validator("port", mode="before")
+    @classmethod
+    def _port_not_bool(cls, v: Any) -> Any:
+        return _int_not_bool(v)
+
+
+_TOP_KEYS = tuple(_Config.model_fields)
+_SECTION_FIELDS = {
+    "upstream": tuple(_Upstream.model_fields),
+    "routing": tuple(_Routing.model_fields),
+    "loopguard": tuple(_Loopguard.model_fields),
+    "trace": tuple(_Trace.model_fields),
+}
+
+
+def _did_you_mean(key: str, candidates: tuple[str, ...] | None) -> str:
+    if not candidates:
+        return ""
+    m = get_close_matches(key, list(candidates), n=1, cutoff=0.6)
+    return f" — did you mean '{m[0]}'?" if m else ""
+
+
+def _pydantic_error_lines(exc: ValidationError) -> list[str]:
+    """Turn pydantic errors into short, pointed config-error lines."""
+    lines: list[str] = []
+    for err in exc.errors(include_url=False):
+        loc = tuple(str(p) for p in err["loc"])
+        if err.get("type") == "extra_forbidden" and loc:
+            key = loc[-1]
+            if len(loc) == 1:
+                lines.append("unknown key '" + key + "' (top level)"
+                             + _did_you_mean(key, _TOP_KEYS))
+            else:
+                section = loc[0]
+                lines.append("unknown key '" + key + "' in [" + section + "]"
+                             + _did_you_mean(key, _SECTION_FIELDS.get(section)))
+            continue
+        msg = str(err.get("msg", "invalid value"))
+        prefix = "[" + ".".join(loc or ()) + "] " if loc else ""
+        lines.append(prefix + msg)
+    return lines
+
+
+def validate_config(data: dict[str, Any], label: str = "config") -> None:
+    """Raise ValueError with every problem found, or return silently."""
+    errors: list[str] = []
+
+    routing = data.get("routing")
+    if routing is not None:
+        if not isinstance(routing, dict):
+            errors.append("[routing] must be a table of [routing.<name>] entries")
+        else:
+            for name, t in routing.items():
+                if not isinstance(t, dict):
+                    errors.append(f"routing.{name} must be a table")
+                    continue
+                if not t.get("url"):
+                    errors.append(f"routing.{name} needs at least a url")
+                if str(name).upper() in RESERVED_ROUTE_SUFFIXES:
+                    errors.append(
+                        f"routing.{name}: reserved route name "
+                        f"({'/'.join(s.lower() for s in RESERVED_ROUTE_SUFFIXES)})")
+            defaults = [str(n) for n, t in routing.items()
+                        if isinstance(t, dict) and t.get("default")]
+            if len(defaults) > 1:
+                errors.append(
+                    "default = true on more than one routing entry: "
+                    + ", ".join(defaults))
+
+    try:
+        _Config.model_validate(data)
+    except ValidationError as exc:
+        errors.extend(_pydantic_error_lines(exc))
+
+    if errors:
+        raise ValueError(label + ":\n  - " + "\n  - ".join(errors))
+
+
+def _env_set(*names: str) -> bool:
+    return any(os.environ.get(n) for n in names)
+
+
+def _set_if_unset(env_key: str, value: str) -> bool:
+    """Set ``env_key`` unless it is already set."""
+    if _env_set(env_key) or not value:
+        return False
+    os.environ[env_key] = value
+    return True
+
+
+def _flag(attr: str, args: Any) -> Any:
+    return getattr(args, attr, None) if args is not None else None
+
+
+def _flag_unset(value: Any) -> bool:
+    return value is None or value is False
+
+
+def _env_backends_present() -> bool:
+    """True when the env already declares a *named* routed backend.
+
+    Settings-valued suffixes under the same namespace (``PTP_UPSTREAM_URL`` /
+    ``_DEFAULT`` / ``_API_KEY`` / ``_TIMEOUT``) are single-upstream settings,
+    not named backends.
+    """
+    for var in os.environ:
+        if not var.startswith("PTP_UPSTREAM_"):
+            continue
+        rest = var[len("PTP_UPSTREAM_"):]
+        if rest in RESERVED_ROUTE_SUFFIXES:
+            continue
+        return True
+    return False
+
+
+def _bridge_routing(cfg: dict[str, Any], args: Any, applied: list[str]) -> None:
+    """[routing.<name>] + default_backend → PTP_UPSTREAM_* env."""
+    flag_backends = list(getattr(args, "upstream", None) or [])
+    if flag_backends or _env_backends_present():
+        return
+    for name, table in (cfg.get("routing") or {}).items():
+        if not isinstance(table, dict) or not table.get("url"):
+            raise ValueError(f"routing.{name} needs at least a url")
+        upper = str(name).upper().replace("-", "_")
+        if _set_if_unset(f"PTP_UPSTREAM_{upper}", str(table["url"]).rstrip("/")):
+            applied.append(f"PTP_UPSTREAM_{upper}")
+        models = table.get("models") or []
+        if isinstance(models, str):
+            models = [m.strip() for m in models.split(",") if m.strip()]
+        if models:
+            joined = ",".join(str(m) for m in models)
+            if _set_if_unset(f"PTP_UPSTREAM_{upper}_MODELS", joined):
+                applied.append(f"PTP_UPSTREAM_{upper}_MODELS")
+    flag_default = _flag("default_backend", args)
+    if flag_default is None and not _env_set("PTP_DEFAULT_BACKEND"):
+        cfg_default = cfg.get("default_backend")
+        if cfg_default:
+            os.environ["PTP_DEFAULT_BACKEND"] = str(cfg_default)
+            applied.append("PTP_DEFAULT_BACKEND")
+        else:
+            # top-level default_backend unset → accept `default = true` on
+            # exactly one [routing.*] entry (the llama-swap-style spelling).
+            defaults = [str(n) for n, t in (cfg.get("routing") or {}).items()
+                        if isinstance(t, dict) and t.get("default")]
+            if len(defaults) > 1:
+                raise ValueError(
+                    "default = true on more than one routing entry: "
+                    + ", ".join(defaults))
+            if defaults:
+                os.environ["PTP_DEFAULT_BACKEND"] = defaults[0]
+                applied.append("PTP_DEFAULT_BACKEND")
+
+
+def _bridge_settings(cfg: dict[str, Any], args: Any, applied: list[str]) -> None:
+    """Top-level + [upstream] + [model_map] + [loopguard] + [trace] settings."""
+    if _flag_unset(_flag("host", args)) and "host" in cfg and _set_if_unset(
+            "PTP_HOST", str(cfg["host"])):
+        applied.append("PTP_HOST")
+    if _flag("port", args) is None and "port" in cfg and _set_if_unset(
+            "PTP_PORT", str(int(cfg["port"]))):
+        applied.append("PTP_PORT")
+    if _flag("log_level", args) is None and not _flag("quiet", args):
+        raw = str(cfg.get("log_level", "") or "")
+        if raw and _set_if_unset("PTP_LOG_LEVEL", raw):
+            applied.append("PTP_LOG_LEVEL")
+
+    up = cfg.get("upstream") or {}
+    if _flag_unset(_flag("upstream_url", args)) and up.get("url") and _set_if_unset(
+            "PTP_UPSTREAM_URL", str(up["url"]).rstrip("/")):
+        applied.append("PTP_UPSTREAM_URL")
+    for attr, key, envk in (
+        ("upstream_api_key", "api_key", "PTP_UPSTREAM_API_KEY"),
+        ("upstream_timeout", "timeout", "PTP_UPSTREAM_TIMEOUT"),
+    ):
+        if _flag_unset(_flag(attr, args)) and up.get(key) and _set_if_unset(
+                envk, str(up[key])):
+            applied.append(envk)
+
+    mm = None
+    if _flag_unset(_flag("model_map", args)) and _flag_unset(
+            _flag("model_map_file", args)):
+        table = cfg.get("model_map")
+        if isinstance(table, dict) and table:
+            mm = json.dumps({str(k): str(v) for k, v in table.items()})
+        elif up.get("model_map_file"):
+            mm = "@file:" + str(up["model_map_file"])
+    if mm and _set_if_unset("PTP_MODEL_MAP", mm):
+        applied.append("PTP_MODEL_MAP")
+
+    lg = cfg.get("loopguard") or {}
+    for attr, key, envk in (
+        ("loop_nudge", "nudge", "PTP_LOOP_NUDGE"),
+        ("loop_abort", "abort", "PTP_LOOP_ABORT"),
+    ):
+        if _flag(attr, args) is None and lg.get(key) is not None and _set_if_unset(
+                envk, str(int(lg[key]))):
+            applied.append(envk)
+
+    tr = cfg.get("trace") or {}
+    if not _flag("trace", args) and tr.get("enabled") and _set_if_unset(
+            "PTP_TRACE", "1"):
+        applied.append("PTP_TRACE")
+    if tr.get("file") and not _env_set("PTP_TRACE_FILE"):
+        os.environ["PTP_TRACE_FILE"] = str(tr["file"])
+        applied.append("PTP_TRACE_FILE")
+
+
+def apply_config(args: Any, *, serve: bool,
+                 routing: bool = False) -> tuple[Path | None, dict[str, Any],
+                                                 dict[str, Any]]:
+    """Bridge the resolved config into env.
+
+    Returns ``(path, cfg, info)`` where ``info`` carries ``applied``
+    (env keys set by the bridge).
+    """
+    path = find_config(getattr(args, "config", None) if args is not None else None)
+    cfg = load_config(path)
+    info: dict[str, Any] = {"applied": []}
+    if not cfg:
+        return path, cfg, info
+    applied: list[str] = info["applied"]
+    _bridge_settings(cfg, args, applied)
+    if routing:
+        _bridge_routing(cfg, args, applied)
+    return path, cfg, info
+
+
+def config_help_line() -> str:
+    """Short discovery summary for --help text."""
+    home = Path.home() / ".config" / "proxytool" / "config.toml"
+    return (f"TOML config file (PTP_CONFIG; default search: ./proxytool.toml, "
+            f"./.proxytool.toml, {home})")
+
+
+# ── diagnostics (`proxytool config print|check`) ────────────────────────────
+
+_SEARCH_DETAIL = {
+    "PTP_HOST": "host",
+    "PTP_PORT": "port",
+    "PTP_LOG_LEVEL": "log_level",
+    "PTP_UPSTREAM_URL": "upstream.url",
+    "PTP_UPSTREAM_API_KEY": "upstream.api_key",
+    "PTP_UPSTREAM_TIMEOUT": "upstream.timeout",
+    "PTP_MODEL_MAP": "model_map",
+    "PTP_LOOP_NUDGE": "loopguard.nudge",
+    "PTP_LOOP_ABORT": "loopguard.abort",
+    "PTP_TRACE": "trace.enabled",
+    "PTP_TRACE_FILE": "trace.file",
+}
+
+
+def _search_candidates(explicit: str | None) -> list[Path]:
+    """The paths find_config consults, in order (for diagnostic display)."""
+    if explicit:
+        return [Path(explicit).expanduser()]
+    env = os.environ.get("PTP_CONFIG")
+    if env:
+        return [Path(env).expanduser()]
+    xdg = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    cwd = Path.cwd()
+    return [cwd / name for name in CWD_NAMES] + [Path(xdg) / "proxytool" / "config.toml"]
+
+
+def _detail_for(key: str) -> str:
+    """Which config-file key would supply ``env key`` (for sourced rows)."""
+    if key in _SEARCH_DETAIL:
+        return _SEARCH_DETAIL[key]
+    m = re.fullmatch(r"PTP_UPSTREAM_([A-Z0-9_]+)_MODELS", key)
+    if m:
+        return f"routing.{m.group(1).lower()}.models"
+    m = re.fullmatch(r"PTP_UPSTREAM_([A-Z0-9_]+)", key)
+    if m:
+        return f"routing.{m.group(1).lower()}.url"
+    return ""
+
+
+def _relevant_env_keys(keys: Any) -> list[str]:
+    """Env vars the bridge could read or fill — diagnostic row candidates."""
+    out = []
+    for key in keys:
+        if key == "PTP_CONFIG":
+            continue  # it *selects* the file; shown in the discovery block
+        if key.startswith("PTP_"):
+            out.append(key)
+    return sorted(out)
+
+
+def describe_config(args: Any | None, *, routing: bool = True,
+                    serve: bool = True) -> dict[str, Any]:
+    """Dry-run the config bridge: resolve, validate, attribute — no env edits.
+
+    Returns a JSON-friendly dict with the discovered file, the candidates
+    consulted, validation errors when any, and one row per relevant env var
+    (PTP_*) with its value and where it would come from at serve/start time:
+    ``config file`` (bridged now) or ``env (pre-existing)`` (already set, so
+    the bridge would leave it). Flags are intentionally not shown —
+    precedence is CLI flag > env > config file > default, and this
+    subcommand takes no flags.
+    """
+    explicit = getattr(args, "config", None) if args is not None else None
+    candidates = [str(p) for p in _search_candidates(explicit)]
+    snapshot = dict(os.environ)
+    out: dict[str, Any] = {
+        "file": None, "searched": candidates, "valid": True, "errors": [],
+        "applied": [], "settings": [],
+        "precedence": "CLI flag > env var > config file > built-in default",
+    }
+    in_file = next((c for c in candidates if Path(c).is_file()), None)
+    try:
+        path = find_config(explicit)
+        if path is not None:
+            load_config(path)  # validates strictly (unknown keys, types, ...)
+        _path, _cfg, _info = apply_config(args, serve=serve, routing=routing)
+        changed = {k: v for k, v in os.environ.items() if snapshot.get(k) != v}
+    except ValueError as exc:
+        out["valid"] = False
+        out["errors"] = str(exc).splitlines()
+        out["file"] = in_file
+        return out
+    finally:
+        os.environ.clear()
+        os.environ.update(snapshot)
+
+    rows: list[dict[str, str]] = []
+    for key in sorted(set(changed) | set(_relevant_env_keys(snapshot.keys()))):
+        if key in changed:
+            src, value = "config file", changed[key]
+        else:
+            src, value = "env (pre-existing)", snapshot[key]
+        detail = _detail_for(key) if src == "config file" else ""
+        rows.append({"key": key, "value": value, "source": src, "detail": detail})
+    out["file"] = str(path) if path is not None else None
+    out["applied"] = sorted(changed)
+    out["settings"] = rows
+    return out

proxytool/loopguard.py

@@ -0,0 +1,92 @@
+"""LoopGuard: detect and break identical-prompt repetition loops.
+
+When a client re-prompts with a byte-identical message history (after
+sanitization), llama-server tends to replay the same continuation — a loop.
+The proxytool counters this in two steps:
+
+1. **nudge** after ``nudge_after`` identical consecutive requests: append a
+   short user message asking the model to finish the turn and stop.
+2. **abort** after ``abort_after``: stop forwarding upstream entirely and
+   return a clean, short OpenAI-style completion telling the user how to
+   break the loop (rephrase or start a new session). This bounds the loop
+   at ``abort_after`` requests instead of 100+.
+
+State is per-process and deliberately simple: a counter keyed by the request
+fingerprint, reset whenever a *different* request (a new user message or
+changed history) arrives. Long-identity loops are the only failure mode we
+guard against.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+NUDGE_TEXT = (
+    "[system-reminder] You have produced the same answer several times in a row. "
+    "That previous answer is already recorded. Do NOT repeat it. Either call a "
+    "tool you have not called yet, or give a short final answer that completes "
+    "the user's request, then stop."
+)
+
+ABORT_TEXT = (
+    "**LoopGuard: request aborted after {count} identical attempts.**\n\n"
+    "The model kept producing the same reply for the same prompt, so the "
+    "proxytool stopped forwarding to avoid burning tokens. To continue:\n"
+    "- Rephrase your message (even slightly), or\n"
+    "- Start a new session.\n\n"
+    "This is a safety cut-off, not a model answer."
+)
+
+
+@dataclass(frozen=True)
+class GuardDecision:
+    action: str  # "none" | "nudge" | "abort"
+    count: int
+
+
+class LoopGuard:
+    """Track consecutive identical requests per conversation fingerprint."""
+
+    def __init__(self, nudge_after: int = 3, abort_after: int = 6) -> None:
+        self.nudge_after = nudge_after
+        self.abort_after = abort_after
+        self._state: dict[str, int] = {}
+        self._last_key: str | None = None
+
+    # -- fingerprinting ----------------------------------------------------
+    @staticmethod
+    def request_key(payload: dict[str, Any]) -> str:
+        """Stable fingerprint of the *conversation* the model will see."""
+        return hashlib.sha256(
+            json.dumps(
+                {
+                    "messages": payload.get("messages"),
+                    "tools": payload.get("tools"),
+                },
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode()
+        ).hexdigest()
+
+    # -- decision flow ------------------------------------------------------
+    def check(self, key: str) -> GuardDecision:
+        """Record the incoming request and return the action to take."""
+        if key != self._last_key:
+            # A genuinely new request arrived: reset.
+            self._last_key = key
+            self._state = {key: 1}
+            return GuardDecision("none", 1)
+        count = self._state.get(key, 0) + 1
+        self._state[key] = count
+        if self.abort_after and count >= self.abort_after:
+            return GuardDecision("abort", count)
+        if self.nudge_after and count >= self.nudge_after:
+            return GuardDecision("nudge", count)
+        return GuardDecision("none", count)
+
+    def reset(self) -> None:
+        self._last_key = None
+        self._state.clear()