alogram-payrisk 0.1.6

The official Alogram Payrisk 'Smart' SDK for Python. Features built-in resiliency, ergonomic risk intelligence, and automated identity management.

Alogram PayRisk SDK for Python

The official Alogram PayRisk 'Smart' SDK for Python. Built for modern financial systems that require high resiliency, ergonomic risk intelligence, and automated identity management.

🚀 Features

• 🏢 Smart Client Architecture: Specialized clients for server-side (AlogramRiskClient) and public-facing (AlogramPublicClient) environments.
• 🛡️ Automated Identity: Injects x-api-key, Authorization, and tenant headers automatically.
• 🔄 Built-in Resiliency: Transparent exponential backoff and jittered retries powered by tenacity.
• 🕵️ OpenTelemetry Ready: Native tracing support for deep observability into risk decisions.
• 🧩 Type Safe: Built with Pydantic v2 and full PEP 561 compliance (py.typed).

📦 Installation

pip install alogram-payrisk

🛠️ Quick Start

Evaluate Risk (Server-Side)

from alogram_payrisk import AlogramRiskClient
from alogram_payrisk.models import CheckRequest, Purchase, Identity

# Initialize the smart client
client = AlogramRiskClient(
    api_key="sk_live_your_secret_key",
    tenant_id="tenant_123"
)

# Perform the check with automatic retries and tracing
decision = client.check_risk(CheckRequest(
    purchase=Purchase(amount=99.99, currency="USD"),
    identity=Identity(email="[e-mail]")
))

print(f"Risk Decision: {decision.decision}")

---

🛡️ Error Handling

The SDK provides specific exceptions for robust error state management:

from alogram_payrisk.exceptions import RateLimitError, ValidationError, AlogramError

try:
    decision = client.check_risk(request)
except RateLimitError:
    # 🔄 Standard exponential backoff is handled by the SDK
    pass
except ValidationError as e:
    # ❌ Check e.body for specific field validation errors
    print(f"Invalid request: {e}")
except AlogramError as e:
    # 🚨 Generic fallback for other API issues
    print(f"API Error: {e.status_code}")

🔑 Authentication & Keys

To use the Alogram SDK, you need API keys from the Alogram Dashboard.

Key Type	Prefix	Client	Use Case
Secret Key	sk_live_...	AlogramRiskClient	Server-side risk checks. Never expose.
Publishable Key	pk_live_...	AlogramPublicClient	Frontend signals & browser ingestion.

🤖 For AI Agents (Integration Context)

If you are using an AI agent (like ChatGPT, Claude, or Gemini) to help with your integration, provide it with the following context:

"I am integrating the Alogram PayRisk Python SDK. I need to implement a risk check during my checkout endpoint. Use the AlogramRiskClient, handle RateLimitError gracefully, and ensure you use the idempotency_key from my transaction ID."

---

🧪 Local Testing & Mocking

For fast unit tests without network dependencies, use the built-in MockRiskClient.

from alogram_payrisk.testing import MockRiskClient

mock = MockRiskClient()
mock.queue_decision("decline", score=0.95, reason="high_risk_ip")

# Your app code uses the mock as if it were a real client
decision = my_app.process_checkout(mock)
assert decision.decision == "decline"

🏗️ Environment Testing

Alogram Sandbox

For safe integration testing without impacting production data, point your client to the Sandbox environment:

client = AlogramRiskClient(
    api_key="sk_test_...",
    base_url="https://api-sandbox.alogram.ai"
)

Local Emulator

For hermetic local testing, run the Alogram Local Emulator:

docker run -p 8080:8080 alogram/payrisk-emulator

Point your client to the local instance:

client = AlogramRiskClient(base_url="http://localhost:8080", api_key="test")

---

📚 Documentation

For full API reference, visit docs.alogram.ai.

⚖️ License

Apache License 2.0. See LICENSE for details.