agent-action-policy 0.1.0__tar.gz

agent_action_policy-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg
+.eggs/
+
+CLAUDE.md
+PLAN.txt
+.env
+.env.local

agent_action_policy-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuartzUnit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_action_policy-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: agent-action-policy
+Version: 0.1.0
+Summary: Declarative action policies for AI agents — approve, deny, or escalate any tool call before execution
+Project-URL: Homepage, https://github.com/QuartzUnit/agent-action-policy
+Project-URL: Repository, https://github.com/QuartzUnit/agent-action-policy
+Project-URL: Issues, https://github.com/QuartzUnit/agent-action-policy/issues
+Author-email: hmj <hmj@quartzunit.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai-agent,guardrail,llm,policy,safety,security,tool-use
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# agent-action-policy
+
+Declarative action policies for AI agents — approve, deny, or escalate any tool call before execution.
+
+## Install
+
+```bash
+pip install agent-action-policy
+pip install agent-action-policy[yaml]  # for YAML policy files
+```
+
+## Quick Start
+
+```python
+from action_policy import PolicyEngine, Action
+
+engine = PolicyEngine.from_dict({
+    "policies": [{
+        "name": "no-force-push",
+        "match": {"tool": "bash", "args_pattern": "git push --force"},
+        "action": "deny",
+        "reason": "Force push requires human approval",
+    }]
+})
+
+decision = engine.evaluate(tool="bash", args={"command": "git push --force origin main"})
+print(decision.denied)  # True
+print(decision.reason)  # "Force push requires human approval"
+```
+
+## Sandboxing vs Policy
+
+| | Sandboxing (containers) | Policy (this library) |
+|---|---|---|
+| **Controls** | *Where* code runs | *What* the agent can do |
+| **Granularity** | Process-level | Per-tool-call |
+| **Configuration** | Infrastructure | YAML/Python |
+| **Use with** | Any runtime | Any agent framework |
+
+Sandboxing and policies are complementary. Use both.
+
+## Policy Definition (YAML)
+
+```yaml
+policies:
+  - name: no-destructive-git
+    match:
+      tool: bash
+      args_pattern: "git (push --force|reset --hard|branch -D)"
+    action: deny
+    reason: "Destructive git operations require human approval"
+
+  - name: escalate-system-files
+    match:
+      tool: "~(file_write|write_file)"
+      path_patterns:
+        - "/etc/*"
+        - "/usr/*"
+    action: escalate
+    reason: "System file modification needs confirmation"
+
+  - name: approve-reads
+    match:
+      tool: "~(read|search|grep)"
+    action: approve
+    priority: 10  # lower = higher priority
+```
+
+## Built-in Templates
+
+```python
+engine = PolicyEngine.from_template("safe_coding")
+```
+
+| Template | What it protects |
+|----------|-----------------|
+| `safe_coding` | Blocks force-push, rm -rf, system file writes, credential access, hook skipping |
+| `safe_browsing` | Blocks internal URLs, file:// protocol, escalates downloads |
+| `safe_database` | Blocks DDL (DROP/TRUNCATE), escalates DELETE and WHERE-less UPDATE |
+| `strict` | Whitelist mode — only read operations allowed, everything else denied |
+
+## Python API
+
+```python
+# From YAML file
+engine = PolicyEngine.from_yaml("policies.yaml")
+
+# From dict
+engine = PolicyEngine.from_dict({"policies": [...]})
+
+# From template
+engine = PolicyEngine.from_template("safe_coding")
+
+# Evaluate
+decision = engine.evaluate(tool="bash", args={"command": "rm -rf /"})
+decision.action     # Action.DENY
+decision.denied     # True
+decision.reason     # "..."
+decision.policy_name  # "no-rm-rf"
+
+# Fail-closed mode (deny by default)
+engine = PolicyEngine.from_template("strict", default_action=Action.DENY)
+
+# Decorator
+@engine.guard
+def execute_tool(tool: str, args: dict = None):
+    ...  # raises PolicyDenied or PolicyEscalated
+```
+
+## Pattern Matching
+
+| Pattern type | Syntax | Example |
+|-------------|--------|---------|
+| Exact match | `tool_name` | `"bash"` |
+| Glob | `*`, `?`, `[...]` | `"file_*"` |
+| Regex | `~pattern` | `"~(bash\|shell\|exec)"` |
+| Args regex | any regex | `"git\\s+push\\s+--force"` |
+| Path glob | glob or `~regex` | `"/etc/*"`, `"~\\.env$"` |
+
+## License
+
+MIT

agent_action_policy-0.1.0/README.md

@@ -0,0 +1,122 @@
+# agent-action-policy
+
+Declarative action policies for AI agents — approve, deny, or escalate any tool call before execution.
+
+## Install
+
+```bash
+pip install agent-action-policy
+pip install agent-action-policy[yaml]  # for YAML policy files
+```
+
+## Quick Start
+
+```python
+from action_policy import PolicyEngine, Action
+
+engine = PolicyEngine.from_dict({
+    "policies": [{
+        "name": "no-force-push",
+        "match": {"tool": "bash", "args_pattern": "git push --force"},
+        "action": "deny",
+        "reason": "Force push requires human approval",
+    }]
+})
+
+decision = engine.evaluate(tool="bash", args={"command": "git push --force origin main"})
+print(decision.denied)  # True
+print(decision.reason)  # "Force push requires human approval"
+```
+
+## Sandboxing vs Policy
+
+| | Sandboxing (containers) | Policy (this library) |
+|---|---|---|
+| **Controls** | *Where* code runs | *What* the agent can do |
+| **Granularity** | Process-level | Per-tool-call |
+| **Configuration** | Infrastructure | YAML/Python |
+| **Use with** | Any runtime | Any agent framework |
+
+Sandboxing and policies are complementary. Use both.
+
+## Policy Definition (YAML)
+
+```yaml
+policies:
+  - name: no-destructive-git
+    match:
+      tool: bash
+      args_pattern: "git (push --force|reset --hard|branch -D)"
+    action: deny
+    reason: "Destructive git operations require human approval"
+
+  - name: escalate-system-files
+    match:
+      tool: "~(file_write|write_file)"
+      path_patterns:
+        - "/etc/*"
+        - "/usr/*"
+    action: escalate
+    reason: "System file modification needs confirmation"
+
+  - name: approve-reads
+    match:
+      tool: "~(read|search|grep)"
+    action: approve
+    priority: 10  # lower = higher priority
+```
+
+## Built-in Templates
+
+```python
+engine = PolicyEngine.from_template("safe_coding")
+```
+
+| Template | What it protects |
+|----------|-----------------|
+| `safe_coding` | Blocks force-push, rm -rf, system file writes, credential access, hook skipping |
+| `safe_browsing` | Blocks internal URLs, file:// protocol, escalates downloads |
+| `safe_database` | Blocks DDL (DROP/TRUNCATE), escalates DELETE and WHERE-less UPDATE |
+| `strict` | Whitelist mode — only read operations allowed, everything else denied |
+
+## Python API
+
+```python
+# From YAML file
+engine = PolicyEngine.from_yaml("policies.yaml")
+
+# From dict
+engine = PolicyEngine.from_dict({"policies": [...]})
+
+# From template
+engine = PolicyEngine.from_template("safe_coding")
+
+# Evaluate
+decision = engine.evaluate(tool="bash", args={"command": "rm -rf /"})
+decision.action     # Action.DENY
+decision.denied     # True
+decision.reason     # "..."
+decision.policy_name  # "no-rm-rf"
+
+# Fail-closed mode (deny by default)
+engine = PolicyEngine.from_template("strict", default_action=Action.DENY)
+
+# Decorator
+@engine.guard
+def execute_tool(tool: str, args: dict = None):
+    ...  # raises PolicyDenied or PolicyEscalated
+```
+
+## Pattern Matching
+
+| Pattern type | Syntax | Example |
+|-------------|--------|---------|
+| Exact match | `tool_name` | `"bash"` |
+| Glob | `*`, `?`, `[...]` | `"file_*"` |
+| Regex | `~pattern` | `"~(bash\|shell\|exec)"` |
+| Args regex | any regex | `"git\\s+push\\s+--force"` |
+| Path glob | glob or `~regex` | `"/etc/*"`, `"~\\.env$"` |
+
+## License
+
+MIT

agent_action_policy-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-action-policy"
+version = "0.1.0"
+description = "Declarative action policies for AI agents — approve, deny, or escalate any tool call before execution"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "hmj", email = "hmj@quartzunit.com" }]
+keywords = [
+    "agent",
+    "policy",
+    "safety",
+    "guardrail",
+    "tool-use",
+    "llm",
+    "ai-agent",
+    "security",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+yaml = ["pyyaml>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/QuartzUnit/agent-action-policy"
+Repository = "https://github.com/QuartzUnit/agent-action-policy"
+Issues = "https://github.com/QuartzUnit/agent-action-policy/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/action_policy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP"]

agent_action_policy-0.1.0/src/action_policy/__init__.py

@@ -0,0 +1,18 @@
+"""agent-action-policy — Declarative action policies for AI agents.
+
+Approve, deny, or escalate any tool call before execution.
+"""
+
+from action_policy.decision import Action, Decision
+from action_policy.engine import PolicyDenied, PolicyEngine, PolicyEscalated
+from action_policy.policy import PolicyRule
+
+__all__ = [
+    "Action",
+    "Decision",
+    "PolicyDenied",
+    "PolicyEngine",
+    "PolicyEscalated",
+    "PolicyRule",
+]
+__version__ = "0.1.0"

agent_action_policy-0.1.0/src/action_policy/decision.py

@@ -0,0 +1,39 @@
+"""Decision types for policy evaluation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum, auto
+
+
+class Action(Enum):
+    """Policy evaluation result."""
+
+    APPROVE = auto()
+    DENY = auto()
+    ESCALATE = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class Decision:
+    """Result of a policy evaluation."""
+
+    action: Action
+    policy_name: str = ""
+    reason: str = ""
+
+    @property
+    def approved(self) -> bool:
+        return self.action == Action.APPROVE
+
+    @property
+    def denied(self) -> bool:
+        return self.action == Action.DENY
+
+    @property
+    def escalated(self) -> bool:
+        return self.action == Action.ESCALATE
+
+
+# Singleton for default approve (no policy matched)
+APPROVE_DEFAULT = Decision(action=Action.APPROVE, policy_name="", reason="No matching policy — default approve")

agent_action_policy-0.1.0/src/action_policy/engine.py

@@ -0,0 +1,123 @@
+"""Core PolicyEngine — evaluate tool calls against policies."""
+
+from __future__ import annotations
+
+import functools
+from pathlib import Path
+from typing import Any, Callable
+
+from action_policy.decision import APPROVE_DEFAULT, Action, Decision
+from action_policy.loader import load_policies_from_dict, load_policies_from_yaml
+from action_policy.policy import PolicyRule
+
+
+class PolicyEngine:
+    """Declarative action policy engine for AI agents.
+
+    Evaluates tool calls against a set of policies and returns
+    APPROVE, DENY, or ESCALATE decisions.
+
+    Usage:
+        engine = PolicyEngine.from_yaml("policies.yaml")
+        decision = engine.evaluate(tool="bash", args={"command": "rm -rf /"})
+        # -> Decision(action=DENY, policy_name="no-destructive-bash", ...)
+
+    Default behavior (no matching policy): APPROVE (open by default).
+    Use `default_action=Action.DENY` for fail-closed mode.
+    """
+
+    def __init__(
+        self,
+        policies: list[PolicyRule] | None = None,
+        default_action: Action = Action.APPROVE,
+        default_reason: str = "",
+    ):
+        self._policies = sorted(policies or [], key=lambda p: p.priority)
+        self._default_action = default_action
+        self._default_reason = default_reason or (
+            "No matching policy — default approve" if default_action == Action.APPROVE
+            else "No matching policy — default deny (fail-closed)"
+        )
+
+    @classmethod
+    def from_yaml(cls, path: str | Path, **kwargs: Any) -> PolicyEngine:
+        """Load policies from a YAML file."""
+        policies = load_policies_from_yaml(path)
+        return cls(policies=policies, **kwargs)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], **kwargs: Any) -> PolicyEngine:
+        """Load policies from a dict."""
+        policies = load_policies_from_dict(data)
+        return cls(policies=policies, **kwargs)
+
+    @classmethod
+    def from_template(cls, template_name: str, **kwargs: Any) -> PolicyEngine:
+        """Load a built-in policy template.
+
+        Available templates: safe_coding, safe_browsing, safe_database, strict
+        """
+        templates_dir = Path(__file__).parent / "templates"
+        path = templates_dir / f"{template_name}.yaml"
+        if not path.exists():
+            available = [f.stem for f in templates_dir.glob("*.yaml")]
+            raise ValueError(f"Unknown template '{template_name}'. Available: {available}")
+        return cls.from_yaml(path, **kwargs)
+
+    def evaluate(self, tool: str, args: dict[str, Any] | str | None = None) -> Decision:
+        """Evaluate a tool call against all policies.
+
+        First matching policy wins (ordered by priority).
+        """
+        for policy in self._policies:
+            if policy.matches(tool, args):
+                return policy.to_decision()
+
+        if self._default_action == Action.APPROVE:
+            return APPROVE_DEFAULT
+        return Decision(
+            action=self._default_action,
+            policy_name="default",
+            reason=self._default_reason,
+        )
+
+    def guard(self, func: Callable) -> Callable:
+        """Decorator that checks policy before executing the wrapped function.
+
+        The function must accept `tool` as its first argument and `args` as keyword.
+        Raises PolicyDenied if the policy denies the action.
+        """
+        @functools.wraps(func)
+        def wrapper(tool: str, args: dict | str | None = None, **kwargs: Any) -> Any:
+            decision = self.evaluate(tool, args)
+            if decision.denied:
+                raise PolicyDenied(decision)
+            if decision.escalated:
+                raise PolicyEscalated(decision)
+            return func(tool, args=args, **kwargs)
+        return wrapper
+
+    @property
+    def policies(self) -> list[PolicyRule]:
+        return list(self._policies)
+
+    def add_policy(self, policy: PolicyRule) -> None:
+        """Add a policy and re-sort by priority."""
+        self._policies.append(policy)
+        self._policies.sort(key=lambda p: p.priority)
+
+
+class PolicyDenied(Exception):
+    """Raised when a policy denies an action."""
+
+    def __init__(self, decision: Decision):
+        self.decision = decision
+        super().__init__(f"Policy '{decision.policy_name}' denied: {decision.reason}")
+
+
+class PolicyEscalated(Exception):
+    """Raised when a policy requires human escalation."""
+
+    def __init__(self, decision: Decision):
+        self.decision = decision
+        super().__init__(f"Policy '{decision.policy_name}' requires escalation: {decision.reason}")

agent_action_policy-0.1.0/src/action_policy/loader.py

@@ -0,0 +1,35 @@
+"""Policy loader from YAML files and dicts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from action_policy.policy import PolicyRule, policy_from_dict
+
+
+def load_policies_from_yaml(path: str | Path) -> list[PolicyRule]:
+    """Load policies from a YAML file.
+
+    Requires PyYAML (optional dependency).
+    """
+    try:
+        import yaml
+    except ImportError as e:
+        raise ImportError(
+            "PyYAML is required for YAML loading. Install with: pip install agent-action-policy[yaml]"
+        ) from e
+
+    with open(path) as f:
+        data = yaml.safe_load(f)
+
+    return load_policies_from_dict(data)
+
+
+def load_policies_from_dict(data: dict[str, Any]) -> list[PolicyRule]:
+    """Load policies from a dict structure (e.g., already-parsed YAML)."""
+    policies_data = data.get("policies", [])
+    policies = [policy_from_dict(p) for p in policies_data]
+    # Sort by priority (lower = higher priority)
+    policies.sort(key=lambda p: p.priority)
+    return policies

agent_action_policy-0.1.0/src/action_policy/patterns.py

@@ -0,0 +1,74 @@
+"""Pattern matching utilities for policy rules."""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from functools import lru_cache
+
+
+@lru_cache(maxsize=256)
+def _compile_regex(pattern: str) -> re.Pattern:
+    """Compile and cache a regex pattern."""
+    return re.compile(pattern)
+
+
+def match_tool(tool_name: str, pattern: str) -> bool:
+    """Match a tool name against a pattern.
+
+    Supports:
+      - Exact match: "bash"
+      - Glob: "file_*"
+      - Regex (prefixed with ~): "~(bash|shell|exec)"
+    """
+    if pattern.startswith("~"):
+        return bool(_compile_regex(pattern[1:]).search(tool_name))
+    if any(c in pattern for c in ("*", "?", "[")):
+        return fnmatch.fnmatch(tool_name, pattern)
+    return tool_name == pattern
+
+
+def match_args(args: dict | str | None, pattern: str) -> bool:
+    """Match tool arguments against a pattern.
+
+    The pattern is matched against the string representation of args.
+    Supports:
+      - Regex (always): searches the stringified args
+    """
+    if args is None:
+        return False
+    text = _stringify_args(args)
+    try:
+        return bool(_compile_regex(pattern).search(text))
+    except re.error:
+        return False
+
+
+def match_path(path: str, patterns: list[str]) -> bool:
+    """Match a file path against a list of glob/regex patterns.
+
+    Each pattern can be:
+      - Glob: "/etc/*", "~/.ssh/*"
+      - Regex (prefixed with ~): "~\\.env$"
+    """
+    for pat in patterns:
+        if pat.startswith("~"):
+            if _compile_regex(pat[1:]).search(path):
+                return True
+        elif fnmatch.fnmatch(path, pat):
+            return True
+    return False
+
+
+def _stringify_args(args: dict | str | None) -> str:
+    """Convert args to string for pattern matching."""
+    if args is None:
+        return ""
+    if isinstance(args, str):
+        return args
+    if isinstance(args, dict):
+        parts = []
+        for k, v in sorted(args.items()):
+            parts.append(f"{k}={v}")
+        return " ".join(parts)
+    return str(args)