lumina-core-sdk 0.1.0

Lumina Core Python SDK

Lumina Python SDK

Production-grade Python SDK with:

• Retry + exponential backoff
• Batch sending (/api/v1/events/batch)
• Offline disk queue (crash-safe)
• Persistent device id
• Error model (LuminaHTTPError, LuminaTransportError)
• Event hooks (on("CRITICAL", ...))
• Optional mouse auto-tracking (auto_track_mouse)

Structure

sdk/python/
  lumina_sdk/
    __init__.py
    client.py
    queue.py
    utils.py
  lumina_client.py  # backward-compatible shim

Quick Start

Install:

pip install lumina-core-sdk

from lumina_sdk import Lumina

lumina = Lumina(
    api_key="lumina_test",
    trader_id="TR_001",
    org_id="org_abc123",
    base_url="http://localhost:5000",
    flush_interval=2.0,
    max_batch=10,
)

lumina.on("CRITICAL", lambda payload: print("CRITICAL", payload))

lumina.track(
    {
        "type": "order_open",
        "reaction_time": 120,
        "rapid_reentry": True,
    }
)

state = lumina.get_state()
print(state)

lumina.shutdown(flush=True)

Optional Auto Tracking

# pip install pynput
lumina.auto_track_mouse(emit_interval_seconds=2.0)

Offline Persistence

By default SDK stores local data in:

• ~/.lumina/device_id
• ~/.lumina/events.queue.json
• ~/.lumina/dead_letter.queue.json

Use storage_dir to change location.

Error Handling

from lumina_sdk import Lumina, LuminaHTTPError, LuminaTransportError

lumina = Lumina(api_key="lumina_test", trader_id="TR_001")

try:
    lumina.get_state()
except LuminaHTTPError as exc:
    print("HTTP", exc.status_code, exc.payload)
except LuminaTransportError as exc:
    print("Network", str(exc))

Notes

• org_id is optional but recommended for org-scoped SDK keys.
• When org_id is set, SDK sends x-org-id automatically.

Release Helpers

From repository root:

./sdk/release/bump-sdk-version.ps1 -Version 0.2.0
./sdk/release/run-sdk-release-checks.ps1 -SkipJavaScript