Metadata-Version: 2.4
Name: lumina-core-sdk
Version: 0.1.0
Summary: Lumina Core Python SDK
Author: Lumina Core
License: Proprietary
Project-URL: Homepage, https://lumina-core.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 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:

```bash
pip install lumina-core-sdk
```

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

```python
# 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

```python
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:

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