amanai 0.1.0__tar.gz

amanai-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+*.sqlite3
+*.db
+node_modules/
+dist/
+.DS_Store
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.fida
+release.sh
+uv.lock

amanai-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: amanai
+Version: 0.1.0
+Summary: Action Policy Engine for AI agents: policy-as-code for tool-calls — evaluate, enforce (block/warn/approve), and trace agent actions, with the same policy asserted in CI. Plus local guardrails and an offline judge. Pure-Python, zero dependencies.
+Author-email: Aji Purnomo <hi@aji.is-a.dev>
+Keywords: agent,ai,guardrails,llm,owasp,pii,policy-as-code,prompt-injection,security,tool-call
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# amanai
+
+**Action Policy Engine for AI agents — policy-as-code for tool-calls. Pure-Python, zero dependencies.**
+
+Write **one policy** for risky agent actions. Amanai evaluates every tool-call
+against it before the tool runs, enforces the decision, and records a structured
+trace as evidence. The same policy file asserts in CI — what you test is what you
+enforce. Decisions are deterministic: no LLM decides whether a high-risk tool runs.
+
+```bash
+pip install amanai
+```
+
+## Action Policy Engine
+
+Five verbs: **load** a policy, **evaluate** an action, **protect** a tool,
+**collect** a trace, **assert** it in tests.
+
+```python
+from amanai import set_policy, tool, ToolBlocked, ApprovalRequired, collect_trace
+
+set_policy("amanai.policy.json")          # load + validate (raises PolicyError if bad)
+
+@tool(name="billing.refund", capability="money_movement", risk="high")
+def refund_payment(amount): ...
+
+refund_payment(amount=500)                # ToolBlocked / ApprovalRequired per policy
+trace = collect_trace()                   # canonical evidence: action + decision + status
+```
+
+A **policy** is a list of rules. A rule matches on `tool` and/or `capability`,
+with optional `args` and `context` predicates, and carries an `action`:
+
+```json
+[
+  { "id": "discount-cap", "tool": "apply_discount",
+    "args": [{ "arg": "pct", "op": ">=", "value": 50 }],
+    "action": "block", "reason": "discount of 50% or more is never allowed" },
+
+  { "id": "refund-approval", "tool": "refund_payment",
+    "args": [{ "arg": "amount", "op": ">", "value": 100 }],
+    "action": "require_approval" },
+
+  { "id": "external-email", "capability": "external_comms",
+    "args": [{ "arg": "to", "op": "email_external", "value": ["acme.com"] }],
+    "action": "block" }
+]
+```
+
+- **Outcomes:** `allow` · `block` · `warn` · `require_approval`.
+- **Operators:** `>= > <= < == !=` · `contains` · `regex` · `in` / `not_in` ·
+  `email_external` · `domain_in` / `domain_not_in`.
+- **Modes** (per request, never global): `enforce` blocks before execution ·
+  `shadow` records what it *would* block but lets the call run · `test`
+  evaluates with no side effects.
+- The legacy flat rule `{tool, arg, op, value}` still loads (it defaults to
+  `block`). Rules without an `id` get a deterministic generated one.
+
+```python
+from amanai import set_mode, set_context, evaluate, ActionRequest
+
+set_mode("shadow")                                   # observe before enforcing
+set_context(role="support", tenant="t1", environment="prod")  # authz context for rules
+evaluate(ActionRequest("apply_discount", {"pct": 90}))        # -> PolicyDecision(outcome="block", ...)
+```
+
+## Assert the same policy in CI
+
+```python
+from amanai.testing import assert_blocked, assert_no_violations
+
+def test_excessive_discount_is_blocked():
+    set_policy("amanai.policy.json")
+    assert_blocked(apply_discount, pct=90)
+
+def test_attack_trace_is_clean():
+    run_agent(attack_prompt)             # produces a trace
+    assert_no_violations(collect_trace())  # replays actions against the active policy
+```
+
+`amanai.testing` also ships `assert_requires_approval`,
+`using_mode`, and `replay` (re-evaluate a recorded trace against a policy).
+
+## Runtime guardrails (input / output, supporting)
+
+```python
+from amanai import guard_input, guard_output, GuardrailBlocked
+
+try:
+    msg = guard_input(user_msg)          # raises GuardrailBlocked on injection
+except GuardrailBlocked:
+    reply = "I can't help with that."
+else:
+    reply = guard_output(run_agent(msg)) # redacts emails, cards, secrets
+```
+
+## Offline judge & MCP checks (supporting)
+
+Score an agent's input / response / tool-calls against detectors (string match,
+tool assertions, MCP checks; LLM-as-judge when you pass a gateway). The
+`tool_assertion` detector reuses the engine's operators, so the test side can't
+drift from runtime — a contract test guarantees it.
+
+## Monitoring (optional — needs an Amanai server)
+
+```python
+from amanai import Monitor, collect_trace
+
+mon = Monitor("http://localhost:8000", PUBLIC_KEY, SECRET_KEY)
+mon.log_trace(collect_trace(), user_id="u123")   # canonical events, PII redacted
+```
+
+## API
+
+- **Engine:** `load_policy` `set_policy` `get_policy` `evaluate` `Policy` `Rule`
+  `ActionRequest` `PolicyDecision` `TraceEvent` `PendingAction` `PolicyError`
+- **Modes / context:** `set_mode` `get_mode` `set_context` `get_context` `clear_context`
+- **Protect / collect:** `tool` `collect_trace` `collect_tool_calls` `record_tool_call`
+  `reset` `registered_tools` `uncovered_tools` `ToolBlocked` `ApprovalRequired`
+- **Test:** `amanai.testing` — `assert_blocked`
+  `assert_requires_approval` `assert_no_violations` `using_mode` `replay`
+- **Policy lifecycle:** `clear_tool_policy` (deactivate the active policy)
+- **Guardrails:** `guard_input` `guard_output` `redact_pii` `detect_injection` `detect_pii` `GuardResult` `GuardrailBlocked`
+- **Judge / monitor:** `judge` `Monitor`
+
+Apache-2.0. Zero runtime dependencies.

amanai-0.1.0/README.md

@@ -0,0 +1,126 @@
+# amanai
+
+**Action Policy Engine for AI agents — policy-as-code for tool-calls. Pure-Python, zero dependencies.**
+
+Write **one policy** for risky agent actions. Amanai evaluates every tool-call
+against it before the tool runs, enforces the decision, and records a structured
+trace as evidence. The same policy file asserts in CI — what you test is what you
+enforce. Decisions are deterministic: no LLM decides whether a high-risk tool runs.
+
+```bash
+pip install amanai
+```
+
+## Action Policy Engine
+
+Five verbs: **load** a policy, **evaluate** an action, **protect** a tool,
+**collect** a trace, **assert** it in tests.
+
+```python
+from amanai import set_policy, tool, ToolBlocked, ApprovalRequired, collect_trace
+
+set_policy("amanai.policy.json")          # load + validate (raises PolicyError if bad)
+
+@tool(name="billing.refund", capability="money_movement", risk="high")
+def refund_payment(amount): ...
+
+refund_payment(amount=500)                # ToolBlocked / ApprovalRequired per policy
+trace = collect_trace()                   # canonical evidence: action + decision + status
+```
+
+A **policy** is a list of rules. A rule matches on `tool` and/or `capability`,
+with optional `args` and `context` predicates, and carries an `action`:
+
+```json
+[
+  { "id": "discount-cap", "tool": "apply_discount",
+    "args": [{ "arg": "pct", "op": ">=", "value": 50 }],
+    "action": "block", "reason": "discount of 50% or more is never allowed" },
+
+  { "id": "refund-approval", "tool": "refund_payment",
+    "args": [{ "arg": "amount", "op": ">", "value": 100 }],
+    "action": "require_approval" },
+
+  { "id": "external-email", "capability": "external_comms",
+    "args": [{ "arg": "to", "op": "email_external", "value": ["acme.com"] }],
+    "action": "block" }
+]
+```
+
+- **Outcomes:** `allow` · `block` · `warn` · `require_approval`.
+- **Operators:** `>= > <= < == !=` · `contains` · `regex` · `in` / `not_in` ·
+  `email_external` · `domain_in` / `domain_not_in`.
+- **Modes** (per request, never global): `enforce` blocks before execution ·
+  `shadow` records what it *would* block but lets the call run · `test`
+  evaluates with no side effects.
+- The legacy flat rule `{tool, arg, op, value}` still loads (it defaults to
+  `block`). Rules without an `id` get a deterministic generated one.
+
+```python
+from amanai import set_mode, set_context, evaluate, ActionRequest
+
+set_mode("shadow")                                   # observe before enforcing
+set_context(role="support", tenant="t1", environment="prod")  # authz context for rules
+evaluate(ActionRequest("apply_discount", {"pct": 90}))        # -> PolicyDecision(outcome="block", ...)
+```
+
+## Assert the same policy in CI
+
+```python
+from amanai.testing import assert_blocked, assert_no_violations
+
+def test_excessive_discount_is_blocked():
+    set_policy("amanai.policy.json")
+    assert_blocked(apply_discount, pct=90)
+
+def test_attack_trace_is_clean():
+    run_agent(attack_prompt)             # produces a trace
+    assert_no_violations(collect_trace())  # replays actions against the active policy
+```
+
+`amanai.testing` also ships `assert_requires_approval`,
+`using_mode`, and `replay` (re-evaluate a recorded trace against a policy).
+
+## Runtime guardrails (input / output, supporting)
+
+```python
+from amanai import guard_input, guard_output, GuardrailBlocked
+
+try:
+    msg = guard_input(user_msg)          # raises GuardrailBlocked on injection
+except GuardrailBlocked:
+    reply = "I can't help with that."
+else:
+    reply = guard_output(run_agent(msg)) # redacts emails, cards, secrets
+```
+
+## Offline judge & MCP checks (supporting)
+
+Score an agent's input / response / tool-calls against detectors (string match,
+tool assertions, MCP checks; LLM-as-judge when you pass a gateway). The
+`tool_assertion` detector reuses the engine's operators, so the test side can't
+drift from runtime — a contract test guarantees it.
+
+## Monitoring (optional — needs an Amanai server)
+
+```python
+from amanai import Monitor, collect_trace
+
+mon = Monitor("http://localhost:8000", PUBLIC_KEY, SECRET_KEY)
+mon.log_trace(collect_trace(), user_id="u123")   # canonical events, PII redacted
+```
+
+## API
+
+- **Engine:** `load_policy` `set_policy` `get_policy` `evaluate` `Policy` `Rule`
+  `ActionRequest` `PolicyDecision` `TraceEvent` `PendingAction` `PolicyError`
+- **Modes / context:** `set_mode` `get_mode` `set_context` `get_context` `clear_context`
+- **Protect / collect:** `tool` `collect_trace` `collect_tool_calls` `record_tool_call`
+  `reset` `registered_tools` `uncovered_tools` `ToolBlocked` `ApprovalRequired`
+- **Test:** `amanai.testing` — `assert_blocked`
+  `assert_requires_approval` `assert_no_violations` `using_mode` `replay`
+- **Policy lifecycle:** `clear_tool_policy` (deactivate the active policy)
+- **Guardrails:** `guard_input` `guard_output` `redact_pii` `detect_injection` `detect_pii` `GuardResult` `GuardrailBlocked`
+- **Judge / monitor:** `judge` `Monitor`
+
+Apache-2.0. Zero runtime dependencies.

amanai-0.1.0/amanai/__init__.py

@@ -0,0 +1,121 @@
+"""Amanai SDK — policy-as-code for AI agent actions.
+
+Test the policy in CI. Enforce the same policy at runtime. Keep evidence for audit.
+
+The Action Policy Engine is the product center. Five verbs:
+
+    from amanai import load_policy, set_policy, evaluate, tool, collect_trace
+
+    set_policy(load_policy("amanai.policy.json"))   # 1. load policy
+
+    @tool(capability="money_movement", risk="high")  # 3. protect tool
+    def refund_payment(amount): ...
+
+    evaluate(ActionRequest("refund_payment", {"amount": 500}))  # 2. evaluate action
+    trace = collect_trace()                          # 4. collect trace
+    # 5. assert in tests → amanai.testing
+
+Decisions are deterministic — no LLM decides whether a high-risk tool runs.
+Prompt-injection and PII guardrails remain supporting modules, not the center.
+"""
+
+from amanai.client import (
+    collect_tool_calls,
+    collect_trace,
+    record_tool_call,
+    registered_tools,
+    reset,
+    tool,
+    uncovered_tools,
+)
+from amanai.coverage import COVERAGE, coverage_for
+from amanai.guardrails import (
+    GuardrailBlocked,
+    GuardResult,
+    detect_injection,
+    detect_pii,
+    guard_input,
+    guard_output,
+    redact_pii,
+    scan,
+)
+from amanai.judge import run_detector, run_mcp_check
+from amanai.mcp_adapter import guard_mcp_call
+from amanai.monitor import Monitor
+from amanai.policy import (
+    MODES,
+    OUTCOMES,
+    ActionRequest,
+    ApprovalRequired,
+    PendingAction,
+    Policy,
+    PolicyDecision,
+    PolicyError,
+    Rule,
+    ToolBlocked,
+    TraceEvent,
+    clear_context,
+    clear_tool_policy,
+    evaluate,
+    get_context,
+    get_mode,
+    get_policy,
+    load_policy,
+    set_context,
+    set_mode,
+    set_policy,
+)
+
+__all__ = [
+    # --- Action Policy Engine ---
+    "load_policy",
+    "set_policy",
+    "get_policy",
+    "evaluate",
+    "Policy",
+    "Rule",
+    "ActionRequest",
+    "PolicyDecision",
+    "TraceEvent",
+    "PendingAction",
+    "ToolBlocked",
+    "ApprovalRequired",
+    "PolicyError",
+    "OUTCOMES",
+    "MODES",
+    # modes & context
+    "set_mode",
+    "get_mode",
+    "set_context",
+    "get_context",
+    "clear_context",
+    # protect & collect
+    "tool",
+    "record_tool_call",
+    "collect_tool_calls",
+    "collect_trace",
+    "reset",
+    "registered_tools",
+    "uncovered_tools",
+    # MCP adapter
+    "guard_mcp_call",
+    # --- supporting: offline judge & MCP static checks ---
+    "run_detector",
+    "run_mcp_check",
+    # clear active policy
+    "clear_tool_policy",
+    # --- supporting: guardrails ---
+    "scan",
+    "guard_input",
+    "guard_output",
+    "redact_pii",
+    "detect_injection",
+    "detect_pii",
+    "GuardResult",
+    "GuardrailBlocked",
+    # --- supporting: monitoring & coverage ---
+    "Monitor",
+    "COVERAGE",
+    "coverage_for",
+]
+__version__ = "0.1.0"

amanai-0.1.0/amanai/client.py

@@ -0,0 +1,229 @@
+"""Protect tools and collect traces — the runtime entry point into the engine.
+
+`@tool` is a thin adapter: it normalizes the call into an `ActionRequest`, asks
+the Action Policy Engine for a decision, enforces it according to the current
+mode, and records a `TraceEvent` as evidence. The policy logic lives in
+`policy.py`; this module only wires real Python calls into it.
+
+    from amanai import tool, set_policy, collect_trace
+
+    @tool(capability="money_movement", risk="high")
+    def refund_payment(amount): ...
+
+    set_policy("amanai.policy.json")
+    refund_payment(amount=500)          # ToolBlocked / ApprovalRequired per policy
+    trace = collect_trace()             # canonical evidence for CI / monitoring
+"""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+from typing import Any, Callable
+
+from amanai.policy import (
+    ActionRequest,
+    ApprovalRequired,
+    PendingAction,
+    Policy,
+    ToolBlocked,
+    TraceEvent,
+    evaluate,
+    get_context,
+    get_mode,
+    get_policy,
+)
+
+# Context-local trace buffer — concurrent requests never see each other's calls.
+_trace: contextvars.ContextVar[list | None] = contextvars.ContextVar("amanai_trace", default=None)
+
+# Static, declaration-time inventory of every protected tool (for security review).
+_REGISTRY: dict[str, dict] = {}
+
+
+def _buffer() -> list:
+    buf = _trace.get()
+    if buf is None:
+        buf = []
+        _trace.set(buf)
+    return buf
+
+
+def record_event(event: TraceEvent) -> None:
+    _buffer().append(event)
+
+
+def _normalize_args(fn: Callable, args: tuple, kwargs: dict) -> dict:
+    """Map a call to {param_name: value} so policies match regardless of whether
+    the tool was called positionally or by keyword (`apply_discount(50)` ==
+    `apply_discount(pct=50)`)."""
+    try:
+        sig = inspect.signature(fn)
+        bound = sig.bind_partial(*args, **kwargs)
+        out: dict[str, Any] = {}
+        for name, param in sig.parameters.items():
+            if name not in bound.arguments:
+                continue
+            val = bound.arguments[name]
+            if param.kind is inspect.Parameter.VAR_KEYWORD:
+                out.update(val)  # **kwargs → flatten to top level
+            elif param.kind is inspect.Parameter.VAR_POSITIONAL:
+                out[name] = list(val)  # *args → keep as a list
+            else:
+                out[name] = val
+        return out
+    except (TypeError, ValueError):
+        # Builtins / C-functions without an introspectable signature.
+        out = dict(kwargs)
+        if args:
+            out["_args"] = list(args)
+        return out
+
+
+def record_tool_call(
+    tool_name: str,
+    tool_input: dict,
+    tool_output: Any,
+    *,
+    capability: str | None = None,
+    context: dict | None = None,
+    metadata: dict | None = None,
+) -> None:
+    """Manually record an executed tool-call.
+
+    Use this when you can't decorate the function. Because the tool has already
+    run, Amanai cannot prevent it here; it still evaluates the active policy and
+    marks policy violations as `shadowed` so CI/monitoring can catch bypasses.
+    """
+    action = ActionRequest(
+        tool_name,
+        dict(tool_input),
+        capability=capability,
+        context=context if context is not None else get_context(),
+        metadata=metadata or {},
+    )
+    decision = evaluate(action)
+    status = "shadowed" if decision.outcome in ("block", "require_approval") else "executed"
+    record_event(TraceEvent(action, decision, status=status, output=tool_output))
+
+
+def tool(
+    fn: Callable | None = None,
+    *,
+    name: str | None = None,
+    capability: str | None = None,
+    risk: str | None = None,
+    input_schema: dict | None = None,
+):
+    """Protect a function with the Action Policy Engine.
+
+    Usage: `@tool` or `@tool(name="billing.refund", capability="money_movement")`.
+
+    Behavior depends on the current mode (`enforce` by default):
+      * enforce — `block` raises `ToolBlocked`, `require_approval` raises
+        `ApprovalRequired`; neither runs the function.
+      * shadow  — violations execute anyway but are recorded as evidence.
+      * test    — nothing executes (no side effects); the decision is recorded.
+    """
+
+    def decorate(fn: Callable) -> Callable:
+        tool_name = name or fn.__name__
+        meta = {
+            "capability": capability,
+            "risk": risk,
+            "input_schema": input_schema,
+            "python_name": fn.__name__,
+        }
+        _REGISTRY[tool_name] = meta
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            inp = _normalize_args(fn, args, kwargs)
+            action = ActionRequest(
+                tool_name, inp, capability=capability, context=get_context(), metadata=meta
+            )
+            decision = evaluate(action)
+            mode = get_mode()
+
+            if mode == "test":
+                record_event(TraceEvent(action, decision, status="evaluated"))
+                return None
+
+            if decision.outcome == "block" and mode == "enforce":
+                record_event(TraceEvent(action, decision, status="blocked"))
+                raise ToolBlocked(decision.reason or f"{tool_name} blocked by policy")
+            if decision.outcome == "require_approval" and mode == "enforce":
+                pending = PendingAction(action, decision)
+                record_event(TraceEvent(action, decision, status="pending"))
+                raise ApprovalRequired(pending)
+
+            try:
+                result = fn(*args, **kwargs)
+            except Exception as e:
+                record_event(TraceEvent(action, decision, status="error", error=str(e)))
+                raise
+
+            # In shadow mode a would-be-blocked call still ran — mark it.
+            shadowed = decision.outcome in ("block", "require_approval")
+            record_event(
+                TraceEvent(
+                    action, decision, status="shadowed" if shadowed else "executed", output=result
+                )
+            )
+            return result
+
+        return wrapper
+
+    return decorate(fn) if callable(fn) else decorate
+
+
+def collect_trace() -> list[TraceEvent]:
+    """Return the canonical trace events recorded so far and clear the buffer."""
+    buf = _trace.get() or []
+    _trace.set([])
+    return list(buf)
+
+
+def collect_tool_calls() -> list:
+    """Legacy view: the executed tool-calls as `{tool, input, output}` dicts.
+
+    Derived from the trace — blocked/pending/evaluated actions are omitted, so a
+    test can prove a dangerous function did not run. Drains the buffer (use
+    `collect_trace` if you want the full evidence instead)."""
+    out = []
+    for e in collect_trace():
+        if e.status in ("executed", "shadowed"):
+            rec = {"tool": e.action.tool, "input": dict(e.action.input), "output": e.output}
+            if e.decision.outcome == "warn":
+                rec["policy_warning"] = True
+            out.append(rec)
+    return out
+
+
+def reset() -> None:
+    _trace.set([])
+
+
+def registered_tools() -> dict[str, dict]:
+    """Every `@tool`-protected function and its declared capability/risk/schema —
+    the inventory a security engineer reviews for high-risk actions."""
+    return dict(_REGISTRY)
+
+
+def uncovered_tools(policy: Policy | None = None) -> list[str]:
+    """Names of registered tools that no rule covers (by tool name or capability)
+    in the given (or active) policy — risky actions left silently unprotected."""
+    pol = policy if policy is not None else get_policy()
+    names, caps = set(), set()
+    if pol is not None:
+        for r in pol.rules:
+            if r.tool:
+                names.add(r.tool)
+            if r.capability:
+                caps.add(r.capability)
+    return [
+        name
+        for name, meta in _REGISTRY.items()
+        if name not in names and meta.get("capability") not in caps
+    ]