reactor-runtime 0.0.0__tar.gz

reactor_runtime-0.0.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: reactor_runtime
+Version: 0.0.0
+Summary: Reactor runtime with public model API
+Author-email: Reactor <team@reactor.inc>
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=13.0
+Requires-Dist: numpy<2.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml
+Requires-Dist: av>=12.0.0
+Requires-Dist: aiortc>=1.10.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: uvicorn[standard]>=0.23.0
+Requires-Dist: livekit-api>=1.0.5
+Requires-Dist: livekit==1.0.12
+Requires-Dist: aiohttp>=3.9.3
+Requires-Dist: redis
+Requires-Dist: supabase>=2.0.0
+Requires-Dist: boto3>=1.28.0
+Requires-Dist: opentelemetry-api
+Requires-Dist: opentelemetry-sdk
+Requires-Dist: opentelemetry-exporter-otlp-proto-http
+Requires-Dist: tqdm
+
+# Reactor Runtime
+
+A Python runtime for building real-time video processing models. This runtime abstracts all the techincal implementations of real-time networking, allowing
+researchers and models developers to run their model focusing only on the ML code.
+
+You can think of this similarly to the way you write Telegram/Discord applications or bots using SDKs. You don't have to worry about the networking and the protocols of the medium. Instead, you can put all your effort in writing your application code, which in this case is ML code.
+
+## Installation
+
+```bash
+pip install reactor-runtime
+```
+
+## CLI Reference
+
+The reactor-runtime library offers a set of commands that help you getting started with development.
+
+### `reactor init <name>`
+
+Initialize a new model workspace from a template.
+
+```bash
+reactor init my-model
+```
+
+Creates a directory `my-model/` with:
+
+- `model_template.py` - Example VideoModel implementation
+- `manifest.json` - Model configuration
+- `requirements.txt` - Python dependencies
+- `README.md` - Documentation Template
+
+Once you have created your workspace, you're ready to start implementing your model.
+
+---
+
+### `reactor run`
+
+Run your model with the Reactor runtime.
+
+```bash
+reactor run [--host HOST] [--port PORT] [--log-level LEVEL]
+```
+
+**Arguments:**
+
+- `--host` - Server host (default: `0.0.0.0`)
+- `--port` - Server port (default: `8081`)
+- `--log-level` - Log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` (default: `INFO`)
+
+The `reactor run` command, will use the `manifest.json` file to infer the basic information and properties of your model.
+Read the next section in order to understand what the `manifest.json` is, and how to customize it for your needs.
+
+After running `reactor run`, you might encounter an error if you don't have the livekit local server installed. Follow
+this link (which is also shown in the error) to install livekit on your OS: https://docs.livekit.io/home/self-hosting/local/
+
+**Example:**
+
+```bash
+reactor run
+```
+
+---
+
+### `reactor capabilities`
+
+Print the command capabilities of a VideoModel.
+
+```bash
+reactor capabilities
+```
+
+Outputs JSON schema of all available commands defined in your model (via `@command` decorators). When implementing your model, you will be able
+to specify specific messages you want to "react" to, in real-time.
+
+After these messages have been defined in your code, the runtime will generate a schema automatically, that clients will be able to use to infer what messages to send to the model.
+
+---
+
+## Manifest Format
+
+```json
+{
+  "reactor-runtime": "0.0.0",
+  "model_name": "my-model",
+  "model_version": "1.0.0",
+  "class": "model_file:ModelClass",
+  "args": {
+    "fps": 30,
+    "size": [480, 640]
+  },
+  "weights": ["sam2_hiera_large", "dinov2_vitl14"],
+  "video_input": false
+}
+```
+
+The manifest is what defines your model. It defines the entrypoint, the version, the arguments, and so on. It is basically as the ID card of the model.
+
+- reactor-runtime -> the version of the runtime used for development, so that it can be used for deployments and guarantee compatibility
+- model_name -> the name of the model. This will identify the model on the Reactor ecosystem. (Multiple versions of the models should be specified using the version parameter.)
+- model_version -> the version of the model.
+- class -> Really important, it should be a pointer to the VideoModel class your model implements. For example, if you have implemented VideoModel in a file called `magic-model`, calling the model `MyMagicModel`, the value should be ``magic-model:MyMagicModel`
+- args: the arguments with which the model will be started. You'll be able to access these arguments in the **init** call of the VideoModel, through the `kwargs`
+- weights: not needed for local development (for now). Specify your weights as you normally would, when deploying the Reactor Team will manually optimize the weights path.
+- video_input: if enabled, your model will be able to accept video input during a session. This means that whenever a user will stream their own video stream, you'll receive each frame call on a method called `on_frame`. You'll receive frames as numpy ndarrays.

reactor_runtime-0.0.0/README.md

@@ -0,0 +1,105 @@
+# Reactor Runtime
+
+A Python runtime for building real-time video processing models. This runtime abstracts all the techincal implementations of real-time networking, allowing
+researchers and models developers to run their model focusing only on the ML code.
+
+You can think of this similarly to the way you write Telegram/Discord applications or bots using SDKs. You don't have to worry about the networking and the protocols of the medium. Instead, you can put all your effort in writing your application code, which in this case is ML code.
+
+## Installation
+
+```bash
+pip install reactor-runtime
+```
+
+## CLI Reference
+
+The reactor-runtime library offers a set of commands that help you getting started with development.
+
+### `reactor init <name>`
+
+Initialize a new model workspace from a template.
+
+```bash
+reactor init my-model
+```
+
+Creates a directory `my-model/` with:
+
+- `model_template.py` - Example VideoModel implementation
+- `manifest.json` - Model configuration
+- `requirements.txt` - Python dependencies
+- `README.md` - Documentation Template
+
+Once you have created your workspace, you're ready to start implementing your model.
+
+---
+
+### `reactor run`
+
+Run your model with the Reactor runtime.
+
+```bash
+reactor run [--host HOST] [--port PORT] [--log-level LEVEL]
+```
+
+**Arguments:**
+
+- `--host` - Server host (default: `0.0.0.0`)
+- `--port` - Server port (default: `8081`)
+- `--log-level` - Log level: `CRITICAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG` (default: `INFO`)
+
+The `reactor run` command, will use the `manifest.json` file to infer the basic information and properties of your model.
+Read the next section in order to understand what the `manifest.json` is, and how to customize it for your needs.
+
+After running `reactor run`, you might encounter an error if you don't have the livekit local server installed. Follow
+this link (which is also shown in the error) to install livekit on your OS: https://docs.livekit.io/home/self-hosting/local/
+
+**Example:**
+
+```bash
+reactor run
+```
+
+---
+
+### `reactor capabilities`
+
+Print the command capabilities of a VideoModel.
+
+```bash
+reactor capabilities
+```
+
+Outputs JSON schema of all available commands defined in your model (via `@command` decorators). When implementing your model, you will be able
+to specify specific messages you want to "react" to, in real-time.
+
+After these messages have been defined in your code, the runtime will generate a schema automatically, that clients will be able to use to infer what messages to send to the model.
+
+---
+
+## Manifest Format
+
+```json
+{
+  "reactor-runtime": "0.0.0",
+  "model_name": "my-model",
+  "model_version": "1.0.0",
+  "class": "model_file:ModelClass",
+  "args": {
+    "fps": 30,
+    "size": [480, 640]
+  },
+  "weights": ["sam2_hiera_large", "dinov2_vitl14"],
+  "video_input": false
+}
+```
+
+The manifest is what defines your model. It defines the entrypoint, the version, the arguments, and so on. It is basically as the ID card of the model.
+
+- reactor-runtime -> the version of the runtime used for development, so that it can be used for deployments and guarantee compatibility
+- model_name -> the name of the model. This will identify the model on the Reactor ecosystem. (Multiple versions of the models should be specified using the version parameter.)
+- model_version -> the version of the model.
+- class -> Really important, it should be a pointer to the VideoModel class your model implements. For example, if you have implemented VideoModel in a file called `magic-model`, calling the model `MyMagicModel`, the value should be ``magic-model:MyMagicModel`
+- args: the arguments with which the model will be started. You'll be able to access these arguments in the **init** call of the VideoModel, through the `kwargs`
+- weights: not needed for local development (for now). Specify your weights as you normally would, when deploying the Reactor Team will manually optimize the weights path.
+- video_input: if enabled, your model will be able to accept video input during a session. This means that whenever a user will stream their own video stream, you'll receive each frame call on a method called `on_frame`. You'll receive frames as numpy ndarrays.

reactor_runtime-0.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "reactor_runtime"
+version = "0.0.0"
+description = "Reactor runtime with public model API"
+authors = [
+	{ name = "Reactor", email = "team@reactor.inc" }
+]
+readme = "README.md"
+requires-python = ">=3.9"
+
+dependencies = [
+	"websockets>=13.0",
+	"numpy<2.0",
+	"pydantic>=2.0.0",
+    "pyyaml",
+    "av>=12.0.0",
+    "aiortc>=1.10.0",
+    "fastapi>=0.100.0",
+    "uvicorn[standard]>=0.23.0",
+ 	"livekit-api>=1.0.5",
+	"livekit==1.0.12",
+	"aiohttp>=3.9.3",
+	"redis",
+	"supabase>=2.0.0",
+	"boto3>=1.28.0",
+	"opentelemetry-api",
+	"opentelemetry-sdk",
+	"opentelemetry-exporter-otlp-proto-http",
+	"tqdm"
+]
+
+[project.scripts]
+reactor = "reactor_cli.main:main"

reactor_runtime-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

reactor_runtime-0.0.0/src/reactor_cli/commands/__init__.py

@@ -0,0 +1,14 @@
+"""Reactor CLI Commands
+
+This module contains all command implementations for the reactor CLI.
+Each command is implemented as a class following the HuggingFace pattern.
+"""
+
+from .run import RunCommand
+from .init import InitCommand
+from .download import DownloadCommand
+from .upload import UploadCommand
+from .setup import SetupCommand
+from .capabilities import CapabilitiesCommand
+
+__all__ = ['RunCommand', 'InitCommand', 'DownloadCommand', 'UploadCommand', 'SetupCommand', 'CapabilitiesCommand']

reactor_runtime-0.0.0/src/reactor_cli/commands/capabilities.py

@@ -0,0 +1,118 @@
+"""Run command implementation."""
+
+import importlib
+import json
+from reactor_runtime.model_api import VideoModel, command
+import ast
+from pathlib import Path
+
+def load_class_without_init(file_path: str, class_name: str):
+	"""
+	Load only the subclass definition from a Python file (without executing imports or __init__),
+	recreate it with CommandBase as its parent, and call its inherited commands() method.
+	All imports from the source file are detected via AST and replicated in the namespace.
+	"""
+	source = Path(file_path).read_text(encoding="utf-8")
+	tree = ast.parse(source, filename=file_path)
+
+	def extract_imports(tree):
+		"""Return a dict of {imported_name: module_object or attribute} from the AST."""
+		imports = {}
+
+		for node in tree.body:
+			if isinstance(node, ast.Import):
+				for alias in node.names:
+					mod_name = alias.name
+					as_name = alias.asname or mod_name.split(".")[0]
+					try:
+						imports[as_name] = importlib.import_module(mod_name)
+					except ImportError:
+						pass  # Skip missing modules safely
+
+			elif isinstance(node, ast.ImportFrom):
+				if node.module is None:
+					continue
+				try:
+					mod = importlib.import_module(node.module)
+				except ImportError:
+					continue
+				for alias in node.names:
+					as_name = alias.asname or alias.name
+					if alias.name == "*":
+						# Handle "from X import *" by copying all public symbols
+						for name in dir(mod):
+							if not name.startswith("_"):
+								imports[name] = getattr(mod, name)
+					else:
+						try:
+							imports[as_name] = getattr(mod, alias.name)
+						except AttributeError:
+							pass
+
+		return imports
+
+	# Detect and import all modules referenced in the source
+	imported_symbols = extract_imports(tree)
+
+	for node in tree.body:
+		if isinstance(node, ast.ClassDef) and node.name == class_name:
+			# Replace base classes with CommandBase
+			node.bases = [ast.Name(id='CommandBase', ctx=ast.Load())]
+			ast.fix_missing_locations(node)
+
+			# Compile a module containing only that class
+			class_module = ast.Module(body=[node], type_ignores=[])
+			ast.fix_missing_locations(class_module)
+			code = compile(class_module, filename=file_path, mode="exec")
+
+			# Build isolated namespace
+			ns = {
+				"CommandBase": VideoModel,
+				"command": command,
+				**imported_symbols
+			}
+
+			exec(code, ns)
+			subcls = ns[class_name]
+			obj = subcls.__new__(subcls)
+			return obj
+
+	raise ValueError(f"Class '{class_name}' not found in {file_path}")
+
+
+class CapabilitiesCommand:
+    @staticmethod
+    def register_subcommand(subparsers):
+        """Register capabilities command"""
+        run_parser = subparsers.add_parser("capabilities", help="Print the capabilities of a reactor VideoModel.")
+        run_parser.set_defaults(func=CapabilitiesCommand)
+
+    def __init__(self, args):
+        """Initialize with parsed arguments"""
+        self.args = args
+
+    def run(self):
+        """Print the capabilities of a reactor VideoModel."""
+        from ..main import verify_reactor_workspace
+
+        # Verify workspace and get manifest data
+        manifest_data = verify_reactor_workspace()
+        if manifest_data is None:
+            return
+
+        # Extract model information from manifest
+        model_class_name: str = manifest_data["class"]
+        model_file, model_class = model_class_name.split(":")
+        model_class: VideoModel = load_class_without_init(model_file+".py", model_class)
+
+        if "model_name" not in manifest_data.keys():
+            print("Error: manifest.json is missing required 'model_name' field.")
+            print("Please add a 'model_name' field specifying the model name.")
+            return
+        if "model_version" not in manifest_data.keys():
+            print("Error: manifest.json is missing required 'model_version' field.")
+            print("Please add a 'model_version' field specifying the model version.")
+            return
+
+
+        print(json.dumps(model_class.commands(), indent=4))

reactor_runtime-0.0.0/src/reactor_cli/commands/download.py

@@ -0,0 +1,217 @@
+"""Download command implementation."""
+
+import os
+import json
+import logging
+from typing import List, Optional
+from pathlib import Path
+from supabase import create_client
+from ..utils import get_weights_parallel, get_latest_version
+from ..main import verify_reactor_workspace
+
+# Set up logger
+logger = logging.getLogger(__name__)
+
+
+def parse_manifest(manifest_str: str) -> dict:
+    """Parse a manifest string into a dictionary.
+    
+    Args:
+        manifest_str: JSON string containing the manifest
+        
+    Returns:
+        Parsed manifest dictionary
+    """
+    try:
+        return json.loads(manifest_str)
+    except json.JSONDecodeError as e:
+        logger.error(f"Failed to parse manifest JSON: {e}")
+        raise ValueError(f"Invalid manifest JSON: {e}")
+
+
+def get_weights_from_manifest(manifest: dict) -> List[str]:
+    """Extract the weights list from a manifest dictionary.
+    
+    Args:
+        manifest: Dictionary containing manifest data
+        
+    Returns:
+        List of weight folder names
+    """
+    if "weights" not in manifest:
+        logger.warning("Manifest does not contain a 'weights' field")
+        return []
+    
+    weights = manifest["weights"]
+    if not isinstance(weights, list):
+        logger.error(f"'weights' field must be a list, got {type(weights)}")
+        raise ValueError("'weights' field in manifest must be a list")
+    
+    return weights
+
+
+def get_weights_from_local_manifest() -> List[str]:
+    """Read weights from local manifest.json file.
+    
+    Returns:
+        List of weight folder names from local manifest
+    """
+    manifest = verify_reactor_workspace()
+    if not manifest:
+        raise RuntimeError("Failed to verify reactor workspace or read manifest.json")
+    
+    return get_weights_from_manifest(manifest)
+
+
+def get_weights_from_model_id(model_id: str) -> List[str]:
+    """Fetch model manifest from Supabase and extract weights.
+    
+    Args:
+        model_id: Model identifier with optional version (e.g., "matrix-2" or "matrix-2@v1.0")
+                  If no version is specified, defaults to "latest"
+        
+    Returns:
+        List of weight folder names from the model's manifest
+    """
+    # Parse model_id and version from format: model@version or just model
+    if '@' in model_id:
+        model_name, version = model_id.split('@', 1)
+    else:
+        model_name = model_id
+        version = "latest"
+    
+    supabase = create_client(
+        os.getenv('SUPABASE_URL'),
+        os.getenv('SUPABASE_SERVICE_KEY')
+    )
+    
+    # If version is "latest", we need to find the actual latest version
+    if version == "latest":
+        logger.info(f"Resolving latest version for model '{model_name}'...")
+        
+        # Get the latest version using our utility function
+        try:
+            version = get_latest_version(model_name)
+            logger.info(f"Resolved latest version for '{model_name}': {version}")
+        except (ValueError, RuntimeError) as e:
+            raise ValueError(f"Failed to determine latest version for model '{model_name}': {e}")
+    
+    logger.info(f"Fetching manifest for model '{model_name}' version '{version}'...")
+    
+    result = supabase.table('models').select('manifest').eq(
+        'model_id', model_name
+    ).eq('version', version).execute()
+    
+    if not result.data:
+        raise ValueError(f"Model '{model_name}' version '{version}' not found in database")
+    
+    manifest = result.data[0]['manifest']
+
+    if not manifest:
+        raise ValueError(f"Model '{model_name}' version '{version}' doesn't have a manifest in database.")
+    
+    return get_weights_from_manifest(manifest)
+
+
+def get_weights_from_model_ids(model_ids: List[str]) -> List[str]:
+    """Fetch manifests for multiple models and extract unique weights.
+    
+    Args:
+        model_ids: List of model identifiers with optional versions 
+                   (e.g., ["matrix-2", "longlive@v1.0", "mk64"])
+        
+    Returns:
+        Deduplicated list of weight folder names from all models
+    """
+    all_weights = set()
+    
+    for model_id in model_ids:
+        try:
+            weights = get_weights_from_model_id(model_id)
+            all_weights.update(weights)
+            logger.info(f"Model '{model_id}' requires weights: {weights}")
+        except Exception as e:
+            logger.error(f"Failed to fetch weights for model '{model_id}': {e}")
+            raise
+    
+    unique_weights = list(all_weights)
+    logger.info(f"Total unique weights across all models: {unique_weights}")
+    return unique_weights
+
+
+class DownloadCommand:
+    @staticmethod
+    def register_subcommand(subparsers):
+        """Register download command"""
+        download_parser = subparsers.add_parser(
+            "download",
+            help="Download model weights"
+        )
+        download_parser.add_argument(
+            "--weights",
+            nargs='+',
+            help="List of weight folder names to download"
+        )
+        download_parser.add_argument(
+            "--models",
+            nargs='+',
+            help="List of model identifiers to fetch weights from (e.g., matrix-2 longlive@v1.0). Use model@version format to specify version, defaults to 'latest'"
+        )
+        download_parser.add_argument(
+            "--no-cache",
+            action="store_true",
+            help="Force re-download even if weights exist locally"
+        )
+        download_parser.set_defaults(func=DownloadCommand)
+
+    def __init__(self, args):
+        """Initialize command with parsed arguments"""
+        self.args = args
+
+    def run(self):
+        """Download model weights from registry"""
+        try:
+            # Determine which route to take based on arguments
+            weights_list: Optional[List[str]] = None
+            
+            if self.args.weights:
+                # Route 1: Explicit weights list provided
+                weights_list = self.args.weights
+                logger.info(f"Downloading specified weights: {weights_list}")
+                
+            elif self.args.models:
+                # Route 2: Fetch from model IDs in Supabase and deduplicate
+                print(f"Fetching manifests for {len(self.args.models)} model(s)...")
+                weights_list = get_weights_from_model_ids(self.args.models)
+                print(f"Found {len(weights_list)} unique weight(s) across all models")
+                logger.info(f"Downloaded manifests for models {self.args.models}, unique weights: {weights_list}")
+                
+            else:
+                # Route 3: Default - read from local manifest.json
+                logger.info("No arguments specified, reading from local manifest.json...")
+                weights_list = get_weights_from_local_manifest()
+                logger.info(f"Found weights in local manifest: {weights_list}")
+            
+            if not weights_list:
+                print("No weights to download.")
+                return
+            
+            # Download weights in parallel
+            if self.args.no_cache:
+                print(f"Force downloading {len(weights_list)} weight folder(s) (no-cache mode)...")
+            else:
+                print(f"Downloading {len(weights_list)} weight folder(s)...")
+            weight_paths = get_weights_parallel(weights_list, no_cache=self.args.no_cache)
+            
+            # Print results
+            print("\nDownload complete! Weight paths:")
+            for i, (weight_name, weight_path) in enumerate(zip(weights_list, weight_paths), 1):
+                if weight_path:
+                    print(f"  {i}. {weight_name}: {weight_path}")
+                else:
+                    print(f"  {i}. {weight_name}: FAILED")
+            
+        except Exception as e:
+            logger.error(f"Download command failed: {e}")
+            print(f"Error: {e}")
+            return