prismguard 0.1.2__py3-none-any.whl

prismguard/__init__.py

@@ -0,0 +1,3 @@
+"""PrismGuard — self-hosted prompt-injection firewall."""
+
+__version__ = "0.1.2"

prismguard/app_cli.py

@@ -0,0 +1,394 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from prismguard.config.loader import load_triage_config
+from prismguard.context.loader import (
+    load_lexicon_file,
+    load_lexicon_from_sql_table,
+    resolve_lexicon_path,
+)
+from prismguard.context.templates import lexicon_to_parsed_seed
+from prismguard.domains.registry import get_domain_pack, list_domains
+from prismguard.runtime.guard_model import create_guard_model
+from prismguard.seed import import_bundled_seed, import_seeds
+from prismguard.storage import create_storage, create_storage_from_env
+
+
+def _storage_for_cli(backend: str | None):
+    if backend is not None:
+        return create_storage(backend)
+    if os.environ.get("PRISMGUARD_STORAGE_BACKEND"):
+        return create_storage_from_env()
+    if os.environ.get("PRISMGUARD_STORAGE_DSN"):
+        return create_storage("pgvector", dsn=os.environ["PRISMGUARD_STORAGE_DSN"])
+    return create_storage("memory")
+
+
+def _import_domain(storage, domain: str, *, dry_run: bool) -> dict:
+    pack = get_domain_pack(domain)
+    from prismguard.seed.parse import parse_seed_file
+
+    parsed = parse_seed_file(pack.overlay_path)
+    report = import_seeds(
+        storage,
+        parsed,
+        mode="update",
+        dry_run=dry_run,
+        skip_taxonomy=dry_run,
+    )
+    return {
+        "domain": pack.name,
+        "label": pack.label,
+        "overlay": str(pack.overlay_path),
+        "inserted": report.inserted,
+        "updated": report.updated,
+        "skipped": report.skipped,
+        "dry_run": report.dry_run,
+    }
+
+
+def _import_tenant_context(
+    storage,
+    lexicon_path: Path | None,
+    *,
+    dry_run: bool,
+    apply_templates: bool,
+) -> dict:
+    if lexicon_path is None:
+        return {"skipped": True, "reason": "no tenant lexicon provided"}
+    lexicon = load_lexicon_file(lexicon_path)
+    result: dict = {
+        "source": str(lexicon_path),
+        "domain": lexicon.domain,
+        "entity_count": len(lexicon.entities),
+        "dry_run": dry_run,
+    }
+    if not apply_templates:
+        result["templates_skipped"] = True
+        return result
+    parsed = lexicon_to_parsed_seed(lexicon)
+    report = import_seeds(storage, parsed, mode="update", dry_run=dry_run, skip_taxonomy=dry_run)
+    result.update(
+        {
+            "inserted": report.inserted,
+            "updated": report.updated,
+            "skipped_entries": report.skipped,
+            "template_entries": len(parsed.entries),
+        }
+    )
+    return result
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    if args.context_file or args.context_table:
+        from prismguard.licensing.features import ENTERPRISE_TENANT, require_feature
+
+        require_feature(ENTERPRISE_TENANT)
+    storage = _storage_for_cli(args.backend)
+    output: dict = {"steps": []}
+    try:
+        bundled = import_bundled_seed(
+            storage,
+            profile=args.profile,
+            mode="update",
+            dry_run=args.dry_run,
+            skip_taxonomy=args.dry_run,
+        )
+        output["steps"].append(
+            {
+                "step": "bundled_seed",
+                "profile": args.profile,
+                "inserted": bundled.inserted,
+                "updated": bundled.updated,
+                "dry_run": bundled.dry_run,
+            }
+        )
+
+        if args.domain:
+            output["steps"].append(
+                _import_domain(storage, args.domain, dry_run=args.dry_run)
+            )
+
+        lexicon_path: Path | None = None
+        if args.context_file:
+            lexicon_path = Path(args.context_file)
+        elif args.context_table and args.context_dsn:
+            lexicon = load_lexicon_from_sql_table(args.context_dsn, args.context_table)
+            if args.dry_run:
+                output["steps"].append(
+                    {
+                        "step": "tenant_context",
+                        "source": f"sql:{args.context_table}",
+                        "entity_count": len(lexicon.entities),
+                        "dry_run": True,
+                    }
+                )
+            else:
+                tmp = Path.cwd() / ".prismguard_tenant_lexicon.yaml"
+                import yaml
+
+                tmp.write_text(
+                    yaml.safe_dump(lexicon.model_dump(), sort_keys=False),
+                    encoding="utf-8",
+                )
+                lexicon_path = tmp
+        elif args.context_file is None and not args.context_table:
+            auto_path = resolve_lexicon_path()
+            if auto_path is not None:
+                lexicon_path = auto_path
+
+        if lexicon_path is not None or (args.context_table and args.dry_run):
+            if lexicon_path is not None:
+                output["steps"].append(
+                    _import_tenant_context(
+                        storage,
+                        lexicon_path,
+                        dry_run=args.dry_run,
+                        apply_templates=not args.context_lexicon_only,
+                    )
+                )
+                if not args.dry_run and not args.context_lexicon_only:
+                    os.environ["PRISMGUARD_TENANT_LEXICON_PATH"] = str(lexicon_path)
+
+        if args.write_config and not args.dry_run:
+            cfg_path = Path(args.write_config)
+            cfg_path.parent.mkdir(parents=True, exist_ok=True)
+            cfg = load_triage_config()
+            updates = {
+                "tenant_context": {
+                    "enabled": lexicon_path is not None,
+                    "lexicon_path": str(lexicon_path) if lexicon_path else "",
+                }
+            }
+            if args.domain:
+                updates["tenant_context"]["domain"] = args.domain  # type: ignore[index]
+            import yaml
+
+            raw = yaml.safe_load(cfg_path.read_text(encoding="utf-8")) if cfg_path.is_file() else {}
+            if not isinstance(raw, dict):
+                raw = {}
+            raw.setdefault("tenant_context", {}).update(updates["tenant_context"])
+            cfg_path.write_text(yaml.safe_dump(raw, sort_keys=False), encoding="utf-8")
+            output["config_written"] = str(cfg_path)
+
+        output["success"] = True
+    finally:
+        storage.close()
+
+    print(json.dumps(output, indent=2))
+    return 0
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    report: dict = {"checks": [], "ok": True}
+    cfg = load_triage_config(Path(args.config) if args.config else None)
+
+    report["checks"].append({"name": "python", "ok": True, "detail": sys.version.split()[0]})
+
+    coherence_ok = True
+    if cfg.gray_zone_policy == "escalate" and cfg.guard_model.enabled:
+        model = create_guard_model(cfg.guard_model)
+        ready = model is not None and model.is_ready
+        report["checks"].append({"name": "guard_model", "ok": ready, "artifact_id": cfg.guard_model.artifact_id})
+        if not ready:
+            coherence_ok = False
+    else:
+        report["checks"].append({"name": "guard_model", "ok": True, "detail": "not required for current policy"})
+
+    lexicon_path = cfg.tenant_context.lexicon_path or os.environ.get("PRISMGUARD_TENANT_LEXICON_PATH", "")
+    if cfg.tenant_context.enabled:
+        exists = bool(lexicon_path and Path(lexicon_path).is_file())
+        report["checks"].append({"name": "tenant_lexicon", "ok": exists, "path": lexicon_path})
+        if not exists:
+            coherence_ok = False
+    else:
+        report["checks"].append({"name": "tenant_lexicon", "ok": True, "detail": "optional — not enabled"})
+
+    report["checks"].append({"name": "domains_available", "ok": True, "domains": list_domains()})
+    report["checks"].append(
+        {
+            "name": "classifier_mode",
+            "ok": True,
+            "mode": cfg.guard_model.classifier_mode,
+            "disagreement_escalation": cfg.guard_model.disagreement_escalation,
+            "veto_enabled": cfg.guard_model.veto_enabled,
+        }
+    )
+
+    storage = _storage_for_cli(args.backend)
+    try:
+        categories = storage.relational.list_categories()
+        entries = sum(
+            len(storage.vector.list_seed_entries_by_category(c.slug)) for c in categories
+        )
+        report["checks"].append({"name": "seed_corpus", "ok": entries > 0, "entries": entries, "categories": len(categories)})
+        if entries == 0:
+            coherence_ok = False
+    except Exception as exc:
+        report["checks"].append({"name": "seed_corpus", "ok": False, "error": str(exc)})
+        coherence_ok = False
+    finally:
+        storage.close()
+
+    report["ok"] = coherence_ok
+    print(json.dumps(report, indent=2))
+    return 0 if coherence_ok else 1
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    from prismguard.cli_check import format_check_result, run_check
+
+    result = run_check(args.text)
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "decision": result.decision,
+                    "resolution_gate": result.resolution_gate,
+                    "matched_category": result.matched_category,
+                    "details": result.details,
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(format_check_result(result))
+    return 0 if result.decision == "allow" else 1
+
+
+def cmd_context_import(args: argparse.Namespace) -> int:
+    if args.apply:
+        from prismguard.licensing.features import ENTERPRISE_TENANT, require_feature
+
+        require_feature(ENTERPRISE_TENANT)
+    path = Path(args.source)
+    lexicon = load_lexicon_file(path)
+    print(
+        json.dumps(
+            {
+                "domain": lexicon.domain,
+                "entities": len(lexicon.entities),
+                "source": lexicon.source or str(path),
+            },
+            indent=2,
+        )
+    )
+    if args.dry_run:
+        parsed = lexicon_to_parsed_seed(lexicon)
+        print(json.dumps({"dry_run": True, "template_entries": len(parsed.entries)}, indent=2))
+        return 0
+
+    storage = _storage_for_cli(args.backend)
+    try:
+        if args.apply:
+            parsed = lexicon_to_parsed_seed(lexicon)
+            report = import_seeds(storage, parsed, mode="update", skip_taxonomy=False)
+            print(
+                json.dumps(
+                    {
+                        "applied": True,
+                        "inserted": report.inserted,
+                        "updated": report.updated,
+                        "skipped": report.skipped,
+                    },
+                    indent=2,
+                )
+            )
+    finally:
+        storage.close()
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="prismguard", description="PrismGuard setup and diagnostics")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init_cmd = sub.add_parser("init", help="Bootstrap bundled seed, optional domain pack, optional tenant context")
+    init_cmd.add_argument("--domain", choices=list_domains(), help="Optional domain pack (law, healthcare, finance)")
+    init_cmd.add_argument("--profile", default="authored", choices=["authored", "full"])
+    init_cmd.add_argument("--context-file", type=Path, help="Optional tenant lexicon (.yaml, .json, .csv)")
+    init_cmd.add_argument("--context-table", help="Optional SQL table name with term rows")
+    init_cmd.add_argument("--context-dsn", help="Database DSN for --context-table")
+    init_cmd.add_argument(
+        "--context-lexicon-only",
+        action="store_true",
+        help="Load lexicon for runtime only; do not import template seed entries",
+    )
+    init_cmd.add_argument("--dry-run", action="store_true")
+    init_cmd.add_argument("--backend", default=None)
+    init_cmd.add_argument("--write-config", type=Path, help="Write tenant_context settings to triage yaml")
+
+    doctor_cmd = sub.add_parser("doctor", help="Verify storage, seed, guard model, and optional tenant lexicon")
+    doctor_cmd.add_argument("--config", type=Path, default=None)
+    doctor_cmd.add_argument("--backend", default=None)
+
+    check_cmd = sub.add_parser("check", help="Check one prompt and print an auditable decision")
+    check_cmd.add_argument("text", help="Prompt text to classify")
+    check_cmd.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable output")
+
+    ctx_cmd = sub.add_parser("context", help="Tenant context lexicon tools")
+    ctx_sub = ctx_cmd.add_subparsers(dest="context_command", required=True)
+    import_cmd = ctx_sub.add_parser("import", help="Validate or import optional tenant lexicon")
+    import_cmd.add_argument("source", type=Path)
+    import_cmd.add_argument("--dry-run", action="store_true")
+    import_cmd.add_argument("--apply", action="store_true", help="Import template-generated seed entries")
+    import_cmd.add_argument("--backend", default=None)
+
+    domains_cmd = sub.add_parser("domains", help="List available domain packs")
+    domains_cmd.add_argument("--json", action="store_true")
+
+    eval_cmd = sub.add_parser("eval", help="Install verification (not internal holdout benchmark)")
+    eval_sub = eval_cmd.add_subparsers(dest="eval_command", required=True)
+    self_check_cmd = eval_sub.add_parser(
+        "self-check",
+        help="Verify classifier + fresh probes after pip install (holdout is eval-only, never imported)",
+    )
+    self_check_cmd.add_argument(
+        "--skip-runtime",
+        action="store_true",
+        help="Config checks only (no ONNX runtime probes)",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        raise SystemExit(cmd_init(args))
+    if args.command == "doctor":
+        raise SystemExit(cmd_doctor(args))
+    if args.command == "check":
+        raise SystemExit(cmd_check(args))
+    if args.command == "context":
+        if args.context_command == "import":
+            raise SystemExit(cmd_context_import(args))
+        parser.error(f"Unknown context command {args.context_command!r}")
+    if args.command == "domains":
+        packs = [get_domain_pack(name) for name in list_domains()]
+        if args.json:
+            print(json.dumps([{"name": p.name, "label": p.label} for p in packs], indent=2))
+        else:
+            for pack in packs:
+                print(f"{pack.name}\t{pack.label}\t{pack.overlay_path}")
+        return
+    if args.command == "eval":
+        if args.eval_command == "self-check":
+            from prismguard.eval.self_check import format_report, run_user_verify
+
+            report = run_user_verify(skip_runtime=args.skip_runtime)
+            print(format_report(report))
+            raise SystemExit(0 if report.ok else 1)
+        parser.error(f"Unknown eval command {args.eval_command!r}")
+    parser.error(f"Unknown command {args.command!r}")
+
+
+if __name__ == "__main__":
+    main()

prismguard/calibration/tune.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from prismguard.config.loader import TriageConfig, load_triage_config
+from prismguard.runtime.check import RuntimeChecker
+from prismguard.seed import load_bundled_seed
+from prismguard.storage import create_storage
+
+
+@dataclass(frozen=True)
+class TuneResult:
+    block_threshold: float
+    allow_threshold: float
+    w_clf: float
+    holdout_block_rate: float
+    normal_allow_rate: float
+    score: float
+
+
+def _holdout_rows(domain: str = "law") -> list[dict[str, str]]:
+    from prismguard.domains.registry import get_domain_pack
+
+    pack = get_domain_pack(domain)
+    holdout_path = pack.holdout_path
+    if holdout_path is None or not holdout_path.is_file():
+        return []
+    with holdout_path.open(encoding="utf-8") as handle:
+        raw = yaml.safe_load(handle)
+    rows: list[dict[str, str]] = []
+    for entry in raw.get("entries") or []:
+        slug = entry.get("category_slug", "")
+        kind = "attack" if slug != "benign_adjacent" else "benign_adjacent"
+        rows.append({"text": entry["text"], "traffic_kind": kind, "category_slug": slug})
+    return rows
+
+
+def _normal_rows() -> list[dict[str, str]]:
+    from benchmark.law.shared.normal_scenarios import load_normal_scenarios
+
+    return [
+        {"text": s.text, "traffic_kind": "normal", "category_slug": s.category_hint}
+        for s in load_normal_scenarios()
+    ]
+
+
+def _evaluate_config(
+    checker: RuntimeChecker,
+    cfg: TriageConfig,
+    rows: list[dict[str, str]],
+) -> tuple[float, float]:
+    """Return (attack_block_rate, normal_allow_rate) for holdout + normal rows."""
+    attacks = [r for r in rows if r["traffic_kind"] == "attack"]
+    normals = [r for r in rows if r["traffic_kind"] == "normal"]
+    blocked = 0
+    for row in attacks:
+        result = checker.check(row["text"])
+        if result.decision == "block":
+            blocked += 1
+    attack_rate = blocked / len(attacks) if attacks else 0.0
+    allowed = 0
+    for row in normals:
+        result = checker.check(row["text"])
+        if result.decision == "allow":
+            allowed += 1
+    normal_rate = allowed / len(normals) if normals else 1.0
+    return attack_rate, normal_rate
+
+
+def tune_thresholds(
+    *,
+    domain: str = "law",
+    block_grid: list[float] | None = None,
+    allow_grid: list[float] | None = None,
+    w_clf_grid: list[float] | None = None,
+    config_path: Path | None = None,
+) -> TuneResult:
+    block_grid = block_grid or [0.68, 0.72, 0.76, 0.78]
+    allow_grid = allow_grid or [0.38, 0.42, 0.46]
+    w_clf_grid = w_clf_grid or [0.25, 0.30, 0.35, 0.40]
+
+    base_cfg = load_triage_config(config_path, domain=domain)
+    base_cfg = base_cfg.model_copy(deep=True)
+    base_cfg.embedding.prefer_transformer = False
+    base_cfg.embedding.corpus_path_enabled = True  # fusion tuning requires ANN path (HashEmbedder when prefer_transformer=False)
+    base_cfg.guard_model.enabled = False
+    base_cfg.gray_zone_policy = "fail_closed"
+    base_cfg.guard_model = base_cfg.guard_model.model_copy(update={"classifier_mode": "gray_only"})
+    storage = create_storage("memory")
+    parsed = load_bundled_seed(profile="authored")
+    checker = RuntimeChecker.from_storage(storage, parsed, config=base_cfg)
+    rows = _holdout_rows(domain) + _normal_rows()
+
+    best: TuneResult | None = None
+    for block_t in block_grid:
+        for allow_t in allow_grid:
+            for w_clf in w_clf_grid:
+                checker._config.triage.block_threshold = block_t  # noqa: SLF001
+                checker._config.triage.allow_threshold = allow_t  # noqa: SLF001
+                checker._config.fusion.w_clf = w_clf  # noqa: SLF001
+                attack_rate, normal_rate = _evaluate_config(checker, checker._config, rows)
+                if normal_rate < 1.0:
+                    continue
+                score = attack_rate
+                candidate = TuneResult(
+                    block_threshold=block_t,
+                    allow_threshold=allow_t,
+                    w_clf=w_clf,
+                    holdout_block_rate=round(attack_rate, 4),
+                    normal_allow_rate=round(normal_rate, 4),
+                    score=round(score, 4),
+                )
+                if best is None or candidate.score > best.score:
+                    best = candidate
+    storage.close()
+    if best is None:
+        raise RuntimeError("No threshold configuration satisfied normal-scenario pass constraint")
+    return best
+
+
+def write_tuned_config(result: TuneResult, output_path: Path, *, base_path: Path | None = None) -> None:
+    from prismguard.config.loader import _default_config_path
+
+    source = base_path or _default_config_path()
+    base = yaml.safe_load(source.read_text(encoding="utf-8"))
+    if not isinstance(base, dict):
+        base = {}
+    base.setdefault("triage", {})
+    base["triage"]["block_threshold"] = result.block_threshold
+    base["triage"]["allow_threshold"] = result.allow_threshold
+    base.setdefault("fusion", {})
+    base["fusion"]["w_clf"] = result.w_clf
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(yaml.safe_dump(base, sort_keys=False), encoding="utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="prismguard-calibrate", description="Holdout-safe threshold tuning")
+    parser.add_argument("--domain", default="law", choices=["law", "healthcare", "finance"])
+    parser.add_argument("--output", type=Path, default=Path("triage.tuned.yaml"))
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    result = tune_thresholds(domain=args.domain)
+    write_tuned_config(result, args.output)
+    payload = {
+        "block_threshold": result.block_threshold,
+        "allow_threshold": result.allow_threshold,
+        "w_clf": result.w_clf,
+        "holdout_block_rate": result.holdout_block_rate,
+        "normal_allow_rate": result.normal_allow_rate,
+        "output": str(args.output),
+    }
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())