willow-runtime 5.1.0__tar.gz

willow_runtime-5.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Willow Dynamics
+
+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.

willow_runtime-5.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: willow-runtime
+Version: 5.1.0
+Summary: Willow 5 Runtime: Action Recognition, Retargeting, & Edge Evaluator
+Author: Willow Dynamics
+License: MIT
+Project-URL: Homepage, https://willowdynamics.com
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: numba>=0.56.0
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# Willow 5 Runtime SDK
+
+The official Python SDK for **Willow Dynamics**.
+
+This SDK acts as the bridge between the Willow Cloud Oracle and your local environment. It enables **Zero-Shot Action Recognition**, **Kinematic Retargeting**, and **Physics Evaluation** on edge devices, cloud pipelines, and simulation clusters.
+
+It is designed to be dependency-light (No AWS/Boto3 required) and privacy-first (Models run in ephemeral RAM).
+
+---
+
+## Installation
+
+```bash
+pip install willow-runtime
+```
+
+---
+
+## 1. Quick Start: Model Provisioning
+
+Securely fetch your proprietary action models from the Willow Cloud.
+
+```python
+from willow import WillowClient
+
+# Initialize with your API Key
+client = WillowClient(api_key="YOUR_WILLOW_API_KEY")
+
+# Option A: Stream directly to RAM (Secure / Cloud / Ephemeral)
+# The model never touches the physical disk.
+model = client.get_model("tactical-reload-v1")
+
+# Option B: Download to Disk (Offline / Edge / Air-Gapped)
+client.download_model("tactical-reload-v1", "./models/reload.int8")
+```
+
+---
+
+## 2. Usage: Active Streaming (Real-Time)
+
+Best for **Robotics**, **Webcams**, or **Smart Gyms** where frames arrive one by one. The `step()` method manages an internal sliding window buffer for zero-latency triggering.
+
+```python
+from willow import WillowClient, WillowDetector
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("tactical-reload-v1")
+detector = WillowDetector(model)
+
+# 2. The Real-Time Loop
+# Assume 'get_next_frame()' returns a (75, 3) numpy array of skeletal data
+while True:
+    current_skeleton, timestamp_ms = get_next_frame()
+    
+    # .step() executes in <2ms on modern CPUs
+    event = detector.step(current_skeleton, timestamp_ms)
+    
+    if event:
+        print(f"!!! ACTION DETECTED !!!")
+        print(f"Timestamp: {event['end_ms']}ms | Confidence: {event['confidence']:.2f}")
+        
+        # Trigger Actuator / Robot / UI here
+```
+
+---
+
+## 3. Usage: Batch Analysis (Passive)
+
+Best for **Data Science**, **Historical Video Processing**, or **Cloud ETL** pipelines.
+
+```python
+from willow import WillowClient, WillowDetector
+import numpy as np
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("golf-swing-v4")
+detector = WillowDetector(model)
+
+# 2. Load Data (e.g., from an uploaded video file processed by MediaPipe)
+# Shape: (Frames, 75, 3)
+full_sequence = np.load("recording_data.npy") 
+timestamps = [t * 33 for t in range(len(full_sequence))]
+
+# 3. Detect All Occurrences
+matches = detector.detect(full_sequence, timestamps)
+
+print(f"Found {len(matches)} events:")
+for m in matches:
+    print(f" - {m['start_ms']}ms to {m['end_ms']}ms (Conf: {m['confidence']:.2f})")
+```
+
+---
+
+## 4. Usage: Sim-to-Real & Robotics
+
+Best for **Reinforcement Learning (RL)**, **NVIDIA Isaac Sim**, and **Humanoid Teleoperation**. Bridges the gap between Computer Vision coordinates and Robotics standards.
+
+```python
+from willow import CoordinateBridge, KinematicRetargeter
+
+# 1. Convert Coordinate Space
+# MediaPipe (Y-Down) -> ROS/Isaac Sim (Z-Up)
+ros_ready_sequence = CoordinateBridge.to_ros_z_up(raw_skeleton_sequence)
+
+# 2. Extract Joint Angles for RL Training
+# Returns dictionary of 1D angle arrays (e.g., "right_elbow_flexion")
+joint_angles = KinematicRetargeter.extract_joint_angles(ros_ready_sequence)
+
+print(f"Extracted {len(joint_angles)} joint features for simulation training.")
+```
+
+---
+
+## License
+
+MIT License. Copyright (c) 2025 Willow Dynamics.

willow_runtime-5.1.0/README.md

@@ -0,0 +1,118 @@
+# Willow 5 Runtime SDK
+
+The official Python SDK for **Willow Dynamics**.
+
+This SDK acts as the bridge between the Willow Cloud Oracle and your local environment. It enables **Zero-Shot Action Recognition**, **Kinematic Retargeting**, and **Physics Evaluation** on edge devices, cloud pipelines, and simulation clusters.
+
+It is designed to be dependency-light (No AWS/Boto3 required) and privacy-first (Models run in ephemeral RAM).
+
+---
+
+## Installation
+
+```bash
+pip install willow-runtime
+```
+
+---
+
+## 1. Quick Start: Model Provisioning
+
+Securely fetch your proprietary action models from the Willow Cloud.
+
+```python
+from willow import WillowClient
+
+# Initialize with your API Key
+client = WillowClient(api_key="YOUR_WILLOW_API_KEY")
+
+# Option A: Stream directly to RAM (Secure / Cloud / Ephemeral)
+# The model never touches the physical disk.
+model = client.get_model("tactical-reload-v1")
+
+# Option B: Download to Disk (Offline / Edge / Air-Gapped)
+client.download_model("tactical-reload-v1", "./models/reload.int8")
+```
+
+---
+
+## 2. Usage: Active Streaming (Real-Time)
+
+Best for **Robotics**, **Webcams**, or **Smart Gyms** where frames arrive one by one. The `step()` method manages an internal sliding window buffer for zero-latency triggering.
+
+```python
+from willow import WillowClient, WillowDetector
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("tactical-reload-v1")
+detector = WillowDetector(model)
+
+# 2. The Real-Time Loop
+# Assume 'get_next_frame()' returns a (75, 3) numpy array of skeletal data
+while True:
+    current_skeleton, timestamp_ms = get_next_frame()
+    
+    # .step() executes in <2ms on modern CPUs
+    event = detector.step(current_skeleton, timestamp_ms)
+    
+    if event:
+        print(f"!!! ACTION DETECTED !!!")
+        print(f"Timestamp: {event['end_ms']}ms | Confidence: {event['confidence']:.2f}")
+        
+        # Trigger Actuator / Robot / UI here
+```
+
+---
+
+## 3. Usage: Batch Analysis (Passive)
+
+Best for **Data Science**, **Historical Video Processing**, or **Cloud ETL** pipelines.
+
+```python
+from willow import WillowClient, WillowDetector
+import numpy as np
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("golf-swing-v4")
+detector = WillowDetector(model)
+
+# 2. Load Data (e.g., from an uploaded video file processed by MediaPipe)
+# Shape: (Frames, 75, 3)
+full_sequence = np.load("recording_data.npy") 
+timestamps = [t * 33 for t in range(len(full_sequence))]
+
+# 3. Detect All Occurrences
+matches = detector.detect(full_sequence, timestamps)
+
+print(f"Found {len(matches)} events:")
+for m in matches:
+    print(f" - {m['start_ms']}ms to {m['end_ms']}ms (Conf: {m['confidence']:.2f})")
+```
+
+---
+
+## 4. Usage: Sim-to-Real & Robotics
+
+Best for **Reinforcement Learning (RL)**, **NVIDIA Isaac Sim**, and **Humanoid Teleoperation**. Bridges the gap between Computer Vision coordinates and Robotics standards.
+
+```python
+from willow import CoordinateBridge, KinematicRetargeter
+
+# 1. Convert Coordinate Space
+# MediaPipe (Y-Down) -> ROS/Isaac Sim (Z-Up)
+ros_ready_sequence = CoordinateBridge.to_ros_z_up(raw_skeleton_sequence)
+
+# 2. Extract Joint Angles for RL Training
+# Returns dictionary of 1D angle arrays (e.g., "right_elbow_flexion")
+joint_angles = KinematicRetargeter.extract_joint_angles(ros_ready_sequence)
+
+print(f"Extracted {len(joint_angles)} joint features for simulation training.")
+```
+
+---
+
+## License
+
+MIT License. Copyright (c) 2025 Willow Dynamics.

willow_runtime-5.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "willow-runtime"
+version = "5.1.0"
+description = "Willow 5 Runtime: Action Recognition, Retargeting, & Edge Evaluator"
+readme = "README.md"
+authors = [{ name = "Willow Dynamics" }]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "numpy>=1.21.0",
+    "numba>=0.56.0",
+    "requests>=2.25.0"
+]
+
+[project.urls]
+Homepage = "https://willowdynamics.com"

willow_runtime-5.1.0/setup.cfg

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

willow_runtime-5.1.0/tests/test_willow_sdk.py

@@ -0,0 +1,93 @@
+import struct
+import numpy as np
+from willow import WillowDetector, load_local_model, parse_int8_model
+from willow import CoordinateBridge, KinematicRetargeter, PhysicsEvaluator
+
+def create_mock_int8_model():
+    # Model: Version 40, Torso Bitmask (2), 5 frames
+    # Scale: 1.2
+    header = struct.pack('<IIffff', 40, 2, 1.2, 0.25, 3.0, 0.20)
+    # Features: 127 (Int8 Max) -> Dequantized to 1.2
+    mock_features = np.ones((5, 6), dtype=np.int8) * 127 
+    return header + mock_features.tobytes()
+
+def test_willow_pipeline():
+    print("--- RUNNING WILLOW 5 SDK TEST SUITE ---")
+    
+    # 1. PARSERS
+    model = parse_int8_model(create_mock_int8_model())
+    assert model.config.version == 40
+    print("✓ RAM-Only Parsing Passed")
+    
+    # 2. GENERATE DATA
+    test_seq = np.zeros((20, 75, 3), dtype=np.float32)
+    timestamps = [t * 33 for t in range(20)]
+    
+    # Base Pose (Rest)
+    for f in range(20):
+        test_seq[f, 11] = [-0.5, 1.5, 0.0]  # L Shoulder
+        test_seq[f, 12] = [ 0.5, 1.5, 0.0]  # R Shoulder
+        test_seq[f, 23] = [-0.3, 0.5, 0.0]  # L Hip (Torso Len = 1.0)
+        test_seq[f, 24] = [ 0.3, 0.5, 0.0]  # R Hip
+        
+        # Inject Perfect Match at frames 8-12
+        if 8 <= f <= 12:
+            # We need Normalized Distances = 1.2
+            # Torso Length = 1.0 (Shoulder Y 1.5 - Hip Y 0.5)
+            # So we need Absolute Distances = 1.2
+            
+            # Widen Shoulders to 1.2 width (-0.6 to 0.6)
+            test_seq[f, 11] = [-0.6, 1.5, 0.0]
+            test_seq[f, 12] = [ 0.6, 1.5, 0.0]
+            
+            # Widen Hips to 1.2 width (-0.6 to 0.6)
+            test_seq[f, 23] = [-0.6, 0.5, 0.0]
+            test_seq[f, 24] = [ 0.6, 0.5, 0.0]
+            
+            # Vertical Dists (11-23) = 1.0. 
+            # This will result in features [1.2, 1.2, 1.0, 1.0, 1.56, 1.56]
+            # This is closer to the model [1.2, 1.2, 1.2, 1.2, 1.2, 1.2]
+            # than the previous data.
+
+    # 3. DETECTOR (PASSIVE BATCH)
+    detector = WillowDetector(model)
+    batch_detections = detector.detect(test_seq, timestamps)
+    
+    if len(batch_detections) == 0:
+        print("DEBUG: No detections found. Check NMS logic or Data Scaling.")
+        
+    assert len(batch_detections) > 0
+    print("✓ Passive Batch Detection Passed")
+
+    # 4. DETECTOR (ACTIVE STREAMING)
+    detector_live = WillowDetector(model)
+    live_detections = []
+    for frame, ts in zip(test_seq, timestamps):
+        match = detector_live.step(frame, ts)
+        if match: 
+            live_detections.append(match)
+            
+    assert len(live_detections) > 0
+    print("✓ Active Real-Time Streaming Passed")
+
+    # 5. SPATIAL TRANSFORMS
+    ros_seq = CoordinateBridge.to_ros_z_up(test_seq)
+    # Check Y -> -Z translation (1.5 becomes -1.5)
+    assert ros_seq[0, 11, 2] == -1.5 
+    print("✓ Coordinate Bridging Passed")
+
+    # 6. KINEMATIC RETARGETING
+    angles = KinematicRetargeter.extract_joint_angles(test_seq)
+    assert "left_elbow_flexion" in angles
+    print("✓ Sim-to-Real IK Passed")
+
+    # 7. PHYSICS EVALUATOR
+    right_wrist_traj = test_seq[:, 16, :3]
+    physics = PhysicsEvaluator.calculate_derivatives(right_wrist_traj, fps=30.0)
+    assert "peak_jerk" in physics
+    print("✓ Edge Physics Evaluator Passed")
+    
+    print("--- ALL TESTS PASSED ---")
+
+if __name__ == "__main__":
+    test_willow_pipeline()

willow_runtime-5.1.0/willow/__init__.py

@@ -0,0 +1,14 @@
+from .types import WillowConfig, WillowModel, ZONES
+from .client import WillowClient
+from .parsers import parse_int8_model, parse_json_model, load_local_model
+from .detector import WillowDetector
+from .transforms import CoordinateBridge
+from .retargeting import KinematicRetargeter
+from .evaluator import PhysicsEvaluator
+
+__all__ =[
+    "WillowConfig", "WillowModel", "ZONES",
+    "WillowClient", "WillowDetector",
+    "CoordinateBridge", "KinematicRetargeter", "PhysicsEvaluator",
+    "load_local_model", "parse_int8_model", "parse_json_model"
+]

willow_runtime-5.1.0/willow/client.py

@@ -0,0 +1,82 @@
+import base64
+import json
+import requests
+from io import BytesIO
+from typing import Union
+
+from .types import WillowModel
+from .parsers import parse_int8_model, parse_json_model
+
+class WillowClient:
+    """
+    The official Willow API Client for Model Provisioning.
+    Handles secure retrieval of action recognition models for local or edge execution.
+    """
+    
+    # Defaults to the Master AWS Oracle Gateway
+    DEFAULT_API_URL = "https://55zydxbe05.execute-api.us-east-2.amazonaws.com"
+    
+    def __init__(self, api_key: str, base_url: str = DEFAULT_API_URL):
+        """
+        Initializes the client.
+        :param api_key: Your Willow API Key.
+        :param base_url: The base URL of the Willow API.
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip('/')
+        self.headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json"
+        }
+
+    def _fetch_model_payload(self, model_id: str, format_type: str) -> Union[bytes, dict]:
+        """Internal method to handle the HTTP request and Base64 decoding."""
+        url = f"{self.base_url}/export"
+        
+        # Legacy architecture routing abstraction:
+        # 'shopifyCustomerId' acts as the API identifier credential for the Oracle backend.
+        params = {
+            "analysisId": model_id,
+            "shopifyCustomerId": self.api_key, 
+            "format": format_type
+        }
+        
+        response = requests.get(url, params=params, headers=self.headers)
+        
+        if response.status_code != 200:
+            raise ConnectionError(f"Failed to fetch model {model_id}: {response.status_code} - {response.text}")
+
+        if format_type == "int8":
+            # The Willow Backend returns the binary payload as a Base64 string
+            return base64.b64decode(response.text)
+        else:
+            # Standard JSON payload
+            return response.json()
+
+    def get_model(self, model_id: str) -> WillowModel:
+        """
+        ON-DEMAND EPHEMERAL RAM: 
+        Fetches the highly-optimized .int8 model directly into an ephemeral memory buffer.
+        The model is parsed and ready for inference, never touching the physical disk.
+        """
+        raw_bytes = self._fetch_model_payload(model_id, format_type="int8")
+        memory_buffer = BytesIO(raw_bytes)
+        return parse_int8_model(memory_buffer)
+
+    def download_model(self, model_id: str, dest_path: str, format_type: str = "int8") -> str:
+        """
+        STORE LOCALLY: 
+        Fetches the model via the API and writes it to the local disk for offline usage.
+        :param dest_path: The file path to save the model to (e.g., './models/reload.int8').
+        :param format_type: 'int8' (recommended) or 'json'.
+        """
+        data = self._fetch_model_payload(model_id, format_type)
+        
+        mode = 'wb' if format_type == "int8" else 'w'
+        with open(dest_path, mode) as f:
+            if format_type == "int8":
+                f.write(data)
+            else:
+                json.dump(data, f, indent=2)
+                
+        return dest_path

willow_runtime-5.1.0/willow/detector.py

@@ -0,0 +1,124 @@
+import numpy as np
+from typing import List, Dict, Optional
+from .types import WillowModel
+from .math_kernels import fast_streaming_dtw_continuous, extract_rdm_signature
+
+class WillowDetector:
+    """
+    Core Runtime Engine for executing Zero-Shot Action Recognition locally.
+    """
+    def __init__(self, model: WillowModel):
+        self.model = model
+        self.cfg = model.config
+        
+        # State architecture for the Real-Time Streaming functionality
+        self._max_buffer_size = self.model.signature.shape[0] * 3
+        self._frame_buffer =[]
+        self._timestamp_buffer =[]
+        self._last_emitted_end_ms = -1
+
+    def detect(self, skeleton_sequence: np.ndarray, timestamps_ms: List[int]) -> List[Dict]:
+        """
+        PASSIVE MODE: Batch execution. Processes a full video array at once.
+        skeleton_sequence: Expected shape (Frames, 75, 3) or (Frames, 75, 4).
+        """
+        if skeleton_sequence.shape[0] != len(timestamps_ms):
+            raise ValueError("Skeleton sequence length must match timestamps array length.")
+
+        # 1. RDM Feature Extraction (Torso-Normalized)
+        test_sig = extract_rdm_signature(skeleton_sequence, self.cfg.zone_bitmask)
+        if len(test_sig) == 0: 
+            return[]
+
+        # 2. Continuous DTW Kernel
+        costs, lengths = fast_streaming_dtw_continuous(test_sig, self.model.signature)
+        
+        # Normalize costs to similarities (0.0 to 1.0)
+        similarities = np.clip(1.0 - (costs / self.cfg.dtw_sensitivity), 0.0, 1.0)
+        
+        occurrences =[]
+        n_frames = len(similarities)
+        
+        # 3. NMS with Terminal Peak Logic (Robust to Plateaus)
+        for i in range(1, n_frames):
+            # Check if this frame is a local maximum (Allowing plateaus via >=)
+            is_local_max = similarities[i] >= similarities[i-1]
+            
+            # Check falling edge (Strictly greater than next, or end of sequence)
+            # This ensures we pick the *end* of a plateau as the event timestamp
+            is_falling_edge = (i == n_frames - 1) or (similarities[i] > similarities[i+1])
+            
+            if similarities[i] >= 0.50 and is_local_max and is_falling_edge:
+                match_len = lengths[i]
+                start_idx = max(0, i - match_len)
+                
+                occurrences.append({
+                    "start_ms": timestamps_ms[start_idx],
+                    "end_ms": timestamps_ms[i],
+                    "confidence": float(similarities[i]),
+                    "start_idx": start_idx,
+                    "end_idx": i
+                })
+
+        # 4. Temporal Overlap Suppression (NMS)
+        occurrences.sort(key=lambda x: x['confidence'], reverse=True)
+        final_occurrences =[]
+        
+        for occ in occurrences:
+            is_overlapping = False
+            occ_dur = max(1, occ['end_ms'] - occ['start_ms'])
+            
+            for fin in final_occurrences:
+                latest_start = max(occ['start_ms'], fin['start_ms'])
+                earliest_end = min(occ['end_ms'], fin['end_ms'])
+                overlap_dur = max(0, earliest_end - latest_start)
+                
+                if overlap_dur > 0:
+                    overlap_ratio = overlap_dur / occ_dur
+                    if overlap_ratio > self.cfg.overlap_tolerance:
+                        is_overlapping = True
+                        break
+                        
+            if not is_overlapping:
+                final_occurrences.append(occ)
+
+        # Return chronologically sorted
+        final_occurrences.sort(key=lambda x: x['start_ms'])
+        
+        # Clean internal indices for pristine API output
+        for o in final_occurrences:
+            del o['start_idx']
+            del o['end_idx']
+            
+        return final_occurrences
+
+    def step(self, current_frame_skeleton: np.ndarray, timestamp_ms: int) -> Optional[Dict]:
+        """
+        ACTIVE MODE: Real-Time Streaming loop for live webcam or robotics edge processing.
+        Ingests a single frame (75, 3) and yields an event the millisecond an action completes.
+        """
+        # 1. Manage Ring Buffer
+        self._frame_buffer.append(current_frame_skeleton)
+        self._timestamp_buffer.append(timestamp_ms)
+        
+        if len(self._frame_buffer) > self._max_buffer_size:
+            self._frame_buffer.pop(0)
+            self._timestamp_buffer.pop(0)
+            
+        # Needs minimum history to run DTW
+        if len(self._frame_buffer) < self.model.signature.shape[0]:
+            return None
+            
+        # 2. Execute Batch Detect on the sliding window
+        window_arr = np.array(self._frame_buffer)
+        window_matches = self.detect(window_arr, self._timestamp_buffer)
+        
+        # 3. Filter for Zero-Latency Events
+        for match in window_matches:
+            # If the match completed EXACTLY on this millisecond, emit it.
+            # And ensure we haven't already emitted it due to sliding window overlap.
+            if match['end_ms'] == timestamp_ms and match['end_ms'] > self._last_emitted_end_ms:
+                self._last_emitted_end_ms = match['end_ms']
+                return match
+                
+        return None

willow_runtime-5.1.0/willow/evaluator.py

@@ -0,0 +1,35 @@
+import numpy as np
+
+class PhysicsEvaluator:
+    """
+    Ports the Da Vinci Backend's physics derivatives to the Edge.
+    Allows real-time coaching apps to evaluate speed, acceleration, and jerk.
+    """
+
+    @staticmethod
+    def calculate_derivatives(end_effector_trajectory: np.ndarray, fps: float) -> dict:
+        """
+        Calculates Speed (m/s), Acceleration (m/s^2), and Jerk (m/s^3) 
+        for a specific 3D trajectory sequence.
+        """
+        dt = 1.0 / fps if fps > 0 else 0.033
+        
+        # 1st Derivative: Velocity
+        velocity = np.gradient(end_effector_trajectory, dt, axis=0)
+        speed = np.linalg.norm(velocity, axis=1)
+        
+        # 2nd Derivative: Acceleration
+        acceleration = np.gradient(velocity, dt, axis=0)
+        accel_mag = np.linalg.norm(acceleration, axis=1)
+        
+        # 3rd Derivative: Jerk (Smoothness penalty)
+        jerk = np.gradient(acceleration, dt, axis=0)
+        jerk_mag = np.linalg.norm(jerk, axis=1)
+
+        return {
+            "speed_mps": speed,
+            "acceleration_mps2": accel_mag,
+            "jerk_mps3": jerk_mag,
+            "peak_speed": float(np.max(speed)),
+            "peak_jerk": float(np.max(jerk_mag))
+        }

willow_runtime-5.1.0/willow/math_kernels.py

@@ -0,0 +1,106 @@
+import numpy as np
+from numba import jit
+from .types import ZONES
+
+@jit(nopython=True)
+def fast_streaming_dtw_continuous(test_seq, seed_seq):
+    """
+    Space-Optimized O(M) Subsequence DTW. 
+    Returns the normalized cost vector and match length for every frame.
+    """
+    N = test_seq.shape[0]
+    M = seed_seq.shape[0]
+    
+    cost_array = np.full(N, np.inf)
+    length_array = np.zeros(N, dtype=np.int32)
+    if M == 0 or N == 0: 
+        return cost_array, length_array
+    
+    D_prev = np.full(M + 1, np.inf)
+    D_curr = np.full(M + 1, np.inf)
+    D_prev[0] = 0.0
+    
+    S_prev = np.zeros(M + 1, dtype=np.int32)
+    S_curr = np.zeros(M + 1, dtype=np.int32)
+
+    for i in range(1, N + 1):
+        D_curr[0] = 0.0
+        S_curr[0] = i - 1 
+        
+        for j in range(1, M + 1):
+            dist = 0.0
+            for k in range(test_seq.shape[1]):
+                diff = test_seq[i-1, k] - seed_seq[j-1, k]
+                dist += diff * diff
+            cost = np.sqrt(dist)
+            
+            if D_prev[j-1] <= D_prev[j] and D_prev[j-1] <= D_curr[j-1]:
+                prev_cost, S_curr[j] = D_prev[j-1], S_prev[j-1]
+            elif D_prev[j] <= D_curr[j-1]:
+                prev_cost, S_curr[j] = D_prev[j], S_prev[j]
+            else:
+                prev_cost, S_curr[j] = D_curr[j-1], S_curr[j-1]
+                
+            D_curr[j] = cost + prev_cost
+        
+        # Save the normalized alignment cost ending at THIS specific frame
+        cost_array[i-1] = D_curr[M] / M
+        length_array[i-1] = (i - 1) - S_curr[M]
+
+        for j in range(M + 1):
+            D_prev[j] = D_curr[j]
+            S_prev[j] = S_curr[j]
+
+    return cost_array, length_array
+
+def extract_rdm_signature(skeleton_sequence: np.ndarray, bitmask: int) -> np.ndarray:
+    """
+    Extracts the Scale-Invariant Relative Distance Matrix (RDM).
+    Strictly adheres to the Torso-Length Normalization mandate.
+    """
+    # Resolve active joint indices based on binary bitmask
+    active_indices =[]
+    for name, (bit, indices) in ZONES.items():
+        if bitmask & bit:
+            active_indices.extend(indices)
+            
+    if not active_indices:
+        active_indices = ZONES["torso"][1]  # Failsafe
+
+    n_joints = len(active_indices)
+    dim = int(n_joints * (n_joints - 1) / 2)
+    frames = skeleton_sequence.shape[0]
+    has_vis = skeleton_sequence.shape[2] == 4 if frames > 0 else False
+
+    signature = np.zeros((frames, dim), dtype=np.float32)
+    CONF_THRESH = 0.5 
+
+    for f in range(frames):
+        lms = skeleton_sequence[f]
+        if np.all(lms == 0):
+            continue
+        
+        # --- WILLOW 5 DIRECTIVE: Strict Torso-Length Normalization ---
+        # 3D distance between the midpoint of shoulders (11, 12) and hips (23, 24)
+        mid_shoulder = (lms[11][:3] + lms[12][:3]) / 2.0
+        mid_hip = (lms[23][:3] + lms[24][:3]) / 2.0
+        torso_length = np.linalg.norm(mid_shoulder - mid_hip)
+        
+        scale = max(torso_length, 0.01)  # Avoid division by zero
+        
+        idx = 0
+        for i in range(n_joints):
+            for j in range(i + 1, n_joints):
+                idx1, idx2 = active_indices[i], active_indices[j]
+                
+                v1 = lms[idx1][3] if has_vis else 1.0
+                v2 = lms[idx2][3] if has_vis else 1.0
+                
+                if (v1 * v2) >= (CONF_THRESH * CONF_THRESH):
+                    dist = np.linalg.norm(lms[idx1][:3] - lms[idx2][:3]) / scale
+                    signature[f, idx] = dist
+                else:
+                    signature[f, idx] = 0.0  # Mask out low confidence
+                idx += 1
+
+    return signature

willow_runtime-5.1.0/willow/parsers.py

@@ -0,0 +1,87 @@
+import os
+import json
+import struct
+import numpy as np
+from io import BytesIO
+from typing import Union
+from .types import WillowConfig, WillowModel, ZONES
+
+def parse_int8_model(data: Union[bytes, BytesIO]) -> WillowModel:
+    """
+    Parses the secure Willow V4.0 .int8 binary format.
+    Executes entirely in RAM (Zero physical disk footprint).
+    """
+    if isinstance(data, BytesIO):
+        buffer = data.read()
+    else:
+        buffer = data
+
+    if len(buffer) < 24:
+        raise ValueError("Invalid Willow Binary: Header too short.")
+
+    # Strict Little-Endian 24-Byte Header parsing
+    header = struct.unpack('<IIffff', buffer[:24])
+    version, bitmask, scale, overlap, dtw_sens, tempo = header
+
+    if version != 40:
+        raise ValueError(f"Unsupported model version: {version}. Expected 40 (V4.0).")
+
+    config = WillowConfig(
+        version=version,
+        zone_bitmask=bitmask,
+        overlap_tolerance=overlap,
+        dtw_sensitivity=dtw_sens,
+        tempo_variance=tempo
+    )
+
+    # Resolve dimension size from bitmask to reshape flat array
+    n_joints = sum(len(indices) for bit, indices in ZONES.values() if bitmask & bit)
+    dim = int(n_joints * (n_joints - 1) / 2)
+
+    # Fast De-Quantization
+    raw_int8 = np.frombuffer(buffer[24:], dtype=np.int8)
+    signature = (raw_int8.astype(np.float32) / 127.0) * scale
+    
+    # Reshape to (Frames, Features)
+    signature = signature.reshape(-1, dim)
+
+    return WillowModel(config=config, signature=signature)
+
+def parse_json_model(data: Union[str, dict]) -> WillowModel:
+    """
+    Fallback parser for standard web JSON signatures.
+    """
+    if isinstance(data, str):
+        payload = json.loads(data)
+    else:
+        payload = data
+        
+    cfg = payload.get("calibration_config", {})
+    
+    config = WillowConfig(
+        version=int(float(cfg.get("version", 4.0)) * 10),
+        zone_bitmask=int(cfg.get("zone_bitmask", 2)),
+        overlap_tolerance=float(cfg.get("overlap_tolerance", 0.25)),
+        dtw_sensitivity=float(cfg.get("dtw_sensitivity", 3.0)),
+        tempo_variance=float(cfg.get("tempo_variance", 0.20))
+    )
+    
+    signature = np.array(payload.get("signature",[]), dtype=np.float32)
+    return WillowModel(config=config, signature=signature)
+
+def load_local_model(filepath: str) -> WillowModel:
+    """
+    Loads a Willow model directly from a local file.
+    Use this if you downloaded the model manually via the Willow Web Interface.
+    """
+    if not os.path.exists(filepath):
+        raise FileNotFoundError(f"Model file not found: {filepath}")
+
+    if filepath.endswith('.json'):
+        with open(filepath, 'r') as f:
+            payload = json.load(f)
+            return parse_json_model(payload)
+    else:
+        # Assumes .int8 or .bin optimized format
+        with open(filepath, 'rb') as f:
+            return parse_int8_model(f.read())

willow_runtime-5.1.0/willow/retargeting.py

@@ -0,0 +1,52 @@
+import numpy as np
+
+class KinematicRetargeter:
+    """
+    Extracts joint angles (Euler approximations) from raw 3D point clouds.
+    Required for Reinforcement Learning (RL) simulation environments.
+    """
+
+    @staticmethod
+    def _angle_between_vectors(v1: np.ndarray, v2: np.ndarray) -> np.ndarray:
+        n1 = np.linalg.norm(v1, axis=1)
+        n2 = np.linalg.norm(v2, axis=1)
+        # Avoid division by zero
+        mask = (n1 > 0) & (n2 > 0)
+        angles = np.zeros(v1.shape[0])
+        dot_prod = np.sum(v1 * v2, axis=1)
+        cos_theta = np.clip(dot_prod[mask] / (n1[mask] * n2[mask]), -1.0, 1.0)
+        angles[mask] = np.degrees(np.arccos(cos_theta))
+        return angles
+
+    @staticmethod
+    def extract_joint_angles(skeleton_seq: np.ndarray) -> dict:
+        """
+        Returns a dictionary of critical 1D joint angle arrays over time.
+        """
+        # Willow topology keys
+        L_SHOULDER, L_ELBOW, L_WRIST = 11, 13, 15
+        R_SHOULDER, R_ELBOW, R_WRIST = 12, 14, 16
+        L_HIP, L_KNEE, L_ANKLE = 23, 25, 27
+        R_HIP, R_KNEE, R_ANKLE = 24, 26, 28
+
+        angles = {}
+
+        # 1. Elbow Flexions
+        l_upper_arm = skeleton_seq[:, L_SHOULDER, :3] - skeleton_seq[:, L_ELBOW, :3]
+        l_forearm = skeleton_seq[:, L_WRIST, :3] - skeleton_seq[:, L_ELBOW, :3]
+        angles["left_elbow_flexion"] = KinematicRetargeter._angle_between_vectors(l_upper_arm, l_forearm)
+
+        r_upper_arm = skeleton_seq[:, R_SHOULDER, :3] - skeleton_seq[:, R_ELBOW, :3]
+        r_forearm = skeleton_seq[:, R_WRIST, :3] - skeleton_seq[:, R_ELBOW, :3]
+        angles["right_elbow_flexion"] = KinematicRetargeter._angle_between_vectors(r_upper_arm, r_forearm)
+
+        # 2. Knee Flexions
+        l_thigh = skeleton_seq[:, L_HIP, :3] - skeleton_seq[:, L_KNEE, :3]
+        l_calf = skeleton_seq[:, L_ANKLE, :3] - skeleton_seq[:, L_KNEE, :3]
+        angles["left_knee_flexion"] = KinematicRetargeter._angle_between_vectors(l_thigh, l_calf)
+
+        r_thigh = skeleton_seq[:, R_HIP, :3] - skeleton_seq[:, R_KNEE, :3]
+        r_calf = skeleton_seq[:, R_ANKLE, :3] - skeleton_seq[:, R_KNEE, :3]
+        angles["right_knee_flexion"] = KinematicRetargeter._angle_between_vectors(r_thigh, r_calf)
+
+        return angles

willow_runtime-5.1.0/willow/transforms.py

@@ -0,0 +1,35 @@
+import numpy as np
+
+class CoordinateBridge:
+    """
+    Bridges the standard Willow space (MediaPipe: X-Right, Y-Down, Z-Forward) 
+    to industry-standard spaces for Robotics and VR/AR.
+    """
+
+    @staticmethod
+    def to_ros_z_up(skeleton_seq: np.ndarray) -> np.ndarray:
+        """
+        Translates to ROS/Isaac Sim Standard (Z-Up, Right-Handed).
+        Maps: MP_X -> ROS_X, MP_Z -> ROS_Y, -MP_Y -> ROS_Z
+        """
+        transformed = np.zeros_like(skeleton_seq)
+        transformed[..., 0] = skeleton_seq[..., 0]   # X = X
+        transformed[..., 1] = skeleton_seq[..., 2]   # Y = Depth
+        transformed[..., 2] = -skeleton_seq[..., 1]  # Z = Up
+        if skeleton_seq.shape[-1] == 4:
+            transformed[..., 3] = skeleton_seq[..., 3]
+        return transformed
+
+    @staticmethod
+    def to_unity_y_up(skeleton_seq: np.ndarray) -> np.ndarray:
+        """
+        Translates to Unity/Unreal Standard (Y-Up, Left-Handed).
+        Maps: MP_X -> Unity_X, -MP_Y -> Unity_Y, MP_Z -> Unity_Z
+        """
+        transformed = np.zeros_like(skeleton_seq)
+        transformed[..., 0] = skeleton_seq[..., 0]
+        transformed[..., 1] = -skeleton_seq[..., 1]
+        transformed[..., 2] = skeleton_seq[..., 2]
+        if skeleton_seq.shape[-1] == 4:
+            transformed[..., 3] = skeleton_seq[..., 3]
+        return transformed

willow_runtime-5.1.0/willow/types.py

@@ -0,0 +1,28 @@
+import dataclasses
+import numpy as np
+
+# Willow Standard 75-Point Topology Map
+# Maps logical zones to their respective 3D joint indices
+ZONES = {
+    "head":  (1,[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]),
+    "torso": (2,[11, 12, 23, 24]),
+    "arms":  (4,[13, 14, 15, 16]),
+    "hands": (8,  list(range(33, 75))),
+    "legs":  (16,[25, 26, 27, 28]),
+    "feet":  (32,[29, 30, 31, 32])
+}
+
+@dataclasses.dataclass
+class WillowConfig:
+    """Configuration derived from the 24-Byte .int8 Model Header."""
+    version: int
+    zone_bitmask: int
+    overlap_tolerance: float
+    dtw_sensitivity: float
+    tempo_variance: float
+
+@dataclasses.dataclass
+class WillowModel:
+    """The runtime representation of an Action Model."""
+    config: WillowConfig
+    signature: np.ndarray  # The Float32 De-quantized RDM Matrix

willow_runtime-5.1.0/willow_runtime.egg-info/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: willow-runtime
+Version: 5.1.0
+Summary: Willow 5 Runtime: Action Recognition, Retargeting, & Edge Evaluator
+Author: Willow Dynamics
+License: MIT
+Project-URL: Homepage, https://willowdynamics.com
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: numba>=0.56.0
+Requires-Dist: requests>=2.25.0
+Dynamic: license-file
+
+# Willow 5 Runtime SDK
+
+The official Python SDK for **Willow Dynamics**.
+
+This SDK acts as the bridge between the Willow Cloud Oracle and your local environment. It enables **Zero-Shot Action Recognition**, **Kinematic Retargeting**, and **Physics Evaluation** on edge devices, cloud pipelines, and simulation clusters.
+
+It is designed to be dependency-light (No AWS/Boto3 required) and privacy-first (Models run in ephemeral RAM).
+
+---
+
+## Installation
+
+```bash
+pip install willow-runtime
+```
+
+---
+
+## 1. Quick Start: Model Provisioning
+
+Securely fetch your proprietary action models from the Willow Cloud.
+
+```python
+from willow import WillowClient
+
+# Initialize with your API Key
+client = WillowClient(api_key="YOUR_WILLOW_API_KEY")
+
+# Option A: Stream directly to RAM (Secure / Cloud / Ephemeral)
+# The model never touches the physical disk.
+model = client.get_model("tactical-reload-v1")
+
+# Option B: Download to Disk (Offline / Edge / Air-Gapped)
+client.download_model("tactical-reload-v1", "./models/reload.int8")
+```
+
+---
+
+## 2. Usage: Active Streaming (Real-Time)
+
+Best for **Robotics**, **Webcams**, or **Smart Gyms** where frames arrive one by one. The `step()` method manages an internal sliding window buffer for zero-latency triggering.
+
+```python
+from willow import WillowClient, WillowDetector
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("tactical-reload-v1")
+detector = WillowDetector(model)
+
+# 2. The Real-Time Loop
+# Assume 'get_next_frame()' returns a (75, 3) numpy array of skeletal data
+while True:
+    current_skeleton, timestamp_ms = get_next_frame()
+    
+    # .step() executes in <2ms on modern CPUs
+    event = detector.step(current_skeleton, timestamp_ms)
+    
+    if event:
+        print(f"!!! ACTION DETECTED !!!")
+        print(f"Timestamp: {event['end_ms']}ms | Confidence: {event['confidence']:.2f}")
+        
+        # Trigger Actuator / Robot / UI here
+```
+
+---
+
+## 3. Usage: Batch Analysis (Passive)
+
+Best for **Data Science**, **Historical Video Processing**, or **Cloud ETL** pipelines.
+
+```python
+from willow import WillowClient, WillowDetector
+import numpy as np
+
+# 1. Load Model
+client = WillowClient(api_key="YOUR_API_KEY")
+model = client.get_model("golf-swing-v4")
+detector = WillowDetector(model)
+
+# 2. Load Data (e.g., from an uploaded video file processed by MediaPipe)
+# Shape: (Frames, 75, 3)
+full_sequence = np.load("recording_data.npy") 
+timestamps = [t * 33 for t in range(len(full_sequence))]
+
+# 3. Detect All Occurrences
+matches = detector.detect(full_sequence, timestamps)
+
+print(f"Found {len(matches)} events:")
+for m in matches:
+    print(f" - {m['start_ms']}ms to {m['end_ms']}ms (Conf: {m['confidence']:.2f})")
+```
+
+---
+
+## 4. Usage: Sim-to-Real & Robotics
+
+Best for **Reinforcement Learning (RL)**, **NVIDIA Isaac Sim**, and **Humanoid Teleoperation**. Bridges the gap between Computer Vision coordinates and Robotics standards.
+
+```python
+from willow import CoordinateBridge, KinematicRetargeter
+
+# 1. Convert Coordinate Space
+# MediaPipe (Y-Down) -> ROS/Isaac Sim (Z-Up)
+ros_ready_sequence = CoordinateBridge.to_ros_z_up(raw_skeleton_sequence)
+
+# 2. Extract Joint Angles for RL Training
+# Returns dictionary of 1D angle arrays (e.g., "right_elbow_flexion")
+joint_angles = KinematicRetargeter.extract_joint_angles(ros_ready_sequence)
+
+print(f"Extracted {len(joint_angles)} joint features for simulation training.")
+```
+
+---
+
+## License
+
+MIT License. Copyright (c) 2025 Willow Dynamics.

willow_runtime-5.1.0/willow_runtime.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE.txt
+README.md
+pyproject.toml
+tests/test_willow_sdk.py
+willow/__init__.py
+willow/client.py
+willow/detector.py
+willow/evaluator.py
+willow/math_kernels.py
+willow/parsers.py
+willow/retargeting.py
+willow/transforms.py
+willow/types.py
+willow_runtime.egg-info/PKG-INFO
+willow_runtime.egg-info/SOURCES.txt
+willow_runtime.egg-info/dependency_links.txt
+willow_runtime.egg-info/requires.txt
+willow_runtime.egg-info/top_level.txt

willow_runtime-5.1.0/willow_runtime.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

willow_runtime-5.1.0/willow_runtime.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy>=1.21.0
+numba>=0.56.0
+requests>=2.25.0

willow_runtime-5.1.0/willow_runtime.egg-info/top_level.txt

@@ -0,0 +1 @@
+willow