pawly 0.1.0__py3-none-any.whl

pawly/runtime_bootstrap.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+from pawly.backends.audit import AuditSink, build_default_audit_sink
+from pawly.backends.reviewer import ReviewerPolicy
+from pawly.backends.risk import RiskProvider
+from pawly.budget.state import BudgetState
+from pawly.memory.store import MemoryStore
+from pawly.middleware.hooks import HookRegistry
+from pawly.pawprint_loader import PawprintConfig, load_pawprint_file
+from pawly.policy import resolve_action_routing_policies, resolve_reviewer_policy, resolve_reviewer_selection
+from pawly.policy.base import Policy
+from pawly.protected_oss import ProtectedAuditRedactingSink, is_protected_skill
+from pawly.runtime_ids import RuntimeIdSequence
+from pawly.validator.validator import PawprintValidator
+
+ScoringPolicyFallbackMode = Literal["review", "heuristic", "deny"]
+
+
+@dataclass(slots=True)
+class RuntimeConfig:
+    agent_path: Path
+    raw_pawprint_config: dict
+    pawprint_config: PawprintConfig
+    reviewer_name: str
+    reviewer_policy: ReviewerPolicy
+    local_scoring_policy: Policy
+    scoring_policy: Policy
+    fallback_scoring_policy: Policy
+    scoring_policy_fallback_mode: ScoringPolicyFallbackMode
+
+
+@dataclass(slots=True)
+class RuntimeServices:
+    audit_sink: AuditSink
+    audit_ledger: object
+    validator: PawprintValidator
+    memory_store: MemoryStore
+    hooks: HookRegistry
+    budget_state: BudgetState = field(default_factory=BudgetState)
+    ids: RuntimeIdSequence = field(default_factory=RuntimeIdSequence)
+    decisions: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class RuntimeBootstrap:
+    config: RuntimeConfig
+    services: RuntimeServices
+
+
+def bootstrap_runtime(
+    *,
+    agent_path: str | Path,
+    audit_path: str | Path | None,
+    policy: str,
+    policy_impl: ReviewerPolicy | None,
+    risk_provider: RiskProvider | None,
+    audit_sink: AuditSink | None,
+    scoring_policy_fallback_mode: ScoringPolicyFallbackMode,
+    scoring_policy: Policy | str | None,
+    reviewer: str | None,
+    reviewer_backend: ReviewerPolicy | None,
+) -> RuntimeBootstrap:
+    resolved_agent_path = Path(agent_path)
+    validator = PawprintValidator()
+    loaded_pawprint = load_pawprint_file(resolved_agent_path, validator)
+
+    selected_policy, selected_policy_impl = resolve_reviewer_selection(
+        policy=policy,
+        policy_impl=policy_impl,
+        reviewer=reviewer,
+        reviewer_backend=reviewer_backend,
+    )
+    local_scoring_policy, scoring_policy_impl, fallback_scoring_policy = resolve_action_routing_policies(scoring_policy)
+    resolved_audit_sink = audit_sink or build_default_audit_sink(audit_path)
+    if is_protected_skill(loaded_pawprint.config):
+        resolved_audit_sink = ProtectedAuditRedactingSink(resolved_audit_sink, loaded_pawprint.config)
+    return RuntimeBootstrap(
+        config=RuntimeConfig(
+            agent_path=resolved_agent_path,
+            raw_pawprint_config=loaded_pawprint.raw_document,
+            pawprint_config=loaded_pawprint.config,
+            reviewer_name=selected_policy,
+            reviewer_policy=resolve_reviewer_policy(
+                selected_policy,
+                policy_impl=selected_policy_impl,
+                risk_provider=risk_provider,
+            ),
+            local_scoring_policy=local_scoring_policy,
+            scoring_policy=scoring_policy_impl,
+            fallback_scoring_policy=fallback_scoring_policy,
+            scoring_policy_fallback_mode=scoring_policy_fallback_mode,
+        ),
+        services=RuntimeServices(
+            audit_sink=resolved_audit_sink,
+            audit_ledger=getattr(resolved_audit_sink, "ledger", resolved_audit_sink),
+            validator=validator,
+            memory_store=MemoryStore("none"),
+            hooks=HookRegistry(),
+        ),
+    )

pawly/runtime_decision.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pawly.contracts import Decision
+from pawly.backends.reviewer import ReviewerPolicy, evaluate_reviewer_policy
+from pawly.budget.checker import BudgetResult, check_budget
+from pawly.budget.state import BudgetState
+from pawly.pawprint_loader import PawprintConfig
+from pawly.policy_engine.models import PolicyEvaluation
+from pawly.policy_engine.runtime_overlay import apply_runtime_overlays
+from pawly.types import Intent
+
+
+@dataclass(slots=True)
+class RuntimeDecisionState:
+    policy_evaluation: PolicyEvaluation
+    budget_result: BudgetResult
+    decision: Decision
+    runtime_overlays: dict[str, object]
+
+
+def evaluate_core_policy(
+    policy: ReviewerPolicy,
+    *,
+    intent: Intent,
+    pawprint: PawprintConfig,
+) -> PolicyEvaluation:
+    return evaluate_reviewer_policy(policy, intent, pawprint)
+
+
+def evaluate_runtime_decision(
+    *,
+    policy: ReviewerPolicy,
+    intent: Intent,
+    pawprint: PawprintConfig,
+    raw_pawprint_config: dict,
+    budget_state: BudgetState,
+) -> RuntimeDecisionState:
+    policy_evaluation = evaluate_core_policy(
+        policy,
+        intent=intent,
+        pawprint=pawprint,
+    )
+    budget_result = check_budget(raw_pawprint_config, budget_state, intent)
+    decision, runtime_overlays = apply_runtime_overlays(policy_evaluation, budget_result)
+    return RuntimeDecisionState(
+        policy_evaluation=policy_evaluation,
+        budget_result=budget_result,
+        decision=decision,
+        runtime_overlays=runtime_overlays,
+    )

pawly/runtime_execute.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from pawly.contracts import Intent
+from pawly.loader.schema_loader import load_pawprint_version
+from pawly.protected_oss import apply_extraction_guardrail
+from pawly.runtime_decision import evaluate_runtime_decision
+from pawly.runtime_bootstrap import RuntimeConfig, RuntimeServices
+from pawly.runtime_flow import (
+    build_before_hook_payload,
+    finalize_runtime_artifacts,
+    remember_allowed_decision,
+    validate_intent_or_raise,
+)
+from pawly.runtime_result import RuntimeDecisionResult, build_runtime_decision_artifacts
+
+
+def evaluate_runtime_intent(
+    *,
+    config: RuntimeConfig,
+    services: RuntimeServices,
+    intent: Intent,
+) -> RuntimeDecisionResult:
+    validate_intent_or_raise(services.validator, intent)
+    services.hooks.run_before(build_before_hook_payload(intent, config.pawprint_config.id))
+
+    decision_state = evaluate_runtime_decision(
+        policy=config.reviewer_policy,
+        intent=intent,
+        pawprint=config.pawprint_config,
+        raw_pawprint_config=config.raw_pawprint_config,
+        budget_state=services.budget_state,
+    )
+    guarded_decision, guarded_runtime_overlays = apply_extraction_guardrail(
+        pawprint=config.pawprint_config,
+        policy_evaluation=decision_state.policy_evaluation,
+        decision=decision_state.decision,
+        runtime_overlays=decision_state.runtime_overlays,
+        intent=intent,
+    )
+    remember_allowed_decision(services.memory_store, intent, guarded_decision)
+
+    artifacts = build_runtime_decision_artifacts(
+        event_id=services.ids.next_event_id(),
+        decision_id=services.ids.next_decision_id(),
+        agent_id=config.pawprint_config.id,
+        pawprint_version=load_pawprint_version(),
+        intent=intent,
+        policy_evaluation=decision_state.policy_evaluation,
+        runtime_overlays=guarded_runtime_overlays,
+        decision=guarded_decision,
+        budget_result=decision_state.budget_result,
+    )
+    return finalize_runtime_artifacts(
+        validator=services.validator,
+        audit_sink=services.audit_sink,
+        hooks=services.hooks,
+        decisions=services.decisions,
+        artifacts=artifacts,
+    )

pawly/runtime_flow.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pawly.contracts import Decision, Intent
+from pawly.memory.store import MemoryStore
+from pawly.middleware.hooks import HookRegistry
+from pawly.runtime_result import RuntimeDecisionArtifacts, RuntimeDecisionResult
+from pawly.validator.validator import PawprintValidator, SchemaValidationError
+
+
+def validate_intent_or_raise(validator: PawprintValidator, intent: Intent) -> None:
+    intent_validation = validator.validate_intent(intent.to_dict())
+    if not intent_validation.valid:
+        raise SchemaValidationError("; ".join(intent_validation.errors))
+
+
+def build_before_hook_payload(intent: Intent, agent_id: str) -> dict[str, object]:
+    return {
+        "intent": intent.to_dict(),
+        "agent_id": agent_id,
+    }
+
+
+def remember_allowed_decision(memory_store: MemoryStore, intent: Intent, decision: Decision) -> None:
+    if decision.type.value != "allow":
+        return
+    memory_store.remember(
+        "default",
+        {"intent": intent.to_dict(), "decision_type": decision.type.value},
+    )
+
+
+def finalize_runtime_artifacts(
+    *,
+    validator: PawprintValidator,
+    audit_sink: Any,
+    hooks: HookRegistry,
+    decisions: list[dict[str, Any]],
+    artifacts: RuntimeDecisionArtifacts,
+) -> RuntimeDecisionResult:
+    audit_sink.append(artifacts.event)
+    decision_validation = validator.validate_decision(artifacts.result.decision.to_dict())
+    if not decision_validation.valid:
+        raise SchemaValidationError("; ".join(decision_validation.errors))
+
+    result_payload = artifacts.result.to_dict()
+    decisions.append(result_payload)
+    hooks.run_after(result_payload)
+    return artifacts.result

pawly/runtime_ids.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from itertools import count
+
+
+@dataclass(slots=True)
+class RuntimeIdSequence:
+    _decision_counter: count = field(default_factory=lambda: count(1))
+    _event_counter: count = field(default_factory=lambda: count(1))
+
+    def next_intent_id(self) -> str:
+        return f"intent-{next(self._decision_counter)}"
+
+    def next_decision_id(self) -> str:
+        return f"decision-{next(self._decision_counter)}"
+
+    def next_event_id(self) -> str:
+        return f"event-{next(self._event_counter)}"

pawly/runtime_report.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from pawly.pawprint_loader import PawprintConfig
+from pawly.performance.report import build_daily_report
+from pawly.validator.validator import PawprintValidator, SchemaValidationError
+
+
+def build_validated_runtime_report(
+    *,
+    validator: PawprintValidator,
+    pawprint: PawprintConfig,
+    decisions: list[dict],
+) -> dict:
+    report = build_daily_report(pawprint, decisions)
+    validation = validator.validate_report(report)
+    if not validation.valid:
+        raise SchemaValidationError("; ".join(validation.errors))
+    return report

pawly/runtime_request.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pawly.contracts import Intent
+from pawly.task_request import TaskRequest
+
+
+def build_task_request_intent(
+    *,
+    task: str,
+    action: str,
+    confidence: float,
+    metadata: dict[str, Any] | None = None,
+    intent_id: str = "intent-from-task-request",
+) -> Intent:
+    request = TaskRequest(
+        task=task,
+        action=action,
+        confidence=confidence,
+        metadata=metadata or {},
+    )
+    return request.to_intent(intent_id=intent_id)

pawly/runtime_result.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from pawly.contracts import Decision, Intent
+from pawly.audit.events import AuditEvent
+from pawly.budget.checker import BudgetResult
+from pawly.policy_engine.models import PolicyEvaluation
+
+
+@dataclass(slots=True)
+class RuntimeDecisionArtifacts:
+    event: AuditEvent
+    result: RuntimeDecisionResult
+
+
+@dataclass(slots=True)
+class RuntimeDecisionResult:
+    agent_id: str
+    pawprint_version: str
+    intent: Intent
+    policy_evaluation: PolicyEvaluation
+    runtime_overlays: dict[str, object]
+    decision_id: str
+    decision: Decision
+    budget_consumed: dict[str, float]
+
+    @classmethod
+    def from_dict(cls, payload: dict[str, Any]) -> "RuntimeDecisionResult":
+        return cls(
+            agent_id=str(payload["agent_id"]),
+            pawprint_version=str(payload["pawprint_version"]),
+            intent=Intent.from_dict(payload["intent"]),
+            policy_evaluation=PolicyEvaluation.from_dict(payload["policy_evaluation"]),
+            runtime_overlays=dict(payload["runtime_overlays"]),
+            decision_id=str(payload["decision_id"]),
+            decision=Decision.from_dict(payload),
+            budget_consumed=dict(payload.get("budget_consumed", {})),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "agent_id": self.agent_id,
+            "pawprint_version": self.pawprint_version,
+            "intent": self.intent.to_dict(),
+            "policy_evaluation": self.policy_evaluation.to_dict(),
+            "runtime_overlays": self.runtime_overlays,
+            "decision_id": self.decision_id,
+            **self.decision.to_dict(),
+            "budget_consumed": self.budget_consumed,
+        }
+
+
+def build_decision_audit_event(
+    *,
+    event_id: str,
+    decision_id: str,
+    agent_id: str,
+    pawprint_version: str,
+    intent: Intent,
+    policy_evaluation: PolicyEvaluation,
+    runtime_overlays: dict[str, object],
+    decision: Decision,
+) -> AuditEvent:
+    intent_payload = intent.to_dict()
+    return AuditEvent.from_decision(
+        event_id=event_id,
+        decision_id=decision_id,
+        agent_id=agent_id,
+        pawprint_version=pawprint_version,
+        outcome=decision.type.value,
+        original_intent=intent_payload,
+        normalized_intent=intent_payload,
+        action_name=intent.action.name,
+        policy_evaluation=policy_evaluation.to_dict(),
+        runtime_overlays=runtime_overlays,
+        policy_references=decision.matched_rules,
+        final_decision=decision.to_dict(),
+        reason_codes=decision.reason_codes,
+        risk_score=decision.risk_score,
+        escalated_to=policy_evaluation.handoff_target if decision.type.value == "require_approval" else None,
+    )
+
+
+def build_decision_result(
+    *,
+    agent_id: str,
+    pawprint_version: str,
+    intent: Intent,
+    policy_evaluation: PolicyEvaluation,
+    runtime_overlays: dict[str, object],
+    decision_id: str,
+    decision: Decision,
+    budget_result: BudgetResult,
+) -> RuntimeDecisionResult:
+    return RuntimeDecisionResult(
+        agent_id=agent_id,
+        pawprint_version=pawprint_version,
+        intent=intent,
+        policy_evaluation=policy_evaluation,
+        runtime_overlays=runtime_overlays,
+        decision_id=decision_id,
+        decision=decision,
+        budget_consumed=budget_result.consumed,
+    )
+
+
+def build_runtime_decision_artifacts(
+    *,
+    event_id: str,
+    decision_id: str,
+    agent_id: str,
+    pawprint_version: str,
+    intent: Intent,
+    policy_evaluation: PolicyEvaluation,
+    runtime_overlays: dict[str, object],
+    decision: Decision,
+    budget_result: BudgetResult,
+) -> RuntimeDecisionArtifacts:
+    return RuntimeDecisionArtifacts(
+        event=build_decision_audit_event(
+            event_id=event_id,
+            decision_id=decision_id,
+            agent_id=agent_id,
+            pawprint_version=pawprint_version,
+            intent=intent,
+            policy_evaluation=policy_evaluation,
+            runtime_overlays=runtime_overlays,
+            decision=decision,
+        ),
+        result=build_decision_result(
+            agent_id=agent_id,
+            pawprint_version=pawprint_version,
+            intent=intent,
+            policy_evaluation=policy_evaluation,
+            runtime_overlays=runtime_overlays,
+            decision_id=decision_id,
+            decision=decision,
+            budget_result=budget_result,
+        ),
+    )

pawly/runtime_scoring.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pawly.contracts import Action, PolicyScore
+from pawly.policy.base import Policy
+
+
+def build_scoring_state(
+    *,
+    state: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    if state is None:
+        return {}
+    return dict(state)
+
+
+def score_actions(
+    *,
+    policy: Policy,
+    actions: Sequence[Action],
+    state: Mapping[str, Any] | None = None,
+) -> list[PolicyScore]:
+    return policy.evaluate(build_scoring_state(state=state), actions)

pawly/schemas/decision.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["type", "reason"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["allow", "deny", "require_approval", "simulate"]
+    },
+    "reason": { "type": "string", "minLength": 1 },
+    "source": { "type": "string" },
+    "reason_codes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "matched_rules": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "risk_score": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
+    "rewritten_action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "arguments"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "arguments": { "type": "object" },
+        "target": { "type": "string" }
+      }
+    },
+    "audit_tags": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "worker_id": { "type": "string" }
+  }
+}

pawly/schemas/intent.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["intent_id", "source", "action", "context", "metadata"],
+  "properties": {
+    "intent_id": { "type": "string", "minLength": 1 },
+    "source": {
+      "type": "string",
+      "enum": ["tool_call", "planner_output", "execution_request"]
+    },
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "arguments"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "arguments": { "type": "object" },
+        "target": { "type": "string" }
+      }
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["summary", "confidence"],
+      "properties": {
+        "summary": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0 }
+      }
+    },
+    "metadata": { "type": "object" }
+  }
+}

pawly/schemas/report.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["worker_id", "generated_at", "summary", "policy_summary", "runtime_overlay_summary"],
+  "properties": {
+    "worker_id": { "type": "string", "minLength": 1 },
+    "generated_at": { "type": "string", "minLength": 1 },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "notes"],
+      "properties": {
+        "status": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "policy_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "notes"],
+      "properties": {
+        "status": { "type": "string" },
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "runtime_overlay_summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["notes"],
+      "properties": {
+        "notes": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}