orze

PyPI License orze-pro

A GPU experiment orchestrator for ML research.

Orze runs experiments on GPUs: schedule ideas → train → evaluate → report → repeat. It coordinates GPUs via filesystem locks, works across machines, and gives you a complete leaderboard, notifications, and analysis — out of the box.

Website: orze.ai

Install

curl -sL https://orze.ai/install | bash

That's it. It installs orze, detects your GPUs and codebase, generates training scripts and experiment ideas, and starts running — all in one command.

Pass environment variables for additional options:

# LLM-powered setup
ANTHROPIC_API_KEY=sk-ant-... curl -sL https://orze.ai/install | bash

# With pro (autopilot)
ORZE_PRO_KEY=ORZE-PRO-xxx curl -sL https://orze.ai/install | bash

# Custom project path
curl -sL https://orze.ai/install | bash -s /nfs/my-project

orze vs orze-pro

orze is a complete, production-ready tool. orze-pro adds autopilot — so experiments run while you sleep.

Feature orze (free) + orze-pro
GPU scheduling & multi-node ✓ ✓
Idea queue (ideas.md + SQLite) ✓ ✓
Hyperparameter sweep (auto-expand grid) ✓ ✓
Leaderboard report ✓ ✓
Notifications (Telegram/Slack) ✓ ✓
Admin dashboard & MCP server ✓ ✓
Retrospection (plateau detection) ✓ ✓
Cross-experiment regression analysis ✓ ✓
Failure analysis & categorization ✓ ✓
Checkpoint GC ✓ ✓
Sealed eval protection ✓ ✓
Service watchdog (auto-restart + containers) ✓ ✓
Autonomous research agents (Gemini/GPT/Claude) ✓
The Professor (paper lake, cross-domain search, strategy) ✓
Engineer (implement ideas, fix bugs) ✓
Auto-fix failed experiments ✓
Code evolution on plateau ✓
Meta-research (strategy adjustment) ✓
FSM orchestration (7 procedures) ✓
Data analyst & thinker (auto-injected) ✓

Research Loop Comparison

orze free + orze-pro
How ideas are generated Smart Suggestions — rule-based: detects regressions, generates scale sweeps, perturbations Research Agents — LLM-driven: reads all results, forms hypotheses, designs novel experiments
How failures are handled You read the failure log Auto-fix: LLM diagnoses and patches the error
How plateaus are handled Smart Suggestions tries parameter variations Code Evolution: LLM modifies your train script
Does research stop? Never — Smart Suggestions keeps GPUs busy Never — agents run indefinitely
Requires API key? No Yes (Gemini/OpenAI/Anthropic)

Compatibility

orze orze-pro Notes
4.1.x 0.8.x Current release

Quick Start

After install, orze auto-detects GPUs and starts running experiments.

AI CLI users (Claude Code, Cursor, Codex):

do @ORZE-AGENT.md

CLI Reference

# Project lifecycle
orze init [path]              # initialize a new project
orze start                    # start as background daemon
orze stop                     # stop gracefully
orze restart                  # stop + start
orze --check                  # validate config, files, GPUs, API keys
orze --uninstall              # full cleanup, preserves research results

# Operations
orze upgrade                  # reinstall from source + restart daemon
orze admin migrate            # migrate legacy layout to .orze/
orze service install          # auto-restart on crash (systemd)

# Pro
orze pro activate <key>       # activate license
orze pro status               # check license info
orze pro deactivate           # remove license
orze sop list                 # list available SOPs

File Layout

your-project/
├── orze.yaml                 # Project config (single source of truth)
├── train.py                  # Your training script
├── ideas.md                  # Experiment queue
├── GOAL.md                   # Research objective
├── RESEARCH_RULES.md         # Agent constraints
├── configs/base.yaml         # Default hyperparameters
├── .env                      # API keys (gitignored)
├── ORZE-AGENT.md             # AI CLI instructions
├── ORZE-RULES.md             # Agent guardrails
├── venv/                     # Training dependencies
├── .orze/                    # Runtime state (gitignored)
│   ├── state/version.json    # Layout version
│   ├── logs/                 # Role logs
│   ├── locks/                # Filesystem locks
│   ├── rules/                # Migrated rule files
│   ├── mcp/                  # MCP server configs
│   ├── receipts/             # Execution evidence
│   ├── triggers/             # One-shot role triggers
│   ├── heartbeats/           # Per-host liveness
│   ├── backups/              # ideas.md backups
│   └── feedback/             # Failure feedback
├── procedures/               # User procedure overrides (pro)
├── fsm/runner.py             # FSM orchestrator (pro)
└── orze_results/             # Research outputs
    ├── idea-0001/metrics.json
    ├── methods/              # Generated code
    └── knowledge/            # Analysis insights

Multi-node

Start orze in the same shared folder on any machine — nodes auto-join the research pool.

# Node 1
ssh node1 "cd /nfs/project && orze start"

# Node 2
ssh node2 "cd /nfs/project && orze start"

Key Features

  • Scales to 1M+ Experiments — SQLite-backed job queue with O(log N) scheduling
  • Config Inheritance — Child ideas inherit parent configs; specify only what changes
  • HP Sweep — lr: [1e-4, 3e-4] auto-expands into all combinations
  • Failure Protection — Stops automatically when failure rates spike
  • Cross-Experiment Analysis — Detects regressions, tradeoffs, and suggests actions
  • Rich Notifications — GPU VRAM, per-dataset breakdown, verified results, target/gap tracking
  • Admin Panel — Real-time web dashboard at http://localhost:8787
  • Clean Uninstall — orze --uninstall removes runtime files, preserves results

The Contract

Your training script receives:

python train.py --idea-id idea-001 --results-dir orze_results --ideas-md ideas.md --config base.yaml

Required output: orze_results/{idea_id}/metrics.json:

{"status": "COMPLETED", "test_accuracy": 0.92, "training_time": 142.5}

See SKILL.md for the full technical specification.

Admin Panel

Auto-launches at http://localhost:8787. No extra install needed.

admin-panel admin-queue admin-leaderboard

Telegram Notifications

notifications:
  enabled: true
  on: [completed, failed, new_best]
  channels:
    - type: telegram
      bot_token: "YOUR_BOT_TOKEN"
      chat_id: "YOUR_CHAT_ID"
tg

Service Management

orze service install -c orze.yaml    # auto-restart on crash + manage containers
orze service status                  # check health
orze service uninstall               # remove

The watchdog runs every minute (crontab) or every 5 minutes (systemd). It restarts orze on crash/stall and manages Docker containers defined in orze.yaml:

containers:
  paperdog:
    image: orzeai/paperdog:latest
    ports:
      - "8000:8000"

Containers are auto-pulled and recreated when a new image is available.

Citation

@article{li2026autoresearching,
  title={Auto Researching, not hyperparameter tuning: Convergence Analysis of 10,000 Experiments},
  author={Li, Xiaoyi},
  journal={arXiv preprint arXiv:2603.15916},
  year={2026}
}

License

Apache 2.0 — orze is and will always be free and open source.

orze-pro (autopilot features) is commercially licensed.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aimesh from gravatar.com aimesh

Credits

Author: orze contributors

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.9

Tags

gpu experiment orchestrator machine-learning research-automation

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

orze-4.4.3.tar.gz (462.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

orze-4.4.3-py3-none-any.whl (456.2 kB view details)

Uploaded Python 3

File details

Details for the file orze-4.4.3.tar.gz.

File metadata

  • Download URL: orze-4.4.3.tar.gz
  • Upload date:
  • Size: 462.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.24

File hashes

Hashes for orze-4.4.3.tar.gz
Algorithm Hash digest
SHA256 11aa1b612f8a32afea0217eb13bb48f322b55bb6995cd73bfa7db0185450432e
MD5 83615d5a1f0a6bca4728ab146e10adb3
BLAKE2b-256 f7fba687b12609801e135b158bd29e306d25f651ec38bca3b5a470f7164e2c79

See more details on using hashes here.

File details

Details for the file orze-4.4.3-py3-none-any.whl.

File metadata

  • Download URL: orze-4.4.3-py3-none-any.whl
  • Upload date:
  • Size: 456.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.9.24

File hashes

Hashes for orze-4.4.3-py3-none-any.whl
Algorithm Hash digest
SHA256 034f2d06877bc6d57ff9cf1b79622650ca28f329bd8bf711abc2dc71e210a20c
MD5 d0c9fd76b4cbae1583345c61a8f85886
BLAKE2b-256 4183b4f8cbdf9037ad2bab87803858941cdbcf5df5dafdceb25e7864a822887d

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

4.4.3 This release

2 files

4.4.2

2 files

4.4.1

2 files

4.4.0

2 files

4.3.9

2 files

4.3.2

2 files

4.3.0

2 files

4.2.8

2 files

4.2.7

2 files

4.2.6

2 files

4.2.5

2 files

4.2.4

2 files

4.2.2

2 files

4.2.1

2 files

4.1.5

2 files

4.1.4

2 files

4.1.3

2 files

4.1.2

2 files

4.1.1

2 files

4.1.0

2 files

4.0.5

2 files

4.0.2

2 files

3.4.11

2 files

3.4.10

2 files

3.4.9

2 files

3.4.8

2 files

3.4.7

2 files

3.4.6

2 files

3.4.5

2 files

3.4.4

2 files

3.4.3

2 files

3.4.2

2 files

3.4.1

2 files

3.4.0

2 files

3.3.7

2 files

3.3.6

2 files

3.3.5

2 files

3.3.4

2 files

3.3.3

2 files

3.3.2

2 files

3.3.1

2 files

3.3.0

2 files

3.2.33

2 files

3.2.32

2 files

3.2.31

2 files

3.2.30

2 files

3.2.29

2 files

3.2.28

2 files

3.2.27

2 files

3.2.26

2 files

3.2.25

2 files

3.2.24

2 files

3.2.23

2 files

3.2.22

2 files

3.2.21

2 files

3.2.20

2 files

3.2.14

2 files

3.2.13

2 files

3.2.12

2 files

3.2.11

2 files

3.2.10

2 files

3.2.9

2 files

3.2.8

2 files

3.2.7

2 files

3.2.6

2 files

3.2.5

2 files

3.2.4

2 files

3.2.3

2 files

3.2.2

2 files

3.2.1

2 files

3.2.0

2 files

3.1.2

2 files

3.1.1

2 files

3.1.0

2 files

3.0.23

2 files

3.0.22

2 files

3.0.21

2 files

3.0.20

2 files

3.0.19

2 files

3.0.18

2 files

3.0.17

2 files

3.0.16

2 files

3.0.15

2 files

3.0.14

2 files

3.0.12

2 files

3.0.10

2 files

3.0.9

2 files

3.0.8

2 files

3.0.7

2 files

3.0.6

2 files

3.0.5

2 files

3.0.4

2 files

3.0.3

2 files

3.0.2

2 files

3.0.1

2 files

3.0.0

2 files

2.20.3

2 files

2.20.2

2 files

2.20.1

2 files

2.20.0

2 files

2.19.2

2 files

2.19.1

2 files

2.19.0

2 files

2.18.2

2 files

2.18.1

2 files

2.17.2

2 files

2.17.1

2 files

2.17.0

2 files

2.16.0

2 files

2.15.2

2 files

2.15.1

2 files

2.15.0

2 files

2.14.1

2 files

2.14.0

2 files

2.13.0

2 files

2.12.1

2 files

2.12.0

2 files

2.10.0

2 files

2.9.2

2 files

2.9.1

2 files

2.9.0

2 files

2.8.0

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.7.0

2 files

2.6.9

2 files

2.6.8

2 files

2.6.7

2 files

2.6.6

2 files

2.6.5

2 files

2.6.4

2 files

2.6.3

2 files

2.6.2

2 files

2.6.1

2 files

2.6.0

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.0

2 files

2.3.6

2 files

2.3.5

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.1

1 file

2.2.0

2 files

2.1.8

2 files

2.1.7

2 files

2.1.6

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

1.10.2

1 file

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page