znyx-core 1.0.0__tar.gz

znyx_core-1.0.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: znyx-core
+Version: 1.0.0
+Summary: Znyx guardrails detection engine: detectors, policy resolution, and orchestration for LLM safety, usable in-process.
+Author: Zitrino
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/zitrino-oss/znyx-runtime
+Project-URL: Source, https://github.com/zitrino-oss/znyx-runtime
+Project-URL: Issues, https://github.com/zitrino-oss/znyx-runtime/issues
+Keywords: llm,guardrails,safety,ai-security,prompt-injection,pii,content-moderation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rapidfuzz>=3.6.0
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: fastapi>=0.109.0
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
+
+# znyx-core
+
+The Znyx guardrails detection engine: detectors, policy resolution, scoring, and
+orchestration for LLM safety. Importable in-process, with no server or HTTP hop.
+
+```bash
+pip install znyx-core
+```
+
+`znyx-core` is the engine that powers the [`znyx-runtime`](https://github.com/zitrino-oss/znyx-runtime)
+service. Install it directly when you want to run detection inside your own Python
+process rather than calling the runtime over HTTP.
+
+It runs rules-only by default. Model-backed (ML) detection is an optional layer
+served by a separate Znyx inference sidecar over HTTP; without it, every detector
+has a deterministic rules path.
+
+See the [repository README](https://github.com/zitrino-oss/znyx-runtime) for
+configuration, the policy schema, and usage examples.
+
+## License
+
+Apache-2.0

znyx_core-1.0.0/README.md

@@ -0,0 +1,23 @@
+# znyx-core
+
+The Znyx guardrails detection engine: detectors, policy resolution, scoring, and
+orchestration for LLM safety. Importable in-process, with no server or HTTP hop.
+
+```bash
+pip install znyx-core
+```
+
+`znyx-core` is the engine that powers the [`znyx-runtime`](https://github.com/zitrino-oss/znyx-runtime)
+service. Install it directly when you want to run detection inside your own Python
+process rather than calling the runtime over HTTP.
+
+It runs rules-only by default. Model-backed (ML) detection is an optional layer
+served by a separate Znyx inference sidecar over HTTP; without it, every detector
+has a deterministic rules path.
+
+See the [repository README](https://github.com/zitrino-oss/znyx-runtime) for
+configuration, the policy schema, and usage examples.
+
+## License
+
+Apache-2.0

znyx_core-1.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "znyx-core"
+version = "1.0.0"
+description = "Znyx guardrails detection engine: detectors, policy resolution, and orchestration for LLM safety, usable in-process."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Zitrino" }]
+keywords = ["llm", "guardrails", "safety", "ai-security", "prompt-injection", "pii", "content-moderation"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "pydantic>=2.5.0",
+  "pyyaml>=6.0",
+  "rapidfuzz>=3.6.0",
+  "httpx>=0.26.0",
+  "cryptography>=41.0.0",
+  "defusedxml>=0.7.1",
+  "fastapi>=0.109.0",
+]
+
+[project.optional-dependencies]
+# The hallucination / groundedness detector uses sentence-transformers when
+# present, and falls back to a token-overlap heuristic when it is not installed.
+semantic = ["sentence-transformers>=2.2.0"]
+
+[project.urls]
+Homepage = "https://github.com/zitrino-oss/znyx-runtime"
+Source = "https://github.com/zitrino-oss/znyx-runtime"
+Issues = "https://github.com/zitrino-oss/znyx-runtime/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+znyx_core = ["**/*.yaml", "**/*.yml", "**/*.json"]

znyx_core-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

znyx_core-1.0.0/src/znyx_core/config/tunables.py

@@ -0,0 +1,194 @@
+"""Centralised numeric tunables — single source of truth for thresholds,
+batch sizes, retry counts, and timeout windows.
+
+Adding a new constant here is preferable to inlining a number in service
+code for three reasons:
+
+1. **Discoverability.** A new engineer can grep one file to learn what
+   knobs exist and what their defaults are.
+2. **Override surface.** Every value reads from an env var with a sensible
+   default — ops never has to redeploy to retune a quota.
+3. **Type/range safety.** The casts (``int(os.getenv(..., default))``) live
+   in one place; adding a min/max guard is one edit, not a campaign.
+
+Convention: every setting is ``UPPER_SNAKE_CASE``, exposed as a module-level
+constant. Group by subsystem with a comment header. When a service consumes
+one, prefer ``from znyx_core.config.tunables import RETRY_DELAYS_SECONDS`` over
+duplicating the literal value.
+"""
+from __future__ import annotations
+
+import os
+from typing import Tuple
+
+
+def _int(env: str, default: int) -> int:
+    try:
+        return int(os.getenv(env, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+def _float(env: str, default: float) -> float:
+    try:
+        return float(os.getenv(env, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
+def _str(env: str, default: str = "") -> str:
+    return os.getenv(env, default)
+
+
+def _bool(env: str, default: bool = False) -> bool:
+    raw = os.getenv(env)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes")
+
+
+def _csv_floats(env: str, default: Tuple[float, ...]) -> Tuple[float, ...]:
+    raw = os.getenv(env)
+    if not raw:
+        return default
+    try:
+        return tuple(float(x.strip()) for x in raw.split(",") if x.strip())
+    except (TypeError, ValueError):
+        return default
+
+
+# ---------------------------------------------------------------------------
+# Webhook delivery
+# ---------------------------------------------------------------------------
+WEBHOOK_MAX_RETRIES: int = _int("ZNYX_WEBHOOK_MAX_RETRIES", 3)
+WEBHOOK_RETRY_DELAYS_SECONDS: Tuple[float, ...] = _csv_floats(
+    "ZNYX_WEBHOOK_RETRY_DELAYS", (1.0, 5.0, 30.0)
+)
+WEBHOOK_REQUEST_TIMEOUT_SECONDS: float = _float("ZNYX_WEBHOOK_TIMEOUT", 10.0)
+
+
+# ---------------------------------------------------------------------------
+# Runtime telemetry batching
+# ---------------------------------------------------------------------------
+TELEMETRY_BATCH_SIZE: int = _int("ZNYX_TELEMETRY_BATCH_SIZE", 100)
+TELEMETRY_FLUSH_INTERVAL_SECONDS: int = _int("ZNYX_TELEMETRY_FLUSH_INTERVAL", 10)
+
+
+# ---------------------------------------------------------------------------
+# Bundle manager
+# ---------------------------------------------------------------------------
+BUNDLE_BOOT_RETRY_DELAYS_SECONDS: Tuple[float, ...] = _csv_floats(
+    "ZNYX_BUNDLE_BOOT_RETRY_DELAYS", (1.0, 3.0, 5.0)
+)
+BUNDLE_POLL_INTERVAL_SECONDS: float = _float("ZNYX_BUNDLE_POLL_INTERVAL", 30.0)
+
+
+# ---------------------------------------------------------------------------
+# Billing — subscription state machine
+# ---------------------------------------------------------------------------
+BILLING_GRACE_DAYS: int = _int("ZNYX_BILLING_GRACE_DAYS", 7)
+# DEPRECATED: trials are removed — no plan grants a trial and nothing reads
+# this value anymore. Kept only so existing env/config files don't error.
+# The ``trialing`` status is left inert for any pre-existing trialing orgs.
+BILLING_TRIAL_DAYS: int = _int("ZNYX_BILLING_TRIAL_DAYS", 14)
+
+
+# ---------------------------------------------------------------------------
+# Retention defaults (per plan, in days). Keep alongside other tunables so
+# ops can override per-tier without editing the service body.
+# ---------------------------------------------------------------------------
+RETENTION_FREE_DAYS: int = _int("ZNYX_RETENTION_FREE_DAYS", 30)
+RETENTION_GROWTH_DAYS: int = _int("ZNYX_RETENTION_GROWTH_DAYS", 90)
+RETENTION_ENTERPRISE_DAYS: int = _int("ZNYX_RETENTION_ENTERPRISE_DAYS", 365)
+
+
+# ---------------------------------------------------------------------------
+# Auth / brute-force protection
+# ---------------------------------------------------------------------------
+AUTH_MAX_FAILED_ATTEMPTS: int = _int("MAX_FAILED_LOGIN_ATTEMPTS", 10)
+AUTH_LOCKOUT_DURATION_MINUTES: int = _int("LOGIN_LOCKOUT_MINUTES", 15)
+AUTH_LOGIN_RATE_LIMIT_PER_MINUTE: int = _int("LOGIN_RATE_LIMIT_PER_MINUTE", 10)
+AUTH_REGISTER_RATE_LIMIT_PER_MINUTE: int = _int("REGISTER_RATE_LIMIT_PER_MINUTE", 5)
+
+
+# ---------------------------------------------------------------------------
+# Remote detector HTTP client
+# ---------------------------------------------------------------------------
+REMOTE_DETECTOR_TIMEOUT_SECONDS: float = _float("ZNYX_REMOTE_DETECTOR_TIMEOUT", 5.0)
+REMOTE_DETECTOR_MAX_RETRIES: int = _int("ZNYX_REMOTE_DETECTOR_MAX_RETRIES", 2)
+REMOTE_DETECTOR_CIRCUIT_THRESHOLD: int = _int(
+    "ZNYX_REMOTE_DETECTOR_CIRCUIT_THRESHOLD", 5
+)
+
+
+# ---------------------------------------------------------------------------
+# Scheduler intervals (seconds)
+# ---------------------------------------------------------------------------
+SCHEDULER_RETENTION_INTERVAL_SECONDS: int = _int("SCHEDULER_RETENTION_INTERVAL", 3600)
+SCHEDULER_ALERT_INTERVAL_SECONDS: int = _int("SCHEDULER_ALERT_INTERVAL", 300)
+SCHEDULER_SUBSCRIPTION_INTERVAL_SECONDS: int = _int(
+    "SCHEDULER_SUBSCRIPTION_INTERVAL", 3600
+)
+# Auto-invoice generation: how often to check for ended billing periods.
+SCHEDULER_BILLING_INTERVAL_SECONDS: int = _int("SCHEDULER_BILLING_INTERVAL", 3600)
+# egress audit: how often to fold the durable egress spool into egress_events rows
+# (read endpoints also drain on demand; this keeps the table fresh without a read).
+SCHEDULER_EGRESS_DRAIN_INTERVAL_SECONDS: int = _int("SCHEDULER_EGRESS_DRAIN_INTERVAL", 60)
+
+
+# ---------------------------------------------------------------------------
+# Pagination defaults
+# ---------------------------------------------------------------------------
+DEFAULT_PAGE_SIZE: int = _int("ZNYX_DEFAULT_PAGE_SIZE", 50)
+MAX_PAGE_SIZE: int = _int("ZNYX_MAX_PAGE_SIZE", 200)
+
+
+# ---------------------------------------------------------------------------
+# Database connection pool
+# ---------------------------------------------------------------------------
+DB_POOL_SIZE: int = _int("DB_POOL_SIZE", 20)
+DB_MAX_OVERFLOW: int = _int("DB_MAX_OVERFLOW", 40)
+
+
+# ---------------------------------------------------------------------------
+# HTTP rate limiter (per-IP / per-key sliding window)
+# ---------------------------------------------------------------------------
+RATE_LIMIT_REQUESTS_PER_MINUTE: int = _int("RATE_LIMIT_REQUESTS_PER_MINUTE", 60)
+RATE_LIMIT_BURST: int = _int("RATE_LIMIT_BURST", 10)
+
+
+# ---------------------------------------------------------------------------
+# Server ports
+# ---------------------------------------------------------------------------
+CONTROL_PLANE_PORT: int = _int("CONTROL_PLANE_PORT", _int("PORT", 8000))
+RUNTIME_PORT: int = _int("RUNTIME_PORT", _int("PORT", 8080))
+
+
+# ---------------------------------------------------------------------------
+# Email — Microsoft Graph API
+# ---------------------------------------------------------------------------
+MS_GRAPH_TENANT_ID: str = _str("MICROSOFT_TENANT_ID", "")
+MS_GRAPH_CLIENT_ID: str = _str("MICROSOFT_CLIENT_ID", "")
+MS_GRAPH_CLIENT_SECRET: str = _str("MICROSOFT_CLIENT_SECRET", "")
+MS_GRAPH_SENDER_EMAIL: str = _str("MICROSOFT_SENDER_EMAIL", "")
+EMAIL_FROM_NAME: str = _str("EMAIL_FROM_NAME", "ZNYX Guardrails")
+# Inbox that website contact-form enquiries (POST /v1/contact) are delivered to.
+# Mirrors the website's NEXT_PUBLIC_ENQUIRY_EMAIL default.
+CONTACT_ENQUIRY_EMAIL: str = _str("CONTACT_ENQUIRY_EMAIL", "").strip()
+# NB: a *present but empty* env var (e.g. an unset GitHub Actions variable
+# expanded into a ConfigMap as CONSOLE_BASE_URL='') makes os.getenv return ""
+# rather than the default, which would yield relative links like
+# "/console/verify-email?..." in emails — broken in Outlook and other clients.
+# Strip + `or default` so an empty value still resolves to an absolute URL.
+CONSOLE_BASE_URL: str = _str("CONSOLE_BASE_URL", "").strip().rstrip("/") or "http://localhost:3701"
+PASSWORD_RESET_EXPIRES_MINUTES: int = _int("PASSWORD_RESET_EXPIRES_MINUTES", 60)
+
+
+# ---------------------------------------------------------------------------
+# Azure Storage
+# ---------------------------------------------------------------------------
+AZURE_STORAGE_ACCOUNT_NAME: str = _str("AZURE_STORAGE_ACCOUNT_NAME", "")
+AZURE_STORAGE_ACCOUNT_KEY: str = _str("AZURE_STORAGE_ACCOUNT_KEY", "")
+AZURE_STORAGE_CONTAINER_NAME: str = _str("AZURE_STORAGE_CONTAINER_NAME", "")
+AZURE_PUBLIC_STORAGE_CONTAINER: str = _str("AZURE_PUBLIC_STORAGE_CONTAINER", "publicmailtemplates")
+KEY_VAULT_NAME: str = _str("KEY_VAULT_NAME", "")

znyx_core-1.0.0/src/znyx_core/core/__init__.py

@@ -0,0 +1 @@
+# Core module

znyx_core-1.0.0/src/znyx_core/core/decision.py

@@ -0,0 +1,68 @@
+from typing import List
+from znyx_core.core.models import Decision, DetectorResult, RuleHit
+from znyx_core.core.labels import DECISION_PRECEDENCE
+
+
+class DecisionAggregator:
+    """Aggregates detector results into a final decision"""
+
+    # Canonical "worst wins" ranking (BLOCK > REDACT > TRANSFORM > WARN > ALLOW),
+    # defined once in core.labels so the aggregator, trace UI, and docs agree.
+    DECISION_PRIORITY = DECISION_PRECEDENCE
+
+    @staticmethod
+    def aggregate(results: List[DetectorResult]) -> DetectorResult:
+        """
+        Aggregate multiple detector results into a single result.
+        Uses highest priority decision and combines all rule hits.
+        """
+        if not results:
+            return DetectorResult(
+                decision=Decision.ALLOW,
+                risk_score=0,
+                rule_hits=[],
+                sanitized_text=None,
+                user_message=None,
+                developer_message=None
+            )
+
+        # Combine all rule hits
+        all_rule_hits: List[RuleHit] = []
+        for result in results:
+            all_rule_hits.extend(result.rule_hits)
+
+        # Calculate max risk score
+        max_risk_score = max((r.risk_score for r in results), default=0)
+
+        # Find highest priority decision
+        highest_decision = Decision.ALLOW
+        highest_priority = 0
+        selected_result = None
+
+        for result in results:
+            if result.decision:
+                priority = DecisionAggregator.DECISION_PRIORITY.get(result.decision, 0)
+                if priority > highest_priority:
+                    highest_priority = priority
+                    highest_decision = result.decision
+                    selected_result = result
+
+        # Use sanitized/transformed text and messages from the selected result
+        sanitized_text = selected_result.sanitized_text if selected_result else None
+        user_message = selected_result.user_message if selected_result else None
+        developer_message = selected_result.developer_message if selected_result else None
+
+        # If we have multiple results with text transformations, use the last one
+        # (this handles chaining of transformations)
+        for result in results:
+            if result.sanitized_text and result.decision in [Decision.REDACT, Decision.TRANSFORM]:
+                sanitized_text = result.sanitized_text
+
+        return DetectorResult(
+            decision=highest_decision,
+            risk_score=max_risk_score,
+            rule_hits=all_rule_hits,
+            sanitized_text=sanitized_text,
+            user_message=user_message,
+            developer_message=developer_message
+        )

znyx_core-1.0.0/src/znyx_core/core/fingerprint.py

@@ -0,0 +1,48 @@
+"""Keyed shingle fingerprinting (OWASP LLM07 system-prompt leakage).
+
+Privacy-preserving fingerprints: a system prompt is reduced to a set of **keyed**
+hashes of its overlapping token n-grams ("shingles"). The raw prompt is never stored —
+only ``HMAC-SHA256(per_org_key, shingle)`` digests. Detection HMACs the candidate
+output's shingles with the SAME per-org key and counts how many match.
+
+A per-org key (pepper) means digests are not comparable across orgs and resist offline
+dictionary attack; the ``min_shingle_tokens`` floor (≥8) means trivially-guessable short
+fragments are never fingerprinted. This module is dependency-free (stdlib only) so both
+the control plane (builds fingerprints) and the runtime detector (matches) share it.
+"""
+from __future__ import annotations
+
+import hmac
+import re
+from hashlib import sha256
+from typing import List, Set
+
+DEFAULT_MIN_SHINGLE_TOKENS = 8
+_DIGEST_HEX = 32  # truncated 128-bit digest — compact for JSONB, ample collision margin
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+
+def tokenize(text: str) -> List[str]:
+    return _TOKEN_RE.findall((text or "").lower())
+
+
+def _shingles(tokens: List[str], n: int) -> List[str]:
+    if n <= 0 or len(tokens) < n:
+        return []
+    return [" ".join(tokens[i:i + n]) for i in range(len(tokens) - n + 1)]
+
+
+def shingle_hashes(text: str, key: bytes, min_shingle_tokens: int = DEFAULT_MIN_SHINGLE_TOKENS) -> Set[str]:
+    """Keyed digests of every ``min_shingle_tokens``-token shingle in ``text``.
+    Returns an empty set when the text is too short to fingerprint."""
+    out: Set[str] = set()
+    for sh in _shingles(tokenize(text), min_shingle_tokens):
+        out.add(hmac.new(key, sh.encode("utf-8"), sha256).hexdigest()[:_DIGEST_HEX])
+    return out
+
+
+def overlap_count(text: str, key: bytes, min_shingle_tokens: int, known: Set[str]) -> int:
+    """How many of ``text``'s keyed shingle digests are in the ``known`` set."""
+    if not known:
+        return 0
+    return len(shingle_hashes(text, key, min_shingle_tokens) & set(known))

znyx_core-1.0.0/src/znyx_core/core/labels.py

@@ -0,0 +1,125 @@
+"""Canonical label / score semantics.
+
+The single source of truth for how ZNYX labels things, so every layer, the aggregator,
+the trace UI, scorecards, model cards, and benchmark scoring agree:
+
+  * **Decision set + precedence** — the 5 decisions and their "worst wins" ranking.
+  * **Severity ↔ risk bands** — the 3 severities and their 0–100 risk bands.
+  * **Confidence bands** — coarse 0–1 confidence buckets.
+  * **Score normalization** — mapping each layer's native score onto one 0–100 scale.
+
+Documented for humans in ``docs/label-semantics.md`` (keep the two in sync — the doc
+quotes these constants). Answers the research question "how to normalize scores
+across layers".
+"""
+from __future__ import annotations
+
+from enum import Enum
+
+from znyx_core.core.models import Decision, Severity
+
+
+class ConfidenceBand(str, Enum):
+    """Coarse confidence buckets for display/triage. Thresholds are inclusive-low."""
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+# ── Decision set + precedence ────────────────────────────────────────────────
+# The canonical "worst wins" ranking used when aggregating detector results
+# (BLOCK > REDACT > TRANSFORM > WARN > ALLOW). The DecisionAggregator imports this so
+# there is exactly one ordering in the system.
+DECISION_PRECEDENCE = {
+    Decision.BLOCK: 5,
+    Decision.REDACT: 4,
+    Decision.TRANSFORM: 3,
+    Decision.WARN: 2,
+    Decision.ALLOW: 1,
+}
+
+# Human-facing meaning of each decision (model cards / docs / UI tooltips).
+DECISION_SEMANTICS = {
+    Decision.ALLOW: "No action — content passes unchanged.",
+    Decision.WARN: "Allowed, but flagged for observability/telemetry; does not modify or stop.",
+    Decision.TRANSFORM: "Content is rewritten (e.g. reformatted to a contract) before passing.",
+    Decision.REDACT: "Sensitive spans are masked; the redacted content passes.",
+    Decision.BLOCK: "Content is stopped; it does not pass.",
+}
+
+
+def decision_rank(decision: Decision | None) -> int:
+    """Precedence rank of a decision (higher = more severe). None/unknown → 0."""
+    return DECISION_PRECEDENCE.get(decision, 0) if decision else 0
+
+
+def most_severe_decision(decisions) -> Decision:
+    """The highest-precedence decision in an iterable (empty → ALLOW)."""
+    best, best_rank = Decision.ALLOW, 0
+    for d in decisions:
+        r = decision_rank(d)
+        if r > best_rank:
+            best, best_rank = d, r
+    return best
+
+
+# ── Severity ↔ risk bands ────────────────────────────────────────────────────
+# Representative 0-100 risk for each severity (used when a layer reports only a
+# severity, e.g. a deterministic rule hit, and a numeric risk is needed).
+SEVERITY_TO_RISK = {
+    Severity.LOW: 25,
+    Severity.MEDIUM: 60,
+    Severity.HIGH: 90,
+}
+
+# Inclusive-low boundaries that bucket a 0-100 risk score back into a severity.
+RISK_BAND_MEDIUM_MIN = 40
+RISK_BAND_HIGH_MIN = 80
+
+# Inclusive-low boundaries that bucket a 0-1 confidence into a ConfidenceBand.
+CONFIDENCE_BAND_MEDIUM_MIN = 0.5
+CONFIDENCE_BAND_HIGH_MIN = 0.8
+
+
+def confidence_band(confidence: float | None) -> ConfidenceBand | None:
+    """Bucket a 0..1 confidence. None → None (no model confidence available)."""
+    if confidence is None:
+        return None
+    c = min(1.0, max(0.0, float(confidence)))
+    if c < CONFIDENCE_BAND_MEDIUM_MIN:
+        return ConfidenceBand.LOW
+    if c < CONFIDENCE_BAND_HIGH_MIN:
+        return ConfidenceBand.MEDIUM
+    return ConfidenceBand.HIGH
+
+
+def severity_to_risk(severity: Severity) -> int:
+    return SEVERITY_TO_RISK.get(severity, 60)
+
+
+def risk_to_severity(risk: float) -> Severity:
+    r = min(100.0, max(0.0, float(risk)))
+    if r >= RISK_BAND_HIGH_MIN:
+        return Severity.HIGH
+    if r >= RISK_BAND_MEDIUM_MIN:
+        return Severity.MEDIUM
+    return Severity.LOW
+
+
+def normalize_risk(value: float, kind: str = "deterministic") -> int:
+    """Map a layer's native score onto the common 0..100 risk scale.
+
+    - ``deterministic`` / ``judge``: already a 0..100 risk score — clamp.
+    - ``ml`` / ``embedding`` / ``probability``: a 0..1 probability — ×100 then clamp
+      ( "ML probability ×100"). Probabilities are clamped to [0,1] upstream.
+
+    Keeps the aggregator's "worst decision wins" intact while letting each layer
+    record both its native and normalized score for divergence analysis.
+    """
+    if value is None:
+        return 0
+    v = float(value)
+    kind = (kind or "deterministic").lower()
+    if kind in ("ml", "embedding", "probability"):
+        v *= 100.0
+    return int(round(min(100.0, max(0.0, v))))