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

# River SFT, native RL, and retained evidence

> Distinguish managed SFT, synchronous group-relative RL, and native CISPO sandbox training, with hosted-checkpoint recovery and scoped study results.

River executes remote sampling, autograd, and optimizer work. StateSet supplies task
definitions, rewards, batch/protocol checks, selection, and retained experiment evidence.
The reviewed integration supports Python **3.12+** and `river-client>=0.11.0,<0.12`.

From the reviewed source checkout:

```bash theme={null}
pip install -e '.[river]'
stateset-agents river-preflight
```

Configure `RIVER_API_KEY` through your environment for live use. Local preflight checks SDK,
Python, and credential presence without constructing a client or making a provider request.
`--live` separately queries account model capabilities; neither mode trains or samples.
A passing capability report does not establish funding, capacity, or model quality.

## Choose the actual workflow

| Workflow | Entry point | Meaning |
| - | - | - |
| Managed SFT | `train-remote --provider river` or studio River/SFT | Assistant-only supervised training |
| Rejection-sampling SFT | `flywheel --provider river --algorithm sft` | Collect/curate candidate responses, then train supervised targets |
| Synchronous RL | `flywheel --provider river --algorithm cispo` | One logical group-relative optimizer update per round; also supports its documented PPO/importance-sampling objectives |
| Native sandbox RL | `python -m stateset_agents.training.river_refund` | River RolloutEngine/AsyncTrainer with executed StateSet sandbox actions |

The studio's River backend supports SFT, not native studio GRPO/GSPO/DAPO. These workflows
have different data and recovery contracts. A nominal algorithm name does not establish
that the same trainer, reward, or optimizer schedule was used.

## Managed SFT and hosted artifacts

The studio requires explicit `cost_policy: provider_billed` and an authorized remote launch
with `--allow-paid`. This interface does not enforce a dollar ceiling or a River whole-run
deadline. Token reservations and request timeouts are not dollar-spend guarantees.

SFT captures dataset source bytes/row identity and starting-checkpoint lineage before work.
For continuation, a `RemoteJobSpec` can explicitly set `harvest.checkpoint` to a `river://`
URI or a directory with `river_checkpoint.json`. Declared model/rank compatibility is checked
before provider work. `parent_adapter` records lineage separately; it does not load weights.

Results retain `river_checkpoint.json`, a `river://` URI, and provenance. The file is a
hosted pointer, not downloaded adapter weights, so local `serve --checkpoint` cannot load
it. Hosted inference/deployment has its own account capability and billable lifecycle.

## Native refund RL

Inspect the runner and prepare its default offline plan from the source checkout:

```bash theme={null}
python -m stateset_agents.training.river_refund --help
python examples/river_refund_rl.py --dry-run --output outputs/refund-plan
```

The native runner bridges StateSet environments into River's rollout engine. Policies must
execute sandbox lookups/actions to obtain private facts; prompt text is not evidence that
an external action occurred. Successful sandbox episodes are separate from real refunds,
bank transfers, or merchant outcomes.

Current evidence binds generated token IDs, sampled log probabilities, rewards, masks,
native datums, checkpoint receipts, and acknowledged updates. Invalid sampling evidence or
policy mismatch rejects a batch before forward/backward. Truncation is explicit and cannot
silently become a successful episode or verified SFT demonstration.

The latest recovery replication used one logical CISPO batch per seed: group-centered
advantages without standardization, token normalization, four samples per task, LoRA rank
16, and at most one acknowledged update. This is the retained study's configuration, not a
universal RL default. Zero-signal attempts are retained rather than replaced until a
favorable batch appears.

## Recovery and provider uncertainty

Synchronous RL persists validated `rl_state.json` and optimizer checkpoint progress.
Explicit resume restores the last committed state and executes only remaining rounds.
If all rounds committed, final local publication can finish offline. Missing/corrupt state
blocks continuation instead of restarting fresh.

An in-flight remote update can outlive client interruption. Local receipts cannot undo it,
refund its usage, or independently attest remote weight bytes. Preserve the original
configuration/handle and inspect committed progress before retrying. Cleanup errors retain
the original training outcome and diagnostics; a completed checkpoint can remain fetchable
even when client cleanup fails.

Native recovery and study admission use their separate retained-state protocol. Do not
substitute the [local studio checkpoint flow](/stateset-agents/checkpoints-and-evaluation)
for River-hosted state.

## Latest retained results

| Study | Observations | Acceptance outcome |
| - | - | - |
| October 20 recovery RL replication | Six fixed seeds from one shared SFT parent; six acknowledged CISPO updates; parent 954/960 test successes, candidate 960/960 | Failed prespecified replication gate; no promotion |
| October 20 arithmetic continuation pilot | Both arms 157/158 validation; arithmetic improved, existing window-stress policy regressed | Stopped before test; all 308 test cases unattempted |
| October 19 boundary SFT continuation study | Across 768 test cases per arm: original 689, repeat-data control 719, boundary SFT 747 | Primary boundary-versus-control gate failed despite higher pooled success |

The recovery RL test difference was **0.625 percentage points**, with exact two-sided seed
sign-flip **p = 0.125** and seed/case bootstrap 95% interval **\[0, 1.458] percentage points**.
These observations condition on 40 shared synthetic case clusters and six training seeds;
four rollouts per case are aggregated before inference. They are not 960 independent
merchant trials or six independent base-model/SFT-parent replications.

An initial consecutive-seed protocol was stopped after discovering deterministic
sampler-stream reuse. It submitted zero optimizer updates and no evaluation cases; its
admissions/cost uncertainty remain separate. The corrected protocol retained a
source-bound sampler audit and widely spaced seeds. Distinct seed identities prevent
direct reuse under that audit; they do not prove random-stream independence.

The final study retained no observed test regressions but failed its significance and
prespecified strict per-seed improvement requirements. No best seed or checkpoint was
promoted. Billed dollar cost is unavailable; reserved tokens are admission bounds rather
than actual usage or a dollar cap. Production quality remains unverified.

## Reproduce the review boundary

The evidence source is the local October 20, 2026
`benchmark_results/training_contracts/20261020/river-recovery-replication/README.md` and
`replication-statistics.json`, with the stopped protocol retained separately. The provider
contract is `docs/RIVER_PROVIDER.md`; the arithmetic and boundary studies have their own
dated reports. Keep their original protocol, failures, and unattempted holdouts when
reporting results.

Current native SDK CI uses the real River rollout engine/trainer with scripted transport
and forbids live client/RPC construction. Those offline contract checks are separate from
paid provider evidence. No live training, deployment, or model-quality claim follows merely
from a passing mock suite.

Continue with [data isolation](/stateset-agents/industry-finetuning) or
[checkpoint selection and quality evidence](/stateset-agents/checkpoints-and-evaluation).


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