axiorank 0.1.0__tar.gz

axiorank-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# dependencies
+node_modules/
+.pnpm-store/
+
+# builds
+.next/
+out/
+dist/
+build/
+
+# env / secrets
+.env
+.env.local
+.env*.local
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# misc
+.DS_Store
+.vercel
+.turbo
+coverage/
+*.tsbuildinfo
+next-env.d.ts
+
+# python (packages/sdk-python)
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info

axiorank-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to the `axiorank` Python SDK are documented here.
+
+## 0.1.0
+
+Initial release. Parity with `@axiorank/sdk` (TypeScript).
+
+- `AxioRank` (sync) and `AsyncAxioRank` (async) clients over `httpx`.
+- `tool_call` / `enforce` — route a tool call through the gateway; `enforce`
+  raises `AxioRankDeniedError` on a `deny` verdict. Transparently waits out a
+  `require_approval` hold and resolves to the final `allow` / `deny`.
+- `verify_card` / `enforce_card` — preflight an external MCP server or A2A
+  agent before trusting it.
+- Typed result dataclasses and the full error taxonomy.
+- LangChain integration (`axiorank[langchain]`): `AxioRankCallbackHandler`,
+  `AxioRankAsyncCallbackHandler`, and `guard_tool`.

axiorank-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AxioRank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

axiorank-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: axiorank
+Version: 0.1.0
+Summary: Official Python SDK for AxioRank — route AI agent tool calls through your agent firewall.
+Project-URL: Homepage, https://axiorank.com
+Project-URL: Documentation, https://app.axiorank.com/docs
+Project-URL: Source, https://github.com/frostyhand/AxioRank
+Project-URL: Issues, https://github.com/frostyhand/AxioRank/issues
+Author: AxioRank
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,axiorank,firewall,gateway,llm,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# axiorank
+
+Official Python SDK for [AxioRank](https://axiorank.com) — route your AI
+agent's tool calls through your agent firewall so policies are enforced, risk is
+scored, and every call is audited.
+
+Parity with the TypeScript [`@axiorank/sdk`](https://www.npmjs.com/package/@axiorank/sdk).
+
+## Install
+
+```bash
+pip install axiorank
+```
+
+## Quickstart (sync)
+
+```python
+import os
+from axiorank import AxioRank
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])  # looks like axr_live_...
+
+# Get the decision and act on it yourself:
+result = axio.tool_call("github.push", {"repo": "myrepo"})
+if result.decision == "deny":
+    print(f"Blocked: {result.reason} (risk {result.risk})")
+else:
+    ...  # proceed with the real tool call
+```
+
+### `enforce()` — guard in one line
+
+```python
+from axiorank import AxioRank, AxioRankDeniedError
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])
+
+try:
+    axio.enforce("aws.delete_bucket", {"name": "prod-data"})
+    delete_bucket("prod-data")  # only runs if AxioRank allowed it
+except AxioRankDeniedError as e:
+    log.warning("AxioRank blocked the call: %s", e.result.reason)
+```
+
+A `require_approval` policy holds the call for a human; `tool_call`/`enforce`
+transparently wait out the hold and resolve to the final `allow`/`deny`.
+
+## Quickstart (async)
+
+```python
+import os
+from axiorank import AsyncAxioRank
+
+async def main():
+    async with AsyncAxioRank(api_key=os.environ["AXIORANK_API_KEY"]) as axio:
+        result = await axio.tool_call("stripe.refund", {"amount": 5000})
+        print(result.decision, result.risk)
+```
+
+## Preflight an external server before trusting it
+
+```python
+result = axio.verify_card(url="https://mcp.acme.com")
+print(result.decision, result.identity.signature_valid, result.protocol)
+
+# Or guard in one line — raises AxioRankCardDeniedError on `deny`:
+axio.enforce_card(url="https://mcp.acme.com")
+```
+
+## LangChain
+
+```bash
+pip install "axiorank[langchain]"
+```
+
+```python
+from axiorank import AxioRank
+from axiorank.integrations.langchain import AxioRankCallbackHandler
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])
+
+# Every tool the agent runs is checked against your policies first; a blocked
+# tool raises and the step fails.
+agent_executor.invoke(
+    {"input": "..."},
+    config={"callbacks": [AxioRankCallbackHandler(axio)]},
+)
+```
+
+Prefer a model-readable refusal over a raised exception? Wrap individual tools:
+
+```python
+from axiorank.integrations.langchain import guard_tool
+
+safe_tool = guard_tool(my_tool, axio, on_deny="return")
+```
+
+## Configuration
+
+| Argument           | Default                       | Notes                                            |
+| ------------------ | ----------------------------- | ------------------------------------------------ |
+| `api_key`          | — (required)                  | Your agent's key (`axr_live_...`).               |
+| `base_url`         | `https://app.axiorank.com`    | Point at your own deployment.                    |
+| `timeout`          | `10.0`                        | Per-request timeout, in seconds.                 |
+| `approval_timeout` | `300.0`                       | Max wait for a human to resolve a hold, seconds. |
+| `client`           | a fresh `httpx.Client`        | Inject your own `httpx` client (tests, proxies). |
+
+## License
+
+MIT

axiorank-0.1.0/README.md

@@ -0,0 +1,110 @@
+# axiorank
+
+Official Python SDK for [AxioRank](https://axiorank.com) — route your AI
+agent's tool calls through your agent firewall so policies are enforced, risk is
+scored, and every call is audited.
+
+Parity with the TypeScript [`@axiorank/sdk`](https://www.npmjs.com/package/@axiorank/sdk).
+
+## Install
+
+```bash
+pip install axiorank
+```
+
+## Quickstart (sync)
+
+```python
+import os
+from axiorank import AxioRank
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])  # looks like axr_live_...
+
+# Get the decision and act on it yourself:
+result = axio.tool_call("github.push", {"repo": "myrepo"})
+if result.decision == "deny":
+    print(f"Blocked: {result.reason} (risk {result.risk})")
+else:
+    ...  # proceed with the real tool call
+```
+
+### `enforce()` — guard in one line
+
+```python
+from axiorank import AxioRank, AxioRankDeniedError
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])
+
+try:
+    axio.enforce("aws.delete_bucket", {"name": "prod-data"})
+    delete_bucket("prod-data")  # only runs if AxioRank allowed it
+except AxioRankDeniedError as e:
+    log.warning("AxioRank blocked the call: %s", e.result.reason)
+```
+
+A `require_approval` policy holds the call for a human; `tool_call`/`enforce`
+transparently wait out the hold and resolve to the final `allow`/`deny`.
+
+## Quickstart (async)
+
+```python
+import os
+from axiorank import AsyncAxioRank
+
+async def main():
+    async with AsyncAxioRank(api_key=os.environ["AXIORANK_API_KEY"]) as axio:
+        result = await axio.tool_call("stripe.refund", {"amount": 5000})
+        print(result.decision, result.risk)
+```
+
+## Preflight an external server before trusting it
+
+```python
+result = axio.verify_card(url="https://mcp.acme.com")
+print(result.decision, result.identity.signature_valid, result.protocol)
+
+# Or guard in one line — raises AxioRankCardDeniedError on `deny`:
+axio.enforce_card(url="https://mcp.acme.com")
+```
+
+## LangChain
+
+```bash
+pip install "axiorank[langchain]"
+```
+
+```python
+from axiorank import AxioRank
+from axiorank.integrations.langchain import AxioRankCallbackHandler
+
+axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])
+
+# Every tool the agent runs is checked against your policies first; a blocked
+# tool raises and the step fails.
+agent_executor.invoke(
+    {"input": "..."},
+    config={"callbacks": [AxioRankCallbackHandler(axio)]},
+)
+```
+
+Prefer a model-readable refusal over a raised exception? Wrap individual tools:
+
+```python
+from axiorank.integrations.langchain import guard_tool
+
+safe_tool = guard_tool(my_tool, axio, on_deny="return")
+```
+
+## Configuration
+
+| Argument           | Default                       | Notes                                            |
+| ------------------ | ----------------------------- | ------------------------------------------------ |
+| `api_key`          | — (required)                  | Your agent's key (`axr_live_...`).               |
+| `base_url`         | `https://app.axiorank.com`    | Point at your own deployment.                    |
+| `timeout`          | `10.0`                        | Per-request timeout, in seconds.                 |
+| `approval_timeout` | `300.0`                       | Max wait for a human to resolve a hold, seconds. |
+| `client`           | a fresh `httpx.Client`        | Inject your own `httpx` client (tests, proxies). |
+
+## License
+
+MIT

axiorank-0.1.0/pyproject.toml

@@ -0,0 +1,74 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "axiorank"
+dynamic = ["version"]
+description = "Official Python SDK for AxioRank — route AI agent tool calls through your agent firewall."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "AxioRank" }]
+keywords = ["axiorank", "ai", "agent", "firewall", "security", "gateway", "llm"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27,<1"]
+
+[project.optional-dependencies]
+# Framework integrations (lazy-imported; install what you use).
+langchain = ["langchain-core>=0.3"]
+# Tooling for local development and CI.
+dev = [
+  "pytest>=8",
+  "pytest-asyncio>=0.23",
+  "mypy>=1.8",
+  "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://axiorank.com"
+Documentation = "https://app.axiorank.com/docs"
+Source = "https://github.com/frostyhand/AxioRank"
+Issues = "https://github.com/frostyhand/AxioRank/issues"
+
+[tool.hatch.version]
+path = "src/axiorank/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/axiorank"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/axiorank", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+# Type-checked at 3.10 (the floor this mypy supports); runtime stays 3.9-safe,
+# enforced by ruff's py39 target + `from __future__ import annotations`.
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/axiorank"]

axiorank-0.1.0/src/axiorank/__init__.py

@@ -0,0 +1,64 @@
+"""AxioRank Python SDK — route AI agent tool calls through your agent firewall.
+
+Parity with ``@axiorank/sdk`` (TypeScript). Sync and async clients::
+
+    from axiorank import AxioRank, AsyncAxioRank
+
+    axio = AxioRank(api_key="axr_live_...")
+    result = axio.tool_call("github.push", {"repo": "myrepo"})
+
+See https://app.axiorank.com/docs for the full guide.
+"""
+
+from __future__ import annotations
+
+from ._async import AsyncAxioRank
+from ._errors import (
+    AxioRankAuthError,
+    AxioRankCardDeniedError,
+    AxioRankDeniedError,
+    AxioRankError,
+    AxioRankRequestError,
+)
+from ._sync import AxioRank
+from ._types import (
+    CardAuth,
+    CardCapabilities,
+    CardCapabilitySample,
+    CardDecision,
+    CardIdentity,
+    CardVerifyResult,
+    Decision,
+    Severity,
+    SignalCategory,
+    ToolCallResult,
+    ToolCallSignal,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # clients
+    "AxioRank",
+    "AsyncAxioRank",
+    # errors
+    "AxioRankError",
+    "AxioRankAuthError",
+    "AxioRankRequestError",
+    "AxioRankDeniedError",
+    "AxioRankCardDeniedError",
+    # result types
+    "ToolCallResult",
+    "ToolCallSignal",
+    "CardVerifyResult",
+    "CardIdentity",
+    "CardCapabilities",
+    "CardCapabilitySample",
+    "CardAuth",
+    # literal aliases
+    "Decision",
+    "CardDecision",
+    "SignalCategory",
+    "Severity",
+]

axiorank-0.1.0/src/axiorank/_async.py

@@ -0,0 +1,187 @@
+"""Asynchronous client over ``httpx.AsyncClient``."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._base import (
+    build_headers,
+    drop_none,
+    normalize_base_url,
+    process_response,
+    resolved_hold,
+)
+from ._constants import (
+    APPROVAL_POLL_BACKOFF,
+    APPROVAL_POLL_TIMEOUT,
+    APPROVALS_PATH,
+    DEFAULT_APPROVAL_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    TOOL_CALL_PATH,
+    VERIFY_CARD_PATH,
+)
+from ._errors import (
+    AxioRankAuthError,
+    AxioRankCardDeniedError,
+    AxioRankDeniedError,
+    AxioRankError,
+    AxioRankRequestError,
+)
+from ._types import CardVerifyResult, ToolCallResult
+
+
+class AsyncAxioRank:
+    """Route AI agent tool calls through your AxioRank gateway (asyncio).
+
+    Example::
+
+        from axiorank import AsyncAxioRank
+
+        async with AsyncAxioRank(api_key=os.environ["AXIORANK_API_KEY"]) as axio:
+            await axio.enforce("aws.delete_bucket", {"name": "prod"})
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        approval_timeout: float | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key:
+            raise AxioRankError("AxioRank: `api_key` is required")
+        self._api_key = api_key
+        self._base_url = normalize_base_url(base_url)
+        self._timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self._approval_timeout = (
+            DEFAULT_APPROVAL_TIMEOUT if approval_timeout is None else approval_timeout
+        )
+        self._headers = build_headers(api_key)
+        self._client = client if client is not None else httpx.AsyncClient()
+        self._owns_client = client is None
+
+    # ── lifecycle ────────────────────────────────────────────────
+    async def aclose(self) -> None:
+        """Close the underlying httpx client (only if the SDK created it)."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncAxioRank:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    # ── outbound tool calls ──────────────────────────────────────
+    async def tool_call(
+        self, tool: str, arguments: Mapping[str, Any] | None = None
+    ) -> ToolCallResult:
+        """Send a tool call to the gateway and return the policy decision.
+
+        Resolves normally for an explicit ``deny``. A ``require_approval`` hold
+        is waited out transparently, so callers only ever see ``allow``/``deny``.
+        """
+        if not tool:
+            raise AxioRankError("AxioRank: `tool` is required")
+        body = await self._post(TOOL_CALL_PATH, {"tool": tool, "arguments": arguments or {}})
+        if body.get("decision") == "hold" and body.get("approvalId"):
+            return await self._wait_for_approval(str(body["approvalId"]), body)
+        return ToolCallResult.from_dict(body)
+
+    async def enforce(
+        self, tool: str, arguments: Mapping[str, Any] | None = None
+    ) -> ToolCallResult:
+        """Like :meth:`tool_call`, but raise :class:`AxioRankDeniedError` on deny."""
+        result = await self.tool_call(tool, arguments)
+        if result.decision == "deny":
+            raise AxioRankDeniedError(result)
+        return result
+
+    # ── preflight (card verification) ────────────────────────────
+    async def verify_card(
+        self,
+        *,
+        url: str | None = None,
+        document: Any | None = None,
+        protocol: str | None = None,
+    ) -> CardVerifyResult:
+        """Preflight an external MCP server / A2A agent before trusting it."""
+        if url is None and document is None:
+            raise AxioRankError("AxioRank: `url` or `document` is required")
+        body = await self._post(
+            VERIFY_CARD_PATH,
+            drop_none({"url": url, "document": document, "protocol": protocol}),
+        )
+        return CardVerifyResult.from_dict(body)
+
+    async def enforce_card(
+        self,
+        *,
+        url: str | None = None,
+        document: Any | None = None,
+        protocol: str | None = None,
+    ) -> CardVerifyResult:
+        """Like :meth:`verify_card`, but raise on a ``deny`` verdict."""
+        result = await self.verify_card(url=url, document=document, protocol=protocol)
+        if result.decision == "deny":
+            raise AxioRankCardDeniedError(result)
+        return result
+
+    # ── internals ────────────────────────────────────────────────
+    async def _post(self, path: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        try:
+            response = await self._client.post(
+                f"{self._base_url}{path}",
+                headers=self._headers,
+                json=payload,
+                timeout=self._timeout,
+            )
+        except httpx.TimeoutException as err:
+            raise AxioRankRequestError(
+                f"AxioRank: request timed out after {self._timeout}s"
+            ) from err
+        except httpx.RequestError as err:
+            raise AxioRankRequestError(f"AxioRank: network error — {err}") from err
+        return process_response(response)
+
+    async def _wait_for_approval(self, approval_id: str, held: Mapping[str, Any]) -> ToolCallResult:
+        """Poll the approvals endpoint until a held call resolves (the gateway
+        long-polls, so this is cheap). After ``approval_timeout`` give up and
+        return ``deny`` — the gateway also auto-denies after its own TTL."""
+        url = f"{self._base_url}{APPROVALS_PATH}/{approval_id}"
+        deadline = time.monotonic() + self._approval_timeout
+
+        while time.monotonic() < deadline:
+            try:
+                response = await self._client.get(
+                    url, headers=self._headers, timeout=APPROVAL_POLL_TIMEOUT
+                )
+                if response.status_code == 401:
+                    raise AxioRankAuthError()
+                status: Any = response.json()
+            except AxioRankAuthError:
+                raise
+            except Exception:
+                # Transient network/timeout while polling — back off and retry.
+                await asyncio.sleep(APPROVAL_POLL_BACKOFF)
+                continue
+
+            decision = status.get("decision") if isinstance(status, dict) else None
+            if decision and decision != "hold":
+                reason = status.get("reason") if isinstance(status, dict) else None
+                return resolved_hold(held, decision, reason)
+
+        return resolved_hold(held, "deny", "AxioRank: approval timed out")

axiorank-0.1.0/src/axiorank/_base.py

@@ -0,0 +1,74 @@
+"""Transport-agnostic helpers shared by the sync and async clients.
+
+The only thing that differs between :class:`AxioRank` and
+:class:`AsyncAxioRank` is *how* a request is awaited — building the request and
+mapping the response are identical (httpx reads the body during the request, so
+``response.json()`` is synchronous on both clients). That shared logic lives
+here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._constants import DEFAULT_BASE_URL
+from ._errors import AxioRankAuthError, AxioRankRequestError
+from ._types import ToolCallResult, _parse_signals
+
+
+def normalize_base_url(base_url: str | None) -> str:
+    """Strip trailing slashes; fall back to the public default."""
+    return (base_url or DEFAULT_BASE_URL).rstrip("/")
+
+
+def build_headers(api_key: str) -> dict[str, str]:
+    return {
+        "content-type": "application/json",
+        "authorization": f"Bearer {api_key}",
+    }
+
+
+def drop_none(payload: dict[str, Any]) -> dict[str, Any]:
+    """Drop ``None`` values so the wire matches JS's ``JSON.stringify`` (which
+    omits ``undefined``) — the gateway's optional fields reject ``null``."""
+    return {k: v for k, v in payload.items() if v is not None}
+
+
+def process_response(response: httpx.Response) -> dict[str, Any]:
+    """Map an httpx response to a parsed body dict, raising the SDK's errors.
+
+    Mirrors the TS client: 401 → :class:`AxioRankAuthError`; any other non-2xx
+    → :class:`AxioRankRequestError` (carrying the server's ``error`` message and
+    the status code); a 2xx with an unparseable body resolves to ``{}``.
+    """
+    if response.status_code == 401:
+        raise AxioRankAuthError()
+
+    body: Any
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+
+    if not response.is_success:
+        message = body.get("error") if isinstance(body, dict) else None
+        if not message:
+            message = f"request failed with status {response.status_code}"
+        raise AxioRankRequestError(f"AxioRank: {message}", response.status_code)
+
+    return body if isinstance(body, dict) else {}
+
+
+def resolved_hold(held: Mapping[str, Any], decision: str, reason: str | None) -> ToolCallResult:
+    """Build the final result for a resolved approval hold, carrying forward the
+    risk / audit-log id / signals from the original held response."""
+    return ToolCallResult(
+        decision=decision,  # type: ignore[arg-type]
+        reason=reason or held.get("reason", ""),
+        risk=int(held.get("risk") or 0),
+        audit_log_id=held.get("auditLogId", ""),
+        signals=_parse_signals(held.get("signals")),
+    )

axiorank-0.1.0/src/axiorank/_constants.py

@@ -0,0 +1,26 @@
+"""Defaults and gateway paths, kept in lockstep with the TypeScript SDK.
+
+Timeouts are expressed in **seconds** (httpx's unit), whereas the TS SDK uses
+milliseconds — the values are otherwise identical.
+"""
+
+DEFAULT_BASE_URL = "https://app.axiorank.com"
+
+# Per-request timeout. TS: DEFAULT_TIMEOUT_MS = 10_000.
+DEFAULT_TIMEOUT = 10.0
+
+# Max time to wait for a human to resolve a `require_approval` hold before the
+# call resolves to `deny`. TS: DEFAULT_APPROVAL_TIMEOUT_MS = 300_000.
+DEFAULT_APPROVAL_TIMEOUT = 300.0
+
+# Per-poll timeout while waiting on an approval. MUST stay larger than the
+# gateway's server-side long-poll window (~8s) — and is deliberately NOT the
+# 10s request timeout, or a held call would abort mid-long-poll. TS: 20_000.
+APPROVAL_POLL_TIMEOUT = 20.0
+
+# Back-off after a transient error while polling an approval. TS: delay(1_000).
+APPROVAL_POLL_BACKOFF = 1.0
+
+TOOL_CALL_PATH = "/api/gateway/tool-call"
+VERIFY_CARD_PATH = "/api/gateway/verify-card"
+APPROVALS_PATH = "/api/gateway/approvals"

axiorank-0.1.0/src/axiorank/_errors.py

@@ -0,0 +1,43 @@
+"""Error taxonomy — a 1:1 port of `@axiorank/sdk`'s `errors.ts`."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ._types import CardVerifyResult, ToolCallResult
+
+
+class AxioRankError(Exception):
+    """Base class for all errors raised by the SDK."""
+
+
+class AxioRankAuthError(AxioRankError):
+    """Raised when the API key is missing, invalid, or revoked (HTTP 401)."""
+
+    def __init__(self, message: str = "Invalid or missing AxioRank API key") -> None:
+        super().__init__(message)
+
+
+class AxioRankRequestError(AxioRankError):
+    """Raised for malformed requests, timeouts, and other non-2xx responses."""
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status: int | None = status
+
+
+class AxioRankDeniedError(AxioRankError):
+    """Raised by :meth:`AxioRank.enforce` when the gateway denies the call."""
+
+    def __init__(self, result: ToolCallResult) -> None:
+        super().__init__(f"AxioRank denied tool call: {result.reason}")
+        self.result: ToolCallResult = result
+
+
+class AxioRankCardDeniedError(AxioRankError):
+    """Raised by :meth:`AxioRank.enforce_card` when the verdict is ``deny``."""
+
+    def __init__(self, result: CardVerifyResult) -> None:
+        super().__init__(f"AxioRank denied card preflight: {result.reason}")
+        self.result: CardVerifyResult = result

axiorank-0.1.0/src/axiorank/_sync.py

@@ -0,0 +1,184 @@
+"""Synchronous client over ``httpx.Client``."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from ._base import (
+    build_headers,
+    drop_none,
+    normalize_base_url,
+    process_response,
+    resolved_hold,
+)
+from ._constants import (
+    APPROVAL_POLL_BACKOFF,
+    APPROVAL_POLL_TIMEOUT,
+    APPROVALS_PATH,
+    DEFAULT_APPROVAL_TIMEOUT,
+    DEFAULT_TIMEOUT,
+    TOOL_CALL_PATH,
+    VERIFY_CARD_PATH,
+)
+from ._errors import (
+    AxioRankAuthError,
+    AxioRankCardDeniedError,
+    AxioRankDeniedError,
+    AxioRankError,
+    AxioRankRequestError,
+)
+from ._types import CardVerifyResult, ToolCallResult
+
+
+class AxioRank:
+    """Route AI agent tool calls through your AxioRank gateway (synchronous).
+
+    Example::
+
+        from axiorank import AxioRank
+
+        axio = AxioRank(api_key=os.environ["AXIORANK_API_KEY"])
+        result = axio.tool_call("github.push", {"repo": "myrepo"})
+        if result.decision == "deny":
+            ...
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        approval_timeout: float | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key:
+            raise AxioRankError("AxioRank: `api_key` is required")
+        self._api_key = api_key
+        self._base_url = normalize_base_url(base_url)
+        self._timeout = DEFAULT_TIMEOUT if timeout is None else timeout
+        self._approval_timeout = (
+            DEFAULT_APPROVAL_TIMEOUT if approval_timeout is None else approval_timeout
+        )
+        self._headers = build_headers(api_key)
+        self._client = client if client is not None else httpx.Client()
+        self._owns_client = client is None
+
+    # ── lifecycle ────────────────────────────────────────────────
+    def close(self) -> None:
+        """Close the underlying httpx client (only if the SDK created it)."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> AxioRank:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    # ── outbound tool calls ──────────────────────────────────────
+    def tool_call(self, tool: str, arguments: Mapping[str, Any] | None = None) -> ToolCallResult:
+        """Send a tool call to the gateway and return the policy decision.
+
+        Resolves normally for an explicit ``deny``. A ``require_approval`` hold
+        is waited out transparently, so callers only ever see ``allow``/``deny``.
+        """
+        if not tool:
+            raise AxioRankError("AxioRank: `tool` is required")
+        body = self._post(TOOL_CALL_PATH, {"tool": tool, "arguments": arguments or {}})
+        if body.get("decision") == "hold" and body.get("approvalId"):
+            return self._wait_for_approval(str(body["approvalId"]), body)
+        return ToolCallResult.from_dict(body)
+
+    def enforce(self, tool: str, arguments: Mapping[str, Any] | None = None) -> ToolCallResult:
+        """Like :meth:`tool_call`, but raise :class:`AxioRankDeniedError` on deny."""
+        result = self.tool_call(tool, arguments)
+        if result.decision == "deny":
+            raise AxioRankDeniedError(result)
+        return result
+
+    # ── preflight (card verification) ────────────────────────────
+    def verify_card(
+        self,
+        *,
+        url: str | None = None,
+        document: Any | None = None,
+        protocol: str | None = None,
+    ) -> CardVerifyResult:
+        """Preflight an external MCP server / A2A agent before trusting it."""
+        if url is None and document is None:
+            raise AxioRankError("AxioRank: `url` or `document` is required")
+        body = self._post(
+            VERIFY_CARD_PATH,
+            drop_none({"url": url, "document": document, "protocol": protocol}),
+        )
+        return CardVerifyResult.from_dict(body)
+
+    def enforce_card(
+        self,
+        *,
+        url: str | None = None,
+        document: Any | None = None,
+        protocol: str | None = None,
+    ) -> CardVerifyResult:
+        """Like :meth:`verify_card`, but raise on a ``deny`` verdict."""
+        result = self.verify_card(url=url, document=document, protocol=protocol)
+        if result.decision == "deny":
+            raise AxioRankCardDeniedError(result)
+        return result
+
+    # ── internals ────────────────────────────────────────────────
+    def _post(self, path: str, payload: Mapping[str, Any]) -> dict[str, Any]:
+        try:
+            response = self._client.post(
+                f"{self._base_url}{path}",
+                headers=self._headers,
+                json=payload,
+                timeout=self._timeout,
+            )
+        except httpx.TimeoutException as err:
+            raise AxioRankRequestError(
+                f"AxioRank: request timed out after {self._timeout}s"
+            ) from err
+        except httpx.RequestError as err:
+            raise AxioRankRequestError(f"AxioRank: network error — {err}") from err
+        return process_response(response)
+
+    def _wait_for_approval(self, approval_id: str, held: Mapping[str, Any]) -> ToolCallResult:
+        """Poll the approvals endpoint until a held call resolves (the gateway
+        long-polls, so this is cheap). After ``approval_timeout`` give up and
+        return ``deny`` — the gateway also auto-denies after its own TTL."""
+        url = f"{self._base_url}{APPROVALS_PATH}/{approval_id}"
+        deadline = time.monotonic() + self._approval_timeout
+
+        while time.monotonic() < deadline:
+            try:
+                response = self._client.get(
+                    url, headers=self._headers, timeout=APPROVAL_POLL_TIMEOUT
+                )
+                if response.status_code == 401:
+                    raise AxioRankAuthError()
+                status: Any = response.json()
+            except AxioRankAuthError:
+                raise
+            except Exception:
+                # Transient network/timeout while polling — back off and retry.
+                time.sleep(APPROVAL_POLL_BACKOFF)
+                continue
+
+            decision = status.get("decision") if isinstance(status, dict) else None
+            if decision and decision != "hold":
+                reason = status.get("reason") if isinstance(status, dict) else None
+                return resolved_hold(held, decision, reason)
+
+        return resolved_hold(held, "deny", "AxioRank: approval timed out")

axiorank-0.1.0/src/axiorank/_types.py

@@ -0,0 +1,175 @@
+"""Result types — frozen dataclasses mirroring `@axiorank/sdk`'s `types.ts`.
+
+Wire payloads use camelCase keys (``auditLogId``); the dataclasses expose
+snake_case attributes (``audit_log_id``). ``from_dict`` bridges the two and is
+deliberately tolerant of missing / unknown fields so a newer gateway never
+breaks an older SDK.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal
+
+# Policy decision the gateway surfaces to a caller. (`hold` is internal — the
+# client waits it out and only ever returns `allow`/`deny`.)
+Decision = Literal["allow", "deny"]
+# Three-way verdict for a card preflight. Precedence: deny > review > allow.
+CardDecision = Literal["allow", "review", "deny"]
+Severity = Literal["low", "medium", "high", "critical"]
+# Category of a content-inspection finding. The last two are inbound-only.
+SignalCategory = Literal[
+    "secret",
+    "pii",
+    "destructive",
+    "injection",
+    "egress",
+    "bot_spoof",
+    "rate_abuse",
+]
+
+
+@dataclass(frozen=True)
+class ToolCallSignal:
+    """A redacted content-inspection finding on a tool-call payload."""
+
+    detector: str
+    category: str
+    severity: str
+    label: str
+    location: str
+    evidence: str
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> ToolCallSignal:
+        return cls(
+            detector=d.get("detector", ""),
+            category=d.get("category", ""),
+            severity=d.get("severity", ""),
+            label=d.get("label", ""),
+            location=d.get("location", ""),
+            evidence=d.get("evidence", ""),
+        )
+
+
+def _parse_signals(raw: Any) -> list[ToolCallSignal] | None:
+    if not raw:
+        return None
+    return [ToolCallSignal.from_dict(s) for s in raw]
+
+
+@dataclass(frozen=True)
+class ToolCallResult:
+    """Outcome of routing a tool call through the gateway."""
+
+    decision: Decision
+    reason: str
+    risk: int
+    audit_log_id: str
+    signals: list[ToolCallSignal] | None = None
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> ToolCallResult:
+        return cls(
+            decision=d.get("decision", "deny"),
+            reason=d.get("reason", ""),
+            risk=int(d.get("risk") or 0),
+            audit_log_id=d.get("auditLogId", ""),
+            signals=_parse_signals(d.get("signals")),
+        )
+
+
+@dataclass(frozen=True)
+class CardIdentity:
+    name: str | None
+    provider: str | None
+    signed: bool
+    # True = verified · False = forged · None = unsigned / key unresolvable.
+    signature_valid: bool | None
+    key_source: str  # "embedded" | "jwks" | "none"
+    key_domain_bound: bool
+    key_id: str | None
+    source_url: str
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> CardIdentity:
+        return cls(
+            name=d.get("name"),
+            provider=d.get("provider"),
+            signed=bool(d.get("signed", False)),
+            signature_valid=d.get("signatureValid"),
+            key_source=d.get("keySource", "none"),
+            key_domain_bound=bool(d.get("keyDomainBound", False)),
+            key_id=d.get("keyId"),
+            source_url=d.get("sourceUrl", ""),
+        )
+
+
+@dataclass(frozen=True)
+class CardCapabilitySample:
+    kind: str
+    name: str
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> CardCapabilitySample:
+        return cls(kind=d.get("kind", ""), name=d.get("name", ""))
+
+
+@dataclass(frozen=True)
+class CardCapabilities:
+    count: int
+    sample: list[CardCapabilitySample]
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> CardCapabilities:
+        return cls(
+            count=int(d.get("count") or 0),
+            sample=[CardCapabilitySample.from_dict(s) for s in (d.get("sample") or [])],
+        )
+
+
+@dataclass(frozen=True)
+class CardAuth:
+    schemes: list[str]
+    protected_resource: bool
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> CardAuth:
+        return cls(
+            schemes=list(d.get("schemes") or []),
+            protected_resource=bool(d.get("protectedResource", False)),
+        )
+
+
+@dataclass(frozen=True)
+class CardVerifyResult:
+    """Outcome of preflighting an external MCP server / A2A agent."""
+
+    decision: CardDecision
+    reason: str
+    risk: int
+    # The wire carries ~20 protocol ids (a2a, mcp, oauth, did, x402, …); typed
+    # as a plain ``str`` so the SDK never lags the gateway's protocol list.
+    protocol: str
+    identity: CardIdentity
+    capabilities: CardCapabilities
+    auth: CardAuth
+    warnings: list[str]
+    card_id: str
+    signals: list[ToolCallSignal] | None = None
+
+    @classmethod
+    def from_dict(cls, d: Mapping[str, Any]) -> CardVerifyResult:
+        return cls(
+            decision=d.get("decision", "deny"),
+            reason=d.get("reason", ""),
+            risk=int(d.get("risk") or 0),
+            protocol=d.get("protocol", ""),
+            identity=CardIdentity.from_dict(d.get("identity") or {}),
+            capabilities=CardCapabilities.from_dict(d.get("capabilities") or {}),
+            auth=CardAuth.from_dict(d.get("auth") or {}),
+            warnings=list(d.get("warnings") or []),
+            card_id=d.get("cardId", ""),
+            signals=_parse_signals(d.get("signals")),
+        )

axiorank-0.1.0/src/axiorank/integrations/__init__.py

@@ -0,0 +1,6 @@
+"""Framework integrations for the AxioRank SDK.
+
+Each integration lives in its own module and lazily imports the framework it
+wraps, so installing ``axiorank`` never pulls in LangChain, OpenAI, etc. Install
+only what you use, e.g. ``pip install axiorank[langchain]``.
+"""

axiorank-0.1.0/src/axiorank/integrations/langchain.py

@@ -0,0 +1,147 @@
+"""LangChain integration for AxioRank.
+
+Two ways to put your agent's tools behind the gateway:
+
+* :class:`AxioRankCallbackHandler` / :class:`AxioRankAsyncCallbackHandler` —
+  zero-touch. Attach the handler and *every* tool the agent runs is checked
+  first; a denied call raises and the step fails.
+* :func:`guard_tool` — wrap a single tool. A denied call can either raise or
+  return a model-readable refusal (``on_deny="return"``) so the agent recovers.
+
+Requires ``langchain-core`` (``pip install 'axiorank[langchain]'``).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+try:
+    from langchain_core.callbacks import AsyncCallbackHandler, BaseCallbackHandler
+    from langchain_core.tools import BaseTool, StructuredTool
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(
+        "The AxioRank LangChain integration requires `langchain-core`. "
+        "Install it with: pip install 'axiorank[langchain]'"
+    ) from exc
+
+from .._async import AsyncAxioRank
+from .._errors import AxioRankDeniedError
+from .._sync import AxioRank
+from .._types import ToolCallResult
+
+
+def _extract_call(serialized: Any, input_str: str, inputs: Any) -> tuple[str, dict[str, Any]]:
+    """Pull the tool name and an arguments dict out of a callback's payload."""
+    name = ""
+    if isinstance(serialized, dict):
+        raw_name = serialized.get("name")
+        if not raw_name:
+            ident = serialized.get("id")
+            if isinstance(ident, list) and ident:
+                raw_name = ident[-1]
+        name = str(raw_name or "")
+
+    if isinstance(inputs, dict):
+        return name, dict(inputs)
+
+    # Older LangChain passes only the stringified input — best-effort decode.
+    try:
+        parsed = json.loads(input_str)
+    except Exception:
+        return name, {"input": input_str}
+    return name, parsed if isinstance(parsed, dict) else {"input": parsed}
+
+
+def _denied_message(name: str, result: ToolCallResult) -> str:
+    return f"AxioRank blocked the tool call `{name}`: {result.reason} (risk {result.risk})."
+
+
+class AxioRankCallbackHandler(BaseCallbackHandler):
+    """Check every tool call against AxioRank before it runs (synchronous).
+
+    Attach to an agent run; a ``deny`` verdict raises
+    :class:`~axiorank.AxioRankDeniedError`, aborting the tool step.
+    """
+
+    # Propagate our exception instead of letting LangChain swallow it.
+    raise_error: bool = True
+
+    def __init__(self, client: AxioRank) -> None:
+        self._client = client
+
+    def on_tool_start(self, serialized: dict[str, Any], input_str: str, **kwargs: Any) -> None:
+        name, args = _extract_call(serialized, input_str, kwargs.get("inputs"))
+        result = self._client.tool_call(name, args)
+        if result.decision == "deny":
+            raise AxioRankDeniedError(result)
+
+
+class AxioRankAsyncCallbackHandler(AsyncCallbackHandler):
+    """Async counterpart of :class:`AxioRankCallbackHandler`."""
+
+    raise_error: bool = True
+
+    def __init__(self, client: AsyncAxioRank) -> None:
+        self._client = client
+
+    async def on_tool_start(
+        self, serialized: dict[str, Any], input_str: str, **kwargs: Any
+    ) -> None:
+        name, args = _extract_call(serialized, input_str, kwargs.get("inputs"))
+        result = await self._client.tool_call(name, args)
+        if result.decision == "deny":
+            raise AxioRankDeniedError(result)
+
+
+def guard_tool(
+    tool: BaseTool,
+    client: AxioRank | None = None,
+    *,
+    async_client: AsyncAxioRank | None = None,
+    on_deny: str = "raise",
+) -> StructuredTool:
+    """Wrap ``tool`` so its arguments are checked by AxioRank before it runs.
+
+    Provide ``client`` (sync), ``async_client`` (async), or both. On a ``deny``:
+    ``on_deny="raise"`` raises :class:`~axiorank.AxioRankDeniedError`;
+    ``on_deny="return"`` returns a short, model-readable refusal string instead.
+    """
+    if client is None and async_client is None:
+        raise ValueError("guard_tool: provide `client` and/or `async_client`")
+    if on_deny not in ("raise", "return"):
+        raise ValueError("guard_tool: `on_deny` must be 'raise' or 'return'")
+
+    name = tool.name
+    func: Callable[..., Any] | None = None
+    coroutine: Callable[..., Any] | None = None
+
+    if client is not None:
+        sync_client = client
+
+        def func(**kwargs: Any) -> Any:
+            result = sync_client.tool_call(name, kwargs)
+            if result.decision == "deny":
+                if on_deny == "return":
+                    return _denied_message(name, result)
+                raise AxioRankDeniedError(result)
+            return tool.run(kwargs)
+
+    if async_client is not None:
+        a_client = async_client
+
+        async def coroutine(**kwargs: Any) -> Any:
+            result = await a_client.tool_call(name, kwargs)
+            if result.decision == "deny":
+                if on_deny == "return":
+                    return _denied_message(name, result)
+                raise AxioRankDeniedError(result)
+            return await tool.arun(kwargs)
+
+    return StructuredTool.from_function(
+        func=func,
+        coroutine=coroutine,
+        name=name,
+        description=tool.description,
+        args_schema=tool.args_schema,
+    )