signalgate 0.1.0

SignalGate antifraud backend SDK for Python — thin HTTP forwarder to api.signalgate.ai

signalgate — Python backend SDK

Thin HTTP forwarder for SignalGate antifraud. Tenants embed this in their backend to call /v0/check (synchronous verdict) and /v0/log (async analytics). The SDK does no crypto — the opaque encrypted payload comes from @signalgate/frontend-js-sdk.

Install

pip install signalgate

For local development against an unpublished checkout:

pip install -e /path/to/backend-python-sdk

Quickstart

from signalgate import Client, Event, EncryptedPayload

client = Client(api_key="<your-jwt>")

event = Event(
    user_id="u_123",
    ip=request.headers.get("X-Forwarded-For", request.remote_addr),
    method="login",
    timestamp="2026-04-01T13:08:50+00:00",
    payload=EncryptedPayload(**frontend_payload_dict),  # verbatim from the browser
    custom={"plan": "pro"},
)

verdict = client.check(event)
if verdict.action == "block":
    raise PermissionError("blocked by SignalGate")

client.log(event)  # fire-and-forget analytics

At process shutdown:

client.close()  # drains the log queue within 5 × log_timeout_ms

Or use it as a context manager:

with Client(api_key="...") as client:
    client.check(event)

Configuration

All defaults match the spec. Override selectively:

Client(
    api_key="...",
    check_timeout_ms=3000,
    log_timeout_ms=1000,
    log_queue_capacity=10000,
    log_max_retries=3,
    fail_open=True,   # default: on timeout/5xx, check() returns allow
)

Error handling

check() raises on 4xx (tenant bug — bad JWT, malformed event). With fail_open=True (default), timeouts / network errors / 5xx return a synthesized CheckResult(action="allow", failed_open=True).

from signalgate import ServerError, TimeoutError, NetworkError

try:
    result = client.check(event)
except ServerError as e:
    # e.status_code, e.code, e.message, e.request_id, e.details
    ...

log() never raises. Failures are counted in client.metrics.

Metrics

client.metrics.get("check_total")
client.metrics.get("check_failed_open_total")
client.metrics.get("log_dropped_total", reason="queue_full")
client.metrics.snapshot()  # all counters

See the spec §7 for the full counter list.

License

Licensed under the Apache License, Version 2.0.

Links

• Homepage: https://signalgate.ai
• Documentation: https://signalgate.ai/docs/python