mayi 0.0.0__py3-none-any.whl

mayi/__init__.py

@@ -0,0 +1,18 @@
+from .approvals import ApprovalSet, ApprovalToken
+from .audit import SqliteAuditLog
+from .boundary import ToolBoundary
+from .catalog import Catalog, CatalogError, Pen
+from .diff import CatalogDiff, diff_catalogs
+from .report import GovernanceReport, generate_report
+from .resolve import SourcePathError, dotted_lookup
+from .results import Escalated, Executed, Rejected
+from .schema import hide_application_pen, tools_for_model
+from .seal import MayiEscalationRequired, MayiRejected, check_no_direct_exposure, gate
+
+__all__ = [
+    "ApprovalSet", "ApprovalToken", "ToolBoundary", "Catalog", "CatalogError", "Pen",
+    "Escalated", "Executed", "Rejected", "SqliteAuditLog", "hide_application_pen", "tools_for_model",
+    "dotted_lookup", "SourcePathError", "GovernanceReport", "generate_report",
+    "CatalogDiff", "diff_catalogs",
+    "gate", "MayiEscalationRequired", "MayiRejected", "check_no_direct_exposure",
+]

mayi/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

mayi/adapters.py

@@ -0,0 +1,84 @@
+"""
+Adapters that put an agent framework's tools behind a mayi gateway.
+
+Each takes the tool definitions in the Anthropic shape (name, description,
+input_schema -- what `mayi.agent_client.tool_schemas` returns) and returns
+framework tools whose every invocation goes through MayiClient.call. The
+tool body never runs in your process: the gateway decides, and runs the real
+tool only when the rules allow. A held or rejected call comes back to the
+model as a plain message saying so.
+
+    from mayi.adapters import openai_agents_tools, crewai_tools
+    tools = openai_agents_tools(MayiClient(), "ticket-1042", schemas)
+
+The framework packages are imported only when you call the adapter.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import MayiClient
+
+
+def outcome_text(res: dict) -> str:
+    """What the model is told. Keeps the reason, drops nothing a model needs to explain itself."""
+    o = res.get("outcome")
+    if o == "executed":
+        return json.dumps({"status": "done", "result": res.get("result")}, default=str)
+    if o == "escalated":
+        return json.dumps({"status": "waiting for a person to approve", "argument": res.get("arg"),
+                           "reason": res.get("reason")}, default=str)
+    return json.dumps({"status": "not allowed", "reason": res.get("reason")}, default=str)
+
+
+def _invoke(client: MayiClient, session_id: str, tool: str, args: dict) -> str:
+    return outcome_text(client.call(session_id, tool, args))
+
+
+def openai_agents_tools(client: MayiClient, session_id: str, schemas: list[dict]) -> list[Any]:
+    from agents import FunctionTool  # type: ignore[import-not-found]
+
+    tools = []
+    for sch in schemas:
+        name = sch["name"]
+
+        async def on_invoke(ctx: Any, raw: str, _name: str = name) -> str:
+            try:
+                args = json.loads(raw or "{}")
+            except json.JSONDecodeError:
+                return json.dumps({"status": "not allowed", "reason": "arguments were not valid JSON"})
+            if not isinstance(args, dict):
+                return json.dumps({"status": "not allowed", "reason": "arguments must be an object"})
+            return _invoke(client, session_id, _name, args)
+
+        schema = dict(sch["input_schema"])
+        schema.setdefault("additionalProperties", False)
+        tools.append(FunctionTool(name=name, description=sch.get("description", name),
+                                  params_json_schema=schema, on_invoke_tool=on_invoke,
+                                  strict_json_schema=False))
+    return tools
+
+
+def crewai_tools(client: MayiClient, session_id: str, schemas: list[dict]) -> list[Any]:
+    from crewai.tools import BaseTool  # type: ignore[import-not-found]
+    from pydantic import Field, create_model
+
+    tools = []
+    for sch in schemas:
+        name = sch["name"]
+        props = sch["input_schema"].get("properties", {})
+        Args = create_model(f"{name}_args", **{p: (Any, Field(default=None, description=d.get("description", p)))
+                                               for p, d in props.items()})
+
+        def _run(self: Any, _name: str = name, **kwargs: Any) -> str:
+            return _invoke(client, session_id, _name, {k: v for k, v in kwargs.items() if v is not None})
+
+        cls = type(f"Mayi_{name}", (BaseTool,), {
+            "__module__": __name__,
+            "__annotations__": {"name": str, "description": str, "args_schema": type},
+            "name": name, "description": sch.get("description", name),
+            "args_schema": Args, "_run": _run})
+        tools.append(cls())
+    return tools

mayi/agent_client.py

@@ -0,0 +1,66 @@
+"""
+A model-agnostic agent loop that talks to a mayi gateway with the AGENT key.
+
+The agent sees only the arguments it is allowed to propose (model and human
+pens). Application-pen and derived arguments are never offered to it, and
+anything it sends for them is discarded by the gateway anyway.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.request
+from typing import Any
+
+
+def _post(base: str, key: str, path: str, body: dict) -> dict:
+    r = urllib.request.Request(base + path, json.dumps(body).encode(), method="POST",
+                               headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"})
+    with urllib.request.urlopen(r, timeout=30) as resp:  # nosec B310 (operator-configured URL)
+        return json.loads(resp.read())
+
+
+def tool_schemas(catalog_view: dict, descriptions: dict[str, str] | None = None) -> list[dict]:
+    """Anthropic tool schemas from the gateway's /v1/catalog view (agent-proposable args only)."""
+    out = []
+    for tool, args in catalog_view["tools"].items():
+        props = {a: {"description": f"{a} ({pen}-controlled)"} for a, pen in args.items()
+                 if pen in ("model", "human")}
+        out.append({"name": tool, "description": (descriptions or {}).get(tool, tool),
+                    "input_schema": {"type": "object", "properties": props, "required": list(props)}})
+    return out
+
+
+def run_agent(client: Any, model: str, base: str, agent_key: str, session_id: str,
+              tools: list[dict], task: str, max_turns: int = 6, log=print,
+              wait_for_approval: float = 0, poll: float = 2.0, session_token: str | None = None) -> list[dict]:
+    """Run a tool-use loop; every tool call goes through the gateway. Returns the gateway outcomes."""
+    messages = [{"role": "user", "content": task}]
+    outcomes: list[dict] = []
+    for _ in range(max_turns):
+        resp = client.messages.create(model=model, max_tokens=1024, tools=tools, messages=messages)
+        uses = [b for b in resp.content if getattr(b, "type", "") == "tool_use"]
+        if not uses:
+            break
+        messages.append({"role": "assistant", "content": resp.content})
+        results = []
+        for u in uses:
+            body = {"session_id": session_id, "tool": u.name, "args": u.input}
+            if session_token:
+                body["session_token"] = session_token
+            r = _post(base, agent_key, "/v1/call", body)
+            if r.get("outcome") == "escalated" and wait_for_approval:
+                # Hold the call open for a human decision. simulate never consumes
+                # an approval; only the final /v1/call executes (once).
+                log(f"  waiting up to {wait_for_approval:.0f}s for a human to approve {u.name}...")
+                deadline = time.time() + wait_for_approval
+                while time.time() < deadline:
+                    time.sleep(poll)
+                    if _post(base, agent_key, "/v1/simulate", body).get("outcome") == "simulated":
+                        r = _post(base, agent_key, "/v1/call", body)
+                        break
+            outcomes.append(r)
+            log(f"  model proposed {u.name}({json.dumps(u.input)}) -> {r['outcome']} {r.get('reason', '')}")
+            results.append({"type": "tool_result", "tool_use_id": u.id, "content": json.dumps(r)})
+        messages.append({"role": "user", "content": results})
+    return outcomes

mayi/approvals.py

@@ -0,0 +1,79 @@
+"""
+An approval token covers one tool, one argument, one value. It is never
+a standing "whatever it needs" grant — a bounded standing approval is
+expressed in the catalog's `limit` instead (see limits.py), reviewed and
+committed once, not minted per call.
+
+Tokens are single-use and may carry an expiry. A token that already fired,
+or that has expired, is exactly as absent as one that was never issued.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class ApprovalToken:
+    tool: str
+    arg: str
+    value: Any
+    approved_by: str
+    expires_at: Optional[float] = None  # epoch seconds; None = no expiry
+    used: bool = False
+    # Optional resource scope, e.g. {"ticket_id": "T-9"}: the approval holds
+    # only for a call whose application-pen (trusted) argument values equal
+    # these. Keys are checked against values the application resolved, never
+    # against anything the model proposed. A scoped token with no matching
+    # trusted context is exactly as absent as no token (fails closed).
+    scope: Optional[dict] = None
+    approvers: tuple = ()  # for two-person approvals: every distinct person who signed off
+    store_id: Optional[int] = None  # row id when a StateStore keeps this token
+
+    def matches(self, tool: str, arg: str, value: Any, context: Optional[dict] = None) -> bool:
+        if not (self.tool == tool and self.arg == arg and self.value == value):
+            return False
+        if self.scope:
+            context = context or {}
+            return all(k in context and context[k] == v for k, v in self.scope.items())
+        return True
+
+    def is_live(self, now: Optional[float] = None) -> bool:
+        now = time.time() if now is None else now
+        return not self.used and (self.expires_at is None or now <= self.expires_at)
+
+
+class ApprovalSet:
+    """A small collection of tokens gathered for one call attempt."""
+
+    def __init__(self, tokens: Optional[list[ApprovalToken]] = None, on_use: Optional[Any] = None):
+        self._tokens = tokens or []
+        self.on_use = on_use  # called with the token the moment it is consumed, before the tool runs
+
+    def add(self, token: "ApprovalToken") -> None:
+        self._tokens.append(token)
+
+    def take(self, tool: str, arg: str, value: Any, now: Optional[float] = None,
+             context: Optional[dict] = None) -> Optional[ApprovalToken]:
+        """
+        Find a live token matching exactly this tool/arg/value and consume
+        it. Returns None if no such token exists, is expired, or was
+        already used by an earlier call in this same run.
+        """
+        for token in self._tokens:
+            if token.matches(tool, arg, value, context) and token.is_live(now):
+                token.used = True
+                if self.on_use is not None:
+                    self.on_use(token)
+                return token
+        return None
+
+    def peek(self, tool: str, arg: str, value: Any, now: Optional[float] = None,
+             context: Optional[dict] = None) -> Optional[ApprovalToken]:
+        """Like take(), but does not consume the token (used by dry runs)."""
+        for token in self._tokens:
+            if token.matches(tool, arg, value, context) and token.is_live(now):
+                return token
+        return None

mayi/audit.py

@@ -0,0 +1,93 @@
+"""
+A durable, queryable audit log backed by SQLite. Pass an instance of
+SqliteAuditLog as ToolBoundary's audit_log callable, or write your own --
+the boundary only needs something callable with one dict argument.
+
+Known fields get their own column so they're queryable with plain SQL.
+Anything else (e.g. a field an integration adds) is kept, not dropped, in `extra`.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from typing import Any, Optional
+
+_KNOWN = (
+    "tool", "outcome", "actor", "catalog_hash", "catalog_version", "catalog_reviewed_by",
+    "model_proposed", "pens", "notes", "reason", "escalated_arg", "escalated_value",
+)
+
+
+class SqliteAuditLog:
+    def __init__(self, path: str = "mayi_audit.db"):
+        self.path = path
+        self._conn = sqlite3.connect(path)
+        self._conn.execute("""
+            CREATE TABLE IF NOT EXISTS audit_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                ts REAL NOT NULL,
+                tool TEXT,
+                outcome TEXT NOT NULL,
+                actor TEXT,
+                catalog_hash TEXT,
+                catalog_version TEXT,
+                catalog_reviewed_by TEXT,
+                model_proposed TEXT NOT NULL,
+                pens TEXT NOT NULL,
+                notes TEXT NOT NULL,
+                reason TEXT,
+                escalated_arg TEXT,
+                escalated_value TEXT,
+                extra TEXT NOT NULL
+            )
+        """)
+        self._conn.commit()
+
+    def __call__(self, record: dict) -> None:
+        extra = {k: v for k, v in record.items() if k not in _KNOWN}
+        self._conn.execute(
+            "INSERT INTO audit_log (ts, tool, outcome, actor, catalog_hash, catalog_version, "
+            "catalog_reviewed_by, model_proposed, pens, notes, reason, escalated_arg, "
+            "escalated_value, extra) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+            (
+                time.time(), record.get("tool"), record["outcome"], record.get("actor"),
+                record.get("catalog_hash"), record.get("catalog_version"), record.get("catalog_reviewed_by"),
+                json.dumps(record.get("model_proposed", {})), json.dumps(record.get("pens", {})),
+                json.dumps(record.get("notes", {})), record.get("reason"),
+                record.get("escalated_arg"), json.dumps(record.get("escalated_value"))
+                if "escalated_value" in record else None,
+                json.dumps(extra),
+            ),
+        )
+        self._conn.commit()
+
+    _COLUMNS = ("id", "ts", "tool", "outcome", "actor", "catalog_hash", "catalog_version",
+                "catalog_reviewed_by", "model_proposed", "pens", "notes", "reason",
+                "escalated_arg", "escalated_value", "extra")
+    _SELECT_ALL = (
+        "SELECT id, ts, tool, outcome, actor, catalog_hash, catalog_version, catalog_reviewed_by, "
+        "model_proposed, pens, notes, reason, escalated_arg, escalated_value, extra "
+        "FROM audit_log ORDER BY id"
+    )
+
+    def all(self) -> list[dict]:
+        rows = self._conn.execute(self._SELECT_ALL).fetchall()
+        out = []
+        for row in rows:
+            d = dict(zip(self._COLUMNS, row))
+            d["model_proposed"] = json.loads(d["model_proposed"])
+            d["pens"] = json.loads(d["pens"])
+            d["notes"] = json.loads(d["notes"])
+            d["escalated_value"] = json.loads(d["escalated_value"]) if d["escalated_value"] is not None else None
+            extra = json.loads(d.pop("extra"))
+            d.update(extra)  # extra fields land back at the top level, same as what was logged
+            out.append(d)
+        return out
+
+    def rejected_and_escalated(self) -> list[dict]:
+        return [r for r in self.all() if r["outcome"] != "Executed"]
+
+    def close(self) -> None:
+        self._conn.close()