Metadata-Version: 2.4
Name: ekstra-provider-sdk
Version: 0.1.0
Summary: Standalone Python provider SDK wrapper for Ekstra.OS
Author: Ekstra.OS
License-Expression: Apache-2.0
Project-URL: Homepage, https://ekstra.ai/build-with-ekstra
Project-URL: Repository, https://github.com/imxdemetri/ekstra-os
Project-URL: Issues, https://github.com/imxdemetri/ekstra-os/issues
Keywords: ekstra,motion,provider,sdk
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ekstra-os>=0.1.0
Dynamic: license-file

# Ekstra.OS Python Provider SDK

This folder presents the standalone Python SDK surface for Ekstra.OS.

Current implementation:

- source: `ekstra_os/providers/sdk.py`
- primary class: `ProviderSDK`
- package wrapper: `sdk/python/src/ekstra_provider_sdk`
- purpose: minimal provider helper for publishing `MotionSample` events into `motiond`

## Install shape

Package metadata now lives in `sdk/python/pyproject.toml`.

The distributable package name is:

```powershell
ekstra-provider-sdk
```

Published install:

```powershell
pip install ekstra-provider-sdk
```

Primary import:

```python
from ekstra_provider_sdk import MotionSample, ProviderSDK
```

## What it supports today

1. Provider identity connect
2. Provider manifest registration
3. Attested provider registration
4. Heartbeat management
5. Motion sample publish
6. Automatic reconnect on publish failure

## Primary source

```python
from ekstra_provider_sdk import MotionSample, ProviderSDK

provider = ProviderSDK(
    provider_id="python-provider",
    actor_id="actor-1",
    parts=["hand.right"],
)
provider.connect({"name": "Python Provider"})

sample = MotionSample(
    actor_id="actor-1",
    part="hand.right",
    frame="device:python",
    timestamp=1.0,
)
provider.publish_sample("motion.samples", sample)
provider.close()
```

## Test

```powershell
$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
python -m pytest -q ekstra_os/tests/test_provider_sdk.py ekstra_os/tests/test_python_sdk_package.py
python sdk/python/scripts/smoke_build_install.py
```

## Current status

- Verified locally on 2026-03-13
- Builds as a standalone Python distribution under `sdk/python`
- Still depends on the main `ekstra-os` runtime package for the underlying implementation

## Release

Python release tags:

```text
python-sdk-vX.Y.Z
```

The release workflow verifies:
1. provider SDK tests
2. wheel and sdist build
3. clean virtual environment install smoke
4. `twine check`
5. publish only on release tags or explicit manual release
