luckyrobots 0.1.68__py3-none-any.whl → 0.1.69__py3-none-any.whl

luckyrobots/{utils/helpers.py → utils.py}

@@ -1,18 +1,87 @@
-import yaml
+"""
+Utility functions and classes for LuckyRobots.
+"""
+
 import time
+import yaml
 import importlib.resources
 from collections import deque
 
 
+class FPS:
+    """Utility for measuring frames per second with a rolling window.
+
+    Usage:
+        fps = FPS(frame_window=30)
+        while running:
+            # ... do work ...
+            current_fps = fps.measure()
+    """
+
+    def __init__(self, frame_window: int = 30):
+        """Initialize FPS counter.
+
+        Args:
+            frame_window: Number of frames to average over.
+        """
+        self.frame_window = frame_window
+        self.frame_times: deque[float] = deque(maxlen=frame_window)
+        self.last_frame_time = time.perf_counter()
+
+    def measure(self) -> float:
+        """Record a frame and return current FPS.
+
+        Returns:
+            Current frames per second (averaged over window).
+        """
+        current_time = time.perf_counter()
+        frame_delta = current_time - self.last_frame_time
+        self.last_frame_time = current_time
+
+        self.frame_times.append(frame_delta)
+
+        if len(self.frame_times) >= 2:
+            avg_frame_time = sum(self.frame_times) / len(self.frame_times)
+            return 1.0 / avg_frame_time if avg_frame_time > 0 else 0.0
+        return 0.0
+
+
+def get_robot_config(robot: str = None) -> dict:
+    """Get the configuration for a robot from robots.yaml.
+
+    Args:
+        robot: Robot name. If None, returns entire config.
+
+    Returns:
+        Robot configuration dict, or full config if robot is None.
+    """
+    with importlib.resources.files("luckyrobots").joinpath("config/robots.yaml").open(
+        "r"
+    ) as f:
+        config = yaml.safe_load(f)
+        if robot is not None:
+            return config[robot]
+        else:
+            return config
+
+
 def validate_params(
     scene: str = None,
     robot: str = None,
     task: str = None,
     observation_type: str = None,
-) -> bool:
-    """Validate the parameters passed into Lucky World"""
-    robot_config = get_robot_config(robot)
+) -> None:
+    """Validate parameters for launching LuckyEngine.
+
+    Args:
+        scene: Scene name.
+        robot: Robot name.
+        task: Task name.
+        observation_type: Observation type.
 
+    Raises:
+        ValueError: If any parameter is invalid.
+    """
     if scene is None:
         raise ValueError("Scene is required")
     if robot is None:
@@ -22,6 +91,8 @@ def validate_params(
     if observation_type is None:
         raise ValueError("Observation type is required")
 
+    robot_config = get_robot_config(robot)
+
     if scene not in robot_config["available_scenes"]:
         raise ValueError(f"Scene {scene} not available in {robot} config")
     if task not in robot_config["available_tasks"]:
@@ -30,39 +101,3 @@ def validate_params(
         raise ValueError(
             f"Observation type {observation_type} not available in {robot} config"
         )
-
-
-def get_robot_config(robot: str = None) -> dict:
-    """Get the configuration for the robot"""
-    with importlib.resources.files("luckyrobots").joinpath("config/robots.yaml").open(
-        "r"
-    ) as f:
-        config = yaml.safe_load(f)
-        if robot is not None:
-            return config[robot]
-        else:
-            return config
-
-
-class FPS:
-    def __init__(self, frame_window: int = 30):
-        self.frame_window = frame_window
-        self.frame_times = deque(maxlen=frame_window)
-        self.last_frame_time = time.perf_counter()
-
-    def measure(self) -> float:
-        current_time = time.perf_counter()
-        frame_delta = current_time - self.last_frame_time
-        self.last_frame_time = current_time
-
-        # Add frame time to rolling window
-        self.frame_times.append(frame_delta)
-
-        # Calculate FPS from average frame time
-        if len(self.frame_times) >= 2:  # Need at least 2 samples
-            avg_frame_time = sum(self.frame_times) / len(self.frame_times)
-            fps = 1.0 / avg_frame_time if avg_frame_time > 0 else 0
-        else:
-            fps = 0
-
-        print(f"FPS: {fps}")

luckyrobots-0.1.69.dist-info/METADATA

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: luckyrobots
+Version: 0.1.69
+Summary: Robotics-AI Training in Hyperrealistic Game Environments
+Project-URL: Homepage, https://github.com/luckyrobots/luckyrobots
+Project-URL: Documentation, https://luckyrobots.readthedocs.io
+Project-URL: Repository, https://github.com/luckyrobots/luckyrobots
+Project-URL: Issues, https://github.com/luckyrobots/luckyrobots/issues
+Author-email: Devrim Yasar <braces.verbose03@icloud.com>, Ethan Clark <ethan@luckyrobots.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: opencv-python>=4.8.0
+Requires-Dist: packaging>=23.0
+Requires-Dist: protobuf>=4.25.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: watchdog>=3.0.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img width="384" alt="Default_Logo_Horizontal@2x" src="https://github.com/user-attachments/assets/ae6ad53a-741e-4e7a-94cb-5a46a8e81398" />
+</p>
+
+<p align="center">
+   Infinite synthetic data generation for embodied AI
+</p>
+
+<div align="center">
+
+[![PyPI version](https://img.shields.io/pypi/v/luckyrobots.svg)](https://pypi.org/project/luckyrobots/)
+[![Documentation](https://img.shields.io/badge/docs-read%20the%20docs-blue)](https://luckyrobots.readthedocs.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python Version](https://img.shields.io/pypi/pyversions/luckyrobots)](https://pypi.org/project/luckyrobots/)
+[![Status](https://img.shields.io/badge/Status-Alpha-orange)](https://pypi.org/project/luckyrobots/)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2?logo=discord&logoColor=white)](https://discord.gg/5CH3wx3tAs)
+
+</div>
+
+https://github.com/user-attachments/assets/0ab2953d-b188-4af7-a225-71decdd2378c
+
+# Lucky Robots
+
+Hyperrealistic robotics simulation framework with Python API for embodied AI training and testing.
+
+<p align="center">
+  <img width="49%" alt="Bedroom environment in LuckyEngine" src="https://github.com/user-attachments/assets/279a7864-9a8b-453e-8567-3a174f5db8ab" />
+  <img width="49%" alt="Open floor plan in LuckyEngine" src="https://github.com/user-attachments/assets/68c72b97-98ab-42b0-a065-8a4247b014c7" />
+</p>
+
+## Quick Start
+
+1. **Download LuckyEngine** from our [releases page](https://github.com/luckyrobots/luckyrobots/releases/latest) and set the path:
+   ```bash
+   # Set environment variable (choose one method):
+
+   # Method 1: Set LUCKYENGINE_PATH directly to the executable
+   export LUCKYENGINE_PATH=/path/to/LuckyEngine      # Linux/Mac
+   export LUCKYENGINE_PATH=/path/to/LuckyEngine.exe  # Windows
+
+   # Method 2: Set LUCKYENGINE_HOME to the directory containing the executable
+   export LUCKYENGINE_HOME=/path/to/luckyengine/directory
+   ```
+
+2. **Install**
+   ```bash
+   pip install luckyrobots
+   ```
+
+3. **Run Example**
+   ```bash
+   git clone https://github.com/luckyrobots/luckyrobots.git
+   cd luckyrobots/examples
+   python controller.py --skip-launch  # If LuckyEngine is already running
+   ```
+
+## Basic Usage
+
+```python
+from luckyrobots import LuckyEngineClient
+
+# Connect to LuckyEngine
+client = LuckyEngineClient(
+    host="127.0.0.1",
+    port=50051,
+    robot_name="unitreego1",
+)
+client.wait_for_server()
+
+# Optional: Fetch schema for named observation access
+client.fetch_schema()
+
+# Get RL observation
+obs = client.get_observation()
+print(f"Observation: {obs.observation[:5]}...")  # Flat vector for RL
+print(f"Timestamp: {obs.timestamp_ms}")
+
+# Named access (if schema fetched)
+# obs["proj_grav_x"]  # Access by name
+# obs.to_dict()       # Convert to dict
+
+# Send controls
+client.send_control(controls=[0.1, 0.2, -0.1, ...])
+
+# Get joint state (separate from RL observation)
+joints = client.get_joint_state()
+print(f"Positions: {joints.positions}")
+print(f"Velocities: {joints.velocities}")
+```
+
+## API Overview
+
+### Core Classes
+
+**`LuckyEngineClient`** - Low-level gRPC client
+- `wait_for_server(timeout)` - Wait for LuckyEngine connection
+- `get_observation()` - Get RL observation vector
+- `get_joint_state()` - Get joint positions/velocities
+- `send_control(controls)` - Send actuator commands
+- `get_agent_schema()` - Get observation/action names and sizes
+- `reset_agent()` - Reset agent state
+
+**`LuckyRobots`** - High-level wrapper (launches LuckyEngine)
+- `start(scene, robot, task)` - Launch and connect
+- `get_observation()` - Get observation
+- `step(controls)` - Send controls and get next observation
+
+### Models
+
+```python
+from luckyrobots import ObservationResponse, StateSnapshot
+
+# ObservationResponse - returned by get_observation()
+obs.observation      # List[float] - flat RL observation vector
+obs.actions          # List[float] - last applied actions
+obs.timestamp_ms     # int - wall-clock timestamp
+obs.frame_number     # int - monotonic counter
+obs["name"]          # Named access (if schema fetched)
+obs.to_dict()        # Convert to name->value dict
+```
+
+## Available Robots & Environments
+
+### Robots
+- **unitreego1**: Quadruped robot
+- **so100**: 6-DOF manipulator with gripper
+- **stretch_v1**: Mobile manipulator
+
+### Scenes
+- **velocity**: Velocity control training
+- **kitchen**: Residential kitchen environment
+
+### Tasks
+- **locomotion**: Walking/movement
+- **pickandplace**: Object manipulation
+
+## Development
+
+### Setup with uv (recommended)
+
+```bash
+# Clone and enter repo
+git clone https://github.com/luckyrobots/luckyrobots.git
+cd luckyrobots
+
+# Install uv if you haven't
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Create venv and install deps
+uv sync
+
+# Run tests
+uv run pytest
+
+# Run example
+uv run python examples/controller.py --skip-launch
+```
+
+### Setup with pip
+
+```bash
+git clone https://github.com/luckyrobots/luckyrobots.git
+cd luckyrobots
+pip install -e ".[dev]"
+```
+
+### Regenerating gRPC Stubs
+
+The Python gRPC stubs are in `src/luckyrobots/grpc/generated/` and are
+generated from protos in `src/luckyrobots/grpc/proto/`.
+
+```bash
+python -m grpc_tools.protoc \
+  -I "src/luckyrobots/grpc/proto" \
+  --python_out="src/luckyrobots/grpc/generated" \
+  --grpc_python_out="src/luckyrobots/grpc/generated" \
+  src/luckyrobots/grpc/proto/*.proto
+```
+
+### Project Structure
+
+```
+src/luckyrobots/
+├── client.py            # LuckyEngineClient (main API)
+├── luckyrobots.py       # LuckyRobots high-level wrapper
+├── models/              # Pydantic models
+│   ├── observation.py   # ObservationResponse, StateSnapshot
+│   └── camera.py        # CameraData, CameraShape
+├── engine/              # Engine management
+├── grpc/                # gRPC internals
+│   ├── generated/       # Protobuf stubs
+│   └── proto/           # .proto files
+└── config/              # Robot configurations
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes and add tests
+4. Run `uv run ruff check .` and `uv run ruff format .`
+5. Submit a pull request
+
+## Architecture
+
+Lucky Robots uses gRPC for communication:
+
+- **LuckyEngine**: Physics + rendering backend (Unreal Engine + MuJoCo)
+- **Python client**: Connects via gRPC (default `127.0.0.1:50051`)
+
+### gRPC Services
+
+| Service | Status | Description |
+|---------|--------|-------------|
+| MujocoService | ✅ Working | Joint state, controls |
+| AgentService | ✅ Working | Observations, reset |
+| SceneService | 🚧 Placeholder | Scene inspection |
+| TelemetryService | 🚧 Placeholder | Telemetry streaming |
+| CameraService | 🚧 Placeholder | Camera frames |
+| ViewportService | 🚧 Placeholder | Viewport pixels |
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/luckyrobots/luckyrobots/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/luckyrobots/luckyrobots/discussions)
+- **Discord**: [Community Server](https://discord.gg/5CH3wx3tAs)

luckyrobots-0.1.69.dist-info/RECORD

@@ -0,0 +1,44 @@
+luckyrobots/__init__.py,sha256=3hJT7tvGfzU6-PzXICpv4O9SNAiuFhE95o0_dTxLi7Y,739
+luckyrobots/client.py,sha256=D81pk16ZFKP_uYDSJAur_aucRu7eW2JXW0s63HAYWfQ,28935
+luckyrobots/luckyrobots.py,sha256=F68TUhKplLbdkuARGGUer9jSf1QUzLhu1Rfc-vqDZso,6788
+luckyrobots/utils.py,sha256=62BqpSRBFykVRMZ5Ti2F-yKRDoyU3UNHeesDF_PVCFc,2958
+luckyrobots/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+luckyrobots/config/robots.yaml,sha256=Wu2AgwhZxo9F-RLcqPJXHnqzjT8a0wR-rFBcecck_eE,5164
+luckyrobots/engine/__init__.py,sha256=-3r7aLueDF7eyumqIhTvYqS8ZNnVSJUJEHG4ybsKrjc,546
+luckyrobots/engine/check_updates.py,sha256=KGQHrj1LB0_vexktO01xx-ZvPOYKkto4VBb3H1KV7uI,7593
+luckyrobots/engine/download.py,sha256=vIb5T40Jk2BnfjPo0f4KgW14Om6P4_mvPpZ9JAlkVvg,4029
+luckyrobots/engine/manager.py,sha256=8vxSevaoXo-lw2G6y74lVc-Ms8xIELK0yLswydMiOQY,13388
+luckyrobots/grpc/__init__.py,sha256=hPh-X_FEus2sxrfQB2fQjD754X5bMaUFTWm3mZmUhe0,153
+luckyrobots/grpc/generated/__init__.py,sha256=u69M4E_2LwRQSD_n4wvQyMX7dryBCrIdsho59c52Crk,732
+luckyrobots/grpc/generated/agent_pb2.py,sha256=71ILNgwKLNhfiTsU8ocZTasG-hNViF03Cn3-ldBvc9A,5728
+luckyrobots/grpc/generated/agent_pb2_grpc.py,sha256=LAiYHz2UhQNFCKYmm4FeKnSIVXpAoR9CpWiIKTu1Bro,8962
+luckyrobots/grpc/generated/camera_pb2.py,sha256=QGxa8sfMqzzdShyA7RVXLWsfSzXZ0Kg7cPSZYYl6E2c,2664
+luckyrobots/grpc/generated/camera_pb2_grpc.py,sha256=u7jimo_r0ThMmQOl43IXoyWNGIX2T583mv4xcCBciqk,5212
+luckyrobots/grpc/generated/common_pb2.py,sha256=puH7AOneT8K5FjcW2PjnUY6e2u-vobtnS4bpaPl4nhM,2073
+luckyrobots/grpc/generated/common_pb2_grpc.py,sha256=kFXVJY9Ju1lO1ramSeiLiMAZBYWBDrDaON96j2C3rXI,901
+luckyrobots/grpc/generated/media_pb2.py,sha256=FUgow9NoFf9DztuVrrokGXxuJBHFb0AKBQAc3aez7BU,1839
+luckyrobots/grpc/generated/media_pb2_grpc.py,sha256=AqZmnqqFTTxtFC5bsA-YygCMD93BTRSb97RBovHCARo,900
+luckyrobots/grpc/generated/mujoco_pb2.py,sha256=20UVm-fptmjfv17L06HKSTkMyVZwKa-aPzaltAUaNSA,3540
+luckyrobots/grpc/generated/mujoco_pb2_grpc.py,sha256=HDroQ6_HgaG06WxLsMwo6DHze3Or8bGXlhJln8Oqwfo,8442
+luckyrobots/grpc/generated/scene_pb2.py,sha256=ggZ5ZqMoYyWY4MShDG6S7TTH7HIa3_uyddxFEkF4ocw,4067
+luckyrobots/grpc/generated/scene_pb2_grpc.py,sha256=yPWO10jLAL9orTtzG08NDjWVz1uw8i9Yf8zRVtESMHE,8417
+luckyrobots/grpc/generated/telemetry_pb2.py,sha256=RdTlqizfmLBlT3Es0A_gkW0ec4rY3AsMwXkuG8Ds8zU,2840
+luckyrobots/grpc/generated/telemetry_pb2_grpc.py,sha256=Sq6nExNUZe1-rERJceSoSt23Pbx-DeFA3zrOJsOQpxA,5397
+luckyrobots/grpc/generated/viewport_pb2.py,sha256=LO_6MujrgVjm_QgeGjsyBVHal13SXN_6ROGb86WAEso,3147
+luckyrobots/grpc/generated/viewport_pb2_grpc.py,sha256=QIrjDAdE2kU-R6VVzAso3iZDDdurJllXkXwBggFYCcs,5370
+luckyrobots/grpc/proto/agent.proto,sha256=-3MzIKGzDC6QhPYUHuCXZfp6ygXA7c9usWblV55np3s,5694
+luckyrobots/grpc/proto/camera.proto,sha256=fXCaU9TdJk0zHJs0Jbkq9DABOwaPJBHyUKj1RyMoJeQ,1100
+luckyrobots/grpc/proto/common.proto,sha256=6twE6_HQUMd1N6Ko2vUEDWtL07pCflHIfmit66ggvg0,775
+luckyrobots/grpc/proto/hazel_rpc.proto,sha256=a0F_Dl1JgmJdoIe4okL_tHDzIQvL7dETrb634EuWTrg,1232
+luckyrobots/grpc/proto/media.proto,sha256=CNZJTepdS6Gx68d_Cd3ciaPrOsAe3e7yZbgHIGYe1LY,839
+luckyrobots/grpc/proto/mujoco.proto,sha256=nVovXeedm-imERtSVLeBR8dpEDmlFxXhyVujKy9BylU,1876
+luckyrobots/grpc/proto/scene.proto,sha256=9p19X6_IdiarDXHczkxvjO6Uhjltbwnk8lYuZik7Q1s,1828
+luckyrobots/grpc/proto/telemetry.proto,sha256=vD27JPNPhgi36fkJMTLoFNbv5YXEiz1xntsK00OJ6-Q,1484
+luckyrobots/grpc/proto/viewport.proto,sha256=l3BZBho-v0DHLKt3OQhJwodaZMxZfFceAPQQUmW7PVU,1327
+luckyrobots/models/__init__.py,sha256=LsKj7q9fMTqpSC4WThJVlRMmwho5D08OURVCgerEURI,246
+luckyrobots/models/camera.py,sha256=e-CftAndHASfokhtUtU7ujGb2q_kcXZ6-2KKvY42CKg,3682
+luckyrobots/models/observation.py,sha256=jbRiUTjOP2ZiSobsnNcks3aMPAJA6oPoKqiXwvrNQK0,4758
+luckyrobots-0.1.69.dist-info/METADATA,sha256=S9czWJXY1XdNYfp2uPzs96YnxBqeJo9CD8ECBy1lQX0,8379
+luckyrobots-0.1.69.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+luckyrobots-0.1.69.dist-info/licenses/LICENSE,sha256=xsPYvRJPH_fW_sofTUknI_KvZOsD4-BqjSOTZqI6Nmw,1069
+luckyrobots-0.1.69.dist-info/RECORD,,

{luckyrobots-0.1.68.dist-info → luckyrobots-0.1.69.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.27.0
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any