pawly 0.1.0__py3-none-any.whl

pawly/gateway/result.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from pawly.contracts import Decision, Intent
+from pawly.audit.diff import diff_actions
+from pawly.audit.events import AuditEvent
+from pawly.loader.schema_loader import load_pawprint_version
+from pawly.runtime_result import RuntimeDecisionResult
+
+
+def build_gateway_payload(
+    decision_result: RuntimeDecisionResult,
+    *,
+    execution: dict[str, Any],
+    approval: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    payload = {
+        **decision_result.to_dict(),
+        "execution": execution,
+    }
+    if approval is not None:
+        payload["approval"] = approval
+    return payload
+
+
+def build_governed_execution_event(
+    *,
+    event_id: str | None,
+    original_intent: Intent,
+    decision_result: RuntimeDecisionResult,
+    payload: dict[str, Any],
+) -> AuditEvent:
+    executed_action = payload.get("execution", {}).get("used_action")
+    action = original_intent.action.to_dict()
+    return AuditEvent.from_governed_execution(
+        event_id=event_id or f"event-{uuid4().hex}",
+        decision_id=decision_result.decision_id,
+        agent_id=decision_result.agent_id,
+        pawprint_version=decision_result.pawprint_version or load_pawprint_version(),
+        outcome=decision_result.decision.type.value,
+        original_intent=original_intent.to_dict(),
+        normalized_intent=decision_result.intent.to_dict(),
+        action=action,
+        policy_evaluation=decision_result.policy_evaluation.to_dict(),
+        runtime_overlays=decision_result.runtime_overlays,
+        policy_references=decision_result.decision.matched_rules,
+        final_decision=decision_result.decision.to_dict(),
+        reason_codes=decision_result.decision.reason_codes,
+        approval=payload.get("approval"),
+        executed_action=executed_action,
+        action_diff=diff_actions(action, executed_action),
+        execution=payload.get("execution"),
+        execution_result_ref=_execution_result_ref(payload.get("execution", {}).get("result")),
+        risk_score=decision_result.decision.risk_score,
+        escalated_to=decision_result.policy_evaluation.handoff_target,
+    )
+
+
+def _execution_result_ref(result: Any) -> str | None:
+    if isinstance(result, dict):
+        for key in ("result_ref", "artifact_ref", "reference", "uri", "path"):
+            value = result.get(key)
+            if isinstance(value, str) and value:
+                return value
+    return None

pawly/gateway/wrapper.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Callable
+
+from pawly.approval.handler import ApprovalHandler
+from pawly.approval.models import ApprovalStatus
+from pawly.approval.router import ApprovalRouter
+from pawly.backends.approval import ApprovalBackend, LocalApprovalBackend
+from pawly.backends.audit import AuditSink
+from pawly.backends.reviewer import ReviewerPolicy
+from pawly.backends.risk import RiskProvider
+from pawly.decision_engine import DecisionEngine
+from pawly.gateway.protocol import ExecutorFunc
+from pawly.gateway.result import build_gateway_payload, build_governed_execution_event
+from pawly.policy import resolve_reviewer_selection
+from pawly.runtime_request import build_task_request_intent
+from pawly.runtime_result import RuntimeDecisionResult
+from pawly.types import Intent
+
+ExecuteFn = Callable[[str, str, float, dict[str, Any] | None], Any]
+
+
+class ExecutionGateway:
+    def __init__(
+        self,
+        decision_engine: DecisionEngine,
+        approval_handler: ApprovalHandler | None = None,
+        policy: str = "rules",
+        approval_router: ApprovalRouter | None = None,
+        approval_backend: ApprovalBackend | None = None,
+        runtime: DecisionEngine | None = None,
+        reviewer: str | None = None,
+    ) -> None:
+        self.runtime = runtime or decision_engine
+        self.policy = reviewer or policy
+        self.reviewer = self.policy
+        self.approval_backend = approval_backend or LocalApprovalBackend(
+            handler=approval_handler,
+            router=approval_router,
+        )
+
+    def execute(
+        self,
+        *,
+        task: str,
+        action: str,
+        confidence: float,
+        executor: ExecutorFunc,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        return self.execute_intent(
+            build_task_request_intent(
+                task=task,
+                action=action,
+                confidence=confidence,
+                metadata=metadata,
+            ),
+            executor,
+        )
+
+    def execute_intent(self, intent: Intent, executor: ExecutorFunc) -> dict[str, Any]:
+        decision_result = (
+            self.runtime.evaluate_intent_result(intent)
+            if hasattr(self.runtime, "evaluate_intent_result")
+            else None
+        )
+        if decision_result is None:
+            from pawly.runtime_result import RuntimeDecisionResult
+
+            decision_result = RuntimeDecisionResult.from_dict(self.runtime.evaluate_intent(intent))
+        if decision_result.decision.type.value == "require_approval":
+            record = self.approval_backend.submit(intent, decision_result.decision)
+            approval = self.approval_backend.status_payload(record)
+            if record.status == ApprovalStatus.APPROVED:
+                approved_intent = record.approved_intent()
+                result = executor(approved_intent)
+                payload = build_gateway_payload(
+                    decision_result,
+                    approval=approval,
+                    execution={
+                        "attempted": True,
+                        "executed": True,
+                        "blocked_by": None,
+                        "result": result,
+                        "used_action": approved_intent.action.to_dict(),
+                    },
+                )
+                self._append_governed_execution_event(intent, decision_result, payload)
+                return payload
+            blocked_by = "expired" if record.status == ApprovalStatus.EXPIRED else "require_approval"
+            payload = build_gateway_payload(
+                decision_result,
+                approval=approval,
+                execution={
+                    "attempted": False,
+                    "executed": False,
+                    "blocked_by": blocked_by,
+                    "reviewer": self.policy,
+                },
+            )
+            self._append_governed_execution_event(intent, decision_result, payload)
+            return payload
+        if decision_result.decision.type.value == "simulate":
+            payload = build_gateway_payload(
+                decision_result,
+                execution={
+                    "attempted": False,
+                    "executed": False,
+                    "blocked_by": "simulate",
+                    "reviewer": self.policy,
+                },
+            )
+            self._append_governed_execution_event(intent, decision_result, payload)
+            return payload
+        if decision_result.decision.type.value != "allow":
+            payload = build_gateway_payload(
+                decision_result,
+                execution={
+                    "attempted": False,
+                    "executed": False,
+                    "blocked_by": decision_result.decision.type.value,
+                    "reviewer": self.policy,
+                },
+            )
+            self._append_governed_execution_event(intent, decision_result, payload)
+            return payload
+
+        result = executor(intent)
+        payload = build_gateway_payload(
+            decision_result,
+            execution={
+                "attempted": True,
+                "executed": True,
+                "blocked_by": None,
+                "reviewer": self.policy,
+                "result": result,
+                "used_action": intent.action.to_dict(),
+            },
+        )
+        self._append_governed_execution_event(intent, decision_result, payload)
+        return payload
+
+    def _append_governed_execution_event(
+        self,
+        original_intent: Intent,
+        decision_result: RuntimeDecisionResult,
+        payload: dict[str, Any],
+    ) -> None:
+        event = build_governed_execution_event(
+            event_id=self.runtime.next_event_id() if hasattr(self.runtime, "next_event_id") else None,
+            original_intent=original_intent,
+            decision_result=decision_result,
+            payload=payload,
+        )
+        if hasattr(self.runtime, "audit_sink"):
+            self.runtime.audit_sink.append(event)
+
+
+def wrap_executor(
+    executor: ExecutorFunc,
+    pawprint: str | Path,
+    policy: str = "rules",
+    *,
+    approval_handler: ApprovalHandler | None = None,
+    approval_router: ApprovalRouter | None = None,
+    approval_backend: ApprovalBackend | None = None,
+    policy_impl: ReviewerPolicy | None = None,
+    risk_provider: RiskProvider | None = None,
+    audit_sink: AuditSink | None = None,
+    audit_path: str | Path | None = None,
+    reviewer: str | None = None,
+    reviewer_backend: ReviewerPolicy | None = None,
+) -> ExecutorFunc:
+    selected_policy, selected_policy_impl = resolve_reviewer_selection(
+        policy=policy,
+        policy_impl=policy_impl,
+        reviewer=reviewer,
+        reviewer_backend=reviewer_backend,
+    )
+    decision_engine = DecisionEngine(
+        pawprint,
+        audit_path=audit_path,
+        policy=selected_policy,
+        policy_impl=selected_policy_impl,
+        risk_provider=risk_provider,
+        audit_sink=audit_sink,
+    )
+    gateway = ExecutionGateway(
+        decision_engine,
+        approval_handler=approval_handler,
+        policy=selected_policy,
+        approval_router=approval_router,
+        approval_backend=approval_backend,
+    )
+
+    def wrapped(intent: Intent) -> dict[str, Any]:
+        return gateway.execute_intent(intent, executor)
+
+    return wrapped
+
+
+def wrap_execute_fn(
+    fn: ExecuteFn,
+    pawprint: str | Path,
+    policy: str = "rules",
+    *,
+    approval_handler: ApprovalHandler | None = None,
+    approval_router: ApprovalRouter | None = None,
+    approval_backend: ApprovalBackend | None = None,
+    policy_impl: ReviewerPolicy | None = None,
+    risk_provider: RiskProvider | None = None,
+    audit_sink: AuditSink | None = None,
+    audit_path: str | Path | None = None,
+    reviewer: str | None = None,
+    reviewer_backend: ReviewerPolicy | None = None,
+) -> ExecuteFn:
+    selected_policy, selected_policy_impl = resolve_reviewer_selection(
+        policy=policy,
+        policy_impl=policy_impl,
+        reviewer=reviewer,
+        reviewer_backend=reviewer_backend,
+    )
+    decision_engine = DecisionEngine(
+        pawprint,
+        audit_path=audit_path,
+        policy=selected_policy,
+        policy_impl=selected_policy_impl,
+        risk_provider=risk_provider,
+        audit_sink=audit_sink,
+    )
+    gateway = ExecutionGateway(
+        decision_engine,
+        approval_handler=approval_handler,
+        policy=selected_policy,
+        approval_router=approval_router,
+        approval_backend=approval_backend,
+    )
+
+    def wrapped(task: str, action: str, confidence: float, metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+        return gateway.execute(
+            task=task,
+            action=action,
+            confidence=confidence,
+            metadata=metadata,
+            executor=lambda intent: _call_execute_fn_from_intent(fn, intent),
+        )
+
+    return wrapped
+
+
+def wrap_framework_adapter(
+    decision_engine: DecisionEngine,
+    framework: str = "generic",
+    *,
+    approval_handler: ApprovalHandler | None = None,
+    approval_router: ApprovalRouter | None = None,
+    approval_backend: ApprovalBackend | None = None,
+) -> ExecutionGateway:
+    del framework
+    return ExecutionGateway(
+        decision_engine,
+        approval_handler=approval_handler,
+        policy="rules",
+        approval_router=approval_router,
+        approval_backend=approval_backend,
+    )
+def _call_execute_fn_from_intent(fn: ExecuteFn, intent: Intent) -> Any:
+    metadata = dict(intent.metadata)
+    for key, value in intent.action.arguments.items():
+        if key != "task":
+            metadata[key] = value
+    return fn(intent.summary, intent.action.name, intent.confidence, metadata)

pawly/loader/schema_loader.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from importlib import resources
+import json
+from functools import lru_cache
+from pathlib import Path
+
+
+class PawprintDependencyError(RuntimeError):
+    """Raised when the runtime cannot load schema assets."""
+
+
+PAWLY_SCHEMA_DIR = Path(__file__).resolve().parents[1] / "schemas"
+
+
+def _schema_path(name: str) -> Path:
+    if name == "pawprint.schema.json":
+        schema_path = _pawprint_resource_path("schemas", name)
+    else:
+        schema_path = PAWLY_SCHEMA_DIR / name
+    if not schema_path.exists():
+        raise PawprintDependencyError(f"schema not found: {schema_path}")
+    return schema_path
+
+
+@lru_cache(maxsize=None)
+def load_schema(name: str) -> dict:
+    schema_path = _schema_path(name)
+    return json.loads(schema_path.read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=1)
+def load_pawprint_version() -> str:
+    version_path = _pawprint_resource_path("VERSION")
+    if not version_path.exists():
+        raise PawprintDependencyError(f"pawprint version file not found: {version_path}")
+    return version_path.read_text(encoding="utf-8").strip()
+
+
+def resolve_schema_path(name: str) -> Path:
+    return _schema_path(name)
+
+
+def _pawprint_resource_path(*parts: str) -> Path:
+    try:
+        resource = resources.files("pawprint").joinpath(*parts)
+    except ModuleNotFoundError as exc:
+        raise PawprintDependencyError(
+            "pawprint package is not installed. Install 'pawprint' before using pawly."
+        ) from exc
+    return Path(str(resource))

pawly/loader/yaml_loader.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+
+class YAMLParseError(ValueError):
+    """Raised when the lightweight YAML parser cannot parse a document."""
+
+
+def load_yaml_file(path: str | Path) -> dict:
+    text = Path(path).read_text(encoding="utf-8")
+    return loads(text)
+
+
+def loads(text: str):
+    lines = []
+    for number, raw in enumerate(text.splitlines(), start=1):
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        indent = len(raw) - len(raw.lstrip(" "))
+        lines.append((number, indent, raw.strip()))
+    if not lines:
+        return {}
+    value, index = _parse_block(lines, 0, lines[0][1])
+    if index != len(lines):
+        raise YAMLParseError(f"Unexpected trailing content near line {lines[index][0]}")
+    return value
+
+
+def _parse_block(lines, index: int, indent: int):
+    if index >= len(lines):
+        return {}, index
+    if lines[index][1] != indent:
+        raise YAMLParseError(f"Unexpected indentation near line {lines[index][0]}")
+    if lines[index][2].startswith("- "):
+        return _parse_sequence(lines, index, indent)
+    return _parse_mapping(lines, index, indent)
+
+
+def _parse_mapping(lines, index: int, indent: int):
+    mapping = {}
+    while index < len(lines):
+        line_no, line_indent, text = lines[index]
+        if line_indent < indent:
+            break
+        if line_indent > indent:
+            raise YAMLParseError(f"Unexpected indentation near line {line_no}")
+        if text.startswith("- "):
+            break
+        key, has_value, remainder = _split_key_value(text, line_no)
+        index += 1
+        if has_value:
+            mapping[key] = _parse_scalar(remainder)
+            continue
+        if index >= len(lines) or lines[index][1] <= indent:
+            mapping[key] = {}
+            continue
+        child, index = _parse_block(lines, index, lines[index][1])
+        mapping[key] = child
+    return mapping, index
+
+
+def _parse_sequence(lines, index: int, indent: int):
+    items = []
+    while index < len(lines):
+        line_no, line_indent, text = lines[index]
+        if line_indent < indent:
+            break
+        if line_indent != indent or not text.startswith("- "):
+            break
+        content = text[2:].strip()
+        index += 1
+        if not content:
+            if index >= len(lines) or lines[index][1] <= indent:
+                items.append(None)
+                continue
+            child, index = _parse_block(lines, index, lines[index][1])
+            items.append(child)
+            continue
+        if _looks_like_mapping(content):
+            key, has_value, remainder = _split_key_value(content, line_no)
+            item = {}
+            if has_value:
+                item[key] = _parse_scalar(remainder)
+            else:
+                item[key] = {}
+            if index < len(lines) and lines[index][1] > indent:
+                child, index = _parse_block(lines, index, lines[index][1])
+                if not isinstance(child, dict):
+                    raise YAMLParseError(f"List item near line {line_no} must contain a mapping")
+                item.update(child)
+            items.append(item)
+            continue
+        items.append(_parse_scalar(content))
+    return items, index
+
+
+def _split_key_value(text: str, line_no: int):
+    if ":" not in text:
+        raise YAMLParseError(f"Expected ':' in mapping near line {line_no}")
+    key, remainder = text.split(":", 1)
+    key = key.strip()
+    if not key:
+        raise YAMLParseError(f"Empty key near line {line_no}")
+    remainder = remainder.strip()
+    return key, bool(remainder), remainder
+
+
+def _looks_like_mapping(text: str) -> bool:
+    if text.startswith("[") or text.startswith("{"):
+        return False
+    return ":" in text
+
+
+def _parse_scalar(value: str):
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [_parse_scalar(part.strip()) for part in _split_flow_items(inner)]
+    if value.startswith(('"', "'")) and value.endswith(('"', "'")):
+        return value[1:-1]
+    lowered = value.lower()
+    if lowered == "true":
+        return True
+    if lowered == "false":
+        return False
+    if lowered in {"null", "none"}:
+        return None
+    if re.fullmatch(r"-?[0-9]+", value):
+        return int(value)
+    if re.fullmatch(r"-?[0-9]+\.[0-9]+", value):
+        return float(value)
+    return value
+
+
+def _split_flow_items(text: str) -> list[str]:
+    items = []
+    current = []
+    quote = None
+    depth = 0
+    for char in text:
+        if quote:
+            current.append(char)
+            if char == quote:
+                quote = None
+            continue
+        if char in {'"', "'"}:
+            quote = char
+            current.append(char)
+            continue
+        if char in "[{":
+            depth += 1
+        elif char in "]}":
+            depth -= 1
+        if char == "," and depth == 0:
+            items.append("".join(current).strip())
+            current = []
+            continue
+        current.append(char)
+    if current:
+        items.append("".join(current).strip())
+    return items

pawly/memory/store.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from pawly.memory.tiers import MemoryTier
+
+
+class MemoryStore:
+    def __init__(self, mode: str = MemoryTier.NONE.value) -> None:
+        self.mode = MemoryTier(mode)
+        self._store: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+    def remember(self, category: str, payload: dict[str, Any]) -> None:
+        if self.mode == MemoryTier.NONE:
+            return
+        self._store[category].append(payload)
+
+    def recall(self, category: str) -> list[dict[str, Any]]:
+        return list(self._store.get(category, []))
+
+    def clear(self) -> None:
+        self._store.clear()

pawly/memory/tiers.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class MemoryTier(str, Enum):
+    NONE = "none"
+    SESSION_ONLY = "session-only"
+    BOUNDED_PERSISTENT = "bounded-persistent"

pawly/middleware/__init__.py

@@ -0,0 +1 @@
+"""Middleware helpers for the Pawly execution-boundary controller."""

pawly/middleware/hooks.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Callable
+
+
+Hook = Callable[[dict], None]
+
+
+class HookRegistry:
+    def __init__(self) -> None:
+        self.before_decision: list[Hook] = []
+        self.after_decision: list[Hook] = []
+
+    def run_before(self, payload: dict) -> None:
+        for hook in self.before_decision:
+            hook(payload)
+
+    def run_after(self, payload: dict) -> None:
+        for hook in self.after_decision:
+            hook(payload)