Metadata-Version: 2.5
Name: parallax-fraud-sdk
Version: 0.1.0
Summary: Python client for the Parallax intent-inference fraud detection gateway
Project-URL: Homepage, https://github.com/Koded0214H/parallax
Project-URL: Documentation, https://github.com/Koded0214H/parallax/blob/main/docs/report.md
Author: Parallax (Team NaN)
License: MIT
Keywords: account-takeover,fintech,fraud,risk,sdk
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Description-Content-Type: text/markdown

# parallax-fraud-sdk

Python client for the [Parallax](../../docs/report.md) 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`](../../docs/detection_architecture.md) for
why that separation is deliberate.

## Install

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

```python
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`](examples/quickstart.py) for a full walkthrough,
including handling an intent probe.

## API surface

| Method | Gateway endpoint | Purpose |
|---|---|---|
| `send_event(...)` | `POST /v1/events` | Submit one observed session/transaction event |
| `get_intent(session_id)` | `GET /v1/sessions/{id}/intent` | Current intent distribution & policy decision |
| `get_events(session_id)` | `GET /v1/sessions/{id}/events` | Raw event trajectory for a session |
| `submit_probe_response(session_id, text)` | `POST /v1/sessions/{id}/probe` | Answer an active intent probe |
| `list_sessions(limit=50)` | `GET /v1/sessions` | Recent sessions with last-known decision |
| `get_baseline(user_id)` | `GET /v1/baselines/{id}` | A customer's behavioural baseline |
| `list_scenarios()` / `run_scenario(id)` | `GET/POST /v1/scenarios...` | Canned demo scenarios |
| `stream_events(session_id=None)` | `GET /v1/stream` (SSE) | Live event feed, blocking generator |
| `health()` / `metrics()` | `GET /healthz`, `GET /v1/metrics` | Gateway liveness & counters |
| `reset()` | `POST /v1/reset` | Clear demo state — **not for production gateways** |

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

## Development

```bash
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`](../../docs/technical-writeup.md) for what is and
isn't production-hardened yet.
