pawly 0.1.0__py3-none-any.whl

pawly/pawprint_loader.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from pawly.loader.yaml_loader import load_yaml_file
+from pawly.validator.validator import PawprintValidator, SchemaValidationError
+
+LOGGER = logging.getLogger(__name__)
+
+PROTECTED_SKILL_WARNING = (
+    "This skill declares skill-protection metadata. Open-source Pawly provides baseline protection only. "
+    "For stronger skill-protection controls and managed enforcement, upgrade at https://aploy.ai."
+)
+
+PRIVATE_SKILL_FIELDS = {
+    "raw_prompt",
+    "core_prompt",
+    "private_prompt",
+    "private_rubric",
+    "private_examples",
+    "private_assets",
+    "private_notes",
+    "internal_rules",
+    "developer_secret",
+    "hidden_instructions",
+}
+
+PUBLIC_SKILL_CARD_FIELDS = {
+    "input_schema",
+    "output_schema",
+    "public_usage_notes",
+}
+
+
+@dataclass(slots=True)
+class SkillProtection:
+    level: str
+    raw_prompt_visible_to_model: bool
+    examples_visible_to_model: bool
+    allow_prompt_export: bool
+    allow_training_use: bool
+    allow_distillation: bool
+    require_no_train_route: bool
+    watermark_outputs: bool
+    monitor_extraction: bool
+    max_calls_per_user_per_day: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "level": self.level,
+            "raw_prompt_visible_to_model": self.raw_prompt_visible_to_model,
+            "examples_visible_to_model": self.examples_visible_to_model,
+            "allow_prompt_export": self.allow_prompt_export,
+            "allow_training_use": self.allow_training_use,
+            "allow_distillation": self.allow_distillation,
+            "require_no_train_route": self.require_no_train_route,
+            "watermark_outputs": self.watermark_outputs,
+            "monitor_extraction": self.monitor_extraction,
+        }
+        if self.max_calls_per_user_per_day is not None:
+            payload["max_calls_per_user_per_day"] = self.max_calls_per_user_per_day
+        return payload
+
+
+@dataclass(slots=True)
+class SkillLicense:
+    type: str
+    attribution_required: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.type,
+            "attribution_required": self.attribution_required,
+        }
+
+
+@dataclass(slots=True)
+class SkillMetadata:
+    protection: SkillProtection | None = None
+    license: SkillLicense | None = None
+    model_visible_context: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if self.protection is not None:
+            payload["protection"] = self.protection.to_dict()
+        if self.license is not None:
+            payload["license"] = self.license.to_dict()
+        if self.model_visible_context:
+            payload["model_visible_context"] = dict(self.model_visible_context)
+        return payload
+
+
+@dataclass(slots=True)
+class ProtectionConfig:
+    level: str = "standard"
+    assets: list[str] = field(default_factory=list)
+    handling: str = "auto"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "level": self.level,
+            "assets": list(self.assets),
+            "handling": self.handling,
+        }
+
+
+@dataclass(slots=True)
+class PawprintConfig:
+    id: str
+    name: str
+    description: str
+    capabilities: list[str] = field(default_factory=list)
+    allowed_actions: list[str] = field(default_factory=list)
+    review_actions: list[str] = field(default_factory=list)
+    blocked_actions: list[str] = field(default_factory=list)
+    protection: ProtectionConfig | None = None
+    skill_metadata: SkillMetadata | None = None
+    model_visible_skill_context: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "capabilities": list(self.capabilities),
+            "actions": {
+                "allowed": list(self.allowed_actions),
+                "requiring_review": list(self.review_actions),
+                "blocked": list(self.blocked_actions),
+            },
+        }
+        if self.protection is not None:
+            payload["protection"] = self.protection.to_dict()
+        if self.skill_metadata is not None:
+            payload["skill"] = self.skill_metadata.to_dict()
+        if self.model_visible_skill_context:
+            payload["model_visible_skill_context"] = dict(self.model_visible_skill_context)
+        return payload
+
+    def resolved_protection(self) -> ProtectionConfig:
+        if self.protection is not None:
+            return self.protection
+        return ProtectionConfig()
+
+
+@dataclass(slots=True)
+class LoadedPawprint:
+    source_path: Path
+    raw_document: dict[str, Any]
+    config: PawprintConfig
+
+
+def load_pawprint_file(path: str | Path, validator: PawprintValidator | None = None) -> LoadedPawprint:
+    resolved_path = Path(path)
+    raw_document = _load_document(resolved_path)
+    validated_validator = validator or PawprintValidator()
+    validation = validated_validator.validate_agent_config(raw_document)
+    if not validation.valid:
+        raise SchemaValidationError("; ".join(validation.errors))
+    return LoadedPawprint(
+        source_path=resolved_path,
+        raw_document=raw_document,
+        config=parse_pawprint_document(raw_document),
+    )
+
+
+def parse_pawprint_document(raw_document: dict[str, Any]) -> PawprintConfig:
+    metadata = _mapping(raw_document.get("metadata"))
+    boundaries = _mapping(raw_document.get("boundaries"))
+    protection = _mapping(raw_document.get("protection"))
+    skill = _mapping(raw_document.get("skill"))
+    capabilities = raw_document.get("capabilities", [])
+    skill_metadata = _parse_skill_metadata(metadata, skill)
+
+    return PawprintConfig(
+        id=str(metadata["id"]),
+        name=str(metadata["name"]),
+        description=str(metadata["description"]),
+        capabilities=[
+            str(item.get("name", "")).strip()
+            for item in capabilities
+            if isinstance(item, dict) and str(item.get("name", "")).strip()
+        ],
+        allowed_actions=_string_list(boundaries.get("allow", [])),
+        review_actions=_string_list(boundaries.get("review", [])),
+        blocked_actions=_string_list(boundaries.get("block", [])),
+        protection=_parse_protection_config(protection),
+        skill_metadata=skill_metadata,
+        model_visible_skill_context={} if skill_metadata is None else dict(skill_metadata.model_visible_context),
+    )
+
+
+def _load_document(path: Path) -> dict[str, Any]:
+    suffix = path.suffix.lower()
+    if suffix == ".json":
+        data = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        data = load_yaml_file(path)
+    if not isinstance(data, dict):
+        raise SchemaValidationError("Pawprint document must be a JSON or YAML object")
+    return data
+
+
+def _mapping(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return value
+    return {}
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip()]
+
+
+def _parse_skill_metadata(metadata: dict[str, Any], skill: dict[str, Any]) -> SkillMetadata | None:
+    if not skill:
+        return None
+
+    protection = _parse_skill_protection(skill.get("protection"))
+    if protection is not None and protection.level in {"protected", "vault"}:
+        LOGGER.warning(PROTECTED_SKILL_WARNING)
+
+    license = _parse_skill_license(skill.get("license"))
+    return SkillMetadata(
+        protection=protection,
+        license=license,
+        model_visible_context=build_model_visible_skill_context(metadata, skill),
+    )
+
+
+def _parse_skill_protection(value: Any) -> SkillProtection | None:
+    mapping = _mapping(value)
+    if not mapping:
+        return None
+    limit = mapping.get("max_calls_per_user_per_day")
+    max_calls = None if limit is None else float(limit)
+    return SkillProtection(
+        level=str(mapping.get("level", "")),
+        raw_prompt_visible_to_model=bool(mapping.get("raw_prompt_visible_to_model")),
+        examples_visible_to_model=bool(mapping.get("examples_visible_to_model")),
+        allow_prompt_export=bool(mapping.get("allow_prompt_export")),
+        allow_training_use=bool(mapping.get("allow_training_use")),
+        allow_distillation=bool(mapping.get("allow_distillation")),
+        require_no_train_route=bool(mapping.get("require_no_train_route")),
+        watermark_outputs=bool(mapping.get("watermark_outputs")),
+        monitor_extraction=bool(mapping.get("monitor_extraction")),
+        max_calls_per_user_per_day=max_calls,
+    )
+
+
+def _parse_skill_license(value: Any) -> SkillLicense | None:
+    mapping = _mapping(value)
+    if not mapping:
+        return None
+    return SkillLicense(
+        type=str(mapping.get("type", "")),
+        attribution_required=bool(mapping.get("attribution_required")),
+    )
+
+
+def _parse_protection_config(value: Any) -> ProtectionConfig | None:
+    mapping = _mapping(value)
+    if not mapping:
+        return None
+    return ProtectionConfig(
+        level=str(mapping.get("level", "standard")).strip() or "standard",
+        assets=_string_list(mapping.get("assets", [])),
+        handling=str(mapping.get("handling", "auto")).strip() or "auto",
+    )
+
+
+def build_model_visible_skill_context(metadata: dict[str, Any], skill: dict[str, Any]) -> dict[str, Any]:
+    context: dict[str, Any] = {}
+    name = metadata.get("name")
+    description = metadata.get("description")
+    if isinstance(name, str) and name.strip():
+        context["name"] = name
+    if isinstance(description, str) and description.strip():
+        context["description"] = description
+
+    for key in PUBLIC_SKILL_CARD_FIELDS:
+        value = skill.get(key)
+        if value is not None:
+            context[key] = value
+
+    public_card = skill.get("public_skill_card")
+    if isinstance(public_card, dict):
+        for key, value in public_card.items():
+            if key in PRIVATE_SKILL_FIELDS:
+                continue
+            context[key] = value
+
+    for key in PRIVATE_SKILL_FIELDS:
+        context.pop(key, None)
+    return context

pawly/performance/metrics.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from collections import Counter
+
+
+def summarize_decisions(decisions: list[dict]) -> dict:
+    counts = Counter(item.get("type", "unknown") for item in decisions)
+    total = sum(counts.values())
+    return {
+        "total_decisions": total,
+        "allow": counts.get("allow", 0),
+        "deny": counts.get("deny", 0),
+        "require_approval": counts.get("require_approval", 0),
+        "simulate": counts.get("simulate", 0),
+    }
+
+
+def summarize_policy_evaluations(decisions: list[dict]) -> dict:
+    counts = Counter(item.get("policy_evaluation", {}).get("type", "unknown") for item in decisions)
+    total = sum(counts.values())
+    return {
+        "total_policy_evaluations": total,
+        "allow": counts.get("allow", 0),
+        "deny": counts.get("deny", 0),
+        "require_approval": counts.get("require_approval", 0),
+        "simulate": counts.get("simulate", 0),
+    }
+
+
+def summarize_runtime_overlays(decisions: list[dict]) -> dict:
+    overlay_decisions = 0
+    budget_exhausted = 0
+    budget_warning_decisions = 0
+    for item in decisions:
+        overlays = item.get("runtime_overlays", {})
+        budget = overlays.get("budget", {})
+        has_overlay = bool(overlays.get("overlay_applied"))
+        if budget.get("exhausted"):
+            budget_exhausted += 1
+        if budget.get("warnings"):
+            budget_warning_decisions += 1
+        if has_overlay:
+            overlay_decisions += 1
+    return {
+        "overlay_decisions": overlay_decisions,
+        "budget_exhausted": budget_exhausted,
+        "budget_warning_decisions": budget_warning_decisions,
+    }

pawly/performance/report.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+
+from pawly.pawprint_loader import PawprintConfig
+from pawly.performance.metrics import summarize_decisions, summarize_policy_evaluations, summarize_runtime_overlays
+
+
+def build_daily_report(agent_config: PawprintConfig, decisions: list[dict]) -> dict:
+    metrics = summarize_decisions(decisions)
+    policy_metrics = summarize_policy_evaluations(decisions)
+    overlay_metrics = summarize_runtime_overlays(decisions)
+    report = {
+        "worker_id": agent_config.id,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "summary": {
+            "status": "failed" if metrics["deny"] else "needs-review" if (metrics["require_approval"] or metrics["simulate"]) else "ok",
+            "notes": [
+                f"total_decisions={metrics['total_decisions']}",
+                f"allow={metrics['allow']}",
+                f"require_approval={metrics['require_approval']}",
+                f"deny={metrics['deny']}",
+                f"simulate={metrics['simulate']}",
+            ],
+        },
+        "policy_summary": {
+            "status": "failed" if policy_metrics["deny"] else "needs-review" if (policy_metrics["require_approval"] or policy_metrics["simulate"]) else "ok",
+            "notes": [
+                f"total_policy_evaluations={policy_metrics['total_policy_evaluations']}",
+                f"allow={policy_metrics['allow']}",
+                f"require_approval={policy_metrics['require_approval']}",
+                f"deny={policy_metrics['deny']}",
+                f"simulate={policy_metrics['simulate']}",
+            ],
+        },
+        "runtime_overlay_summary": {
+            "notes": [
+                f"overlay_decisions={overlay_metrics['overlay_decisions']}",
+                f"budget_exhausted={overlay_metrics['budget_exhausted']}",
+                f"budget_warning_decisions={overlay_metrics['budget_warning_decisions']}",
+            ],
+        },
+    }
+    return report

pawly/policy/__init__.py

@@ -0,0 +1,15 @@
+"""Action-scoring policy abstractions for Pawly OSS."""
+
+from .base import Policy
+from .heuristic import DefaultOssPolicy, HeuristicPolicy
+from .resolve import resolve_action_routing_policies, resolve_reviewer_policy, resolve_reviewer_selection, resolve_scoring_policy
+
+__all__ = [
+    "DefaultOssPolicy",
+    "HeuristicPolicy",
+    "Policy",
+    "resolve_action_routing_policies",
+    "resolve_reviewer_policy",
+    "resolve_reviewer_selection",
+    "resolve_scoring_policy",
+]

pawly/policy/base.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+from pawly.contracts import Action, PolicyScore
+
+
+class ScoringPolicyUnavailableError(RuntimeError):
+    """Raised when a scoring policy is configured but cannot be used."""
+
+
+class Policy(ABC):
+    """Scores already-filtered candidate actions without executing or constraining them."""
+
+    name = "custom"
+    source = "custom"
+    policy_source = "custom"
+    supports_scoring = None
+    supports_scoring_decision = False
+
+    def source_name(self) -> str:
+        return str(getattr(self, "source", getattr(self, "policy_source", "custom")))
+
+    def is_scoring_capable(self) -> bool:
+        support_mode = getattr(self, "supports_scoring", getattr(self, "supports_scoring_decision", False))
+        if support_mode is None:
+            support_mode = getattr(self, "supports_scoring_decision", False)
+        return bool(support_mode is True)
+
+    def scoring_support_mode(self) -> str:
+        support_mode = getattr(self, "supports_scoring", getattr(self, "supports_scoring_decision", False))
+        if support_mode is None:
+            support_mode = getattr(self, "supports_scoring_decision", False)
+        if support_mode is True:
+            return "native"
+        if support_mode == "fallback":
+            return "fallback"
+        return "none"
+
+    def is_scoring_available(self) -> bool:
+        return self.is_scoring_capable()
+
+    def scoring_unavailable_reason(self) -> str | None:
+        return None
+
+    def local_policy(self) -> "Policy":
+        return self
+
+    def fallback_scoring_policy(self) -> "Policy | None":
+        return None
+
+    @abstractmethod
+    def evaluate(self, state: Any, actions: Sequence[Action]) -> list[PolicyScore]:
+        """Return one score per action in the same order as the input sequence."""
+
+
+_SOURCE_PREFIX = "source:"
+
+
+def score_source(score: PolicyScore, default_source: str = "custom") -> str:
+    for tag in score.audit_tags:
+        if tag.startswith(_SOURCE_PREFIX):
+            return tag.split(":", 1)[1]
+    return default_source
+
+
+def tag_scores(scores: Sequence[PolicyScore], source: str) -> list[PolicyScore]:
+    tagged_scores: list[PolicyScore] = []
+    source_tag = f"{_SOURCE_PREFIX}{source}"
+    for score in scores:
+        audit_tags = [tag for tag in score.audit_tags if not tag.startswith(_SOURCE_PREFIX)]
+        audit_tags.append(source_tag)
+        tagged_scores.append(
+            PolicyScore(
+                risk_score=score.risk_score,
+                reason_codes=list(score.reason_codes),
+                matched_rules=list(score.matched_rules),
+                audit_tags=audit_tags,
+                uncertainty=score.uncertainty,
+            )
+        )
+    return tagged_scores

pawly/policy/cloud.py

@@ -0,0 +1,18 @@
+"""Compatibility shim for the optional external pawly-cloud package."""
+
+from __future__ import annotations
+
+from importlib import import_module
+
+
+def __getattr__(name: str):
+    if name != "CloudPolicy":
+        raise AttributeError(name)
+    try:
+        module = import_module("pawly_cloud")
+    except ModuleNotFoundError as exc:
+        raise ModuleNotFoundError(
+            "CloudPolicy moved to the optional sibling package 'pawly-cloud'. "
+            "Install or add 'pawly-cloud' and import CloudPolicy from 'pawly_cloud'."
+        ) from exc
+    return getattr(module, "CloudPolicy")

pawly/policy/heuristic.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pawly.contracts import Action, PolicyScore
+
+from .base import Policy, tag_scores
+
+
+_HIGH_IMPACT_TERMS = frozenset({"approve", "delete", "deploy", "publish", "refund", "remove", "send"})
+_LOW_IMPACT_TERMS = frozenset({"answer", "draft", "fetch", "list", "preview", "read", "summarize", "view"})
+
+
+class HeuristicPolicy(Policy):
+    """Deterministic OSS baseline for ranking already-allowed actions."""
+
+    name = "heuristic"
+    source = "heuristic"
+    policy_source = "heuristic"
+    supports_scoring = "fallback"
+    supports_scoring_decision = False
+
+    def evaluate(self, state: Any, actions: Sequence[Action]) -> list[PolicyScore]:
+        preferred_targets = _preferred_targets(state)
+        recent_failures = _recent_failures(state)
+        return tag_scores(
+            [
+                _score_action(
+                    action,
+                    preferred_targets=preferred_targets,
+                    recent_failures=recent_failures,
+                )
+                for action in actions
+            ],
+            self.source_name(),
+        )
+
+
+DefaultOssPolicy = HeuristicPolicy
+
+
+def _score_action(
+    action: Action,
+    *,
+    preferred_targets: set[str],
+    recent_failures: set[str],
+) -> PolicyScore:
+    score = 0.5
+    reason_codes: list[str] = []
+    matched_rules: list[str] = []
+    audit_tags: list[str] = ["policy:heuristic"]
+
+    if action.target:
+        normalized_target = action.target.strip().lower()
+        if normalized_target in preferred_targets:
+            score -= 0.1
+            reason_codes.append("preferred_target")
+            audit_tags.append(f"target:{normalized_target}")
+        else:
+            score += 0.05
+            reason_codes.append("unrecognized_target")
+    else:
+        score += 0.03
+        reason_codes.append("missing_target")
+
+    normalized_name = action.name.strip().lower()
+    if normalized_name in recent_failures:
+        score += 0.2
+        reason_codes.append("recent_failure")
+        audit_tags.append("history:retry")
+
+    action_terms = _tokenize(action.name)
+    if action_terms & _LOW_IMPACT_TERMS:
+        score -= 0.05
+        reason_codes.append("low_friction_action")
+
+    complexity_penalty = _complexity_penalty(action)
+    if complexity_penalty:
+        score += complexity_penalty
+        reason_codes.append("action_complexity")
+
+    impact_adjustment, impact_code = _impact_adjustment(action.name)
+    score += impact_adjustment
+    if impact_code is not None:
+        reason_codes.append(impact_code)
+
+    return PolicyScore(
+        risk_score=_clamp(score),
+        reason_codes=reason_codes,
+        matched_rules=matched_rules,
+        audit_tags=audit_tags,
+    )
+
+
+def _preferred_targets(state: Any) -> set[str]:
+    if not isinstance(state, Mapping):
+        return set()
+    raw_targets = state.get("preferred_targets", [])
+    if not isinstance(raw_targets, Sequence) or isinstance(raw_targets, (str, bytes)):
+        return set()
+    return {str(item).strip().lower() for item in raw_targets if str(item).strip()}
+
+
+def _recent_failures(state: Any) -> set[str]:
+    if not isinstance(state, Mapping):
+        return set()
+    raw_failures = state.get("recent_failures", [])
+    if not isinstance(raw_failures, Sequence) or isinstance(raw_failures, (str, bytes)):
+        return set()
+    return {str(item).strip().lower() for item in raw_failures if str(item).strip()}
+
+
+def _complexity_penalty(action: Action) -> float:
+    penalty = 0.0
+    if len(action.arguments) > 4:
+        penalty += 0.05
+    for value in action.arguments.values():
+        if isinstance(value, Mapping):
+            penalty += 0.05
+        elif isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+            penalty += 0.03
+    return min(penalty, 0.15)
+
+
+def _impact_adjustment(action_name: str) -> tuple[float, str | None]:
+    terms = _tokenize(action_name)
+    if terms & _HIGH_IMPACT_TERMS:
+        return 0.2, "high_impact_action"
+    if terms & _LOW_IMPACT_TERMS:
+        return -0.1, "low_impact_action"
+    return 0.0, None
+
+
+def _tokenize(value: str) -> set[str]:
+    normalized = value.replace("-", " ").replace("_", " ").lower()
+    return {token for token in normalized.split() if token}
+
+
+def _clamp(value: float) -> float:
+    return max(0.0, min(1.0, round(value, 4)))