# Running Safe Synthesizer

## Local Run Prerequisites

- A Linux host with a CUDA-capable NVIDIA GPU.
- The Safe Synthesizer plugin installed as an editable local plugin, for repo development: `BOOTSTRAP_LOCAL_PLUGIN_DIRS=plugins/nemo-safe-synthesizer make bootstrap-python`.
- The separate Safe Synthesizer runtime venv created with `uv run nemo safe-synthesizer runtime setup`.
- A job spec JSON file with `data_source` and `config`.
- A local input file or directory when using `--data-source`.

If you submit **platform jobs** (not bare `run-local` with `--data-source`), start services first (`nemo setup --start-services` or `nemo services run`), then optionally register model filesets:

```bash
curl -s http://localhost:8080/health/ready
uv run python plugins/nemo-safe-synthesizer/scripts/setup_model_filesets.py --files-api-url http://localhost:8080
```

See `docs/safe-synthesizer/about/host-local-development.md` for when the platform is required.

## Platform Job Prerequisites

- The Safe Synthesizer service and Jobs service are available.
- `data_source` points to a platform fileset path such as `default/my-fileset#input.csv`.
- If `hf_token_secret` is set, the named platform secret exists in the target workspace.
- If PII classification is enabled, the model provider exists and is referenced as `<workspace>/<provider_name>`.

## Resolve the CLI

Run `command -v nemo 2>/dev/null || (test -x .venv/bin/nemo && realpath .venv/bin/nemo) || echo CLI_NOT_FOUND`.

- If the output is a path, use that path as the command prefix.
- If the output is `CLI_NOT_FOUND`, tell the user the NeMo CLI is not available in this environment and ask whether they want help installing or syncing dependencies.

## Choose the Execution Mode

Use host-local execution when the user is iterating on a local machine with CUDA/GPU access:

```bash
uv run nemo safe-synthesizer runtime setup
uv run nemo safe-synthesizer run-local \
  --workspace default \
  --spec-file nss-job.json \
  --data-source ./input.csv \
  --output-dir ./nss-output
```

Use the Jobs API or SDK when the user wants the NMP Jobs service to run Safe Synthesizer. The plugin CLI does not expose `nemo safe-synthesizer jobs` commands.

For CLI users, point them to the generated Jobs/API surface available in their installed NeMo CLI, or to the Python SDK builder documented in `docs/safe-synthesizer/tutorials/safe-synthesizer-101.md`.

## Minimal Spec Shape

```json
{
  "data_source": "default/my-input#input.csv",
  "config": {
    "enable_synthesis": true,
    "enable_replace_pii": false,
    "generation": {
      "num_records": 100
    },
    "evaluation": {
      "enabled": true
    },
    "privacy": {
      "dp_enabled": false
    }
  }
}
```

For platform submission, pass this object as the `spec` field in the Jobs API or SDK create payload.

`platform-job.json` wraps the job spec:

```json
{
  "spec": {
    "data_source": "default/my-input#input.csv",
    "config": {
      "enable_synthesis": true,
      "enable_replace_pii": false
    }
  }
}
```

## Next Steps

- Tune job parameters with `workflows/config.md` and `workflows/config-runs.md`.
- Reuse a prior adapter or run plugin tests: `docs/safe-synthesizer/about/host-local-development.md`.
- Retrieve job result files with `workflows/results.md`.
- Interpret output files with `workflows/artifacts.md`.
- Debug failed runs with `workflows/diagnose.md`.
