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
