llm-stream-guards 0.1.0__py3-none-any.whl

llm_stream_guards/__init__.py

@@ -0,0 +1,38 @@
+"""Deterministic guards for a streamed LLM reply: what may be shown now, what must wait, and when to stop."""
+
+from ._amounts import ENGLISH, AmountStream, Locale, numbers_in, unsupported_amounts
+from ._code import CodeStream, contains_code_deliverable
+from ._leak import LeakGuard, LeakStream
+from ._links import (
+    LinkStream,
+    emails_in,
+    hosts_of,
+    phones_in,
+    strip_untrusted_links,
+    without_ungrounded_emails,
+    without_ungrounded_phones,
+)
+from ._stream import Blocked, Chain, StreamGuard
+
+__all__ = [
+    "ENGLISH",
+    "AmountStream",
+    "Blocked",
+    "Chain",
+    "CodeStream",
+    "LeakGuard",
+    "LeakStream",
+    "LinkStream",
+    "Locale",
+    "StreamGuard",
+    "contains_code_deliverable",
+    "emails_in",
+    "hosts_of",
+    "numbers_in",
+    "phones_in",
+    "strip_untrusted_links",
+    "unsupported_amounts",
+    "without_ungrounded_emails",
+    "without_ungrounded_phones",
+]
+__version__ = "0.1.0"

llm_stream_guards/_amounts.py

@@ -0,0 +1,344 @@
+import re
+from collections.abc import Collection, Iterable, Iterator, Mapping
+from dataclasses import dataclass, field
+
+from ._stream import Blocked, next_anchor
+
+# 1,200 or 1200.50 or 50 000 (a space or a no-break space between thousands). A number does not start after a digit, or
+# after a digit and a comma: that is the middle of one, which would only be matched again, and failed again, from every
+# digit of a long run. A comma after a letter ("Basic,29") does not stop one, and an empty field ("12,,45") ends one.
+_NUMBER_TEXT = r"((?<!\d)(?<!\d,)\d{1,3}(?:[^\S\r\n]\d{3})+(?:\.\d+)?|(?<!\d)(?<!\d,)\d+(?:,\d+)*,*(?:\.\d+)?)"
+_DIGITS = r"((?<!\d)(?<!\d,)\d+(?:,\d+)*,*(?:\.\d+)?)"
+# A cost word this many characters before or after a bare magnitude ("60k") or a rate makes it a price.
+_COST_WORD_WINDOW = 120
+# What an empty list of words compiles to, so that it matches nothing rather than everything.
+_NEVER = "(?!)"
+# What may be the start of a magnitude: letters only, as `_TRAILING_NUMBER` holds them.
+_WORD_ONLY = re.compile(r"[^\W\d_]+")
+
+
+def _either(parts: Iterable[str]) -> str:
+    return "|".join(part for part in parts if part) or _NEVER
+
+
+@dataclass(frozen=True, eq=False)
+class Locale:
+    """
+    The words and symbols the amount guard reads. The regex fragments are matched ignoring case.
+
+    - `currency_symbols`: written before or after an amount: `$120`, `50 000 €`.
+    - `currency_codes`: written before or after an amount: `INR 50,000`, `120 usd`.
+    - `currency_prefixes`: regex fragments written before an amount, besides the codes: `Rs. 50,000`.
+    - `currency_names`: regex fragments written after an amount: `40 euros`, `40 US dollars`.
+    - `magnitudes`: a word after a number that multiplies it, so `$2M` and `$2,000,000` compare equal. A word longer
+      than two letters may take a plural `s`.
+    - `cost_words`: words that make a bare magnitude (`60k`) or a rate a price when they are near it.
+    - `effort`: a regex fragment after an amount that makes it effort in person-time: `300 engineering hours`.
+    - `rate`: a regex fragment after a number that makes it a rate: `120 per hour`, `120 an hour`.
+    - `range_words`: words that join the two ends of a range, besides a hyphen or a dash: `$40 to $65`.
+
+    Change one with `dataclasses.replace`: `replace(ENGLISH, currency_codes=(*ENGLISH.currency_codes, "nok"))`.
+    Numbers are read with `.` as the decimal point and `,` or a space between thousands, whatever the locale.
+    """
+
+    currency_symbols: str = "$€£₹¥"
+    currency_codes: tuple[str, ...] = ("usd", "eur", "gbp", "inr", "aed", "sgd", "chf", "sar", "jpy", "aud", "cad")
+    currency_prefixes: tuple[str, ...] = (r"rs\.?", r"us\$")
+    currency_names: tuple[str, ...] = (r"(?:us\s+)?dollars?", "euros?", "pounds?", "rupees?")
+    magnitudes: Mapping[str, int] = field(
+        default_factory=lambda: {
+            "k": 1_000,
+            "m": 1_000_000,
+            "bn": 1_000_000_000,
+            "thousand": 1_000,
+            "lakh": 100_000,
+            "million": 1_000_000,
+            "crore": 10_000_000,
+            "billion": 1_000_000_000,
+        }
+    )
+    cost_words: tuple[str, ...] = (
+        "cost", "costs", "costing", "price", "priced", "pricing", "budget", "budgets", "quote", "quoted", "rate",
+        "rates", "fee", "fees", "charge", "charges", "invest", "investment", "spend", "ballpark", "estimate",
+        "estimates",
+    )  # fmt: skip
+    effort: str = r"(?:person|man|developer|dev|engineer|engineering)[-\s](?:hours?|days?|weeks?|months?)\b"
+    rate: str = r"\s*(?:per|/)\s*(?:hour|hr|day)\b|\s+an?\s+hour\b"
+    range_words: tuple[str, ...] = ("to", "and")
+
+    _scale: dict[str, int] = field(init=False, repr=False)
+    _number: re.Pattern[str] = field(init=False, repr=False)
+    _money: re.Pattern[str] = field(init=False, repr=False)
+    _range: re.Pattern[str] = field(init=False, repr=False)
+    _range_named: re.Pattern[str] = field(init=False, repr=False)
+    _bare_magnitude: re.Pattern[str] = field(init=False, repr=False)
+    _rate: re.Pattern[str] = field(init=False, repr=False)
+    _cost_word: re.Pattern[str] = field(init=False, repr=False)
+    _trailing_symbol: re.Pattern[str] = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        scale = {word.lower(): value for word, value in self.magnitudes.items()}
+        words = _either(f"{re.escape(word)}s?" if len(word) > 2 else re.escape(word) for word in scale)
+        amount = _NUMBER_TEXT + r"\s*(?:(" + words + r")\b)?"
+        symbol = "[" + re.escape(self.currency_symbols) + "]" if self.currency_symbols else _NEVER
+        codes = [re.escape(code) for code in self.currency_codes]
+        before = _either([*self.currency_prefixes, *codes])
+        after = _either([*self.currency_names, *codes])
+        joiner = _either([r"-|\u2013|\u2014", *map(re.escape, self.range_words)])
+        effort, rate = _either([self.effort]), _either([self.rate])
+        cost_words = _either(map(re.escape, self.cost_words))
+        compiled = {
+            "_scale": scale,
+            "_number": re.compile(amount, re.IGNORECASE),
+            "_money": re.compile(
+                f"{symbol}\\s*{amount}"
+                f"|(?<![A-Za-z])(?:{before})\\s*{amount}"
+                f"|{amount}\\s*(?:{after})\\b"
+                f"|{amount}\\s*{symbol}"
+                f"|{amount}\\s*(?:{effort})",
+                re.IGNORECASE,
+            ),
+            "_range": re.compile(f"({symbol})?\\s*{amount}\\s*(?:{joiner})\\s*({symbol})?\\s*{amount}", re.IGNORECASE),
+            # A range priced by a code or a name ("USD 40 to 65", "40 to 65 euros") rather than by a symbol.
+            "_range_named": re.compile(
+                f"(?<![A-Za-z])(?:{before})\\s*{amount}\\s*(?:{joiner})\\s*{amount}"
+                f"|{amount}\\s*(?:{joiner})\\s*{amount}\\s*(?:{after})\\b",
+                re.IGNORECASE,
+            ),
+            "_bare_magnitude": re.compile(r"\b" + _DIGITS + r"\s*(" + words + r")\b", re.IGNORECASE),
+            "_rate": re.compile(r"\b" + _DIGITS + f"(?:{rate})", re.IGNORECASE),
+            "_cost_word": re.compile(r"\b(?:" + cost_words + r")\b", re.IGNORECASE),
+            "_trailing_symbol": re.compile(symbol + r"\s*\Z"),
+        }
+        for name, value in compiled.items():
+            object.__setattr__(self, name, value)
+
+
+ENGLISH = Locale()
+
+
+def _unit(magnitude: str, scale: Mapping[str, int]) -> str:
+    """
+    A written magnitude as `scale` names it. Folded, not lowered: ignoring case, the "s" of a plural also matches the
+    long s (U+017F), which lowercasing leaves as it is and casefolding turns into "s".
+    """
+    unit = magnitude.casefold()
+    return unit if unit in scale else unit.removesuffix("s")
+
+
+def _amount_keys(number: str, magnitude: str | None, scale: Mapping[str, int]) -> set[str]:
+    """
+    How one written amount is compared. A bare figure is its digits and nothing else, so a "5" anywhere in a source
+    never grounds a "$5k". A figure with a magnitude is its digits with the magnitude ("5k") and the value it stands for
+    ("5000"), so "$2M" and "$2,000,000" compare equal and either alone is enough. A decimal is also its digits without
+    trailing zeros, so "$1,200" and "$1,200.00" do too.
+    """
+    digits = re.sub(r"[,\s]", "", number).rstrip(".")
+    # "12.50" is "12.5": a price is written either way, and a source's and a reply's may differ.
+    written = {digits, digits.rstrip("0").rstrip(".")} if "." in digits else {digits}
+    if not magnitude:
+        return written
+    unit = _unit(magnitude, scale)
+    keys = {f"{form}{unit}" for form in written}
+    value = float(digits) * scale[unit]
+    if value.is_integer():
+        keys.add(str(int(value)))
+    return keys
+
+
+def _range_key(ends: tuple[str, str | None, str, str | None], scale: Mapping[str, int]) -> str:
+    """A range as its two values, so "$2M to $3M" and "$2,000,000-$3,000,000" compare equal."""
+    low, low_unit, high, high_unit = ends
+    values = []
+    for number, magnitude in ((low, low_unit), (high, high_unit)):
+        unit = _unit(magnitude or "", scale)
+        value = float(re.sub(r"[,\s]", "", number).rstrip(".")) * scale.get(unit, 1)
+        values.append(str(int(value)) if value.is_integer() else str(value))
+    return f"range:{values[0]}-{values[1]}"
+
+
+def _ranges(text: str, locale: Locale) -> Iterator[tuple[re.Match[str], str, bool]]:
+    """
+    (match, key, priced) for each range in `text`; `priced` is that a currency symbol, code or name sits beside an end.
+    A range with a symbol is one match even when a code or name follows it too; one with none is still a key.
+    """
+    spans: list[tuple[int, int]] = []
+    for match in locale._range.finditer(text):
+        symbol_before, low, low_unit, symbol_after, high, high_unit = match.groups()
+        priced = bool(symbol_before or symbol_after)
+        if priced:
+            spans.append(match.span())
+        yield match, _range_key((low, low_unit, high, high_unit), locale._scale), priced
+    for match in locale._range_named.finditer(text):
+        if any(match.start() < end and start < match.end() for start, end in spans):
+            continue
+        # The amounts are read again, so that a fragment of the locale with a group of its own cannot shift them.
+        (low, low_unit), (high, high_unit) = locale._number.findall(match.group(0))[:2]
+        yield match, _range_key((low, low_unit, high, high_unit), locale._scale), True
+
+
+def numbers_in(*texts: str | None, locale: Locale = ENGLISH) -> set[str]:
+    """
+    Every number `texts` state, in the form `unsupported_amounts` compares against, and every range as one more
+    key (`range:low-high`): the grounded set for the amount guard.
+    """
+    keys: set[str] = set()
+    for text in texts:
+        for number, magnitude in locale._number.findall(text or ""):
+            keys |= _amount_keys(number, magnitude or None, locale._scale)
+        keys |= {key for _, key, _ in _ranges(text or "", locale)}
+    return keys
+
+
+def _near_cost_word(text: str, match: re.Match[str], locale: Locale, *, complete: bool = True) -> bool:
+    start = max(0, match.start() - _COST_WORD_WINDOW)
+    window = text[start : match.end() + _COST_WORD_WINDOW]
+    # A cost word that ends a text still streaming may be the start of another word: "cost" before "umes".
+    return any(complete or start + word.end() < len(text) for word in locale._cost_word.finditer(window))
+
+
+def unsupported_amounts(
+    text: str, grounded: Collection[str], *, complete: bool = True, locale: Locale = ENGLISH
+) -> list[str]:
+    """
+    The money and person-time figures in `text` that `grounded` (see `numbers_in`) does not state, as written.
+
+    A figure is a currency symbol, code or name beside a number (`$120`, `INR 50,000`, `40 euros`), effort in
+    person-time (`300 engineering hours`), a range with a currency (`$40 to $65`), or a bare magnitude or a rate with
+    a cost word within 120 characters (`a budget of 60k`, `the rate is 120 per hour`). A bare figure is grounded by
+    the same figure only, one with a magnitude by the same value, and a range only by a source stating that range.
+
+    With `complete=False`, for text still streaming, a figure that ends the text is not judged yet: it may still
+    grow ("$5" before "00 a month").
+    """
+    found: list[str] = []
+
+    def settled(match: re.Match[str]) -> bool:
+        if complete:
+            return True
+        rest = text[match.end() :]
+        if not rest:
+            return False
+        # What follows may still be part of the figure: the start of "million", or the point of "12.50" when a source
+        # states a figure that goes on like that. Otherwise a full stop ends the sentence.
+        if rest == "." and match.group(0)[-1].isdecimal():
+            digits = re.sub(r"[,\s]", "", locale._number.findall(match.group(0))[-1][0])
+            if any(key.startswith(f"{digits}.") for key in grounded):
+                return False
+        return not (_WORD_ONLY.fullmatch(rest) and any(word.startswith(rest.lower()) for word in locale._scale))
+
+    for match in locale._money.finditer(text):
+        if not settled(match):
+            continue
+        number, magnitude = locale._number.findall(match.group(0))[0]
+        if _amount_keys(number, magnitude, locale._scale).isdisjoint(grounded):
+            found.append(match.group(0).strip())
+    # Each end of "$65 to $120" may be a figure a source states in different places: the range is grounded only where
+    # a source states it as one.
+    for match, key, priced in _ranges(text, locale):
+        if priced and key not in grounded and settled(match):
+            found.append(match.group(0).strip())
+    for match in locale._bare_magnitude.finditer(text):
+        if (
+            settled(match)
+            and _near_cost_word(text, match, locale, complete=complete)
+            and _amount_keys(match.group(1), match.group(2), locale._scale).isdisjoint(grounded)
+        ):
+            found.append(match.group(0).strip())
+    for match in locale._rate.finditer(text):
+        if (
+            settled(match)
+            and _near_cost_word(text, match, locale, complete=complete)
+            and _amount_keys(match.group(1), None, locale._scale).isdisjoint(grounded)
+        ):
+            found.append(match.group(0).strip())
+    return found
+
+
+_TRAILING_NUMBER = re.compile(r"(?<!\d)(?<!\d,)\b\d+(?:,\d+)*,*(?:\.\d*)?\s*([^\W\d_]*)\Z")
+
+
+def _hold_start(text: str, grounded: Collection[str], locale: Locale) -> int | None:
+    """
+    Where a streaming text must stop being shown for now, or None.
+
+    A money figure or a currency symbol that ends the text may still grow, grounded or not ("$5" then "00"). A bare
+    magnitude no source states is a price only if a cost word comes within the window after it, so it is held until
+    that window has streamed. A number at the end may still become a magnitude ("60" before " thousand").
+    """
+    open_figures = [match.start() for match in locale._money.finditer(text) if match.end() == len(text)]
+    if symbol := locale._trailing_symbol.search(text):
+        open_figures.append(symbol.start())
+    if open_figures:
+        return min(open_figures)
+    starts: set[int] = set()
+    for match in locale._bare_magnitude.finditer(text):
+        unsettled = len(text) < match.end() + _COST_WORD_WINDOW
+        if unsettled and _amount_keys(match.group(1), match.group(2), locale._scale).isdisjoint(grounded):
+            return match.start()
+        starts.add(match.start())
+    for match in locale._rate.finditer(text):
+        if len(text) < match.end() + _COST_WORD_WINDOW and _amount_keys(match.group(1), None, locale._scale).isdisjoint(
+            grounded
+        ):
+            return match.start()
+    trailing = _TRAILING_NUMBER.search(text)
+    # A trailing magnitude already settled above ("60m", grounded) stays settled: "m" only grows into "million".
+    if (
+        trailing
+        and trailing.start() not in starts
+        and any(word.startswith(trailing.group(1).lower()) for word in locale._scale)
+    ):
+        return trailing.start()
+    return None
+
+
+class AmountStream:
+    """
+    Blocks a reply as soon as it states a money or person-time figure that `grounded` (see `numbers_in`) does
+    not, before the piece completing it is shown. A figure that may still grow is held, sourced or not, until a
+    character that cannot continue it arrives; a bare magnitude no source states is held, with the text after it,
+    until the cost-word window after it has streamed or the reply ends. `finish` judges the finished text.
+
+    Each piece is judged with the last 320 to 640 characters of the reply, not the whole of it, so that the time a
+    reply takes grows with its length and not with its square; `finish` judges the whole reply once.
+    """
+
+    def __init__(self, grounded: Collection[str], *, locale: Locale = ENGLISH):
+        self._grounded = grounded
+        self._locale = locale
+        self._text = ""
+        self._anchor = 0
+        self._released = 0
+        self._blocked: Blocked | None = None
+
+    @property
+    def text(self) -> str:
+        return self._text[: self._released]
+
+    def feed(self, delta: str) -> str:
+        self._check(delta, complete=False)
+        held = _hold_start(self._text[self._anchor :], self._grounded, self._locale)
+        upto = len(self._text) if held is None else max(self._anchor + held, self._released)
+        released = self._release(upto)
+        # Never past what is still held: the hold has to see all of it.
+        self._anchor = next_anchor(self._text, self._anchor, len(self._text), self._released)
+        return released
+
+    def finish(self) -> str:
+        self._check("", complete=True)
+        return self._release(len(self._text))
+
+    def _check(self, delta: str, *, complete: bool) -> None:
+        if self._blocked:
+            raise self._blocked
+        self._text += delta
+        text = self._text if complete else self._text[self._anchor :]
+        if found := unsupported_amounts(text, self._grounded, complete=complete, locale=self._locale):
+            self._blocked = Blocked("amount", tuple(found))
+            raise self._blocked
+
+    def _release(self, upto: int) -> str:
+        released = self._text[self._released : upto]
+        self._released = upto
+        return released

llm_stream_guards/_code.py

@@ -0,0 +1,114 @@
+import re
+
+from ._stream import Blocked
+
+# A fenced block is the surest sign that a reply hands over code rather than discussing it. The other shapes are the
+# same content asked for in another format: tilde fences, indented blocks, SQL, shell lines, markup, declarations,
+# shebangs, compose files and definition signatures. Every pattern prefers matching too much: a false positive costs
+# one replaced reply, a false negative hands the code over. Inline code (single backticks) is allowed.
+_FENCE = re.compile(r"```|^[ \t]*~{3,}", re.MULTILINE)
+_SIGNATURE = re.compile(
+    # A definition or an import, not the word: "Import the data first" and "Function calling lets..." are prose,
+    # "import os" and "function go() {" are code.
+    r"\bpublic\s+(?:static\s+)?(?:void|class)\b|\bdef\s+\w+\s*\(|\bfunction\s+\w*\s*\([^)\n]*\)\s*(?:\{|:|=>)|"
+    r"^[^\S\n]*import\s+[\w.]+(?:\s+as\s+\w+)?\s*(?:;|$)|^[^\S\n]*import\s+[\w{},*\s]+\s+from\s+['\"]|^[^\S\n]*#include\s*[<\"]|"
+    r"^[^\S\n]*from\s+[\w.]+\s+import\b|\bclass\s+\w+\s*[{:]|\bfn\s+\w+\s*\(|\bfunc\s+\w+\s*\(|<\w+\s+on\w+=",
+    re.IGNORECASE | re.MULTILINE,
+)
+# The SQL forms need statement structure after the keyword (a column list, a table name plus SET or VALUES), so
+# advice like "select the vendor from the shortlist" does not match.
+_STATEMENT = re.compile(
+    r"^[^\S\n]*SELECT\s+(?:\*|DISTINCT\b|[\w.]+\s*[,(]|[\w.]+\s+FROM\s+\w+\s*(?:;|WHERE\b|JOIN\b|GROUP\b|ORDER\b|LIMIT\b|$))"
+    r"|^[^\S\n]*INSERT\s+INTO\s+\w+[^\n]*(?:\bVALUES\b|\bSELECT\b|\()"
+    r"|^[^\S\n]*UPDATE\s+\w+\s+SET\b"
+    r"|^[^\S\n]*DELETE\s+FROM\s+\w+\s*(?:WHERE\b|;|$)"
+    r"|^[^\S\n]*CREATE\s+TABLE\s+\w+\s*\("
+    r"|^[^\S\n]*(?:\$ |sudo\s|pip\s+install|npm\s+(?:install|run)\b|docker\s+(?:run|compose)\b|curl\s+-)"
+    r"|<(?:script|div|html|body|style)\b"
+    r"|^[^\S\n]*(?:const|let|var)\s+\w+\s*="
+    r"|#!/"
+    # A compose file's top key with a service under it; "Services:" opening a list is not one.
+    r"|^[^\S\n]*services:[ \t]*\n[ \t]+[\w-]+:"
+    # A block opener with its body indented under it; a list under a heading is not a body.
+    r"|^[ \t]*(?:for\s+\w+\s+in\s+[^\n]+|while\s+[^\n]+|if\s+[^\n]*[=<>()][^\n]*|elif\b[^\n]*|else|try)[ \t]*:[ \t]*\n"
+    r"[ \t]+(?![-*+]\s|\d+[.)]\s)\S",
+    re.IGNORECASE | re.MULTILINE,
+)
+# Two consecutive lines indented 4+ spaces or a tab, each with code punctuation. A prose bullet that wraps onto an
+# indented line rarely has these characters on two lines in a row, and a line starting with a list marker never counts.
+_INDENTED = re.compile(
+    r"^(?:(?: {4,}|\t)(?![-*+]\s|\d+[.)]\s)[^\n]*[;{}=(][^\n]*)\n"
+    r"(?:(?: {4,}|\t)(?![-*+]\s|\d+[.)]\s)[^\n]*[;{}=(][^\n]*)(?:\n|$)",
+    re.MULTILINE,
+)
+
+
+def contains_code_deliverable(text: str) -> bool:
+    """Whether `text` hands over code rather than talking about it. Biased towards false positives."""
+    return bool(_FENCE.search(text) or _SIGNATURE.search(text) or _STATEMENT.search(text) or _INDENTED.search(text))
+
+
+def _opens_line(buf: str, i: int, before: str) -> bool:
+    """Whether only indentation precedes `buf[i]` on its line; `before` is the text released ahead of `buf`."""
+    j = i - 1
+    while j >= 0 and buf[j] in " \t":
+        j -= 1
+    if j >= 0:
+        return buf[j] == "\n"
+    before = before.rstrip(" \t")
+    return not before or before.endswith("\n")
+
+
+class CodeStream:
+    """
+    Blocks a reply at its first code fence: three backticks, or three tildes opening a line. A run of backticks
+    or tildes that ends a delta is held until the next one settles it. With `deliverable` (the default), `finish` also
+    blocks a finished reply that `contains_code_deliverable` flags.
+    """
+
+    def __init__(self, *, deliverable: bool = True):
+        self._deliverable = deliverable
+        self._pending = ""
+        self._text = ""
+        self._blocked: Blocked | None = None
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    def feed(self, delta: str) -> str:
+        return self._drain(delta, final=False)
+
+    def finish(self) -> str:
+        tail = self._drain("", final=True)
+        if self._deliverable and contains_code_deliverable(self._text):
+            self._blocked = Blocked("code")
+            raise self._blocked
+        return tail
+
+    def _drain(self, delta: str, *, final: bool) -> str:
+        if self._blocked:
+            raise self._blocked
+        buf = self._pending + delta
+        out: list[str] = []
+        i = 0
+        while i < len(buf):
+            char = buf[i]
+            if char == "`" or (char == "~" and _opens_line(buf, i, self._text)):
+                end = i
+                while end < len(buf) and buf[end] == char:
+                    end += 1
+                if end - i >= 3:
+                    self._blocked = Blocked("code", (char * 3,))
+                    raise self._blocked
+                if end == len(buf) and not final:
+                    break
+                out.append(buf[i:end])
+                i = end
+                continue
+            out.append(char)
+            i += 1
+        self._pending = buf[i:]
+        released = "".join(out)
+        self._text += released
+        return released

llm_stream_guards/_leak.py

@@ -0,0 +1,92 @@
+import re
+from collections.abc import Mapping
+
+from ._stream import Blocked
+
+_WORD = re.compile(r"\w+")
+
+
+def _words(text: str) -> list[str]:
+    return _WORD.findall(text.casefold())
+
+
+class LeakGuard:
+    """
+    Catches a reply that quotes a protected text word for word.
+
+    Each protected text becomes the set of its n-word runs (shingles), after casefolding and dropping punctuation and
+    Markdown, and a reply leaks when any n consecutive words of it are one of them. `protected` maps a name to a text,
+    or to `(text, n)` to give that text its own n; the others use `words`. The default of 8 is long enough that an
+    ordinary reply does not repeat 8 words of a system prompt in a row, and short enough that a quoted sentence is
+    caught. A text with fewer than n words has no run to quote and is refused. A guard holds no state about a reply, so
+    one built for a system prompt can serve every request.
+    """
+
+    def __init__(self, protected: Mapping[str, str | tuple[str, int]], *, words: int = 8):
+        self._shingles: list[tuple[str, int, set[tuple[str, ...]]]] = []
+        for name, value in protected.items():
+            text, n = value if isinstance(value, tuple) else (value, words)
+            if n < 1:
+                raise ValueError(f"{name!r}: the run length must be at least 1, got {n}")
+            found = _words(text)
+            if len(found) < n:
+                # Such a text has no run to quote, and the guard would let a reply repeat all of it.
+                raise ValueError(
+                    f"{name!r}: the text has {len(found)} word(s), fewer than the run length {n}; "
+                    f"give it its own, as ({name!r}: (text, {max(len(found), 1)})), or leave it out"
+                )
+            self._shingles.append((name, n, {tuple(found[i : i + n]) for i in range(len(found) - n + 1)}))
+        self._longest = max((n for _, n, _ in self._shingles), default=0)
+
+    def match(self, text: str) -> str | None:
+        """The name of the first protected text that `text` quotes, or None."""
+        return self._match(_words(text), 0)
+
+    def leaked(self, text: str) -> bool:
+        return self.match(text) is not None
+
+    def _match(self, found: list[str], first: int) -> str | None:
+        """The name of the first protected text quoted by a run of `found` that ends at word `first` or later."""
+        for name, n, shingles in self._shingles:
+            if any(tuple(found[i : i + n]) in shingles for i in range(max(0, first - n + 1), len(found) - n + 1)):
+                return name
+        return None
+
+
+class LeakStream:
+    """
+    Blocks a reply as soon as the text so far quotes a protected text. Holds nothing back, so up to n-1 words of a
+    quotation are shown before the run that completes it is caught.
+    """
+
+    def __init__(self, guard: LeakGuard):
+        self._guard = guard
+        self._text = ""
+        self._blocked: Blocked | None = None
+        # The last words of the reply that a run could still start in, and the word being written, which may still grow.
+        self._words: list[str] = []
+        self._open = ""
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    def feed(self, delta: str) -> str:
+        if self._blocked:
+            raise self._blocked
+        self._text += delta
+        # Casefolding works one character at a time, so the words of the pieces joined are those of the text.
+        written = self._open + delta.casefold()
+        found = _WORD.findall(written)
+        # Only runs that end in a word that is new or has grown can be new: the others were judged as they arrived.
+        if (name := self._guard._match([*self._words, *found], len(self._words))) is not None:
+            self._blocked = Blocked("leak", (name,))
+            raise self._blocked
+        self._open = found.pop() if found and _WORD.match(written[-1]) else ""
+        self._words = [*self._words, *found][max(0, len(self._words) + len(found) - self._guard._longest + 1) :]
+        return delta
+
+    def finish(self) -> str:
+        if self._blocked:
+            raise self._blocked
+        return ""

llm_stream_guards/_links.py

@@ -0,0 +1,358 @@
+import re
+from collections.abc import Collection, Iterable
+from urllib.parse import urlparse
+
+from ._stream import next_anchor
+
+REMOVED = "[removed]"
+
+# A URL inside inline code is a placeholder ("set the callback to `https://yourapp.example/hook`"), not a link anyone
+# follows, and cutting it out would leave a hole mid-sentence. It is held aside while links are stripped. A span ends
+# at a run of backticks as long as the one that opened it, as in Markdown: "`[a](https://evil.example)``" is a link.
+# A backslash escapes a backtick or a backslash: "\`[a](https://evil.example)\`" opens no span, and is a link.
+_CODE_SPAN = re.compile(r"\\[\\`]|(?<!`)(`+)(?!`)[^`\n]*\1(?!`)")
+_HOLD_OPEN, _HOLD_CLOSE = chr(0xE000), chr(0xE001)
+_HELD = re.compile(f"{_HOLD_OPEN}(\\d+){_HOLD_CLOSE}")
+# Full-width and ideographic punctuation ends a URL, and so does a held code span: a backtick did before it was held.
+_URL_CHARS = r"(?:[^\s<>()\[\]\"'`。、，" + _HOLD_OPEN + _HOLD_CLOSE + r"]|\([^\s<>()\[\]`]*\))"  # noqa: RUF001
+# A link or an image, with a URL that may hold balanced parentheses; a <url> autolink; a reference definition line. The
+# last two take any scheme or a `//host`: `_host_of` decides which of them is a web link.
+_MARKDOWN_LINK = re.compile(r"(!?)\[([^\]\n]*)\]\(\s*<?((?:[^()\s>]|\([^()\s]*\))*)>?[^)]*\)")
+_AUTOLINK = re.compile(r"<((?:[a-z][a-z0-9+.\-]{1,31}:|www\.)[^\s<>]+)>", re.IGNORECASE)
+_LINK_DEFINITION = re.compile(r"^([ \t]*\[[^\]\n]+\]:[ \t]*)(?:<([^\s<>]+)>|(\S+))[ \t]*$", re.MULTILINE)
+_BARE_URL = re.compile(r"[ \t]?(?:https?://|www\.)" + _URL_CHARS + "+", re.IGNORECASE)
+_TRAILING_PUNCTUATION = ".,;:!?。、，"  # noqa: RUF001
+# What Markdown reads as other characters in a link destination: an HTML character reference (`&#104;ttps://`) or a
+# backslash before punctuation (`https\://`). Before the first `/`, `?` or `#` (not the `#` of a reference) they can
+# hide the scheme or a leading `//`, so the URL reads as a relative one here and as a web link to the reader.
+# A browser drops these from the start of a URL, so "\x01//evil.example" is a link to evil.example.
+_C0_OR_SPACE = "".join(map(chr, range(0x21)))
+_DESTINATION_HEAD = re.compile(r"[/?]|(?<!&)#")
+_CHARACTER_REFERENCE = re.compile(r"&(?:#[0-9]{1,7}|#[xX][0-9a-fA-F]{1,6}|[A-Za-z][A-Za-z0-9]{1,31});")
+_DISGUISED_HEAD = re.compile(_CHARACTER_REFERENCE.pattern + r"|\\[!-/:-@\[-`{-~]")
+
+
+def _host_of(url: str) -> str | None:
+    """
+    The lowercase host of an absolute web URL, "" for one with no usable host or a script scheme, None for
+    anything else (a relative path, a fragment, a mailto link).
+    """
+    # A scheme or a leading "//" written as a character reference or an escape is not one this function can read.
+    stripped = url.strip().lstrip(_C0_OR_SPACE)
+    head = _DESTINATION_HEAD.split(stripped, maxsplit=1)[0]
+    if _DISGUISED_HEAD.search(head):
+        return ""
+    # A character reference in the host can hide the "/", "?" or "#" that ends it: "https://evil.example&sol;@acme.com".
+    if stripped.startswith("//", len(head)):
+        authority = _DESTINATION_HEAD.split(stripped[len(head) + 2 :], maxsplit=1)[0]
+        if _CHARACTER_REFERENCE.search(authority):
+            return ""
+    # Browsers read a backslash as a slash in a web URL: "https://evil.example\@acme.example" is evil.example.
+    candidate = stripped.replace("\\", "/")
+    if candidate.lower().startswith("www."):
+        candidate = "//" + candidate
+    try:
+        parsed = urlparse(candidate)
+        host = parsed.hostname
+    except ValueError:
+        return ""
+    if parsed.scheme.lower() in ("http", "https") or candidate.startswith("//"):
+        return (host or "").removeprefix("www.")
+    if parsed.scheme.lower() in ("javascript", "data", "vbscript", "file"):
+        return ""
+    return None
+
+
+def hosts_of(urls: Iterable[str]) -> set[str]:
+    """The hosts of `urls`, in the form `strip_untrusted_links` compares against: lowercase, without `www.`."""
+    return {host for url in urls if (host := _host_of(url))}
+
+
+def strip_untrusted_links(text: str, allowed_hosts: Collection[str]) -> str:
+    """
+    `text` without the web links whose host is not in `allowed_hosts` (see `hosts_of`).
+
+    `[text](url)` and `![alt](url)` become their text; a bare URL, a `<url>` autolink or a reference definition
+    becomes its host in inline code, so the sentence around it still reads. A link with no usable host, or a
+    `javascript:` one, is dropped. Relative links, fragments, mailto links and URLs inside inline code stay. A host
+    matches exactly: allowing `example.com` does not allow `docs.example.com`.
+    """
+    held: list[str] = []
+
+    def hold(match: re.Match[str]) -> str:
+        if match.group(1) is None:
+            return match.group(0)
+        held.append(match.group(0))
+        return f"{_HOLD_OPEN}{len(held) - 1}{_HOLD_CLOSE}"
+
+    def untrusted(url: str) -> str | None:
+        """The host to show instead of `url`, "" to show nothing, None when the link may stay."""
+        host = _host_of(url)
+        # A held code span inside a URL would come back inside the host's own code span.
+        return None if host is None or host in allowed_hosts else _HELD.sub("", host)
+
+    def shown(host: str) -> str:
+        return f"`{host}`" if host else ""
+
+    def link(match: re.Match[str]) -> str:
+        _, label, url = match.groups()
+        host = untrusted(url)
+        if host is None:
+            return match.group(0)
+        return label if label.strip() else shown(host)
+
+    def autolink(match: re.Match[str]) -> str:
+        host = untrusted(match.group(1))
+        return match.group(0) if host is None else shown(host)
+
+    def definition(match: re.Match[str]) -> str:
+        host = untrusted(match.group(2) or match.group(3))
+        return match.group(0) if host is None else match.group(1) + shown(host)
+
+    def bare(match: re.Match[str]) -> str:
+        found = match.group(0)
+        lead = found[: len(found) - len(found.lstrip(" \t"))]
+        url = found.strip()
+        trailing = ""
+        while url and url[-1] in _TRAILING_PUNCTUATION:
+            trailing = url[-1] + trailing
+            url = url[:-1]
+        host = untrusted(url)
+        if host is None:
+            return found
+        return (lead + shown(host) if host else "") + trailing
+
+    # The placeholder characters are private-use ones; a reply that holds them would be handed other text's spans.
+    cleaned = _CODE_SPAN.sub(hold, text.replace(_HOLD_OPEN, "").replace(_HOLD_CLOSE, ""))
+    cleaned = _LINK_DEFINITION.sub(definition, cleaned)
+    cleaned = _AUTOLINK.sub(autolink, cleaned)
+    cleaned = _MARKDOWN_LINK.sub(link, cleaned)
+    cleaned = _BARE_URL.sub(bare, cleaned)
+
+    def restore(match: re.Match[str]) -> str:
+        # A host shown in inline code next to a span would join their backtick runs, and a longer run closes nothing:
+        # the span's text would then be read as Markdown, links included.
+        span = held[int(match.group(1))]
+        before, after = cleaned[match.start() - 1 : match.start()], cleaned[match.end() : match.end() + 1]
+        return (" " if before == "`" else "") + span + (" " if after == "`" else "")
+
+    return _HELD.sub(restore, cleaned)
+
+
+# An address as it reads in prose; a trailing full stop is not part of it, because the domain must end in a label.
+_EMAIL = r"[\w.%+\-]+@[\w\-]+(?:\.[\w\-]+)+"
+_EMAIL_FIND = re.compile(_EMAIL)
+_MAILTO_LINK = re.compile(r"\[([^\]]*)\]\(\s*mailto:([^)]*)\)", re.IGNORECASE)
+_EMAIL_IN_TEXT = re.compile(r"<(?:mailto:)?(" + _EMAIL + r")>|(?:mailto:)?(" + _EMAIL + r")", re.IGNORECASE)
+
+
+def emails_in(*texts: str | None) -> set[str]:
+    """The email addresses written in `texts`, lowercased: the grounded set for `without_ungrounded_emails`."""
+    return {found.lower() for text in texts for found in _EMAIL_FIND.findall(text or "")}
+
+
+def without_ungrounded_emails(text: str, grounded: Collection[str], *, replacement: str = REMOVED) -> str:
+    """
+    `text` with every email address not in `grounded` (lowercase, see `emails_in`) replaced by `replacement`, and
+    a `mailto:` link to one replaced by its text. A model with no address to give writes a plausible one from a
+    company's name, and someone then writes to it.
+    """
+
+    def mailto(match: re.Match[str]) -> str:
+        found = _EMAIL_FIND.search(match.group(2))
+        if found is None or found.group(0).lower() in grounded:
+            return match.group(0)
+        return match.group(1).strip() or replacement
+
+    def address(match: re.Match[str]) -> str:
+        found = match.group(1) or match.group(2)
+        return match.group(0) if found.lower() in grounded else replacement
+
+    return _EMAIL_IN_TEXT.sub(address, _MAILTO_LINK.sub(mailto, text))
+
+
+# A telephone number as it reads in prose, on one line: an optional "+", digits grouped by spaces, dots, hyphens or
+# brackets.
+# Counted by its digits, so a year, a date or a figure is not one: at least 9 digits, or 8 after a "+".
+_PHONE = re.compile(r"(?<![\w.+])\(?\+?\d(?:[\d().-]|[^\S\n]){5,22}\d(?!\w)")
+_DATE = re.compile(r"(?<!\d)\d{4}-\d{1,2}-\d{1,2}(?!\d)")
+_IPV4 = re.compile(r"\d{1,3}(?:\.\d{1,3}){3}")
+_MIN_PHONE_DIGITS = 9
+# A number written without its country code, or with a trunk zero, is the same number when this many digits agree.
+_MIN_SHARED_PHONE_DIGITS = 7
+
+
+def _phone_digits(found: str) -> str | None:
+    """The digits of a written number when it reads as a telephone number, else None."""
+    if _DATE.search(found) or _IPV4.fullmatch(found):
+        return None
+    digits = re.sub(r"\D", "", found)
+    return digits if len(digits) >= _MIN_PHONE_DIGITS - found.startswith("+") else None
+
+
+def phones_in(*texts: str | None) -> set[str]:
+    """The telephone numbers written in `texts`, as digits only: the grounded set for `without_ungrounded_phones`."""
+    return {digits for text in texts for found in _PHONE.findall(text or "") if (digits := _phone_digits(found))}
+
+
+def without_ungrounded_phones(text: str, grounded: Collection[str], *, replacement: str = REMOVED) -> str:
+    """
+    `text` with every telephone number not in `grounded` (digits, see `phones_in`) replaced by `replacement`.
+    Numbers compare by their digits, and one that is the other without its country code, or with a trunk zero, is
+    the same number: `020 7946 0001` is grounded by `+44 20 7946 0001`.
+    """
+
+    def known(digits: str) -> bool:
+        national = digits.lstrip("0")
+        for other in grounded:
+            theirs = other.lstrip("0")
+            if digits == other or (
+                min(len(national), len(theirs)) >= _MIN_SHARED_PHONE_DIGITS
+                and (theirs.endswith(national) or national.endswith(theirs))
+            ):
+                return True
+        return False
+
+    def phone(match: re.Match[str]) -> str:
+        digits = _phone_digits(match.group(0))
+        return match.group(0) if digits is None or known(digits) else replacement
+
+    return _PHONE.sub(phone, text)
+
+
+# A link still being written: a URL running to the end of the text, the start of a scheme, or a Markdown link whose
+# brackets or parentheses are not closed yet. Held that long only, so a stray "[" in prose does not stall the reply.
+_OPEN_URL = re.compile(r"[ \t]?<?(?:https?://|www\.)[^\s<>()\[\]\"'`。、，]*\Z", re.IGNORECASE)  # noqa: RUF001
+_PARTIAL_SCHEME = re.compile(r"(?<!\w)(?:<|<?(?:h(?:t(?:t(?:ps?(?::/?)?)?)?)?|ww?w?))\Z", re.IGNORECASE)
+_MAX_HELD_LINK_CHARS = 300
+# Link text is short: a "[" with no "]" this far on is prose.
+_MAX_HELD_LINK_TEXT_CHARS = 80
+# The word being written, while addresses are checked: "hello" is shown once no "@" has followed it. Longer than any
+# address, so a long unbroken string is not held.
+_OPEN_WORD = re.compile(r"<?[\w.%+\-@:]*\Z")
+_MAX_HELD_WORD_CHARS = 120
+# A number being written ("+44 7700 9"), held from its bracket or plus sign so no part of one is shown.
+_OPEN_NUMBER = re.compile(r"\(?\+?(?:\d(?:[\d().-]|[^\S\n])*)?\Z")
+_MAX_HELD_NUMBER_CHARS = 30
+
+
+def _open_link_start(text: str) -> int:
+    """Where a link still being written starts in `text`, or len(text) when none is."""
+    cut = len(text)
+    # A "!" that ends the text may open an image and goes with it: alone, it would stay when the image is cut down.
+    if text.endswith("!"):
+        cut -= 1
+    for pattern in (_OPEN_URL, _PARTIAL_SCHEME):
+        if (match := pattern.search(text)) is not None:
+            cut = min(cut, match.start())
+    bracket = text.rfind("[")
+    if bracket != -1:
+        rest = text[bracket:]
+        close = rest.find("]")
+        after = rest[close + 1 :] if close != -1 else ""
+        unfinished = close == -1 or after == "" or (after.startswith("(") and ")" not in after)
+        limit = _MAX_HELD_LINK_TEXT_CHARS if close == -1 else _MAX_HELD_LINK_CHARS
+        if unfinished and "\n" not in rest and len(rest) <= limit:
+            # An image's "!" goes with it: shown alone, it would stay when the image is cut down to its text.
+            cut = min(cut, bracket - 1 if text[bracket - 1 : bracket] == "!" else bracket)
+    return cut
+
+
+def _held_from(pattern: re.Pattern[str], text: str, limit: int) -> int:
+    match = pattern.search(text)
+    return match.start() if match is not None and len(match.group(0)) <= limit else len(text)
+
+
+class LinkStream:
+    """
+    `strip_untrusted_links` while the reply streams, and with `emails` or `phones` (a grounded set, empty for
+    none) `without_ungrounded_emails` and `without_ungrounded_phones` too. Text is let through once no link, word or
+    number in it is still being written, already cleaned, so a URL, address or number the finished reply would lose
+    is never shown.
+
+    Cleaning a longer text can, rarely, change what an earlier piece already showed: a `[` let through as prose after
+    80 characters with no `]`, that then turns out to open a link to an untrusted host. The stream then goes on from
+    where the two agree, and `text` is the reply as it should read: after `finish`, show `text` in place of what was
+    sent if the two differ.
+
+    Each piece is cleaned together with the last 320 to 640 characters of the reply, not the whole of it, so that the
+    time a reply takes grows with its length and not with its square. `finish` cleans the whole reply once.
+    """
+
+    def __init__(
+        self,
+        allowed_hosts: Collection[str],
+        *,
+        emails: Collection[str] | None = None,
+        phones: Collection[str] | None = None,
+        replacement: str = REMOVED,
+    ):
+        self._allowed = allowed_hosts
+        self._emails = emails
+        self._phones = phones
+        self._replacement = replacement
+        self._raw = ""
+        # The reply is `_prefix` (cleaned, settled) then `_window` (cleaned from `_raw[_anchor:]`, as last let through).
+        self._anchor = 0
+        self._prefix = ""
+        self._window = ""
+
+    @property
+    def text(self) -> str:
+        return self._prefix + self._window
+
+    def feed(self, delta: str) -> str:
+        self._raw += delta
+        window = self._raw[self._anchor :]
+        cut = _open_link_start(window)
+        if self._emails is not None:
+            cut = min(cut, _held_from(_OPEN_WORD, window, _MAX_HELD_WORD_CHARS))
+        if self._phones is not None:
+            cut = min(cut, _held_from(_OPEN_NUMBER, window, _MAX_HELD_NUMBER_CHARS))
+        return self._release(self._anchor + cut, final=False)
+
+    def finish(self) -> str:
+        return self._release(len(self._raw), final=True)
+
+    def _clean(self, raw: str) -> str:
+        cleaned = strip_untrusted_links(raw, self._allowed)
+        if self._emails is not None:
+            cleaned = without_ungrounded_emails(cleaned, self._emails, replacement=self._replacement)
+        if self._phones is not None:
+            cleaned = without_ungrounded_phones(cleaned, self._phones, replacement=self._replacement)
+        return cleaned
+
+    def _release(self, upto: int, *, final: bool) -> str:
+        # The window is cleaned on its own; the finished reply, once, whole.
+        cleaned, shown = (
+            (self._clean(self._raw), self.text)
+            if final
+            else (self._clean(self._raw[self._anchor : upto]), self._window)
+        )
+        if cleaned.startswith(shown):
+            shared = len(shown)
+        elif shown.startswith(cleaned):
+            # A link that opened in text already let through is being held: nothing more goes out until it closes.
+            # Once the reply has ended there is nothing left to wait for, and `text` is the cleaned reply.
+            if final:
+                self._prefix, self._window = "", cleaned
+            return ""
+        else:
+            shared = next(i for i, (new, old) in enumerate(zip(cleaned, shown, strict=False)) if new != old)
+        if final:
+            self._prefix, self._window = "", cleaned
+        else:
+            self._window = cleaned
+            self._advance(upto)
+        return cleaned[shared:]
+
+    def _advance(self, upto: int) -> None:
+        """Move the window on once it is long, if no link or address straddles where it would start."""
+        anchor = next_anchor(self._raw, self._anchor, upto, upto)
+        if anchor == self._anchor:
+            return
+        head = self._clean(self._raw[self._anchor : anchor])
+        if self._window.startswith(head):
+            self._prefix += head
+            self._anchor = anchor
+            self._window = self._clean(self._raw[anchor:upto])

llm_stream_guards/_stream.py

@@ -0,0 +1,76 @@
+from typing import Protocol
+
+# How far behind the end of a streaming reply a guard looks. What it has already let through is settled, so each piece
+# is judged with this many characters of context, not the whole reply, and the whole reply is judged once, at `finish`.
+WINDOW = 320
+# Where a window may start: after a line break, a space or a stop no URL runs across. Never inside a word or a URL.
+_BREAKS = "\n \t。、，"  # noqa: RUF001
+
+
+def next_anchor(text: str, anchor: int, end: int, ceiling: int) -> int:
+    """
+    Where the window over `text[:end]` starts, given where it started (`anchor`). It moves only once the window is twice
+    `WINDOW` long, and then to a break at least `WINDOW` behind `end`, and never past `ceiling` (what is still held).
+    """
+    if end - anchor <= 2 * WINDOW:
+        return anchor
+    stop = min(end - WINDOW, ceiling)
+    after = max((text.rfind(char, anchor, stop) for char in _BREAKS), default=-1)
+    return after + 1 if after >= anchor else anchor
+
+
+class Blocked(Exception):
+    """
+    A streaming guard refused the reply: stop reading the model and replace what was shown.
+
+    `reason` names the guard (`"code"`, `"leak"`, `"amount"`) and `found` says what it caught: the protected text's
+    name for a leak, the figures for an amount. A guard that has raised raises the same exception on every later call.
+    """
+
+    def __init__(self, reason: str, found: tuple[str, ...] = ()):
+        super().__init__(f"{reason}: {', '.join(found)}" if found else reason)
+        self.reason = reason
+        self.found = found
+
+    def __reduce__(self) -> tuple[type["Blocked"], tuple[str, tuple[str, ...]]]:
+        return type(self), (self.reason, self.found)
+
+
+class StreamGuard(Protocol):
+    """
+    What every streaming guard does: `feed` takes the next piece of the reply and returns what may be shown now,
+    `finish` returns what was held back once the reply has ended, and either may raise `Blocked`.
+    """
+
+    def feed(self, delta: str) -> str: ...
+
+    def finish(self) -> str: ...
+
+    @property
+    def text(self) -> str:
+        """Everything let through so far, as it should finally read."""
+        ...
+
+
+class Chain:
+    """Guards run in order, each fed what the one before it let through. A chain is a guard itself."""
+
+    def __init__(self, *guards: StreamGuard):
+        if not guards:
+            raise ValueError("a chain needs at least one guard")
+        self._guards = guards
+
+    def feed(self, delta: str) -> str:
+        for guard in self._guards:
+            delta = guard.feed(delta)
+        return delta
+
+    def finish(self) -> str:
+        tail = ""
+        for guard in self._guards:
+            tail = guard.feed(tail) + guard.finish()
+        return tail
+
+    @property
+    def text(self) -> str:
+        return self._guards[-1].text

llm_stream_guards-0.1.0.dist-info/METADATA

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: llm-stream-guards
+Version: 0.1.0
+Summary: Deterministic output guards for a streamed LLM reply: untrusted links, made-up emails, phone numbers and prices, quoted system prompts and code, stopped before they reach the screen.
+Project-URL: Homepage, https://github.com/sansanth/llm-stream-guards
+Project-URL: Issues, https://github.com/sansanth/llm-stream-guards/issues
+Project-URL: Changelog, https://github.com/sansanth/llm-stream-guards/blob/main/CHANGELOG.md
+Author-email: Sandhu Santhakumar <code@sandhu.sh>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatbot,guardrails,llm,output-filter,prompt-injection,security,streaming
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Text Processing :: Filters
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# llm-stream-guards
+
+[![CI](https://github.com/sansanth/llm-stream-guards/actions/workflows/python.yml/badge.svg)](https://github.com/sansanth/llm-stream-guards/actions/workflows/python.yml)
+[![PyPI](https://img.shields.io/pypi/v/llm-stream-guards)](https://pypi.org/project/llm-stream-guards/)
+[![Python versions](https://img.shields.io/pypi/pyversions/llm-stream-guards)](https://pypi.org/project/llm-stream-guards/)
+[![License](https://img.shields.io/pypi/l/llm-stream-guards)](https://github.com/sansanth/llm-stream-guards/blob/main/LICENSE)
+
+Output guards for an LLM reply that streams to a user. Prompt injection can make a model print a phishing link, a made-up price or phone number, or quote its system prompt, and by the time you check the finished reply the user has read it. These guards work on the reply as it streams: each piece is either shown now, held back until it can be judged (a half-written link, a number that may still grow), or the reply is stopped before the piece that breaks a rule reaches the screen.
+
+Plain string logic: no model call, no ML, no dependencies. Every guard can only make a reply more restrictive. The
+same guards are on npm as [`llm-stream-guards`](https://www.npmjs.com/package/llm-stream-guards), and the two packages
+pass the same test cases.
+
+```sh
+pip install llm-stream-guards
+```
+
+## What it guards
+
+| Guard | Stops | While streaming |
+|---|---|---|
+| `LinkStream`, `strip_untrusted_links` | A link to a host you did not supply. `[text](url)` becomes its text; a bare URL becomes its host in inline code (`` `evil.example` ``), so the sentence still reads. | Holds a link from its first character (`h`, `www`, an unclosed `[...](`) until it can be checked. |
+| `LinkStream(emails=...)`, `without_ungrounded_emails` | An email address that none of your sources holds. | Holds the word being written until it ends. |
+| `LinkStream(phones=...)`, `without_ungrounded_phones` | A telephone number that none of your sources holds. `020 7946 0001` and `+44 20 7946 0001` are the same number. | Holds a number from its `+`, `(` or first digit. |
+| `AmountStream`, `unsupported_amounts` | A price or an effort estimate none of your sources states: `$120`, `INR 50,000`, `40 euros`, `300 engineering hours`, `$40 to $65`, and `60k` or `120 per hour` near a cost word. `$2M` and `$2,000,000` compare equal, and so do `$1,200` and `$1,200.00`. A range is judged as a range, whether it is priced by a symbol (`$40 to $65`), a code (`USD 40 to 65`) or a name (`40 to 65 euros`). | Blocks before the piece that completes the figure. Holds a figure that may still grow (`$5` before `00`), and an unsourced `60k` or `120 per hour` until the 120 characters after it show no cost word. |
+| `LeakStream`, `LeakGuard` | A reply that quotes a protected text (your system prompt) 8 words in a row, ignoring case, punctuation and Markdown. | Blocks as soon as the run completes. |
+| `CodeStream`, `contains_code_deliverable` | A reply that hands over code: a fence, an indented block, SQL, a shell line, markup, a definition or an import. Prose that uses the words ("Import the data first") is not code. | Blocks at the first fence, so you stop paying for the rest. |
+
+Links, emails and phone numbers are rewritten and the reply goes on. A code fence, a quotation or an unsourced figure means the reply as a whole is wrong: the guard raises `Blocked`, and you replace what was shown.
+
+## Use it
+
+```python
+from llm_stream_guards import (
+    AmountStream,
+    Blocked,
+    Chain,
+    CodeStream,
+    LeakGuard,
+    LeakStream,
+    LinkStream,
+    emails_in,
+    hosts_of,
+    numbers_in,
+    phones_in,
+)
+
+# Built once: it holds nothing about a reply.
+leaks = LeakGuard({"system prompt": SYSTEM_PROMPT})
+
+
+def guarded(deltas, sources, user_messages):
+    texts = [source.text for source in sources]
+    guards = Chain(
+        CodeStream(),
+        LeakStream(leaks),
+        AmountStream(numbers_in(*texts)),
+        LinkStream(
+            hosts_of(source.url for source in sources),
+            emails=emails_in(*texts, *user_messages),
+            phones=phones_in(*texts, *user_messages),
+            replacement="our team",
+        ),
+    )
+    for delta in deltas:
+        if shown := guards.feed(delta):
+            yield shown
+    if tail := guards.finish():
+        yield tail
+
+
+stream = client.chat.completions.create(..., stream=True)
+deltas = (chunk.choices[0].delta.content or "" for chunk in stream)
+try:
+    for piece in guarded(deltas, sources, user_messages):
+        send(piece)
+except Blocked as blocked:
+    stream.close()  # stop paying for the rest
+    log.warning("reply blocked: %s", blocked)  # e.g. "amount: $80,000"
+    replace_shown_reply("Our team will follow up with a quote.")
+```
+
+A grounded set is what the reply may repeat. For links, emails and phone numbers that is the sources you retrieved for this reply, the user's own messages and your own contact details. Never the model's earlier replies: that would ground what it made up. For amounts, leave the user's messages out, or "you charge 5k, right?" lets the reply confirm it.
+
+Order the chain as above: the guards that block judge the model's own text, and `LinkStream` rewrites what they let through.
+
+Not streaming? Call the functions on the finished text:
+
+```python
+reply = strip_untrusted_links(reply, hosts_of(urls))
+reply = without_ungrounded_emails(reply, emails_in(*texts), replacement="our team")
+if unsupported_amounts(reply, numbers_in(*texts)) or leaks.leaked(reply) or contains_code_deliverable(reply):
+    reply = fallback
+```
+
+## API
+
+### Streaming guards
+
+Every streaming guard has the same three members, and a `Chain` of them is one too (`StreamGuard` is the protocol):
+
+- `feed(delta) -> str`: takes the next piece of the reply and returns what may be shown now, possibly `""`.
+- `finish() -> str`: returns what was held back, once the model has stopped.
+- `text`: everything let through so far, as it should finally read. After `finish`, the reply to store.
+
+`feed` and `finish` raise `Blocked` when the reply must not go on. A guard that has raised raises the same exception on every later call.
+
+| Name | Signature |
+|---|---|
+| `Chain` | `Chain(*guards)`: each guard is fed what the one before it let through. |
+| `CodeStream` | `CodeStream(*, deliverable=True)`: blocks at the first fence (three backticks, or three tildes opening a line). With `deliverable`, `finish` also blocks a finished reply that `contains_code_deliverable` flags. |
+| `LeakStream` | `LeakStream(guard: LeakGuard)`: blocks once the text so far quotes a protected text. Holds nothing back. |
+| `AmountStream` | `AmountStream(grounded, *, locale=ENGLISH)`: blocks an unsourced figure before it is shown; holds what may still grow. `finish` judges the finished text. |
+| `LinkStream` | `LinkStream(allowed_hosts, *, emails=None, phones=None, replacement="[removed]")`: removes untrusted links, and with `emails` or `phones` (a grounded set, empty for none) ungrounded addresses and numbers. |
+| `Blocked` | The exception. `reason` is `"code"`, `"leak"` or `"amount"`; `found` is what was caught: the fence, the protected text's name, or the figures. |
+
+### Finished text
+
+| Name | Signature |
+|---|---|
+| `strip_untrusted_links` | `(text, allowed_hosts) -> str` |
+| `hosts_of` | `(urls) -> set[str]`: the hosts `strip_untrusted_links` compares against: lowercase, without `www.`. Matched exactly: `example.com` does not allow `docs.example.com`. |
+| `without_ungrounded_emails` | `(text, grounded, *, replacement="[removed]") -> str`: a `mailto:` link to an ungrounded address becomes its text. |
+| `emails_in` | `(*texts) -> set[str]`: the addresses in `texts`, lowercased. |
+| `without_ungrounded_phones` | `(text, grounded, *, replacement="[removed]") -> str` |
+| `phones_in` | `(*texts) -> set[str]`: the telephone numbers in `texts`, as digits. |
+| `unsupported_amounts` | `(text, grounded, *, complete=True, locale=ENGLISH) -> list[str]`: the unsourced figures, as written. With `complete=False` a figure that ends the text is not judged yet. |
+| `numbers_in` | `(*texts, locale=ENGLISH) -> set[str]`: every number and range in `texts`, in the form `unsupported_amounts` compares against. |
+| `LeakGuard` | `LeakGuard(protected, *, words=8)`: `protected` maps a name to a text, or to `(text, n)` for its own run length. A text with fewer than `n` words is refused with a `ValueError`: it has no run to quote. `match(text)` returns the name of the first text quoted, or `None`; `leaked(text)` is `match(text) is not None`. |
+| `contains_code_deliverable` | `(text) -> bool` |
+
+### `Locale`
+
+The amount guard's words and symbols: currency symbols, codes, prefixes (`Rs.`) and names, magnitudes (`k`, `million`, `lakh`, `crore`), cost words, and the regex fragments that make a number effort (`person-days`) or a rate (`per hour`). `ENGLISH` is the default. Change part of it with `dataclasses.replace`, or build your own:
+
+```python
+from dataclasses import replace
+from llm_stream_guards import ENGLISH, Locale
+
+nordic = replace(ENGLISH, currency_codes=(*ENGLISH.currency_codes, "nok", "sek", "dkk"))
+german = Locale(
+    currency_names=("euro",),
+    magnitudes={"tsd": 1_000, "mio": 1_000_000, "mrd": 1_000_000_000},
+    cost_words=("kosten", "preis", "budget", "angebot"),
+    effort=r"personentage\b",
+    rate=r"\s*(?:pro|je)\s*stunde\b",
+    range_words=("bis",),
+)
+AmountStream(grounded, locale=german)
+```
+
+An empty list matches nothing. The fields are documented on the class.
+
+## Limits
+
+- **Quotation, not paraphrase.** The leak guard catches a protected text repeated word for word, not one retold. Up to 7 words of a quotation are shown before the eighth completes the run. A protected text shorter than the run length is refused, not ignored: give it its own, `(text, 3)`. Leave out of the protected text any phrase the model is told to say, or saying it counts as a leak.
+- **Text without word boundaries is not covered.** Chinese, Japanese or Thai reduces to very few words, so the leak guard sees almost nothing to compare.
+- **The default patterns read English.** A price written in another language passes `ENGLISH`; give it a `Locale`. A figure in words ("forty thousand dollars") is not caught in any locale. Numbers are read with `.` as the decimal point.
+- **Telephone numbers are counted by their digits**: 9 or more, or 8 after a `+`, on one line. A shorter number, or one written in words, is not checked. A date such as `2026-10-07` is never a number, but a run of other numbers that adds up to that many digits (`2019 2020 2021`) is, and so is an identifier of that length (`Order 12345678901`). A dotted address such as `192.168.100.100` is not a number.
+- **Only web links are checked.** A link is one to `http`, `https`, `www.` or `//host`, and one with a `javascript:`, `data:`, `vbscript:` or `file:` scheme goes too. An `ftp:` link, or one to an app scheme (`intent:`, `slack:`), passes.
+- **Holding back costs latency.** An unsourced `60k` or `120 per hour` waits for the next 120 characters; an unclosed `[` waits up to 80 characters and an unclosed link up to 300. The rest of the reply waits behind it.
+- **Time is spent on the end of the reply.** Each piece is checked together with the last 320 to 640 characters, not the whole reply, so the time a reply takes grows with its length, about 0.3 milliseconds a piece for the chain above (a few times that if your pieces are single characters). The whole reply is checked once more when it ends. A link whose text runs past 300 characters, or a figure with more than 300 characters of white space inside it, is therefore judged only then.
+- **What was shown can differ from `text`.** In a rare case (a `[` let through as prose that then opens a link to an untrusted host) cleaning the longer text changes text already shown. The stream goes on, and after `finish` you show `text` in its place.
+- **The code detector prefers false positives.** A reply with a SQL statement or a block opener with an indented body counts as code. Pass `deliverable=False` to `CodeStream` to block on fences only.
+- **A backstop, not a judge.** These checks see shapes, not meaning: they are what still holds when the prompt, and any model-based check, did not.
+
+## Development
+
+See [CONTRIBUTING.md](https://github.com/sansanth/llm-stream-guards/blob/main/CONTRIBUTING.md). In short:
+
+```sh
+cd python
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run mypy
+```
+
+## License
+
+MIT

llm_stream_guards-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+llm_stream_guards/__init__.py,sha256=n718TYSdKrPe-b0P6TE9YWEPgAVtKO86vHfWofjw-Wc,943
+llm_stream_guards/_amounts.py,sha256=Q_cKJ2wF-dQn7dSgKlASpbKVam6o4bYulRcDKt5bTZY,17358
+llm_stream_guards/_code.py,sha256=z3BaIKie9i6HpYDC49eC09h458NHPoUTRr5K87FMxsM,5183
+llm_stream_guards/_leak.py,sha256=jlOgIBzgqI4CCC9q2aQeXLxBJ7UGUumIpxLp7I0KGpA,4124
+llm_stream_guards/_links.py,sha256=0SKBGCTjBIsBpC_KyKlC6H6dbhb-UeDVnDFX5mLBG2M,17458
+llm_stream_guards/_stream.py,sha256=psfSTxuq7bH2XAYwH0CfoK6mDtSw32NUGI4wreY3uQQ,2821
+llm_stream_guards/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+llm_stream_guards-0.1.0.dist-info/METADATA,sha256=WPM6gemrRwnI1ohbxwXVwcpxE9FFvCVB2NvPs51PsDo,13650
+llm_stream_guards-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+llm_stream_guards-0.1.0.dist-info/licenses/LICENSE,sha256=Ml3YR3qGMwvxt9lCtrt3Gr00WiNPwOYWPRC4kaU82ao,1075
+llm_stream_guards-0.1.0.dist-info/RECORD,,

llm_stream_guards-0.1.0.dist-info/WHEEL

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

llm_stream_guards-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandhu Santhakumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.