agentpriv 0.1.0__tar.gz

agentpriv-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

agentpriv-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

agentpriv-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 agentpriv contributors
+
+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.

agentpriv-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: agentpriv
+Version: 0.1.0
+Summary: sudo for AI agents - allow, deny, or ask before any tool runs
+Project-URL: Homepage, https://github.com/nichkej/agentpriv
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agentpriv
+
+sudo for AI agents - allow, deny, or ask before any tool runs.
+
+AI agents run tools autonomously, but some calls are too risky to run unchecked. agentpriv gives you a permission layer to control what goes through.
+
+## Why
+
+- **One place** - guard a tool once, every agent using it gets the same rule
+- **Gradual trust** - start on `"ask"`, promote to `"allow"` as you gain confidence
+- **Visibility** - every blocked or prompted call is printed with full arguments, so you see exactly what the agent is trying to do
+- **Framework agnostic** - plain wrapper around your functions, so it works with any agent framework or none at all
+
+## Install
+
+```
+pip install agentpriv
+```
+
+## Quick start
+
+```python
+from agentpriv import guard, guard_all, AgentPrivDenied
+
+safe_send = guard(send_message, policy="ask")
+
+tools = guard_all(
+    [read_messages, send_message, delete_channel],
+    policy={
+        "delete_*": "deny",
+        "send_*":   "ask",
+        "*":        "allow",
+    }
+)
+```
+
+## Three modes
+
+| Mode      | What happens                                                      |
+| --------- | ----------------------------------------------------------------- |
+| `"allow"` | Runs normally, no interruption                                    |
+| `"deny"`  | Raises `AgentPrivDenied` immediately, the function never executes |
+| `"ask"`   | Pauses, shows the call in your terminal, waits for y/n            |
+
+```
+agentpriv: send_message(channel='general', text='deploying now')
+Allow this call? [y/n]: y   # runs the function
+Allow this call? [y/n]: n   # raises AgentPrivDenied
+```
+
+## `on_deny` - raise or return
+
+By default, denied calls raise `AgentPrivDenied`. When using frameworks, set `on_deny="return"` so the LLM sees the denial as a tool result instead of crashing:
+
+```python
+# Plain Python - raises exception
+safe = guard(delete_channel, policy="deny")
+
+# Frameworks - returns error string to the LLM
+safe = guard(delete_channel, policy="deny", on_deny="return")
+```
+
+## Works with any framework
+
+Guard first, then pass to your framework as usual:
+
+**OpenAI Agents SDK**
+
+```python
+safe_delete = function_tool(guard(delete_db, policy="ask", on_deny="return"))
+agent = Agent(name="Demo", tools=[safe_delete])
+```
+
+**LangChain / LangGraph**
+
+```python
+safe_delete = tool(guard(delete_db, policy="ask", on_deny="return"))
+agent = create_agent(model=llm, tools=[safe_delete])
+```
+
+**PydanticAI**
+
+```python
+agent = Agent("openai:gpt-4o", tools=[guard(delete_db, policy="ask", on_deny="return")])
+```
+
+**CrewAI**
+
+```python
+safe_delete = tool("Delete DB")(guard(delete_db, policy="ask", on_deny="return"))
+agent = Agent(role="DBA", tools=[safe_delete])
+```
+
+## Policy matching
+
+- Patterns use glob syntax (`fnmatch`) against the function's `__name__`
+- More specific patterns win over wildcards (`delete_channel` > `delete_*` > `*`)
+- If a function doesn't match any pattern, it defaults to `"deny"` - so forgetting a rule blocks the call rather than silently allowing it. Use `"*": "allow"` as a catch-all to opt out
+
+## License
+
+MIT

agentpriv-0.1.0/README.md

@@ -0,0 +1,102 @@
+# agentpriv
+
+sudo for AI agents - allow, deny, or ask before any tool runs.
+
+AI agents run tools autonomously, but some calls are too risky to run unchecked. agentpriv gives you a permission layer to control what goes through.
+
+## Why
+
+- **One place** - guard a tool once, every agent using it gets the same rule
+- **Gradual trust** - start on `"ask"`, promote to `"allow"` as you gain confidence
+- **Visibility** - every blocked or prompted call is printed with full arguments, so you see exactly what the agent is trying to do
+- **Framework agnostic** - plain wrapper around your functions, so it works with any agent framework or none at all
+
+## Install
+
+```
+pip install agentpriv
+```
+
+## Quick start
+
+```python
+from agentpriv import guard, guard_all, AgentPrivDenied
+
+safe_send = guard(send_message, policy="ask")
+
+tools = guard_all(
+    [read_messages, send_message, delete_channel],
+    policy={
+        "delete_*": "deny",
+        "send_*":   "ask",
+        "*":        "allow",
+    }
+)
+```
+
+## Three modes
+
+| Mode      | What happens                                                      |
+| --------- | ----------------------------------------------------------------- |
+| `"allow"` | Runs normally, no interruption                                    |
+| `"deny"`  | Raises `AgentPrivDenied` immediately, the function never executes |
+| `"ask"`   | Pauses, shows the call in your terminal, waits for y/n            |
+
+```
+agentpriv: send_message(channel='general', text='deploying now')
+Allow this call? [y/n]: y   # runs the function
+Allow this call? [y/n]: n   # raises AgentPrivDenied
+```
+
+## `on_deny` - raise or return
+
+By default, denied calls raise `AgentPrivDenied`. When using frameworks, set `on_deny="return"` so the LLM sees the denial as a tool result instead of crashing:
+
+```python
+# Plain Python - raises exception
+safe = guard(delete_channel, policy="deny")
+
+# Frameworks - returns error string to the LLM
+safe = guard(delete_channel, policy="deny", on_deny="return")
+```
+
+## Works with any framework
+
+Guard first, then pass to your framework as usual:
+
+**OpenAI Agents SDK**
+
+```python
+safe_delete = function_tool(guard(delete_db, policy="ask", on_deny="return"))
+agent = Agent(name="Demo", tools=[safe_delete])
+```
+
+**LangChain / LangGraph**
+
+```python
+safe_delete = tool(guard(delete_db, policy="ask", on_deny="return"))
+agent = create_agent(model=llm, tools=[safe_delete])
+```
+
+**PydanticAI**
+
+```python
+agent = Agent("openai:gpt-4o", tools=[guard(delete_db, policy="ask", on_deny="return")])
+```
+
+**CrewAI**
+
+```python
+safe_delete = tool("Delete DB")(guard(delete_db, policy="ask", on_deny="return"))
+agent = Agent(role="DBA", tools=[safe_delete])
+```
+
+## Policy matching
+
+- Patterns use glob syntax (`fnmatch`) against the function's `__name__`
+- More specific patterns win over wildcards (`delete_channel` > `delete_*` > `*`)
+- If a function doesn't match any pattern, it defaults to `"deny"` - so forgetting a rule blocks the call rather than silently allowing it. Use `"*": "allow"` as a catch-all to opt out
+
+## License
+
+MIT

agentpriv-0.1.0/agentpriv/__init__.py

@@ -0,0 +1,4 @@
+from .core import guard, guard_all
+from .exceptions import AgentPrivDenied
+
+__all__ = ["guard", "guard_all", "AgentPrivDenied"]

agentpriv-0.1.0/agentpriv/core.py

@@ -0,0 +1,93 @@
+import functools
+import inspect
+from fnmatch import fnmatch
+
+from .exceptions import AgentPrivDenied
+from .prompt import ask_human
+
+VALID_POLICIES = ("allow", "deny", "ask")
+
+
+def _resolve_policy(name, policy):
+    """
+    Resolve which policy applies to a function name.
+
+    If policy is a string, return it directly.
+    If policy is a dict, find the best matching pattern.
+    More specific patterns (fewer wildcards / longer) win over broad ones.
+    Falls back to "deny" if nothing matches.
+    """
+    if isinstance(policy, str):
+        if policy not in VALID_POLICIES:
+            raise ValueError(f"Invalid policy {policy!r}, must be one of {VALID_POLICIES}")
+        return policy
+
+    best_policy = "deny"
+    best_specificity = float("-inf")
+
+    for pattern, pol in policy.items():
+        if pol not in VALID_POLICIES:
+            raise ValueError(f"Invalid policy {pol!r} for pattern {pattern!r}")
+        if fnmatch(name, pattern):
+            # specificity = number of non-wildcard characters
+            specificity = len(pattern.replace("*", "").replace("?", ""))
+            if specificity > best_specificity:
+                best_specificity = specificity
+                best_policy = pol
+
+    return best_policy
+
+
+def guard(fn, policy="ask", on_deny="raise"):
+    """
+    Wrap a callable with a permission policy.
+
+    Returns a new callable with the same signature that checks the policy
+    before executing. Supports both sync and async functions.
+
+    on_deny controls what happens when a call is denied:
+      - "raise": raise AgentPrivDenied (default, good for plain Python)
+      - "return": return an error string (good for frameworks like PydanticAI,
+        LangChain, etc. where the LLM sees the tool result)
+    """
+    if on_deny not in ("raise", "return"):
+        raise ValueError(f"Invalid on_deny {on_deny!r}, must be 'raise' or 'return'")
+
+    resolved = _resolve_policy(fn.__name__, policy)
+
+    def _denied(reason):
+        msg = f"Call to {fn.__name__}() denied by {reason}"
+        if on_deny == "return":
+            return msg
+        raise AgentPrivDenied(msg)
+
+    if inspect.iscoroutinefunction(fn):
+        @functools.wraps(fn)
+        async def wrapper(*args, **kwargs):
+            if resolved == "deny":
+                return _denied("policy")
+            if resolved == "ask" and not ask_human(fn.__name__, args, kwargs):
+                return _denied("human")
+            return await fn(*args, **kwargs)
+    else:
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            if resolved == "deny":
+                return _denied("policy")
+            if resolved == "ask" and not ask_human(fn.__name__, args, kwargs):
+                return _denied("human")
+            return fn(*args, **kwargs)
+
+    return wrapper
+
+
+def guard_all(fns, policy=None):
+    """
+    Wrap a list of callables with a policy dict.
+
+    Policy is a dict mapping glob patterns to policy strings.
+    Returns a list of wrapped callables in the same order.
+    """
+    if policy is None:
+        policy = {"*": "ask"}
+    return [guard(fn, policy) for fn in fns]

agentpriv-0.1.0/agentpriv/exceptions.py

@@ -0,0 +1,2 @@
+class AgentPrivDenied(Exception):
+    """Raised when a guarded call is denied by policy or by human."""

agentpriv-0.1.0/agentpriv/prompt.py

@@ -0,0 +1,7 @@
+def ask_human(name, args, kwargs):
+    """Print call details and ask the human for y/n approval."""
+    parts = [repr(a) for a in args] + [f"{k}={v!r}" for k, v in kwargs.items()]
+    sig = ", ".join(parts)
+    print(f"\nagentpriv: {name}({sig})")
+    answer = input("Allow this call? [y/n]: ").strip().lower()
+    return answer == "y"

agentpriv-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentpriv"
+version = "0.1.0"
+description = "sudo for AI agents - allow, deny, or ask before any tool runs"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/nichkej/agentpriv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

agentpriv-0.1.0/tests/test_core.py

@@ -0,0 +1,180 @@
+import asyncio
+import inspect
+from unittest.mock import patch
+
+import pytest
+
+from agentpriv import AgentPrivDenied, guard, guard_all
+
+
+# --- helpers ---
+
+def read_messages():
+    return ["msg1", "msg2"]
+
+def send_message(channel, text):
+    return f"sent to {channel}: {text}"
+
+def delete_channel(name):
+    return f"deleted {name}"
+
+def delete_repo(name):
+    return f"deleted repo {name}"
+
+async def async_read():
+    return "async result"
+
+async def async_delete(name):
+    return f"async deleted {name}"
+
+
+# --- guard() ---
+
+class TestGuardAllow:
+    def test_runs_normally(self):
+        safe = guard(read_messages, policy="allow")
+        assert safe() == read_messages()
+
+    def test_passes_args(self):
+        safe = guard(send_message, policy="allow")
+        assert safe("general", text="hello") == send_message("general", text="hello")
+
+
+class TestGuardDeny:
+    def test_raises(self):
+        safe = guard(delete_channel, policy="deny")
+        with pytest.raises(AgentPrivDenied, match="denied by policy"):
+            safe("general")
+
+    def test_never_calls_function(self):
+        calls = []
+        def tracked():
+            calls.append(1)
+        safe = guard(tracked, policy="deny")
+        with pytest.raises(AgentPrivDenied):
+            safe()
+        assert calls == []
+
+
+class TestGuardAsk:
+    @patch("agentpriv.core.ask_human", return_value=True)
+    def test_approved(self, mock_ask):
+        safe = guard(send_message, policy="ask")
+        assert safe("general", text="hi") == send_message("general", text="hi")
+        mock_ask.assert_called_once_with("send_message", ("general",), {"text": "hi"})
+
+    @patch("agentpriv.core.ask_human", return_value=False)
+    def test_denied(self, _):
+        safe = guard(send_message, policy="ask")
+        with pytest.raises(AgentPrivDenied, match="denied by human"):
+            safe("general", text="hi")
+
+
+class TestGuardAsync:
+    def test_allow(self):
+        safe = guard(async_read, policy="allow")
+        assert inspect.iscoroutinefunction(safe)
+        assert asyncio.run(safe()) == asyncio.run(async_read())
+
+    def test_deny(self):
+        safe = guard(async_delete, policy="deny")
+        assert inspect.iscoroutinefunction(safe)
+        with pytest.raises(AgentPrivDenied):
+            asyncio.run(safe("general"))
+
+    @patch("agentpriv.core.ask_human", return_value=True)
+    def test_ask_approved(self, _):
+        safe = guard(async_read, policy="ask")
+        assert asyncio.run(safe()) == asyncio.run(async_read())
+
+
+# --- guard_all() ---
+
+class TestGuardAll:
+    def _make_tools(self, policy):
+        return guard_all(
+            [read_messages, send_message, delete_channel, delete_repo],
+            policy=policy,
+        )
+
+    def test_deny_pattern(self):
+        tools = self._make_tools({"delete_*": "deny", "*": "allow"})
+        assert tools[0]() == read_messages()
+        with pytest.raises(AgentPrivDenied):
+            tools[2]("general")
+
+    @patch("agentpriv.core.ask_human", return_value=True)
+    def test_ask_pattern(self, _):
+        tools = self._make_tools({"send_*": "ask", "*": "allow"})
+        assert tools[1]("general", text="hi") == send_message("general", text="hi")
+
+    def test_no_match_defaults_to_deny(self):
+        tools = self._make_tools({"send_*": "allow"})
+        with pytest.raises(AgentPrivDenied):
+            tools[0]()
+
+    def test_specific_pattern_wins(self):
+        tools = self._make_tools({
+            "delete_channel": "allow",
+            "delete_*": "deny",
+            "*": "allow",
+        })
+        assert tools[2]("general") == delete_channel("general")
+        with pytest.raises(AgentPrivDenied):
+            tools[3]("myrepo")
+
+    def test_default_policy_is_ask(self):
+        tools = guard_all([read_messages])
+        with patch("agentpriv.core.ask_human", return_value=False):
+            with pytest.raises(AgentPrivDenied):
+                tools[0]()
+
+
+# --- on_deny="return" ---
+
+class TestOnDenyReturn:
+    def test_deny_returns_string(self):
+        safe = guard(delete_channel, policy="deny", on_deny="return")
+        result = safe("general")
+        assert isinstance(result, str)
+        assert "denied by policy" in result
+
+    @patch("agentpriv.core.ask_human", return_value=False)
+    def test_ask_denied_returns_string(self, _):
+        safe = guard(send_message, policy="ask", on_deny="return")
+        result = safe("general", text="hi")
+        assert isinstance(result, str)
+        assert "denied by human" in result
+
+    def test_async_deny_returns_string(self):
+        safe = guard(async_delete, policy="deny", on_deny="return")
+        result = asyncio.run(safe("general"))
+        assert isinstance(result, str)
+        assert "denied by policy" in result
+
+
+# --- edge cases ---
+
+class TestEdgeCases:
+    def test_invalid_policy(self):
+        with pytest.raises(ValueError):
+            guard(read_messages, policy="yolo")
+
+    def test_invalid_policy_in_dict(self):
+        with pytest.raises(ValueError):
+            guard_all([read_messages], policy={"*": "yolo"})
+
+    def test_invalid_on_deny(self):
+        with pytest.raises(ValueError):
+            guard(read_messages, policy="deny", on_deny="explode")
+
+    def test_preserves_function_name(self):
+        safe = guard(send_message, policy="allow")
+        assert safe.__name__ == "send_message"
+
+    def test_preserves_docstring(self):
+        def documented():
+            """My doc."""
+            pass
+        safe = guard(documented, policy="allow")
+        assert safe.__doc__ == "My doc."