pawly 0.1.0__py3-none-any.whl

pawly/__init__.py

@@ -0,0 +1,154 @@
+"""Aploy Pawly execution-boundary controller package."""
+
+from .adapters import (
+    ClaudeSkillInvocation,
+    ClaudeSkillsPawAdapter,
+    OpenAIAgentAction,
+    OpenAIAgentsPawAdapter,
+    wrap_claude_skill_executor,
+    wrap_claude_skills,
+    wrap_openai_tool_executor,
+    wrap_openai_tools,
+)
+from .api import decide, run, run_actions
+from .approval import (
+    ApprovalHandler,
+    ApprovalRecord,
+    ApprovalRequest,
+    ApprovalResponse,
+    ApprovalRouter,
+    ApprovalStatus,
+    CallbackApprovalNotifier,
+    FileApprovalQueue,
+    InMemoryApprovalQueue,
+    StaticApprovalHandler,
+)
+from .backends import (
+    AdvancedRiskProviderStub,
+    ApprovalBackend,
+    AuditSink,
+    CloudApprovalBackendStub,
+    CloudReviewer,
+    CloudAuditSinkStub,
+    CloudReviewerStub,
+    CompositeAuditSink,
+    HostedActionSyncAuditSink,
+    LocalApprovalBackend,
+    LocalAuditSink,
+    LocalRiskProvider,
+    ReviewerPolicy,
+    ReviewerBackend,
+    RiskContext,
+    RiskProvider,
+    RulePolicy,
+    RuleReviewer,
+    build_default_audit_sink,
+    resolve_policy,
+    resolve_reviewer_backend,
+)
+from .decision_engine import ActionCandidate, ActionDecision, DecisionEngine
+from .gateway import ExecutionGateway, GatewayProtocol, wrap_execute_fn, wrap_executor, wrap_framework_adapter
+from .loader.yaml_loader import load_yaml_file
+from .pawprint_loader import (
+    PROTECTED_SKILL_WARNING,
+    PawprintConfig,
+    SkillLicense,
+    SkillMetadata,
+    SkillProtection,
+    build_model_visible_skill_context,
+    load_pawprint_file,
+    parse_pawprint_document,
+)
+from .policy import DefaultOssPolicy, HeuristicPolicy, Policy
+from .policy.base import ScoringPolicyUnavailableError, score_source, tag_scores
+from .policy.resolve import resolve_scoring_policy
+from .policy_engine.engine import evaluate_pawprint
+from .protected_oss import ProtectedAuditRedactingSink, detect_extraction_attempt, is_protected_skill, redact_audit_event
+from .runtime import PawlyRuntime
+from .runtime_result import RuntimeDecisionResult
+from .skill_registry import MissingSkillRegistryError, SkillRegistry
+from .contracts import Action, Decision, DecisionState, Intent, IntentSource, PolicyScore
+
+__all__ = [
+    "AdvancedRiskProviderStub",
+    "Action",
+    "ApprovalBackend",
+    "ApprovalHandler",
+    "ApprovalRecord",
+    "ApprovalRequest",
+    "ApprovalResponse",
+    "ApprovalRouter",
+    "ApprovalStatus",
+    "ActionCandidate",
+    "ActionDecision",
+    "AuditSink",
+    "CloudReviewer",
+    "CallbackApprovalNotifier",
+    "ClaudeSkillInvocation",
+    "ClaudeSkillsPawAdapter",
+    "CloudApprovalBackendStub",
+    "CloudAuditSinkStub",
+    "CloudReviewerStub",
+    "CompositeAuditSink",
+    "Decision",
+    "DecisionState",
+    "ExecutionGateway",
+    "GatewayProtocol",
+    "FileApprovalQueue",
+    "InMemoryApprovalQueue",
+    "LocalApprovalBackend",
+    "LocalAuditSink",
+    "LocalRiskProvider",
+    "MissingSkillRegistryError",
+    "OpenAIAgentAction",
+    "OpenAIAgentsPawAdapter",
+    "PawprintConfig",
+    "DecisionEngine",
+    "DefaultOssPolicy",
+    "Intent",
+    "IntentSource",
+    "Policy",
+    "PolicyScore",
+    "PawlyRuntime",
+    "ProtectedAuditRedactingSink",
+    "ReviewerPolicy",
+    "ReviewerBackend",
+    "RiskContext",
+    "RiskProvider",
+    "RuntimeDecisionResult",
+    "HeuristicPolicy",
+    "HostedActionSyncAuditSink",
+    "RulePolicy",
+    "RuleReviewer",
+    "SkillLicense",
+    "SkillMetadata",
+    "SkillProtection",
+    "ScoringPolicyUnavailableError",
+    "StaticApprovalHandler",
+    "SkillRegistry",
+    "PROTECTED_SKILL_WARNING",
+    "build_model_visible_skill_context",
+    "build_default_audit_sink",
+    "decide",
+    "load_yaml_file",
+    "evaluate_pawprint",
+    "detect_extraction_attempt",
+    "is_protected_skill",
+    "load_pawprint_file",
+    "parse_pawprint_document",
+    "resolve_policy",
+    "resolve_reviewer_backend",
+    "run",
+    "run_actions",
+    "redact_audit_event",
+    "score_source",
+    "tag_scores",
+    "resolve_scoring_policy",
+    "wrap_execute_fn",
+    "wrap_executor",
+    "wrap_framework_adapter",
+    "wrap_claude_skill_executor",
+    "wrap_claude_skills",
+    "wrap_openai_tool_executor",
+    "wrap_openai_tools",
+]

pawly/action_selection.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from pawly.contracts import Action, PolicyScore
+
+
+BoundaryType = Literal["allow", "review", "blocked"]
+DecisionSourceName = Literal["heuristic", "custom", "cloud", "fallback"]
+
+
+@dataclass(slots=True)
+class ActionCandidate:
+    action: Action
+    boundary_type: BoundaryType
+    requires_review: bool
+    decision_source: DecisionSourceName
+    score: PolicyScore
+    reason: str
+    uncertainty: float | None
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "action": self.action.to_dict(),
+            "boundary_type": self.boundary_type,
+            "requires_review": self.requires_review,
+            "decision_source": self.decision_source,
+            "source": self.decision_source,
+            "reason": self.reason,
+            "uncertainty": self.uncertainty,
+            "score": self.score.to_dict(),
+        }
+
+
+@dataclass(slots=True)
+class ActionDecision:
+    trace_id: str | None
+    selected_action: Action | None
+    requires_review: bool
+    decision_source: DecisionSourceName | None
+    boundary_type: Literal["allow", "review"] | None
+    reason: str | None = None
+    uncertainty: float | None = None
+    protection: dict[str, object] | None = None
+    allowed_actions: list[ActionCandidate] = field(default_factory=list)
+    review_required_actions: list[ActionCandidate] = field(default_factory=list)
+    blocked_actions: list[Action] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "trace_id": self.trace_id,
+            "selected_action": None if self.selected_action is None else self.selected_action.to_dict(),
+            "requires_review": self.requires_review,
+            "decision_source": self.decision_source,
+            "source": self.decision_source,
+            "boundary_type": self.boundary_type,
+            "reason": self.reason,
+            "uncertainty": self.uncertainty,
+            "protection": None if self.protection is None else dict(self.protection),
+            "allowed_actions": [candidate.to_dict() for candidate in self.allowed_actions],
+            "review_required_actions": [candidate.to_dict() for candidate in self.review_required_actions],
+            "blocked_actions": [action.to_dict() for action in self.blocked_actions],
+        }

pawly/adapters/__init__.py

@@ -0,0 +1,25 @@
+"""Public adapter helpers for rapid framework integration."""
+
+from .claude_skills import (
+    ClaudeSkillInvocation,
+    ClaudeSkillsPawAdapter,
+    wrap_claude_skill_executor,
+    wrap_claude_skills,
+)
+from .openai_agents import (
+    OpenAIAgentAction,
+    OpenAIAgentsPawAdapter,
+    wrap_openai_tool_executor,
+    wrap_openai_tools,
+)
+
+__all__ = [
+    "ClaudeSkillInvocation",
+    "ClaudeSkillsPawAdapter",
+    "OpenAIAgentAction",
+    "OpenAIAgentsPawAdapter",
+    "wrap_claude_skill_executor",
+    "wrap_claude_skills",
+    "wrap_openai_tool_executor",
+    "wrap_openai_tools",
+]

pawly/adapters/claude_skills.py

@@ -0,0 +1,210 @@
+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 ClaudeSkillInvocation:
+    skill_name: str
+    task: str
+    confidence: float
+    metadata: dict[str, Any] = field(default_factory=dict)
+    approved_action_name: str | None = None
+    raw_item: Any = None
+
+    @classmethod
+    def from_value(
+        cls,
+        value: Any,
+        *,
+        task: str | None = None,
+        confidence: float | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        skill_name_field: str = "skill_name",
+        task_field: str = "task",
+        confidence_field: str = "confidence",
+        metadata_field: str = "metadata",
+    ) -> "ClaudeSkillInvocation":
+        skill_name = _extract_value(value, skill_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_metadata = dict(metadata) if metadata is not None else dict(
+            _extract_value(value, metadata_field, required=False, default={}) or {}
+        )
+        return cls(
+            skill_name=str(skill_name),
+            task=str(resolved_task),
+            confidence=float(resolved_confidence),
+            metadata=resolved_metadata,
+            raw_item=value,
+        )
+
+
+SkillExecutor = Callable[[ClaudeSkillInvocation], Any]
+AuditHook = Callable[[dict[str, Any]], None]
+
+
+class ClaudeSkillsPawAdapter:
+    """Gateway-backed adapter for Claude-style skill 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_skill(self, invocation: ClaudeSkillInvocation, executor: SkillExecutor) -> dict[str, Any]:
+        return execute_adapter_action(
+            gateway=self.gateway,
+            item=invocation,
+            task=invocation.task,
+            action=invocation.skill_name,
+            confidence=invocation.confidence,
+            metadata=invocation.metadata,
+            executor=executor,
+            remap=lambda current, intent: replace(
+                current,
+                task=intent.summary,
+                skill_name=intent.action.name,
+                confidence=intent.confidence,
+                metadata=metadata_from_intent(intent),
+                approved_action_name=intent.action.name,
+            ),
+            audit_hook=self.audit_hook,
+            audit_payload=lambda outcome: {
+                "framework": "claude-skills",
+                "event": "skill-execution",
+                "skill_name": invocation.skill_name,
+                "decision_type": outcome["type"],
+                "executed": outcome["execution"]["executed"],
+            },
+        )
+
+    def execute_native_skill(
+        self,
+        value: Any,
+        executor: SkillExecutor,
+        *,
+        task: str | None = None,
+        confidence: float | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        skill_name_field: str = "skill_name",
+        task_field: str = "task",
+        confidence_field: str = "confidence",
+        metadata_field: str = "metadata",
+    ) -> dict[str, Any]:
+        return self.execute_skill(
+            ClaudeSkillInvocation.from_value(
+                value,
+                task=task,
+                confidence=confidence,
+                metadata=metadata,
+                skill_name_field=skill_name_field,
+                task_field=task_field,
+                confidence_field=confidence_field,
+                metadata_field=metadata_field,
+            ),
+            executor,
+        )
+
+
+def wrap_claude_skill_executor(
+    runtime: PawlyRuntime,
+    executor: SkillExecutor,
+    *,
+    audit_hook: AuditHook | None = None,
+    approval_handler=None,
+    gateway: GatewayProtocol | None = None,
+    task: str | None = None,
+    confidence: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    skill_name_field: str = "skill_name",
+    task_field: str = "task",
+    confidence_field: str = "confidence",
+    metadata_field: str = "metadata",
+) -> Callable[[Any], dict[str, Any]]:
+    adapter = ClaudeSkillsPawAdapter(
+        runtime,
+        audit_hook=audit_hook,
+        approval_handler=approval_handler,
+        gateway=gateway,
+    )
+
+    def wrapped(value: Any) -> dict[str, Any]:
+        return adapter.execute_native_skill(
+            value,
+            executor,
+            task=task,
+            confidence=confidence,
+            metadata=metadata,
+            skill_name_field=skill_name_field,
+            task_field=task_field,
+            confidence_field=confidence_field,
+            metadata_field=metadata_field,
+        )
+
+    return wrapped
+
+
+def wrap_claude_skills(
+    runtime: PawlyRuntime,
+    skills: Iterable[Any],
+    *,
+    audit_hook: AuditHook | None = None,
+    approval_handler=None,
+    gateway: GatewayProtocol | None = None,
+    executor_field: str = "executor",
+    skill_name_field: str = "skill_name",
+    task: str | None = None,
+    confidence: float | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    task_field: str = "task",
+    confidence_field: str = "confidence",
+    metadata_field: str = "metadata",
+) -> dict[str, Callable[[Any], dict[str, Any]]]:
+    wrapped_skills: dict[str, Callable[[Any], dict[str, Any]]] = {}
+    for skill in skills:
+        skill_name = str(_extract_value(skill, skill_name_field))
+        executor = _extract_value(skill, executor_field)
+        if not callable(executor):
+            raise TypeError(f"executor for skill '{skill_name}' must be callable")
+        wrapped_skills[skill_name] = wrap_claude_skill_executor(
+            runtime,
+            executor,
+            audit_hook=audit_hook,
+            approval_handler=approval_handler,
+            gateway=gateway,
+            task=task,
+            confidence=confidence,
+            metadata=metadata,
+            skill_name_field=skill_name_field,
+            task_field=task_field,
+            confidence_field=confidence_field,
+            metadata_field=metadata_field,
+        )
+    return wrapped_skills
+
+
+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