freesolo-flash-dev 0.2.25__py3-none-any.whl

flash/server/run_registry.py

@@ -0,0 +1,150 @@
+"""Best-effort reporting of managed Flash runs/checkpoints to the Freesolo backend."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import urllib.error
+import urllib.request
+from datetime import UTC, datetime
+from typing import Any
+
+from .auth import INTERNAL_KEY_ENV, freesolo_base_url
+
+_LOG = logging.getLogger("flash.server.runs")
+_TIMEOUT_S = 10.0
+_RUN_PATH = "/api/flash/runs/internal"
+_CHECKPOINT_PATH = "/api/flash/runs/checkpoints/internal"
+
+
+def _iso_from_epoch(value: float | int | None) -> str | None:
+    if value is None:
+        return None
+    try:
+        return datetime.fromtimestamp(float(value), tz=UTC).isoformat()
+    except (TypeError, ValueError, OSError):
+        return None
+
+
+def _post(path: str, body: dict[str, Any]) -> bool:
+    internal_key = os.environ.get(INTERNAL_KEY_ENV)
+    if not internal_key:
+        return False
+    req = urllib.request.Request(
+        f"{freesolo_base_url()}{path}",
+        data=json.dumps(body).encode("utf-8"),
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {internal_key}",
+            "Content-Type": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=_TIMEOUT_S) as resp:
+            return 200 <= resp.status < 300
+    except urllib.error.HTTPError as exc:
+        detail = ""
+        with contextlib.suppress(Exception):
+            detail = exc.read().decode("utf-8", "replace")[:500]
+        _LOG.warning("failed to report %s: HTTP %s %s", path, exc.code, detail)
+    except (urllib.error.URLError, OSError) as exc:
+        _LOG.warning("failed to report %s: %s", path, exc)
+    return False
+
+
+def _context_from_status(status: Any) -> dict[str, Any]:
+    platform = getattr(status, "platform_context", None)
+    if isinstance(platform, dict):
+        return platform
+    billing = getattr(status, "billing_context", None)
+    if isinstance(billing, dict):
+        return billing
+    return {}
+
+
+def _spec_from_status(status: Any) -> dict[str, Any]:
+    spec = getattr(status, "spec", None)
+    return spec if isinstance(spec, dict) else {}
+
+
+def _managed_environment_slug(spec: dict[str, Any]) -> str | None:
+    env = spec.get("environment") if isinstance(spec.get("environment"), dict) else {}
+    env_id = env.get("id")
+    if not isinstance(env_id, str) or not env_id.strip():
+        return None
+    try:
+        from flash.envs.adapter import is_managed_environment_slug
+
+        return env_id.strip() if is_managed_environment_slug(env_id.strip()) else None
+    except Exception:
+        return None
+
+
+def record_training_run(*, status: Any, key: dict[str, Any] | None = None) -> bool:
+    context = {**_context_from_status(status), **(key or {})}
+    org_id = str(context.get("org_id") or "").strip()
+    if not org_id:
+        return False
+
+    spec = _spec_from_status(status)
+    gpu = spec.get("gpu") if isinstance(spec.get("gpu"), dict) else {}
+    body = {
+        "orgId": org_id,
+        "runId": status.run_id,
+        "status": status.state,
+        "userId": context.get("user_id"),
+        "apiKeyId": context.get("api_key_id"),
+        "environmentSlug": _managed_environment_slug(spec),
+        "model": spec.get("model") if isinstance(spec.get("model"), str) else None,
+        "algorithm": spec.get("algorithm") if isinstance(spec.get("algorithm"), str) else None,
+        "phase": spec.get("phase") if isinstance(spec.get("phase"), str) else None,
+        "gpuType": gpu.get("type") if isinstance(gpu.get("type"), str) else None,
+        "costUsd": status.cost_usd,
+        "realizedCostUsd": status.realized_cost_usd,
+        "adapterRef": status.to_dict().get("adapter_ref"),
+        "artifactsDir": status.artifacts_dir,
+        "error": status.error,
+        "spec": spec,
+        "deployment": status.deployment,
+        "lastHeartbeat": status.last_heartbeat,
+        "gpuStatus": status.gpu_status,
+        "createdAt": _iso_from_epoch(status.created_at),
+        "updatedAt": _iso_from_epoch(status.updated_at),
+        "metadata": {"source": "flash.control_plane"},
+    }
+    return _post(_RUN_PATH, body)
+
+
+def record_training_checkpoint(
+    *,
+    spec: Any,
+    seed: int,
+    metrics: dict[str, Any],
+    artifact_path: str,
+) -> bool:
+    try:
+        from flash.runner import adapter_ref, get_status
+
+        status = get_status(spec.run_id)
+        ref = adapter_ref(spec, seed=seed)
+    except Exception:
+        return False
+    context = _context_from_status(status)
+    org_id = str(context.get("org_id") or "").strip()
+    if not org_id:
+        return False
+    body = {
+        "orgId": org_id,
+        "runId": spec.run_id,
+        "checkpointId": f"seed{seed}",
+        "seed": seed,
+        "phase": getattr(spec, "phase", None),
+        "adapterRef": ref,
+        "artifactPath": artifact_path,
+        "metrics": metrics,
+        "metadata": {"source": "flash.control_plane"},
+        "updatedAt": _iso_from_epoch(getattr(status, "updated_at", None)),
+    }
+    return _post(_CHECKPOINT_PATH, body)

flash/spec.py

@@ -0,0 +1,333 @@
+"""Structured job specification shared by CLI/API/runner and GPU workers."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .catalog import DEFAULT_GPU, DEFAULT_MODEL, normalize_algorithm
+
+_FALSE_STRINGS = {"", "0", "false", "no", "off", "none"}
+
+
+def _str_tuple(value: Any) -> tuple[str, ...]:
+    """Normalize a string-or-list knob (e.g. stop_sequences) to a tuple of strings.
+
+    A bare string is ONE element — never iterated into characters ("</s>" must not become
+    ('<','/','s','>')). None and empty strings -> () (no stop configured); empty entries
+    in a list are dropped."""
+    if value is None:
+        return ()
+    if isinstance(value, str):
+        return (value,) if value else ()
+    return tuple(s for s in (str(x) for x in value) if s)
+
+
+def coerce_bool(value: Any) -> bool:
+    """Parse a bool from loosely-typed sources (JSON request bodies / env / persisted dicts).
+
+    bool(...) on a string is truthy for ANY non-empty string, so "false"/"0"/"no" would
+    wrongly become True; treat the usual falsey strings (see ``_FALSE_STRINGS``) as False.
+    An already-bool value passes through.
+    """
+    if isinstance(value, str):
+        return value.strip().lower() not in _FALSE_STRINGS
+    return bool(value)
+
+
+def _coerce_str_map(value: Any) -> dict[str, str]:
+    """Coerce a loosely-typed spec field into a ``dict[str, str]``.
+
+    A malformed persisted spec (or programmatic caller) can set a mapping field to a non-dict;
+    `.items()` on that would crash `from_dict` with AttributeError. Treat a non-dict as empty,
+    mirroring how the other nested fields tolerate missing/garbage input.
+    """
+    if not isinstance(value, dict):
+        return {}
+    return {str(k): str(v) for k, v in value.items()}
+
+
+def _coerce_wandb(value: Any) -> WandbSpec:
+    """Coerce a loosely-typed ``wandb`` spec field into a ``WandbSpec``.
+
+    A malformed/older persisted spec can set ``wandb`` to a non-dict (e.g. a bare string), and
+    ``(value or {}).get(...)`` would crash ``from_dict`` with AttributeError on the worker. Treat
+    a non-dict as empty (default naming), mirroring ``_coerce_str_map``. String-coerce + trim the
+    leaves so a non-string label can't reach the W&B SDK / run-name path; blank -> None (default).
+    """
+    if not isinstance(value, dict):
+        return WandbSpec()
+
+    def _label(v: Any) -> str | None:
+        if v is None:
+            return None
+        s = str(v).strip()
+        return s or None
+
+    return WandbSpec(project=_label(value.get("project")), run_name=_label(value.get("run_name")))
+
+
+def _volume_gb(value: Any, default: int = 100) -> int:
+    """Parse the platform-managed weight-cache volume size, defaulting on anything not a positive int.
+
+    Tolerant by design (the field is platform-set, and stale/hand-edited specs must still load): a
+    missing / null / empty / non-numeric value, or a non-positive size (incl. the string "0" or a
+    negative), all fall back to ``default`` rather than crashing or round-tripping a nonsensical size.
+    """
+    if isinstance(value, bool):
+        # bool is an int subclass (int(True) == 1), so a stray boolean would become a 1 GB volume;
+        # treat it as invalid and default (mirrors the bool rejection in _opt_int).
+        return default
+    try:
+        gb = int(value)
+    except (TypeError, ValueError):
+        return default
+    return gb if gb > 0 else default
+
+
+def _opt_int(value: Any) -> int | None:
+    """Parse an optional int from a loosely-typed spec source; None stays None.
+
+    Rejects JSON booleans: ``bool`` is an ``int`` subclass in Python, so ``int(True)`` would
+    silently coerce a stray boolean train knob to 1 (and ``False`` to 0). Mirrors the
+    bool rejection in schema._train_int — a bool is a type error, not a number.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise TypeError(f"expected a number, got bool {value!r}")
+    return int(value)
+
+
+def _opt_float(value: Any) -> float | None:
+    """Parse an optional float from a loosely-typed spec source; None stays None.
+
+    Rejects JSON booleans (``bool`` is an ``int`` subclass) so a stray boolean train knob is
+    not silently coerced to 0.0/1.0; mirrors the bool rejection in schema._train_float.
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        raise TypeError(f"expected a number, got bool {value!r}")
+    return float(value)
+
+
+@dataclass(frozen=True)
+class EnvironmentSpec:
+    # Freesolo environment id. No default:
+    # a run must name an environment explicitly (validated in schema / the worker).
+    id: str = ""
+    params: dict[str, Any] = field(default_factory=dict)
+    # Pip requirements the GPU worker needs for this environment.
+    # Filled in client-side from the local install manifest so the managed control
+    # plane never depends on client-local state; empty means "derive on the server".
+    pip: tuple[str, ...] = ()
+    # Secret env var names the environment requires on the worker. Values are never stored in the
+    # spec; the client reads matching local env/.env values and sends them out-of-band via
+    # runtime_secrets.
+    secrets: tuple[str, ...] = ()
+    # Optional pinned commit SHA for the environment's GitHub ref, resolved ONCE in the control
+    # plane (runner._assign_resolved_env_sha, called from submit_job after the spec is finalized) so
+    # every worker boots from an immutable sha instead of each one re-resolving the symbolic ref
+    # (e.g. "main") against the GitHub commits API — which trips GitHub's secondary rate limit on a
+    # cold spawn wave. Empty (the default, and whenever the control-plane resolve fails) preserves
+    # today's behavior: the worker resolves the ref itself. The adapter only trusts a real 40-char
+    # sha (see adapter._resolve_ref_sha), so a stale/garbage value falls back to live resolution.
+    resolved_sha: str = ""
+
+
+@dataclass(frozen=True)
+class TrainSpec:
+    steps: int | None = None
+    epochs: int | None = None
+    lora_rank: int = 32
+    lora_alpha: int = 64
+    seeds: tuple[int, ...] = (0,)
+    # Artifact-store adapter ref output by `flash status`:
+    # ``<hf_repo>:<phase>/<run_id>/seed<N>``.
+    init_from_adapter: str = ""
+    # Per-run HuggingFace artifact repo ("owner/name") for this run's adapter/checkpoint/
+    # code storage AND serving. PLATFORM-MANAGED, not a user field: the control plane assigns
+    # it server-side in runner.submit_job (a per-run private dataset under the operator's
+    # namespace, written by the operator HF_TOKEN). A user-supplied value is ignored by
+    # schema.spec_from_dict; this field carries the control-plane-assigned repo to the worker.
+    hf_repo: str = ""
+    # Optimizer/batching knobs (SFT + GRPO). None -> the worker's tuned recipe default.
+    # batch_size is the GLOBAL/effective batch (SFT: grad-accum is sized to hit it; GRPO:
+    # prompts per optimizer step). max_length is the SFT max sequence length. save_every
+    # is the checkpoint interval in optimizer steps.
+    learning_rate: float | None = None
+    batch_size: int | None = None
+    max_length: int | None = None
+    save_every: int | None = None
+    # SFT caps (None/0 -> no cap). max_steps caps optimizer steps (cheap pre-flight smoke);
+    # max_examples truncates the SFT dataset.
+    max_steps: int | None = None
+    max_examples: int | None = None
+    # GRPO recipe knobs (datums parity), shipped by the SDK in [train] (NOT in
+    # [environment.params], which is forwarded verbatim to the Freesolo env loader).
+    # None/() -> recipe default. group_size = completions per prompt; temperature = rollout
+    # sampling temp; max_tokens = completion budget; kl_penalty_coef = KL beta;
+    # advantage_clip = centered-advantage clamp; thinking_length_penalty_coef =
+    # per-<think>-token reward deduction; stop_sequences = rollout stop strings.
+    group_size: int | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    kl_penalty_coef: float | None = None
+    advantage_clip: float | None = None
+    thinking_length_penalty_coef: float | None = None
+    stop_sequences: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class GpuSpec:
+    # The parse-time provisional GPU class (cheapest VALIDATED class that fits the model). GPU
+    # pinning is gone: the submit-time allocator always re-picks the cheapest fitting validated
+    # active RunPod class, so a config's gpu.type does NOT pin — ``type`` is just the offline
+    # sizing/display default and the carrier the runner overwrites with the actually-allocated
+    # class.
+    type: str = DEFAULT_GPU
+    disk_gb: int = 60
+    max_wall_seconds: int = 24 * 3600
+    # Auto-resubmit budget for infra-shaped failures (worker loss / stall / timeout);
+    # each retry resumes from the latest streamed checkpoint.
+    max_retries: int = 2
+    # Persistent RunPod network-volume weight cache (platform-managed, NOT user config). When set,
+    # the RunPod provider attaches a same-named volume in EVERY datacenter in the cache fleet and
+    # allows the endpoint across all of them (no single-DC pin), and the worker points HF_HOME at
+    # the mount so a model download is a one-time cost per region instead of per run. Assigned by
+    # the runner (``_assign_weight_cache_volume``); a single fixed datacenter is intentionally NOT
+    # a field — the DC SET is deploy-time platform policy (see jobs.weight_cache_datacenters), so a
+    # run can never be region-pinned. ``None`` = no volume (cold download, cross-region).
+    network_volume: str | None = None
+    network_volume_gb: int = 100
+
+
+@dataclass(frozen=True)
+class WandbSpec:
+    # Optional W&B naming, defined in the [wandb] config table (first-class spec config, NOT
+    # env vars). project/run_name are non-secret labels; the actual WANDB_API_KEY stays an
+    # env-var secret. None -> the worker's defaults ("flash" project, "flash-<phase>-<run_id>-
+    # seedN" run name).
+    project: str | None = None
+    run_name: str | None = None
+
+
+@dataclass(frozen=True)
+class JobSpec:
+    model: str = DEFAULT_MODEL
+    algorithm: str = "grpo"
+    environment: EnvironmentSpec = field(default_factory=EnvironmentSpec)
+    train: TrainSpec = field(default_factory=TrainSpec)
+    gpu: GpuSpec = field(default_factory=GpuSpec)
+    run_id: str = "local"
+    # Per-run worker-environment overrides merged into the GPU worker's env (highest precedence
+    # over the control-plane os.environ allowlist). The escape hatch for A/B kernel experiments
+    # that must differ PER RUN, not globally: e.g. an optimizer or LoRA-init override on just the
+    # experiment run while others keep the global default. Forwarded verbatim (string values);
+    # never set secrets here.
+    worker_env: dict[str, str] = field(default_factory=dict)
+    # "catalog" (curated models only) or "allow" (any HF model that fits the GPU).
+    model_policy: str = "catalog"
+    # Thinking/reasoning mode (thinking-capable models only). One flag per run, consumed
+    # identically by SFT rendering, RL rollouts, and serving (decoding parity). OFF by default
+    # (operator preference: training defaults to no-reasoning; set thinking = true to enable).
+    thinking: bool = False
+    # Optional W&B run naming from the [wandb] config table. Carried as typed spec config
+    # (round-tripped in the job-spec JSON the worker reads), not as environment variables.
+    wandb: WandbSpec = field(default_factory=WandbSpec)
+
+    @property
+    def phase(self) -> str:
+        return "rl" if self.algorithm == "grpo" else self.algorithm
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), sort_keys=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> JobSpec:
+        env = data.get("environment") or {}
+        # Defense-in-depth: a stale/older payload may still carry a local `path`. The worker only
+        # runs published Freesolo environment ids, so reject it here rather than silently
+        # dropping it.
+        if isinstance(env, dict) and env.get("path"):
+            raise ValueError(
+                "local environment paths are no longer supported; the worker only runs "
+                "published Freesolo environment ids"
+            )
+        train = data.get("train") or {}
+        gpu = data.get("gpu") or {}
+        return cls(
+            model=data.get("model", cls.model),
+            algorithm=normalize_algorithm(data.get("algorithm", cls.algorithm)),
+            environment=EnvironmentSpec(
+                id=env.get("id", ""),
+                params=dict(env.get("params") or {}),
+                pip=tuple(str(p) for p in env.get("pip") or ()),
+                secrets=_str_tuple(env.get("secrets")),
+                resolved_sha=str(env.get("resolved_sha") or ""),
+            ),
+            train=TrainSpec(
+                steps=_opt_int(train.get("steps")),
+                epochs=_opt_int(train.get("epochs")),
+                lora_rank=int(train.get("lora_rank", 32)),
+                lora_alpha=int(train.get("lora_alpha", 64)),
+                seeds=tuple(int(s) for s in train.get("seeds", (0,))),
+                init_from_adapter=str(train.get("init_from_adapter") or ""),
+                hf_repo=str(train.get("hf_repo") or ""),
+                learning_rate=_opt_float(train.get("learning_rate")),
+                batch_size=_opt_int(train.get("batch_size")),
+                max_length=_opt_int(train.get("max_length")),
+                save_every=_opt_int(train.get("save_every")),
+                max_steps=_opt_int(train.get("max_steps")),
+                max_examples=_opt_int(train.get("max_examples")),
+                group_size=_opt_int(train.get("group_size")),
+                temperature=_opt_float(train.get("temperature")),
+                max_tokens=_opt_int(train.get("max_tokens")),
+                kl_penalty_coef=_opt_float(train.get("kl_penalty_coef")),
+                advantage_clip=_opt_float(train.get("advantage_clip")),
+                thinking_length_penalty_coef=_opt_float(train.get("thinking_length_penalty_coef")),
+                stop_sequences=_str_tuple(train.get("stop_sequences")),
+            ),
+            gpu=GpuSpec(
+                type=gpu.get("type", DEFAULT_GPU),
+                disk_gb=int(gpu.get("disk_gb", 60)),
+                max_wall_seconds=int(gpu.get("max_wall_seconds", 24 * 3600)),
+                max_retries=int(gpu.get("max_retries", 2)),
+                # network_volume/network_volume_gb round-trip so the runner-assigned weight cache
+                # survives the to_dict()->from_dict() hops in _with_model_disk / _spec_with_gpu /
+                # _assign_managed_hf_repo before deploy. A legacy ``datacenter`` key (from the
+                # reverted single-DC pin) is intentionally ignored — the DC set is deploy-time
+                # policy now, so stale specs carrying it are tolerated, never region-pinned.
+                network_volume=gpu.get("network_volume"),
+                # Tolerant: null / "" / "0" / 0 / negative / non-numeric / missing -> the default.
+                # Platform-managed, so a stale or hand-edited spec must still load with a sane size.
+                network_volume_gb=_volume_gb(gpu.get("network_volume_gb")),
+            ),
+            run_id=data.get("run_id", "local"),
+            worker_env=_coerce_str_map(data.get("worker_env")),
+            model_policy=data.get("model_policy", "catalog"),
+            thinking=coerce_bool(data.get("thinking", False)),
+            wandb=_coerce_wandb(data.get("wandb")),
+        )
+
+    @classmethod
+    def from_json(cls, raw: str) -> JobSpec:
+        return cls.from_dict(json.loads(raw))
+
+
+def load_job_spec_from_env() -> JobSpec | None:
+    """Load FLASH_JOB_SPEC_JSON or FLASH_JOB_SPEC_PATH if present on a worker node."""
+    raw = os.environ.get("FLASH_JOB_SPEC_JSON")
+    if raw:
+        return JobSpec.from_json(raw)
+    path = os.environ.get("FLASH_JOB_SPEC_PATH")
+    if path and os.path.exists(path):
+        with open(path) as f:
+            return JobSpec.from_json(f.read())
+    return None

freesolo_flash_dev-0.2.25.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: freesolo-flash-dev
+Version: 0.2.25
+Summary: Flash — managed LoRA post-training (SFT/GRPO) 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
+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; extra == 'dev'
+Requires-Dist: freesolo>=0.2.49; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: huggingface-hub>=0.34; extra == 'dev'
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: runpod-flash; extra == 'dev'
+Requires-Dist: uvicorn; 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.2.49; extra == 'gpu'
+Requires-Dist: huggingface-hub>=0.34; extra == 'gpu'
+Requires-Dist: peft>=0.19; extra == 'gpu'
+Requires-Dist: torch==2.10.0; extra == 'gpu'
+Requires-Dist: transformers<5.11,>=5.6; extra == 'gpu'
+Requires-Dist: trl<1.7,>=1.6; extra == 'gpu'
+Requires-Dist: vllm==0.19.1; extra == 'gpu'
+Provides-Extra: server
+Requires-Dist: datasets>=2.19; extra == 'server'
+Requires-Dist: fastapi; extra == 'server'
+Requires-Dist: freesolo>=0.2.49; extra == 'server'
+Requires-Dist: httpx>=0.27; extra == 'server'
+Requires-Dist: huggingface-hub>=0.34; extra == 'server'
+Requires-Dist: runpod-flash; extra == 'server'
+Requires-Dist: uvicorn; extra == 'server'
+Description-Content-Type: text/markdown
+
+# Flash
+
+Managed LoRA post-training service: SFT and GRPO on managed RunPod Flash GPUs.
+The allocator picks the cheapest validated RunPod GPU class that fits the run.
+
+## Scope
+
+- `flash train <cfg.toml>` / control-plane `POST /runs` — submit a training job;
+  one dedicated GPU per run, supervised server-side (stall watchdog, bounded
+  auto-retry resuming from the last streamed checkpoint, endpoint GC).
+- `flash deploy`, `flash chat` — serving for trained adapters.
+- **Freesolo SDK environments.** Every run names a Freesolo environment id.
+  Scaffold `environment.py` plus `datasets/train.jsonl`, upload `.` or another
+  folder with `flash env push --name <name> <folder>`, then reference the
+  returned id. The worker loads it through `freesolo.environments`. There are no
+  built-in task environments. Single-turn and bounded multi-turn environments are
+  supported.
+
+## Layout
+
+- `flash/catalog.py` — curated model catalog (Qwen3 dense supported tier;
+  Qwen3.5/3.6 experimental tier) + `model_policy = "allow"` VRAM-fit check + each
+  model's `thinking` capability (opt-in reasoning mode `thinking = true`)
+- `flash/schema.py`, `flash/spec.py` — TOML → `JobSpec`
+- `flash/runner.py` — server-side run supervisor (durable job handle,
+  retries, cost guard, endpoint GC)
+- `flash/providers/` — RunPod Flash provider code (pricing, gpus, durable
+  submit/poll, preflight) behind the `base.Provider` protocol, with an
+  `allocator.py` that picks the cheapest fitting class
+- `flash/engine/` — the on-GPU worker (TRL + colocated vLLM rollouts) and the
+  shared recipe; SFT targets and RL rewards route through the active environment
+  (task-specific grading lives with its example, not in the engine)
+- `flash/envs/` — environment machinery: registry and the adapter that loads
+  Freesolo SDK environments onto the worker's interface
+- `flash env setup` — scaffold a starter local Freesolo env, `datasets/train.jsonl`,
+  and ready-to-run configs to start from
+- `flash/serve/`, `flash/server/` — adapter serving and the FastAPI control
+  plane (run operator-side via the separate `flash-server` command)
+- `flash/mcp/` — stdio MCP bridge for coding agents
+- `Dockerfile` — the control-plane image (used by the repo docker-compose)
+- `tests/` — pytest suite (CPU-only; offline-by-default, no GPU/network)
+
+## Local commands
+
+```bash
+cd flash
+uv sync --extra server
+uv run pytest                           # CPU tests (offline-by-default, no GPU/network)
+uv run ruff check . && uv run ruff format .
+uv run flash --help
+uv run flash-server                      # control plane (operator-side, run once)
+```
+
+The control plane owns provider credentials: `RUNPOD_API_KEY` is always required,
+plus the shared `HF_TOKEN`.
+The artifact repo is platform-managed and per-run (each run gets its own
+`Freesolo-Co/flashrun-<run_id>`, written by the operator `HF_TOKEN`); it is not a user
+knob and not an operator-wide env var. Clients authenticate with their freesolo API key
+(`flash login`).
+
+## Release channels
+
+Two channels are published to PyPI from the *same source*, distinguished by one line in
+`flash/_channel.py` (`CHANNEL`):
+
+| Channel | PyPI package | CLI | Default plane | Published from |
+| --- | --- | --- | --- | --- |
+| prod | `freesolo-flash` | `flash` | `flash.freesolo.co` | push to `main` that bumps `[project].version` (`.github/workflows/publish.yml`) |
+| dev | `freesolo-flash-dev` | `flash-dev` | `flash-dev.freesolo.co` | push to `dev` whose `[tool.flash-dev].version` isn't on PyPI yet (`.github/workflows/publish-dev.yml`) |
+
+The two install side by side (distinct package + CLI names). The dev build is produced by
+`scripts/build_dev_dist.py`, which renames the package/CLI and flips `CHANNEL` to `dev` before
+`uv build`. To cut a dev release, bump `[tool.flash-dev].version` and merge to `dev`. Either CLI
+still honours an explicit `FLASH_API_URL` / `flash login --api-url`; the channel only sets the
+default.
+
+## Serving From an API
+
+`flash chat` is a CLI wrapper around the Flash control-plane chat endpoint. To call a
+deployed adapter from your own app, deploy the finished run once and then POST chat
+requests with your freesolo API key:
+
+```bash
+export FLASH_API_URL=https://flash.freesolo.co
+export FREESOLO_API_KEY=fslo_...
+export RUN_ID=flash-1782194170-ce1cfcff
+
+curl -X POST "$FLASH_API_URL/v1/runs/$RUN_ID/deploy" \
+  -H "Authorization: Bearer $FREESOLO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"dry_run": false}'
+
+curl -X POST "$FLASH_API_URL/v1/runs/$RUN_ID/chat" \
+  -H "Authorization: Bearer $FREESOLO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "Write a two-sentence summary of the run."}
+    ],
+    "temperature": 0.0,
+    "max_tokens": 256
+  }'
+```
+
+The response uses the OpenAI chat-completions shape:
+
+```json
+{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "..."
+      }
+    }
+  ]
+}
+```
+
+Use `choices[0].message.content` for the generated text. The run id is the adapter id
+for serving. If the run is not deployed yet, `/v1/runs/<run_id>/chat` returns `409`
+with a hint to deploy first.
+
+Operators can also call the Modal serving app directly after the adapter is registered.
+The default serving app is `https://clado-ai--freesolo-lora-serving.modal.run`, and
+operators can point Flash at another serving app by setting `FREESOLO_SERVING_URL`.
+Use that same base URL when calling the app directly; pass the run id as `model`:
+
+```bash
+export FREESOLO_SERVING_URL=https://clado-ai--freesolo-lora-serving.modal.run
+
+curl -X POST "$FREESOLO_SERVING_URL/v1/chat/completions" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "flash-1782194170-ce1cfcff",
+    "messages": [{"role": "user", "content": "Hello"}],
+    "temperature": 0.0,
+    "max_tokens": 256
+  }'
+```
+
+Prefer the Flash control-plane endpoint for user apps because it enforces run ownership
+and forwards per-run serving options such as thinking-mode parity.