factguard 0.1.0__py3-none-any.whl

factguard/__init__.py

@@ -0,0 +1,29 @@
+"""Code computes every number, the LLM only interprets.
+
+factguard keeps LLM-written text free of numbers your code didn't compute.
+"""
+
+from .facts import RULES, Fact, Facts, Formatter
+from .guard import Result, Retry, StreamGuard, aguard, guard
+from .sentences import drop_sentences, split_sentences
+from .validate import Report, Violation, Window, validate
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RULES",
+    "Fact",
+    "Facts",
+    "Formatter",
+    "Report",
+    "Result",
+    "Retry",
+    "StreamGuard",
+    "Violation",
+    "Window",
+    "aguard",
+    "drop_sentences",
+    "guard",
+    "split_sentences",
+    "validate",
+]

factguard/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

factguard/cli.py

@@ -0,0 +1,73 @@
+"""factguard check / render, for checking recorded answers from the shell or CI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+from .facts import Facts
+from .validate import Window, validate
+
+
+def _window(value: str) -> Window:
+    try:
+        start, end = value.split(":")
+        return date.fromisoformat(start), date.fromisoformat(end)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"expected START:END as ISO dates, got {value!r}") from None
+
+
+def _read(path: str) -> str:
+    return sys.stdin.read() if path == "-" else Path(path).read_text(encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="factguard", description="Keep LLM text free of numbers code didn't compute.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check = sub.add_parser("check", help="list ungrounded numbers; exit 1 if there are any")
+    check.add_argument("draft", help="text file with {{fact:key}} placeholders, or - for stdin")
+    check.add_argument("--facts", required=True, help="JSON file with the facts")
+    check.add_argument(
+        "--window",
+        action="append",
+        type=_window,
+        default=[],
+        metavar="START:END",
+        help="a date range the answer used (repeatable)",
+    )
+    check.add_argument("--user", default="", help="the user's question; numbers in it may be repeated")
+    check.add_argument("--number-words", action="store_true", help="also flag words like 'double' or 'twenty'")
+    check.add_argument("--json", action="store_true", help="print violations as JSON")
+
+    render = sub.add_parser("render", help="replace placeholders with formatted values")
+    render.add_argument("draft", help="text file, or - for stdin")
+    render.add_argument("--facts", required=True, help="JSON file with the facts")
+
+    args = parser.parse_args(argv)
+    facts = Facts.from_records(json.loads(_read(args.facts)))
+    text = _read(args.draft)
+
+    if args.command == "render":
+        try:
+            sys.stdout.write(facts.render(text))
+        except KeyError as e:
+            print(f"factguard: {e.args[0]}", file=sys.stderr)
+            return 1
+        return 0
+
+    report = validate(text, facts, windows=args.window, user_text=args.user, number_words=args.number_words)
+    if args.json:
+        print(json.dumps([v.__dict__ for v in report.violations], indent=2))
+    else:
+        for v in report.violations:
+            line = text.count("\n", 0, v.start) + 1
+            print(f"{args.draft}:{line}: {v.kind}: `{v.token}`: {v.detail}")
+    return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

factguard/facts.py

@@ -0,0 +1,211 @@
+"""Facts are numbers computed in code. The LLM cites them by placeholder."""
+
+from __future__ import annotations
+
+import math
+import re
+from collections.abc import Callable, Iterable, Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+Kind = Literal["money", "percent", "count", "number", "ratio", "text"]
+KINDS: tuple[str, ...] = ("money", "percent", "count", "number", "ratio", "text")
+
+KEY = r"[A-Za-z0-9_.:\-]+"
+PLACEHOLDER = re.compile(r"\{\{\s*fact:(" + KEY + r")\s*\}\}")
+
+# Codes and symbols the model tends to type in front of a money placeholder.
+# Kept to real currencies so "CPA {{fact:cpa}}" is never touched.
+CURRENCIES = frozenset(
+    "USD EUR GBP INR JPY CNY AUD CAD NZD SGD HKD AED SAR CHF SEK NOK DKK ZAR BRL MXN IDR THB MYR PHP KRW".split()
+)
+_TYPED_CURRENCY = re.compile(
+    r"(?:(?<![A-Za-z])(?P<code>[A-Z]{3}|Rs\.?)\s?|(?P<symbol>[$€£₹¥])\s?)"
+    r"(?P<placeholder>\{\{\s*fact:(?P<key>" + KEY + r")\s*\}\})"
+)
+
+RULES = """\
+Every number in your answer must come from the facts listed below.
+- Cite a fact only as its placeholder, exactly as written, for example {{fact:spend}}. \
+Never type its value: code fills it in, already formatted with any currency or % sign.
+- Do not type any other digits: no totals, differences, percentages, dates, \
+durations or thresholds you worked out yourself.
+- If a number you want is not in the list, describe the change in words without a figure."""
+
+
+@dataclass(frozen=True)
+class Fact:
+    """One computed value, plus where it came from."""
+
+    key: str
+    value: float | int | str
+    kind: Kind = "number"
+    label: str = ""
+    currency: str | None = None
+    decimals: int | None = None
+    source: str | None = None
+    step: str | None = None
+
+    def __post_init__(self) -> None:
+        if not re.fullmatch(KEY, self.key):
+            raise ValueError(f"fact key {self.key!r} may only use letters, digits and _ . : -")
+        if self.kind not in KINDS:
+            raise ValueError(f"fact kind must be one of {', '.join(KINDS)}, not {self.kind!r}")
+        numeric = isinstance(self.value, (int, float)) and not isinstance(self.value, bool)
+        if self.kind != "text" and not numeric:
+            raise TypeError(f"fact {self.key!r} is {self.kind}, so its value must be a number")
+
+    @property
+    def placeholder(self) -> str:
+        return "{{fact:" + self.key + "}}"
+
+
+def _trim(s: str) -> str:
+    return s.rstrip("0").rstrip(".") if "." in s else s
+
+
+def _compact(x: float, decimals: int) -> str | None:
+    """60_240 -> "60.2K". Returns None below a thousand."""
+    for size, suffix in ((1e9, "B"), (1e6, "M"), (1e3, "K")):
+        # Check the rounded value so 999_960 becomes "1M", not "1000K".
+        if abs(x) >= 1000 and round(abs(x) / size, decimals) >= 1:
+            return _trim(f"{x / size:.{decimals}f}") + suffix
+    return None
+
+
+@dataclass(frozen=True)
+class Formatter:
+    """Turns a fact into the text that replaces its placeholder.
+
+    Percent facts are fractions: 0.034 renders as "3.4%".
+    """
+
+    currency: str | None = None
+    compact: bool = True
+
+    def __call__(self, fact: Fact) -> str:
+        if fact.kind == "text":
+            return str(fact.value)
+        x = float(fact.value)
+        if not math.isfinite(x):
+            return "n/a"
+        if fact.kind == "money":
+            return self._prefix(fact.currency or self.currency) + self._money(x, fact.decimals)
+        if fact.kind == "percent":
+            return _trim(f"{x * 100:.{1 if fact.decimals is None else fact.decimals}f}") + "%"
+        if fact.kind == "count":
+            return f"{round(x):,}"
+        if fact.kind == "ratio":
+            return _trim(f"{x:.{2 if fact.decimals is None else fact.decimals}f}") + "x"
+        if x.is_integer() and fact.decimals is None:
+            return f"{int(x):,}"
+        return _trim(f"{x:,.{2 if fact.decimals is None else fact.decimals}f}")
+
+    def _money(self, x: float, decimals: int | None) -> str:
+        if self.compact and (short := _compact(x, 1 if decimals is None else decimals)):
+            return short
+        if decimals is not None:
+            return f"{x:,.{decimals}f}"
+        if x.is_integer() or abs(x) >= 100:
+            return f"{x:,.0f}"
+        return f"{x:,.2f}"
+
+    @staticmethod
+    def _prefix(currency: str | None) -> str:
+        if not currency:
+            return ""
+        return currency + " " if currency.isalpha() else currency
+
+
+class Facts:
+    """The facts for one answer. Renders placeholders and describes facts to the LLM."""
+
+    def __init__(
+        self,
+        facts: Iterable[Fact] = (),
+        *,
+        currency: str | None = None,
+        formatter: Callable[[Fact], str] | None = None,
+    ) -> None:
+        self._facts: dict[str, Fact] = {}
+        self.formatter = formatter or Formatter(currency=currency)
+        for fact in facts:
+            self.put(fact)
+
+    @classmethod
+    def from_records(cls, data: Mapping[str, Any] | Iterable[Mapping[str, Any]]) -> Facts:
+        """Load {"currency": ..., "facts": [...]}, a list of fact dicts, or {key: value}."""
+        currency = None
+        if isinstance(data, Mapping):
+            if "facts" in data:
+                currency = data.get("currency")
+                data = data["facts"]
+            else:
+                data = [{"key": k, "value": v} for k, v in data.items()]
+        facts = cls(currency=currency)
+        for record in data:
+            record = dict(record)
+            if "kind" not in record:
+                record["kind"] = "number" if isinstance(record.get("value"), (int, float)) else "text"
+            facts.put(Fact(**record))
+        return facts
+
+    def add(self, key: str, value: float | int | str, kind: Kind = "number", **fields: Any) -> Fact:
+        return self.put(Fact(key, value, kind, **fields))
+
+    def put(self, fact: Fact) -> Fact:
+        if fact.key in self._facts:
+            raise ValueError(f"fact {fact.key!r} is already defined")
+        self._facts[fact.key] = fact
+        return fact
+
+    def get(self, key: str) -> Fact | None:
+        return self._facts.get(key)
+
+    def __getitem__(self, key: str) -> Fact:
+        return self._facts[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._facts
+
+    def __iter__(self) -> Iterator[Fact]:
+        return iter(self._facts.values())
+
+    def __len__(self) -> int:
+        return len(self._facts)
+
+    def format(self, fact: Fact | str) -> str:
+        return self.formatter(self[fact] if isinstance(fact, str) else fact)
+
+    def strip_currency(self, text: str) -> str:
+        """Drop a currency the model typed before a money placeholder: "INR {{fact:spend}}"."""
+
+        def fix(m: re.Match[str]) -> str:
+            fact = self.get(m["key"])
+            typed = m["code"] or m["symbol"]
+            known = typed in CURRENCIES or typed.startswith("Rs") or m["symbol"] is not None
+            if fact is not None and fact.kind == "money" and known:
+                return m["placeholder"]
+            return m[0]
+
+        return _TYPED_CURRENCY.sub(fix, text)
+
+    def render(self, text: str) -> str:
+        """Replace every placeholder with its formatted value. Unknown keys raise KeyError,
+        so validate first."""
+
+        def fill(m: re.Match[str]) -> str:
+            if m[1] not in self._facts:
+                raise KeyError(f"unknown fact {m[1]!r}")
+            return self.format(m[1])
+
+        return PLACEHOLDER.sub(fill, self.strip_currency(text))
+
+    def prompt(self, *, rules: bool = True) -> str:
+        """The fact list for the system prompt, optionally preceded by the citation rules."""
+        lines = [RULES, ""] if rules else []
+        lines.append("Facts:")
+        for fact in self:
+            about = ", ".join(x for x in (fact.label, fact.kind, fact.source) if x)
+            lines.append(f"- {fact.placeholder} = {self.format(fact)} ({about})")
+        return "\n".join(lines)

factguard/guard.py

@@ -0,0 +1,143 @@
+"""The validate, retry once, then drop loop around any LLM call."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .facts import Facts
+from .sentences import drop_sentences, split_sentences
+from .validate import Report, Violation, validate
+
+
+@dataclass(frozen=True)
+class Retry:
+    """Handed to your generate function when the previous draft failed."""
+
+    draft: str
+    report: Report
+
+    @property
+    def feedback(self) -> str:
+        return self.report.feedback
+
+
+@dataclass(frozen=True)
+class Result:
+    text: str  # rendered: placeholders replaced with formatted values
+    raw: str  # the accepted text, still with placeholders
+    attempts: int
+    dropped: tuple[str, ...]  # sentences removed because they still broke the rules
+    violations: tuple[Violation, ...]  # what the last draft got wrong
+
+    @property
+    def clean(self) -> bool:
+        """True when nothing had to be dropped."""
+        return not self.dropped
+
+
+def _finish(draft: str, report: Report, facts: Facts, attempts: int, rules: dict[str, Any]) -> Result:
+    if report.ok:
+        return Result(facts.render(draft), draft, attempts, (), ())
+    kept, dropped = draft, []
+    current = report
+    # One pass is enough for local violations; loop in case a drop changes what a
+    # later sentence means (a list marker that lost its line, say).
+    for _ in range(3):
+        kept, more = drop_sentences(kept, [(v.start, v.end) for v in current.violations])
+        dropped += more
+        current = validate(kept, facts, **rules)
+        if current.ok:
+            break
+    else:
+        kept, dropped = "", dropped + [kept]
+    return Result(facts.render(kept), kept, attempts, tuple(dropped), report.violations)
+
+
+def guard(
+    generate: Callable[[Retry | None], str],
+    facts: Facts,
+    *,
+    retries: int = 1,
+    **rules: Any,
+) -> Result:
+    """Call generate(None) for a draft. If it breaks the rules, call generate(Retry)
+    up to `retries` times. If the last draft still fails, drop the offending sentences.
+
+    rules are passed to validate(): windows, user_text, allow, number_words, ...
+    """
+    retry = None
+    attempts = 0
+    while True:
+        attempts += 1
+        draft = generate(retry)
+        report = validate(draft, facts, **rules)
+        if report.ok or attempts > retries:
+            return _finish(draft, report, facts, attempts, rules)
+        retry = Retry(draft, report)
+
+
+async def aguard(
+    generate: Callable[[Retry | None], Awaitable[str]],
+    facts: Facts,
+    *,
+    retries: int = 1,
+    **rules: Any,
+) -> Result:
+    """guard() for an async generate function."""
+    retry = None
+    attempts = 0
+    while True:
+        attempts += 1
+        draft = await generate(retry)
+        report = validate(draft, facts, **rules)
+        if report.ok or attempts > retries:
+            return _finish(draft, report, facts, attempts, rules)
+        retry = Retry(draft, report)
+
+
+class StreamGuard:
+    """Validates streamed text sentence by sentence.
+
+    A sentence already on screen can't be rewritten, so a failing sentence is
+    dropped rather than retried.
+
+        sg = StreamGuard(facts, windows=[window])
+        for chunk in stream:
+            for sentence in sg.feed(chunk):
+                show(sentence)
+        for sentence in sg.close():
+            show(sentence)
+    """
+
+    def __init__(self, facts: Facts, **rules: Any) -> None:
+        self.facts = facts
+        self.rules = rules
+        self.dropped: list[str] = []
+        self.violations: list[Violation] = []
+        self._buffer = ""
+        self._line_closed = True
+
+    def feed(self, chunk: str) -> list[str]:
+        self._buffer += chunk
+        pieces = split_sentences(self._buffer)
+        # The last piece may still be growing.
+        self._buffer = pieces.pop() if pieces else ""
+        return [out for piece in pieces if (out := self._check(piece))]
+
+    def close(self) -> list[str]:
+        rest, self._buffer = self._buffer, ""
+        out = self._check(rest) if rest else ""
+        return [out] if out else []
+
+    def _check(self, piece: str) -> str:
+        report = validate(piece, self.facts, **self.rules)
+        if report.ok:
+            self._line_closed = piece.endswith("\n")
+            return self.facts.render(piece)
+        self.dropped.append(piece.strip())
+        self.violations.extend(report.violations)
+        # Same rule as drop_sentences: close the line only if it isn't closed already.
+        ends_line = "\n" in piece[len(piece.rstrip()) :]
+        return "\n" if ends_line and not self._line_closed else ""

factguard/sentences.py

@@ -0,0 +1,56 @@
+"""Sentence splitting that keeps whitespace, so dropped sentences leave tidy text."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+_END = re.compile(r"[.!?]+[\"')\]]*[ \t]*(?:\n\s*|[ \t]+)|\n\s*")
+_ABBREVIATION = re.compile(r"(?:\b(?:e\.g|i\.e|vs|etc|approx|incl|Mr|Ms|Dr)|^\s*\d{1,3})\.$")
+
+
+def split_sentences(text: str) -> list[str]:
+    """Split text into sentences and lines. Each piece keeps its trailing whitespace,
+    so "".join(pieces) == text."""
+    pieces: list[str] = []
+    start = 0
+    for m in _END.finditer(text):
+        line_start = text.rfind("\n", 0, m.start()) + 1
+        # "e.g. " and the "1. " of a numbered list are not sentence ends.
+        if text[m.start()] == "." and _ABBREVIATION.search(text[line_start : m.start() + 1]):
+            continue
+        pieces.append(text[start : m.end()])
+        start = m.end()
+    if start < len(text):
+        pieces.append(text[start:])
+    return pieces
+
+
+_EMPTY_BULLET = re.compile(r"(?m)^[ \t]*(?:[-*•]|\d{1,3}[.)])[ \t]*$\n?")
+
+
+def drop_sentences(text: str, spans: Iterable[tuple[int, int]]) -> tuple[str, list[str]]:
+    """Remove every sentence that overlaps one of the (start, end) spans.
+
+    Returns the remaining text and the removed sentences."""
+    spans = list(spans)
+    kept: list[str] = []
+    dropped: list[str] = []
+    pos = 0
+    for piece in split_sentences(text):
+        start, end = pos, pos + len(piece)
+        pos = end
+        if any(s < end and e > start for s, e in spans):
+            body = piece.rstrip()
+            dropped.append(body.strip())
+            # A sentence that ended its line takes the line break with it; keep the
+            # break unless the line is already closed, so lists keep their shape.
+            if "\n" in piece[len(body) :] and kept and not kept[-1].endswith("\n"):
+                kept.append("\n")
+        else:
+            kept.append(piece)
+    out = "".join(kept)
+    out = _EMPTY_BULLET.sub("", out)
+    out = re.sub(r"[ \t]+\n", "\n", out)
+    out = re.sub(r"\n{3,}", "\n\n", out)
+    return out.strip(), dropped

factguard/testing.py

@@ -0,0 +1,16 @@
+"""Helpers for eval suites: assert that recorded answers contain zero ungrounded numbers."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .facts import Facts
+from .validate import Report, validate
+
+
+def assert_grounded(text: str, facts: Facts, **rules: Any) -> Report:
+    """Raise AssertionError listing every ungrounded number in text."""
+    report = validate(text, facts, **rules)
+    if not report.ok:
+        raise AssertionError(report.feedback)
+    return report

factguard/validate.py

@@ -0,0 +1,252 @@
+"""Checks LLM text for numbers that did not come from a fact."""
+
+from __future__ import annotations
+
+import calendar
+import re
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import date
+
+from .facts import PLACEHOLDER, Facts
+
+Window = tuple[date, date]
+
+_MALFORMED = re.compile(r"\{\{[^{}]*\}\}|\{fact:[^{}]*\}")
+_LIST_MARKER = re.compile(r"(?m)^[ \t]*(?:[-*•][ \t]+)?\d{1,3}[.)](?=\s)")
+# Names and words that contain digits but state no quantity.
+_TERMS = re.compile(r"(?i)\b(?:GA4|GA360|B2B|B2C|D2C|C2C|P2P|24/7|[123](?:st|nd|rd)[- ]party|H\.26[45])\b")
+_ATTRIBUTION = re.compile(r"(?i)\b\d{1,2}[- ]?(?:days?|d)[- ](?:click|view)s?\b")
+
+_MONTH = (
+    r"(?P<mon>Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|Aug(?:ust)?"
+    r"|Sep(?:t(?:ember)?)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\.?"
+)
+_DAY = r"(?P<day>\d{1,2})(?:st|nd|rd|th)?"
+_YEAR = r"(?:,?\s+(?P<year>(?:19|20)\d{2})\b)?"
+_DATES = [
+    re.compile(r"\b(?P<year>\d{4})-(?P<m>\d{2})-(?P<day>\d{2})\b"),
+    re.compile(r"\b" + _MONTH + r"\s+" + _DAY + r"\b" + _YEAR),
+    re.compile(r"\b" + _DAY + r"\s+" + _MONTH + r"(?![A-Za-z])" + _YEAR),
+]
+_MONTH_YEAR = re.compile(r"\b" + _MONTH + r",?\s+(?P<year>(?:19|20)\d{2})\b")
+_YEAR_ONLY = re.compile(r"\b(?:19|20)\d{2}\b")
+_DURATION = re.compile(r"(?i)\b(?P<n>\d+)[- ]?(?P<unit>day|week|month)s?\b")
+
+_TOKEN = re.compile(r"\S*\d\S*")
+_NUMBER = re.compile(r"(?i)^[^\d\-+]*?(?P<sign>[-+])?(?P<num>\d[\d,]*(?:\.\d+)?)\s*(?P<suffix>%|x|k|m|mn|bn|b)?$")
+_MULTIPLIER = {"k": 1e3, "m": 1e6, "mn": 1e6, "b": 1e9, "bn": 1e9}
+
+_NUMBER_WORDS = re.compile(
+    r"(?i)\b(?:two|three|four|five|six|seven|eight|nine|ten|eleven|twelve"
+    r"|twenty|thirty|forty|fifty|sixty|seventy|eighty|ninety|hundred|thousand|million|billion"
+    r"|dozen|double[sd]?|doubling|triple[sd]?|tripling|twice|half|halved|\w+fold)\b"
+)
+
+
+@dataclass(frozen=True)
+class Violation:
+    """One broken rule: what kind, the offending text and where it is."""
+
+    kind: str  # unknown_fact | malformed_placeholder | literal_number | date | duration | number_word
+    token: str
+    start: int
+    end: int
+    detail: str
+
+
+@dataclass(frozen=True)
+class Report:
+    text: str
+    violations: tuple[Violation, ...]
+
+    @property
+    def ok(self) -> bool:
+        return not self.violations
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+    @property
+    def feedback(self) -> str:
+        """A retry message that names every offending key or token."""
+        if self.ok:
+            return ""
+        lines = [
+            "Your draft broke the rule that every number must come from a fact placeholder. "
+            "Fix only these and keep the rest of the draft as it is:"
+        ]
+        seen = set()
+        for v in self.violations:
+            if (v.kind, v.token) not in seen:
+                seen.add((v.kind, v.token))
+                lines.append(f"- `{v.token}`: {v.detail}")
+        return "\n".join(lines)
+
+
+def _fmt_windows(windows: Sequence[Window]) -> str:
+    return ", ".join(f"{a.isoformat()} to {b.isoformat()}" for a, b in windows)
+
+
+def _month_number(name: str) -> int:
+    return [m.lower() for m in calendar.month_abbr].index(name[:3].lower())
+
+
+def _value(token: str) -> float | None:
+    m = _NUMBER.match(token)
+    if not m:
+        return None
+    x = float(m["num"].replace(",", ""))
+    x *= _MULTIPLIER.get((m["suffix"] or "").lower(), 1)
+    return -x if m["sign"] == "-" else x
+
+
+def _strip(token: str) -> tuple[str, int]:
+    """Trim surrounding punctuation. Returns the token and how much was cut from the left."""
+    left = len(token) - len(token.lstrip("(\"'[“‘"))
+    return token[left:].rstrip(".,;:!?)\"']”’"), left
+
+
+class _Text:
+    """The text being checked, with spans blanked out once they are accounted for."""
+
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.masked = text
+
+    def blank(self, start: int, end: int) -> None:
+        self.masked = self.masked[:start] + " " * (end - start) + self.masked[end:]
+
+
+def validate(
+    text: str,
+    facts: Facts,
+    *,
+    windows: Iterable[Window] = (),
+    user_text: str = "",
+    allow: Iterable[str | re.Pattern[str]] = (),
+    list_markers: bool = True,
+    attribution_labels: bool = True,
+    terms: bool = True,
+    number_words: bool = False,
+) -> Report:
+    """Check LLM text against the rule: no number the code did not compute.
+
+    windows: the date ranges this answer actually used. Dates, years and
+        durations ("last 28 days") are allowed only when they match one.
+    user_text: what the user wrote. Numbers they typed may be repeated.
+    allow: extra regexes for text that may contain digits.
+    terms: allow names like GA4, B2B and 3rd-party.
+    number_words: also flag quantities in words ("doubled", "twenty").
+    """
+    windows = tuple(windows)
+    t = _Text(text)
+    found: list[Violation] = []
+
+    def flag(kind: str, start: int, end: int, detail: str) -> None:
+        found.append(Violation(kind, text[start:end], start, end, detail))
+        t.blank(start, end)
+
+    for m in PLACEHOLDER.finditer(text):
+        if m[1] in facts:
+            t.blank(*m.span())
+        else:
+            flag("unknown_fact", *m.span(), f"`{m[1]}` is not a known fact key. Use only keys from the fact list.")
+    for m in _MALFORMED.finditer(t.masked):
+        flag("malformed_placeholder", *m.span(), "write placeholders exactly as {{fact:key}}.")
+
+    patterns = [re.compile(p) if isinstance(p, str) else p for p in allow]
+    if list_markers:
+        patterns.append(_LIST_MARKER)
+    if attribution_labels:
+        patterns.append(_ATTRIBUTION)
+    if terms:
+        patterns.append(_TERMS)
+    for pattern in patterns:
+        for m in pattern.finditer(t.masked):
+            t.blank(*m.span())
+
+    _check_dates(t, windows, flag)
+
+    allowed = _numbers(user_text)
+    for m in _TOKEN.finditer(t.masked):
+        token, cut = _strip(m[0])
+        if not token:
+            continue
+        start = m.start() + cut
+        value = _value(token)
+        if token in allowed or (value is not None and value in allowed):
+            continue
+        flag(
+            "literal_number",
+            start,
+            start + len(token),
+            "this is a number you typed. Cite it with a {{fact:...}} placeholder, or say it without the figure.",
+        )
+
+    if number_words:
+        for m in _NUMBER_WORDS.finditer(t.masked):
+            flag("number_word", *m.span(), "this states a quantity in words. Cite a fact or drop the comparison.")
+
+    return Report(text, tuple(sorted(found, key=lambda v: v.start)))
+
+
+def _numbers(user_text: str) -> set[str | float]:
+    out: set[str | float] = set()
+    for m in _TOKEN.finditer(user_text):
+        token, _ = _strip(m[0])
+        out.add(token)
+        if (value := _value(token)) is not None:
+            out.add(value)
+    return out
+
+
+def _check_dates(t: _Text, windows: tuple[Window, ...], flag) -> None:
+    where = f"the analysis window ({_fmt_windows(windows)})" if windows else "an analysis window, and none was given"
+
+    def judge(m: re.Match[str], inside: bool, kind: str = "date") -> None:
+        if inside:
+            t.blank(*m.span())
+        else:
+            flag(kind, *m.span(), f"dates and periods must come from {where}.")
+
+    def contains(d: date) -> bool:
+        return any(a <= d <= b for a, b in windows)
+
+    for i, pattern in enumerate(_DATES):
+        for m in pattern.finditer(t.masked):
+            month = int(m["m"]) if i == 0 else _month_number(m["mon"])
+            day = int(m["day"])
+            years = (
+                [int(m["year"])]
+                if m["year"]
+                else range(
+                    min((a.year for a, _ in windows), default=0), max((b.year for _, b in windows), default=-1) + 1
+                )
+            )
+            inside = False
+            for year in years:
+                try:
+                    inside = inside or contains(date(year, month, day))
+                except ValueError:
+                    pass
+            judge(m, inside)
+
+    for m in _MONTH_YEAR.finditer(t.masked):
+        year, month = int(m["year"]), _month_number(m["mon"])
+        first, last = date(year, month, 1), date(year, month, calendar.monthrange(year, month)[1])
+        judge(m, any(a <= last and b >= first for a, b in windows))
+
+    for m in _YEAR_ONLY.finditer(t.masked):
+        judge(m, any(a.year <= int(m[0]) <= b.year for a, b in windows))
+
+    lengths = [(b - a).days + 1 for a, b in windows]
+    for m in _DURATION.finditer(t.masked):
+        n, unit = int(m["n"]), m["unit"].lower()
+        if unit == "day":
+            inside = n in lengths
+        elif unit == "week":
+            inside = n * 7 in lengths
+        else:
+            inside = any(abs(length - n * 30.44) <= 3 for length in lengths)
+        judge(m, inside, "duration")

factguard-0.1.0.dist-info/METADATA

@@ -0,0 +1,175 @@
+Metadata-Version: 2.5
+Name: factguard
+Version: 0.1.0
+Summary: Keep LLM-written text free of numbers your code didn't compute: fact placeholders, a strict validator, one retry, then drop the sentence
+Project-URL: Homepage, https://github.com/shivamsingh262/factguard
+Project-URL: Issues, https://github.com/shivamsingh262/factguard/issues
+Project-URL: Design notes, https://shivamsingh262.github.io/notes/code-computes-llm-interprets/
+Author: Shivam Singh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,analytics,grounding,guardrails,hallucination,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# factguard
+
+[![CI](https://github.com/shivamsingh262/factguard/actions/workflows/ci.yml/badge.svg)](https://github.com/shivamsingh262/factguard/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)
+![No dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](CONTRIBUTING.md)
+
+Keep LLM-written text free of numbers your code didn't compute.
+
+If an LLM writes a wrong number confidently, users stop trusting every other
+number on the screen. factguard enforces one rule: **code computes every
+number, the LLM only interprets.**
+
+- Your code registers each number as a **fact**: a key, a value, a format
+  (money, percent, count, ratio...) and where it came from.
+- The LLM cites facts as placeholders like `{{fact:spend}}` and never types the
+  digits itself.
+- A **validator** rejects any literal number, unknown fact key, or date or
+  duration outside the analysis window.
+- On failure the model gets **one retry** with a message naming exactly what
+  broke. If the retry fails too, the offending **sentences are dropped**. A
+  shorter answer is better than a wrong one.
+
+It works with any LLM and any SDK, and has no dependencies. The design comes
+from a production AI analyst for marketing teams; the write-up is
+[Stopping an LLM from making up numbers in an AI analyst](https://shivamsingh262.github.io/notes/code-computes-llm-interprets/).
+
+## Install
+
+```sh
+pip install git+https://github.com/shivamsingh262/factguard
+```
+
+## Quick start
+
+```python
+from datetime import date
+from factguard import Facts, guard
+
+facts = Facts(currency="INR")
+facts.add("spend", 61_240, "money", label="Ad spend this week")
+facts.add("roas", 1.8, "ratio", label="ROAS this week")
+facts.add("roas_prev", 2.4, "ratio", label="ROAS last week")
+
+system_prompt = facts.prompt()   # the rules, plus "- {{fact:spend}} = INR 61.2K (...)"
+
+def generate(retry):
+    # Call your LLM here. On a retry, show it retry.draft and retry.feedback.
+    ...
+
+week = (date(2026, 9, 22), date(2026, 9, 28))
+result = guard(generate, facts, windows=[week], user_text="Why did ROAS drop?")
+
+result.text      # "ROAS fell from 2.4x to 1.8x while spend held at INR 61.2K."
+result.dropped   # sentences removed because they still broke the rules
+result.attempts  # 1 or 2
+```
+
+[`examples/anthropic_analyst.py`](examples/anthropic_analyst.py) is a complete
+example using Claude.
+
+## What counts as a violation
+
+| Kind | Example | Why it fails |
+|---|---|---|
+| `literal_number` | `CPA is up 40%` | The model typed a number. Cite a fact or say it without the figure. |
+| `unknown_fact` | `{{fact:f_9999.roas}}` | No such fact was computed. |
+| `malformed_placeholder` | `{{spend}}` | Placeholders must be exactly `{{fact:key}}`. |
+| `date` | `since Oct 3` | Dates, months and years must fall inside a window you passed. |
+| `duration` | `over the last 45 days` | Durations must match the length of a window you passed. |
+| `number_word` | `spend nearly doubled` | Only with `number_words=True`. |
+
+Allowed without a fact:
+
+- numbered list markers (`1.`, `2)`)
+- attribution labels (`7-day click`, `1-day view`)
+- names like `GA4`, `B2B`, `3rd-party` and `24/7`
+- numbers the user typed (`user_text`), so "campaigns with ROAS below 2" can
+  repeat the 2
+- your own patterns: `allow=[r"SKU-\d+"]`
+
+Without `windows`, every date and duration fails. That is deliberate: the
+model shouldn't do date arithmetic. Resolve "last month" in code and pass the
+window you actually queried. Pass both windows when you compare two periods.
+
+## The pieces
+
+**`Facts`** holds the facts for one answer.
+
+- `facts.add(key, value, kind, label=..., currency=..., decimals=..., source=..., step=...)`
+- `facts.prompt()` returns the citation rules and fact list for your system prompt.
+- `facts.render(text)` replaces placeholders with formatted values. It also strips a currency the model typed in
+  front of a money placeholder (`INR {{fact:spend}}`), since the fact brings its own.
+- `Facts.from_records(json_data)` loads facts from JSON.
+
+Formats: `money` renders as `INR 61.2K` or `$1.2M` (pass `Formatter(compact=False)` for `61,240`). `percent` takes
+fractions, so `0.034` renders as `3.4%`. `count` renders as `12,480`, `ratio` as `2.3x`, and `text` as-is. To use
+your own formatting, pass any `Callable[[Fact], str]` as `formatter=`.
+
+**`validate(text, facts, **rules)`** returns a `Report` with `.ok`, `.violations` (kind, token, start, end) and
+`.feedback`, a retry message that names each offending token.
+
+**`guard(generate, facts, retries=1, **rules)`** runs the whole loop. `generate(None)` should return a first draft,
+and `generate(retry)` a corrected one. Use `aguard` for async code.
+
+**`StreamGuard(facts, **rules)`** checks streamed text one sentence at a time. A sentence already on screen can't
+be rewritten, so a failing sentence is dropped instead of retried:
+
+```python
+sg = StreamGuard(facts, windows=[week])
+for chunk in llm_stream:
+    for sentence in sg.feed(chunk):
+        ui.append(sentence)
+for sentence in sg.close():
+    ui.append(sentence)
+```
+
+**Evals.** Check every recorded answer for zero ungrounded numbers, not just for the right answer:
+
+```python
+from factguard.testing import assert_grounded
+
+def test_recorded_answer():
+    assert_grounded(answer, facts, windows=[week])
+```
+
+Or from the shell or CI:
+
+```sh
+factguard check answer.txt --facts facts.json --window 2026-09-22:2026-09-28
+factguard render answer.txt --facts facts.json
+```
+
+## Trade-offs
+
+The prose gets stiffer. Without "nearly double" or "about a third", the model
+writes more literal sentences. Some sentences get dropped, and a retry adds
+latency. If users have to trust the numbers before the interpretation is worth
+anything, that trade is worth it.
+
+Placeholders don't stop the model from citing the *wrong* fact, so keep fact
+labels clear and test with recorded questions. And `number_words` is a
+heuristic: it is off by default because words like "half" are often harmless.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports with a sentence that was
+wrongly flagged or wrongly let through are especially useful.
+
+## License
+
+[MIT](LICENSE)

factguard-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+factguard/__init__.py,sha256=4ZF4pMjZLxUGTHTl1LI5QC1hIbMLB9TI2mlVHZ6vycQ,632
+factguard/__main__.py,sha256=E6Gls0DNz8GQK2K-kOUIx8cYhgANW_CH54VKrfCfs14,52
+factguard/cli.py,sha256=e-2uySQpnHycvGwp904kZCpU3utG7E7tBxThdNhl8iE,2739
+factguard/facts.py,sha256=3qFffUzKHAQYizjwOTikhHcNQFFKDCNeuPFlpAGFAsU,7949
+factguard/guard.py,sha256=IAoY6iKgpy54M9-wKdMbbVy2emOqqBdF9_YiBp8UkLI,4669
+factguard/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+factguard/sentences.py,sha256=MQTu2vWh38FGOkncm0Pjt8inU4IcNgG1AARwDyUM30s,2100
+factguard/testing.py,sha256=wyT8JyE8wcuCz5Qk74lEvd1JteAYHgWUyq6hviOi9lQ,492
+factguard/validate.py,sha256=MIf2hUhIeNlCtijKzx5jAdqGkr9i_MOWJ3bGMVRJrQc,8892
+factguard-0.1.0.dist-info/METADATA,sha256=JosUWYZmwStaRADEPhj1U-_TJEe3wf5rsMSlXkLC6cw,7372
+factguard-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+factguard-0.1.0.dist-info/entry_points.txt,sha256=W44S9PmOZh5qN5N1JlAxVDVhGiKQuimJLq6ZJ7l75c0,49
+factguard-0.1.0.dist-info/licenses/LICENSE,sha256=7si93GIH3wzi1-ttSl--KR1PnU3Wvc4bJD4GXETM_Ys,1069
+factguard-0.1.0.dist-info/RECORD,,

factguard-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

factguard-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+factguard = factguard.cli:main

factguard-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shivam Singh
+
+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.