MAGMA-GEN

Generate robotic interaction data through simulation with MAGMA. MAGMA-GEN coordinates an HTTP agent, task scenarios, and a motion planner, saves generation graphs, and provides an optional web viewer for live and saved runs.

Version 2.0.0 is the first stable release. Inference and coaching use the shared agent–core HTTP protocol 2.0; saved files identify their Gen producer with the installed package version.

Official documentation · Report an issue

Installation

Python 3.12 is required. Simulation installation has been checked on Linux x86_64. GPU rendering also requires compatible system drivers.

Install with the web viewer:

python -m pip install "magma_gen[gui]==2.0.0"

For generation without the viewer dependencies:

python -m pip install "magma_gen==2.0.0"

Both install magma_core[simulation]>=2.0.1,<3.0.0 and magma_scenarios>=2.0.0,<3.0.0, along with their Python dependencies. The viewer is included in the package; users do not need Node.js to run it.

To update to the latest stable version, use python -m pip install --upgrade "magma_gen[gui]". Publish/install Core 2.0.1 before deploying Gen 2.0.0, and update and restart the agent server separately.

Usage

Start a compatible agent and motion planner separately, then configure their addresses and any required language-model backends. Installing MAGMA-GEN does not start these services or install model weights.

magma-gen run --help
magma-gen batch --help
magma-gen export --help

Generation supports a task preset (--preset) or a task definition (--definition). The former curriculum option --scenarios/-s was never implemented and is rejected before any service call or output cleanup.

To browse live or saved generations:

magma-gen viewer --output-dir ./output

Open http://127.0.0.1:8900. Dataset export requires the selected agent's export plugin to be installed in the same Python environment as MAGMA-GEN.

Automatic coaching budget

Configure the per-stage automatic coaching limits in config.yaml:

coaching:
  enabled: true
  max_pending_per_stage: 5
  max_unproven_per_stage: 5

Both limits default to 5 and require positive integers. Automatic requests stop being enqueued when either limit is reached. Pending requests include queued, running and answered requests awaiting reinjection. Unproven attempts are pending requests plus completed attempts minus attempts that later led to a stage success. These limits do not apply to manual viewer interventions. A stage success does not itself disable automatic coaching.

Correct an active generation

Start the viewer before launching the run. With coaching.enabled: true and an agent announcing correction reinjection support (full-history-agent, except Llama), switch Viewer → Coach. The active run is selected and the run picker is locked. Only one browser tab can hold Coach mode.

Select an agent decision containing tool calls once its execution has returned, even if the stage is still ongoing, and choose Créer une alternative at the top of the panel. Enter either a nonempty say or one or more tool calls (robot, tool name, JSON object arguments), plus the diagnostic reason and expected decision. The runner derives the decision index and reconstructs the trajectory from its own graph. Invalid responses and internal execution nodes cannot be corrected.

Corrections are classified as failure:diagnosis. They enter the ordinary reinjection path immediately, without a coach LLM call. They preserve the input memory, attributes and skill snapshot and retain the original branch. Redundant LLM requests still waiting to start can be pruned; running requests and completed corrections are preserved. Accepted interventions retain their command ID, source node and diagnosis in coaching_source in the exported graph.

Coach mode keeps the run alive and suspends the inactivity watchdog. Presence is renewed every two seconds and expires after twenty seconds without renewal. Returning to Viewer restores ordinary termination. Accepted corrections continue even after presence expires; fatal manager errors still stop the run. A finished run cannot be reopened, and existing stage quotas may stop an alternative before the final stage.

Successful corrected branches use the existing few-shot cache. Set coaching.examples.register_successful: true to enable registration and use_for_automatic: true to reuse examples. There is no forced save: failures are not saved and the five-case group limit remains. New caches record the installed magma_gen package version. Existing coaching_examples v6 and suboptimal_examples v1 caches remain readable without rewriting them.

Compatibility and saved files

Inference and coaching share core's HTTP protocol "2.0". /v1/info announces this version and the agent's available capabilities; there is no separate coaching-session version. Session configuration remains backends and capture_logs. Coaching payloads retain all their context fields.

The runner and viewer are shipped together. Run both from the same Python installation and restart them after updating it. Their internal HTTP exchange does not have a separate version number.

Saved graphs and new coaching caches contain generator_version, taken from the installed magma_gen distribution. A reader accepts a producer from the same major release whose version is not newer than the reader, then validates the complete data structure. Minor and corrective releases must preserve reading older saves of their major release. Breaking changes require a migration or a new major package release; prereleases do not guarantee stability.

Previous graph saves containing schema_version are no longer supported, even if they also contain generator_version. Generate a new run. The viewer lists these saves as unsupported and displays the reason. No graph conversion or historical reader is provided. The limited compatibility for v6/v1 caches does not apply to graphs.

Dataset content and rendering belong to the selected agent. Gen retains a technical export manifest containing the calling package's identity/version, agent identity, options, signature and file hashes, without a global export format version. --skip-pre-made checks the manifest and file integrity; it does not interpret the exported examples. Upgrading the producer or exporter invalidates the signature. Older export manifests are regenerated on the next export. Agent exporters currently identify themselves with their agent version.

Check the agent server

Update core, Gen and the server agent together. An editable installation does not reload imports in a running process. Servers advertising the old coaching_session_version metadata must be updated and restarted manually.

From the workspace root, in the runner's Python environment:

python -m pip install --no-deps -e ./magma-core-dev -e ./magma-gen-dev
python - <<'PY'
import sys
from pathlib import Path
import magma_core, magma_gen
from magma_core.configs import MAGMAConfig
from magma_core.protocol.agent import PROTOCOL_VERSION
print('Python:', sys.executable)
print('Core:', magma_core.__file__)
print('Gen:', magma_gen.__file__, magma_gen.__version__)
print('HTTP:', PROTOCOL_VERSION)
print('Agent:', MAGMAConfig.load(Path('config.yaml')).magma_agent_address)
PY

Use the actual config path and account for address overrides passed on the CLI. --no-deps requires dependencies already installed; install normally when adding dependencies such as packaging.

Separately, in the server's environment and its checkout:

python -m pip install --no-deps -e ./magma-core-dev -e ./agents/full-history-agent
python - <<'PY'
import sys
import magma_core, full_history_agent
from magma_core.protocol.agent import PROTOCOL_VERSION
print('Python:', sys.executable)
print('Core:', magma_core.__file__)
print('Agent:', full_history_agent.__file__)
print('HTTP:', PROTOCOL_VERSION)
PY

Restart the server manually using its normal configuration and environment. For example, with an existing model configuration:

python -m full_history_agent --config agents/full-history-agent/config.qwen.json
curl --fail --max-time 5 http://localhost:8888/v1/info

Use the address actually configured for generation. Expect protocol_version="2.0", no coaching_session_version, and, for a compatible full-history model, coaching_resume=true and the three specialized coaches. Llama remains excluded; HSR/TSR retain their explicit coaching limitations.

Development and validation

The test suite uses fake graphs, simulated agent responses and the viewer's in-memory HTTP client. It does not start a model, a remote service, a listening HTTP server, or a physical simulation. Core and scenarios are declared runtime dependencies; no other agent, benchmark or off-policy package is needed.

From this repository, install the package and its test dependencies:

python -m pip install -e ".[dev]"
python -m pytest tests --import-mode=importlib -q
python -m compileall -q src tests

Node.js 20.19+ is only needed to develop or build the viewer:

cd frontend
npm ci
npm run build
cd ..
python -m pip install build twine
python -m build
python -m twine check --strict dist/*

Build the frontend before creating distributions so both the wheel and source archive contain its compiled assets. The source archive also includes the changelog, frontend sources and tests. The publication workflow checks the tag, source tests, installed wheel tests and packaged viewer assets before upload. These automated checks do not replace an end-to-end run against your chosen agent, planner and simulation environment.

See the official documentation for configuration, generation examples, agent setup, and custom scenario packages.

Install from source

Clone the release and build the viewer before installing from source:

git clone --branch v2.0.0 https://github.com/MAGMA-rob/magma-gen.git
cd magma-gen/frontend
npm ci
npm run build
cd ..
python -m pip install ".[gui]"

Compiled viewer assets are generated locally and are not stored in Git. A direct VCS installation does not build them; use the PyPI wheel for a prebuilt viewer. For local Python development, use python -m pip install -e ".[dev]" after the frontend build. Dependencies are resolved from PyPI.

License

BSD 2-Clause.