nanny-sdk 0.1.4__tar.gz

nanny_sdk-0.1.4/.gitignore

@@ -0,0 +1,37 @@
+# Rust build output — never commit this
+/target
+
+# macOS filesystem noise
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# IDE and editor files
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Environment / secrets — never commit these
+.env
+.env.local
+.env.*
+!.env.example
+
+# Python build output and caches
+__pycache__/
+*.py[cod]
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.egg-info/
+dist/
+# Note: uv.lock is intentionally committed — reproducible Python builds.
+
+# Note: Cargo.lock is intentionally committed.
+# This workspace produces a binary (nanny CLI). Committing Cargo.lock ensures
+# every user gets an identical, reproducible build — a direct requirement of
+# the determinism invariant in the Nanny manifesto.
+.windsurf

nanny_sdk-0.1.4/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: nanny-sdk
+Version: 0.1.4
+Summary: Python SDK for the Nanny execution boundary — @tool, @rule, @agent decorators
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27

nanny_sdk-0.1.4/nanny_sdk/__init__.py

@@ -0,0 +1,36 @@
+"""Nanny SDK — execution boundary for AI agents.
+
+    from nanny_sdk import tool, rule, agent
+    from nanny_sdk import BudgetExhausted, RuleDenied
+
+Run your agent under ``nanny run agent.py``. All decorators are no-ops when
+``NANNY_BRIDGE_PORT`` is absent — zero friction in direct development.
+"""
+
+from nanny_sdk._decorators import agent, rule, tool
+from nanny_sdk.exceptions import (
+    AgentCompleted,
+    AgentNotFound,
+    BudgetExhausted,
+    MaxStepsReached,
+    NannyStop,
+    RuleDenied,
+    TimeoutExpired,
+    ToolDenied,
+)
+
+__all__ = [
+    # Decorators
+    "tool",
+    "rule",
+    "agent",
+    # Exceptions
+    "NannyStop",
+    "MaxStepsReached",
+    "BudgetExhausted",
+    "TimeoutExpired",
+    "AgentCompleted",
+    "AgentNotFound",
+    "ToolDenied",
+    "RuleDenied",
+]

nanny_sdk-0.1.4/nanny_sdk/_client.py

@@ -0,0 +1,188 @@
+"""Bridge HTTP client.
+
+The bridge uses different transports depending on the OS:
+
+- **Unix (macOS/Linux):** Unix domain socket at ``/tmp/nanny-<token>.sock``.
+  The CLI injects ``NANNY_BRIDGE_SOCKET`` into the child process environment.
+- **Windows:** TCP loopback on a fixed port (47374).
+  The CLI injects ``NANNY_BRIDGE_PORT`` into the child process environment.
+
+``NANNY_SESSION_TOKEN`` is always injected on both platforms.
+
+All environment variables are read at call time (not import time) so tests can
+set them via ``monkeypatch`` without reloading the module.
+
+When neither ``NANNY_BRIDGE_SOCKET`` nor ``NANNY_BRIDGE_PORT`` is set the SDK
+is in passthrough mode — every decorator is a no-op and no network calls are
+made. This is the normal state when running ``python agent.py`` directly
+instead of ``nanny run agent.py``.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+from nanny_sdk.exceptions import (
+    AgentCompleted,
+    AgentNotFound,
+    BudgetExhausted,
+    MaxStepsReached,
+    RuleDenied,
+    TimeoutExpired,
+    ToolDenied,
+)
+
+# ---------------------------------------------------------------------------
+# Environment helpers — evaluated lazily so monkeypatch works in tests
+# ---------------------------------------------------------------------------
+
+
+def _socket_path() -> str | None:
+    """Unix domain socket path set by the CLI on macOS/Linux."""
+    return os.environ.get("NANNY_BRIDGE_SOCKET")
+
+
+def _port() -> str | None:
+    """TCP port set by the CLI on Windows."""
+    return os.environ.get("NANNY_BRIDGE_PORT")
+
+
+def _token() -> str:
+    return os.environ.get("NANNY_SESSION_TOKEN", "")
+
+
+def is_passthrough() -> bool:
+    """True when the SDK is running outside ``nanny run`` (no bridge present).
+
+    Checks ``NANNY_BRIDGE_SOCKET`` first (Unix), then ``NANNY_BRIDGE_PORT``
+    (Windows). Neither set → passthrough.
+    """
+    return _socket_path() is None and _port() is None
+
+
+def _make_client(**kwargs: Any) -> httpx.Client:
+    """Return an ``httpx.Client`` connected to the bridge.
+
+    - Unix socket present → ``HTTPTransport(uds=...)`` with ``base_url=http://localhost``
+    - TCP port present    → plain TCP with ``base_url=http://127.0.0.1:<port>``
+
+    Raises ``RuntimeError`` if called in passthrough mode (should never happen
+    because decorators check ``is_passthrough()`` first).
+    """
+    sock = _socket_path()
+    if sock is not None:
+        transport = httpx.HTTPTransport(uds=sock)
+        return httpx.Client(transport=transport, base_url="http://localhost", **kwargs)
+    port = _port()
+    if port is not None:
+        return httpx.Client(base_url=f"http://127.0.0.1:{port}", **kwargs)
+    raise RuntimeError(  # pragma: no cover
+        "nanny: bridge not available "
+        "(NANNY_BRIDGE_SOCKET and NANNY_BRIDGE_PORT are both unset)"
+    )
+
+
+def _headers() -> dict[str, str]:
+    return {"X-Nanny-Session-Token": _token()}
+
+
+# ---------------------------------------------------------------------------
+# Stop-reason dispatch
+# ---------------------------------------------------------------------------
+
+
+def _raise_for_stop(reason: str, tool_name: str = "", rule_name: str = "") -> None:
+    """Convert a stop-reason string from the bridge into a typed exception.
+
+    ``tool_name`` and ``rule_name`` carry the optional detail fields that the
+    bridge includes in a ``ToolDenied`` or ``RuleDenied`` deny response.
+    """
+    match reason:
+        case "MaxStepsReached":
+            raise MaxStepsReached()
+        case "BudgetExhausted":
+            raise BudgetExhausted()
+        case "TimeoutExpired":
+            raise TimeoutExpired()
+        case "AgentCompleted":
+            raise AgentCompleted()
+        case "AgentNotFound":
+            raise AgentNotFound()
+        case "ToolDenied":
+            raise ToolDenied(tool_name)
+        case "RuleDenied":
+            raise RuleDenied(rule_name)
+        case _:
+            raise RuntimeError(f"nanny: unknown stop reason: {reason!r}")
+
+
+# ---------------------------------------------------------------------------
+# Bridge calls
+# ---------------------------------------------------------------------------
+
+
+def health() -> bool:
+    """Connectivity check — returns True if bridge responds with state running."""
+    with _make_client(timeout=5.0) as c:
+        resp = c.get("/health", headers=_headers())
+    resp.raise_for_status()
+    data: dict[str, str] = resp.json()
+    return data.get("state") == "running"
+
+
+def call_tool(tool_name: str, cost: int, args: dict[str, Any]) -> None:
+    """POST /tool/call — raises a NannyStop subclass if denied, returns None if allowed."""
+    payload = {"tool": tool_name, "cost": cost, "args": args}
+    with _make_client(timeout=10.0) as c:
+        resp = c.post("/tool/call", json=payload, headers=_headers())
+    resp.raise_for_status()
+    data: dict[str, Any] = resp.json()
+    if data.get("status") == "denied":
+        _raise_for_stop(
+            str(data.get("reason", "")),
+            tool_name=str(data.get("tool_name") or ""),
+            rule_name=str(data.get("rule_name") or ""),
+        )
+
+
+def agent_enter(name: str) -> None:
+    """POST /agent/enter — activate a named limit scope.
+
+    The bridge returns 404 when the named scope is not in nanny.toml —
+    raises ``AgentNotFound`` in that case.
+    """
+    with _make_client(timeout=5.0) as c:
+        resp = c.post("/agent/enter", json={"name": name}, headers=_headers())
+    if resp.status_code == 404:
+        raise AgentNotFound()
+    resp.raise_for_status()
+
+
+def agent_exit(name: str) -> None:
+    """POST /agent/exit — deactivate the named limit scope.
+
+    Silently ignored if the bridge closed the connection after a stop event —
+    the bridge already recorded the scope exit when it issued the stop.
+    """
+    try:
+        with _make_client(timeout=5.0) as c:
+            c.post("/agent/exit", json={}, headers=_headers())
+    except Exception:
+        pass
+
+
+def report_stop(reason: str) -> None:
+    """POST /stop — notify the bridge of a stop reason before raising.
+
+    The bridge records this so the NDJSON log shows the real stop reason
+    (e.g. ``RuleDenied``) instead of ``ProcessCrashed`` when the process exits.
+    Silently ignored if the bridge is unreachable — best-effort only.
+    """
+    try:
+        with _make_client(timeout=2.0) as c:
+            c.post("/stop", json={"reason": reason}, headers=_headers())
+    except Exception:
+        pass

nanny_sdk-0.1.4/nanny_sdk/_context.py

@@ -0,0 +1,33 @@
+"""PolicyContext — mirrors the Rust PolicyContext struct field-for-field.
+
+Passed to every ``@rule`` function so it can inspect agent state before
+deciding whether to allow or deny the pending tool call.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PolicyContext:
+    step_count: int = 0
+    elapsed_ms: int = 0
+    requested_tool: str | None = None
+    cost_units_spent: int = 0
+    tool_call_counts: dict[str, int] = field(default_factory=dict)
+    tool_call_history: list[str] = field(default_factory=list)
+    last_tool_args: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> PolicyContext:
+        return cls(
+            step_count=data.get("step_count", 0),
+            elapsed_ms=data.get("elapsed_ms", 0),
+            requested_tool=data.get("requested_tool"),
+            cost_units_spent=data.get("cost_units_spent", 0),
+            tool_call_counts=data.get("tool_call_counts", {}),
+            tool_call_history=data.get("tool_call_history", []),
+            last_tool_args=data.get("last_tool_args", {}),
+        )

nanny_sdk-0.1.4/nanny_sdk/_decorators.py

@@ -0,0 +1,148 @@
+"""``@tool``, ``@rule``, ``@agent`` decorators.
+
+Day 1: skeletons that work in passthrough mode.
+Day 2: ``@tool`` bridge integration.
+Day 3: ``@rule`` client-side rule evaluation.
+Day 4: ``@agent`` scope enter/exit.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from nanny_sdk import _client
+from nanny_sdk._context import PolicyContext
+from nanny_sdk.exceptions import RuleDenied
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+# ---------------------------------------------------------------------------
+# Rule registry — populated at decoration time, evaluated before each tool call
+# ---------------------------------------------------------------------------
+
+# Ordered dict so rules are evaluated in registration order.
+_RULES: dict[str, Callable[[PolicyContext], bool]] = {}
+
+
+def tool(*, cost: int = 0) -> Callable[[F], F]:
+    """Declare a Nanny-governed tool.
+
+    Contacts the bridge before each call to enforce step, budget, timeout,
+    allowlist, and rule limits. Charges ``cost`` units on each allowed call.
+
+    In passthrough mode (no ``NANNY_BRIDGE_PORT``) the decorated function
+    is returned unchanged — zero overhead, zero import errors.
+    """
+
+    def decorator(fn: F) -> F:
+        if _client.is_passthrough():
+            return fn
+
+        tool_name = fn.__name__
+        sig = inspect.signature(fn)
+
+        def _str_args(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, str]:
+            """Bind call-site args to parameter names and stringify the values."""
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            return {k: str(v) for k, v in bound.arguments.items()}
+
+        def _check_rules(str_args: dict[str, str]) -> None:
+            """Evaluate all registered rules in registration order.
+
+            Raises ``RuleDenied`` on the first rule that returns ``False``.
+            The bridge is never contacted if a rule denies.
+            """
+            ctx = PolicyContext(last_tool_args=str_args, requested_tool=tool_name)
+            for rule_name, rule_fn in _RULES.items():
+                if not rule_fn(ctx):
+                    _client.report_stop("RuleDenied")
+                    raise RuleDenied(rule_name)
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                str_args = _str_args(args, kwargs)
+                _check_rules(str_args)
+                _client.call_tool(tool_name, cost, str_args)
+                return await fn(*args, **kwargs)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            str_args = _str_args(args, kwargs)
+            _check_rules(str_args)
+            _client.call_tool(tool_name, cost, str_args)
+            return fn(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+def rule(name: str) -> Callable[[F], F]:
+    """Register a policy rule function.
+
+    The decorated function receives a ``PolicyContext`` and returns ``bool``.
+    ``False`` → ``RuleDenied(name)`` raised at the pending tool call site,
+    before the bridge is ever contacted.
+
+    Rules are evaluated in registration order. The first rule that returns
+    ``False`` stops evaluation — remaining rules are not called.
+
+    ``ctx.last_tool_args`` and ``ctx.requested_tool`` are always populated.
+    ``ctx.step_count``, ``ctx.cost_units_spent``, and ``ctx.tool_call_history``
+    reflect bridge-tracked state and are available via full context in v0.1.5+.
+    """
+
+    def decorator(fn: F) -> F:
+        _RULES[name] = fn
+        return fn
+
+    return decorator
+
+
+def agent(name: str) -> Callable[[F], F]:
+    """Activate a named limit scope for the duration of the decorated function.
+
+    Calls ``/agent/enter`` on entry and ``/agent/exit`` in a ``finally``
+    block so the scope always exits even on exception. Supports both sync
+    and async functions.
+
+    ``/agent/enter`` is called **before** the ``try`` block — if the scope
+    is not found (bridge returns 404), ``AgentNotFound`` propagates immediately
+    and ``/agent/exit`` is never called (the scope was never activated).
+    """
+
+    def decorator(fn: F) -> F:
+        if _client.is_passthrough():
+            return fn
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                _client.agent_enter(name)
+                try:
+                    return await fn(*args, **kwargs)
+                finally:
+                    _client.agent_exit(name)
+
+            return async_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            _client.agent_enter(name)
+            try:
+                return fn(*args, **kwargs)
+            finally:
+                _client.agent_exit(name)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

nanny_sdk-0.1.4/nanny_sdk/exceptions.py

@@ -0,0 +1,47 @@
+"""Nanny stop-reason exceptions.
+
+Each variant of the Rust ``StopReason`` enum maps to a typed Python exception.
+Names match exactly — no prefix, no divergence.
+
+    from nanny_sdk import BudgetExhausted, ToolDenied
+"""
+
+
+class NannyStop(Exception):
+    """Base class for all Nanny stop signals."""
+
+
+class MaxStepsReached(NannyStop):
+    """The step ceiling was reached before the agent completed."""
+
+
+class BudgetExhausted(NannyStop):
+    """The cost budget was exhausted before the agent completed."""
+
+
+class TimeoutExpired(NannyStop):
+    """The wall-clock timeout elapsed before the agent completed."""
+
+
+class AgentCompleted(NannyStop):
+    """The agent finished normally (used as a signal, not an error)."""
+
+
+class AgentNotFound(NannyStop):
+    """The named agent scope is not defined in nanny.toml."""
+
+
+class ToolDenied(NannyStop):
+    """A tool call was denied by the allowlist or a rule."""
+
+    def __init__(self, tool_name: str) -> None:
+        self.tool_name = tool_name
+        super().__init__(f"tool denied: {tool_name!r}")
+
+
+class RuleDenied(NannyStop):
+    """A policy rule returned False and blocked the tool call."""
+
+    def __init__(self, rule_name: str) -> None:
+        self.rule_name = rule_name
+        super().__init__(f"rule denied: {rule_name!r}")

nanny_sdk-0.1.4/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "nanny-sdk"
+version = "0.1.4"
+description = "Python SDK for the Nanny execution boundary — @tool, @rule, @agent decorators"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.9",
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpserver>=1.0",
+    "ruff>=0.4",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["nanny_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

nanny_sdk-0.1.4/tests/conftest.py

@@ -0,0 +1,46 @@
+"""Shared pytest fixtures.
+
+``mock_bridge`` — spins up a fake Nanny bridge via pytest-httpserver and
+sets ``NANNY_BRIDGE_PORT`` so _client routes to it. Because _client reads
+env vars lazily (at call time), monkeypatch works without reloading modules.
+
+``_reset_rules`` — clears the global rule registry before and after every
+test so rules registered in one test don't bleed into the next.
+"""
+
+from collections.abc import Generator
+
+import pytest
+from pytest_httpserver import HTTPServer
+
+
+@pytest.fixture(autouse=True)
+def _reset_rules() -> Generator[None, None, None]:
+    """Clear _RULES before and after every test."""
+    from nanny_sdk._decorators import _RULES
+
+    _RULES.clear()
+    yield
+    _RULES.clear()
+
+
+@pytest.fixture()
+def mock_bridge(httpserver: HTTPServer, monkeypatch: pytest.MonkeyPatch) -> HTTPServer:
+    """Fake Nanny bridge for unit tests.
+
+    Sets ``NANNY_BRIDGE_PORT`` and ``NANNY_SESSION_TOKEN`` for the duration
+    of the test, then restores the original environment on teardown.
+
+    Returns the ``HTTPServer`` so tests can register expected requests::
+
+        def test_something(mock_bridge):
+            mock_bridge.expect_request("/health").respond_with_json({"status": "ok"})
+            assert client.health() is True
+    """
+    monkeypatch.setenv("NANNY_BRIDGE_PORT", str(httpserver.port))
+    monkeypatch.setenv("NANNY_SESSION_TOKEN", "test-token")
+    # Permanent catch-all for POST /stop — report_stop() calls this on every denial.
+    # Using expect_request (not expect_oneshot_request) so it handles any number of calls
+    # and is NOT checked by check_assertions(), avoiding noise in allow-path tests.
+    httpserver.expect_request("/stop", method="POST").respond_with_json({"status": "ok"})
+    return httpserver