actionrail 0.1.0b7__py3-none-any.whl

actionrail/__init__.py

@@ -0,0 +1,29 @@
+"""ActionRail — grounded actions for AI agents."""
+
+from .sdk.action_tests import ActionTestError, ActionTestReport, run_action_tests
+from .sdk.actions import ActionDefinition
+from .sdk.context import current_trusted_context, trusted_context
+from .sdk.enforce import enforce
+from .sdk.instrument import instrument
+from .sdk.lifecycle import close_reporting, flush_reporting, get_runtime_health
+from .sdk.pipeline import Decision
+from .sdk.runtime import ActionBlocked, ActionHeld, ActionNotAllowed, ActionRuntime
+
+__all__ = [
+    "ActionTestError",
+    "ActionDefinition",
+    "ActionTestReport",
+    "run_action_tests",
+    "instrument",
+    "enforce",
+    "trusted_context",
+    "current_trusted_context",
+    "flush_reporting",
+    "close_reporting",
+    "get_runtime_health",
+    "Decision",
+    "ActionRuntime",
+    "ActionNotAllowed",
+    "ActionBlocked",
+    "ActionHeld",
+]

actionrail/cli.py

@@ -0,0 +1,82 @@
+"""Command-line interface for ActionRail framework tooling."""
+
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import PackageNotFoundError, version
+import json
+import sys
+
+from .sdk.action_tests import ActionTestError, run_action_tests
+
+
+def _package_version() -> str:
+    try:
+        return version("actionrail")
+    except PackageNotFoundError:
+        return "development"
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="actionrail",
+        description="Test and operate ActionRail action contracts.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_package_version()}")
+    commands = parser.add_subparsers(dest="command", required=True)
+    test = commands.add_parser(
+        "test",
+        help="run deterministic allow, hold, and block regression cases",
+    )
+    test.add_argument("config", nargs="?", default="actionrail.yaml", help="rules file")
+    test.add_argument(
+        "--cases",
+        default="actionrail.cases.yaml",
+        help="Action Tests document (default: actionrail.cases.yaml)",
+    )
+    test.add_argument(
+        "--live-sources",
+        action="store_true",
+        help="allow cases without fixtures to use Sources from the rules file",
+    )
+    test.add_argument("--format", choices=("text", "json"), default="text")
+    return parser
+
+
+def _print_text(report) -> None:
+    print("ActionRail Action Tests")
+    print(f"Rules: {report.config_path}")
+    print(f"Cases: {report.cases_path}\n")
+    for result in report.results:
+        mark = "PASS" if result.passed else "FAIL"
+        print(f"{mark}  {result.name}")
+        print(f"      {result.tool}: expected {result.expected}, got {result.actual}")
+        for reason in result.reasons:
+            print(f"      {reason}")
+        if result.error:
+            print(f"      {result.error}")
+    print(f"\n{report.passed} passed · {report.failed} failed")
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command != "test":
+        return 2
+    try:
+        report = run_action_tests(
+            args.config,
+            args.cases,
+            live_sources=args.live_sources,
+        )
+    except ActionTestError as exc:
+        print(f"Action Tests configuration error: {exc}", file=sys.stderr)
+        return 2
+    if args.format == "json":
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        _print_text(report)
+    return 0 if report.successful else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

actionrail/mcp_quickstart.py

@@ -0,0 +1,193 @@
+"""Run a local MCP Streamable HTTP grounding example.
+
+The example starts a temporary read-only MCP server, calls it through the real
+ActionRail MCP Source adapter, and proves that a cross-customer payment is
+blocked before the simulated refund function executes.
+"""
+
+from __future__ import annotations
+
+import socket
+import threading
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Iterator
+
+from mcp.types import CallToolResult, ToolAnnotations
+
+from actionrail.sdk.config import config_from_dict
+from actionrail.sdk.grounding import MCPSource
+from actionrail.sdk.pipeline import decide
+
+
+CALLER_CUSTOMER_ID = "CUSTOMER-100"
+OWN_PAYMENT_ID = "PAYMENT-OWN"
+OTHER_PAYMENT_ID = "PAYMENT-OTHER"
+
+_PAYMENTS = {
+    OWN_PAYMENT_ID: {
+        "payment_id": OWN_PAYMENT_ID,
+        "customer_id": CALLER_CUSTOMER_ID,
+        "status": "captured",
+    },
+    OTHER_PAYMENT_ID: {
+        "payment_id": OTHER_PAYMENT_ID,
+        "customer_id": "CUSTOMER-OTHER",
+        "status": "captured",
+    },
+}
+
+
+@dataclass
+class _Gateway:
+    endpoint: str
+    server: object
+    thread: threading.Thread
+    socket: socket.socket
+
+
+@contextmanager
+def _local_gateway() -> Iterator[_Gateway]:
+    import uvicorn
+    from mcp.server.fastmcp import FastMCP
+
+    mcp = FastMCP(
+        "ActionRail MCP quickstart",
+        stateless_http=True,
+        json_response=True,
+        log_level="ERROR",
+    )
+
+    @mcp.tool(annotations=ToolAnnotations(readOnlyHint=True))
+    def lookup_payment(payment_id: str) -> CallToolResult:
+        """Return one payment record without modifying the billing system."""
+
+        return CallToolResult(
+            content=[],
+            structuredContent={"payment": _PAYMENTS.get(payment_id)},
+        )
+
+    listener = socket.socket()
+    listener.bind(("127.0.0.1", 0))
+    host, port = listener.getsockname()
+    server = uvicorn.Server(
+        uvicorn.Config(
+            mcp.streamable_http_app(),
+            log_level="error",
+            lifespan="on",
+        )
+    )
+    thread = threading.Thread(
+        target=server.run,
+        kwargs={"sockets": [listener]},
+        daemon=True,
+    )
+    thread.start()
+    deadline = time.monotonic() + 5
+    while not server.started and thread.is_alive() and time.monotonic() < deadline:
+        time.sleep(0.01)
+    if not server.started:
+        server.should_exit = True
+        thread.join(timeout=2)
+        listener.close()
+        raise RuntimeError("the local MCP server did not start")
+
+    gateway = _Gateway(f"http://{host}:{port}/mcp", server, thread, listener)
+    try:
+        yield gateway
+    finally:
+        server.should_exit = True
+        thread.join(timeout=5)
+        listener.close()
+
+
+def run_quickstart() -> dict:
+    config = config_from_dict({
+        "schema_version": 1,
+        "tools": {
+            "refund_payment": {
+                "kind": "consequential",
+                "args": {
+                    "payment_id": {
+                        "ground": {
+                            "checks": [{
+                                "source": "billing-mcp",
+                                "match": [
+                                    {"column": "customer_id", "ctx": "customer_id"},
+                                    {"column": "status", "value": "captured"},
+                                ],
+                            }],
+                        },
+                    },
+                },
+            },
+        },
+    })
+
+    executed: list[str] = []
+
+    def refund_payment(payment_id: str) -> None:
+        executed.append(payment_id)
+
+    with _local_gateway() as gateway:
+        source = MCPSource(
+            endpoint=gateway.endpoint,
+            tool="lookup_payment",
+            arguments={"payment_id": "{value}"},
+            select="payment",
+        )
+        sources = {"billing-mcp": source}
+        context = {"customer_id": CALLER_CUSTOMER_ID}
+
+        allowed = decide(
+            "refund_payment",
+            {"payment_id": OWN_PAYMENT_ID},
+            config,
+            sources,
+            context,
+        )
+        if allowed.outcome == "allow":
+            refund_payment(OWN_PAYMENT_ID)
+
+        blocked = decide(
+            "refund_payment",
+            {"payment_id": OTHER_PAYMENT_ID},
+            config,
+            sources,
+            context,
+        )
+        if blocked.outcome == "allow":
+            refund_payment(OTHER_PAYMENT_ID)
+
+    if allowed.outcome != "allow":
+        raise RuntimeError(f"expected owned payment to be allowed, got {allowed.outcome}")
+    if blocked.outcome != "block":
+        raise RuntimeError(f"expected cross-customer payment to be blocked, got {blocked.outcome}")
+    if executed != [OWN_PAYMENT_ID]:
+        raise RuntimeError(f"unexpected refund executions: {executed}")
+
+    return {
+        "allowed": allowed.outcome,
+        "blocked": blocked.outcome,
+        "executed": executed,
+    }
+
+
+def main() -> int:
+    try:
+        result = run_quickstart()
+    except (OSError, RuntimeError) as exc:
+        print(f"ActionRail MCP quickstart failed: {exc}")
+        return 1
+
+    print("✓ Started a local MCP Streamable HTTP server")
+    print("✓ Discovered a verification tool marked read-only")
+    print(f"✓ Owned payment decision: {result['allowed']}")
+    print(f"✓ Cross-customer payment decision: {result['blocked']}")
+    print("✓ The blocked refund function did not execute")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

actionrail/quickstart.py

@@ -0,0 +1,207 @@
+"""Run the deterministic ActionRail + LangGraph quickstart.
+
+The command creates a local LangGraph agent, registers it and a SQLite Source
+with the ActionRail Console, installs a grounding rule, and proves that a
+cross-customer refund is blocked before the refund tool executes.
+
+Start ``actionrail-console`` first, then run ``actionrail-quickstart``. No
+model API key or repository checkout is required.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sqlite3
+from pathlib import Path
+
+import httpx
+from langchain_core.messages import AIMessage, HumanMessage
+from langchain_core.tools import tool
+
+from actionrail import close_reporting, enforce
+
+ORDER_ID = "ORDER-OTHER-CUSTOMER"
+CALLER_CUSTOMER_ID = "CUSTOMER-100"
+
+
+def _langgraph_types():
+    try:
+        from langgraph.graph import END, START, MessagesState, StateGraph
+        from langgraph.prebuilt import ToolNode
+    except ImportError as exc:  # pragma: no cover - exercised by installed-package smoke tests
+        raise RuntimeError(
+            'LangGraph is not installed. Run: python -m pip install "actionrail[agents]"'
+        ) from exc
+    return END, START, MessagesState, StateGraph, ToolNode
+
+
+def _build_database(path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    connection = sqlite3.connect(path)
+    try:
+        connection.execute(
+            "CREATE TABLE IF NOT EXISTS orders "
+            "(order_id TEXT PRIMARY KEY, customer_id TEXT, status TEXT)"
+        )
+        connection.execute("DELETE FROM orders")
+        connection.executemany(
+            "INSERT INTO orders VALUES (?, ?, ?)",
+            [
+                ("ORDER-MINE", CALLER_CUSTOMER_ID, "delivered"),
+                (ORDER_ID, "CUSTOMER-OTHER", "delivered"),
+            ],
+        )
+        connection.commit()
+    finally:
+        connection.close()
+
+
+def _build_agent(executed: list[dict]):
+    END, START, MessagesState, StateGraph, ToolNode = _langgraph_types()
+
+    @tool
+    def issue_refund(order_id: str, amount: float) -> str:
+        """Issue a real customer refund for a delivered order."""
+        executed.append({"order_id": order_id, "amount": amount})
+        return f"Refunded {amount} for {order_id}"
+
+    def request_refund(_state: MessagesState):
+        return {"messages": [AIMessage(
+            content="",
+            tool_calls=[{
+                "name": "issue_refund",
+                "args": {"order_id": ORDER_ID, "amount": 250},
+                "id": "quickstart-refund",
+                "type": "tool_call",
+            }],
+        )]}
+
+    graph = StateGraph(MessagesState)
+    graph.add_node("agent", request_refund)
+    graph.add_node("tools", ToolNode([issue_refund]))
+    graph.add_edge(START, "agent")
+    graph.add_edge("agent", "tools")
+    graph.add_edge("tools", END)
+    return graph.compile()
+
+
+def _register(client: httpx.Client, database: Path, agent_name: str) -> tuple[str, str, str]:
+    created = client.post("/api/agents", json={"name": agent_name})
+    created.raise_for_status()
+    identity = created.json()
+    agent_id = identity["agent_id"]
+    api_key = identity["api_key"]
+    source_name = f"quickstart-billing-{agent_id[:8]}"
+
+    source = client.post("/api/sources", json={
+        "name": source_name,
+        "adapter": "sqlite",
+        "config": {"path": str(database)},
+    })
+    source.raise_for_status()
+
+    rules = {"schema_version": 1, "tools": {"issue_refund": {
+        "kind": "consequential",
+        "args": {
+            "order_id": {"ground": {"checks": [{
+                "source": source_name,
+                "query": (
+                    "SELECT customer_id, status FROM orders "
+                    "WHERE order_id = :value"
+                ),
+                "match": [
+                    {"column": "customer_id", "ctx": "customer_id"},
+                    {"column": "status", "value": "delivered"},
+                ],
+            }]}},
+            "amount": {"policy": "amount <= 1000"},
+        },
+        # Runtime values stay local. Activity shows a useful redacted preview;
+        # add a field to report_args only after deciding it is safe to export.
+        "write": {
+            "preview": "Refund order {order_id} for {amount}",
+            "report_args": [],
+        },
+    }}}
+    saved = client.put(f"/api/agents/{agent_id}/rules", json={"rules": rules})
+    saved.raise_for_status()
+    return agent_id, api_key, source_name
+
+
+def run_quickstart(
+    *,
+    endpoint: str = "http://127.0.0.1:8020",
+    database: Path | None = None,
+    agent_name: str = "LangGraph refund quickstart",
+    state_dir: Path | None = None,
+) -> dict:
+    endpoint = endpoint.rstrip("/")
+    database = (database or Path.home() / ".actionrail" / "quickstart-billing.sqlite3").resolve()
+    _build_database(database)
+
+    with httpx.Client(base_url=endpoint, timeout=5.0) as client:
+        agent_id, api_key, source_name = _register(client, database, agent_name)
+        executed = []
+        agent = _build_agent(executed)
+        agent = enforce(
+            agent,
+            agent_id=agent_id,
+            api_key=api_key,
+            endpoint=endpoint,
+            ctx={"customer_id": CALLER_CUSTOMER_ID},
+            state_dir=state_dir,
+        )
+        result = agent.invoke({"messages": [HumanMessage(content="Refund the order")]})
+        blocked_message = str(result["messages"][-1].content)
+
+        if executed:
+            raise RuntimeError("quickstart safety check failed: the refund tool executed")
+        if "BLOCKED" not in blocked_message:
+            raise RuntimeError(f"expected a blocked tool result, received: {blocked_message}")
+        if not close_reporting(agent, timeout=5):
+            raise RuntimeError("the ActionRail reporting queue did not flush cleanly")
+
+        feed = client.get("/api/decisions", params={"agent": agent_id, "page_size": 5})
+        feed.raise_for_status()
+        activity = feed.json().get("decisions", [])
+        if not activity:
+            raise RuntimeError("the blocked decision did not appear in Activity")
+        decision = activity[0]
+        serialized = json.dumps(decision)
+        if ORDER_ID in serialized or "CUSTOMER-OTHER" in serialized:
+            raise RuntimeError("Activity unexpectedly contains private runtime values")
+
+    return {
+        "agent_id": agent_id,
+        "source_name": source_name,
+        "blocked_message": blocked_message,
+        "activity": decision,
+        "executed": executed,
+        "database": str(database),
+        "endpoint": endpoint,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--endpoint", default="http://127.0.0.1:8020")
+    parser.add_argument("--database", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        result = run_quickstart(endpoint=args.endpoint, database=args.database)
+    except (httpx.HTTPError, OSError, RuntimeError) as exc:
+        print(f"ActionRail quickstart failed: {exc}")
+        print(f"Is actionrail-console running at {args.endpoint.rstrip('/')}?")
+        return 1
+
+    print(f"✓ Registered agent {result['agent_id']}")
+    print(f"✓ Connected local source {result['source_name']}")
+    print("✓ ActionRail blocked the cross-customer refund before the tool executed")
+    print("✓ The value-free decision is visible in Activity")
+    print(f"Open {result['endpoint']}/activity")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

actionrail/sdk/__init__.py

@@ -0,0 +1,47 @@
+"""ActionRail runtime SDK."""
+
+from .action_tests import ActionTestError, ActionTestReport, run_action_tests
+from .actions import ActionDefinition
+from .context import current_trusted_context, trusted_context
+from .enforce import enforce
+from .instrument import instrument
+from .lifecycle import close_reporting, flush_reporting, get_runtime_health
+from .report import Reporter
+from .pipeline import Decision
+from .runtime import ActionBlocked, ActionHeld, ActionNotAllowed, ActionRuntime
+from .scanner import (
+    ToolInfo,
+    SurfaceMap,
+    calls_from_messages,
+    enumerate_tools,
+    observe_run,
+    build_surface_map,
+    print_surface_map,
+)
+
+__all__ = [
+    "ActionTestError",
+    "ActionDefinition",
+    "ActionTestReport",
+    "run_action_tests",
+    "instrument",
+    "enforce",
+    "trusted_context",
+    "current_trusted_context",
+    "Reporter",
+    "Decision",
+    "ActionRuntime",
+    "ActionNotAllowed",
+    "ActionBlocked",
+    "ActionHeld",
+    "flush_reporting",
+    "close_reporting",
+    "get_runtime_health",
+    "ToolInfo",
+    "SurfaceMap",
+    "calls_from_messages",
+    "enumerate_tools",
+    "observe_run",
+    "build_surface_map",
+    "print_surface_map",
+]