{"id":49233797,"url":"https://github.com/kuds/mesozoic-labs","last_synced_at":"2026-04-24T13:33:34.084Z","repository":{"id":279336003,"uuid":"937285621","full_name":"kuds/mesozoic-labs","owner":"kuds","description":"Open-source research platform for dinosaur biomechanics and robotic locomotion using reinforcement learning. MuJoCo-based Gymnasium environments with curriculum learning, W\u0026B experiment tracking, and sim-to-real transfer goals.","archived":false,"fork":false,"pushed_at":"2026-03-30T01:38:33.000Z","size":55549,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-30T04:52:56.739Z","etag":null,"topics":["dinosaur","mujoco","reinforcement-learning","robotics","sim2real"],"latest_commit_sha":null,"homepage":"https://mesozoiclabs.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuds.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-22T19:16:40.000Z","updated_at":"2026-03-30T01:38:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"0f49f3e4-fc26-4e50-b559-fd3ac6511ad5","html_url":"https://github.com/kuds/mesozoic-labs","commit_stats":null,"previous_names":["kuds/apex","kuds/mesozoic-labs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kuds/mesozoic-labs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuds%2Fmesozoic-labs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuds%2Fmesozoic-labs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuds%2Fmesozoic-labs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuds%2Fmesozoic-labs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuds","download_url":"https://codeload.github.com/kuds/mesozoic-labs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuds%2Fmesozoic-labs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32225813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dinosaur","mujoco","reinforcement-learning","robotics","sim2real"],"created_at":"2026-04-24T13:33:33.287Z","updated_at":"2026-04-24T13:33:34.072Z","avatar_url":"https://github.com/kuds.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mesozoic Labs\n\nRobotic dinosaur locomotion research using reinforcement learning and MuJoCo physics simulation.\n\n![Trained PPO Agent](/results/velociraptor/ppo/stage1_balance.gif)\n\n## Overview\n\nMesozoic Labs is a research project exploring bipedal and quadrupedal locomotion in robotic dinosaurs. We use MuJoCo for realistic physics simulation and train agents with algorithms like PPO and SAC.\n\n**Goals:**\n- Develop realistic locomotion controllers for various dinosaur species\n- Explore predatory behaviors (hunting, striking, pack coordination)\n- Create transferable policies for robotic applications\n- Experiment with JAX/MJX for high-performance training\n\n## Repository Structure\n\n```\nmesozoic-labs/\n├── environments/              # Dinosaur training environments\n│   ├── velociraptor/          # Velociraptor (bipedal predator with sickle claws)\n│   │   ├── assets/            # MJCF model files\n│   │   ├── envs/              # Gymnasium environments\n│   │   ├── scripts/           # Training \u0026 utility scripts\n│   │   ├── tests/             # Pytest test suite\n│   │   └── README.md\n│   ├── brachiosaurus/         # Brachiosaurus (quadrupedal sauropod)\n│   │   ├── assets/            # MJCF model files\n│   │   ├── envs/              # Gymnasium environments\n│   │   ├── scripts/           # Training \u0026 utility scripts\n│   │   ├── tests/             # Pytest test suite\n│   │   └── README.md\n│   ├── trex/                  # T-Rex (large bipedal predator)\n│   │   ├── assets/            # MJCF model files\n│   │   ├── envs/              # Gymnasium environments\n│   │   ├── scripts/           # Training \u0026 utility scripts\n│   │   ├── tests/             # Pytest test suite\n│   │   └── README.md\n│   └── shared/                # Shared base classes and utilities\n│       ├── base_env.py        # BaseDinoEnv abstract class\n│       ├── config.py          # TOML configuration loading\n│       ├── curriculum.py      # Curriculum learning manager\n│       ├── train_base.py      # Shared SB3 training infrastructure\n│       ├── species_registry.py # Species configuration registry\n│       ├── metrics.py         # Locomotion evaluation metrics\n│       ├── wandb_integration.py # W\u0026B experiment tracking\n│       ├── mjx_env.py         # JAX/MJX batched environment\n│       ├── jax_ppo.py         # JAX-native PPO implementation\n│       ├── jax_training.py    # JAX training loop\n│       └── tests/             # Shared utility tests\n├── configs/                   # TOML hyperparameter configs per species/stage\n├── notebooks/                 # Jupyter notebooks for experiments\n│   ├── sb3_training.ipynb\n│   ├── jax_training.ipynb\n│   ├── ray_tune_sweep.ipynb\n│   └── google_drive_summary.ipynb\n├── website/                   # Documentation site (Docusaurus)\n└── results/                   # Training results (GIFs + collected_results.csv per species/algorithm)\n```\n\n## Environments\n\n### Velociraptor\n**Status:** Active development\n\nA bipedal predator with distinctive sickle claws, trained using 3-stage curriculum learning:\n1. **Balance** - Learn to stand without falling\n2. **Locomotion** - Walk and run forward\n3. **Strike** - Sprint and attack prey with claws\n\n| Feature | Details |\n|---------|---------|\n| Observation | 67 dims (joints, pelvis, prey tracking) |\n| Action | 22 dims (legs, claws, tail, arms) |\n| Model | `environments/velociraptor/assets/raptor.xml` |\n\n[Full documentation →](environments/velociraptor/README.md)\n\n[HuggingFace Models →](https://huggingface.co/kuds/mesozoic-labs-velocipastor)\n\n### Brachiosaurus\n**Status:** Active development\n\nA quadrupedal sauropod herbivore with a long neck for reaching elevated food sources. The first quadrupedal species in the project, featuring columnar elephant-like legs and characteristic longer front legs.\n\nTrained using 3-stage curriculum learning:\n1. **Balance** - Stable quadrupedal stance\n2. **Locomotion** - Coordinated four-legged walking\n3. **Food Reach** - Walk to food and reach with neck\n\n| Feature | Details |\n|---------|---------|\n| Observation | 83 dims (joints, torso, food tracking) |\n| Action | 26 dims (6 neck + 20 leg controls) |\n| Model | `environments/brachiosaurus/assets/brachiosaurus.xml` |\n\n[Full documentation →](environments/brachiosaurus/README.md)\n\n### T-Rex\n**Status:** Active development\n\nLarge bipedal predator with a massive skull, powerful jaws, and vestigial forelimbs. Hunts by sprinting toward prey and delivering a bite.\n\nTrained using 3-stage curriculum learning:\n1. **Balance** - Stable bipedal stance\n2. **Locomotion** - Walk and run toward prey\n3. **Hunting** - Sprint and bite prey with jaws\n\n| Feature | Details |\n|---------|---------|\n| Observation | 83 dims (joints, pelvis, prey tracking) |\n| Action | 21 dims (3 neck/head + 7 per leg + 4 tail) |\n| Model | `environments/trex/assets/trex.xml` |\n\n[Full documentation →](environments/trex/README.md)\n\n### Planned Species\n- Deinonychus (pack hunter)\n- Compsognathus (small, fast biped)\n- Stegosaurus (armored quadrupedal defender)\n\n## Quick Start\n\n```bash\n# Clone and setup\ngit clone https://github.com/kuds/mesozoic-labs.git\ncd mesozoic-labs\n\npython -m venv venv\nsource venv/bin/activate\n\n# Install the package with training dependencies\npip install -e \".[train]\"\n\n# View the velociraptor model\npython environments/velociraptor/scripts/view_model.py\n\n# Full 3-stage curriculum — one command, all stages handled automatically\n# (each stage loads its own hyperparameters from the TOML config)\ncd environments/velociraptor\npython scripts/train_sb3.py curriculum --algorithm ppo\n```\n\n## Docker\n\nThe repo ships a `Dockerfile` that bundles MuJoCo, Stable-Baselines3, and all training dependencies:\n\n```bash\n# Build\ndocker build -t mesozoic-labs:latest .\n\n# Quick smoke-test (no GPU needed)\ndocker run --rm mesozoic-labs:latest \\\n  environments/velociraptor/scripts/train_sb3.py \\\n  train --stage 1 --timesteps 1000 --n-envs 1\n\n# Full curriculum with GPU, writing outputs to local disk\ndocker run --rm --gpus all \\\n  -v \"$(pwd)/outputs:/app/outputs\" \\\n  mesozoic-labs:latest \\\n  environments/velociraptor/scripts/train_sb3.py \\\n  curriculum --algorithm ppo --n-envs 4 --output-dir /app/outputs/velociraptor\n```\n\nSee [Vertex AI training docs](website/docs/training/vertex-ai.md) for cloud deployment.\n\n## Training Results\n\nHardware: Google Colab L4 GPU\n\n### Velociraptor (PPO) — All 3 stages passed | 22M steps | 11:25:15 total\n\n| Stage | Name | Best Reward | Avg Fwd Vel | Success Rate | Time |\n|-------|------|-------------|-------------|--------------|------|\n| 1 | Balance | 1964.43 | 0.11 m/s | — | 2:57:25 |\n| 2 | Locomotion | 2678.68 | 3.47 m/s | — | 4:35:55 |\n| 3 | Strike | 1366.19 | 2.02 m/s | 93.3% | 3:51:54 |\n\n### Velociraptor (SAC) — All 3 stages passed | 22M steps | 22:59:18 total\n\n| Stage | Name | Best Reward | Avg Fwd Vel | Success Rate | Time |\n|-------|------|-------------|-------------|--------------|------|\n| 1 | Balance | 970.19 | -0.64 m/s | — | 5:08:59 |\n| 2 | Locomotion | 2078.62 | 2.91 m/s | — | 8:36:12 |\n| 3 | Strike | 1195.43 | 1.63 m/s | 90.0% | 9:14:06 |\n\n### T-Rex (PPO) — All 3 stages passed | 22M steps | 13:02:32 total\n\n| Stage | Name | Best Reward | Avg Fwd Vel | Success Rate | Time |\n|-------|------|-------------|-------------|--------------|------|\n| 1 | Balance | 3008.66 | 0.02 m/s | — | 3:35:24 |\n| 2 | Locomotion | 1936.01 | 3.47 m/s | — | 5:17:18 |\n| 3 | Bite | 1294.28 | 1.68 m/s | 96.7% | 4:09:49 |\n\n### Brachiosaurus (PPO) — Stages 1-2 passed, Stage 3 in progress | 30M steps | 15:59:39 total\n\n| Stage | Name | Best Reward | Avg Fwd Vel | Success Rate | Time |\n|-------|------|-------------|-------------|--------------|------|\n| 1 | Balance | 3002.52 | 0.02 m/s | — | 3:46:42 |\n| 2 | Locomotion | 4176.95 | 1.12 m/s | — | 8:18:51 |\n| 3 | Food Reach | 732.20 | 0.52 m/s | 16.7% (target: 50%) | 3:54:06 |\n\n## Notebooks\n\n| Notebook | Description |\n|----------|-------------|\n| `notebooks/sb3_training.ipynb` | Unified 3-stage curriculum training for all species (Colab-ready) |\n| `notebooks/jax_training.ipynb` | JAX/MJX training for all species with GPU acceleration (Colab-ready) |\n| `notebooks/ray_tune_sweep.ipynb` | Ray Tune hyperparameter sweep with ASHA early stopping (Colab-ready) |\n| `notebooks/google_drive_summary.ipynb` | Training runs summary and comparison across all species (Colab-ready) |\n\n## Roadmap\n\n- [x] Complete velociraptor 3-stage training (PPO, 93.3% strike success)\n- [x] Complete velociraptor 3-stage training (SAC, 90.0% strike success)\n- [x] Complete T-Rex 3-stage training (PPO, 96.7% bite success)\n- [-] Complete brachiosaurus 3-stage training (Stages 1-2 passed, Stage 3 food_reach at 16.7% vs 50% target)\n- [-] SAC training for T-Rex (velociraptor SAC complete)\n- [ ] Domain randomization (friction, damping, gravity, actuator strength, external pushes, observation noise)\n- [ ] Terrain adaptation (uneven ground, obstacles)\n- [-] JAX/MJX migration for faster training (PPO pipeline complete, SAC pending)\n- [-] mjlab pilot (MuJoCo-Warp + Isaac-Lab manager API) — scaffold landed, velociraptor Stage 1 spike pending\n- [ ] Multi-agent pack hunting scenarios\n- [ ] Sim-to-real transfer experiments\n\nSee [docs/ROADMAP.md](docs/ROADMAP.md) for the full phased timeline, milestones, and dependency graph.\n\n## Resources\n\n- **Documentation:** [mesozoiclabs.com](https://mesozoiclabs.com)\n- **Blog:** [From Zero to Dino-Roar](https://www.findingtheta.com/blog/from-zero-to-dino-roar-teaching-a-t-rex-to-walk-with-mujoco-and-reinforcement-learning)\n\n## Development\n\n```bash\n# Install with all dev dependencies\npip install -e \".[all]\"\n\n# Run tests\npytest\n\n# Lint and type check\nruff check environments/\nmypy environments/\n```\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## Citation\n\nIf you use Mesozoic Labs in your research, please cite:\n\n```bibtex\n@software{mesozoic_labs,\n  title     = {Mesozoic Labs: Dinosaur Locomotion via Reinforcement Learning},\n  author    = {Michael Kudlaty},\n  year      = {2025},\n  url       = {https://github.com/kuds/mesozoic-labs},\n  license   = {MIT}\n}\n```\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuds%2Fmesozoic-labs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuds%2Fmesozoic-labs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuds%2Fmesozoic-labs/lists"}