Metadata-Version: 2.4
Name: ahm-shield
Version: 0.1.0
Summary: Python SDK for Agent Health Monitor — trust-routed agent payment decisions
Project-URL: Homepage, https://github.com/moonshot-cyber/ahm-shield
Project-URL: Documentation, https://agenthealthmonitor.xyz/docs
Author: Moonshot Cyber
License-Expression: MIT
Keywords: agent,escrow,health,monitor,payments,trust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: fastapi>=0.100; extra == 'dev'
Requires-Dist: httpx[http2]>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100; extra == 'fastapi'
Description-Content-Type: text/markdown

# ahm-shield

Python SDK for [Agent Health Monitor](https://agenthealthmonitor.xyz) — trust-routed agent payment decisions.

Sits in front of agent payment flows and automates trust-routed decisions using AHM's scoring API.

## Install

```bash
pip install ahm-shield

# with FastAPI middleware support
pip install ahm-shield[fastapi]
```

## Quick start

### Pattern A — Explicit check

```python
from ahm_shield import AHMShield

shield = AHMShield(api_key="ahm_live_...")
result = shield.route("0xABC...")

result.action      # "instant_settle" | "escrow" | "reject"
result.grade       # "A"–"F"
result.score       # 0–100
result.confidence  # 0.0–1.0
result.stale       # bool
```

### Pattern B — Guard decorator

```python
@shield.guard(on_reject="raise", on_escrow="flag")
def process_payment(address: str, amount: float):
    ...
```

- `on_reject="raise"` — raises `AHMRejectError` (default)
- `on_reject="return"` — returns `None` without calling the function
- `on_escrow="flag"` — proceeds, sets `ahm_decision` context var (default)
- `on_escrow="raise"` — raises `AHMEscrowFlag`
- `on_escrow="allow"` — proceeds silently

Async functions are auto-detected and handled correctly.

### Pattern C — FastAPI middleware

```python
from ahm_shield.middleware import AHMShieldMiddleware

app.add_middleware(
    AHMShieldMiddleware,
    api_key="ahm_live_...",
    address_extractor=lambda r: r.headers.get("x-agent-address"),
)
```

Rejected addresses receive a `403`. Escrow-flagged requests pass through with `x-ahm-action: escrow` response headers. The `RoutingDecision` is available at `request.state.ahm_decision`.

## Async support

Every method has a sync and async variant:

```python
result = shield.route("0xABC...")          # sync
result = await shield.aroute("0xABC...")   # async
```

## Partner / white-label support

```python
shield = AHMShield(api_key="ahm_live_...", partner_id="partner_42")
```

The `partner_id` is sent as an `x-partner-id` header on every request for backend attribution.

## Exceptions

| Exception | When |
|---|---|
| `AHMRejectError` | Address scored as reject |
| `AHMEscrowFlag` | Address routed to escrow (when `on_escrow="raise"`) |
| `AHMAuthError` | Invalid or missing API key (401/403) |
| `AHMConnectionError` | API unreachable or timed out |

All inherit from `AHMError`.

## Development

```bash
pip install -e ".[dev]"
pytest
```
