reactor-sdk 0.1.0__tar.gz

reactor_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build

reactor_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

reactor_sdk-0.1.0/.gitignore

@@ -0,0 +1,131 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log

reactor_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Reactor Technologies, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

reactor_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: reactor-sdk
+Version: 0.1.0
+Summary: Python SDK for Reactor - Real-time AI video streaming
+Project-URL: Homepage, https://reactor.inc
+Project-URL: Documentation, https://docs.reactor.inc
+Project-URL: Repository, https://github.com/reactor-team/py-sdk
+Author-email: Reactor Technologies <support@reactor.inc>
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: aiortc>=1.9.0
+Requires-Dist: av>=12.0.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Reactor Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/reactor-sdk)](https://pypi.org/project/reactor-sdk/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/reactor-sdk)](https://pypi.org/project/reactor-sdk/)
+[![build](https://img.shields.io/github/actions/workflow/status/reactor-team/py-sdk/ci.yml?branch=main)](https://github.com/reactor-team/py-sdk/actions)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Python SDK for Reactor - Real-time AI video streaming platform.
+
+## Installation
+
+```bash
+pip install reactor-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from reactor_sdk import Reactor, ReactorStatus
+
+async def main():
+    # Create a Reactor instance with your API key
+    reactor = Reactor(
+        model_name="my-model",
+        api_key="REACTOR_API_KEY",  # SDK automatically fetches JWT token
+    )
+    
+    # Use decorators for clean event handling
+    @reactor.on_frame
+    def handle_frame(frame):
+        print(f"Received frame: {frame.shape}")
+    
+    @reactor.on_message
+    def handle_message(msg):
+        print(f"Message: {msg}")
+    
+    @reactor.on_status(ReactorStatus.READY)
+    def handle_ready(status):
+        print("Connected and ready!")
+    
+    @reactor.on_error
+    def handle_error(error):
+        print(f"Error: {error}")
+    
+    # Connect to the model (JWT token is fetched automatically)
+    await reactor.connect()
+    
+    # Send commands
+    await reactor.send_command("setParameter", {"value": 0.5})
+    
+    # Keep running
+    try:
+        while reactor.get_status() == ReactorStatus.READY:
+            await asyncio.sleep(0.1)
+    finally:
+        await reactor.disconnect()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Features
+
+- **WebRTC video streaming** via aiortc
+- **Event-driven API** matching the JavaScript SDK
+- **Frame callbacks** for single-frame access
+- **Video input** support for sending video to models
+- **Local development** mode for testing
+- **Full type hints** for IDE support
+
+## API Reference
+
+### Reactor
+
+The main class for connecting to Reactor models.
+
+```python
+from reactor_sdk import Reactor
+
+# Production usage with API key
+reactor = Reactor(
+    model_name="my-model",
+    api_key="REACTOR_API_KEY",  # SDK fetches JWT automatically
+)
+
+# Local development (no API key needed)
+reactor = Reactor(
+    model_name="my-model",
+    local=True,
+)
+```
+
+The `Reactor` type can also be used for type annotations:
+
+```python
+from reactor_sdk import Reactor
+
+def process_reactor(reactor: Reactor) -> None:
+    # reactor has full type hints for all methods
+    pass
+```
+
+#### Methods
+
+- `await reactor.connect()` - Connect to the model (fetches JWT automatically if API key provided)
+- `await reactor.disconnect(recoverable: bool = False)` - Disconnect
+- `await reactor.reconnect()` - Reconnect to existing session
+- `await reactor.send_command(command: str, data: dict)` - Send a command
+- `await reactor.publish_track(track: MediaStreamTrack)` - Send video to model
+- `await reactor.unpublish_track()` - Stop sending video
+- `reactor.get_status()` - Get current status
+- `reactor.get_session_id()` - Get session ID
+- `reactor.set_frame_callback(callback)` - Set frame callback
+
+#### Decorators
+
+Use decorators for clean event handling:
+
+```python
+@reactor.on_frame
+def handle_frame(frame):
+    """Called for each video frame (numpy array H,W,3)."""
+    pass
+
+@reactor.on_message
+def handle_message(message):
+    """Called for each message from the model."""
+    pass
+
+@reactor.on_status
+def handle_any_status(status):
+    """Called for all status changes."""
+    pass
+
+@reactor.on_status(ReactorStatus.READY)
+def handle_ready(status):
+    """Called only when status becomes READY."""
+    pass
+
+@reactor.on_status([ReactorStatus.READY, ReactorStatus.CONNECTING])
+def handle_active(status):
+    """Called when status is READY or CONNECTING."""
+    pass
+
+@reactor.on_error
+def handle_error(error):
+    """Called when an error occurs."""
+    pass
+
+@reactor.on_stream
+def handle_stream(track):
+    """Called when video stream/track changes."""
+    pass
+```
+
+#### Events (alternative to decorators)
+
+- `status_changed` - Status changed (disconnected, connecting, ready)
+- `session_id_changed` - Session ID changed
+- `new_message` - Message received from model
+- `stream_changed` - Video stream changed
+- `error` - Error occurred
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `pygame_app/` - Pygame application with dynamic UI controls
+- `rtmp_app/` - Stream Reactor video to RTMP servers (Twitch, YouTube, etc.)
+
+## License
+
+MIT License - Copyright (c) 2025 Reactor Technologies, Inc.

reactor_sdk-0.1.0/README.md

@@ -0,0 +1,174 @@
+# Reactor Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/reactor-sdk)](https://pypi.org/project/reactor-sdk/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/reactor-sdk)](https://pypi.org/project/reactor-sdk/)
+[![build](https://img.shields.io/github/actions/workflow/status/reactor-team/py-sdk/ci.yml?branch=main)](https://github.com/reactor-team/py-sdk/actions)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+Python SDK for Reactor - Real-time AI video streaming platform.
+
+## Installation
+
+```bash
+pip install reactor-sdk
+```
+
+## Quick Start
+
+```python
+import asyncio
+from reactor_sdk import Reactor, ReactorStatus
+
+async def main():
+    # Create a Reactor instance with your API key
+    reactor = Reactor(
+        model_name="my-model",
+        api_key="REACTOR_API_KEY",  # SDK automatically fetches JWT token
+    )
+    
+    # Use decorators for clean event handling
+    @reactor.on_frame
+    def handle_frame(frame):
+        print(f"Received frame: {frame.shape}")
+    
+    @reactor.on_message
+    def handle_message(msg):
+        print(f"Message: {msg}")
+    
+    @reactor.on_status(ReactorStatus.READY)
+    def handle_ready(status):
+        print("Connected and ready!")
+    
+    @reactor.on_error
+    def handle_error(error):
+        print(f"Error: {error}")
+    
+    # Connect to the model (JWT token is fetched automatically)
+    await reactor.connect()
+    
+    # Send commands
+    await reactor.send_command("setParameter", {"value": 0.5})
+    
+    # Keep running
+    try:
+        while reactor.get_status() == ReactorStatus.READY:
+            await asyncio.sleep(0.1)
+    finally:
+        await reactor.disconnect()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Features
+
+- **WebRTC video streaming** via aiortc
+- **Event-driven API** matching the JavaScript SDK
+- **Frame callbacks** for single-frame access
+- **Video input** support for sending video to models
+- **Local development** mode for testing
+- **Full type hints** for IDE support
+
+## API Reference
+
+### Reactor
+
+The main class for connecting to Reactor models.
+
+```python
+from reactor_sdk import Reactor
+
+# Production usage with API key
+reactor = Reactor(
+    model_name="my-model",
+    api_key="REACTOR_API_KEY",  # SDK fetches JWT automatically
+)
+
+# Local development (no API key needed)
+reactor = Reactor(
+    model_name="my-model",
+    local=True,
+)
+```
+
+The `Reactor` type can also be used for type annotations:
+
+```python
+from reactor_sdk import Reactor
+
+def process_reactor(reactor: Reactor) -> None:
+    # reactor has full type hints for all methods
+    pass
+```
+
+#### Methods
+
+- `await reactor.connect()` - Connect to the model (fetches JWT automatically if API key provided)
+- `await reactor.disconnect(recoverable: bool = False)` - Disconnect
+- `await reactor.reconnect()` - Reconnect to existing session
+- `await reactor.send_command(command: str, data: dict)` - Send a command
+- `await reactor.publish_track(track: MediaStreamTrack)` - Send video to model
+- `await reactor.unpublish_track()` - Stop sending video
+- `reactor.get_status()` - Get current status
+- `reactor.get_session_id()` - Get session ID
+- `reactor.set_frame_callback(callback)` - Set frame callback
+
+#### Decorators
+
+Use decorators for clean event handling:
+
+```python
+@reactor.on_frame
+def handle_frame(frame):
+    """Called for each video frame (numpy array H,W,3)."""
+    pass
+
+@reactor.on_message
+def handle_message(message):
+    """Called for each message from the model."""
+    pass
+
+@reactor.on_status
+def handle_any_status(status):
+    """Called for all status changes."""
+    pass
+
+@reactor.on_status(ReactorStatus.READY)
+def handle_ready(status):
+    """Called only when status becomes READY."""
+    pass
+
+@reactor.on_status([ReactorStatus.READY, ReactorStatus.CONNECTING])
+def handle_active(status):
+    """Called when status is READY or CONNECTING."""
+    pass
+
+@reactor.on_error
+def handle_error(error):
+    """Called when an error occurs."""
+    pass
+
+@reactor.on_stream
+def handle_stream(track):
+    """Called when video stream/track changes."""
+    pass
+```
+
+#### Events (alternative to decorators)
+
+- `status_changed` - Status changed (disconnected, connecting, ready)
+- `session_id_changed` - Session ID changed
+- `new_message` - Message received from model
+- `stream_changed` - Video stream changed
+- `error` - Error occurred
+
+## Examples
+
+See the `examples/` directory for complete examples:
+
+- `pygame_app/` - Pygame application with dynamic UI controls
+- `rtmp_app/` - Stream Reactor video to RTMP servers (Twitch, YouTube, etc.)
+
+## License
+
+MIT License - Copyright (c) 2025 Reactor Technologies, Inc.

reactor_sdk-0.1.0/examples/pygame_app/README.md

@@ -0,0 +1,126 @@
+# Pygame Example Application
+
+A pygame-based application demonstrating the Reactor Python SDK with real-time video streaming and dynamic UI controls.
+
+## Features
+
+- Real-time video stream display from Reactor models
+- Dynamic controller UI that builds controls based on model capabilities
+- Support for sliders, checkboxes, dropdowns, and text inputs
+- Automatic command execution when adjusting slider values
+
+## Prerequisites
+
+- Python 3.10 or higher
+- A Reactor API key (get one at https://reactor.inc)
+
+## Installation
+
+1. Install the Reactor SDK (from the parent directory):
+
+```bash
+cd /path/to/py-sdk
+pip install -e .
+```
+
+2. Install pygame:
+
+```bash
+pip install pygame
+```
+
+Or install all dependencies:
+
+```bash
+cd examples/pygame_app
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Local Development
+
+Connect to a local Reactor model running at `localhost:8080`:
+
+```bash
+python main.py --local
+```
+
+### Remote Connection
+
+Connect to a remote Reactor model using your API key:
+
+```bash
+python main.py --api-key REACTOR_API_KEY --model your-model-name
+```
+
+### Command Line Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--api-key` | `-k` | Reactor API key for authentication |
+| `--model` | `-m` | Model name to connect to (default: `example-model`) |
+| `--local` | `-l` | Connect to local coordinator at `localhost:8080` |
+| `--coordinator-url` | `-c` | Custom coordinator URL |
+| `--verbose` | `-v` | Enable verbose logging |
+
+### Examples
+
+```bash
+# Local development
+python main.py --local --model my-local-model
+
+# Production with API key
+python main.py -k sk_live_xxxxx -m production-model
+
+# With verbose logging
+python main.py --local -v
+
+# Custom coordinator
+python main.py -k REACTOR_API_KEY -m my-model -c https://custom-coordinator.example.com
+```
+
+## Controls
+
+- **ESC**: Quit the application
+- **Mouse Click**: Interact with controller UI elements
+- **Mouse Scroll**: Scroll the controller panel
+
+## UI Layout
+
+```
+┌─────────────────────────────────┬──────────────────┐
+│                                 │                  │
+│                                 │  Reactor         │
+│      Video Stream               │  Commands        │
+│      (960 x 720)                │                  │
+│                                 │  [Dynamic UI     │
+│                                 │   controls       │
+│                                 │   based on       │
+│                                 │   model caps]    │
+│                                 │                  │
+└─────────────────────────────────┴──────────────────┘
+```
+
+## How It Works
+
+1. **Connection**: The app connects to the Reactor coordinator, which assigns a GPU machine
+2. **Capabilities**: Once connected, it requests the model's capabilities schema
+3. **Dynamic UI**: The controller parses the schema and builds appropriate UI controls
+4. **Commands**: User interactions trigger commands sent to the model via WebRTC data channel
+5. **Video**: The model's video output is streamed back and displayed in real-time
+
+## Troubleshooting
+
+### "No API key provided" error
+Make sure to provide either `--api-key` or `--local` flag.
+
+### Video not displaying
+- Check that the model is running and producing output
+- Verify the connection status indicator (green = connected)
+- Enable verbose logging with `-v` to see detailed connection info
+
+### Controller not showing commands
+- Wait a few seconds after connection for capabilities to be received
+- The app automatically retries requesting capabilities every 5 seconds
+- Check verbose logs for any errors in the capabilities response