privacyprobe 0.2.0__py3-none-any.whl

privacyprobe/__init__.py

@@ -0,0 +1,45 @@
+"""privacyprobe: privacy compliance (DPDP, GDPR) and quality testing for LLM apps."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from privacyprobe.checks import (
+    AgentFlowCheck,
+    BaseCheck,
+    HallucinationCheck,
+    LatencyCheck,
+    PIILeakCheck,
+    PromptInjectionCheck,
+    SchemaCheck,
+    ToxicityCheck,
+)
+from privacyprobe.compliance import ComplianceReport, build_compliance_report
+from privacyprobe.redact import redact
+from privacyprobe.regulations import REGULATIONS
+from privacyprobe.report import generate_report
+from privacyprobe.result import SuiteResult, TestResult
+from privacyprobe.suite import Suite
+
+try:
+    __version__ = version("privacyprobe")
+except PackageNotFoundError:  # running from a source checkout without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "REGULATIONS",
+    "AgentFlowCheck",
+    "BaseCheck",
+    "ComplianceReport",
+    "HallucinationCheck",
+    "LatencyCheck",
+    "PIILeakCheck",
+    "PromptInjectionCheck",
+    "SchemaCheck",
+    "Suite",
+    "SuiteResult",
+    "TestResult",
+    "ToxicityCheck",
+    "__version__",
+    "build_compliance_report",
+    "generate_report",
+    "redact",
+]

privacyprobe/checks/__init__.py

@@ -0,0 +1,31 @@
+"""All built-in checks, importable as ``from privacyprobe.checks import X``."""
+
+from privacyprobe.checks.agent_flow import AgentFlowCheck
+from privacyprobe.checks.base import BaseCheck
+from privacyprobe.checks.hallucination import HallucinationCheck, keyword_overlap
+from privacyprobe.checks.latency import LatencyCheck
+from privacyprobe.checks.pii_leak import PII_PATTERNS, PII_PROFILES, PIILeakCheck, PIIMatch
+from privacyprobe.checks.prompt_injection import (
+    DEFAULT_ATTACKS,
+    DEFAULT_CANARY,
+    PromptInjectionCheck,
+)
+from privacyprobe.checks.responsible_ai import ToxicityCheck
+from privacyprobe.checks.schema_validation import SchemaCheck
+
+__all__ = [
+    "DEFAULT_ATTACKS",
+    "DEFAULT_CANARY",
+    "PII_PATTERNS",
+    "PII_PROFILES",
+    "AgentFlowCheck",
+    "BaseCheck",
+    "HallucinationCheck",
+    "LatencyCheck",
+    "PIILeakCheck",
+    "PIIMatch",
+    "PromptInjectionCheck",
+    "SchemaCheck",
+    "ToxicityCheck",
+    "keyword_overlap",
+]

privacyprobe/checks/agent_flow.py

@@ -0,0 +1,98 @@
+"""Validate state transitions in a multi-step agent pipeline."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Mapping
+from typing import Any, Optional
+
+from privacyprobe.checks.base import BaseCheck
+from privacyprobe.result import TestResult
+
+_STATE_KEYS = ("state", "step", "name", "action", "tool")
+
+
+def _state_of(step: Any) -> str:
+    if isinstance(step, str):
+        return step
+    if isinstance(step, Mapping):
+        for key in _STATE_KEYS:
+            if key in step:
+                return str(step[key])
+    raise ValueError(f"Cannot determine state of trace step: {step!r}")
+
+
+class AgentFlowCheck(BaseCheck):
+    """Checks that an agent's trace follows an allowed state machine.
+
+    The trace is a list of steps, each a state name or a dict with one of the
+    keys ``state``/``step``/``name``/``action``/``tool``. It is read from the
+    ``trace`` keyword (per test case) or, if absent, parsed from the response
+    as a JSON list (or an object with a ``trace``/``steps`` list).
+
+    Args:
+        transitions: ``{state: [allowed next states]}``.
+        start: Required first state.
+        terminal: States the trace is allowed to end on.
+        required: States that must appear somewhere in the trace.
+        max_steps: Fail traces longer than this (catches loops).
+    """
+
+    name = "agent_flow"
+    description = "Validates multi-step agent pipeline state transitions"
+
+    def __init__(
+        self,
+        transitions: Mapping[str, Iterable[str]],
+        start: Optional[str] = None,
+        terminal: Optional[Iterable[str]] = None,
+        required: Optional[Iterable[str]] = None,
+        max_steps: Optional[int] = None,
+    ) -> None:
+        self.transitions = {k: set(v) for k, v in transitions.items()}
+        self.start = start
+        self.terminal = set(terminal) if terminal is not None else None
+        self.required = list(required or ())
+        self.max_steps = max_steps
+
+    def _load_trace(self, response: str, kwargs: dict[str, Any]) -> list[str]:
+        trace = kwargs.get("trace")
+        if trace is None:
+            try:
+                trace = json.loads(response)
+            except json.JSONDecodeError as exc:
+                raise ValueError("No 'trace' given and response is not a JSON trace") from exc
+            if isinstance(trace, Mapping):
+                trace = trace.get("trace", trace.get("steps"))
+        if not isinstance(trace, list):
+            raise ValueError("Agent trace must be a list of steps")
+        return [_state_of(s) for s in trace]
+
+    def run(self, prompt: str, response: str, **kwargs: Any) -> TestResult:
+        states = self._load_trace(response, kwargs)
+        errors: list[str] = []
+        if not states:
+            errors.append("empty trace")
+        if self.start is not None and states and states[0] != self.start:
+            errors.append(f"starts at {states[0]!r}, expected {self.start!r}")
+
+        pairs = list(zip(states, states[1:]))
+        bad = [(a, b) for a, b in pairs if b not in self.transitions.get(a, ())]
+        errors += [f"illegal transition {a!r} -> {b!r}" for a, b in bad]
+
+        if self.terminal is not None and states and states[-1] not in self.terminal:
+            errors.append(f"ends at non-terminal state {states[-1]!r}")
+        missing = [s for s in self.required if s not in states]
+        if missing:
+            errors.append(f"required states never reached: {missing}")
+        if self.max_steps is not None and len(states) > self.max_steps:
+            errors.append(f"{len(states)} steps exceeds max_steps={self.max_steps}")
+
+        score = (len(pairs) - len(bad)) / len(pairs) if pairs else (1.0 if states else 0.0)
+        if errors:
+            return self._result(
+                prompt, response, False, score, "; ".join(errors), trace=states, errors=errors
+            )
+        return self._result(
+            prompt, response, True, 1.0, f"Valid flow: {' -> '.join(states)}", trace=states
+        )

privacyprobe/checks/base.py

@@ -0,0 +1,60 @@
+"""Abstract base class shared by every privacyprobe check."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+from privacyprobe.result import TestResult
+
+
+class BaseCheck(ABC):
+    """Every check inherits from this and must implement :meth:`run`.
+
+    Subclasses set ``name`` and ``description`` as class attributes. ``run``
+    receives the prompt, the model's response, and any extra fields from the
+    test case (e.g. ``facts``, ``latency``) as keyword arguments. Checks must
+    accept and ignore keyword arguments they do not use.
+
+    ``clauses`` maps regulation keys to the clauses this check produces evidence
+    for, e.g. ``{"gdpr": ("Art. 9",)}``. It is stamped onto every result as
+    ``metadata["clauses"]`` and used by compliance reports.
+    """
+
+    name: str = "base"
+    description: str = ""
+    clauses: Mapping[str, tuple[str, ...]] = MappingProxyType({})
+
+    @abstractmethod
+    def run(self, prompt: str, response: str, **kwargs: Any) -> TestResult:
+        """Run this check. Returns a TestResult with pass/fail + details."""
+
+    def _result(
+        self,
+        prompt: str,
+        response: str,
+        passed: bool,
+        score: float,
+        details: str,
+        **metadata: Any,
+    ) -> TestResult:
+        """Build a TestResult stamped with this check's name and clauses."""
+        if self.clauses:
+            metadata.setdefault("clauses", self.clause_map())
+        return TestResult(
+            check_name=self.name,
+            passed=passed,
+            score=max(0.0, min(1.0, float(score))),
+            details=details,
+            prompt=prompt,
+            response=response,
+            metadata=metadata,
+        )
+
+    def clause_map(self) -> dict[str, list[str]]:
+        return {reg: list(ids) for reg, ids in self.clauses.items()}
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}()"

privacyprobe/checks/hallucination.py

@@ -0,0 +1,113 @@
+"""Check an LLM response for factual consistency with ground-truth facts."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from typing import Any, Callable, Optional, Union
+
+from privacyprobe.checks.base import BaseCheck
+from privacyprobe.regulations import CHECK_CLAUSES
+from privacyprobe.result import TestResult
+
+_TOKEN_RE = re.compile(r"[a-z0-9]+(?:[.'][a-z0-9]+)*")
+
+STOPWORDS = frozenset(
+    """a an the and or but if then of to in on at by for with from as is are was were be
+    been being it its this that these those there their they he she his her him we our you
+    your i me my do does did has have had not no so than too very can will would should
+    could may might must about into over under also just which who whom what when where why
+    how all any each some such only own same other more most""".split()
+)
+
+
+def _content_tokens(text: str) -> set[str]:
+    return {t for t in _TOKEN_RE.findall(text.lower()) if t not in STOPWORDS}
+
+
+def keyword_overlap(fact: str, response: str) -> float:
+    """Fraction of the fact's content words that appear in the response (0.0-1.0)."""
+    fact_tokens = _content_tokens(fact)
+    if not fact_tokens:
+        return 1.0
+    return len(fact_tokens & _content_tokens(response)) / len(fact_tokens)
+
+
+class HallucinationCheck(BaseCheck):
+    """Scores how well a response is supported by ground-truth facts.
+
+    Each fact counts as *supported* when ``similarity_fn(fact, response)`` is at
+    least ``fact_threshold``. The score is the fraction of supported facts, and
+    the check passes when the score is at least ``threshold`` and no
+    ``forbidden`` statement (a known-false claim) appears in the response.
+
+    By default similarity is keyword overlap. Pass ``similarity_fn`` to plug in
+    semantic similarity (e.g. embedding cosine similarity) without adding
+    dependencies to privacyprobe itself.
+
+    Facts and forbidden claims can be given here or per test case via the
+    ``facts`` / ``forbidden`` keys; per-case values take precedence.
+    """
+
+    name = "hallucination"
+    clauses = CHECK_CLAUSES["hallucination"]
+    description = "Compares response against ground truth facts using keyword/semantic overlap"
+
+    def __init__(
+        self,
+        facts: Optional[Union[str, Sequence[str]]] = None,
+        threshold: float = 1.0,
+        fact_threshold: float = 0.8,
+        forbidden: Optional[Sequence[str]] = None,
+        similarity_fn: Optional[Callable[[str, str], float]] = None,
+    ) -> None:
+        if not 0.0 <= threshold <= 1.0 or not 0.0 <= fact_threshold <= 1.0:
+            raise ValueError("threshold and fact_threshold must be between 0.0 and 1.0")
+        self.facts = facts
+        self.threshold = threshold
+        self.fact_threshold = fact_threshold
+        self.forbidden = forbidden
+        self.similarity_fn = similarity_fn or keyword_overlap
+
+    @staticmethod
+    def _as_list(value: Optional[Union[str, Sequence[str]]]) -> list[str]:
+        if value is None:
+            return []
+        return [value] if isinstance(value, str) else list(value)
+
+    def run(self, prompt: str, response: str, **kwargs: Any) -> TestResult:
+        facts = self._as_list(kwargs.get("facts", self.facts))
+        forbidden = self._as_list(kwargs.get("forbidden", self.forbidden))
+        if not facts and not forbidden:
+            raise ValueError(
+                "HallucinationCheck needs ground truth: pass facts=/forbidden= to the "
+                "check or add a 'facts' key to the test case"
+            )
+
+        scores = {fact: self.similarity_fn(fact, response) for fact in facts}
+        unsupported = [f for f, s in scores.items() if s < self.fact_threshold]
+        contradicted = [
+            f for f in forbidden if self.similarity_fn(f, response) >= self.fact_threshold
+        ]
+
+        score = (len(facts) - len(unsupported)) / len(facts) if facts else 1.0
+        if contradicted:
+            score = 0.0
+        passed = score >= self.threshold and not contradicted
+
+        problems = []
+        if unsupported:
+            problems.append(f"{len(unsupported)}/{len(facts)} facts unsupported: {unsupported}")
+        if contradicted:
+            problems.append(f"forbidden claims present: {contradicted}")
+        details = "; ".join(problems) if problems else f"All {len(facts)} facts supported"
+        return self._result(
+            prompt,
+            response,
+            passed,
+            score,
+            details,
+            fact_scores=scores,
+            unsupported=unsupported,
+            contradicted=contradicted,
+        )

privacyprobe/checks/latency.py

@@ -0,0 +1,47 @@
+"""Flag responses that take longer than a threshold."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from privacyprobe.checks.base import BaseCheck
+from privacyprobe.result import TestResult
+
+
+class LatencyCheck(BaseCheck):
+    """Fails when response time exceeds ``max_seconds``.
+
+    :class:`~privacyprobe.Suite` measures the model call and passes it as the
+    ``latency`` keyword (seconds). When responses are supplied pre-computed in
+    the test case, include a ``latency`` key yourself.
+    """
+
+    name = "latency"
+    description = "Measures response time, flags if over threshold"
+
+    def __init__(self, max_seconds: float = 2.0) -> None:
+        if max_seconds <= 0:
+            raise ValueError("max_seconds must be positive")
+        self.max_seconds = max_seconds
+
+    def run(self, prompt: str, response: str, **kwargs: Any) -> TestResult:
+        latency = kwargs.get("latency")
+        if latency is None:
+            raise ValueError(
+                "No latency measured: run via Suite with a model, or add 'latency' to the test case"
+            )
+        latency = float(latency)
+        passed = latency <= self.max_seconds
+        score = 1.0 if passed else self.max_seconds / latency
+        verdict = "within" if passed else "exceeds"
+        return self._result(
+            prompt,
+            response,
+            passed,
+            score,
+            f"{latency:.3f}s {verdict} limit of {self.max_seconds:.3f}s",
+            latency=latency,
+        )
+
+    def __repr__(self) -> str:
+        return f"LatencyCheck(max_seconds={self.max_seconds})"