eclise

Shared research infrastructure: one eclise wheel under the PEP 420 namespace eclise.*. Import path equals folder path equals taxonomy — one source tree src/eclise/. Heavy stacks live in pixi environments, not in wheel metadata.

Extras (the published wheel)

eclise.models.{octo,smolvla,pi0}, eclise.sims.{libero,phyworld}, eclise.datasets.openvid, and eclise.launch ship as inert source in the same wheel. Running a server or generator needs the matching pixi environment (or python -m eclise.launch).

models/vision/ is deliberately absent: a vision-model contract will be created only once it has at least two real consumers.

Pixi environments (from a checkout)

Installing

Client-side (numpy-1.x-safe eclise.contracts.vla only — no torch/jax):

pip install "eclise[vla]"
python -m eclise.launch start octo --setup

--setup clones this repo at eclise-v<wheel version> (unless ECLISE_ROOT already points at a checkout), installs pixi if needed, and runs pixi install -e <env>. start returns a host/port; the caller wires WebsocketPolicyClient / WebsocketEnvClient.

From a checkout:

pixi install -e dev
pixi run -e dev test
pixi run -e libero setup
pixi run -e libero serve --port 9000

Developing

pixi run -e dev test
pixi run -e libero serve
pixi run -e phyworld generate --family collision --grid in_dist_l0 --experiment smoke --limit 32
python -m eclise.sims.phyworld generate --family collision --grid in_dist_l0 --experiment smoke --limit 32

Editable extras without pixi: pip install -e ".[dev]". Releases are tagged eclise-v0.2.0.

Runtime data (ECLISE_DATA_ROOT / $SCRATCH)

Runtime trees (data/, outputs/, logs/) are not part of the source taxonomy. eclise.paths.data_root() / outputs_root() resolve, in order:

1. ECLISE_DATA_ROOT / ECLISE_OUTPUTS_ROOT if set
2. $SCRATCH/eclise/{data,outputs} if SCRATCH is set
3. <repo>/{data,outputs}

Packages then pick a leaf (data_root() / "phyworld", outputs_root() / "libero"). On quota-capped hosts, set SCRATCH (or the explicit ECLISE_*_ROOT vars) so large artifacts never land on the home quota. There are no scratch-symlink setup tasks.

Design rules

• One distribution, environments at the pixi boundary. Incompatible stacks (JAX vs torch, numpy 1.x vs 2.x) do not share an environment. Wheel extras stay light; pixi features own the heavy pins.
• Import path == folder path == taxonomy. Moving a package is a breaking import change; there is one tree and no alias extras.
• eclise.contracts.clips and eclise.contracts.vla are contracts. Writers and readers may live in different repos/envs; document schema changes in CHANGELOG.md. eclise[vla] must remain numpy 1.x-compatible.

Package archetypes

Every package is one of three kinds. Archetype is recorded in the launcher kind and the pixi feature shape, not in folders.

Library extra — published wheel, installed into a consumer's env, no server. utils, imagenet, clips, vla.

Interactive socket service — pixi env isolates an incompatible stack behind an eclise.contracts.vla websocket. octo, smolvla, pi0, libero.

• Env: pixi install -e <name> (and pixi run -e <name> setup when the feature defines a setup task).
• Server logic lives in the package; the CLI is python -m eclise.<pkg> serve (pi0 wraps upstream openpi instead).
• Launch: python -m eclise.launch start <name> → pixi run -e <env> serve.

Batch producer — pixi env; decoupled via the on-disk eclise.contracts.clips shard contract (no socket). phyworld, openvid.

• Env: pixi install -e <name> (no scratch-symlink setup task).
• Job entrypoint: python -m eclise.<pkg> <verb> (+ .sbatch via pixi run -e <env>).