pawly 0.1.0__py3-none-any.whl

pawly/backends/reviewer.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import inspect
+import importlib
+import logging
+from typing import Any
+from typing import Protocol
+
+from pawly.backends.risk import LocalRiskProvider, RiskProvider
+from pawly.pawprint_loader import PawprintConfig
+from pawly.policy_engine.engine import evaluate_pawprint
+from pawly.types import Intent, PolicyEvaluation
+
+
+LOGGER = logging.getLogger(__name__)
+_CONFIG_WARNING = "Pawly Cloud not configured. Falling back to rule-based decision."
+
+
+class ReviewerPolicy(Protocol):
+    name: str
+
+    def evaluate(self, intent: Intent, pawprint: PawprintConfig, context: dict[str, Any] | None = None) -> PolicyEvaluation:
+        ...
+
+
+class RulePolicy:
+    name = "rules"
+    reviewer_mode = "rule"
+
+    def __init__(self, risk_provider: RiskProvider | None = None) -> None:
+        self.risk_provider = risk_provider or LocalRiskProvider()
+
+    def evaluate(self, intent: Intent, pawprint: PawprintConfig, context: dict[str, Any] | None = None) -> PolicyEvaluation:
+        del context
+        return evaluate_pawprint(
+            intent,
+            pawprint,
+            risk_provider=self.risk_provider,
+        )
+
+    def review(self, intent: Intent, pawprint: PawprintConfig, context: dict[str, Any] | None = None) -> PolicyEvaluation:
+        return self.evaluate(intent, pawprint, context)
+
+
+class CloudReviewerStub:
+    name = "cloud-review"
+
+    def evaluate(self, intent: Intent, pawprint: PawprintConfig, context: dict[str, Any] | None = None) -> PolicyEvaluation:
+        del context
+        del intent, pawprint
+        raise NotImplementedError("Cloud reviewer backends are optional extensions and are not part of the OSS runtime path.")
+
+    def review(self, intent: Intent, pawprint: PawprintConfig, context: dict[str, Any] | None = None) -> PolicyEvaluation:
+        return self.evaluate(intent, pawprint, context)
+
+
+class CloudReviewer(CloudReviewerStub):
+    @classmethod
+    def from_env(cls) -> "CloudReviewer | None":
+        cloud_reviewer_cls = _load_external_cloud_reviewer()
+        if cloud_reviewer_cls is None:
+            return None
+        return cloud_reviewer_cls.from_env()
+
+
+def resolve_policy(
+    policy: str = "rules",
+    *,
+    policy_impl: ReviewerPolicy | None = None,
+    risk_provider: RiskProvider | None = None,
+) -> ReviewerPolicy:
+    if policy_impl is not None:
+        return policy_impl
+    if policy == "rules":
+        return RulePolicy(risk_provider=risk_provider)
+    if policy == "cloud":
+        cloud_reviewer = CloudReviewer.from_env()
+        if cloud_reviewer is not None:
+            return cloud_reviewer
+        LOGGER.warning(_CONFIG_WARNING)
+        return RulePolicy(risk_provider=risk_provider)
+    raise ValueError(f"unsupported policy: {policy}")
+
+
+def evaluate_reviewer_policy(
+    policy: ReviewerPolicy,
+    intent: Intent,
+    pawprint: PawprintConfig,
+    context: dict[str, Any] | None = None,
+) -> PolicyEvaluation:
+    evaluate = getattr(policy, "evaluate", None)
+    if callable(evaluate):
+        return evaluate(intent, pawprint, context)
+
+    review = getattr(policy, "review", None)
+    if not callable(review):
+        raise TypeError("reviewer policy must provide evaluate(...) or review(...)")
+
+    parameters = inspect.signature(review).parameters
+    if "context" in parameters or len(parameters) >= 3:
+        return review(intent, pawprint, context)
+    return review(intent, pawprint)
+
+
+ReviewerBackend = ReviewerPolicy
+RuleReviewer = RulePolicy
+
+
+def resolve_reviewer_backend(
+    reviewer: str = "rules",
+    *,
+    reviewer_backend: ReviewerBackend | None = None,
+    risk_provider: RiskProvider | None = None,
+) -> ReviewerBackend:
+    return resolve_policy(
+        policy=reviewer,
+        policy_impl=reviewer_backend,
+        risk_provider=risk_provider,
+    )
+
+
+def _load_external_cloud_reviewer():
+    try:
+        module = importlib.import_module("pawly_cloud")
+    except ModuleNotFoundError:
+        return None
+    return getattr(module, "CloudReviewer", None)

pawly/backends/risk.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from pawly.escalation.patterns import text_matches_rule
+from pawly.types import Intent
+
+
+EXTERNAL_SIDE_EFFECT_RULES = (
+    "issue refund",
+    "change account details",
+    "delete customer records",
+    "approve exception",
+    "send external message",
+    "publish update",
+    "modify billing",
+    "legal advice",
+)
+
+
+@dataclass(slots=True)
+class RiskContext:
+    intent: Intent
+    ask_first_matches: list[str]
+    never_matches: list[str]
+    capability_matched: bool
+    handoff_matches: list[str]
+
+
+class RiskProvider(Protocol):
+    name: str
+
+    def score(self, context: RiskContext) -> float:
+        ...
+
+
+class LocalRiskProvider:
+    name = "local-rules"
+
+    def score(self, context: RiskContext) -> float:
+        if context.never_matches:
+            return 0.98
+
+        score = 0.1
+        if context.ask_first_matches:
+            score += 0.35
+        if context.handoff_matches:
+            score += 0.2
+        if not context.capability_matched:
+            score += 0.35
+        if _has_external_side_effect(context.intent):
+            score += 0.15
+        if context.intent.confidence < 0.7:
+            score += 0.15
+        return round(min(score, 0.95), 2)
+
+
+class AdvancedRiskProviderStub:
+    name = "cloud-risk"
+
+    def score(self, context: RiskContext) -> float:
+        del context
+        raise NotImplementedError("Cloud risk providers are optional extensions and are not part of the OSS runtime path.")
+
+
+def _has_external_side_effect(intent: Intent) -> bool:
+    text = " ".join(
+        part for part in [intent.summary, intent.action.name, intent.action.target or ""] if part
+    )
+    return any(text_matches_rule(text, rule) for rule in EXTERNAL_SIDE_EFFECT_RULES)

pawly/budget/checker.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pawly.budget.state import BudgetState
+from pawly.types import Intent
+
+
+@dataclass(slots=True)
+class BudgetResult:
+    exhausted: bool
+    warnings: list[str] = field(default_factory=list)
+    consumed: dict[str, float] = field(default_factory=dict)
+
+
+def check_budget(agent_config: dict, state: BudgetState, intent: Intent) -> BudgetResult:
+    warnings: list[str] = []
+    consumed: dict[str, float] = {}
+    exhausted = False
+    for limit in agent_config.get("budget", {}).get("limits", []):
+        name = limit.get("name", "unnamed-limit")
+        amount = float(limit.get("amount", 0))
+        unit = limit.get("unit", "count")
+        increment = float(intent.metadata.get(name, 1 if unit == "count" else 0))
+        current = state.consume(name, increment)
+        consumed[name] = current
+        if amount and current >= amount:
+            if limit.get("enforcement") == "hard":
+                exhausted = True
+            warnings.append(f"budget limit reached for {name}: {current:g}/{amount:g}")
+        else:
+            for threshold in agent_config.get("budget", {}).get("warning_thresholds", []):
+                if threshold.get("limit") == name:
+                    percent = float(threshold.get("percent", 0))
+                    if amount and current >= amount * (percent / 100.0):
+                        warnings.append(f"budget warning for {name}: {current:g}/{amount:g}")
+    return BudgetResult(exhausted=exhausted, warnings=list(dict.fromkeys(warnings)), consumed=consumed)

pawly/budget/state.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from collections import defaultdict
+
+
+class BudgetState:
+    def __init__(self) -> None:
+        self._usage = defaultdict(float)
+
+    def consume(self, name: str, amount: float) -> float:
+        self._usage[name] += amount
+        return self._usage[name]
+
+    def snapshot(self) -> dict[str, float]:
+        return dict(self._usage)

pawly/cli.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from pawly.decision_engine import DecisionEngine
+from pawly.validator.validator import SchemaValidationError
+
+DEFAULT_AUDIT_LOG = "pawly.audit.jsonl"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pawly", description="Aploy Pawly execution-boundary controller CLI")
+    parser.add_argument("--agent", required=True, help="Path to a Pawprint worker card")
+    parser.add_argument("--task", required=True, help="Task description to evaluate")
+    parser.add_argument("--action", required=True, help="Action name to evaluate")
+    parser.add_argument("--confidence", required=True, type=float, help="Model confidence in the proposed action")
+    parser.add_argument("--audit-log", default=DEFAULT_AUDIT_LOG, help="JSONL audit log path (defaults to ./pawly.audit.jsonl)")
+    parser.add_argument("--report", action="store_true", help="Print a report after evaluation")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        runtime = DecisionEngine(args.agent, audit_path=args.audit_log)
+        decision = runtime.evaluate(task=args.task, action=args.action, confidence=args.confidence)
+        decision["audit_log"] = str(Path(args.audit_log).resolve())
+        print(json.dumps(decision, indent=2, sort_keys=True))
+        if args.report:
+            print(json.dumps(runtime.build_report(), indent=2, sort_keys=True))
+        return 0
+    except SchemaValidationError as exc:
+        parser.error(str(exc))
+    except Exception as exc:  # pragma: no cover - CLI safety
+        print(json.dumps({"error": str(exc)}), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

pawly/contracts.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class DecisionState(str, Enum):
+    ALLOW = "allow"
+    DENY = "deny"
+    REQUIRE_APPROVAL = "require_approval"
+    SIMULATE = "simulate"
+
+
+class DecisionSource(str, Enum):
+    RULE = "rule"
+    CLOUD = "cloud"
+
+
+class IntentSource(str, Enum):
+    TOOL_CALL = "tool_call"
+    PLANNER_OUTPUT = "planner_output"
+    EXECUTION_REQUEST = "execution_request"
+
+
+@dataclass(slots=True)
+class Action:
+    name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    target: str | None = None
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "Action":
+        return cls(
+            name=str(payload["name"]),
+            arguments=dict(payload.get("arguments", {})),
+            target=None if payload.get("target") is None else str(payload["target"]),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {"name": self.name, "arguments": self.arguments}
+        if self.target is not None:
+            payload["target"] = self.target
+        return payload
+
+
+@dataclass(slots=True)
+class Intent:
+    intent_id: str
+    source: IntentSource
+    action: Action
+    summary: str = ""
+    confidence: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "Intent":
+        context = payload.get("context", {})
+        return cls(
+            intent_id=str(payload["intent_id"]),
+            source=IntentSource(payload["source"]),
+            action=Action.from_dict(payload["action"]),
+            summary=str(context.get("summary", "")),
+            confidence=float(context.get("confidence", 0.0)),
+            metadata=dict(payload.get("metadata", {})),
+        )
+
+    def text(self) -> str:
+        return f"{self.summary} {self.action.name}".strip()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "intent_id": self.intent_id,
+            "source": self.source.value,
+            "action": self.action.to_dict(),
+            "context": {
+                "summary": self.summary,
+                "confidence": self.confidence,
+            },
+            "metadata": self.metadata,
+        }
+
+
+@dataclass(slots=True)
+class PolicyScore:
+    risk_score: float | None = None
+    reason_codes: list[str] = field(default_factory=list)
+    matched_rules: list[str] = field(default_factory=list)
+    audit_tags: list[str] = field(default_factory=list)
+    uncertainty: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if self.risk_score is not None:
+            payload["risk_score"] = self.risk_score
+        if self.reason_codes:
+            payload["reason_codes"] = list(self.reason_codes)
+        if self.matched_rules:
+            payload["matched_rules"] = list(self.matched_rules)
+        if self.audit_tags:
+            payload["audit_tags"] = list(self.audit_tags)
+        if self.uncertainty is not None:
+            payload["uncertainty"] = self.uncertainty
+        return payload
+
+
+@dataclass(slots=True)
+class Decision:
+    type: DecisionState
+    reason: str
+    source: str | None = None
+    reason_codes: list[str] = field(default_factory=list)
+    matched_rules: list[str] = field(default_factory=list)
+    risk_score: float | None = None
+    rewritten_action: Action | None = None
+    audit_tags: list[str] = field(default_factory=list)
+    worker_id: str | None = None
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "Decision":
+        rewritten_action = payload.get("rewritten_action")
+        return cls(
+            type=DecisionState(payload["type"]),
+            reason=str(payload["reason"]),
+            source=None if payload.get("source") is None else str(payload["source"]),
+            reason_codes=[str(item) for item in payload.get("reason_codes", [])],
+            matched_rules=[str(item) for item in payload.get("matched_rules", [])],
+            risk_score=None if payload.get("risk_score") is None else float(payload["risk_score"]),
+            rewritten_action=Action.from_dict(rewritten_action) if isinstance(rewritten_action, dict) else None,
+            audit_tags=[str(item) for item in payload.get("audit_tags", [])],
+            worker_id=None if payload.get("worker_id") is None else str(payload["worker_id"]),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "type": self.type.value,
+            "reason": self.reason,
+        }
+        if self.source is not None:
+            payload["source"] = self.source
+        if self.reason_codes:
+            payload["reason_codes"] = list(self.reason_codes)
+        if self.matched_rules:
+            payload["matched_rules"] = list(self.matched_rules)
+        if self.risk_score is not None:
+            payload["risk_score"] = self.risk_score
+        if self.rewritten_action is not None:
+            payload["rewritten_action"] = self.rewritten_action.to_dict()
+        if self.audit_tags:
+            payload["audit_tags"] = list(self.audit_tags)
+        if self.worker_id is not None:
+            payload["worker_id"] = self.worker_id
+        return payload

pawly/decision_engine.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from pawly.action_selection import ActionCandidate, ActionDecision
+from pawly.runtime import DecisionEngine, PawlyRuntime
+
+__all__ = ["ActionCandidate", "ActionDecision", "DecisionEngine", "PawlyRuntime"]

pawly/escalation/patterns.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import re
+
+KEYWORD_ALIASES = {
+    "pricing": {"pricing", "price", "discount", "quote"},
+    "contract": {"contract", "agreement", "terms"},
+    "refund": {"refund", "credit", "chargeback"},
+    "security": {"security", "breach", "fraud", "compromise"},
+    "legal": {"legal", "lawsuit", "attorney"},
+    "fairness": {"fairness", "bias", "discrimination", "accommodation"},
+}
+
+
+def normalize_tokens(text: str) -> set[str]:
+    tokens = set(re.findall(r"[a-z0-9]+", text.lower()))
+    expanded = set(tokens)
+    for canonical, aliases in KEYWORD_ALIASES.items():
+        if tokens & aliases:
+            expanded.add(canonical)
+            expanded.update(aliases)
+    return expanded
+
+
+def text_matches_rule(text: str, rule_text: str) -> bool:
+    text_tokens = normalize_tokens(text)
+    rule_tokens = normalize_tokens(rule_text)
+    if not rule_tokens:
+        return False
+    if rule_text.lower() in text.lower():
+        return True
+    overlap = text_tokens & rule_tokens
+    return len(overlap) >= max(1, min(2, len(rule_tokens) // 2 or 1))

pawly/gateway/__init__.py

@@ -0,0 +1,4 @@
+from .protocol import GatewayProtocol
+from .wrapper import ExecutionGateway, wrap_execute_fn, wrap_executor, wrap_framework_adapter
+
+__all__ = ["ExecutionGateway", "GatewayProtocol", "wrap_execute_fn", "wrap_executor", "wrap_framework_adapter"]

pawly/gateway/adapter_support.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+from pawly.gateway import ExecutionGateway, GatewayProtocol
+from pawly.runtime import PawlyRuntime
+
+
+T = TypeVar("T")
+
+AdapterExecutor = Callable[[T], Any]
+AdapterRemap = Callable[[T, Any], T]
+AuditHook = Callable[[dict[str, Any]], None]
+AuditPayloadBuilder = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+def build_gateway(
+    runtime: PawlyRuntime,
+    *,
+    approval_handler: object | None = None,
+    gateway: GatewayProtocol | None = None,
+) -> GatewayProtocol:
+    return gateway or ExecutionGateway(runtime, approval_handler=approval_handler)
+
+
+def metadata_from_intent(intent: Any) -> dict[str, Any]:
+    metadata = dict(intent.metadata)
+    for key, value in intent.action.arguments.items():
+        if key != "task":
+            metadata[key] = value
+    return metadata
+
+
+def execute_adapter_action(
+    *,
+    gateway: GatewayProtocol,
+    item: T,
+    task: str,
+    action: str,
+    confidence: float,
+    metadata: dict[str, Any],
+    executor: AdapterExecutor[T],
+    remap: AdapterRemap[T],
+    audit_hook: AuditHook | None = None,
+    audit_payload: AuditPayloadBuilder | None = None,
+) -> dict[str, Any]:
+    outcome = gateway.execute(
+        task=task,
+        action=action,
+        confidence=confidence,
+        metadata=metadata,
+        executor=lambda intent: executor(remap(item, intent)),
+    )
+    if audit_hook is not None and audit_payload is not None:
+        audit_hook(audit_payload(outcome))
+    return outcome

pawly/gateway/protocol.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Protocol
+
+from pawly.contracts import Intent
+
+
+ExecutorFunc = Callable[[Intent], Any]
+
+
+class GatewayProtocol(Protocol):
+    def execute(
+        self,
+        *,
+        task: str,
+        action: str,
+        confidence: float,
+        executor: ExecutorFunc,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        ...
+
+    def execute_intent(self, intent: Intent, executor: ExecutorFunc) -> dict[str, Any]:
+        ...