> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fine-tuning from AI agents

> Use versioned JSON commands to prepare, review, launch, inspect, and stop exact training plans, with a separate authenticated HTTP operator surface.

The `finetune` CLI shares the studio workspace without requiring a terminal or MCP server.
Schema discovery does not import training libraries or allocate compute.

```bash theme={null}
stateset-agents finetune schema
stateset-agents finetune models
```

Use the reviewed checkout and Python environment described in
[the quickstart](/stateset-agents/quickstart). Credentials belong in the environment, not
configuration JSON. Workspaces use OS permissions and should remain private.

## Parse reports and outcomes separately

Successful commands write one JSON object to stdout:

```json theme={null}
{"schema_version":1,"ok":true,"command":"status","result":{"runs":[]}}
```

Command failures use `ok: false`, controlled `error.code`/`error.message`, and exit 1.
CLI usage errors use help output and exit 2; diagnostics go to stderr. Check the exit code
and `ok`, then inspect the operation's business result:

* `validate`: `result.valid` can be false while the report succeeded.
* `readiness`: inspect failed checks and warnings; success is not provider authentication.
* `launch`: submission is not training completion.
* `quality`: `recorded_study_passed` can be false after a successful inspection.
* `status`: inspect terminal state and execution uncertainty as well as stored metrics.

## Prepare and review one run

Use a schema-derived configuration such as the [SFT fixture](/stateset-agents/quickstart#create-a-small-format-fixture):

```bash theme={null}
stateset-agents finetune validate --config config.json
stateset-agents finetune inspect-data --dataset reviewed-chat.jsonl --method sft
stateset-agents finetune readiness --config config.json --workspace outputs/finetune
stateset-agents finetune prepare --config config.json --workspace outputs/finetune
```

`validate` reads configuration only. `inspect-data` reads bounded regular files, rejects
malformed/ambiguous data, and reports positions without reflecting source values in errors.
Samples require `--include-samples`. Preparation copies input privately and returns
`result.run.run_id`, `result.run.plan_sha256`, `result.review`, and `result.launch_argv`.

Retain that response. Repeating preparation creates another run. Inspect the actual model,
revision, data identity, method, resource requests, timeout, seed, and billing policy before
launching. Changing the dataset after preparation does not change its retained snapshot.

## Launch the exact plan

```bash theme={null}
stateset-agents finetune launch RUN_ID \
  --expected-plan-sha256 REVIEWED_PLAN_SHA \
  --workspace outputs/finetune
stateset-agents finetune status RUN_ID --workspace outputs/finetune
```

Use the returned ID/checksum. If executing `launch_argv` programmatically, pass it as an
argument array to `subprocess.run`; do not join it into shell code. Remote launches require
`--allow-paid`, intentionally omitted from the returned array, and the backend's reviewed
cost policy. Add it only for authorized paid execution.

The worker rechecks plan bytes, dataset identity, package code, and submission ownership.
An identical launch retry returns `already_submitted: true` and starts no new worker, even
after failure. This is submission idempotence, not restart or checkpoint recovery.

Known terminal states include succeeded, failed, and cancelled. Interrupted supervision or
unknown execution can yield `terminal: null` and `state.execution_unconfirmed: true`:
the detached worker may still be active. A completion file alone cannot establish success;
an owned worker must publish the checked outcome. Inspect the original run before preparing
a replacement or repeating paid work.

## Inspect and stop

```bash theme={null}
stateset-agents finetune logs RUN_ID --source supervisor --workspace outputs/finetune
stateset-agents finetune provider-status RUN_ID --workspace outputs/finetune
stateset-agents finetune stop RUN_ID \
  --expected-plan-sha256 REVIEWED_PLAN_SHA --workspace outputs/finetune
```

Logs explicitly expose private output. Reads cover at most the final 128 KiB; offsets address
that bounded window. `auto` chooses nonempty training output with supervisor fallback;
explicit sources do not fall back. Missing output is not training success.

Provider status reads plan-bound retained allocation/cleanup receipts without provider calls,
reconnection, cancellation, or retries. Reconcile uncertain resources through the actual
provider before starting another remote run.

Local stops are cooperative and idempotent for the same plan. A receipt does not establish
worker exit. Queued jobs wait for admission, active training stops at a safe boundary,
and supervisor loss does not remove the reviewed local stop path. Changed package code and
remote backends reject unsupported local stops.

Use [exact recovery](/stateset-agents/checkpoints-and-evaluation#recover-exact-training-state)
instead of changing a failed plan to resume. Use [paired evaluation](/stateset-agents/checkpoints-and-evaluation)
to assess quality; latest training-metric deltas are not a quality winner.

## HTTP operator API

The newer `/finetune` routes require strict authentication and the **admin** role even when
general gateway development routes permit anonymous access. Configure an existing absolute
workspace in server-side `STATESET_FINETUNE_WORKSPACE`. This is a single-operator workspace,
not a tenant ownership grant; clients cannot choose arbitrary server data/report paths.

| Request | Effect |
| - | - |
| `GET /finetune/capabilities` | Shared configuration, methods, effects, and payload limits |
| `POST /finetune/validate` | Configuration report; no dataset read |
| `GET /finetune/runs?limit=20` | Bounded retained run metadata |
| `GET /finetune/runs/{id}` | Run metadata and exact plan checksum for stop review |
| `GET /finetune/runs/{id}/workflow` | Retained dataset/setup inspection |
| `GET /finetune/runs/{id}/provider` | Retained provider observations; no provider request |
| `GET /finetune/runs/{id}/checkpoints` | Recovery choices without preparation |
| `GET /finetune/runs/{id}/quality` | Recompute recorded quality and artifact binding |
| `POST /finetune/runs/{id}/quality` | Import paired JSON reports |
| `POST /finetune/runs/{id}/stop` | Request local stop with `expected_plan_sha256` |

Streamed body limits are 64 KiB for configuration, 8 MiB for quality, and 4 KiB for stop.
Overlapping setup/artifact inspections return 429 with `inspection_busy`; metadata and local
stop remain available. HTTP failures use the gateway status/error envelope and specific
detail codes. A successful response can still report invalid settings or a failed study gate.

These routes do not launch training, run a judge, prepare recovery, or guarantee remote
cleanup. Use the CLI/TUI for separately reviewed preparation and execution. The generated
[Agents API reference](/api-reference/agents/overview) is a separately exported snapshot;
inspect the running server's capabilities for this newer source-derived surface.

Source basis: `docs/FINETUNING_AGENTS.md`, `stateset_agents/cli_finetune.py`, and the current
`finetune schema`, reviewed October 20, 2026. Continue with
[checkpoint and quality evidence](/stateset-agents/checkpoints-and-evaluation).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.