ShreAI Python SDK

POS / BOS event SDK for Python. Single file, stdlib only — no dependencies. Same wire contract as the JavaScript and Swift v2 SDKs.

from shreai import ShreAI

sa = ShreAI(
    endpoint="https://apiauth.shre.ai",
    events_endpoint="https://events.shre.ai",
    tenant_id="merchant_123",
    app="rapid_pos",
    mode="read_only",
)
sa.start()

sa.track("price_updated", entity_type="item", entity_id="UPC_012345678905",
         metadata={"old": 10.49, "new": 10.99})

Install

From PyPI (when published)

pip install shreai

From git

pip install git+https://github.com/Shreai/sdk-python.git@v2.0.0

Single-file copy

curl -O https://raw.githubusercontent.com/Shreai/sdk-python/main/shreai.py

Drop shreai.py next to your code and import shreai.

Quick start

from shreai import ShreAI

# Initialize once at app start
sa = ShreAI(
    endpoint="https://apiauth.shre.ai",
    events_endpoint="https://events.shre.ai",
    tenant_id="<your_tenant>",
    app="rapid_pos",                    # or rapid_bos
    mode="read_only",                   # default; no API key needed
    on_error=lambda e, ctx: print(f"[ShreAI] {ctx}: {e}"),
    on_flush=lambda sent, failed: print(f"[ShreAI] flushed {sent}/{failed}"),
)
sa.start()

# Track events anywhere
sa.track("screen_viewed", entity_type="screen", entity_id="ItemEdit")
sa.track("item_scanned", entity_type="item", entity_id=barcode,
         metadata={"price": item_price, "department": dept})
sa.track("transaction_complete", entity_type="transaction", entity_id=txn_id,
         metadata={"total": total, "item_count": n})

# Optional — graceful shutdown drains the queue
sa.stop()

start() bootstraps a session, fetches kill-switch config, starts the flush + config-refresh threads. The SDK auto-drains on interpreter exit via atexit.

Configuration

Field	Required	Default	Notes
endpoint	yes	—	https://apiauth.shre.ai
events_endpoint	no	= endpoint	https://events.shre.ai
tenant_id	yes	—	Your store / tenant identifier
app	yes	—	^[a-z][a-z0-9_-]{0,31}$
mode	no	"read_only"	or "read_write" (needs bootstrap_key)
bootstrap_key	iff read_write	—	Public bootstrap key from Shre AI ops
store_id, user_id, role	no	—	Optional context
flush_interval_seconds	no	10	Server may override
batch_size	no	50	Server may override
max_queue_size	no	5000	Local queue cap
timeout_s	no	8.0	Per-request HTTP timeout
on_error, on_flush	no	—	Callbacks

Behavior

• Fire-and-forget — track() returns immediately, never blocks
• Local queue up to 5000 events; oldest dropped at cap
• Batches every 10 s (server-tunable)
• Idempotent — every event has a UUID; server upserts on (tenant_id, event_id)
• Backoff on failure: 5 → 15 → 30 → 60 → 300 s
• Drains on exit — atexit hook calls stop() automatically

Error handling

HTTP	SDK reaction
200	Drain accepted events from queue
401	Re-bootstrap session (refresh JWT, read_write only)
403	Set local kill-switch — stop tracking until next config refresh
429 / 5xx	Exponential backoff: 5 → 15 → 30 → 60 → 300 s
Network offline	Stay queued; flush on next interval after recovery

Forbidden hosts

The SDK refuses to initialize against any hostname starting with downloads. (it's the asset host, not the API). You'll get a ShreAIError at construction time.

Threading model

The SDK starts two daemon threads:

• shreai-flush — every flush_interval_seconds, attempts to drain the queue
• shreai-config — every 5 min, refreshes the remote kill-switch config

All daemon threads. No process-keepalive contribution. Clean exit via stop() or atexit.

Cloudflare WAF note

The SDK sets User-Agent: shreai-sdk/python/2.0.0 on every request. Default Python urllib UA is blocked by Cloudflare's bot detection (error 1010); we sidestep by always sending the SDK identity.

Platforms

• Python 3.9+
• Works on macOS, Linux, Windows
• No GIL-sensitive code; safe to use from multi-threaded apps
• Compatible with WSGI / ASGI web frameworks (Flask, FastAPI, Django, etc.)

License

MIT. See LICENSE.

Spec

This SDK implements the Shre AI Shared SDK Spec. Drift between language SDKs is a release blocker.