mnki 0.1.0__tar.gz

mnki-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: mnki
+Version: 0.1.0
+Summary: mnki — the Agent Trust SDK for Python: give an AI agent an identity, verify its authority with evidence, delegate, attest, sign requests (Agent-Proof).
+License: Apache-2.0
+Project-URL: Homepage, https://mnki.com
+Project-URL: Repository, https://github.com/MNKIAgentOS/agent-trust
+Keywords: ai-agents,agent-security,authorization,delegation,mcp,a2a,authzen,spiffe
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: signing
+Requires-Dist: cryptography>=42; extra == "signing"
+Provides-Extra: httpx
+Requires-Dist: httpx>=0.27; extra == "httpx"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == "openai-agents"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.80; extra == "crewai"
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=0.1; extra == "pydantic-ai"
+
+# mnki (Python)
+
+```bash
+pip install mnki            # verify, delegate, attest — no dependencies
+pip install "mnki[signing]" # Agent-Proof signing with a local key
+```
+
+```python
+from mnki import AgentTrustClient, AgentIdentity
+
+c = AgentTrustClient("https://mnki.com", api_key="at_verify_…")
+d = c.verify({"agent": "invoice-agent", "action": "refund.create", "amount": 420, "currency": "EUR"})
+print(d["decision"], [e["title"] for e in d["evidence"]])
+```
+
+Local mode (no account) runs the same pipeline as the control plane, in-process, validated against the conformance vectors:
+
+```python
+from mnki import Guard, Denied, demo_world
+g = Guard(world=demo_world(), agent="invoice-agent", action_prefix="", mode="observe")   # observe → warn → require_approval → enforce
+
+@g.wrap("refund.create")
+def refund(customer_id: str, amount: float, currency: str = "EUR"): ...
+```
+
+Framework adapters (the framework is imported lazily, never required): `mnki.adapters.openai_agents`, `.langchain`,
+`.crewai`, `.pydantic_ai` — each exposes `guard_tools(guard, tools)`; refusals come back to the model as
+`{"error": "denied", "reasons": [...], "evidence": [...]}` or raise with `on_refused="throw"`. Extras:
+`pip install "mnki[openai-agents]"`, `[langchain]`, `[crewai]`, `[pydantic-ai]`, `[httpx]`.
+
+`agent_trust` remains importable as a deprecated alias for one minor version. Apache-2.0.

mnki-0.1.0/README.md

@@ -0,0 +1,31 @@
+# mnki (Python)
+
+```bash
+pip install mnki            # verify, delegate, attest — no dependencies
+pip install "mnki[signing]" # Agent-Proof signing with a local key
+```
+
+```python
+from mnki import AgentTrustClient, AgentIdentity
+
+c = AgentTrustClient("https://mnki.com", api_key="at_verify_…")
+d = c.verify({"agent": "invoice-agent", "action": "refund.create", "amount": 420, "currency": "EUR"})
+print(d["decision"], [e["title"] for e in d["evidence"]])
+```
+
+Local mode (no account) runs the same pipeline as the control plane, in-process, validated against the conformance vectors:
+
+```python
+from mnki import Guard, Denied, demo_world
+g = Guard(world=demo_world(), agent="invoice-agent", action_prefix="", mode="observe")   # observe → warn → require_approval → enforce
+
+@g.wrap("refund.create")
+def refund(customer_id: str, amount: float, currency: str = "EUR"): ...
+```
+
+Framework adapters (the framework is imported lazily, never required): `mnki.adapters.openai_agents`, `.langchain`,
+`.crewai`, `.pydantic_ai` — each exposes `guard_tools(guard, tools)`; refusals come back to the model as
+`{"error": "denied", "reasons": [...], "evidence": [...]}` or raise with `on_refused="throw"`. Extras:
+`pip install "mnki[openai-agents]"`, `[langchain]`, `[crewai]`, `[pydantic-ai]`, `[httpx]`.
+
+`agent_trust` remains importable as a deprecated alias for one minor version. Apache-2.0.

mnki-0.1.0/agent_trust/__init__.py

@@ -0,0 +1,6 @@
+"""Deprecated import path. `agent_trust` is now `mnki` (pip install mnki); this shim will be removed in 0.2."""
+import warnings as _w
+_w.warn("`agent_trust` has been renamed to `mnki` — `from mnki import AgentTrustClient`", DeprecationWarning, stacklevel=2)
+from mnki import AgentTrustClient, AgentTrustError, AgentIdentity, b64url, body_hash  # noqa: E402,F401
+
+__all__ = ["AgentTrustClient", "AgentTrustError", "AgentIdentity", "b64url", "body_hash"]

mnki-0.1.0/mnki/__init__.py

@@ -0,0 +1,22 @@
+"""
+mnki — give every AI agent an identity, authority and proof of action.
+
+    from mnki import AgentTrustClient, AgentIdentity
+    c = AgentTrustClient("https://mnki.com", api_key="at_verify_…")
+    d = c.verify({"agent": "invoice-agent", "action": "refund.create", "amount": 420, "currency": "EUR"})
+    d["decision"]      # "ALLOW" | "DENY" | "REQUIRE_APPROVAL"; d["evidence"] is the ✓/⚠/✕ list
+
+Local mode (no account): `Guard(world=demo_world(), agent="invoice-agent", action_prefix="")` — the same pipeline as the
+control plane, in-process. Framework adapters: `mnki.adapters.openai_agents`, `.langchain`, `.crewai`, `.pydantic_ai`.
+Zero dependencies for verify / attest / delegate; `pip install mnki[signing]` for Agent-Proof signing.
+"""
+from .client import AgentTrustClient, Client
+from .errors import AgentTrustError, MnkiError
+from .identity import AgentIdentity, b64url, b64url_decode, body_hash
+from . import offline
+from .guard import Guard, Denied, ApprovalRequired, wrap
+from .local import demo_world, local_verify, load_world
+from . import pipeline, policy, adapters
+
+__version__ = "0.1.0"
+__all__ = ["AgentTrustClient", "Client", "AgentTrustError", "MnkiError", "AgentIdentity", "b64url", "b64url_decode", "body_hash", "offline", "Guard", "Denied", "ApprovalRequired", "wrap", "demo_world", "local_verify", "load_world", "pipeline", "policy", "adapters"]

mnki-0.1.0/mnki/adapters/__init__.py

@@ -0,0 +1,16 @@
+"""
+Framework adapters — thin, framework-free wrappers over `Guard.check`. Each module imports its framework lazily
+(only when a real framework object is handed in), so `mnki` stays dependency-free.
+
+    from mnki.adapters.openai_agents import guard_tools     # openai-agents  (FunctionTool.on_invoke_tool)
+    from mnki.adapters.langchain import guard_tools         # langchain-core BaseTool (invoke / ainvoke)
+    from mnki.adapters.crewai import guard_tools            # crewai BaseTool (_run)
+    from mnki.adapters.pydantic_ai import guard_tool        # pydantic-ai tool functions (decorator)
+
+Refusals are returned to the model as a JSON result by default (`on_refused="result"`), or raised
+(`on_refused="throw"`).
+"""
+from . import shared
+from .shared import refusal, refusal_json, wanted
+
+__all__ = ["shared", "refusal", "refusal_json", "wanted"]

mnki-0.1.0/mnki/adapters/crewai.py

@@ -0,0 +1,59 @@
+"""
+CrewAI — `crewai.tools.BaseTool`. Real tools become a `GuardedTool` subclass whose `_run` verifies before
+delegating; other objects with `run`/`_run` get a duck-typed proxy. No framework import unless a real tool is given.
+
+    from mnki.adapters.crewai import guard_tools
+    Agent(role="Refunds", tools=guard_tools(guard, [refund_tool]))
+"""
+from __future__ import annotations
+import json
+from typing import Any, Optional
+
+from .shared import check_or_refuse, wanted
+
+
+def _base_tool():
+    try:
+        from crewai.tools import BaseTool  # type: ignore
+        return BaseTool
+    except ImportError: return None
+
+
+def _guarded_class(BaseTool: Any) -> Any:
+    class GuardedTool(BaseTool):  # type: ignore[misc,valid-type]
+        inner: Any = None
+        guard: Any = None
+        verified_name: str = ""
+        on_refused: str = "result"
+
+        def _run(self, *a: Any, **kw: Any) -> Any:
+            r = check_or_refuse(self.guard, self.verified_name, kw or ({"input": a[0]} if len(a) == 1 else {"args": list(a)}), self.on_refused)
+            if r is not None: return json.dumps(r)
+            return self.inner._run(*a, **kw)
+
+    GuardedTool.__name__ = "GuardedTool"
+    return GuardedTool
+
+
+class _Proxy:
+    def __init__(self, guard: Any, inner: Any, verified: str, on_refused: str): self._g, self._i, self._n, self._o = guard, inner, verified, on_refused
+    def __getattr__(self, k: str) -> Any: return getattr(self._i, k)
+    def _run(self, *a: Any, **kw: Any) -> Any:
+        r = check_or_refuse(self._g, self._n, kw or ({"input": a[0]} if len(a) == 1 else {"args": list(a)}), self._o); return json.dumps(r) if r is not None else self._i._run(*a, **kw)
+    def run(self, *a: Any, **kw: Any) -> Any:
+        r = check_or_refuse(self._g, self._n, kw or ({"input": a[0]} if len(a) == 1 else {"args": list(a)}), self._o); return json.dumps(r) if r is not None else self._i.run(*a, **kw)
+
+
+def guard_tool(guard: Any, tool: Any, on_refused: str = "result", only: Optional[list] = None, skip: Optional[list] = None, tool_name=None) -> Any:
+    name = getattr(tool, "name", None) or getattr(tool, "__name__", "tool")
+    if not wanted(name, only, skip): return tool
+    verified = tool_name(name) if tool_name else name
+    BaseTool = _base_tool()
+    if BaseTool is not None and isinstance(tool, BaseTool):
+        fields = {"name": tool.name, "description": tool.description, "inner": tool, "guard": guard, "verified_name": verified, "on_refused": on_refused}
+        if getattr(tool, "args_schema", None) is not None: fields["args_schema"] = tool.args_schema
+        return _guarded_class(BaseTool)(**fields)
+    return _Proxy(guard, tool, verified, on_refused)
+
+
+def guard_tools(guard: Any, tools: list, **kw: Any) -> list: return [guard_tool(guard, t, **kw) for t in tools]

mnki-0.1.0/mnki/adapters/langchain.py

@@ -0,0 +1,74 @@
+"""
+LangChain / LangGraph (Python) — `langchain-core` tools. Real `BaseTool` instances become a `GuardedTool`
+subclass (so `ToolNode`, `bind_tools` and isinstance checks keep working) that verifies in `_run`/`_arun` before
+delegating to the original. Anything else with `invoke`/`run` gets a duck-typed proxy — no framework import.
+
+    from mnki.adapters.langchain import guard_tools
+    graph = create_react_agent(model, guard_tools(guard, [refund, lookup]))
+"""
+from __future__ import annotations
+import json
+from typing import Any, Optional
+
+from .shared import check_or_refuse, wanted
+
+
+def _base_tool():
+    try:
+        from langchain_core.tools import BaseTool  # type: ignore
+        return BaseTool
+    except ImportError: return None
+
+
+def _guarded_class(BaseTool: Any) -> Any:
+    class GuardedTool(BaseTool):  # type: ignore[misc,valid-type]
+        inner: Any = None
+        guard: Any = None
+        verified_name: str = ""
+        on_refused: str = "result"
+
+        # LangChain passes `config` / `run_manager` when the signature declares them; the tool arguments are the rest.
+        def _run(self, *a: Any, config: Any = None, run_manager: Any = None, **kw: Any) -> Any:
+            args = kw or ({"input": a[0]} if len(a) == 1 else {"args": list(a)})
+            r = check_or_refuse(self.guard, self.verified_name, args, self.on_refused)
+            if r is not None: return json.dumps(r)
+            return self.inner.invoke(args if kw else (a[0] if len(a) == 1 else list(a)), config)
+
+        async def _arun(self, *a: Any, config: Any = None, run_manager: Any = None, **kw: Any) -> Any:
+            args = kw or ({"input": a[0]} if len(a) == 1 else {"args": list(a)})
+            r = check_or_refuse(self.guard, self.verified_name, args, self.on_refused)
+            if r is not None: return json.dumps(r)
+            return await self.inner.ainvoke(args if kw else (a[0] if len(a) == 1 else list(a)), config)
+
+    GuardedTool.__name__ = "GuardedTool"
+    return GuardedTool
+
+
+class _Proxy:
+    """Duck-typed guard for tool-like objects with invoke / ainvoke / run (used when langchain-core is absent)."""
+    def __init__(self, guard: Any, inner: Any, verified: str, on_refused: str): self._g, self._i, self._n, self._o = guard, inner, verified, on_refused
+    def __getattr__(self, k: str) -> Any: return getattr(self._i, k)
+    def _args(self, inp: Any) -> Any: return inp.get("args", inp) if isinstance(inp, dict) and "name" in inp and "args" in inp else inp
+    def invoke(self, inp: Any, config: Any = None, **kw: Any) -> Any:
+        r = check_or_refuse(self._g, self._n, self._args(inp), self._o); return json.dumps(r) if r is not None else self._i.invoke(inp, config, **kw)
+    async def ainvoke(self, inp: Any, config: Any = None, **kw: Any) -> Any:
+        r = check_or_refuse(self._g, self._n, self._args(inp), self._o); return json.dumps(r) if r is not None else await self._i.ainvoke(inp, config, **kw)
+    def run(self, inp: Any, **kw: Any) -> Any:
+        r = check_or_refuse(self._g, self._n, self._args(inp), self._o); return json.dumps(r) if r is not None else self._i.run(inp, **kw)
+
+
+def guard_tool(guard: Any, tool: Any, on_refused: str = "result", only: Optional[list] = None, skip: Optional[list] = None, tool_name=None) -> Any:
+    name = getattr(tool, "name", None) or getattr(tool, "__name__", "tool")
+    if not wanted(name, only, skip): return tool
+    verified = tool_name(name) if tool_name else name
+    BaseTool = _base_tool()
+    if BaseTool is not None and isinstance(tool, BaseTool):
+        fields = {"name": tool.name, "description": tool.description, "inner": tool, "guard": guard, "verified_name": verified, "on_refused": on_refused}
+        for k in ("args_schema", "return_direct", "response_format", "metadata", "tags"):
+            v = getattr(tool, k, None)
+            if v is not None: fields[k] = v
+        return _guarded_class(BaseTool)(**fields)
+    return _Proxy(guard, tool, verified, on_refused)
+
+
+def guard_tools(guard: Any, tools: list, **kw: Any) -> list: return [guard_tool(guard, t, **kw) for t in tools]

mnki-0.1.0/mnki/adapters/openai_agents.py

@@ -0,0 +1,40 @@
+"""
+OpenAI Agents SDK (Python) — `openai-agents`. `FunctionTool.on_invoke_tool(ctx, input_json)` is verified before
+the original runs; every other attribute (name, params_json_schema, strict…) is untouched, so `Agent(tools=…)`
+accepts the guarded copies.
+
+    from agents import Agent, function_tool
+    from mnki.adapters.openai_agents import guard_tools
+    agent = Agent(name="invoice-agent", tools=guard_tools(guard, [refund, lookup]))
+"""
+from __future__ import annotations
+import copy, json
+from typing import Any, Optional
+
+from .shared import check_or_refuse, parse_json_args, wanted
+
+
+def guard_tool(guard: Any, tool: Any, on_refused: str = "result", only: Optional[list] = None, skip: Optional[list] = None, tool_name=None) -> Any:
+    name = getattr(tool, "name", None) or getattr(tool, "__name__", "tool")
+    if not wanted(name, only, skip): return tool
+    verified = tool_name(name) if tool_name else name
+    original = tool.on_invoke_tool
+
+    async def on_invoke_tool(ctx: Any, input_json: str) -> Any:
+        r = check_or_refuse(guard, verified, parse_json_args(input_json), on_refused)
+        if r is not None: return json.dumps(r)
+        return await original(ctx, input_json)
+
+    g = copy.copy(tool)
+    try: object.__setattr__(g, "on_invoke_tool", on_invoke_tool)
+    except (AttributeError, TypeError): g = _replace(tool, on_invoke_tool)
+    return g
+
+
+def _replace(tool: Any, fn: Any) -> Any:
+    import dataclasses
+    if dataclasses.is_dataclass(tool): return dataclasses.replace(tool, on_invoke_tool=fn)
+    raise TypeError("tool does not expose a writable on_invoke_tool")
+
+
+def guard_tools(guard: Any, tools: list, **kw: Any) -> list: return [guard_tool(guard, t, **kw) for t in tools]

mnki-0.1.0/mnki/adapters/pydantic_ai.py

@@ -0,0 +1,55 @@
+"""
+Pydantic AI — tools are plain functions registered with `@agent.tool` / `@agent.tool_plain`, or `Tool(...)`
+objects. `guard_tool` wraps the function (sync or async, with or without a `RunContext` first argument) so the
+guard runs before the body; a refusal returns the structured JSON result to the model.
+
+    from mnki.adapters.pydantic_ai import guard_tool
+    @agent.tool_plain
+    @guard_tool(guard)
+    def refund(customer_id: str, amount: float, currency: str = "EUR") -> str: ...
+"""
+from __future__ import annotations
+import functools, inspect, json
+from typing import Any, Callable, Optional
+
+from .shared import check_or_refuse, wanted
+
+
+def _is_run_context(v: Any) -> bool: return type(v).__name__ == "RunContext"
+
+
+def guard_tool(guard: Any, name: Optional[str] = None, on_refused: str = "result", only: Optional[list] = None, skip: Optional[list] = None) -> Callable:
+    def deco(fn: Callable) -> Callable:
+        tool = name or fn.__name__
+        if not wanted(tool, only, skip): return fn
+        sig = inspect.signature(fn)
+
+        def args_of(a: tuple, kw: dict) -> dict:
+            params = list(sig.parameters); vals = list(a)
+            if vals and _is_run_context(vals[0]): vals = vals[1:]; params = params[1:]
+            out = dict(zip(params, vals)); out.update(kw); return out
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def aw(*a: Any, **kw: Any) -> Any:
+                r = check_or_refuse(guard, tool, args_of(a, kw), on_refused); return json.dumps(r) if r is not None else await fn(*a, **kw)
+            return aw
+
+        @functools.wraps(fn)
+        def w(*a: Any, **kw: Any) -> Any:
+            r = check_or_refuse(guard, tool, args_of(a, kw), on_refused); return json.dumps(r) if r is not None else fn(*a, **kw)
+        return w
+    return deco
+
+
+def guard_tools(guard: Any, fns: list, **kw: Any) -> list:
+    """Wrap plain functions, or `Tool` objects (their `.function` is replaced)."""
+    out = []
+    for f in fns:
+        if callable(f) and not hasattr(f, "function"): out.append(guard_tool(guard, **kw)(f)); continue
+        fn = getattr(f, "function", None)
+        if callable(fn):
+            try: f.function = guard_tool(guard, name=getattr(f, "name", None), **kw)(fn)
+            except (AttributeError, TypeError): pass
+        out.append(f)
+    return out

mnki-0.1.0/mnki/adapters/shared.py

@@ -0,0 +1,42 @@
+"""Shared by every adapter: refusal handling and tool filtering."""
+from __future__ import annotations
+import inspect, json
+from typing import Any, Callable, Optional
+
+from ..errors import AgentTrustError
+from ..guard import ApprovalRequired, Denied
+
+
+def wanted(name: str, only: Optional[list] = None, skip: Optional[list] = None) -> bool:
+    return name not in (skip or []) and (not only or name in only)
+
+
+def refusal(e: BaseException) -> dict:
+    """Turn a guard error into the structured result the model sees; anything else is re-raised."""
+    if isinstance(e, Denied):
+        return {"error": "denied", "message": str(e), "reasons": e.reasons, "evidence": [{k: x[k] for k in ("step", "status", "title", "detail") if k in x} for x in e.evidence if x.get("status") != "pass"], "decision_id": e.decision.get("decision_id")}
+    if isinstance(e, ApprovalRequired):
+        return {"error": e.code, "message": str(e), "reasons": e.reasons, "decision_id": e.decision_id, "approval_id": e.approval_id}
+    if isinstance(e, AgentTrustError):
+        return {"error": "verification_failed", "message": f"{e.code}: {e}", "reasons": [e.code]}
+    raise e
+
+
+def refusal_json(e: BaseException) -> str: return json.dumps(refusal(e))
+
+
+def check_or_refuse(guard: Any, tool: str, args: Any, on_refused: str) -> Optional[dict]:
+    """None when the call may proceed; the refusal dict otherwise (or raises when on_refused == "throw")."""
+    try: guard.check(tool, args if isinstance(args, dict) else {"input": args}); return None
+    except AgentTrustError as e:
+        if on_refused == "throw": raise
+        return refusal(e)
+
+
+def parse_json_args(inp: Any) -> Any:
+    if not isinstance(inp, str): return inp if inp is not None else {}
+    try: return json.loads(inp)
+    except ValueError: return {"input": inp}
+
+
+def is_coroutine_fn(fn: Callable) -> bool: return inspect.iscoroutinefunction(fn)

mnki-0.1.0/mnki/client.py

@@ -0,0 +1,73 @@
+"""
+mnki — the Agent Trust SDK for Python.
+
+    from mnki import AgentTrustClient, AgentIdentity
+    c = AgentTrustClient("https://staging.mnki.com", api_key="at_verify_…")
+    d = c.verify({"agent": "procurement-7821", "action": "purchase.create", "amount": 2450, "currency": "EUR"})
+    d["decision"]  # "ALLOW" | "DENY" | "REQUIRE_APPROVAL"; d["evidence"] is the ✓/⚠/✕ list
+
+Signing (Agent-Proof, DPoP-style) needs `pip install cryptography`:
+    ident = AgentIdentity.create(agent_id)            # ES256 key pair; register ident.public_jwk via c.rotate(...)
+    c.verify(req, identity=ident)                     # adds the Agent-Proof header
+"""
+from __future__ import annotations
+import base64, hashlib, json, os, time, urllib.request, urllib.error
+from typing import Any, Callable, Optional
+from .identity import AgentIdentity
+from .errors import AgentTrustError
+
+def b64url(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+def body_hash(body: bytes | str) -> str:
+    return b64url(hashlib.sha256(body.encode() if isinstance(body, str) else body).digest())
+
+class AgentTrustClient:
+    def __init__(self, base_url: str, api_key: str, opener: Optional[Callable[[urllib.request.Request], Any]] = None, timeout: float = 15.0):
+        self.base = base_url.rstrip("/"); self.key = api_key; self._open = opener or (lambda req: urllib.request.urlopen(req, timeout=timeout))
+
+    def _call(self, method: str, path: str, body: Any = None, headers: Optional[dict] = None, raw: Optional[str] = None) -> Any:
+        data = raw.encode() if raw is not None else (None if body is None else json.dumps(body).encode())
+        req = urllib.request.Request(f"{self.base}/api{path}", data=data, method=method)
+        req.add_header("authorization", f"Bearer {self.key}")
+        if data is not None: req.add_header("content-type", "application/json")
+        for k, v in (headers or {}).items(): req.add_header(k, v)
+        try:
+            with self._open(req) as r: return json.loads(r.read() or b"{}")
+        except urllib.error.HTTPError as e:
+            try: j = json.loads(e.read() or b"{}")
+            except Exception: j = {}
+            raise AgentTrustError(e.code, j.get("error", f"http_{e.code}"), j.get("detail", j)) from None
+
+    # --- decisions ---
+    def verify(self, request: dict, identity: Optional[AgentIdentity] = None, credential: Optional[str] = None) -> dict:
+        body = json.dumps(request); headers = {}
+        if identity: headers["agent-proof"] = identity.sign_proof("POST", f"{self.base}/api/v1/verify", body)
+        if credential: headers["agent-credential"] = credential
+        return self._call("POST", "/v1/verify", headers=headers, raw=body)
+    def approval_status(self, approval_id: str) -> dict: return self._call("GET", f"/v1/approvals/{approval_id}/status")
+    def decision(self, decision_id: str) -> dict: return self._call("GET", f"/v1/decisions/{decision_id}")
+    def authzen(self, subject_id: str, action: str, resource: Optional[dict] = None, context: Optional[dict] = None, properties: Optional[dict] = None) -> dict:
+        return self._call("POST", "/access/v1/evaluation", {"subject": {"type": "agent", "id": subject_id}, "action": {"name": action, "properties": properties or {}}, "resource": resource or {}, "context": context or {}})
+    # --- agents ---
+    def register(self, **agent: Any) -> dict: return self._call("POST", "/v1/agents", agent)
+    def agent(self, agent_id: str) -> dict: return self._call("GET", f"/v1/agents/{agent_id}")
+    def rotate(self, agent_id: str, public_jwk: dict, kid: str, kind: str = "jwt_svid", issuer: Optional[str] = None) -> dict:
+        return self._call("POST", f"/v1/agents/{agent_id}/rotate", {"kind": kind, "kid": kid, "publicKeyJwk": public_jwk, "issuer": issuer})
+    def enrol(self, **agent: Any) -> tuple[dict, AgentIdentity]:
+        r = self.register(**agent); ident = AgentIdentity.create(r["id"]); self.rotate(r["id"], ident.public_jwk, ident.kid, issuer=agent.get("issuer")); return r, ident
+    def attest(self, agent_id: str, kind: str, claims: dict, proof: Optional[dict] = None, expires_at: Optional[str] = None) -> dict:
+        return self._call("POST", f"/v1/agents/{agent_id}/attestations", {"kind": kind, "claims": claims, "proof": proof, "expires_at": expires_at})
+    def agent_card(self, agent_id: str) -> dict: return self._call("GET", f"/v1/agents/{agent_id}/agent-card")
+    # --- authority ---
+    def delegate(self, issuer: dict, subject_agent_id: str, capabilities: list, parent_id: Optional[str] = None, task: Optional[str] = None, not_after: Optional[str] = None) -> dict:
+        return self._call("POST", "/v1/delegations", {"issuer": issuer, "subjectAgentId": subject_agent_id, "capabilities": capabilities, "parentId": parent_id, "task": task, "notAfter": not_after})
+    def credential_chain(self, delegation_id: str) -> dict: return self._call("GET", f"/v1/delegations/{delegation_id}/credential")
+    def issue_attestation(self, decision_id: str, ttl_seconds: Optional[int] = None, audience: Optional[str] = None) -> dict:
+        return self._call("POST", "/v1/attestations", {"decision_id": decision_id, "ttl_seconds": ttl_seconds, "audience": audience})
+    def revoke_attestation(self, attestation_id: str, reason: str) -> dict: return self._call("DELETE", f"/v1/attestations/{attestation_id}", {"reason": reason})
+    def status(self, subject: str) -> dict: return self._call("GET", f"/v1/status/{subject}")
+    def jwks(self, org_id: str) -> dict:
+        with self._open(urllib.request.Request(f"{self.base}/api/v1/orgs/{org_id}/jwks")) as r: return json.loads(r.read())
+
+Client = AgentTrustClient

mnki-0.1.0/mnki/errors.py

@@ -0,0 +1,12 @@
+"""Error taxonomy shared by the Python SDK, the guard and the adapters."""
+from __future__ import annotations
+from typing import Any
+
+
+class AgentTrustError(Exception):
+    """An error returned by the control plane (HTTP status + machine code + detail)."""
+    def __init__(self, status: int, code: str, detail: Any = None):
+        super().__init__(f"{code} ({status})"); self.status, self.code, self.detail = status, code, detail
+
+
+MnkiError = AgentTrustError

mnki-0.1.0/mnki/guard.py

@@ -0,0 +1,133 @@
+"""
+guard() / wrap() for Python: verify a tool call before it runs, against the hosted control plane.
+Modes: observe (log only), warn (run, surface evidence), require_approval (escalate only), enforce.
+
+    from mnki import AgentTrustClient, Guard, Denied, ApprovalRequired
+    g = Guard(AgentTrustClient("https://mnki.com", api_key="at_verify_…"), agent="invoice-agent")
+
+    @g.wrap("refund.create")
+    def refund(customer_id: str, amount: float, currency: str = "EUR"): ...
+
+Local mode (no account): `Guard(world=demo_world(), agent="invoice-agent", action_prefix="")` runs the same
+pipeline in-process (`mnki.pipeline`, validated against the conformance vectors).
+"""
+from __future__ import annotations
+import asyncio, functools, hashlib, inspect, json, random, time
+from typing import Any, Callable, Optional
+
+from .errors import AgentTrustError
+from .identity import AgentIdentity, b64url
+from .local import local_verify
+
+Mode = str  # "observe" | "warn" | "require_approval" | "enforce"
+
+
+class Denied(AgentTrustError):
+    """The action was verified and refused. `evidence` is the ✓/⚠/✕ list (fail and warn rows first)."""
+    def __init__(self, decision: dict):
+        reasons = [r for r in decision.get("reasons", []) if not r.endswith("_verified") and r != "authority_valid"]
+        super().__init__(403, "denied", decision); self.decision = decision; self.reasons = decision.get("reasons", [])
+        self.args = (f"denied: {', '.join(reasons) or 'policy'}",)
+    @property
+    def evidence(self) -> list:
+        order = {"fail": 0, "warn": 1, "pass": 2, "skipped": 3}
+        return sorted(self.decision.get("evidence", []), key=lambda e: order.get(e.get("status"), 9))
+
+
+class ApprovalRequired(AgentTrustError):
+    """A human must decide (or already decided against, or the wait ended)."""
+    def __init__(self, approval_id: Optional[str], decision_id: str, status: str, reasons: Optional[list] = None):
+        code = {"pending": "approval_required", "rejected": "approval_rejected", "expired": "approval_expired"}.get(status, "approval_timeout")
+        super().__init__(202, code, {"approval_id": approval_id, "decision_id": decision_id}); self.approval_id, self.decision_id, self.status, self.reasons = approval_id, decision_id, status, reasons or []
+
+
+def _default_map(_tool: str, args: dict) -> dict:
+    out: dict = {}
+    amount = args.get("amount", args.get("value"))
+    if isinstance(amount, str) and amount.replace(".", "", 1).isdigit(): amount = float(amount)
+    if isinstance(amount, (int, float)) and not isinstance(amount, bool): out["amount"] = amount
+    cur = args.get("currency")
+    if isinstance(cur, str) and len(cur) == 3 and cur.isupper(): out["currency"] = cur
+    for k in ("resource", "customer_id", "customerId", "id"):
+        if isinstance(args.get(k), str): out["resource"] = args[k]; break
+    if isinstance(args.get("region"), str): out["context"] = {"region": args["region"]}
+    return out
+
+
+def _tags(d: dict) -> list:
+    t: list = []; r = d.get("reasons", [])
+    if d.get("decision") == "DENY": t.append("would_deny")
+    if d.get("decision") == "REQUIRE_APPROVAL": t.append("approval_required")
+    if "agent_unknown" in r or any(x.startswith("credential_") for x in r): t.append("missing_identity")
+    if "no_delegation" in r or any(x.startswith("delegation_") for x in r): t.append("missing_delegation")
+    if any(x in r for x in ("capability_missing", "constraint_violated", "budget_exceeded")): t.append("excess_capability")
+    if any(x.startswith("policy:") and not x.endswith(":allow") for x in r): t.append("policy_mismatch")
+    return t
+
+
+class Guard:
+    def __init__(self, client: Any = None, agent: str = "", identity: Optional[AgentIdentity] = None, mode: Mode = "enforce", action_prefix: str = "tool:", map_args: Optional[Callable[[str, dict], dict]] = None, on_approval: str = "wait", approval_timeout: float = 300.0, initial_delay: float = 1.0, max_delay: float = 15.0, on_decision: Optional[Callable[[dict], None]] = None, sleep: Callable[[float], None] = time.sleep, world: Optional[dict] = None, now: Optional[Callable[[], Any]] = None):
+        if mode not in ("observe", "warn", "require_approval", "enforce"): raise ValueError("mode must be observe | warn | require_approval | enforce")
+        if client is None and world is None: raise ValueError("guard needs either `client` (hosted) or `world` (local)")
+        if not agent: raise ValueError("agent is required")
+        self.client, self.agent, self.identity, self.mode, self.prefix, self.world, self._now = client, agent, identity, mode, action_prefix, world, now
+        self.map_args, self.on_approval, self.timeout, self.initial_delay, self.max_delay, self.on_decision, self._sleep = map_args or _default_map, on_approval, approval_timeout, initial_delay, max_delay, on_decision, sleep
+
+    def _input(self, tool: str, args: dict) -> dict:
+        mapped = self.map_args(tool, args or {})
+        ctx = dict(mapped.pop("context", {}) or {}); ctx.update({"tool": tool, "arguments_hash": b64url(hashlib.sha256(json.dumps(args or {}, sort_keys=True, separators=(",", ":")).encode()).digest())})
+        return {"agent": self.agent, "action": f"{self.prefix}{tool}", **mapped, "context": ctx}
+
+    def wait_for_approval(self, approval_id: str) -> str:
+        deadline = time.time() + self.timeout; delay = self.initial_delay
+        while True:
+            s = self.client.approval_status(approval_id); st = s.get("status")
+            if st in ("approved", "rejected", "expired"): return st
+            if time.time() >= deadline: return "timeout"
+            self._sleep(min(max(0.0, deadline - time.time()), delay + random.random() * 0.25)); delay = min(self.max_delay, delay * 2)
+
+    def check(self, tool: str, args: Optional[dict] = None) -> dict:
+        """Verify one tool call. Returns the decision when the call may proceed; raises Denied / ApprovalRequired otherwise (mode permitting)."""
+        if self.client is not None: d = self.client.verify(self._input(tool, args or {}), identity=self.identity)
+        else:
+            r = local_verify(self.world, self._input(tool, args or {}), self._now() if self._now else None)
+            if not r["ok"]: raise AgentTrustError(400, r["code"])
+            d = dict(r["result"]); d.update({"request_id": "local", "decision_id": f"local_{int(time.time() * 1000):x}", "approval_id": "local_pending" if d["decision"] == "REQUIRE_APPROVAL" else None, "latency_ms": 0})
+        enforced = self.mode == "enforce" or (self.mode == "require_approval" and d.get("decision") == "REQUIRE_APPROVAL")
+        record = {"at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), "mode": self.mode, "tool": tool, "decision": d.get("decision"), "enforced": enforced, "reasons": d.get("reasons", []), "evidence": d.get("evidence", []), "decision_id": d.get("decision_id"), "approval_id": d.get("approval_id"), "tags": _tags(d)}
+        if self.on_decision: self.on_decision(record)
+        result = {"allowed": d.get("decision") == "ALLOW", "decision": d.get("decision"), "reasons": d.get("reasons", []), "evidence": d.get("evidence", []), "decision_id": d.get("decision_id"), "approval_id": d.get("approval_id"), "enforced": enforced}
+        if d.get("decision") == "ALLOW" or not enforced: result["allowed"] = True; return result
+        if d.get("decision") == "DENY": raise Denied(d)
+        if self.client is None or self.on_approval == "throw" or not d.get("approval_id"): raise ApprovalRequired(d.get("approval_id"), d.get("decision_id", ""), "pending", d.get("reasons"))
+        status = self.wait_for_approval(d["approval_id"])
+        if status != "approved": raise ApprovalRequired(d["approval_id"], d.get("decision_id", ""), status, d.get("reasons"))
+        try: result["attestation"] = self.client.issue_attestation(d["decision_id"]).get("token")
+        except AgentTrustError: pass
+        result["allowed"] = True; return result
+
+    def wrap(self, tool: Optional[str] = None):
+        """Decorator: the function runs only after `check` resolves. Keyword arguments (or a single dict) are the tool arguments."""
+        def deco(fn: Callable):
+            name = tool or fn.__name__
+            if inspect.iscoroutinefunction(fn):
+                @functools.wraps(fn)
+                async def aw(*a, **kw):
+                    await asyncio.get_running_loop().run_in_executor(None, self.check, name, _args(a, kw)); return await fn(*a, **kw)
+                return aw
+            @functools.wraps(fn)
+            def w(*a, **kw):
+                self.check(name, _args(a, kw)); return fn(*a, **kw)
+            return w
+        return deco
+
+
+def _args(a: tuple, kw: dict) -> dict:
+    if kw: return dict(kw)
+    if len(a) == 1 and isinstance(a[0], dict): return a[0]
+    return {"args": list(a)} if a else {}
+
+
+def wrap(client: Any, agent: str, tool: Optional[str] = None, **guard_kw):
+    """`@mnki.wrap(client, "invoice-agent", "refund.create")` — a one-line guard for a single tool."""
+    return Guard(client, agent, **guard_kw).wrap(tool)