Metadata-Version: 2.4
Name: playmind
Version: 0.1.1
Summary: PlayMind Labs — Behavioral Stability Intervention SDK for Python (server-side). Score player sessions and detect dysregulated behavior.
License-Expression: MIT
Project-URL: Homepage, https://playmindlabs.com
Project-URL: Repository, https://github.com/shaythegay13/playmind-b2b
Keywords: playmind,behavioral,tilt,igaming,sportsbook,intervention,retention
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Dynamic: license-file

# playmind

**PlayMind Labs — Behavioral Stability Intervention SDK for Python**

[![PyPI version](https://img.shields.io/pypi/v/playmind?color=blue)](https://pypi.org/project/playmind/)

Server-side client for sportsbook operators integrating PlayMind's real-time tilt detection. Score a player's session and determine the right behavioral intervention — no manual API handling required.

## Installation

```bash
pip install playmind
```

## Quick Start

```python
import asyncio
from playmind import PlayMindSDK

pm = PlayMindSDK(
    endpoint="https://api.playmindlabs.com",
    api_key="pm_live_abc123",
)

# Call on every bet placed or significant session event
async def main():
    result = await pm.check({
        "player_id": "sha256:...",           # one-way hash — never send raw IDs
        "session_id": "sess_abc123",
        "baseline": {
            "avg_stake_cents": 1000,
            "avg_bets_per_session": 5,
            "avg_session_duration_minutes": 30,
        },
        "events": [
            {"type": "bet_placed", "timestamp": "2026-01-01T10:00:00Z", "stake_cents": 1000, "odds": -110},
            {"type": "bet_settled", "timestamp": "2026-01-01T10:05:00Z", "outcome": "win"},
        ],
    })

    if result.state != "stable":
        print(f"Intervention: {result.intervention.type} — {result.intervention.message}")

asyncio.run(main())
```

## States

| `state` | Meaning |
|---------|---------|
| `stable` | No action needed |
| `moderate` | Gentle nudge recommended |
| `high_risk` | Cooldown recommended (5 min) |
| `critical` | Session pause recommended (30 min) |

## Configuration

```python
from playmind import PlayMindSDK

pm = PlayMindSDK(
    endpoint="https://api.playmindlabs.com",
    api_key="pm_live_abc123",
    timeout=30,        # request timeout in seconds (default: 30)
    max_retries=3,     # retries on transient errors (default: 3)
)
```

## API Reference

### `PlayMindSDK(endpoint, api_key, timeout=30, max_retries=3)`

Creates a new SDK client. Validates that `api_key` is non-empty.

### `await pm.check(payload) -> TiltScoreResponse`

Scores the session against the PlayMind API.

**Payload fields:**
- `player_id` (required) — Anonymized player identifier
- `session_id` (optional) — Current session identifier
- `baseline` (required) — 7-day behavioral baseline
- `events` (required for operator context) — Array of event objects
- `context` (optional) — `"operator"` (default) or `"bookie"`
- `bets` (required for bookie context) — Array of bet objects

### Error Handling

| Exception | When |
|-----------|------|
| `PlayMindAuthError` | 401 response — invalid API key |
| `PlayMindAPIError` | Non-2xx response |
| `PlayMindTimeoutError` | Request timed out |
| `PlayMindValidationError` | Invalid parameters provided to the SDK |

```python
import asyncio
from playmind import PlayMindSDK, PlayMindAuthError, PlayMindAPIError, PlayMindTimeoutError

pm = PlayMindSDK(endpoint="...", api_key="...")

async def main():
    try:
        result = await pm.check(payload)
    except PlayMindAuthError:
        print("Check your API key")
    except PlayMindTimeoutError:
        print("PlayMind unreachable — fail open, continue without intervention")
    except PlayMindAPIError as e:
        print(f"API error {e.status_code}: {e.body}")

asyncio.run(main())
```

## Async Support

The SDK uses `httpx.AsyncClient` internally and supports the async context manager:

```python
import asyncio
from playmind import PlayMindSDK

async def main():
    async with PlayMindSDK(endpoint="...", api_key="...") as pm:
        result = await pm.check(payload)

asyncio.run(main())
```

## License

MIT
