freesolo-flash-dev 1.2.119__tar.gz → 1.2.121__tar.gz

freesolo_flash_dev-1.2.121/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Changelog
+
+Notable changes to `freesolo-flash`. The dev-channel package `freesolo-flash-dev` ships in
+lockstep at the same version.
+
+Releases happen by merging a version bump from `dev` into `main`, which publishes to PyPI
+(`.github/workflows/publish.yml`). Versions are `MAJOR.MINOR.PATCH`.
+
+This file starts at 1.1.35. Earlier releases are not reconstructed here; use
+`git log` for anything before that.
+
+## Unreleased
+
+### Added
+
+- OpenAI chat serving now preserves mirror sampling controls across packaged, hosted, and managed
+  entry points: up to four indexed choices, signed seeds, frequency and presence penalties, and
+  OpenAI token logprobs. Buffered and raw SSE responses retain independent choice terminals and
+  aggregate request usage; the decoded text-only stream remains single-choice.
+- A `flash-cli` console script, the same entry point as `flash` under a name nothing else
+  claims. The `server` and `dev` extras install `runpod-flash`, which declares its own `flash`
+  script; whichever distribution is installed last wins, so on a control-plane host
+  `pip install 'freesolo-flash[server]'` could leave `flash` running RunPod's CLI, which exits 0
+  and does nothing. `flash` is unchanged and remains correct on a base (client-only) install.
+
+### Changed
+
+- Run-backed adapters now use only explicit permanent checkpoint identities, `<run_id>/final` and
+  `<run_id>/step-N`. Bare run aliases, composite source-revision identities, activation, implicit
+  checkpoint fallback, and public artifact provenance have been removed across hosted, managed, and
+  customer-owned serving. Checkpoint bindings are write-once, exact undeploy preserves siblings,
+  and customer-owned manifests use schema v2.
+- Active training now exposes exactly `Qwen/Qwen3.5-9B`, `Qwen/Qwen3.8-27B`, and
+  `Qwen/Qwen3.6-35B-A3B`. Hosted serving remains active for 9B and 35B-A3B; hosted Qwen3.8 27B
+  remains inactive. Qwen3.8 uses the immutable BF16 revision
+  `1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0` and official native block-FP8 serving revision
+  `017b9c7af6b5689d5dd426a76e0bc077eb5ca20a`, with the logical base and tokenizer provenance kept
+  distinct from the served checkpoint. The Qwen3.5 0.8B, 2B, and 4B tiers and
+  `Qwen/Qwen3.6-27B` cannot activate, while historical status, accepted billing retry,
+  cancellation, cleanup, hosted revocation, and exact identity-based undeploy remain available.
+  Qwen3.6 27B adapters are not compatible with Qwen3.8.
+- Customer-owned serving is now Modal-only and requires explicit `--provider modal`. Modal remains
+  live-qualified for all three active models. The 27B and 35B-A3B qualifications stay bound to the
+  exact certified serving image digest. Each deployment still serves one exact base model. The 27B
+  engine keeps its `H100!` placement and distinct served checkpoint and tokenizer provenance. The
+  35B-A3B engine keeps its H200, BF16, FP8 KV, 32K context, eight-sequence, 4096 batched-token, and
+  six rank-64 LoRA-slot contract. Customer-serving RunPod commands, profiles, identities, and
+  lifecycle code are removed without a compatibility or teardown shim. Managed RunPod training,
+  serverless workers, dependencies, provider routing, artifacts, and caching are unchanged.
+- `[train] init_from_adapter` now works for every source/target algorithm pair. SFT was rejected as
+  a warm-start target, so an adapter could be continued only by GRPO or OPD; that restriction
+  described the retired trl SFT backend, and the verl backend that replaced it loads a warm-start
+  adapter exactly like the other two. All nine combinations of `sft`, `grpo`, and `opd` are
+  supported, including same-algorithm continuation. A warm-started SFT run also inherits its
+  source's base-model pin instead of resolving its own, so it stays deployable and no longer breaks
+  when the base model's hub tip moves.
+- Managed attempts now pin, verify, and report one immutable Flash source archive across retries and recovery.
+- Multi-turn GRPO now clones each sibling rollout from the task state that produced its prepared
+  prompt. Environments that record randomized episode choices on the task during `start_episode`
+  are stepped and scored against the same episode the model saw, without sharing mutable state
+  between sibling rollouts.
+- A RunPod attempt's stall window is now measured from evidence timestamps rather than from when
+  the control plane happened to look at it. The window was seeded from the moment polling started
+  and was reset again by the first status read, and a heartbeat was credited at the time it was
+  read rather than the time it was written. Every one of those is a wall-clock reading, so each
+  reattach handed a worker that was already wedged a complete fresh setup window, and a supervisor
+  that reattached repeatedly could keep a dead worker on a paid GPU until the run's wall deadline.
+  The window is now anchored to the persisted launch, a heartbeat is credited at its own timestamp
+  clamped to that launch, and only a genuine status transition counts as progress. Instance
+  polling (Vast/Lambda) already worked this way; this brings RunPod onto the same rule. A job that
+  is still queued is unaffected: the capacity wait keeps its own exemption, so a worker granted
+  late still gets its full cold-start budget.
+- An attempt's terminal artifacts (its strict marker plus `metrics.json`) are now interpreted by
+  one shared protocol instead of being decoded separately by live instance polling and by each
+  recovery path. The two decoders disagreed about identical bytes. A marker that could not be tied
+  to the attempt was a terminal failure to the live poller but indistinguishable from "no marker
+  yet" to recovery, so the same corrupt artifact produced a different story depending on which
+  layer happened to observe it; recovery now names it rather than logging silence. Neither path
+  ever adopted such a marker as completed work, and neither does now. Recovery also computed a
+  fresh observation window for the marker and then another for `metrics.json`, so the real ceiling
+  was their sum and moved with however long the first read took; both reads now share one window,
+  which makes the bound the cutoff rather than the sum.
+- CI runs the offline test suite on both supported interpreters (3.11 and 3.12) rather than
+  3.11 alone, and sets `HF_HUB_OFFLINE` / `TRANSFORMERS_OFFLINE` so a test that reaches the
+  network fails deterministically instead of depending on runner connectivity.
+- Every GitHub Action is pinned to a commit SHA rather than a mutable tag.
+- `mypy` runs in CI as an advisory (non-blocking) job.
+
+### Fixed
+
+- Qwen3.6 FP8 MoE serving now preserves unquantized activations for LoRA A while keeping the base
+  MoE path quantized, backporting the exact vLLM PR #42120 behavior into the pinned 0.23.0 image.
+- GRPO publication now validates complete finite optimizer-step actor gradient norms instead of
+  masked advantage-bound spread, so valid truncated groups are not falsely rejected and deployable
+  checkpoints remain withheld until terminal evidence validation succeeds.
+- Completed verl children now finish each captured W&B run before the W&B service shuts down,
+  avoiding teardown tracebacks, and `flash env setup` now gives every starter config explicit W&B
+  project and folder-derived run metadata.
+
+- An ordered `[gpu] type` list is now priced over every class it declares acceptable, not just the
+  first. Allocation cost-ranks the whole set, so quoting the head alone priced a shape the run may
+  never be given — an authored `["B200", "H100"]` quoted roughly 3x the H100 the allocator would
+  really rent, and the submit-time affordability check runs on that estimate, so a run the
+  organization could afford could be refused before allocation ever got to choose. A single
+  authored class is still a hard pin, and a no-fit rejection now names every acceptable class
+  rather than whichever happened to be written first.
+
+- A provider preference that exhausts every configured provider no longer falls back to quoting
+  hardware this plane cannot rent. The final fallback dropped the restriction and ranked the
+  registered RunPod pool regardless of credentials, so a vast-only plane could quote a B200: the
+  estimate passed affordability and the run was recorded, only for live allocation to fail. The
+  quote now raises against the eligible set, which names the real constraint.
+
+- A GitHub token that is invalid, expired, or missing a scope now fails during preparation instead
+  of after a GPU is rented. Non-rate-limit 401 and 403 responses were left as untyped errors, which
+  the submit-time preflight treats as a transient blip worth deferring, so the run proceeded
+  through affordability and allocation and hit the same permanent credential error on the worker.
+  They are now classified permanent, like 404 and 422. The rate-limit 403 is still transient.
+
+- A slow heartbeat upload no longer stalls every other heartbeat behind it. The throttle clock only
+  advances once a commit lands, so during a slow HuggingFace commit other callers still saw an
+  upload as due and blocked on the upload lock for up to its acquire timeout — 30s, or 120s on a
+  critical stage — which stalled the liveness daemon and delayed leaving the wrapped stage by the
+  same window. A throttled heartbeat now skips while a commit is in flight, since that commit
+  already carries the stage's state. Terminal, error, initial, and forced step commits still queue
+  and land: they carry state no later heartbeat would repair.
+
+- A GRPO or OPD run whose rollout actor exited hard no longer wedges on a paid GPU until the
+  wall-time limit. The actor's `os._exit` bypassed verl's own prompt handler, so the prompt
+  stayed `running` forever and verl's unbounded replay poll waited on it at ~0% utilization. The
+  child now writes durable failure evidence, marks the prompt failed, cleans up, and only then
+  exits, and replay sampling fails the step on an explicit failure tag or a positively dead
+  actor instead of returning a survivor-only batch that would silently train on fewer rollouts
+  than were collected. A child that reaches the fit loop and then stops producing distinct
+  output, while the parent has no teacher or environment work in flight, is torn down with a
+  named cause rather than running silently to the limit; repeated identical lines count as
+  silence, and authoritative OOM, host-RAM, and infrastructure evidence still classifies the
+  exit first.
+- `flash models deploy` now warns before it moves the shared `<run-id>` model id onto a
+  different checkpoint. Every checkpoint of a run is served under that one id, so deploying
+  `<run-id>/step-50` while `step-100` was live silently changed what `<run-id>` served for
+  everyone using it — which made "deploy a second checkpoint to compare" a destructive
+  operation on the first, and read as a serving regression rather than the deploy that caused
+  it. The warning names both checkpoints and points at `flash models chat <run-id>/step-N`,
+  which addresses a checkpoint directly and does not depend on where the id points. It is
+  advisory: the deploy still proceeds, the pre-deploy read is abandoned outright once it exceeds
+  a few seconds so no shape of slow plane can hold a deploy behind it, and a control plane that
+  cannot answer (or answers with a checkpoint step this client cannot read) does not fail the
+  command. A deployment whose activation outcome was never settled still warns, but without
+  naming a checkpoint: that record's step describes the incoming attempt rather than what the id
+  currently serves, and the authoritative target is server-side only, so the warning says the
+  live checkpoint cannot be determined and points at `flash models deployments`.
+
+- A response deadline did not actually bound a response that arrived slowly. The deadline is
+  checked between reads, but each read asked for a fixed number of bytes and blocked until all of
+  them arrived, so a peer trickling a short body kept one read inside the socket timeout
+  indefinitely and the check never ran: a 2s deadline took 12s on a 42-byte body, and 61s when
+  the socket timeout was the client default. Reading whatever has already arrived lets the check
+  run, which bounds every stall shape. This affected `flash env list`, whose deadline exists to
+  stop a slow environment hub hanging the command, as well as the new pre-deploy read.
+
+- A response deadline could still be overrun by a read that began near its end. The socket timeout
+  is installed once, when the request opens, and time spent connecting and waiting for headers is
+  charged to the deadline but not to that timeout, so a peer that delayed its headers and then
+  stalled mid-body held the call open past the deadline: 3.5s against a 2s budget. Each read now
+  re-caps the socket to the remaining budget, so the two bounds agree instead of stacking. On a
+  body still arriving this surfaces as a timeout rather than the "stalled" message; both bound the
+  call, and which one wins is a race not worth depending on.
+
+- Commands printed for the operator to run (the resume/cancel hand-off after `flash train`,
+  usage strings, `next:` hints) now name the executable actually invoked rather than always
+  `flash`. On a host where `runpod-flash` owns the `flash` script, the printed
+  `flash runs cancel <run-id>` exited 0 without cancelling, leaving a run billing while the
+  operator believed they had stopped it. Reached through the `python -m flash.cli` escape hatch,
+  the printed command now names the interpreter that is actually running, rather than a bare
+  `python` that is absent on a python3-only host and may resolve to a different environment
+  inside a virtualenv.
+
+- `flash env setup` scaffolded hosted-only environment instructions on every plane. A
+  self-hosted plane cannot publish to Freesolo's managed environment hub, so the generated
+  configs left `[environment] id` empty (which fails validation) beside a `flash env push`
+  command that could not work. Against a self-hosted plane the scaffold now emits the
+  `github:owner/repo@ref:path` id form, which such a plane resolves directly. Output against
+  the managed plane is unchanged.
+
+- `flash-server` reported missing operator configuration as an unhandled ASGI startup
+  exception, so the actionable message arrived under ~20 frames of starlette/contextlib. The
+  refusing half of the preflight now runs before uvicorn starts, and `flash-server` prints
+  `error: ...` and exits 3 (uvicorn's `STARTUP_FAILURE`, which this path already used, so
+  supervision keying on it is unaffected). The advisory warnings still come from the lifespan
+  alone, so a booted plane logs them once.
+- `flash env test` blamed the reward function for a gold answer that scored zero, when the
+  gold completion is equally likely to be at fault: with no `sft_completion` hook the replayed
+  answer is the dataset row's raw `output`, so a dataset whose `output` is a bare value fails a
+  grader that (correctly) requires a wrapper. The warning now names both candidates and prints
+  the exact text it scored, verbatim rather than through the whitespace-collapsing, 200-character
+  preview that hid the formatting faults it exists to reveal. The scaffolded `environment.py`
+  documents that `output` is also the gold assistant turn SFT trains on, and that per-row scorer
+  state belongs in `metadata`.
+- `flash env test` labelled the replayed dataset turns as the text that scored zero, but a
+  multi-turn environment whose `step_episode` returns a `final_response_text` has that override
+  replace the episode's response before scoring, so the diagnostic named text the grader never
+  saw. It now reports what the scorer actually received, captured at the scoring call.
+- An environment that overrode its answer to the empty string had `flash env test` report the
+  replayed turns instead: the captured text was tested for truth, so a graded `""` was
+  indistinguishable from an episode that never reached the scorer. The override propagates on
+  `is not None`, so `""` really is what the grader saw -- and an empty answer explains a zero
+  reward on its own, making it the reading a reader most needs named rather than hidden.
+- A crashed scorer went unreported on an `echo` episode -- a row with no gold answer to replay,
+  which is also the case that leaves the GRPO gate with nothing to count. `flash env test` could
+  exit `overall: PASS` with every reward coming from a scorer that never ran. The scorer's error is
+  now surfaced for any policy.
+- A scorer that crashed behind the SDK's guard reached `flash env test` as a bare `0.000000`,
+  indistinguishable from a judged-wrong answer, because the adapter kept only
+  `RewardResult.score`. The new `FreesoloEnvironment.reward_with_error` returns the reward and the
+  discarded error from a single scoring call, so a missing runtime dependency names itself without
+  re-scoring the episode -- which would bill a paid judge twice and, for a non-deterministic
+  scorer, could report an error that did not produce the printed reward.
+- Two tests resolved Hugging Face model metadata over the network and passed only on a
+  connected runner. They now stub the resolver like their siblings already did.

freesolo_flash_dev-1.2.121/PKG-INFO

@@ -0,0 +1,352 @@
+Metadata-Version: 2.5
+Name: freesolo-flash-dev
+Version: 1.2.121
+Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
+Project-URL: Homepage, https://github.com/freesolo-co/flash
+Project-URL: Repository, https://github.com/freesolo-co/flash
+Author: Freesolo
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: fine-tuning,freesolo,grpo,llm,lora,rl,sft
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.11
+Provides-Extra: dev
+Requires-Dist: datasets>=2.19; extra == 'dev'
+Requires-Dist: fastapi<1,>=0.136; extra == 'dev'
+Requires-Dist: freesolo>=0.4.2; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: huggingface-hub>=1.2.0; extra == 'dev'
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: packaging<27,>=24; extra == 'dev'
+Requires-Dist: pillow>=11; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: referencing>=0.28.4; extra == 'dev'
+Requires-Dist: regex>=2024.11.6; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.6; extra == 'dev'
+Requires-Dist: runpod-flash<2,>=1.19; extra == 'dev'
+Requires-Dist: tiktoken>=0.12; extra == 'dev'
+Requires-Dist: tokenizers>=0.22; extra == 'dev'
+Requires-Dist: transformers<5.13,>=5.8; extra == 'dev'
+Requires-Dist: uvicorn<1,>=0.52; extra == 'dev'
+Provides-Extra: gpu
+Requires-Dist: accelerate>=1.4; extra == 'gpu'
+Requires-Dist: bitsandbytes>=0.49; extra == 'gpu'
+Requires-Dist: datasets>=2.19; extra == 'gpu'
+Requires-Dist: freesolo>=0.4.2; extra == 'gpu'
+Requires-Dist: huggingface-hub>=1.2.0; extra == 'gpu'
+Requires-Dist: peft>=0.19; extra == 'gpu'
+Requires-Dist: tiktoken>=0.12; extra == 'gpu'
+Requires-Dist: tokenizers>=0.22; extra == 'gpu'
+Requires-Dist: torch==2.10.0; extra == 'gpu'
+Requires-Dist: transformers<5.13,>=5.8; extra == 'gpu'
+Requires-Dist: uv>=0.5; extra == 'gpu'
+Requires-Dist: vllm==0.19.1; extra == 'gpu'
+Provides-Extra: serve-runtime
+Requires-Dist: fastapi<0.137,>=0.136; extra == 'serve-runtime'
+Requires-Dist: huggingface-hub>=1.2.0; extra == 'serve-runtime'
+Requires-Dist: pillow>=11.0.0; extra == 'serve-runtime'
+Requires-Dist: safetensors<1,>=0.8; extra == 'serve-runtime'
+Requires-Dist: transformers<5.13,>=5.8; extra == 'serve-runtime'
+Requires-Dist: uvicorn<1,>=0.52; extra == 'serve-runtime'
+Requires-Dist: vllm==0.23.0; extra == 'serve-runtime'
+Provides-Extra: server
+Requires-Dist: datasets>=2.19; extra == 'server'
+Requires-Dist: fastapi<1,>=0.136; extra == 'server'
+Requires-Dist: freesolo>=0.4.2; extra == 'server'
+Requires-Dist: httpx>=0.27; extra == 'server'
+Requires-Dist: huggingface-hub>=1.2.0; extra == 'server'
+Requires-Dist: jsonschema>=4.23; extra == 'server'
+Requires-Dist: modal==1.5.4; extra == 'server'
+Requires-Dist: pillow>=11; extra == 'server'
+Requires-Dist: referencing>=0.28.4; extra == 'server'
+Requires-Dist: regex>=2024.11.6; extra == 'server'
+Requires-Dist: runpod-flash<2,>=1.19; extra == 'server'
+Requires-Dist: transformers<5.13,>=5.8; extra == 'server'
+Requires-Dist: uvicorn<1,>=0.52; extra == 'server'
+Provides-Extra: serving
+Requires-Dist: fastapi<1,>=0.136; extra == 'serving'
+Requires-Dist: httpx>=0.27.0; extra == 'serving'
+Requires-Dist: modal==1.5.4; extra == 'serving'
+Requires-Dist: orjson>=3.10.0; extra == 'serving'
+Requires-Dist: pillow>=11; extra == 'serving'
+Requires-Dist: pydantic-settings>=2.6.0; extra == 'serving'
+Requires-Dist: pydantic>=2.7.0; extra == 'serving'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'serving'
+Description-Content-Type: text/markdown
+
+# Flash
+
+LoRA post-training for open-weight models: SFT, GRPO, and on-policy distillation. You
+describe a run in a TOML file, Flash allocates a GPU, trains, streams checkpoints, and
+serves the resulting adapter.
+
+```bash
+pip install freesolo-flash
+export FREESOLO_API_KEY=fslo_...
+flash login
+flash train run.toml
+```
+
+The allocator picks the cheapest validated GPU class that fits the run, then supervises it
+server-side: stall watchdog, bounded auto-retry resuming from the last streamed checkpoint,
+and endpoint GC.
+
+## What this repository is
+
+Flash is the **client and control plane** for Freesolo's hosted post-training service:
+
+| Path               | What it is                                                        |
+| ------------------ | ----------------------------------------------------------------- |
+| `flash/cli/`       | the `flash` CLI — no declared runtime dependencies\*              |
+| `flash/server/`    | the FastAPI control plane — run submission, auth, project scoping |
+| `flash/engine/`    | the GPU worker and training recipes — verl + colocated vLLM       |
+| `flash/providers/` | the GPU substrate — pricing, allocation, submit/poll              |
+| `flash/envs/`      | environment loading                                               |
+
+\* `pip install freesolo-flash` pulls nothing. Commands that run an environment **locally** —
+`flash env test` and `flash env eval` — do need the `freesolo` SDK, which they import at the
+point of use; install it with `pip install freesolo`.
+
+Two components stay Freesolo-operated and are **not** in this repository:
+
+| Component                 | Where it lives                                                                                         | Self-hosted equivalent                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
+| Multi-tenant identity     | `api.freesolo.co`; verifies keys and owns projects/orgs                                                | `FLASH_STANDALONE=1` runs single-tenant on your own key           |
+| Hosted Multi-LoRA serving | `serve.freesolo.co`, deployed from `flash/serving/`; `flash/serve/` owns the client and shared runtime | `flash serve deploy` provisions serving in your own Modal account |
+
+So there are three ways to use Flash: against the **hosted service**, **self-hosted** against
+your own GPU accounts, or as **training and provider code to read and modify**. The training
+path is self-hostable end to end — see **[SELF_HOSTING.md](SELF_HOSTING.md)**.
+
+## Using the hosted service
+
+The active training catalog is `Qwen/Qwen3.5-9B`, `Qwen/Qwen3.8-27B`, and
+`Qwen/Qwen3.6-35B-A3B`. Hosted serving is active for 9B and 35B-A3B; hosted Qwen3.8 27B remains
+inactive. The retired dense Qwen3.6 27B identity is never translated into Qwen3.8. Customer-owned
+Modal supports all three active models; 27B and 35B-A3B are bound to the certified serving image
+digest. Customer-owned `flash serve` requires explicit `--provider modal`. Customer-serving RunPod
+commands and deployment identities are unsupported, with no migration or teardown shim. Managed
+RunPod training remains supported and unchanged.
+
+`flash login` is not interactive. Export `FREESOLO_API_KEY` first so the key does not appear in process listings:
+
+```bash
+pip install freesolo-flash
+export FREESOLO_API_KEY=fslo_...
+flash login          # validates the key, stores it in ~/.flash/config.json
+flash whoami         # confirm the identity behind it
+```
+
+Every run names an environment, which supplies the task data and the reward or SFT target.
+Environments are published under a project, which scopes them to an organization:
+
+```bash
+flash projects create my-project                       # returns a project uuid
+flash projects list                                    # look up existing uuids
+flash env setup                                        # scaffold environment.py + dataset/train.jsonl
+flash env push --project PROJECT_UUID --name my-env .  # returns an environment id
+```
+
+Every training TOML carries a required top-level `project`, validated against the
+authenticated organization before Flash allocates anything:
+
+```toml
+project = "your-project-uuid"
+model = "Qwen/Qwen3.5-9B"
+algorithm = "sft"
+
+[environment]
+id = "your-org/your-project/my-env"
+
+[train]
+epochs = 1
+max_examples = 1000
+lora_rank = 32              # lora_alpha defaults to 2 x lora_rank; set it to override
+```
+
+```bash
+flash train run.toml                  # submit, prints a run id
+flash runs status RUN_ID               # follow it
+flash models deploy RUN_ID/final             # serve the final checkpoint
+flash models chat RUN_ID/final -m "hello"    # talk to it
+```
+
+Run management lives under `flash runs` (`list`, `status`, `log`, `cancel`, `checkpoint`)
+and serving under `flash models` (`deploy`, `chat`, `deployments`, `undeploy`, `export`).
+`flash models` lists supported base models — six curated Qwen checkpoints — and `flash gpus`
+lists GPU classes with estimated $/hr.
+
+Intermediate RL checkpoints are deployable: list them with `flash runs checkpoint RUN_ID`,
+then pass `RUN_ID/step-N` as the checkpoint id. To copy a finished adapter into your own
+HuggingFace repo:
+
+```bash
+export HF_TOKEN=hf_...
+flash models export --adapter-id RUN_ID/final --repository your-org/your-repo
+```
+
+There are no built-in task environments — the environment you push defines the task.
+Single-turn and bounded multi-turn environments are supported.
+
+### Calling a deployed adapter from your own app
+
+Deploy once with `flash models deploy RUN_ID/final`, then POST chat requests with your API key:
+
+```bash
+export RUN_ID=flash-1782194170-ce1cfcff
+export FREESOLO_API_KEY=fslo_...
+
+curl -X POST "https://flash.freesolo.co/v1/runs/$RUN_ID/chat" \
+  -H "Authorization: Bearer $FREESOLO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "{\"checkpoint_id\": \"$RUN_ID/final\", \"messages\": [{\"role\": \"user\", \"content\": \"hello\"}], \"max_tokens\": 256}"
+```
+
+The response uses the OpenAI chat-completions shape; read `choices[0].message.content`. The
+checkpoint id is the permanent serving identity. If that checkpoint is not deployed yet, the
+endpoint returns `409` with a hint to deploy first. Prefer this control-plane endpoint over calling the serving backend
+directly: it enforces run ownership and forwards per-run serving options such as
+thinking-mode parity.
+
+### Workload estimates (SFT)
+
+`flash train`, `--dry-run`, and `--cost` read the pinned environment's packaged dataset
+without importing `environment.py`. `dataset/train.jsonl` is the canonical default;
+`dataset/train.json` also works, and `[environment.params] split` or `dataset_path` can
+select another packaged file.
+
+The estimate tokenizes raw `input`/`output` fields plus the statically readable training
+contract. Environment-added prompts, few-shot examples, tool schemas, filters, and
+transformations are **not** executed, so real training can retain fewer rows, truncate more
+often, and cost more than the estimate. If no readable dataset exists, cost, dry-run, and
+submit all fail before GPU allocation rather than billing a profiling run.
+
+## Working on the code
+
+The test suite is CPU-only and offline by default. No GPU, no network, no credentials:
+
+```bash
+uv sync --extra server --dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q
+```
+
+CI (`.github/workflows/ci.yml`) runs those on both supported interpreters (3.11 and 3.12),
+plus two size gates and a serial pass for timing-sensitive tests:
+
+```bash
+uv run python scripts/check_file_size.py      # no module in flash/ over 1000 lines
+uv run python scripts/check_function_size.py  # no function in flash/ over 150 lines
+uv run pytest -q -m wallclock                 # asserts on real elapsed time; runs alone
+```
+
+`mypy` also runs in CI but is **advisory** — it reports existing type errors without failing
+the build. Formatting is gated, so run `uv run ruff format .` before you push.
+
+> **The `flash` command can belong to something else.** The `server` and `dev` extras install
+> `runpod-flash`, which declares its own `flash` console script; whichever installs last wins,
+> and RunPod's exits 0 while doing nothing. Use **`flash-cli`** — the same entry point under a
+> name nothing else claims — or `python -m flash.cli` from a checkout. A base
+> `pip install freesolo-flash` is unaffected.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the branching model — in short, **pull requests go
+into `dev`**.
+
+### Layout
+
+- `flash/core/catalog.py` — curated model catalog (Qwen3.5, Qwen3.8 dense, and Qwen3.6 MoE), VRAM
+  sizing, and each model's `thinking` capability
+- `flash/schema/`, `flash/core/spec.py` — TOML to `JobSpec`
+- `flash/runner/` — server-side run supervisor (durable job handle, retries, cost guard)
+- `flash/providers/` — GPU substrate behind the `base.Provider` protocol, with `allocator.py`
+  picking the cheapest fitting class
+- `flash/engine/` — the on-GPU worker (verl + colocated vLLM rollouts) and the shared recipe.
+  SFT targets and RL rewards route through the active environment, so task-specific grading
+  lives with the example, not in the engine
+- `flash/envs/` — environment registry and the Freesolo SDK adapter
+- `flash/serve/` — serving client, shared runtime, and customer-owned provider deployment
+- `flash/serving/` — the hosted multi-LoRA Modal app behind `serve.freesolo.co`
+- `flash/server/` — the FastAPI control plane (run via the separate `flash-server` command)
+- `tests/` — pytest suite, CPU-only and offline
+
+Within `flash/engine/worker/`, trainers live under `train/`, split by algorithm (`sft/`,
+`rl/`, `opd/`) over a shared `core/`. Each carries a `child/` holding stdlib-only modules
+**copied** into the verl subprocess rather than imported — flash and verl pin incompatible
+torch/vllm versions, so neither can import the other.
+
+## Self-hosting
+
+Run your own control plane against your own GPU accounts, with no Freesolo backend involved.
+**[SELF_HOSTING.md](SELF_HOSTING.md) is the full guide**; the short version:
+
+```bash
+pip install 'freesolo-flash[server]'   # the base install is client-only
+
+export FLASH_STANDALONE=1
+export FREESOLO_INTERNAL_KEY=$(openssl rand -hex 32)
+export HF_TOKEN=hf_...
+export FLASH_HF_NAMESPACE=your-hf-username   # a namespace your HF_TOKEN can write to
+export RUNPOD_API_KEY=...                    # or LAMBDA_API_KEY, or VAST_API_KEY
+
+flash-server --host 0.0.0.0 --port 8080
+```
+
+You need **one** of RunPod, Lambda, or Vast. Providers whose key is unset are never
+considered, and the allocator only proposes classes it can actually provision. Startup fails
+only when all three are missing.
+
+`FLASH_STANDALONE=1` stops the plane calling out for project, environment, and billing
+validation, and trusts `FREESOLO_INTERNAL_KEY` as a single-tenant operator credential.
+External bearer tokens are rejected rather than accepted unverified. A standalone plane is
+**single-tenant** — whoever holds that key can spend your GPU budget, so keep it off
+untrusted networks. See [the security model](SELF_HOSTING.md#the-security-model).
+
+`flash serve deploy` provisions serving in your own Modal account and requires explicit
+`--provider modal`. Each deployment owns one exact base model and its compatible adapters; another
+base model requires another deployment. Customer-serving RunPod identities are unsupported.
+It implements the same contract `flash/serve/` speaks; [docs/serving-contract.md](docs/serving-contract.md)
+documents it if you would rather write your own.
+
+The GPU worker image is public and published under an explicit CUDA tag, not `latest`:
+
+```bash
+docker pull ghcr.io/freesolo-co/flash-worker:cu128
+```
+
+## Release channels
+
+Two channels are published to PyPI from the _same source_, distinguished by one line in
+`flash/_internal/channel.py`:
+
+| Channel | PyPI package         | CLI         | Default plane           | Published on                           |
+| ------- | -------------------- | ----------- | ----------------------- | -------------------------------------- |
+| prod    | `freesolo-flash`     | `flash`     | `flash.freesolo.co`     | a version bump merged to `main`        |
+| dev     | `freesolo-flash-dev` | `flash-dev` | `flash-dev.freesolo.co` | a push to `dev` with an unused version |
+
+Each environment holds exactly **one** channel: both packages ship the same import package
+with one baked `CHANNEL` line, so installing both makes the later install win for _both_
+CLIs. For side-by-side prod and staging, use a virtualenv per channel (or `pipx`).
+
+Within a commit, `[project].version` and `[tool.flash-dev].version` must match (CI enforces
+this), so cutting a release bumps both. The **published** channels still differ, because dev
+publishes on merge to `dev` while prod publishes only once `dev` is promoted to `main`.
+
+Either CLI honours an explicit `FLASH_API_URL` or `login --api-url`; the channel only sets
+the default.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: [SECURITY.md](SECURITY.md) — do not
+open a public issue.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).