flowx-border 0.1.0__py3-none-any.whl

flowx_border/__init__.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+"""flowx-border: inspects the text crossing into and out of an LLM.
+
+The public API is two scan functions and a policy loader, and that is the whole of it.
+Everything else in this package is an implementation detail or an adapter. If a task
+appears to need a third public entry point, stop and ask, see CLAUDE.md.
+
+Both scan functions raise NotImplementedError until phase 1 of BUILD_PLAN.md.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from os import PathLike
+
+    from flowx_border.detectors.base import Context
+    from flowx_border.policy import Policy
+    from flowx_border.types import Decision
+
+__all__ = ["load_policy", "scan_input", "scan_output"]
+
+
+def load_policy(path: str | PathLike[str]) -> Policy:
+    """Load, validate and resolve a policy document, and compute its hash.
+
+    Raises PolicyError for anything wrong with the file, including an unknown detector
+    id. It never falls back to a default: scanning under a policy the caller did not
+    write is worse than refusing to start.
+    """
+    from flowx_border.policy import load_policy as _load
+
+    return _load(path)
+
+
+def _scan(text: str, side: str, policy: Policy, ctx: Context | None) -> Decision:
+    """The body both scan functions share.
+
+    `assert_satisfiable` runs first, and it is the reason this indirection
+        exists. With a detector missing, `run_scan` would return `allow` for text
+        nobody checked, and the caller would archive an evidence record for a scan
+        that enforced nothing. So a policy asking a missing detector to block or
+        redact raises here instead. Detectors asked only to flag or log are allowed
+        through, because there the gap shows up in the record rather than being
+        hidden by it.
+
+        Measured at 0.004 ms against the shipped default policy, against a 1 ms T0
+        budget: cheap enough to run per scan rather than cache and risk going stale.
+    """
+    from flowx_border.engine import run_scan
+    from flowx_border.registry import assert_satisfiable, loaded_detectors
+
+    assert_satisfiable(policy, side)
+    return run_scan(text, side, policy, ctx, loaded_detectors())
+
+
+def scan_input(text: str, policy: Policy, ctx: Context | None = None) -> Decision:
+    """Inspect text on its way to the model.
+
+    Raises DetectorUnavailableError when the policy expects a detector this
+    install does not have to enforce something. It does not silently pass the text.
+    """
+    return _scan(text, "input", policy, ctx)
+
+
+def scan_output(text: str, policy: Policy, ctx: Context | None = None) -> Decision:
+    """Inspect text on its way back from the model.
+
+    Raises DetectorUnavailableError when the policy expects a detector this
+    install does not have to enforce something. It does not silently pass the text.
+    """
+    return _scan(text, "output", policy, ctx)

flowx_border/adapters/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Integration adapters.
+
+Deliberately not imported by `flowx_border/__init__.py`. Each adapter imports a
+framework
+the library does not depend on, so importing the package must not drag LangGraph or
+FastAPI in. A caller reaches for the one they need:
+
+    from flowx_border.adapters.fastapi import guard_dependency
+    from flowx_border.adapters.langgraph import guard_node
+    from flowx_border.adapters.llm_guard_compat import scan_prompt
+
+None of them is a third public entry point in the sense CLAUDE.md restricts: each is a
+wrapper over `scan_input` and `scan_output`, holds no logic of its own, and would be
+correct to delete. BUILD_PLAN.md puts the ceiling at roughly 120 lines each, on the
+theory
+that an adapter needing more than that is evidence the core API is wrong.
+"""

flowx_border/adapters/fastapi.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: Apache-2.0
+"""FastAPI integration, offered as a dependency and as middleware.
+
+Both forms exist because they suit different applications, and picking one for you would
+be wrong in half the cases.
+
+`guard_dependency` is the one to reach for. It scans a field you name, and because it is
+a
+dependency it composes with everything FastAPI already does: it runs after
+validation, it
+can be applied per route, and the Decision arrives as a normal parameter, so the handler
+can decide what to do with a redaction.
+
+`GuardMiddleware` is for retrofitting an application whose handlers you would rather not
+touch. It intercepts a JSON path on the request and on the response. It is the blunter
+tool: middleware sees bytes and has to parse them, it cannot know which routes carry
+user
+text, and it applies to all of them until you narrow `paths`.
+
+**A block returns 422 rather than raising.** A refusal is a normal outcome of a guard,
+not
+a server fault, and a 5xx would page somebody. 422 says the request was understood and
+rejected on content, which is what happened. The record id goes in the body so a support
+conversation can start from the audit trail rather than from a screenshot.
+
+FastAPI **is** imported at module scope here, and that is deliberate.
+`adapters/__init__.py`
+imports no submodule, so `import flowx_border` never reaches this file and the library
+keeps
+FastAPI out of its dependency set. Importing it lazily inside the factory looked tidier
+and
+was actually broken: with `from __future__ import annotations` every annotation is a
+string, FastAPI resolves a dependency's signature with `get_type_hints`, and a
+`Request` that only
+exists as a local name cannot be resolved. It silently degraded to treating `request` as
+a
+query parameter, so every call returned 422 with `{"loc": ["query", "request"]}`.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from fastapi import HTTPException, Request
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import JSONResponse, Response
+
+if TYPE_CHECKING:
+    from flowx_border.policy import Policy
+    from flowx_border.types import Decision
+
+#  What a blocked request answers with. Not 400: the request was well formed. Not 5xx:
+# the
+#  server did not fail. 422 is the status FastAPI already uses for content it will not
+# act
+#: on.
+BLOCKED_STATUS = 422
+
+
+def _blocked_body(decision: Decision) -> dict[str, Any]:
+    """The response body for a refusal.
+
+    Carries the record id and the finding summary, and deliberately not the text or the
+    spans. A 4xx body is the most likely thing to end up in a log aggregator, a browser
+    console or a support ticket, so it gets the same no-raw-text treatment as the
+    evidence
+    record itself.
+    """
+    return {
+        "detail": "blocked by content policy",
+        "record_id": decision.evidence.record_id,
+        "policy_id": decision.evidence.policy_id,
+        "findings": [
+            {"detector": f.detector_id, "label": f.label} for f in decision.findings
+        ],
+    }
+
+
+def guard_dependency(
+    policy: Policy,
+    *,
+    field: str = "prompt",
+    side: str = "input",
+) -> Callable[..., Any]:
+    """A FastAPI dependency that scans one field of the JSON body.
+
+    Returns the Decision, so the handler receives the possibly-redacted text as
+    `decision.text` and can still see what was found. Raises HTTPException(422) on a
+    block,
+    which FastAPI turns into a normal response.
+    """
+    from flowx_border import scan_input, scan_output
+
+    scan = scan_input if side == "input" else scan_output
+
+    async def dependency(request: Request) -> Decision | None:
+        try:
+            body = await request.json()
+        except (json.JSONDecodeError, ValueError):
+            # Not JSON, so there is no named field to scan. Letting it through is
+            # correct:
+            # this dependency guards a field, and a request without that field is the
+            # route's problem to reject, not this one's.
+            return None
+
+        text = body.get(field) if isinstance(body, dict) else None
+        if not isinstance(text, str) or not text:
+            return None
+
+        decision = scan(text, policy)
+        if decision.verdict == "block":
+            raise HTTPException(
+                status_code=BLOCKED_STATUS, detail=_blocked_body(decision)
+            )
+        return decision
+
+    return dependency
+
+
+def guard_middleware(
+    policy: Policy,
+    *,
+    request_field: str = "prompt",
+    response_field: str = "completion",
+    paths: tuple[str, ...] = (),
+) -> Callable[..., Any]:
+    """An ASGI middleware factory scanning a request field and a response field.
+
+    `paths` narrows which routes are touched, and defaulting it to empty means every
+    route,
+    which is the behaviour someone reaching for middleware is asking for. Narrow it as
+    soon
+    as you know which routes carry user text: a health check costs a model pass.
+    """
+    from flowx_border import scan_input, scan_output
+
+    class GuardMiddleware(BaseHTTPMiddleware):
+        async def dispatch(
+            self, request: Request, call_next: RequestResponseEndpoint
+        ) -> Response:
+            if paths and not any(str(request.url.path).startswith(p) for p in paths):
+                return await call_next(request)
+
+            raw = await request.body()
+            if raw:
+                try:
+                    body = json.loads(raw)
+                except (json.JSONDecodeError, ValueError):
+                    body = None
+                if isinstance(body, dict) and isinstance(body.get(request_field), str):
+                    decision = scan_input(body[request_field], policy)
+                    if decision.verdict == "block":
+                        return JSONResponse(
+                            status_code=BLOCKED_STATUS, content=_blocked_body(decision)
+                        )
+
+            response = await call_next(request)
+
+            # The response side needs the assembled body, which means buffering the
+            # stream. Stated rather than hidden: this makes a streaming response
+            # non-streaming, and it is the main reason to prefer the dependency form
+            # for an endpoint that streams tokens.
+            #
+            # Both response shapes are handled. BaseHTTPMiddleware normally hands back
+            # a streaming response, but a middleware further down the stack may have
+            # buffered it into a plain one already, and assuming body_iterator exists
+            # would fail on exactly that stack.
+            streaming = getattr(response, "body_iterator", None)
+            if streaming is not None:
+                payload = b"".join([chunk async for chunk in streaming])
+            else:
+                payload = bytes(getattr(response, "body", b""))
+            try:
+                body = json.loads(payload)
+            except (json.JSONDecodeError, ValueError):
+                # Not JSON, so there is no field to scan. Passed through byte for byte
+                # rather than dropped: middleware that eats a non-JSON response because
+                # it
+                # could not parse it would break every file download in the application.
+                return _passthrough(response, payload)
+
+            if isinstance(body, dict) and isinstance(body.get(response_field), str):
+                decision = scan_output(body[response_field], policy)
+                if decision.verdict == "block":
+                    return JSONResponse(
+                        status_code=BLOCKED_STATUS, content=_blocked_body(decision)
+                    )
+                body[response_field] = decision.text
+                return JSONResponse(status_code=response.status_code, content=body)
+
+            return _passthrough(response, payload)
+
+    return GuardMiddleware
+
+
+def _passthrough(response: Response, payload: bytes) -> Response:
+    """Return a buffered response unchanged, preserving status and headers."""
+    headers = dict(response.headers)
+    headers.pop("content-length", None)
+    return Response(
+        content=payload,
+        status_code=response.status_code,
+        headers=headers,
+        media_type=response.media_type,
+    )

flowx_border/adapters/langgraph.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A LangGraph node that scans the message state.
+
+`guard_node(policy, side)` returns a callable to drop into a graph. It reads the last
+message, scans it, writes back the possibly-redacted text, and puts the Decision on the
+state under `border` so a later node or a human reviewer can read the evidence record.
+
+**A block routes, it does not raise.** An exception inside a graph node becomes a
+traceback
+in someone's request handler and takes the whole turn down. Routing to a named terminal
+node keeps the refusal inside the graph's own control flow, which is where a product
+decides what to say to the user. The node name is configurable because only the caller
+knows what their graph calls that state.
+
+LangGraph is not imported. The node is a plain callable over a mapping, which is all
+LangGraph requires, and that keeps the framework out of the dependency set.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from flowx_border.detectors.base import Context
+    from flowx_border.policy import Policy
+
+#: Where the Decision lands on the state. Namespaced so it cannot collide with a graph's
+#: own keys.
+STATE_KEY = "border"
+
+
+def guard_node(
+    policy: Policy,
+    side: str = "input",
+    *,
+    messages_key: str = "messages",
+    blocked_node: str = "blocked",
+    ctx: Context | None = None,
+) -> Callable[[Mapping[str, Any]], dict[str, Any]]:
+    """Build a graph node that scans the most recent message.
+
+    Returns a partial state update, which is what LangGraph expects: the message list
+    is
+    only rewritten when redaction actually changed the text, so a clean scan adds the
+    evidence record and touches nothing else.
+    """
+    from flowx_border import scan_input, scan_output
+
+    scan = scan_input if side == "input" else scan_output
+
+    def node(state: Mapping[str, Any]) -> dict[str, Any]:
+        messages = list(state.get(messages_key) or [])
+        if not messages:
+            return {}
+
+        last = messages[-1]
+        text = (
+            last.get("content")
+            if isinstance(last, Mapping)
+            else getattr(last, "content", "")
+        )
+        if not isinstance(text, str) or not text:
+            return {}
+
+        decision = scan(text, policy, ctx)
+        update: dict[str, Any] = {
+            STATE_KEY: {
+                "verdict": decision.verdict,
+                "findings": [f.model_dump() for f in decision.findings],
+                "evidence": decision.evidence.model_dump(),
+                "elapsed_ms": decision.elapsed_ms,
+            }
+        }
+
+        if decision.verdict == "block":
+            # A routing hint rather than an exception. The graph decides what a refusal
+            # looks like; this node only says that one is required.
+            update["next"] = blocked_node
+            return update
+
+        if decision.text != text:
+            replaced = dict(last) if isinstance(last, Mapping) else last
+            if isinstance(replaced, dict):
+                replaced["content"] = decision.text
+            else:
+                replaced = {
+                    "role": getattr(last, "role", "user"),
+                    "content": decision.text,
+                }
+            update[messages_key] = [*messages[:-1], replaced]
+
+        return update
+
+    return node

flowx_border/adapters/llm_guard_compat.py

@@ -0,0 +1,296 @@
+# SPDX-License-Identifier: Apache-2.0
+"""A source-compatible shim for the archived llm-guard scanner API.
+
+Exists so that migrating is an import change rather than a rewrite. `scan_prompt` and
+`scan_output` keep llm-guard's signatures and its tuple return shape, and scanner names
+map onto detector ids where a real equivalent exists.
+
+**A scanner with no equivalent raises.** This is the whole design of the file. A shim
+that accepted `BanCode` and quietly did nothing would leave a caller believing code was
+being blocked, and they would have no way to find out except by being breached. An
+exception on the first call is loud, immediate, and fixable. So the mapping below is
+exhaustive:
+every scanner llm-guard shipped is either mapped or listed as unsupported by name, and
+`docs/migrating-from-llm-guard.md` carries the same table for people who would rather
+read than run.
+
+One behavioural difference worth stating, because it cannot be shimmed away. llm-guard
+returns a per-scanner dict of scores and a sanitised string. This library returns a
+Decision carrying an evidence record, and the record is the point of it. The tuple is
+reconstructed for compatibility, and `decision_for` hands back the real object for
+anyone ready to use it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Any, Final
+
+from flowx_border.detectors.catalogue import CATALOGUE
+
+if TYPE_CHECKING:
+    from flowx_border.policy import Policy
+    from flowx_border.types import Decision
+
+#: llm-guard scanner name to detector id. Only where the equivalence is real: a mapping
+# that is approximately right is worse than an absent one, because it reports a check
+# the
+#: caller did not ask for and did not get.
+SUPPORTED: Final[dict[str, str]] = {
+    # Input scanners.
+    "Anonymize": "pii",
+    # Listed as unsupported until 2026-08-12, when code_present landed to close exactly
+    # this gap. Both scanners ask the same question and get the same detector: the
+    # difference upstream is which side it runs on, which is a policy choice here.
+    "BanCode": "code_present",
+    # Declined during the port because a token count depends on the tokenizer of the
+    # model being called, which this library does not know. It knows it now: the policy
+    # names the tokenizer and pins it. Landed 2026-08-12.
+    "TokenLimit": "token_limit",
+    "Code": "code_present",
+    # Listed as unsupported until 2026-08-12, with a note saying no detector reported
+    # these characters yet. One had shipped: invisible_text is T0, in CORE, and covers
+    # bidirectional controls, tag characters and zero-width characters. A migration
+    # table that understates what exists sends people away for a capability they already
+    # have.
+    "InvisibleText": "invisible_text",
+    "PromptInjection": "injection",
+    "Secrets": "secrets",
+    "Gibberish": "gibberish",
+    "Toxicity": "toxicity",
+    "BanTopics": "topic_scope",
+    "NSFW": "nsfw",
+    # Output scanners.
+    "Deanonymize": "output_leakage",
+    "Sensitive": "output_leakage",
+    "NoRefusal": "politeness",
+    "Bias": "bias",
+    "FactualConsistency": "groundedness",
+    "Relevance": "topic_scope",
+    # Added 2026-08-11 with the Guardrails Hub port. Each of these was in UNSUPPORTED
+    # until the detector it names existed, and the note there said so. See
+    # docs/porting-guardrails-validators.md.
+    "BanSubstrings": "banned_terms",
+    "BanCompetitors": "banned_terms",
+    "JSON": "output_format",
+    "Regex": "output_format",
+    "ReadingTime": "output_format",
+    "URLReachability": "url_reachability",
+    # Added 2026-08-16 with language_id. Both were in UNSUPPORTED until it existed,
+    # and the note there said what was missing. Language asks whether text is in a
+    # permitted language and needs the list; LanguageSame compares an answer against
+    # the prompt and needs the prompt's language, which only the caller can supply.
+    "Language": "language_id",
+    "LanguageSame": "language_id",
+}
+
+#: Scanners that map onto a detector whose entire input is data the caller has to
+#: supply. llm-guard took that data as constructor arguments, `BanSubstrings(substrings=
+#: [...])`; here it is policy, and this shim cannot invent it.
+#: Passing one of these without a `policy=` raises. That is the same rule the file
+#: already applies to an unmapped scanner, for the same reason: `banned_terms` with no
+#: terms reports `terms_not_configured` and finds nothing, so accepting the call would
+#: hand back a clean-looking result for a check that never ran. The error names the
+#: option to set, so the fix is in the message.
+NEEDS_POLICY: Final[dict[str, str]] = {
+    "BanSubstrings": "banned_terms.options.terms, with whole_words: false",
+    "BanCompetitors": "banned_terms.options.terms",
+    "Regex": "output_format.options.regex",
+    "ReadingTime": "output_format.options.max_reading_seconds",
+    "JSON": "output_format.options.json: true",
+    "Language": "language_id.options.allowed, a list of language codes",
+    "LanguageSame": (
+        "language_id.options.match_input: true, and ctx.metadata['input_language']"
+    ),
+}
+
+# Scanners with no equivalent here, and why. Listed rather than omitted so that the
+# error
+#: can say what the gap is instead of only that there is one.
+UNSUPPORTED: Final[dict[str, str]] = {
+    "Sentiment": (
+        "no sentiment detector. politeness is the nearest, and it is not the same."
+    ),
+    "MaliciousURLs": (
+        "no URL reputation detector. url_reachability asks whether a link answers, "
+        "which is a different question from whether it is hostile, and answering the "
+        "second needs a reputation feed this library does not ship."
+    ),
+}
+
+
+class UnsupportedScannerError(NotImplementedError):
+    """A scanner this shim will not pretend to implement."""
+
+
+class UnconfiguredScannerError(ValueError):
+    """A mapped scanner whose detector needs data only a policy can supply.
+
+    Separate from UnsupportedScannerError because it is a different problem with a
+    different fix: the check exists and is wired, and what is missing is the list. Both
+    raise for the same underlying reason, which is that the alternative is a call that
+    returns a clean result for a check that never ran.
+    """
+
+
+def _scanner_names(scanners: Sequence[Any] | None) -> list[str]:
+    """Scanner names from classes, instances or bare strings.
+
+    All three shapes are in the wild: llm-guard's own examples construct instances, its
+    README lists classes, and configuration files carry strings.
+    """
+    names = []
+    for scanner in scanners or []:
+        name = getattr(scanner, "__name__", None) or type(scanner).__name__
+        if isinstance(scanner, str):
+            name = scanner
+        names.append(name)
+    return names
+
+
+def _detector_ids(scanners: Sequence[Any] | None) -> list[str]:
+    """Map a caller's scanner list onto detector ids. Raises on anything unsupported."""
+    names = _scanner_names(scanners)
+
+    unsupported = [name for name in names if name not in SUPPORTED]
+    if unsupported:
+        details = "\n".join(
+            f"  {name}: {UNSUPPORTED.get(name, 'not a known llm-guard scanner.')}"
+            for name in unsupported
+        )
+        raise UnsupportedScannerError(
+            f"these scanners have no equivalent in flowx-border:\n{details}\n"
+            "They raise rather than passing, because a security shim that silently "
+            "does nothing is worse than one that fails. See "
+            "docs/migrating-from-llm-guard.md."
+        )
+    return [SUPPORTED[name] for name in names]
+
+
+def _to_tuple(
+    decision: Decision, wanted: list[str]
+) -> tuple[str, dict[str, bool], dict[str, float]]:
+    """llm-guard's (sanitised_text, results_valid, results_score) shape.
+
+    `results_valid` is False for a detector that found something, matching llm-guard's
+    sense of valid. Scores are the highest a detector reported, since llm-guard carried
+    one number per scanner and this library carries one per finding.
+    """
+    worst: dict[str, float] = dict.fromkeys(wanted, 0.0)
+    for finding in decision.findings:
+        if finding.detector_id in worst:
+            worst[finding.detector_id] = max(worst[finding.detector_id], finding.score)
+    valid = {detector: score == 0.0 for detector, score in worst.items()}
+    return decision.text, valid, worst
+
+
+def scan_prompt(
+    prompt: str, scanners: Sequence[Any] | None = None, policy: Policy | None = None
+) -> tuple[str, dict[str, bool], dict[str, float]]:
+    """llm-guard's scan_prompt, backed by scan_input.
+
+    `policy` is an addition rather than a rename: llm-guard configured behaviour by
+    constructing scanners, and here behaviour is policy, which is data. Without one, the
+    scanners you pass are enabled at their defaults and everything else is disabled.
+    """
+    from flowx_border import scan_input
+
+    _require_policy_for(_scanner_names(scanners), policy)
+    wanted = _detector_ids(scanners)
+    decision = scan_input(prompt, policy or _policy_for(wanted))
+    return _to_tuple(decision, wanted)
+
+
+def scan_output(
+    prompt: str,
+    output: str,
+    scanners: Sequence[Any] | None = None,
+    policy: Policy | None = None,
+) -> tuple[str, dict[str, bool], dict[str, float]]:
+    """llm-guard's scan_output, backed by scan_output.
+
+    The prompt is not ignored: it becomes `Context.sources`, which is what lets
+    output_leakage tell a leak from the assistant repeating back what the user typed.
+    llm-guard's Deanonymize and Sensitive both map here, and both are better for it.
+    """
+    from flowx_border import scan_output as _scan
+    from flowx_border.detectors.base import Context
+
+    _require_policy_for(_scanner_names(scanners), policy)
+    wanted = _detector_ids(scanners)
+    decision = _scan(output, policy or _policy_for(wanted), Context(sources=(prompt,)))
+    return _to_tuple(decision, wanted)
+
+
+def decision_for(
+    text: str,
+    side: str,
+    scanners: Sequence[Any] | None = None,
+    policy: Policy | None = None,
+) -> Decision:
+    """The real Decision, for a caller who has finished migrating.
+
+    Here so that the tuple above is a stepping stone rather than a ceiling: the evidence
+    record is the reason to be here, and llm-guard's shape has nowhere to put it.
+    """
+    from flowx_border import scan_input
+    from flowx_border import scan_output as _scan
+
+    _require_policy_for(_scanner_names(scanners), policy)
+    wanted = _detector_ids(scanners)
+    resolved = policy or _policy_for(wanted)
+    return scan_input(text, resolved) if side == "input" else _scan(text, resolved)
+
+
+def _require_policy_for(names: list[str], policy: Policy | None) -> None:
+    """Refuse a scanner that needs configuration when no policy carries it.
+
+    llm-guard configured a scan by how you constructed the scanner:
+    `BanSubstrings(substrings=[...])`. Here configuration is policy, which is data, and
+    this shim has nowhere to read a constructor argument from even when the caller
+    passes an instance, because the attribute names are private to that library and
+    guessing them wrong produces an empty list rather than an error.
+
+    An empty list is the case that matters. `banned_terms` with no terms reports
+    `terms_not_configured` and finds nothing, so accepting the call would return a
+    clean-looking tuple for a check that never ran. That is the exact failure this
+    shim's unsupported table exists to prevent, so it gets the same treatment.
+    """
+    if policy is not None:
+        return
+    unconfigured = [name for name in names if name in NEEDS_POLICY]
+    if not unconfigured:
+        return
+    details = "\n".join(f"  {name}: set {NEEDS_POLICY[name]}" for name in unconfigured)
+    raise UnconfiguredScannerError(
+        f"these scanners need configuration that only a policy can carry:\n{details}\n"
+        "llm-guard took it as constructor arguments; here it is policy, because a "
+        "policy is data a reviewer can read and its hash pins what ran. Pass policy= "
+        "with those options set. This raises rather than scanning, because the "
+        "detector would report that it was unconfigured and the tuple would look "
+        "clean. See docs/migrating-from-llm-guard.md."
+    )
+
+
+def _policy_for(detector_ids: list[str]) -> Policy:
+    """A policy enabling exactly the requested detectors, everything else off.
+
+    T0 cannot be disabled, so `secrets` and `disclosure` are present whether or not the
+    caller asked. They report rather than enforce here, because a migration should not
+    start blocking traffic that llm-guard was letting through.
+    """
+    from flowx_border.policy import DetectorPolicy, Policy
+
+    wanted = set(detector_ids)
+    return Policy(
+        policy_id="llm-guard-compat",
+        version=1,
+        fail_mode=dict.fromkeys(("T0", "T1", "T2", "T3"), "open"),
+        detectors={
+            detector: DetectorPolicy(
+                enabled=detector in wanted or spec.tier == "T0",
+                on_fail="flag",
+            )
+            for detector, spec in CATALOGUE.items()
+        },
+    )