parallax-fraud-sdk

Python client for the Parallax intent-inference fraud detection gateway. A fintech backend uses this package to stream session and transaction events to a running Parallax gateway and read back the intent-hypothesis decision — ALLOW, PROBE, VERIFY, BLOCK, or ESCALATE — in real time.

This is a thin client. It formats requests and parses responses; it does not run the detection model, compute features, or make policy decisions itself. Those live in the Go gateway (backend/) — see docs/detection_architecture.md for why that separation is deliberate.

Install

pip install -e sdk/python           # from the repo root, during development

Once published: pip install parallax-fraud-sdk (the import name stays parallax_sdk).

Usage

from parallax_sdk import ParallaxClient, EventType, Action

client = ParallaxClient("https://your-gateway.example.com")

client.send_event(session_id="s1", user_id="cust-42", type=EventType.LOGIN)
client.send_event(
    session_id="s1",
    user_id="cust-42",
    type=EventType.TRANSFER_STARTED,
    metadata={"amount": 350000, "beneficiary_id": "ben-9"},
)

decision = client.get_intent("s1")
print(decision.action, decision.dominant_intent, decision.hypotheses)

if decision.action == Action.PROBE.value and decision.probe:
    updated = client.submit_probe_response("s1", "Bank told me to move this.")

See examples/quickstart.py for a full walkthrough, including handling an intent probe.

API surface

All methods raise ParallaxAPIError (non-2xx response) or ParallaxConnectionError (network failure) — both subclass ParallaxError.

Development

pip install -e ".[dev]"
pytest

Status

Built for the ICSC 2026 Universities Hackathon (Track A1). No authentication scheme is enforced by the reference gateway beyond an optional bearer token passed through ParallaxClient(..., api_key=...) — see docs/technical-writeup.md for what is and isn't production-hardened yet.