Download utils/policy_rules.py from roosttools/llm_moderation_testing: direct link, hf CLI and curl.
- Browser
- Download file 15.9 kB
-
https://huggingface.co/spaces/roosttools/llm_moderation_testing/resolve/main/utils/policy_rules.py
- Command line
-
hf download hf://spaces/roosttools/llm_moderation_testing/utils/policy_rules.py
-
curl -L -o policy_rules.py https://huggingface.co/spaces/roosttools/llm_moderation_testing/resolve/main/utils/policy_rules.py
15.9 kB
| """ | |
| Structured policy rules β the PolicyLM-native "flag / don't flag / exception" model. | |
| PolicyLM's `policylm_infer.Category` takes three separate fields: | |
| Category(name, | |
| violation_rule="flag this", | |
| not_violation_rule="don't flag this", | |
| exception_override="exception / carve-out") | |
| The app lets users author a policy as a list of such rules. The SAME rules are: | |
| * rendered to a plain-text policy (`render_rules_to_text`) that every text model | |
| (gpt-oss-safeguard, Shieldstral, CoPE) receives via the normal `policy` string, | |
| so both model families are judged on an identical policy; and | |
| * sent natively to PolicyLM as discrete categories (`rules_to_categories`), so | |
| exceptions are read as exceptions and each rule gets its own score. | |
| A "rule" is a plain dict: {"name", "flag", "dont_flag", "exception"} (all strings). | |
| """ | |
| from __future__ import annotations | |
| import math | |
| from utils.constants import POLICYLM_MAX_CATEGORIES, POLICYLM_MAX_POLICY_TOKENS | |
| # The empty-rule template. Copy it (`dict(EMPTY_RULE)`) β never mutate the shared one. | |
| EMPTY_RULE = {"name": "", "flag": "", "dont_flag": "", "exception": "", "enabled": True, "context": ""} | |
| _FIELD_ORDER = ("name", "flag", "dont_flag", "exception") | |
| def new_rule() -> dict: | |
| """A fresh, blank rule dict.""" | |
| return dict(EMPTY_RULE) | |
| def _s(rule: dict, field: str) -> str: | |
| """Safely read and strip a rule field.""" | |
| return (rule.get(field) or "").strip() | |
| def rule_has_content(rule: dict) -> bool: | |
| """True if the rule has anything worth sending (a name or any rule text).""" | |
| return any(_s(rule, f) for f in _FIELD_ORDER) | |
| def rule_is_enabled(rule: dict) -> bool: | |
| """Whether this rule is switched on. | |
| Missing means on, so rules saved before the toggle existed keep working. | |
| """ | |
| return bool(rule.get("enabled", True)) | |
| def rules_have_content(rules: list[dict] | None) -> bool: | |
| """True if at least one enabled rule carries content. | |
| Switching every rule off is a way of saying "use the free-form policy instead", | |
| so it must read the same as having no rules at all. | |
| """ | |
| return any(rule_has_content(r) and rule_is_enabled(r) for r in (rules or [])) | |
| def nonempty_rules(rules: list[dict] | None) -> list[dict]: | |
| """Only the rules that carry content and are switched on. | |
| Every consumer funnels through here β the text rendering and the PolicyLM | |
| category payload both β so the toggle is honoured in one place. | |
| """ | |
| return [r for r in (rules or []) if rule_has_content(r) and rule_is_enabled(r)] | |
| def render_rules_to_text(rules: list[dict] | None) -> str: | |
| """ | |
| Render structured rules into a plain-text policy document. | |
| This is what the text models see. It is intentionally literal about the three | |
| PolicyLM fields so a reading model treats "Do not flag" / "Exception" as | |
| carve-outs rather than things to flag. | |
| """ | |
| kept = nonempty_rules(rules) | |
| if not kept: | |
| return "" | |
| lines = [ | |
| "# Content Policy", | |
| "", | |
| "Apply the following rules. Content matching a rule's **Flag this** description " | |
| "is a violation, UNLESS it matches that rule's **Do not flag** description or an " | |
| "**Exception**. Evaluate each rule independently.", | |
| "", | |
| ] | |
| seen_context = list(dict.fromkeys(_s(r, "context") for r in kept if _s(r, "context"))) | |
| if seen_context: | |
| # Once at the top for models that read the whole document; the per-rule copies | |
| # exist only for models scored a category at a time. | |
| lines += ["**Definitions and scope:** " + " ".join(seen_context), ""] | |
| for i, rule in enumerate(kept, start=1): | |
| name = _s(rule, "name") or f"Rule {i}" | |
| lines.append(f"## {i}. {name}") | |
| flag = _s(rule, "flag") | |
| dont = _s(rule, "dont_flag") | |
| exc = _s(rule, "exception") | |
| if flag: | |
| lines.append(f"- **Flag this (violation):** {flag}") | |
| if dont: | |
| lines.append(f"- **Do not flag:** {dont}") | |
| if exc: | |
| lines.append(f"- **Exception:** {exc}") | |
| lines.append("") | |
| return "\n".join(lines).rstrip() + "\n" | |
| def rules_to_categories(rules: list[dict] | None) -> list[dict]: | |
| """ | |
| Convert rules into the category payload the PolicyLM endpoint handler expects. | |
| Each category maps directly onto policylm_infer.Category's constructor kwargs. | |
| Only non-empty optional fields are included so the handler can omit kwargs it | |
| doesn't have values for. A rule with a "flag this" field is a scorable category; a | |
| rule with only a "don't flag" / "exception" (an "applies to all" carve-out) is | |
| policy-wide guidance and is folded into every real category rather than dropped, | |
| so PolicyLM honours it like the prompted models do. | |
| """ | |
| categories = [] | |
| global_dont: list[str] = [] | |
| global_exc: list[str] = [] | |
| # PolicyLM keys its results by category title and rejects the whole policy if two | |
| # share one, so a second rule called "Zone 2: ..." must not reach the endpoint | |
| # under that name. Two rules really can carry the same title β the same preset | |
| # added twice, or two hand-written rules β and failing the run outright is a worse | |
| # answer than scoring them separately, so repeats are numbered. | |
| seen_names: dict[str, int] = {} | |
| for rule in nonempty_rules(rules): | |
| flag = _s(rule, "flag") | |
| dont = _s(rule, "dont_flag") | |
| exc = _s(rule, "exception") | |
| if not flag: | |
| if dont: | |
| global_dont.append(dont) | |
| if exc: | |
| global_exc.append(exc) | |
| continue | |
| context = _s(rule, "context") | |
| base_name = _s(rule, "name") or f"Rule {len(categories) + 1}" | |
| n = seen_names.get(base_name.casefold(), 0) + 1 | |
| seen_names[base_name.casefold()] = n | |
| cat = { | |
| "name": base_name if n == 1 else f"{base_name} ({n})", | |
| "violation_rule": f"{flag} ({context})" if context else flag, | |
| } | |
| if dont: | |
| cat["not_violation_rule"] = dont | |
| if exc: | |
| cat["exception_override"] = exc | |
| categories.append(cat) | |
| return _fold_global(categories, _one_line(" ".join(global_dont)), _one_line(" ".join(global_exc))) | |
| def estimate_policy_tokens(rules: list[dict] | None) -> int: | |
| """ | |
| Rough token estimate for PolicyLM's 1,662 *policy-token* budget. | |
| PolicyLM uses its own tokenizer; we don't load it here (keeps the Space light), | |
| so this is a deliberately conservative heuristic β max of a chars/4 and a | |
| words*4/3 estimate β that tends to warn slightly *early* rather than late. Only | |
| the rule text that becomes category content is counted (not the UI scaffolding). | |
| """ | |
| text_parts: list[str] = [] | |
| for rule in nonempty_rules(rules): | |
| for f in _FIELD_ORDER: | |
| v = _s(rule, f) | |
| if v: | |
| text_parts.append(v) | |
| text = " ".join(text_parts) | |
| if not text: | |
| return 0 | |
| char_est = len(text) / 4 | |
| word_est = len(text.split()) * 4 / 3 | |
| return int(math.ceil(max(char_est, word_est))) | |
| def policy_limits_markdown(rules: list[dict] | None) -> str: | |
| """ | |
| A compact live status line for the editor: rule count, estimated tokens, and | |
| warnings when either PolicyLM limit is exceeded. | |
| """ | |
| n = len(nonempty_rules(rules)) | |
| tokens = estimate_policy_tokens(rules) | |
| cat_ok = n <= POLICYLM_MAX_CATEGORIES | |
| tok_ok = tokens <= POLICYLM_MAX_POLICY_TOKENS | |
| cat_mark = "" if cat_ok else " β οΈ" | |
| tok_mark = "" if tok_ok else " β οΈ" | |
| lines = [ | |
| f"**Rules:** {n} / {POLICYLM_MAX_CATEGORIES}{cat_mark} Β· " | |
| f"**Est. policy tokens:** ~{tokens:,} / {POLICYLM_MAX_POLICY_TOKENS:,}{tok_mark}", | |
| ] | |
| if not cat_ok: | |
| lines.append( | |
| f"> β οΈ **Too many rules for PolicyLM.** It supports at most " | |
| f"{POLICYLM_MAX_CATEGORIES} categories (a schema-model limit; prompted " | |
| f"models are unaffected); extra rules will be rejected by the " | |
| f"endpoint. The text models (gpt-oss-safeguard, Shieldstral, CoPE) still " | |
| f"accept all of them." | |
| ) | |
| if not tok_ok: | |
| lines.append( | |
| f"> β οΈ **Policy likely too long for PolicyLM** (est. ~{tokens:,} tokens > " | |
| f"{POLICYLM_MAX_POLICY_TOKENS:,}). Shorten the rule text or split the policy; " | |
| f"PolicyLM may truncate or error. Estimate is approximate β the real limit " | |
| f"uses PolicyLM's own tokenizer." | |
| ) | |
| return "\n\n".join(lines) | |
| # --- Free-form policy -> PolicyLM categories --------------------------------------- | |
| # | |
| # PolicyLM requires every category field to be a single line. A written policy is a | |
| # multi-line markdown document, so sending one as a catch-all category fails with | |
| # "Violation rule contains a line break; each field is one line" β which is what the | |
| # legacy fallback in policylm_handler.py does. | |
| # | |
| # The workshop policies are already written in the shape PolicyLM wants: a "## Heading" | |
| # per rule with "Flag:", "Don't flag:" and "Exception:" lines under it. Parsing that | |
| # into real categories fixes the error and is strictly better than a catch-all, because | |
| # each rule gets its own score and exceptions are read as exceptions. | |
| _FIELD_PREFIXES = ( | |
| ("violation_rule", ("flag:",)), | |
| ("not_violation_rule", ("don't flag:", "dont flag:", "do not flag:")), | |
| ("exception_override", ("exception:", "exceptions:")), | |
| ) | |
| def _one_line(text: str) -> str: | |
| """Collapse to a single line; PolicyLM rejects any field containing a newline.""" | |
| return " ".join(str(text).split()) | |
| def policy_definitions(policy_text: str) -> list[tuple[str, str]]: | |
| """Definitions stated before the first "## " heading, as (term, line) pairs. | |
| A policy states its scope once at the top β "Protected classes: β¦", | |
| "Not protected: β¦". A model handed the whole document reads that; a model scored | |
| one category at a time never sees it, which measurably changes verdicts. | |
| Only lines of the form "Term: definition" count. Prose in the preamble is left for | |
| the rendered document, since there is no term to attach it to. | |
| """ | |
| head = (policy_text or "").split("\n## ")[0] | |
| out: list[tuple[str, str]] = [] | |
| for raw in head.splitlines(): | |
| line = raw.strip().lstrip("-* ").strip() | |
| if line.startswith("#") or ":" not in line: | |
| continue | |
| term, _, rest = line.partition(":") | |
| if term and rest.strip() and len(term.split()) <= 4: | |
| out.append((_one_line(term).lower(), _one_line(line))) | |
| return out | |
| def _relevant_definitions(text: str, definitions: list[tuple[str, str]]) -> str: | |
| """The definitions this rule actually relies on. | |
| Attached per rule rather than to all of them: repeating every definition on every | |
| category burns the token budget and tells a model about terms its rule never uses. | |
| A term matches on its longest word ("protected" for "Protected classes"), which | |
| also catches the singular. | |
| """ | |
| lowered = (text or "").lower() | |
| kept = [ | |
| line for term, line in definitions | |
| if any(w for w in sorted(term.split(), key=len, reverse=True)[:1] if w in lowered) | |
| ] | |
| return " ".join(dict.fromkeys(kept)) | |
| def _fold_global(categories: list[dict], global_dont: str, global_exc: str) -> list[dict]: | |
| """Merge policy-wide carve-outs into every category. | |
| PolicyLM scores each category independently, so a "## Applies to all categories" | |
| section β a Don't-flag / Exception clause with no Flag of its own β only takes | |
| effect if it is present in each category. Without this it is dropped (nothing to | |
| score), so PolicyLM flags content the carve-out protects while the prompted models, | |
| reading the whole document, do not. | |
| """ | |
| for cat in categories: | |
| if global_dont: | |
| cat["not_violation_rule"] = " ".join( | |
| p for p in (cat.get("not_violation_rule", ""), global_dont) if p | |
| ) | |
| if global_exc: | |
| cat["exception_override"] = " ".join( | |
| p for p in (cat.get("exception_override", ""), global_exc) if p | |
| ) | |
| return categories | |
| def parse_policy_markdown(policy_text: str, max_categories: int = POLICYLM_MAX_CATEGORIES) -> list[dict]: | |
| """Parse a written policy into PolicyLM categories. | |
| Recognises the "## Name" + "Flag:/Don't flag:/Exception:" shape the workshop | |
| policies use. A section with no Flag line is not its own category (nothing to | |
| score) but, if it carries a Don't-flag / Exception clause (an "applies to all" | |
| carve-out), that clause is folded into every real category rather than dropped. | |
| Returns an empty list when the document has no parseable sections. | |
| """ | |
| definitions = policy_definitions(policy_text) | |
| sections: list[tuple[str, list[str]]] = [] | |
| current: tuple[str, list[str]] | None = None | |
| for line in (policy_text or "").splitlines(): | |
| if line.startswith("## "): | |
| if current: | |
| sections.append(current) | |
| current = (line[3:].strip(), []) | |
| elif current: | |
| current[1].append(line) | |
| if current: | |
| sections.append(current) | |
| categories: list[dict] = [] | |
| global_dont: list[str] = [] | |
| global_exc: list[str] = [] | |
| for name, body in sections: | |
| found: dict[str, str] = {} | |
| for raw in body: | |
| stripped = raw.strip().lstrip("-* ").strip() | |
| lowered = stripped.lower() | |
| for field, prefixes in _FIELD_PREFIXES: | |
| for prefix in prefixes: | |
| if lowered.startswith(prefix) and field not in found: | |
| value = _one_line(stripped[len(prefix):]) | |
| if value: | |
| found[field] = value | |
| if "violation_rule" in found: | |
| entry = {"name": _one_line(name)[:120], **found} | |
| context = _relevant_definitions(" ".join([name, *found.values()]), definitions) | |
| if context: | |
| entry["context"] = context | |
| categories.append(entry) | |
| else: | |
| # Flag-less section = policy-wide guidance; keep its carve-out clauses. | |
| if found.get("not_violation_rule"): | |
| global_dont.append(found["not_violation_rule"]) | |
| if found.get("exception_override"): | |
| global_exc.append(found["exception_override"]) | |
| if len(categories) >= max_categories: | |
| break | |
| return _fold_global(categories, _one_line(" ".join(global_dont)), _one_line(" ".join(global_exc))) | |
| def policy_text_to_categories(policy_text: str, max_categories: int = POLICYLM_MAX_CATEGORIES) -> list[dict]: | |
| """Categories for a free-form policy, always safe to send to PolicyLM. | |
| Falls back to a single flattened catch-all when the document has no recognisable | |
| sections β worse than per-rule scoring, but it runs instead of erroring. | |
| """ | |
| categories = parse_policy_markdown(policy_text, max_categories) | |
| if categories: | |
| # Fold the per-category definition context into the violation rule, the same way | |
| # rules_to_categories does for the editor path. The endpoint handler only reads | |
| # name/violation_rule/not_violation_rule/exception_override and ignores a separate | |
| # "context" key, so on this free-form path (which bypasses the editor) the policy's | |
| # preamble definitions would otherwise never reach PolicyLM. | |
| for cat in categories: | |
| context = cat.pop("context", "") | |
| if context: | |
| cat["violation_rule"] = f"{cat['violation_rule']} ({context})" | |
| return categories | |
| flattened = _one_line(policy_text) | |
| return [{"name": "Policy violation", "violation_rule": flattened}] if flattened else [] | |