pawly 0.1.0__py3-none-any.whl

pawly/audit/diff.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def diff_actions(original: dict[str, Any] | None, executed: dict[str, Any] | None) -> dict[str, Any]:
+    original = original or {}
+    executed = executed or {}
+    changed_fields: list[dict[str, Any]] = []
+    for key in sorted(set(original) | set(executed)):
+        if original.get(key) != executed.get(key):
+            changed_fields.append(
+                {
+                    "field": key,
+                    "original": original.get(key),
+                    "executed": executed.get(key),
+                }
+            )
+    return {
+        "changed": bool(changed_fields),
+        "changed_fields": changed_fields,
+        "original_action": original,
+        "executed_action": executed,
+    }

pawly/audit/events.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass(slots=True)
+class AuditEvent:
+    event_id: str
+    event_type: str
+    timestamp: str
+    agent_id: str
+    pawprint_version: str
+    decision_id: str
+    outcome: str
+    action: dict[str, Any]
+    original_intent: dict[str, Any]
+    normalized_intent: dict[str, Any]
+    policy_evaluation: dict[str, Any]
+    runtime_overlays: dict[str, Any]
+    policy_references: list[str]
+    matched_policy_rules: list[str]
+    final_decision: dict[str, Any]
+    reason_codes: list[str]
+    approval: dict[str, Any] | None = None
+    executed_action: dict[str, Any] | None = None
+    action_diff: dict[str, Any] | None = None
+    execution: dict[str, Any] | None = None
+    execution_result_ref: str | None = None
+    risk_score: float | None = None
+    request_id: str | None = None
+    escalated_to: str | None = None
+    tenant_id: str | None = None
+    user_id: str | None = None
+    protection_level: str | None = None
+    protection_handling: str | None = None
+    protection_assets: list[str] | None = None
+    action_argument_summary: dict[str, Any] | None = None
+    output_summary: Any | None = None
+    error_summary: str | None = None
+    redactions_applied: list[str] | None = None
+
+    @classmethod
+    def from_decision(
+        cls,
+        *,
+        event_id: str,
+        decision_id: str,
+        agent_id: str,
+        pawprint_version: str,
+        outcome: str,
+        original_intent: dict[str, Any],
+        normalized_intent: dict[str, Any],
+        action_name: str,
+        policy_evaluation: dict[str, Any],
+        runtime_overlays: dict[str, Any],
+        policy_references: list[str],
+        final_decision: dict[str, Any],
+        reason_codes: list[str],
+        risk_score: float | None,
+        escalated_to: str | None,
+    ) -> "AuditEvent":
+        return cls(
+            event_id=event_id,
+            event_type="action-proposed",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            agent_id=agent_id,
+            pawprint_version=pawprint_version,
+            decision_id=decision_id,
+            outcome=outcome,
+            action={"name": action_name, "approved": outcome == "allow"},
+            original_intent=original_intent,
+            normalized_intent=normalized_intent,
+            policy_evaluation=policy_evaluation,
+            runtime_overlays=runtime_overlays,
+            policy_references=policy_references,
+            matched_policy_rules=list(policy_references),
+            final_decision=final_decision,
+            reason_codes=reason_codes,
+            risk_score=risk_score,
+            escalated_to=escalated_to,
+            redactions_applied=[],
+        )
+
+    @classmethod
+    def from_governed_execution(
+        cls,
+        *,
+        event_id: str,
+        decision_id: str,
+        agent_id: str,
+        pawprint_version: str,
+        outcome: str,
+        original_intent: dict[str, Any],
+        normalized_intent: dict[str, Any],
+        action: dict[str, Any],
+        policy_evaluation: dict[str, Any],
+        runtime_overlays: dict[str, Any],
+        policy_references: list[str],
+        final_decision: dict[str, Any],
+        reason_codes: list[str],
+        approval: dict[str, Any] | None,
+        executed_action: dict[str, Any] | None,
+        action_diff: dict[str, Any] | None,
+        execution: dict[str, Any],
+        execution_result_ref: str | None,
+        risk_score: float | None,
+        escalated_to: str | None,
+        tenant_id: str | None = None,
+        user_id: str | None = None,
+        protection_level: str | None = None,
+        protection_handling: str | None = None,
+        protection_assets: list[str] | None = None,
+        action_argument_summary: dict[str, Any] | None = None,
+        output_summary: Any | None = None,
+        error_summary: str | None = None,
+    ) -> "AuditEvent":
+        return cls(
+            event_id=event_id,
+            event_type="governed-execution",
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            agent_id=agent_id,
+            pawprint_version=pawprint_version,
+            decision_id=decision_id,
+            outcome=outcome,
+            action=action,
+            original_intent=original_intent,
+            normalized_intent=normalized_intent,
+            policy_evaluation=policy_evaluation,
+            runtime_overlays=runtime_overlays,
+            policy_references=policy_references,
+            matched_policy_rules=list(policy_references),
+            final_decision=final_decision,
+            reason_codes=reason_codes,
+            approval=approval,
+            executed_action=executed_action,
+            action_diff=action_diff,
+            execution=execution,
+            execution_result_ref=execution_result_ref,
+            risk_score=risk_score,
+            escalated_to=escalated_to,
+            tenant_id=tenant_id,
+            user_id=user_id,
+            protection_level=protection_level,
+            protection_handling=protection_handling,
+            protection_assets=protection_assets,
+            action_argument_summary=action_argument_summary,
+            output_summary=output_summary,
+            error_summary=error_summary,
+            redactions_applied=[],
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = asdict(self)
+        return {key: value for key, value in payload.items() if value is not None}

pawly/audit/ledger.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from pawly.audit.events import AuditEvent
+
+
+class AuditLedger:
+    def __init__(self, path: str | Path | None = None) -> None:
+        self.path = Path(path) if path else None
+        self.events: list[dict] = []
+
+    def append(self, event: AuditEvent) -> dict:
+        payload = event.to_dict()
+        self.events.append(payload)
+        if self.path:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            with self.path.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(payload, sort_keys=True) + "\n")
+        return payload
+
+    def load_events(self) -> list[dict]:
+        if self.path and self.path.exists():
+            lines = self.path.read_text(encoding="utf-8").splitlines()
+            return [json.loads(line) for line in lines if line.strip()]
+        return list(self.events)
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict | None:
+        events = self.load_events()
+        for event in reversed(events):
+            if event_id is not None and event.get("event_id") != event_id:
+                continue
+            if decision_id is not None and event.get("decision_id") != decision_id:
+                continue
+            if event_type is not None and event.get("event_type") != event_type:
+                continue
+            return event
+        return None

pawly/audit/replay.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from pawly.audit.diff import diff_actions
+from pawly.audit.ledger import AuditLedger
+
+
+def load_audit_record(
+    path: str | Path,
+    *,
+    event_id: str | None = None,
+    decision_id: str | None = None,
+    event_type: str = "governed-execution",
+) -> dict[str, Any]:
+    ledger = AuditLedger(path)
+    record = ledger.find_event(event_id=event_id, decision_id=decision_id, event_type=event_type)
+    if record is None:
+        raise KeyError(event_id or decision_id or event_type)
+    return record
+
+
+def replay_governed_path(record: dict[str, Any]) -> dict[str, Any]:
+    original_action = record.get("action", {})
+    executed_action = record.get("executed_action")
+    action_diff = record.get("action_diff") or diff_actions(original_action, executed_action)
+    return {
+        "event_id": record.get("event_id"),
+        "decision_id": record.get("decision_id"),
+        "agent_id": record.get("agent_id"),
+        "original_intent": record.get("original_intent"),
+        "normalized_intent": record.get("normalized_intent"),
+        "policy": {
+            "matched_rules": record.get("matched_policy_rules", record.get("policy_references", [])),
+            "risk_score": record.get("risk_score"),
+            "policy_evaluation": record.get("policy_evaluation"),
+            "final_decision": record.get("final_decision"),
+        },
+        "approval": record.get("approval"),
+        "execution": record.get("execution"),
+        "original_action": original_action,
+        "executed_action": executed_action,
+        "action_diff": action_diff,
+    }

pawly/backends/__init__.py

@@ -0,0 +1,39 @@
+from .approval import ApprovalBackend, CloudApprovalBackendStub, LocalApprovalBackend
+from .audit import AuditSink, CloudAuditSinkStub, CompositeAuditSink, HostedActionSyncAuditSink, LocalAuditSink, build_default_audit_sink
+from .reviewer import (
+    CloudReviewer,
+    CloudReviewerStub,
+    ReviewerPolicy,
+    ReviewerBackend,
+    RulePolicy,
+    RuleReviewer,
+    evaluate_reviewer_policy,
+    resolve_policy,
+    resolve_reviewer_backend,
+)
+from .risk import AdvancedRiskProviderStub, LocalRiskProvider, RiskContext, RiskProvider
+
+__all__ = [
+    "AdvancedRiskProviderStub",
+    "ApprovalBackend",
+    "AuditSink",
+    "CloudReviewer",
+    "CloudApprovalBackendStub",
+    "CloudAuditSinkStub",
+    "CloudReviewerStub",
+    "CompositeAuditSink",
+    "evaluate_reviewer_policy",
+    "HostedActionSyncAuditSink",
+    "LocalApprovalBackend",
+    "LocalAuditSink",
+    "LocalRiskProvider",
+    "ReviewerPolicy",
+    "ReviewerBackend",
+    "RiskContext",
+    "RiskProvider",
+    "RulePolicy",
+    "RuleReviewer",
+    "resolve_policy",
+    "resolve_reviewer_backend",
+    "build_default_audit_sink",
+]

pawly/backends/approval.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from pawly.contracts import Decision
+from pawly.approval.handler import ApprovalHandler
+from pawly.approval.models import ApprovalRecord, ApprovalResponse
+from pawly.approval.queue import ApprovalQueue, InMemoryApprovalQueue
+from pawly.approval.router import ApprovalRouter
+from pawly.types import Intent
+
+
+class ApprovalBackend(Protocol):
+    name: str
+
+    def submit(self, intent: Intent, decision: Decision) -> ApprovalRecord:
+        ...
+
+    def get(self, record_id: str) -> ApprovalRecord:
+        ...
+
+    def apply_response(self, record_id: str, response: ApprovalResponse) -> ApprovalRecord:
+        ...
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        ...
+
+    def status_payload(self, record: ApprovalRecord) -> dict[str, Any]:
+        ...
+
+
+class LocalApprovalBackend:
+    name = "local-approval"
+
+    def __init__(
+        self,
+        *,
+        queue: ApprovalQueue | None = None,
+        handler: ApprovalHandler | None = None,
+        timeout_seconds: int | None = 300,
+        router: ApprovalRouter | None = None,
+    ) -> None:
+        self.router = router or ApprovalRouter(
+            queue=queue or InMemoryApprovalQueue(),
+            handler=handler,
+            timeout_seconds=timeout_seconds,
+        )
+
+    def submit(self, intent: Intent, decision: Decision) -> ApprovalRecord:
+        return self.router.submit(intent, decision)
+
+    def get(self, record_id: str) -> ApprovalRecord:
+        return self.router.get(record_id)
+
+    def apply_response(self, record_id: str, response: ApprovalResponse) -> ApprovalRecord:
+        return self.router.apply_response(record_id, response)
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        return self.router.expire_due()
+
+    def status_payload(self, record: ApprovalRecord) -> dict[str, Any]:
+        return self.router.status_payload(record)
+
+
+class CloudApprovalBackendStub:
+    name = "cloud-approval"
+
+    def submit(self, intent: Intent, decision: Decision) -> ApprovalRecord:
+        del intent, decision
+        raise NotImplementedError("Cloud approval backends are optional extensions and are not part of the OSS runtime path.")
+
+    def get(self, record_id: str) -> ApprovalRecord:
+        del record_id
+        raise NotImplementedError("Cloud approval backends are optional extensions and are not part of the OSS runtime path.")
+
+    def apply_response(self, record_id: str, response: ApprovalResponse) -> ApprovalRecord:
+        del record_id, response
+        raise NotImplementedError("Cloud approval backends are optional extensions and are not part of the OSS runtime path.")
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        raise NotImplementedError("Cloud approval backends are optional extensions and are not part of the OSS runtime path.")
+
+    def status_payload(self, record: ApprovalRecord) -> dict[str, Any]:
+        del record
+        raise NotImplementedError("Cloud approval backends are optional extensions and are not part of the OSS runtime path.")

pawly/backends/audit.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Protocol
+from urllib import error, request
+
+from pawly.audit.events import AuditEvent
+from pawly.audit.ledger import AuditLedger
+from pawly.loader.yaml_loader import load_yaml_file
+
+DEFAULT_PAWLY_CLOUD_BASE_URL = "https://api.pawly.dev"
+PAWLY_CLOUD_BASE_URL_ENV = "PAWLY_CLOUD_BASE_URL"
+PAWLY_AUTH_PATH_ENV = "PAWLY_AUTH_PATH"
+
+
+class AuditSink(Protocol):
+    name: str
+
+    def append(self, event: AuditEvent) -> dict[str, Any]:
+        ...
+
+    def load_events(self) -> list[dict[str, Any]]:
+        ...
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict[str, Any] | None:
+        ...
+
+
+class LocalAuditSink:
+    name = "local-jsonl"
+
+    def __init__(self, path: str | Path | None = None) -> None:
+        self.ledger = AuditLedger(path)
+
+    def append(self, event: AuditEvent) -> dict[str, Any]:
+        return self.ledger.append(event)
+
+    def load_events(self) -> list[dict[str, Any]]:
+        return self.ledger.load_events()
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict[str, Any] | None:
+        return self.ledger.find_event(event_id=event_id, decision_id=decision_id, event_type=event_type)
+
+
+class CompositeAuditSink:
+    name = "composite-audit"
+
+    def __init__(self, sinks: list[AuditSink]) -> None:
+        if not sinks:
+            raise ValueError("CompositeAuditSink requires at least one sink")
+        self.sinks = sinks
+        self.ledger = getattr(sinks[0], "ledger", sinks[0])
+
+    def append(self, event: AuditEvent) -> dict[str, Any]:
+        payload: dict[str, Any] | None = None
+        for index, sink in enumerate(self.sinks):
+            result = sink.append(event)
+            if index == 0:
+                payload = result
+        return payload or event.to_dict()
+
+    def load_events(self) -> list[dict[str, Any]]:
+        return self.sinks[0].load_events()
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict[str, Any] | None:
+        return self.sinks[0].find_event(event_id=event_id, decision_id=decision_id, event_type=event_type)
+
+
+class HostedActionSyncAuditSink:
+    name = "cloud-action-sync"
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        api_key: str,
+        timeout: float = 5.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+
+    def append(self, event: AuditEvent) -> dict[str, Any]:
+        payload = event.to_dict()
+        body = json.dumps(_action_ingest_payload(payload)).encode("utf-8")
+        req = request.Request(
+            f"{self.base_url}/v1/actions:ingest",
+            data=body,
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with request.urlopen(req, timeout=self.timeout) as response:
+                response.read()
+        except (OSError, error.URLError, error.HTTPError) as exc:
+            raise RuntimeError(f"cloud action sync failed: {exc}") from exc
+        return payload
+
+    def load_events(self) -> list[dict[str, Any]]:
+        raise NotImplementedError("Hosted action sync is write-only from the OSS runtime path.")
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict[str, Any] | None:
+        del event_id, decision_id, event_type
+        raise NotImplementedError("Hosted action sync is write-only from the OSS runtime path.")
+
+
+class CloudAuditSinkStub:
+    name = "cloud-audit"
+
+    def append(self, event: AuditEvent) -> dict[str, Any]:
+        del event
+        raise NotImplementedError("Cloud audit sinks are optional extensions and are not part of the OSS runtime path.")
+
+    def load_events(self) -> list[dict[str, Any]]:
+        raise NotImplementedError("Cloud audit sinks are optional extensions and are not part of the OSS runtime path.")
+
+    def find_event(self, *, event_id: str | None = None, decision_id: str | None = None, event_type: str | None = None) -> dict[str, Any] | None:
+        del event_id, decision_id, event_type
+        raise NotImplementedError("Cloud audit sinks are optional extensions and are not part of the OSS runtime path.")
+
+
+def build_default_audit_sink(audit_path: str | Path | None = None) -> AuditSink:
+    local = LocalAuditSink(audit_path)
+    hosted = _build_hosted_action_sync()
+    if hosted is None:
+        return local
+    return CompositeAuditSink([local, hosted])
+
+
+def _build_hosted_action_sync() -> HostedActionSyncAuditSink | None:
+    auth = _load_pawly_auth()
+    if auth is None:
+        return None
+    api_key = str(auth.get("api_key", "")).strip()
+    if not api_key:
+        return None
+    return HostedActionSyncAuditSink(
+        base_url=_resolve_pawly_cloud_base_url(),
+        api_key=api_key,
+    )
+
+
+def _action_ingest_payload(event: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "event_id": event.get("event_id"),
+        "decision_id": event.get("decision_id"),
+        "timestamp": event.get("timestamp"),
+        "event_type": event.get("event_type"),
+        "outcome": event.get("outcome"),
+        "agent_id": event.get("agent_id"),
+        "action": dict(event.get("executed_action") or event.get("action") or {}),
+        "executed_action": event.get("executed_action"),
+        "risk_score": event.get("risk_score"),
+        "request_id": event.get("request_id"),
+        "metadata": {
+            "reason_codes": event.get("reason_codes") or [],
+            "policy_references": event.get("policy_references") or [],
+            "execution_result_ref": event.get("execution_result_ref"),
+        },
+    }
+
+
+def _load_pawly_auth() -> dict[str, Any] | None:
+    path = _pawly_auth_path()
+    if not path.exists() or not path.is_file():
+        return None
+    if path.suffix.lower() == ".json":
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        payload = load_yaml_file(path)
+    if isinstance(payload, dict):
+        return payload
+    return None
+
+
+def _pawly_auth_path() -> Path:
+    explicit = os.environ.get(PAWLY_AUTH_PATH_ENV, "").strip()
+    if explicit:
+        return Path(explicit)
+    return Path.home() / ".pawly" / "pawly_auth.yaml"
+
+
+def _resolve_pawly_cloud_base_url() -> str:
+    return os.environ.get(PAWLY_CLOUD_BASE_URL_ENV, "").strip() or DEFAULT_PAWLY_CLOUD_BASE_URL