Metadata-Version: 2.4
Name: alogram-payrisk
Version: 0.1.6
Summary: The official Alogram Payrisk 'Smart' SDK for Python. Features built-in resiliency, ergonomic risk intelligence, and automated identity management.
Author-email: "Alogram Inc." <support@alogram.ai>
License: Apache-2.0
Project-URL: Homepage, https://www.alogram.ai
Project-URL: Repository, https://github.com/alogram/alogram-python
Project-URL: Documentation, https://developers.alogram.ai
Project-URL: Bug Tracker, https://github.com/alogram/alogram-python/issues
Keywords: alogram,payrisk,fraud,risk,payments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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 :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: urllib3>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: tenacity>=8.0.0
Requires-Dist: lazy-imports>=0.3.1
Requires-Dist: python-dateutil>=2.8.2
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api; extra == "telemetry"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: responses; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: opentelemetry-api; extra == "dev"
Dynamic: license-file

# Alogram PayRisk SDK for Python

[![PyPI version](https://badge.fury.io/py/alogram-payrisk.svg)](https://badge.fury.io/py/alogram-payrisk)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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

```bash
pip install alogram-payrisk
```

## 🛠️ Quick Start

### Evaluate Risk (Server-Side)

```python
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="customer@example.com")
))

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

---

## 🛡️ Error Handling

The SDK provides specific exceptions for robust error state management:

```python
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](https://dashboard.alogram.ai/keys).

| 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`.

```python
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:
```python
client = AlogramRiskClient(
    api_key="sk_test_...",
    base_url="https://api-sandbox.alogram.ai"
)
```

### Local Emulator
For hermetic local testing, run the **Alogram Local Emulator**:
```bash
docker run -p 8080:8080 alogram/payrisk-emulator
```
Point your client to the local instance:
```python
client = AlogramRiskClient(base_url="http://localhost:8080", api_key="test")
```

---

## 📚 Documentation

For full API reference, visit [docs.alogram.ai](https://docs.alogram.ai).

## ⚖️ License

Apache License 2.0. See [LICENSE](LICENSE) for details.
