playmind 0.1.0

PlayMind Labs — Behavioral Stability Intervention SDK for Python (server-side). Score player sessions and detect dysregulated behavior.

playmind

PlayMind Labs — Behavioral Stability Intervention SDK for Python

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

pip install playmind

Quick Start

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

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

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:

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