Python SDK guide for hosted training, sampling, checkpoints, and Behavior CI.

The cybernetic-physics package is the Python SDK for hosted Cybernetics training, sampling, checkpoints, and Behavior CI. The import package is cybernetics.

Use the SDK when you need code to talk to the Cybernetic Physics control plane:

• create a platform-backed training session
• create a LoRA training client for a supported model
• run forward_backward, optim_step, and save_state
• cancel the hosted session when your script exits
• run read-only readiness checks before spending GPU time
• run Behavior CI tasks against local fixtures or an Isaac session

pip install cybernetic-physics
python -c "import cybernetics; print(cybernetics.__version__)"

uv add "cybernetic-physics @ git+https://github.com/cybernetic-physics/cybernetic.git"

import cybernetics
from cybernetics import types

service = cybernetics.ServiceClient(project_id="robotics-lab")
training = service.create_lora_training_client(base_model="dreamzero-droid")

datum = types.Datum(
    model_input=types.ModelInput.from_ints(tokens=[1, 2, 3]),
    loss_fn_inputs={
        "target_tokens": types.TensorData(data=[1, 2, 3], dtype="int64", shape=[3]),
        "weights": types.TensorData(data=[1.0, 1.0, 1.0], dtype="float32", shape=[3]),
    },
)

training.forward_backward([datum], "cross_entropy").result()
training.optim_step(types.AdamParams(learning_rate=1e-4)).result()
training.save_state("checkpoint-001").result()

Use PyPI for released versions:

pip install cybernetic-physics

Use the public SDK repo for the current source version:

uv add "cybernetic-physics @ git+https://github.com/cybernetic-physics/cybernetic.git"

For pyproject.toml:

dependencies = [
  "cybernetic-physics @ git+https://github.com/cybernetic-physics/cybernetic.git",
]

The CLI can mint and store a control-plane API key through browser device login:

cybernetics auth login
cybernetics auth status

In CI or another non-interactive environment, set a key explicitly:

export CYBERNETICS_API_KEY="cp_live_..."

Do not print real key values into logs, docs, pull requests, or chat.

Run the doctor before creating hosted GPU work:

cybernetics doctor
cybernetics doctor --require-rl
cybernetics --format json doctor

doctor is read-only. It checks API reachability, authentication, advertised training and sampling support, and DreamZero SFT/RL readiness without creating a session, model, lease, or future.

Every smoke example starts in local-only mode:

cd examples
python dreamzero_sft_smoke.py
python dreamzero_rl_smoke.py

Add --remote-run only when you intend to create a hosted Worldlines session and spend GPU time:

cybernetics doctor --require-rl
python examples/dreamzero_sft_smoke.py --remote-run --timeout 2400 --cleanup-timeout 300

Remote examples cancel their SDK session on exit by default. Use --keep-lease only when you deliberately want to debug in the paid container.

The SDK sends customer keys to the control plane as:

Authorization: Bearer <cp_live_...>

The SDK resolves credentials in this order:

1. 1an explicit api_key= argument
2. 2CYBERNETICS_API_KEY
3. 3CP_API_KEY
4. 4deprecated WORLDLINES_API_KEY
5. 5the stored login file written by cybernetics auth login

The stored login lives at:

~/.config/cybernetics/auth.json

Do not commit, paste, or print that file. Use it as a local convenience only.

cybernetics auth login asks the control-plane API for a device code, opens the verification URL, waits for approval, stores the minted key, and verifies the active user and workspace with /v1/me.

cybernetics auth login
cybernetics auth status
cybernetics auth logout
cybernetics auth token

auth token prints the resolved key. Treat the output as a secret.

The default control-plane API origin is:

https://api.cyberneticphysics.com

Override it for dev or staging with:

export CYBERNETICS_BASE_URL="https://luc-api.cyberneticphysics.com"
cybernetics doctor

The SDK also reads CP_API_BASE for compatibility with older scripts.

Run cybernetics doctor before spending GPU time.

cybernetics doctor
cybernetics doctor --require-rl
cybernetics --format json doctor

The command checks:

• API health
• authentication
• training support
• sampling support
• advertised loss families
• DreamZero SFT readiness
• DreamZero RL readiness

It does not create a hosted session, model, compute lease, or future.

Use --require-rl when a workflow depends on DreamZero RL:

cybernetics doctor --require-rl

The command exits nonzero unless the backend advertises the requested RL loss family. The default required loss is flow_rwr.

cybernetics doctor --require-rl --rl-loss flow_rwr

JSON output is easier to consume in CI:

cybernetics --format json doctor

The JSON includes the resolved base URL source, auth source, health result, scheduler mode, supported training and sampling flags, available loss families, and DreamZero readiness fields.

The SDK uses a Tinker-style training contract:

forward_backward([datum], loss_fn) -> optim_step(adam) -> save_state(name)

The client builds model inputs locally, serializes them into Datum objects, and sends those data over the wire. The hosted runtime decodes the datum and runs the model-specific forward/backward path on platform-managed GPU compute.

Create a service client:

import cybernetics

service = cybernetics.ServiceClient(project_id="robotics-lab")

ServiceClient owns one SDK session id. Use it to create training clients, sampling clients, and REST clients.

Create a LoRA training client:

training = service.create_lora_training_client(
    base_model="dreamzero-droid",
    rank=32,
    timeout=2400,
)

Model creation may require cold-start time while backend capacity starts, assets hydrate, and model weights load. Use an explicit timeout for first runs.

Build a datum:

from cybernetics import types

datum = types.Datum(
    model_input=types.ModelInput.from_ints(tokens=[101, 102, 103]),
    loss_fn_inputs={
        "target_tokens": types.TensorData(data=[101, 102, 103], dtype="int64", shape=[3]),
        "weights": types.TensorData(data=[1.0, 1.0, 1.0], dtype="float32", shape=[3]),
    },
)

Model-specific examples usually build richer collate dictionaries and serde payloads. The public examples show the expected shapes for DreamZero, GR00T, pi0.5, and Cosmos.

Run one step:

fb = training.forward_backward([datum], "cross_entropy").result(timeout=2400)
training.optim_step(types.AdamParams(learning_rate=1e-4)).result(timeout=2400)
checkpoint = training.save_state("checkpoint-001").result(timeout=2400)

forward_backward computes gradients. optim_step applies Adam optimizer parameters. save_state writes a checkpoint artifact in the backend artifact root and returns a checkpoint pointer.

Use the REST client to cancel a session in custom scripts:

service.create_rest_client().cancel_session(service.session_id).result(timeout=300)

The shipped remote examples perform this cleanup by default. Pass --keep-lease only when you want to inspect the paid runtime.

The examples/ directory contains local-only and hosted smoke tests for the supported backends.

Local-only mode is the default. It validates serialization without creating a hosted session:

cd examples
python dreamzero_sft_smoke.py
python groot_sft_smoke.py
python pi05_sft_smoke.py
python cosmos_sft_smoke.py
python flywheel_demo.py

Hosted mode creates a Worldlines session/model and spends GPU time:

cybernetics doctor --require-rl
python dreamzero_sft_smoke.py --remote-run --timeout 2400 --cleanup-timeout 300

python groot_sft_smoke.py --remote-run
python groot_sft_smoke.py --remote-run --keep-lease

save_state(name) writes checkpoint files in the backend artifact root. To publish one to Hugging Face:

export HF_TOKEN="hf_..."
python push_checkpoint_to_hf.py \
  --checkpoint-dir /data/<run>/weights/<name> \
  --repo-id your-org/your-model \
  --private

Never hardcode real tokens in examples, docs, or scripts.

Behavior CI is the SDK path for packaging simulation checks and running them as repeatable verification tasks. Use it when a model, controller, or generated simulation needs a pass/fail gate instead of a prose review.

Install extras:

pip install "cybernetic-physics[behavior-ci]"

The extra installs YAML parsing and media tooling used by task packs and report artifacts.

Typical flow:

1. 1Define a task pack with the scene setup, evaluator, and expected artifacts.
2. 2Run locally against fixtures while iterating on the test shape.
3. 3Point the runner at an Isaac session when the task needs a live simulator.
4. 4Review generated artifacts and metrics before using the result as a gate.

Hosted Behavior CI uses the same credential resolution as the rest of the SDK:

cybernetics auth login
# or
export CYBERNETICS_API_KEY="cp_live_..."

Run cybernetics doctor before a hosted run so failures are attributed to the task, not to API/auth readiness.