policyaware 0.2.0__py3-none-any.whl

policyaware/__init__.py

@@ -0,0 +1,46 @@
+from policyaware.gateway import Gateway
+from policyaware.models import (
+    GatewayRequest,
+    GatewayResponse,
+    ModelCandidate,
+    PolicyDecision,
+    RiskAssessment,
+    ToolDecision,
+)
+from policyaware.providers import (
+    AnthropicProvider,
+    AzureOpenAIProvider,
+    BedrockProvider,
+    OllamaProvider,
+    OpenAICompatibleProvider,
+    ProviderRegistry,
+    SimulatedProvider,
+    VLLMProvider,
+    VertexAIProvider,
+    default_provider_registry,
+)
+from policyaware.tools import ToolPolicyEngine, ToolRegistry
+from policyaware.risk import RiskClassifier
+
+__all__ = [
+    "Gateway",
+    "GatewayRequest",
+    "GatewayResponse",
+    "ModelCandidate",
+    "PolicyDecision",
+    "RiskAssessment",
+    "RiskClassifier",
+    "OpenAICompatibleProvider",
+    "AzureOpenAIProvider",
+    "AnthropicProvider",
+    "BedrockProvider",
+    "VertexAIProvider",
+    "OllamaProvider",
+    "VLLMProvider",
+    "ProviderRegistry",
+    "default_provider_registry",
+    "SimulatedProvider",
+    "ToolDecision",
+    "ToolPolicyEngine",
+    "ToolRegistry",
+]

policyaware/approvals.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from pathlib import Path
+from urllib import request as urlrequest
+
+from policyaware.models import ApprovalRequest, GatewayRequest, PolicyDecision
+
+
+class ApprovalClient(ABC):
+    @abstractmethod
+    def submit(self, request: GatewayRequest, decision: PolicyDecision) -> ApprovalRequest:
+        raise NotImplementedError
+
+
+class NoopApprovalClient(ApprovalClient):
+    def submit(self, request: GatewayRequest, decision: PolicyDecision) -> ApprovalRequest:
+        return ApprovalRequest(
+            tenant=request.tenant,
+            app=request.app,
+            user=request.user,
+            decision=decision,
+            request_snapshot=request.model_dump(mode="json"),
+        )
+
+
+class FileApprovalClient(ApprovalClient):
+    def __init__(self, path: str | Path = ".policyaware/approvals.jsonl"):
+        self.path = Path(path)
+
+    def submit(self, request: GatewayRequest, decision: PolicyDecision) -> ApprovalRequest:
+        approval = ApprovalRequest(
+            tenant=request.tenant,
+            app=request.app,
+            user=request.user,
+            decision=decision,
+            request_snapshot=request.model_dump(mode="json"),
+        )
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(approval.model_dump_json() + "\n")
+        return approval
+
+
+class WebhookApprovalClient(ApprovalClient):
+    def __init__(self, url: str, timeout_seconds: int = 15):
+        self.url = url
+        self.timeout_seconds = timeout_seconds
+
+    def submit(self, request: GatewayRequest, decision: PolicyDecision) -> ApprovalRequest:
+        approval = ApprovalRequest(
+            tenant=request.tenant,
+            app=request.app,
+            user=request.user,
+            decision=decision,
+            request_snapshot=request.model_dump(mode="json"),
+        )
+        body = json.dumps(approval.model_dump(mode="json")).encode("utf-8")
+        req = urlrequest.Request(
+            self.url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urlrequest.urlopen(req, timeout=self.timeout_seconds):
+            pass
+        return approval

policyaware/audit.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+from policyaware.models import AuditTrace, GatewayRequest, GatewayResponse
+
+
+def estimate_tokens(text: str) -> int:
+    return max(1, len(text.split()))
+
+
+class AuditLogger:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else None
+
+    def record(self, request: GatewayRequest, response: GatewayResponse, started_at: float) -> AuditTrace:
+        input_tokens = estimate_tokens(request.prompt_text)
+        output_tokens = estimate_tokens(response.content)
+        model = response.route.model if response.route else None
+        trace = AuditTrace(
+            trace_id=response.trace_id,
+            request_id=request.request_id,
+            tenant=request.tenant,
+            app=request.app,
+            user_id=request.user.get("id"),
+            task_type=request.context.get("task_type"),
+            policy_decision=response.policy.decision.value,
+            matched_rules=response.policy.matched_rules,
+            reason_codes=response.policy.reason_codes,
+            actions=response.policy.actions,
+            risk_tier=response.policy.risk_tier.value,
+            model=model.name if model else None,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            estimated_cost_usd=((input_tokens + output_tokens) / 1000)
+            * (model.cost_per_1k_tokens if model else 0),
+            latency_ms=int((time.perf_counter() - started_at) * 1000),
+            risk_score=response.policy.risk_score,
+            eval_scores={result.name: result.score for result in response.evals},
+            request_snapshot=request.model_dump(mode="json"),
+            response_snapshot={
+                "content": response.content,
+                "policy": response.policy.model_dump(mode="json"),
+                "route": response.route.model_dump(mode="json") if response.route else None,
+                "evals": [result.model_dump(mode="json") for result in response.evals],
+            },
+        )
+        if self.path:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as handle:
+                handle.write(trace.model_dump_json() + "\n")
+        return trace
+
+    def export_jsonl(self, traces: list[AuditTrace], path: str | Path) -> None:
+        output = Path(path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        with output.open("w", encoding="utf-8") as handle:
+            for trace in traces:
+                handle.write(json.dumps(trace.model_dump(mode="json")) + "\n")
+
+    def read_traces(self) -> list[dict[str, Any]]:
+        if not self.path or not self.path.exists():
+            return []
+        traces: list[dict[str, Any]] = []
+        with self.path.open("r", encoding="utf-8") as handle:
+            for line in handle:
+                if line.strip():
+                    traces.append(json.loads(line))
+        return traces
+
+    def find_trace(self, trace_id: str) -> dict[str, Any] | None:
+        for trace in self.read_traces():
+            if trace.get("trace_id") == trace_id:
+                return trace
+        return None
+
+
+class SQLiteAuditLogger(AuditLogger):
+    def __init__(self, path: str | Path = ".policyaware/audit.db"):
+        super().__init__(None)
+        self.db_path = Path(path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    def _init_db(self) -> None:
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS traces (
+                    trace_id TEXT PRIMARY KEY,
+                    tenant TEXT NOT NULL,
+                    app TEXT NOT NULL,
+                    policy_decision TEXT NOT NULL,
+                    risk_tier TEXT NOT NULL,
+                    created_at TEXT NOT NULL,
+                    trace_json TEXT NOT NULL
+                )
+                """
+            )
+
+    def record(self, request: GatewayRequest, response: GatewayResponse, started_at: float) -> AuditTrace:
+        trace = super().record(request, response, started_at)
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO traces
+                    (trace_id, tenant, app, policy_decision, risk_tier, created_at, trace_json)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    trace.trace_id,
+                    trace.tenant,
+                    trace.app,
+                    trace.policy_decision,
+                    trace.risk_tier,
+                    trace.created_at.isoformat(),
+                    trace.model_dump_json(),
+                ),
+            )
+        return trace
+
+    def read_traces(self) -> list[dict[str, Any]]:
+        with sqlite3.connect(self.db_path) as conn:
+            rows = conn.execute("SELECT trace_json FROM traces ORDER BY created_at DESC").fetchall()
+        return [json.loads(row[0]) for row in rows]
+
+    def find_trace(self, trace_id: str) -> dict[str, Any] | None:
+        with sqlite3.connect(self.db_path) as conn:
+            row = conn.execute("SELECT trace_json FROM traces WHERE trace_id = ?", (trace_id,)).fetchone()
+        return json.loads(row[0]) if row else None
+
+
+class TraceViewer:
+    def write_html(self, traces: list[dict[str, Any]], path: str | Path) -> Path:
+        output = Path(path)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        rows = "\n".join(
+            "<tr>"
+            f"<td>{trace.get('trace_id')}</td>"
+            f"<td>{trace.get('tenant')}</td>"
+            f"<td>{trace.get('app')}</td>"
+            f"<td>{trace.get('policy_decision')}</td>"
+            f"<td>{trace.get('risk_tier')}</td>"
+            f"<td>{trace.get('model') or '-'}</td>"
+            f"<td>{trace.get('latency_ms')}</td>"
+            f"<td>{', '.join(trace.get('reason_codes', []))}</td>"
+            "</tr>"
+            for trace in traces
+        )
+        html = f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>PolicyAware Trace Viewer</title>
+  <style>
+    body {{ font-family: Arial, sans-serif; margin: 24px; color: #1f2933; }}
+    h1 {{ color: #1f4e79; }}
+    table {{ border-collapse: collapse; width: 100%; font-size: 13px; }}
+    th {{ background: #1f4e79; color: white; text-align: left; }}
+    th, td {{ border: 1px solid #d0d7de; padding: 8px; vertical-align: top; }}
+    tr:nth-child(even) {{ background: #f6f8fa; }}
+  </style>
+</head>
+<body>
+  <h1>PolicyAware Trace Viewer</h1>
+  <p>Static audit trace view generated from local audit storage.</p>
+  <table>
+    <thead>
+      <tr>
+        <th>Trace</th><th>Tenant</th><th>App</th><th>Decision</th>
+        <th>Risk</th><th>Model</th><th>Latency ms</th><th>Reason Codes</th>
+      </tr>
+    </thead>
+    <tbody>{rows}</tbody>
+  </table>
+</body>
+</html>
+"""
+        output.write_text(html, encoding="utf-8")
+        return output
+
+
+class AuditBundleWriter:
+    def write(self, trace: dict[str, Any], output_dir: str | Path) -> list[Path]:
+        output = Path(output_dir)
+        output.mkdir(parents=True, exist_ok=True)
+        files = {
+            "trace.json": trace,
+            "decision.json": trace.get("response_snapshot", {}).get("policy", {}),
+            "request.json": trace.get("request_snapshot", {}),
+            "eval_report.json": trace.get("response_snapshot", {}).get("evals", []),
+            "summary.md": self._summary(trace),
+        }
+        written: list[Path] = []
+        for name, content in files.items():
+            path = output / name
+            with path.open("w", encoding="utf-8") as handle:
+                if name.endswith(".md"):
+                    handle.write(str(content))
+                else:
+                    json.dump(content, handle, indent=2)
+            written.append(path)
+        return written
+
+    def _summary(self, trace: dict[str, Any]) -> str:
+        return "\n".join(
+            [
+                f"# PolicyAware Audit Summary",
+                "",
+                f"- Trace: `{trace.get('trace_id')}`",
+                f"- Tenant: `{trace.get('tenant')}`",
+                f"- Decision: `{trace.get('policy_decision')}`",
+                f"- Risk tier: `{trace.get('risk_tier')}`",
+                f"- Reason codes: `{', '.join(trace.get('reason_codes', [])) or '-'}`",
+                f"- Model: `{trace.get('model') or '-'}`",
+                f"- Latency: `{trace.get('latency_ms')} ms`",
+            ]
+        )

policyaware/cli.py

@@ -0,0 +1,306 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from policyaware.audit import AuditBundleWriter, AuditLogger, SQLiteAuditLogger, TraceViewer
+from policyaware.data_protection import DataProtectionEngine
+from policyaware.evals import EvalSuiteRunner
+from policyaware.gateway import Gateway
+from policyaware.models import GatewayRequest, ToolCallRequest
+from policyaware.observability import OpenTelemetryJsonExporter, PrometheusExporter
+from policyaware.policy import PolicyEngine
+from policyaware.policy_schema import PolicySchemaValidator, PolicyValidationError
+from policyaware.risk import RiskClassifier
+from policyaware.tools import ToolPolicyEngine
+
+app = typer.Typer(help="PolicyAware AI Gateway CLI")
+policy_app = typer.Typer(help="Policy testing commands")
+eval_app = typer.Typer(help="Evaluation commands")
+dev_app = typer.Typer(help="Local development commands")
+tools_app = typer.Typer(help="MCP and tool governance commands")
+audit_app = typer.Typer(help="Audit and replay commands")
+risk_app = typer.Typer(help="Risk classification commands")
+observability_app = typer.Typer(help="Metrics and trace export commands")
+app.add_typer(policy_app, name="policy")
+app.add_typer(eval_app, name="eval")
+app.add_typer(dev_app, name="dev")
+app.add_typer(tools_app, name="tools")
+app.add_typer(audit_app, name="audit")
+app.add_typer(risk_app, name="risk")
+app.add_typer(observability_app, name="observability")
+console = Console()
+
+
+@policy_app.command("validate")
+def validate_policy(policy_file: Path) -> None:
+    """Validate a YAML policy file and print clear schema errors."""
+    import yaml
+
+    with policy_file.open("r", encoding="utf-8") as handle:
+        policy = yaml.safe_load(handle) or {}
+    try:
+        PolicySchemaValidator().validate(policy)
+    except PolicyValidationError as exc:
+        console.print("[bold red]Policy validation failed[/bold red]")
+        for error in exc.errors:
+            console.print(f"- {error}")
+        raise typer.Exit(code=1) from exc
+    console.print("[bold green]Policy validation passed[/bold green]")
+
+
+@policy_app.command("test")
+def test_policy(
+    policy_file: Path,
+    role: str = "support_agent",
+    tenant: str = "acme",
+    region: str = "us",
+    risk: str = "low",
+    prompt: str = "Summarize this customer request.",
+) -> None:
+    """Evaluate a sample request against a YAML policy file."""
+    engine = PolicyEngine.from_file(policy_file)
+    gateway = Gateway(policy_engine=engine)
+    response = gateway.chat(
+        GatewayRequest(
+            tenant=tenant,
+            app="cli-policy-test",
+            user={"id": "cli_user", "role": role},
+            context={"region": region, "risk": risk, "task_type": "policy_test"},
+            messages=[{"role": "user", "content": prompt}],
+        )
+    )
+
+    table = Table(title="Policy Decision")
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("decision", response.policy.decision.value)
+    table.add_row("risk_tier", response.policy.risk_tier.value)
+    table.add_row("reason", response.policy.reason)
+    table.add_row("reason_codes", ", ".join(response.policy.reason_codes) or "-")
+    table.add_row("matched_rules", ", ".join(response.policy.matched_rules) or "-")
+    table.add_row("actions", ", ".join(response.policy.actions) or "-")
+    table.add_row("trace_id", response.trace_id)
+    console.print(table)
+
+
+@policy_app.command("explain")
+def explain_policy(
+    policy_file: Path,
+    role: str = "support_agent",
+    tenant: str = "acme",
+    region: str = "us",
+    risk: str = "low",
+    prompt: str = "Summarize this customer request.",
+) -> None:
+    """Render a machine-readable explanation for a sample policy decision."""
+    gateway = Gateway.from_policy_file(policy_file)
+    response = gateway.chat(
+        GatewayRequest(
+            tenant=tenant,
+            app="cli-policy-explain",
+            user={"id": "cli_user", "role": role},
+            context={"region": region, "risk": risk, "task_type": "policy_explain"},
+            messages=[{"role": "user", "content": prompt}],
+        )
+    )
+    console.print_json(data=response.policy.explanation.model_dump(mode="json"))
+
+
+@eval_app.command("run")
+def run_eval(eval_file: Path, policy_file: Path | None = None) -> None:
+    """Parse an evaluation suite and report configured checks."""
+    gateway = Gateway.from_policy_file(policy_file) if policy_file else None
+    result = EvalSuiteRunner().run_file(eval_file, gateway=gateway)
+    console.print_json(data=result)
+
+
+@risk_app.command("classify")
+def classify_risk(
+    prompt: str,
+    role: str = "support_agent",
+    domain: str = "support",
+    autonomy: str = "assistive",
+    action_type: str = "read",
+) -> None:
+    """Classify request risk without calling a model."""
+    request = GatewayRequest(
+        tenant="cli",
+        app="risk-classifier",
+        user={"id": "cli_user", "role": role},
+        context={"domain": domain, "autonomy": autonomy, "action_type": action_type},
+        messages=[{"role": "user", "content": prompt}],
+    )
+    findings = DataProtectionEngine().inspect(prompt)
+    risk = RiskClassifier().classify(request, findings)
+    console.print_json(data=risk.model_dump(mode="json"))
+
+
+@tools_app.command("check")
+def check_tool(
+    policy_file: Path,
+    agent: str,
+    connector: str,
+    action: str,
+    role: str = "developer",
+) -> None:
+    """Check whether an agent can call a governed tool action."""
+    engine = ToolPolicyEngine.from_file(policy_file)
+    decision = engine.decide(
+        ToolCallRequest(
+            agent_id=agent,
+            connector_id=connector,
+            action=action,
+            user={"id": "cli_user", "role": role},
+        )
+    )
+    console.print_json(data=decision.model_dump(mode="json"))
+
+
+@audit_app.command("bundle")
+def audit_bundle(
+    trace_id: str,
+    traces_file: Path = Path(".policyaware/traces.jsonl"),
+    out: Path = Path(".policyaware/audit-bundle"),
+) -> None:
+    """Create JSON and Markdown evidence artifacts for a trace."""
+    logger = AuditLogger(traces_file)
+    trace = logger.find_trace(trace_id)
+    if trace is None:
+        raise typer.BadParameter(f"Trace not found: {trace_id}")
+    written = AuditBundleWriter().write(trace, out)
+    for path in written:
+        console.print(str(path))
+
+
+@audit_app.command("view")
+def audit_view(
+    traces_file: Path = Path(".policyaware/traces.jsonl"),
+    out: Path = Path(".policyaware/trace-viewer.html"),
+) -> None:
+    """Generate a static HTML trace viewer from JSONL audit traces."""
+    traces = AuditLogger(traces_file).read_traces()
+    output = TraceViewer().write_html(traces, out)
+    console.print(str(output))
+
+
+@audit_app.command("view-sqlite")
+def audit_view_sqlite(
+    db: Path = Path(".policyaware/audit.db"),
+    out: Path = Path(".policyaware/trace-viewer.html"),
+) -> None:
+    """Generate a static HTML trace viewer from SQLite audit storage."""
+    traces = SQLiteAuditLogger(db).read_traces()
+    output = TraceViewer().write_html(traces, out)
+    console.print(str(output))
+
+
+@audit_app.command("replay")
+def replay_trace(
+    trace_id: str,
+    policy_file: Path,
+    traces_file: Path = Path(".policyaware/traces.jsonl"),
+) -> None:
+    """Replay a stored request snapshot against a policy file without external model calls."""
+    trace = AuditLogger(traces_file).find_trace(trace_id)
+    if trace is None:
+        raise typer.BadParameter(f"Trace not found: {trace_id}")
+    gateway = Gateway.from_policy_file(policy_file)
+    request = GatewayRequest(**trace["request_snapshot"])
+    response = gateway.chat(request)
+    console.print_json(
+        data={
+            "trace_id": trace_id,
+            "original_decision": trace.get("policy_decision"),
+            "replay_decision": response.policy.decision.value,
+            "replay_reason_codes": response.policy.reason_codes,
+            "changed": trace.get("policy_decision") != response.policy.decision.value,
+        }
+    )
+
+
+@observability_app.command("prometheus")
+def export_prometheus(
+    traces_file: Path = Path(".policyaware/traces.jsonl"),
+    out: Path = Path(".policyaware/metrics.prom"),
+) -> None:
+    """Export local audit traces as Prometheus text exposition metrics."""
+    traces = AuditLogger(traces_file).read_traces()
+    output = PrometheusExporter().write(traces, out)
+    console.print(str(output))
+
+
+@observability_app.command("otel-json")
+def export_otel_json(
+    traces_file: Path = Path(".policyaware/traces.jsonl"),
+    out: Path = Path(".policyaware/otel-spans.json"),
+) -> None:
+    """Export local audit traces as OpenTelemetry-shaped JSON spans."""
+    traces = AuditLogger(traces_file).read_traces()
+    output = OpenTelemetryJsonExporter().write(traces, out)
+    console.print(str(output))
+
+
+@app.command("chat")
+def chat(
+    policy_file: Path,
+    prompt: str,
+    role: str = "support_agent",
+    tenant: str = "acme",
+    risk: str = "low",
+) -> None:
+    """Send a prompt through the local simulated gateway."""
+    gateway = Gateway.from_policy_file(policy_file)
+    response = gateway.chat(
+        GatewayRequest(
+            tenant=tenant,
+            app="cli-chat",
+            user={"id": "cli_user", "role": role},
+            context={"region": "us", "risk": risk, "task_type": "chat"},
+            messages=[{"role": "user", "content": prompt}],
+        )
+    )
+    console.print(response.model_dump_json(indent=2))
+
+
+@dev_app.command("simulate")
+def simulate(policy_file: Path = Path("examples/policies/basic.yaml")) -> None:
+    """Run local policy scenarios without external model calls."""
+    scenarios = [
+        ("low-risk allow", "support_agent", "low", "Summarize this ticket."),
+        ("PII redaction", "support_agent", "low", "Email jane@example.com about the claim."),
+        ("high-risk approval", "support_agent", "high", "Approve settlement without review."),
+        ("deny unknown role", "intern", "low", "Summarize this ticket."),
+    ]
+    gateway = Gateway.from_policy_file(policy_file)
+    table = Table(title="Local Simulation")
+    table.add_column("Scenario")
+    table.add_column("Decision")
+    table.add_column("Risk")
+    table.add_column("Actions")
+    table.add_column("Matched Rules")
+    for name, role, risk, prompt in scenarios:
+        response = gateway.chat(
+            GatewayRequest(
+                tenant="acme",
+                app="dev-sim",
+                user={"id": role, "role": role},
+                context={"region": "us", "risk": risk, "task_type": "simulation"},
+                messages=[{"role": "user", "content": prompt}],
+            )
+        )
+        table.add_row(
+            name,
+            response.policy.decision.value,
+            response.policy.risk_tier.value,
+            ", ".join(response.policy.actions) or "-",
+            ", ".join(response.policy.matched_rules) or "-",
+        )
+    console.print(table)
+
+
+if __name__ == "__main__":
+    app()

policyaware/data_protection.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import re
+
+from policyaware.models import DataFindings
+
+
+class DataProtectionEngine:
+    """Detects common sensitive data patterns and can redact them."""
+
+    PATTERNS: dict[str, re.Pattern[str]] = {
+        "email": re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"),
+        "phone": re.compile(r"\b(?:\+?1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b"),
+        "ssn": re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+        "credit_card": re.compile(r"\b(?:\d[ -]*?){13,16}\b"),
+        "api_key": re.compile(r"\b(?:sk|pk|api|secret|token)_[A-Za-z0-9_\-]{16,}\b", re.I),
+        "bearer_token": re.compile(r"\bBearer\s+[A-Za-z0-9._\-]{20,}\b", re.I),
+        "medical_record": re.compile(r"\b(?:MRN|medical record|patient id)[:#\s]+[A-Z0-9-]{5,}\b", re.I),
+        "diagnosis": re.compile(r"\b(?:diagnosis|icd-10|prescription|medication)[:\s]", re.I),
+    }
+
+    PII = {"email", "phone", "ssn", "credit_card"}
+    PHI = {"medical_record", "diagnosis"}
+    SECRETS = {"api_key", "bearer_token"}
+
+    def inspect(self, text: str) -> DataFindings:
+        categories: list[str] = []
+        redactions = 0
+        for category, pattern in self.PATTERNS.items():
+            matches = pattern.findall(text)
+            if matches:
+                categories.append(category)
+                redactions += len(matches)
+
+        found = set(categories)
+        return DataFindings(
+            contains_pii=bool(found & self.PII),
+            contains_phi=bool(found & self.PHI),
+            contains_secrets=bool(found & self.SECRETS),
+            categories=categories,
+            redactions=redactions,
+        )
+
+    def redact(self, text: str) -> DataFindings:
+        findings = self.inspect(text)
+        redacted = text
+        for category, pattern in self.PATTERNS.items():
+            redacted = pattern.sub(f"[REDACTED_{category.upper()}]", redacted)
+        findings.redacted_text = redacted
+        return findings
+