vlalab 0.1.0__tar.gz

vlalab-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 VLA-Lab Contributors
+
+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.

vlalab-0.1.0/PKG-INFO

@@ -0,0 +1,443 @@
+Metadata-Version: 2.4
+Name: vlalab
+Version: 0.1.0
+Summary: A toolbox for tracking and visualizing the real-world deployment process of VLA models
+Author: VLA-Lab Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/VLA-Lab/VLA-Lab
+Project-URL: Documentation, https://github.com/VLA-Lab/VLA-Lab#readme
+Project-URL: Repository, https://github.com/VLA-Lab/VLA-Lab
+Project-URL: Issues, https://github.com/VLA-Lab/VLA-Lab/issues
+Keywords: robotics,vla,deployment,visualization,logging
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: streamlit>=1.20.0
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=12.0.0
+Provides-Extra: zarr
+Requires-Dist: zarr>=2.10.0; extra == "zarr"
+Provides-Extra: full
+Requires-Dist: zarr>=2.10.0; extra == "full"
+Requires-Dist: scipy>=1.7.0; extra == "full"
+Requires-Dist: pillow>=9.0.0; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: ruff>=0.0.250; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+  
+# 🧪 VLA-Lab
+
+### The Missing Toolkit for Vision-Language-Action Model Deployment
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![PyPI version](https://img.shields.io/badge/pypi-v0.1.0-orange.svg)](https://pypi.org/project/vlalab/)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/VLA-Lab/VLA-Lab/pulls)
+
+**Debug • Visualize • Analyze** your VLA deployments in the real world
+
+[🚀 Quick Start](#-quick-start) · [📖 Documentation](#-documentation) · [🎯 Features](#-features) · [🔧 Installation](#-installation)
+
+</div>
+
+---
+
+## 🎯 Why VLA-Lab?
+
+Deploying VLA models to real robots is **hard**. You face:
+
+- 🕵️ **Black-box inference** — Can't see what the model "sees" or why it fails
+- ⏱️ **Hidden latencies** — Transport delays, inference bottlenecks, control loop timing issues
+- 📊 **No unified logging** — Every framework logs differently, making cross-model comparison painful
+- 🔄 **Tedious debugging** — Replaying failures requires manual log parsing and visualization
+
+**VLA-Lab solves this.** One unified toolkit for all your VLA deployment needs.
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              VLA-Lab Architecture                           │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│   ┌──────────────┐    ┌──────────────────────┐    ┌────────────────────┐   │
+│   │   Robot      │    │   Inference Server   │    │    VLA-Lab         │   │
+│   │   Client     │───▶│   (DP / GR00T / ...) │───▶│    RunLogger       │   │
+│   └──────────────┘    └──────────────────────┘    └─────────┬──────────┘   │
+│                                                             │              │
+│                                                             ▼              │
+│                          ┌──────────────────────────────────────────┐      │
+│                          │            Unified Run Storage            │      │
+│                          │   ┌──────────┬────────────┬───────────┐  │      │
+│                          │   │meta.json │ steps.jsonl│ artifacts/│  │      │
+│                          │   └──────────┴────────────┴───────────┘  │      │
+│                          └──────────────────┬───────────────────────┘      │
+│                                             │                              │
+│                                             ▼                              │
+│   ┌─────────────────────────────────────────────────────────────────────┐  │
+│   │                        Visualization Suite                           │  │
+│   │  ┌─────────────┐  ┌──────────────────┐  ┌─────────────────────────┐ │  │
+│   │  │  Inference  │  │     Latency      │  │       Dataset           │ │  │
+│   │  │   Viewer    │  │     Analyzer     │  │       Browser           │ │  │
+│   │  └─────────────┘  └──────────────────┘  └─────────────────────────┘ │  │
+│   └─────────────────────────────────────────────────────────────────────┘  │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ✨ Features
+
+<table>
+<tr>
+<td width="50%">
+
+### 📊 Unified Logging Format
+Standardized run structure with JSONL + image artifacts. Works across all VLA frameworks.
+
+### 🔬 Inference Replay
+Step-by-step playback with multi-camera views, 3D trajectory visualization, and action overlays.
+
+</td>
+<td width="50%">
+
+### 📈 Deep Latency Analysis  
+Profile transport delays, inference time, control loop frequency. Find your bottlenecks.
+
+### 🗂️ Dataset Browser
+Explore Zarr-format training/evaluation datasets with intuitive UI.
+
+</td>
+</tr>
+</table>
+
+### 🔌 Framework Support
+
+| Framework | Status | Integration |
+|-----------|--------|-------------|
+| **Diffusion Policy** | ✅ Supported | Drop-in logger |
+| **NVIDIA GR00T** | ✅ Supported | Native adapter |
+| **OpenVLA-OFT** | 🚧 Coming Soon | — |
+| **Pi0.5** | 🚧 Coming Soon | — |
+
+---
+
+## 🔧 Installation
+
+```bash
+# Basic installation
+pip install vlalab
+
+# Full installation (with Zarr dataset support)
+pip install "vlalab[full]"
+
+# Development installation
+git clone https://github.com/VLA-Lab/VLA-Lab.git
+cd VLA-Lab
+pip install -e ".[dev]"
+```
+
+---
+
+## 🚀 Quick Start
+
+### Minimal Example (3 Lines!)
+
+```python
+import vlalab
+
+# Initialize a run
+run = vlalab.init(project="pick_and_place", config={"model": "diffusion_policy"})
+
+# Log during inference
+vlalab.log({"state": obs["state"], "action": action, "images": {"front": obs["image"]}})
+```
+
+### Full Example
+
+```python
+import vlalab
+
+# Initialize with detailed config
+run = vlalab.init(
+    project="pick_and_place",
+    config={
+        "model": "diffusion_policy",
+        "action_horizon": 8,
+        "inference_freq": 10,
+    },
+)
+
+# Access config anywhere
+print(f"Action horizon: {run.config.action_horizon}")
+
+# Inference loop
+for step in range(100):
+    obs = get_observation()
+    
+    t_start = time.time()
+    action = model.predict(obs)
+    latency = (time.time() - t_start) * 1000
+    
+    # Log everything in one call
+    vlalab.log({
+        "state": obs["state"],
+        "action": action,
+        "images": {"front": obs["front_cam"], "wrist": obs["wrist_cam"]},
+        "inference_latency_ms": latency,
+    })
+    
+    robot.execute(action)
+
+# Auto-finishes on exit, or call manually
+vlalab.finish()
+```
+
+### Launch Visualization
+
+```bash
+# One command to view all your runs
+vlalab view
+```
+
+<details>
+<summary><b>📸 Screenshots (Click to expand)</b></summary>
+
+*Coming soon: Inference Viewer, Latency Analyzer, Dataset Browser screenshots*
+
+</details>
+
+---
+
+## 📖 Documentation
+
+### Core Concepts
+
+**Run** — A single deployment session (one experiment, one episode, one evaluation)
+
+**Step** — A single inference timestep with observations, actions, and timing
+
+**Artifacts** — Images, point clouds, and other media saved alongside logs
+
+### API Reference
+
+<details>
+<summary><b>vlalab.init() — Initialize a run</b></summary>
+
+```python
+run = vlalab.init(
+    project: str = "default",     # Project name (creates subdirectory)
+    name: str = None,             # Run name (auto-generated if None)
+    config: dict = None,          # Config accessible via run.config.key
+    dir: str = "./vlalab_runs",   # Base directory (or $VLALAB_DIR)
+    tags: list = None,            # Optional tags
+    notes: str = None,            # Optional notes
+)
+```
+
+</details>
+
+<details>
+<summary><b>vlalab.log() — Log a step</b></summary>
+
+```python
+vlalab.log({
+    # Robot state
+    "state": [...],                    # Full state vector
+    "pose": [x, y, z, qx, qy, qz, qw], # Position + quaternion
+    "gripper": 0.5,                    # Gripper opening (0-1)
+    
+    # Actions
+    "action": [...],                   # Single action or action chunk
+    
+    # Images (multi-camera support)
+    "images": {
+        "front": np.ndarray,           # HWC numpy array
+        "wrist": np.ndarray,
+    },
+    
+    # Timing (any *_ms field auto-captured)
+    "inference_latency_ms": 32.1,
+    "transport_latency_ms": 5.2,
+    "custom_metric_ms": 10.0,
+})
+```
+
+</details>
+
+<details>
+<summary><b>RunLogger — Advanced API</b></summary>
+
+For fine-grained control over logging:
+
+```python
+from vlalab import RunLogger
+
+logger = RunLogger(
+    run_dir="runs/experiment_001",
+    model_name="diffusion_policy",
+    model_path="/path/to/checkpoint.pt",
+    task_name="pick_and_place",
+    robot_name="franka",
+    cameras=[
+        {"name": "front", "resolution": [640, 480]},
+        {"name": "wrist", "resolution": [320, 240]},
+    ],
+    inference_freq=10.0,
+)
+
+logger.log_step(
+    step_idx=0,
+    state=[0.5, 0.2, 0.3, 0, 0, 0, 1, 1.0],
+    action=[[0.51, 0.21, 0.31, 0, 0, 0, 1, 1.0]],
+    images={"front": image_rgb},
+    timing={
+        "client_send": t1,
+        "server_recv": t2,
+        "infer_start": t3,
+        "infer_end": t4,
+    },
+)
+
+logger.close()
+```
+
+</details>
+
+### CLI Commands
+
+```bash
+# Launch visualization dashboard
+vlalab view [--port 8501]
+
+# Convert legacy logs (auto-detects format)
+vlalab convert /path/to/old_log.json -o /path/to/output
+
+# Inspect a run
+vlalab info /path/to/run_dir
+```
+
+---
+
+## 📁 Run Directory Structure
+
+```
+vlalab_runs/
+└── pick_and_place/                 # Project
+    └── run_20240115_103000/        # Run
+        ├── meta.json               # Metadata (model, task, robot, cameras)
+        ├── steps.jsonl             # Step records (one JSON per line)
+        └── artifacts/
+            └── images/             # Saved images
+                ├── step_000000_front.jpg
+                ├── step_000000_wrist.jpg
+                └── ...
+```
+
+---
+
+## 🔗 Framework Integration
+
+### Diffusion Policy
+
+```python
+# In your inference_server.py
+from vlalab import RunLogger
+
+class DPInferenceServer:
+    def __init__(self, checkpoint_path):
+        self.logger = RunLogger(
+            run_dir=f"runs/{datetime.now():%Y%m%d_%H%M%S}",
+            model_name="diffusion_policy",
+            model_path=str(checkpoint_path),
+        )
+    
+    def infer(self, obs):
+        action = self.model(obs)
+        self.logger.log_step(step_idx=self.step, ...)
+        return action
+```
+
+### NVIDIA GR00T
+
+```python
+# In your inference_server_groot.py
+from vlalab import RunLogger
+
+class GrootInferenceServer:
+    def __init__(self, model_path, task_prompt):
+        self.logger = RunLogger(
+            run_dir=f"runs/{datetime.now():%Y%m%d_%H%M%S}",
+            model_name="groot",
+            model_path=str(model_path),
+            task_prompt=task_prompt,
+        )
+```
+
+---
+
+## 🗺️ Roadmap
+
+- [x] Core logging API
+- [x] Streamlit visualization suite
+- [x] Diffusion Policy adapter
+- [x] GR00T adapter
+- [ ] OpenVLA adapter
+- [ ] Cloud sync & team collaboration
+- [ ] Real-time streaming dashboard
+- [ ] Automatic failure detection
+- [ ] Integration with robot simulators
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details.
+
+```bash
+# Setup development environment
+git clone https://github.com/VLA-Lab/VLA-Lab.git
+cd VLA-Lab
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Format code
+black src/
+ruff check src/ --fix
+```
+
+---
+
+## 📄 License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+<div align="center">
+  
+**⭐ Star us on GitHub if VLA-Lab helps your research!**
+
+*Built with ❤️ for the robotics community*
+
+</div>