safety-protocol 0.3.0__py3-none-any.whl

safety_protocol/__init__.py

@@ -0,0 +1,201 @@
+"""
+Safety Protocol Framework for LLM Agents
+
+A framework for building safe, accountable AI agents that operate
+through enforced safety protocols rather than relying on the model's
+good behavior.
+
+The core principle: the user is accountable for their agents. Every
+agent action passes through a safety protocol that enforces binding,
+scope, budget, approval gates, monitoring, audit trail, and kill switch.
+
+The agent operates freely WITHIN these bounds. The bounds are enforced
+by infrastructure, not by hoping the agent behaves.
+
+When the agent messes up, the audit trail tells you what happened, the
+binding tells you who's accountable, and the next iteration has tighter
+scope.
+
+This framework implements a reference architecture for safe agents:
+
+Layer 1: Safety Protocol (enforcement) — scope, budget, approval, monitoring,
+    audit trail (off-chain complete record), kill switch.
+
+Layer 2: On-chain anchors — SBT-style non-transferable binding, on-chain audit
+    for key events (high-value actions, approvals, kill switch, scope violations).
+    Verifiable by anyone. Tamper-resistant.
+
+Layer 3: Insurance interface — claims-ready evidence, underwriter reports,
+    control-adjusted exposure estimates. The protocol makes the agent insurable
+    by providing verifiable evidence of what happened and controls that operated.
+
+The framework is framework-agnostic: works with any LLM, any runtime, any chain.
+In production, swap the simulated on-chain layer for real ERC-5192/ERC-8004 + a
+real chain, and the insurance interface for a real insurer's claims process.
+
+Installation:
+    pip install safety-protocol
+
+Quick start:
+
+    from safety_protocol import (
+        SafetyProtocol, BoundAgent, ScopeRule, AuditTrail, Monitor
+    )
+
+    audit = AuditTrail()
+    protocol = SafetyProtocol(
+        agent_id="agent-001",
+        user_id="alice",
+        scope_rules=[
+            ScopeRule(
+                action_type="api_call",
+                allowed_targets=["https://api.example.com/v1/*"],
+                forbidden_targets=["admin", "billing"],
+                max_cost=5.0,
+            ),
+        ],
+        budget_limit=50.0,
+        approval_threshold_cost=10.0,
+        audit=audit,
+    )
+
+    agent = BoundAgent(
+        agent_id="agent-001",
+        user_id="alice",
+        safety_protocol=protocol,
+    )
+
+    result = agent.propose_action(
+        action_type="api_call",
+        target="https://api.example.com/v1/search",
+        params={"query": "test"},
+        estimated_cost=2.50,
+    )
+
+    print(result.outcome)  # ActionOutcome.ALLOWED
+
+For the full reference architecture with on-chain binding, on-chain audit,
+and insurance interface:
+
+    from safety_protocol.deployment import ReferenceDeployment
+
+    deployment = ReferenceDeployment(
+        agent_id="agent-001",
+        user_id="alice",
+        agent_name="ResearchAgent",
+        agent_role="AI research assistant",
+    )
+
+    # Agent proposes action — full stack enforces
+    result = deployment.agent_propose_action(
+        action_type="api_call",
+        target="https://api.example.com/v1/search",
+        params={"query": "test"},
+        estimated_cost=2.50,
+    )
+
+    # Get binding proof (verifiable by anyone)
+    proof = deployment.get_binding_proof()
+
+    # Get claims evidence (for insurance)
+    evidence = deployment.get_claim_evidence(
+        claim_description="Agent made incorrect API call",
+    )
+
+    # Get underwriter package (for binding coverage)
+    underwriter = deployment.get_underwriter_package(
+        agent_description="Research agent that calls APIs",
+        task_profile="API calls, message sending",
+        max_potential_loss=5000.0,
+    )
+
+The problem this solves:
+-----------------------
+AI agents can take actions with real consequences: spending money, calling
+APIs, modifying systems, sending messages, spawning subagents. The model's
+good behavior is not reliable enough to depend on. The safety protocol makes
+the agent *safe to operate* by enforcing constraints in infrastructure, not
+in prompts.
+
+When the agent messes up, you need to know: what happened, who's accountable,
+what controls operated, what can be reconstructed. The binding + audit trail
++ on-chain record answer these questions. The insurance interface makes the
+agent insurable by providing claims-ready evidence.
+
+The enforcement library (Layer 1) is production-usable. The on-chain layer is
+simulated (same interface as a real chain). In production, use ERC-5192 SBT or
+ERC-8004 on a real chain, and connect the insurance interface to a real
+insurer's claims process.
+
+The architecture is composable: use the protocol alone, add on-chain binding,
+add on-chain audit, add insurance interface — each layer is independent and
+adds value on its own.
+
+Documentation:
+    - Core protocol: src/safety_protocol/protocol.py
+    - On-chain binding: src/safety_protocol/onchain.py
+    - On-chain audit: src/safety_protocol/onchain_audit.py
+    - Insurance interface: src/safety_protocol/insurance.py
+    - Reference deployment: src/safety_protocol/deployment.py
+    - Example (LLM agent): examples/llm_agent.py
+    - Example (reference deployment): examples/reference_deployment.py
+"""
+from .core import (
+    ActionOutcome,
+    ActionRequest,
+    ActionResult,
+    ApprovalRecord,
+    AuditTrail,
+    Monitor,
+    ProtocolState,
+    ScopeRule,
+)
+from .deployment import ReferenceDeployment
+from .guard_service import GuardService, build_protocol_from_config
+from .insurance import InsuranceInterface
+from .onchain import OnChainBindingRegistry, OnChainBoundProtocol
+from .onchain_audit import DualAudit, OnChainAudit
+from .onchain_payment_verifier import OnChainPaymentVerifier
+from .payments import PaymentEnvelope, SafeSpendAgent, SimWallet
+from .protocol import BoundAgent, SafetyProtocol
+from .real_wallet import HAS_REAL_CRYPTO, RealWallet
+from .scope_linter import Finding, Severity, lint_report, lint_rules
+
+try:
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _version
+
+    __version__ = _version("safety-protocol")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.3.0"
+__all__ = [
+    "ActionOutcome",
+    "ProtocolState",
+    "ActionRequest",
+    "ActionResult",
+    "ApprovalRecord",
+    "ScopeRule",
+    "AuditTrail",
+    "Monitor",
+    "SafetyProtocol",
+    "BoundAgent",
+    "OnChainBindingRegistry",
+    "OnChainBoundProtocol",
+    "OnChainAudit",
+    "DualAudit",
+    "InsuranceInterface",
+    "ReferenceDeployment",
+    "SafeSpendAgent",
+    "SimWallet",
+    "PaymentEnvelope",
+    "RealWallet",
+    "HAS_REAL_CRYPTO",
+    "OnChainPaymentVerifier",
+    "lint_rules",
+    "lint_report",
+    "Finding",
+    "Severity",
+    "GuardService",
+    "build_protocol_from_config",
+    "__version__",
+]

safety_protocol/cli.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""
+``safety-guard`` — the CLI developers use to run and lint the guard.
+
+Subcommands (all read the USER-CONTROLLED config; none let the agent widen
+scope):
+
+  init     write a default, least-privilege config to disk
+  serve    start the HTTP guard (fails closed if rules fail lint)
+  check    ask the guard whether an intent is allowed  (--action/--target/...)
+  pay      request a gated payment                       (--recipient/--usd)
+  lint     lint the config ruleset and exit non-zero if too broad
+
+Run:
+  safety-guard init    --out guard_config.json
+  safety-guard serve   --config guard_config.json
+  safety-guard check   --config guard_config.json \\
+        --action api_call --target https://api.research.example/v1/search \\
+        --method POST --params '{"query":"hi"}'
+  safety-guard pay     --config guard_config.json \\
+        --recipient 0xMerchant1111111111111111111111111111111 --usd 0.10
+  safety-guard lint    --config guard_config.json
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib.resources import files
+
+from safety_protocol.guard_service import GuardService
+from safety_protocol.guard_service import serve as serve_http
+from safety_protocol.scope_linter import Severity
+
+
+def load_cfg(path):
+    with open(path) as f:
+        return json.load(f)
+
+
+def cmd_init(args):
+    """Write the packaged default (least-privilege) config to disk."""
+    import os
+
+    if os.path.exists(args.out) and not args.force:
+        print(f"refusing to overwrite existing file: {args.out} (use --force)")
+        sys.exit(1)
+    src = files("safety_protocol").joinpath("data/guard_config.json")
+    with open(args.out, "w", encoding="utf-8") as f:
+        f.write(src.read_text(encoding="utf-8"))
+    print(f"wrote default guard config to {args.out}")
+
+
+def cmd_serve(args):
+    # Delegate to the HTTP server entry (fails closed on lint via GuardService).
+    serve_http(args.config, args.host, args.port)
+
+
+def cmd_check(args):
+    svc = GuardService(load_cfg(args.config))
+    params = json.loads(args.params) if args.params else {}
+    r = svc.guard(args.action, args.target, method=args.method,
+                  params=params, cost=args.cost)
+    print(json.dumps(r, indent=2))
+    sys.exit(0 if r["allowed"] else 1)
+
+
+def cmd_pay(args):
+    svc = GuardService(load_cfg(args.config))
+    r = svc.pay(args.recipient, args.usd, resource=args.resource)
+    print(json.dumps(r, indent=2))
+    sys.exit(0 if r["allowed"] else 1)
+
+
+def cmd_lint(args):
+    cfg = load_cfg(args.config)
+    # Rebuild via the same path the guard uses, so lint + fail-closed match.
+    from safety_protocol.guard_service import build_protocol_from_config
+    from safety_protocol.scope_linter import lint_report
+    try:
+        _, findings = build_protocol_from_config(cfg)
+    except SystemExit as e:
+        # fail-closed: broad rules -> non-zero exit
+        print(str(e))
+        sys.exit(1)
+    print(lint_report(findings))
+    blocking = [f for f in findings
+                if f.severity in (Severity.ERROR, Severity.WARN)]
+    sys.exit(1 if blocking else 0)
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="safety-guard", description="Safety guard CLI")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    i = sub.add_parser("init", help="write a default guard config")
+    i.add_argument("--out", default="guard_config.json")
+    i.add_argument("--force", action="store_true", help="overwrite if it exists")
+    i.set_defaults(func=cmd_init)
+
+    s = sub.add_parser("serve", help="start the HTTP guard")
+    s.add_argument("--config", required=True)
+    s.add_argument("--host", default="127.0.0.1")
+    s.add_argument("--port", type=int, default=8080)
+    s.set_defaults(func=cmd_serve)
+
+    c = sub.add_parser("check", help="check if an intent is allowed")
+    c.add_argument("--config", required=True)
+    c.add_argument("--action", required=True)
+    c.add_argument("--target", required=True)
+    c.add_argument("--method")
+    c.add_argument("--params", default="")
+    c.add_argument("--cost", type=float, default=0.0)
+    c.set_defaults(func=cmd_check)
+
+    p = sub.add_parser("pay", help="request a gated payment")
+    p.add_argument("--config", required=True)
+    p.add_argument("--recipient", required=True)
+    p.add_argument("--usd", type=float, required=True)
+    p.add_argument("--resource", default="weather")
+    p.set_defaults(func=cmd_pay)
+
+    lint_p = sub.add_parser("lint", help="lint the config ruleset")
+    lint_p.add_argument("--config", required=True)
+    lint_p.set_defaults(func=cmd_lint)
+
+    args = ap.parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()