ahm-shield

Python SDK for Agent Health Monitor — trust-routed agent payment decisions.

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

Install

pip install ahm-shield

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

Quick start

Pattern A — Explicit check

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

@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

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:

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

Partner / white-label support

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

pip install -e ".[dev]"
pytest