pawly 0.1.0__py3-none-any.whl

pawly/adapters/openai_agents.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Iterable, Mapping
+
+from pawly.gateway import GatewayProtocol
+from pawly.gateway.adapter_support import build_gateway, execute_adapter_action, metadata_from_intent
+from pawly.runtime import PawlyRuntime
+
+
+@dataclass(slots=True)
+class OpenAIAgentAction:
+    task: str
+    tool_name: str
+    confidence: float
+    payload: dict[str, Any] = field(default_factory=dict)
+    raw_item: Any = None
+
+    @classmethod
+    def from_value(
+        cls,
+        value: Any,
+        *,
+        task: str | None = None,
+        confidence: float | None = None,
+        payload: Mapping[str, Any] | None = None,
+        tool_name_field: str = "tool_name",
+        task_field: str = "task",
+        confidence_field: str = "confidence",
+        payload_field: str = "payload",
+    ) -> "OpenAIAgentAction":
+        tool_name = _extract_value(value, tool_name_field)
+        resolved_task = task if task is not None else _extract_value(value, task_field, required=False, default="")
+        resolved_confidence = confidence if confidence is not None else _extract_value(
+            value,
+            confidence_field,
+            required=False,
+            default=1.0,
+        )
+        resolved_payload = dict(payload) if payload is not None else dict(
+            _extract_value(value, payload_field, required=False, default={}) or {}
+        )
+        return cls(
+            task=str(resolved_task),
+            tool_name=str(tool_name),
+            confidence=float(resolved_confidence),
+            payload=resolved_payload,
+            raw_item=value,
+        )
+
+
+ExecutorHook = Callable[[OpenAIAgentAction], Any]
+AuditHook = Callable[[dict[str, Any]], None]
+
+
+class OpenAIAgentsPawAdapter:
+    """Gateway-backed adapter for OpenAI-style tool invocations."""
+
+    def __init__(
+        self,
+        runtime: PawlyRuntime,
+        audit_hook: AuditHook | None = None,
+        approval_handler=None,
+        gateway: GatewayProtocol | None = None,
+    ) -> None:
+        self.gateway = build_gateway(runtime, approval_handler=approval_handler, gateway=gateway)
+        self.audit_hook = audit_hook
+
+    def execute_tool(self, action: OpenAIAgentAction, executor: ExecutorHook) -> dict[str, Any]:
+        return execute_adapter_action(
+            gateway=self.gateway,
+            item=action,
+            task=action.task,
+            action=action.tool_name,
+            confidence=action.confidence,
+            metadata=action.payload,
+            executor=executor,
+            remap=lambda current, intent: replace(
+                current,
+                task=intent.summary,
+                tool_name=intent.action.name,
+                confidence=intent.confidence,
+                payload=metadata_from_intent(intent),
+            ),
+            audit_hook=self.audit_hook,
+            audit_payload=lambda outcome: {
+                "framework": "openai-agents",
+                "event": "tool-execution",
+                "tool_name": action.tool_name,
+                "decision_type": outcome["type"],
+                "executed": outcome["execution"]["executed"],
+            },
+        )
+
+    def execute_native_tool(
+        self,
+        value: Any,
+        executor: ExecutorHook,
+        *,
+        task: str | None = None,
+        confidence: float | None = None,
+        payload: Mapping[str, Any] | None = None,
+        tool_name_field: str = "tool_name",
+        task_field: str = "task",
+        confidence_field: str = "confidence",
+        payload_field: str = "payload",
+    ) -> dict[str, Any]:
+        return self.execute_tool(
+            OpenAIAgentAction.from_value(
+                value,
+                task=task,
+                confidence=confidence,
+                payload=payload,
+                tool_name_field=tool_name_field,
+                task_field=task_field,
+                confidence_field=confidence_field,
+                payload_field=payload_field,
+            ),
+            executor,
+        )
+
+
+def wrap_openai_tool_executor(
+    runtime: PawlyRuntime,
+    executor: ExecutorHook,
+    *,
+    audit_hook: AuditHook | None = None,
+    approval_handler=None,
+    gateway: GatewayProtocol | None = None,
+    task: str | None = None,
+    confidence: float | None = None,
+    payload: Mapping[str, Any] | None = None,
+    tool_name_field: str = "tool_name",
+    task_field: str = "task",
+    confidence_field: str = "confidence",
+    payload_field: str = "payload",
+) -> Callable[[Any], dict[str, Any]]:
+    adapter = OpenAIAgentsPawAdapter(
+        runtime,
+        audit_hook=audit_hook,
+        approval_handler=approval_handler,
+        gateway=gateway,
+    )
+
+    def wrapped(value: Any) -> dict[str, Any]:
+        return adapter.execute_native_tool(
+            value,
+            executor,
+            task=task,
+            confidence=confidence,
+            payload=payload,
+            tool_name_field=tool_name_field,
+            task_field=task_field,
+            confidence_field=confidence_field,
+            payload_field=payload_field,
+        )
+
+    return wrapped
+
+
+def wrap_openai_tools(
+    runtime: PawlyRuntime,
+    tools: Iterable[Any],
+    *,
+    audit_hook: AuditHook | None = None,
+    approval_handler=None,
+    gateway: GatewayProtocol | None = None,
+    executor_field: str = "executor",
+    tool_name_field: str = "tool_name",
+    task: str | None = None,
+    confidence: float | None = None,
+    payload: Mapping[str, Any] | None = None,
+    task_field: str = "task",
+    confidence_field: str = "confidence",
+    payload_field: str = "payload",
+) -> dict[str, Callable[[Any], dict[str, Any]]]:
+    wrapped_tools: dict[str, Callable[[Any], dict[str, Any]]] = {}
+    for tool in tools:
+        tool_name = str(_extract_value(tool, tool_name_field))
+        executor = _extract_value(tool, executor_field)
+        if not callable(executor):
+            raise TypeError(f"executor for tool '{tool_name}' must be callable")
+        wrapped_tools[tool_name] = wrap_openai_tool_executor(
+            runtime,
+            executor,
+            audit_hook=audit_hook,
+            approval_handler=approval_handler,
+            gateway=gateway,
+            task=task,
+            confidence=confidence,
+            payload=payload,
+            tool_name_field=tool_name_field,
+            task_field=task_field,
+            confidence_field=confidence_field,
+            payload_field=payload_field,
+        )
+    return wrapped_tools
+
+
+def _extract_value(value: Any, field: str, *, required: bool = True, default: Any = None) -> Any:
+    if isinstance(value, Mapping):
+        if field in value:
+            return value[field]
+    elif hasattr(value, field):
+        return getattr(value, field)
+    if required:
+        raise ValueError(f"unable to extract required field '{field}'")
+    return default

pawly/api.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from pawly.action_selection import ActionDecision
+from pawly.contracts import Action
+from pawly.pawprint_loader import PawprintConfig
+from pawly.runtime import DecisionEngine
+from pawly.skill_registry import SkillRegistry
+
+
+def decide(
+    pawprint: str | Path,
+    *,
+    state: Mapping[str, Any] | None,
+    actions: Sequence[Action],
+    pawprint_config: PawprintConfig | None = None,
+    **engine_kwargs: Any,
+) -> ActionDecision:
+    engine = DecisionEngine(pawprint, **engine_kwargs)
+    return engine.decide_actions(state, actions, pawprint_config)
+
+
+def run(
+    pawprint: str | Path,
+    *,
+    task: str,
+    action: str,
+    confidence: float,
+    metadata: dict[str, Any] | None = None,
+    **engine_kwargs: Any,
+) -> dict[str, Any]:
+    engine = DecisionEngine(pawprint, **engine_kwargs)
+    return engine.evaluate(task, action, confidence, metadata)
+
+
+def run_actions(
+    pawprint: str | Path,
+    *,
+    state: Mapping[str, Any] | None,
+    actions: Sequence[Action],
+    context: Mapping[str, Any] | None = None,
+    skill_registry: SkillRegistry | None = None,
+    pawprint_config: PawprintConfig | None = None,
+    **engine_kwargs: Any,
+) -> dict[str, Any]:
+    engine = DecisionEngine(pawprint, **engine_kwargs)
+    if skill_registry is not None:
+        engine.register_skills(skill_registry)
+    return engine.run_actions(
+        state=state,
+        actions=actions,
+        context=context,
+        pawprint_config=pawprint_config,
+    )

pawly/approval/__init__.py

@@ -0,0 +1,18 @@
+from .callback import CallbackApprovalNotifier
+from .handler import ApprovalHandler, StaticApprovalHandler
+from .models import ApprovalRecord, ApprovalRequest, ApprovalResponse, ApprovalStatus
+from .queue import FileApprovalQueue, InMemoryApprovalQueue
+from .router import ApprovalRouter
+
+__all__ = [
+    "ApprovalHandler",
+    "ApprovalRecord",
+    "ApprovalRequest",
+    "ApprovalResponse",
+    "ApprovalRouter",
+    "ApprovalStatus",
+    "CallbackApprovalNotifier",
+    "FileApprovalQueue",
+    "InMemoryApprovalQueue",
+    "StaticApprovalHandler",
+]

pawly/approval/callback.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from typing import Callable
+
+from pawly.approval.models import ApprovalRecord
+
+
+CallbackHook = Callable[[ApprovalRecord], None]
+
+
+class CallbackApprovalNotifier:
+    def __init__(self, callback: CallbackHook) -> None:
+        self.callback = callback
+
+    def notify(self, record: ApprovalRecord) -> None:
+        self.callback(record)

pawly/approval/handler.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from pawly.approval.models import ApprovalRequest, ApprovalResponse, ApprovalStatus
+from pawly.types import IntentAction
+
+
+class ApprovalHandler(Protocol):
+    def review(self, request: ApprovalRequest) -> ApprovalResponse: ...
+
+
+class StaticApprovalHandler:
+    def __init__(
+        self,
+        *,
+        approved: bool,
+        reviewer: str = "local-reviewer",
+        notes: list[str] | None = None,
+        edited_action: IntentAction | None = None,
+    ) -> None:
+        self.approved = approved
+        self.reviewer = reviewer
+        self.notes = notes or []
+        self.edited_action = edited_action
+
+    def review(self, request: ApprovalRequest) -> ApprovalResponse:
+        del request
+        return ApprovalResponse(
+            status=ApprovalStatus.APPROVED if self.approved else ApprovalStatus.REJECTED,
+            reviewer=self.reviewer,
+            notes=list(self.notes),
+            edited_action=self.edited_action,
+        )

pawly/approval/models.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+from uuid import uuid4
+
+from pawly.contracts import Decision
+from pawly.types import Intent, IntentAction
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class ApprovalStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+
+
+@dataclass(slots=True)
+class ApprovalRequest:
+    intent: Intent
+    decision: Decision
+    record: "ApprovalRecord | None" = None
+
+
+@dataclass(slots=True)
+class ApprovalResponse:
+    status: ApprovalStatus
+    reviewer: str | None = "local-reviewer"
+    notes: list[str] = field(default_factory=list)
+    edited_action: IntentAction | None = None
+
+
+@dataclass(slots=True)
+class ApprovalRecord:
+    record_id: str
+    intent: Intent
+    proposed_action: IntentAction
+    edited_action: IntentAction | None
+    status: ApprovalStatus
+    created_at: str
+    updated_at: str
+    expires_at: str | None
+    decision: Decision
+    reviewer: str | None = None
+    notes: list[str] = field(default_factory=list)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        intent: Intent,
+        decision: Decision,
+        expires_at: datetime | None,
+    ) -> "ApprovalRecord":
+        now = utc_now().isoformat()
+        return cls(
+            record_id=f"approval-{uuid4().hex}",
+            intent=intent,
+            proposed_action=intent.action,
+            edited_action=None,
+            status=ApprovalStatus.PENDING,
+            created_at=now,
+            updated_at=now,
+            expires_at=expires_at.isoformat() if expires_at is not None else None,
+            decision=decision,
+        )
+
+    def apply_response(self, response: ApprovalResponse) -> None:
+        self.status = response.status
+        self.reviewer = response.reviewer
+        self.notes = list(response.notes)
+        self.edited_action = response.edited_action
+        self.updated_at = utc_now().isoformat()
+
+    def mark_expired(self) -> None:
+        self.status = ApprovalStatus.EXPIRED
+        self.updated_at = utc_now().isoformat()
+        if "approval request expired" not in self.notes:
+            self.notes.append("approval request expired")
+
+    def approved_action(self) -> IntentAction:
+        return self.edited_action or self.proposed_action
+
+    def approved_intent(self) -> Intent:
+        action = self.approved_action()
+        return Intent(
+            intent_id=self.intent.intent_id,
+            source=self.intent.source,
+            action=action,
+            summary=self.intent.summary,
+            confidence=self.intent.confidence,
+            metadata=self.intent.metadata,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "record_id": self.record_id,
+            "intent": self.intent.to_dict(),
+            "proposed_action": self.proposed_action.to_dict(),
+            "status": self.status.value,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "decision": self.decision.to_dict(),
+        }
+        if self.edited_action is not None:
+            payload["edited_action"] = self.edited_action.to_dict()
+        if self.expires_at is not None:
+            payload["expires_at"] = self.expires_at
+        if self.reviewer is not None:
+            payload["reviewer"] = self.reviewer
+        if self.notes:
+            payload["notes"] = self.notes
+        return payload

pawly/approval/queue.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Protocol
+
+from pawly.contracts import Action, Decision, Intent, IntentSource
+from pawly.approval.models import ApprovalRecord, ApprovalStatus
+from pawly.approval.timeout import is_expired
+from pawly.types import IntentAction
+
+
+class ApprovalQueue(Protocol):
+    def create(self, record: ApprovalRecord) -> ApprovalRecord: ...
+    def get(self, record_id: str) -> ApprovalRecord | None: ...
+    def update(self, record: ApprovalRecord) -> ApprovalRecord: ...
+    def list_pending(self) -> list[ApprovalRecord]: ...
+    def expire_due(self) -> list[ApprovalRecord]: ...
+
+
+class InMemoryApprovalQueue:
+    def __init__(self) -> None:
+        self._records: dict[str, ApprovalRecord] = {}
+
+    def create(self, record: ApprovalRecord) -> ApprovalRecord:
+        self._records[record.record_id] = record
+        return record
+
+    def get(self, record_id: str) -> ApprovalRecord | None:
+        return self._records.get(record_id)
+
+    def update(self, record: ApprovalRecord) -> ApprovalRecord:
+        self._records[record.record_id] = record
+        return record
+
+    def list_pending(self) -> list[ApprovalRecord]:
+        return [record for record in self._records.values() if record.status == ApprovalStatus.PENDING]
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        expired: list[ApprovalRecord] = []
+        for record in self.list_pending():
+            if is_expired(record):
+                record.mark_expired()
+                self.update(record)
+                expired.append(record)
+        return expired
+
+
+class FileApprovalQueue:
+    def __init__(self, path: str | Path) -> None:
+        self.path = Path(path)
+
+    def create(self, record: ApprovalRecord) -> ApprovalRecord:
+        records = self._load()
+        records[record.record_id] = record
+        self._save(records)
+        return record
+
+    def get(self, record_id: str) -> ApprovalRecord | None:
+        return self._load().get(record_id)
+
+    def update(self, record: ApprovalRecord) -> ApprovalRecord:
+        records = self._load()
+        records[record.record_id] = record
+        self._save(records)
+        return record
+
+    def list_pending(self) -> list[ApprovalRecord]:
+        return [record for record in self._load().values() if record.status == ApprovalStatus.PENDING]
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        records = self._load()
+        expired: list[ApprovalRecord] = []
+        for record in records.values():
+            if record.status == ApprovalStatus.PENDING and is_expired(record):
+                record.mark_expired()
+                expired.append(record)
+        self._save(records)
+        return expired
+
+    def _load(self) -> dict[str, ApprovalRecord]:
+        if not self.path.exists():
+            return {}
+        payload = json.loads(self.path.read_text(encoding="utf-8"))
+        return {record_id: _record_from_dict(item) for record_id, item in payload.items()}
+
+    def _save(self, records: dict[str, ApprovalRecord]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {record_id: record.to_dict() for record_id, record in records.items()}
+        self.path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
+def _record_from_dict(value: dict) -> ApprovalRecord:
+    intent = Intent.from_dict(value["intent"])
+    proposed = value["proposed_action"]
+    edited = value.get("edited_action")
+    return ApprovalRecord(
+        record_id=value["record_id"],
+        intent=intent,
+        proposed_action=Action.from_dict(proposed),
+        edited_action=Action.from_dict(edited) if edited is not None else None,
+        status=ApprovalStatus(value["status"]),
+        created_at=value["created_at"],
+        updated_at=value["updated_at"],
+        expires_at=value.get("expires_at"),
+        decision=Decision.from_dict(value["decision"]),
+        reviewer=value.get("reviewer"),
+        notes=value.get("notes", []),
+    )

pawly/approval/router.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from pawly.contracts import Decision
+from pawly.approval.handler import ApprovalHandler
+from pawly.approval.models import ApprovalRecord, ApprovalRequest, ApprovalResponse, ApprovalStatus
+from pawly.approval.queue import ApprovalQueue, InMemoryApprovalQueue
+from pawly.approval.timeout import expiry_from_now
+from pawly.types import Intent
+
+
+class ApprovalRouter:
+    def __init__(
+        self,
+        *,
+        queue: ApprovalQueue | None = None,
+        handler: ApprovalHandler | None = None,
+        timeout_seconds: int | None = 300,
+    ) -> None:
+        self.queue = queue or InMemoryApprovalQueue()
+        self.handler = handler
+        self.timeout_seconds = timeout_seconds
+
+    def submit(self, intent: Intent, decision: Decision) -> ApprovalRecord:
+        record = ApprovalRecord.create(
+            intent=intent,
+            decision=decision,
+            expires_at=expiry_from_now(self.timeout_seconds),
+        )
+        self.queue.create(record)
+        if self.handler is not None:
+            response = self.handler.review(ApprovalRequest(intent=intent, decision=decision, record=record))
+            return self.apply_response(record.record_id, response)
+        self.queue.expire_due()
+        return self.get(record.record_id)
+
+    def get(self, record_id: str) -> ApprovalRecord:
+        self.queue.expire_due()
+        record = self.queue.get(record_id)
+        if record is None:
+            raise KeyError(record_id)
+        return record
+
+    def apply_response(self, record_id: str, response: ApprovalResponse) -> ApprovalRecord:
+        record = self.get(record_id)
+        record.apply_response(response)
+        self.queue.update(record)
+        self.queue.expire_due()
+        return self.get(record_id)
+
+    def expire_due(self) -> list[ApprovalRecord]:
+        return self.queue.expire_due()
+
+    def status_payload(self, record: ApprovalRecord) -> dict:
+        return {
+            "record_id": record.record_id,
+            "status": record.status.value,
+            "approved": record.status == ApprovalStatus.APPROVED,
+            "reviewer": record.reviewer,
+            "notes": record.notes,
+            "proposed_action": record.proposed_action.to_dict(),
+            "edited_action": record.edited_action.to_dict() if record.edited_action is not None else None,
+            "decision": record.decision.to_dict(),
+            "created_at": record.created_at,
+            "updated_at": record.updated_at,
+            "expires_at": record.expires_at,
+        }

pawly/approval/timeout.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+from pawly.approval.models import ApprovalRecord
+
+
+def expiry_from_now(timeout_seconds: int | None) -> datetime | None:
+    if timeout_seconds is None:
+        return None
+    return datetime.now(timezone.utc) + timedelta(seconds=timeout_seconds)
+
+
+def is_expired(record: ApprovalRecord, *, now: datetime | None = None) -> bool:
+    if record.expires_at is None:
+        return False
+    current = now or datetime.now(timezone.utc)
+    return current >= datetime.fromisoformat(record.expires_at)