Metadata-Version: 2.4
Name: magma_gen
Version: 2.0.0
Summary: Robotic interaction data generation with branching graphs, agent coaching, and a live web viewer
Author-email: Loan Bernat <l.bernat@sileane.com>
License-Expression: BSD-2-Clause
Project-URL: Homepage, https://magma-rob.github.io/
Project-URL: Documentation, https://magma-rob.github.io/docs/intro
Project-URL: Repository, https://github.com/MAGMA-rob/magma-gen
Project-URL: Issues, https://github.com/MAGMA-rob/magma-gen/issues
Project-URL: Changelog, https://github.com/MAGMA-rob/magma-gen/blob/main/CHANGELOG.md
Keywords: robotics,llm,agents,simulation,datasets,magma
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: magma_core[simulation]<3.0.0,>=2.0.1
Requires-Dist: magma_scenarios<3.0.0,>=2.0.0
Requires-Dist: PyYAML
Requires-Dist: requests
Requires-Dist: packaging>=23
Requires-Dist: torch
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: httpx<1,>=0.27; extra == "dev"
Requires-Dist: magma_gen[gui]; extra == "dev"
Provides-Extra: gui
Requires-Dist: fastapi>=0.110; extra == "gui"
Requires-Dist: uvicorn>=0.27; extra == "gui"
Dynamic: license-file

# 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](https://magma-rob.github.io/docs/intro) ·
[Report an issue](https://github.com/MAGMA-rob/magma-gen/issues)

## 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:

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

For generation without the viewer dependencies:

```bash
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.

```bash
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:

```bash
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`:

```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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://magma-rob.github.io/docs/intro) for
configuration, generation examples, agent setup, and custom scenario packages.

## Install from source

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

```bash
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](https://github.com/MAGMA-rob/magma-gen/blob/main/LICENSE).
