[deanq]

What

The ## Example sample in the top-level README is the first code most users copy. As written, it doesn't work, and it can leave a pod billing after the script exits:

Problem	Fix
The sync entrypoint called finetune.spawn(...) and returned. A spawned task keeps its pod until the job is awaited or cancelled, and TaskJob.wait()/cancel() are async, so the sync entrypoint could not clean up.	Use finetune.remote(...), which terminates the pod when it returns. A short paragraph shows spawn.aio() with wait()/cancel() from an async entrypoint.
finetune returned final_loss, which was never defined.	A small real training loop that saves a checkpoint to the mounted volume.
chat returned vLLM RequestOutput objects. Remote results must be JSON values.	Return the generated text.
Secret("hf-token") with no step to create it.	Add rp secret add hf-token.
The models volume was mounted on chat but never used. Nothing said the volume persists.	Use the volume only for finetune checkpoints, and note how to delete it.

The task now runs on one H100 instead of two, since the sample loop doesn't need more.

Tests

New tests/test_readme_example.py extracts the README's first python block and checks that:

• every name it uses is defined (this failed on final_loss before the fix)
• app discovery accepts it (spec validation passes)
• a sync @local_entrypoint doesn't call .spawn() on a task (this failed on finetune before the fix)

Test plan

• New tests failed against the old README and pass against the new one
• make quality-check (2776 passed)
• Checked rp secret add, rp volume delete VOLUME_ID, Invoker.aio, and TaskJob.wait/cancel against the CLI and source
• Not run live: it provisions H100s and pulls a gated model

[celine-runpod]

bugbot run

[Copilot]

🟡 Changes recommended

Non-positive step counts leave loss undefined, causing an UnboundLocalError after the persisted checkpoint has already been overwritten with an untrained model.

1 open issue

• Reject non-positive steps before overwriting the checkpoint · New

What changed in this PR

Makes the README’s introductory SDK example runnable and safer to copy, with explicit task cleanup and persistent-volume guidance.

Changes:

• Returns generated text from inference and adds a training loop that saves a checkpoint.
• Uses blocking task execution and documents async cleanup, secret setup, and volume deletion.
• Adds regression checks for undefined names, app discovery, and synchronous task spawning.

File	Description
tests/​test_readme_example.py	Adds validation checks for the README example.
README.md	Updates the example and documents resource setup and cleanup.

_{Review effort: Balanced}