Metadata-Version: 2.4
Name: odin-robotics
Version: 0.1.0
Summary: The standard library for robot learning data
Project-URL: Homepage, https://odin-hub.dev
Project-URL: Documentation, https://odin-hub.dev/docs
Project-URL: Repository, https://github.com/softmata/odin
Project-URL: Issues, https://github.com/softmata/odin/issues
Project-URL: Changelog, https://github.com/softmata/odin/blob/main/CHANGELOG.md
Author-email: Softmata <hello@softmata.com>
License-Expression: Apache-2.0
Keywords: data-format,datasets,imitation-learning,machine-learning,reinforcement-learning,robot-learning,robotics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: msgpack>=1.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: zstandard>=0.18.0
Provides-Extra: all
Requires-Dist: h5py>=3.8.0; extra == 'all'
Requires-Dist: jax>=0.4.0; extra == 'all'
Requires-Dist: mcap>=1.0.0; extra == 'all'
Requires-Dist: pyarrow>=12.0.0; extra == 'all'
Requires-Dist: rosbags>=0.9.0; extra == 'all'
Requires-Dist: torch>=2.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: jax
Requires-Dist: jax>=0.4.0; extra == 'jax'
Requires-Dist: jaxlib>=0.4.0; extra == 'jax'
Provides-Extra: mcap
Requires-Dist: mcap>=1.0.0; extra == 'mcap'
Provides-Extra: ros
Requires-Dist: rosbags>=0.9.0; extra == 'ros'
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.12.0; extra == 'tensorflow'
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == 'torch'
Description-Content-Type: text/markdown

# ODIN Python SDK

**Open Data for Intelligent Robotics** - The standard library for robot learning data.

[![PyPI version](https://badge.fury.io/py/odin-robotics.svg)](https://pypi.org/project/odin-robotics/)
[![Python versions](https://img.shields.io/pypi/pyversions/odin-robotics.svg)](https://pypi.org/project/odin-robotics/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Documentation](https://img.shields.io/badge/docs-odin--hub.dev-blue)](https://odin-hub.dev/docs)

ODIN provides a unified format and tooling for robot learning datasets. It supports recording, loading, validating, converting, and sharing robotics data.

## Installation

```bash
pip install odin-robotics
```

With optional dependencies:

```bash
# For PyTorch integration
pip install odin-robotics[torch]

# For JAX integration
pip install odin-robotics[jax]

# For all format converters
pip install odin-robotics[all]
```

## Quick Start

### Recording Data

```python
from odin import Recorder

# Create a recorder
recorder = Recorder(name="my_robot_task", robot="franka_panda")

# Record episodes
with recorder.episode() as ep:
    for step_data in collect_data():
        ep.record(
            observation={
                "image": camera_image,
                "joint_pos": joint_positions,
            },
            action=commanded_action,
            reward=reward,
            done=done,
        )

# Save the dataset
dataset = recorder.to_dataset()
dataset.save("./my_dataset")
```

### Loading Data

```python
from odin import Dataset

# Load a dataset
dataset = Dataset.load("./my_dataset")

print(f"Dataset: {dataset.name}")
print(f"Episodes: {dataset.num_episodes}")
print(f"Total steps: {dataset.num_steps}")

# Iterate over episodes
for episode in dataset:
    print(f"Episode {episode.episode_id}: {len(episode)} steps")
    for step in episode:
        obs = step.observation
        action = step.action
        reward = step.reward
```

### PyTorch DataLoader

```python
from odin.torch import OdinDataset
from torch.utils.data import DataLoader

torch_dataset = OdinDataset("./my_dataset")
loader = DataLoader(torch_dataset, batch_size=32, shuffle=True)

for batch in loader:
    observations = batch["observation"]
    actions = batch["action"]
    # Train your model...
```

### Hub Integration

```python
from odin.hub import download, upload, search

# Download a dataset from ODIN Hub
dataset = download("lerobot/pusht", "./local_path")

# Search for datasets
results = search(query="manipulation", robot="franka")
for ds in results:
    print(f"{ds['name']}: {ds['num_episodes']} episodes")

# Upload your dataset
upload(dataset, "your-username/dataset-name")
```

## CLI Usage

ODIN provides a comprehensive CLI for dataset operations:

```bash
# Show dataset information
odin info ./my_dataset

# Validate dataset structure
odin validate ./my_dataset --level strict

# Import from other formats
odin import lerobot lerobot/pusht -o ./pusht
odin import rosbag recording.bag -o ./rosbag_dataset

# Export to other formats
odin export lerobot ./my_dataset -o ./lerobot_output
odin export hdf5 ./my_dataset -o ./output.h5

# Split dataset for training
odin split ./my_dataset --train-ratio 0.8 -o ./splits/

# Merge multiple datasets
odin merge dataset1 dataset2 merged_output

# Batch import from multiple sources
odin batch import -o ./all_datasets -s lerobot -s rlds --workers 8

# Search and download from Hub
odin search --query "manipulation" --robot "franka"
odin download lerobot/pusht ./local_path
```

## Supported Formats

### Import From
- **LeRobot** - HuggingFace LeRobot v2 format
- **RLDS/TFDS** - TensorFlow Datasets format (Open X-Embodiment)
- **ROS Bags** - ROS 1/2 bag files
- **MCAP** - MCAP recording files
- **HDF5** - Generic HDF5 datasets
- **D4RL/Minari** - RL benchmark datasets
- **robomimic** - robomimic HDF5 format
- **LIBERO** - LIBERO benchmark datasets
- **CALVIN** - CALVIN benchmark datasets
- **Zarr** - Zarr array format

### Export To
- **LeRobot** - Push to HuggingFace Hub
- **HDF5** - Standard HDF5 format
- **Parquet** - Apache Parquet format
- **MCAP** - MCAP recording format
- **RLDS** - TensorFlow Datasets format

## Dataset Schema

ODIN datasets are self-describing with embedded schema:

```python
from odin import Schema, FieldSpec

schema = Schema(
    observation={
        "image": FieldSpec.image(480, 640, 3),
        "depth": FieldSpec.depth_image(480, 640),
        "joint_pos": FieldSpec.array("float32", 7),
        "gripper": FieldSpec.float(),
    },
    action={
        "joint_velocity": FieldSpec.array("float32", 7),
        "gripper_action": FieldSpec.float(),
    },
)
```

## Cloud Streaming

Stream large datasets without downloading:

```python
from odin.cloud import CloudDataset

# Stream from ODIN Hub
dataset = CloudDataset("stanford/droid-100k")

# Iterate without downloading full dataset
for episode in dataset.episodes():
    for step in episode:
        process(step.observation)

# Random batch sampling for training
batch = dataset.sample_batch(32)
```

## Quality Validation

```python
from odin import validate_dataset

report = validate_dataset("./my_dataset", level="strict")

print(f"Quality score: {report.overall_score:.2f}")
for issue in report.issues:
    print(f"  [{issue.severity}] {issue.message}")
```

## Research Paper Integration

```python
from odin import ResearchPaperManager

manager = ResearchPaperManager()

# Find papers related to a dataset
papers = manager.search_papers("robot manipulation", robotics_only=True)
for paper in papers[:5]:
    print(f"{paper.title} ({paper.year})")
```

## Performance

- **Efficient Storage**: MessagePack serialization with Zstandard compression (3-10x compression)
- **Streaming Access**: Process terabyte-scale datasets without loading into memory
- **Parallel Loading**: Multi-threaded data loading for training

## Documentation

Full documentation is available at [odin-hub.dev/docs](https://odin-hub.dev/docs).

## Contributing

Contributions are welcome! Please see our [Contributing Guide](https://github.com/softmata/odin/blob/main/CONTRIBUTING.md).

## License

Apache-2.0

## Links

- [ODIN Hub](https://odin-hub.dev) - Dataset hosting and discovery
- [Documentation](https://odin-hub.dev/docs)
- [GitHub](https://github.com/softmata/odin)
- [PyPI](https://pypi.org/project/odin-robotics/)
- [Rust SDK](https://crates.io/crates/odin)
