freesolo-flash-dev 1.1.95__tar.gz → 1.2.7__tar.gz

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/Dockerfile.worker

@@ -57,7 +57,8 @@ RUN pip install --no-cache-dir \
     "huggingface_hub>=1.2.0" \
     "accelerate>=1.4" \
     "wandb>=0.17" \
-    "flash-linear-attention @ git+https://github.com/fla-org/flash-linear-attention.git@f0e213dbd8b5fb90c3c7eca869ac1706d5377139" \
+    "flash-linear-attention @ git+https://github.com/fla-org/flash-linear-attention.git@9c8e42e762fce087c27b673af4922795d9edb85e" \
+    "flash-qla==0.1.2" \
     "tilelang==0.1.11" \
     "apache-tvm-ffi==0.1.11" \
     "hf_transfer" \
@@ -331,7 +332,8 @@ RUN printf '%s\n' "numpy==2.2.6" "xgrammar==0.1.25" "vllm==0.19.1" "transformers
         "bitsandbytes>=0.49" qwen-vl-utils \
         "wandb>=0.17" \
         cachetools uvicorn fastapi torchvision tqdm pyarrow \
-        "flash-linear-attention @ git+https://github.com/fla-org/flash-linear-attention.git@f0e213dbd8b5fb90c3c7eca869ac1706d5377139" \
+        "flash-linear-attention @ git+https://github.com/fla-org/flash-linear-attention.git@9c8e42e762fce087c27b673af4922795d9edb85e" \
+        "flash-qla==0.1.2" \
         "tilelang==0.1.11" \
         "apache-tvm-ffi==0.1.11" \
     && rm -f /tmp/verl-overrides.txt \

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: freesolo-flash-dev
-Version: 1.1.95
+Version: 1.2.7
 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
@@ -108,7 +108,7 @@ path is self-hostable end to end — see **[SELF_HOSTING.md](SELF_HOSTING.md)**.
 
 ## Using the hosted service
 
-`flash login` is not interactive — pass the key explicitly or export `FREESOLO_API_KEY` first:
+`flash login` is not interactive. Export `FREESOLO_API_KEY` first so the key does not appear in process listings:
 
 ```bash
 pip install freesolo-flash
@@ -161,6 +161,7 @@ then pass `RUN_ID/step-N` as the adapter id. To copy a finished adapter into you
 HuggingFace repo:
 
 ```bash
+export HF_TOKEN=hf_...
 flash models export --adapter-id RUN_ID --repository your-org/your-repo
 ```
 

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/README.md

@@ -44,7 +44,7 @@ path is self-hostable end to end — see **[SELF_HOSTING.md](SELF_HOSTING.md)**.
 
 ## Using the hosted service
 
-`flash login` is not interactive — pass the key explicitly or export `FREESOLO_API_KEY` first:
+`flash login` is not interactive. Export `FREESOLO_API_KEY` first so the key does not appear in process listings:
 
 ```bash
 pip install freesolo-flash
@@ -97,6 +97,7 @@ then pass `RUN_ID/step-N` as the adapter id. To copy a finished adapter into you
 HuggingFace repo:
 
 ```bash
+export HF_TOKEN=hf_...
 flash models export --adapter-id RUN_ID --repository your-org/your-repo
 ```
 

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/SELF_HOSTING.md

@@ -36,6 +36,28 @@ export RUNPOD_API_KEY=...              # or LAMBDA_API_KEY, or VAST_API_KEY
 flash-server --host 0.0.0.0 --port 8080
 ```
 
+`flash env test` runs a scaffolded environment **locally**, so it needs the `freesolo` SDK in the
+interpreter that loads your `environment.py`. The `[server]` extra above already includes it. The
+bare `pip install freesolo-flash` does not - it is client-only and pulls nothing - so on a machine
+where you author environments without the server extra, validation fails until you add it:
+
+```bash
+pip install freesolo                                     # same interpreter as the CLI
+uv tool install freesolo-flash --with freesolo --force   # existing uv tool: rewrite it with the SDK
+pipx inject freesolo-flash freesolo                      # existing pipx tool
+```
+
+The lower two matter if you installed the CLI with `uv tool` or `pipx`: the `flash` executable then
+lives in its own venv, and a plain `pip install freesolo` lands in your shell's interpreter instead
+
+- `python -c "import freesolo"` works while `flash env test` still fails. Use the line for the
+  manager you installed with; `--force` is what makes `uv tool install` update an existing tool
+  rather than no-op, and pipx has no equivalent of `--with`, so the SDK goes in via `inject`.
+
+(`flash env eval` is not local in this sense. It evaluates a run against a **published** hub
+environment and refuses a generic `github:` ref outright, which is the only kind a standalone plane
+accepts - so installing the SDK does not make it usable self-hosted.)
+
 The `server` extra pulls in `runpod-flash`, which declares its own `flash` console script.
 Whichever distribution installs last wins, so on a plane host the bare `flash` command may launch
 RunPod's CLI instead of this one - it exits 0 and does nothing, which is easy to miss. Use
@@ -51,10 +73,11 @@ the plane itself never terminates TLS. On the same machine, skip the proxy and u
 Then point a client at it:
 
 ```bash
+export FREESOLO_API_KEY="$FREESOLO_INTERNAL_KEY"
 # remote: the https address of your TLS proxy, not the plane's own :8080
-flash login --api-url https://your-plane.example --api-key "$FREESOLO_INTERNAL_KEY"
+flash login --api-url https://your-plane.example
 # same machine: loopback plaintext is fine
-# flash login --api-url http://127.0.0.1:8080 --api-key "$FREESOLO_INTERNAL_KEY"
+# flash login --api-url http://127.0.0.1:8080
 flash train run.toml
 ```
 
@@ -400,8 +423,8 @@ small run and watch it allocate.
 is not set, so the plane is trying to reach a Freesolo backend. Set it to `1`.
 
 **`401` on every request.** In standalone mode only `FREESOLO_INTERNAL_KEY` is accepted.
-Confirm the client is sending that exact value (`flash login --api-key ...`), with no
-trailing newline.
+Confirm `FREESOLO_API_KEY` contains that exact value, with no trailing newline, then run
+`flash login` again.
 
 **Startup says no GPU provider is configured** but you set a key. The value must be
 non-empty and non-whitespace. For RunPod specifically, a value of `","` parses to zero

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/flash/cli/__init__.py

@@ -61,6 +61,10 @@ from flash.cli.ui import render
 from flash.client.config import shadowed_login_warning
 from flash.core.catalog import ALGORITHMS
 
+# argv flags whose VALUE is a credential, so it must never be echoed back to the user. both the
+# freesolo key (`flash login`) and the HuggingFace token (`flash models export`) use this name.
+_CREDENTIAL_FLAGS = frozenset({"--api-key"})
+
 # Themed `flash --help` catalog. Groups are ordered along the training workflow; each row's
 # summary is the short one-liner the themed grid shows (the verbose per-command text stays on
 # every subparser's own `help=` / `<cmd> --help`). test_cli_help.py asserts these rows stay in
@@ -296,8 +300,11 @@ def _add_auth_commands(sub: argparse._SubParsersAction) -> None:
     )
     login.add_argument(
         "--api-key",
-        help="your freesolo API key (default: FREESOLO_API_KEY); create it at "
-        "https://freesolo.co/sign-in",
+        help=(
+            "your freesolo API key (default: FREESOLO_API_KEY); prefer the environment variable "
+            "because argument values are visible in process listings; create a key at "
+            "https://freesolo.co/sign-in"
+        ),
     )
     login.add_argument(
         "--freesolo-url",
@@ -687,6 +694,11 @@ def _add_runs_commands(sub: argparse._SubParsersAction) -> None:
         action="store_true",
         help="poll status until the run ends without replaying logs",
     )
+    runs_status.add_argument(
+        "--json",
+        action="store_true",
+        help="print machine-readable run status",
+    )
     runs_status.set_defaults(func=cmd_status)
 
     runs_log = runs_sub.add_parser(
@@ -757,8 +769,10 @@ def _add_deployment_commands(models_sub: argparse._SubParsersAction) -> None:
     )
     export.add_argument(
         "--api-key",
-        help="HuggingFace token with write access to --repository "
-        "(default: HF_TOKEN from your shell or a local .env / .env.local)",
+        help=(
+            "HuggingFace token with write access to --repository; prefer HF_TOKEN or a local "
+            ".env / .env.local because argument values are visible in process listings"
+        ),
     )
     export.add_argument(
         "--public",
@@ -839,6 +853,52 @@ def _warn_if_login_shadowed(args) -> None:
     print(render.warn(message) if render.styled() else f"warning: {message}", file=sys.stderr)
 
 
+def _is_credential_flag(arg: str) -> bool:
+    """Whether `arg` is a credential flag, including the abbreviations argparse accepts.
+
+    argparse allows any unambiguous prefix of a long option, so `--api-k` and `--api-ke` both reach
+    `api_key`. Matching the full spelling exactly would leave those spellings unredacted and print
+    the key -- the redaction would look correct while missing every abbreviated invocation.
+
+    Ambiguity is deliberately NOT consulted. Whether `--api` is ambiguous depends on the SUBPARSER:
+    `flash login` also defines `--api-url` so argparse refuses it there, but `flash models export`
+    defines no such option, so `--ap`, `--api` and `--api-` are all unambiguous there and bind the
+    HuggingFace token. Judging ambiguity against a fixed rival list gets that case exactly backwards
+    and leaves the token printable. Erring the other way is free: if the parser does reject the
+    spelling, nothing was bound, and redacting an argument in an already-failing command loses
+    nothing.
+    """
+    if not arg.startswith("--") or len(arg) <= 2:
+        return False
+    return any(flag.startswith(arg) for flag in _CREDENTIAL_FLAGS)
+
+
+def _redacted_args(raw_args: list[str]) -> list[str]:
+    """`raw_args` with any credential value replaced, for echoing a command back to the user.
+
+    The unexpected-error handler suggests re-running the exact command with --debug, which would
+    otherwise reproduce a `--api-key <key>` the user typed -- printing the key into a terminal, a
+    CI log or a pasted bug report. That is the same exposure `--api-key` already carries in process
+    listings, and the fix costs nothing: the value is never what makes the traceback useful.
+    """
+    redacted: list[str] = []
+    drop_value = False
+    for arg in raw_args:
+        if drop_value:
+            redacted.append("<redacted>")
+            drop_value = False
+            continue
+        if _is_credential_flag(arg):
+            redacted.append(arg)
+            drop_value = True
+            continue
+        flag, sep, _ = arg.partition("=")
+        # `--api-key=secret` is one argv entry, so the split form has to be handled separately or
+        # the value rides along inside it.
+        redacted.append(f"{flag}=<redacted>" if sep and _is_credential_flag(flag) else arg)
+    return redacted
+
+
 def main(argv: list[str] | None = None) -> int:
     raw_args = list(argv) if argv is not None else sys.argv[1:]
     parser = _build_parser()
@@ -872,7 +932,7 @@ def main(argv: list[str] | None = None) -> int:
         # point at the exact command to re-run, copy-pasteable. --debug is a root-level flag, so it
         # must come BEFORE the subcommand (argparse rejects `flash runs --debug`); place it right
         # after the program name. raw_args never contains --debug here — that path re-raises above.
-        cmd = " ".join([CLI_NAME, "--debug", *(shlex.quote(a) for a in raw_args)])
+        cmd = " ".join([CLI_NAME, "--debug", *(shlex.quote(a) for a in _redacted_args(raw_args))])
         print(render.error(str(exc) or exc.__class__.__name__), file=sys.stderr)
         print(render.arrow(f"run `{cmd}` for the full traceback"), file=sys.stderr)
         return 1

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/flash/cli/commands/__init__.py

@@ -178,6 +178,11 @@ def _plaintext_login_warnings(api_url: str | None, freesolo_url: str | None) ->
 def cmd_login(args) -> int:
     api_url = args.api_url or load_credentials()[0]
     identity: dict | None = None
+    if args.api_key:
+        print(
+            "warning: --api-key is visible in process listings; prefer FREESOLO_API_KEY",
+            file=sys.stderr,
+        )
     # before any request: the warning is worthless once the key has already gone over the wire.
     # both destinations are checked here rather than at the branch below, because which one receives
     # the key is decided after this point and the caller needs the warning while it can still abort.
@@ -637,9 +642,21 @@ def _poll_logs(client: ApiClient, run_id: str, interval: float) -> tuple[str, bo
         spinner.clear()
 
 
-def _render_status(status: dict) -> str:
-    """One rendering of a run status: themed panel on a TTY, indented JSON on the machine path."""
-    return render.run_status(status) if render.styled() else json.dumps(status, indent=2)
+def _render_status(status: dict, *, force_json: bool = False, one_line: bool = False) -> str:
+    """One rendering of a run status: themed panel on a TTY, indented JSON on the machine path.
+
+    ``force_json`` is `--json`: the machine rendering even on a TTY, so a script's output does not
+    depend on whether it happens to have one. ``one_line`` keeps each object on a single line for
+    the `--follow` stream, which emits many of them: indented objects would run together into
+    something no line-by-line JSON reader can parse.
+    """
+    if force_json and one_line:
+        return json.dumps(status, separators=(",", ":"))
+    return (
+        render.run_status(status)
+        if render.styled() and not force_json
+        else json.dumps(status, indent=2)
+    )
 
 
 def _print_detached_note(run_id: str) -> None:
@@ -673,13 +690,15 @@ def _follow_run(client: ApiClient, run_id: str) -> int:
     return 0 if state in _OK_STATES else 1
 
 
-def _follow_status(client: ApiClient, run_id: str, interval: float = 2.0) -> int:
+def _follow_status(
+    client: ApiClient, run_id: str, interval: float = 2.0, *, force_json: bool = False
+) -> int:
     """Poll run status until terminal, without replaying worker logs."""
     last_rendered: str | None = None
     try:
         while True:
             status = client.get_run(run_id)
-            rendered = _render_status(status)
+            rendered = _render_status(status, force_json=force_json, one_line=force_json)
             if rendered != last_rendered:
                 print(rendered)
                 last_rendered = rendered
@@ -725,9 +744,10 @@ def cmd_log(args) -> int:
 
 def cmd_status(args) -> int:
     client = client_from_config()
+    force_json = bool(getattr(args, "json", False))
     if getattr(args, "follow", False):
-        return _follow_status(client, args.run_id)
-    print(_render_status(client.get_run(args.run_id)))
+        return _follow_status(client, args.run_id, force_json=force_json)
+    print(_render_status(client.get_run(args.run_id), force_json=force_json))
     return 0
 
 
@@ -844,7 +864,7 @@ def cmd_deployments(args) -> int:
         return 0
     print(
         f"{'RUN ID':<30}  {'STEP':<6}  {'REVISION':<40}  {'STATE':<14}  "
-        f"{'VERIFIED AT':<20}  {'OPENAI MODEL':<30}  DETAIL"
+        f"{'VERIFIED AT':<20}  {'OPENAI MODEL':<30}  {'OPENAI BASE URL':<48}  DETAIL"
     )
     for row in rows:
         deployment = row.get("deployment") or {}
@@ -858,10 +878,11 @@ def cmd_deployments(args) -> int:
         revision = str(deployment.get("adapter_revision") or "-")
         state = str(deployment.get("state") or "-")
         openai_model = str(deployment.get("openai_model") or run_id)
+        openai_base_url = str(deployment.get("openai_base_url") or "-")
         detail = str(deployment.get("error") or deployment.get("detail") or "")[:160]
         print(
             f"{run_id:<30}  {step_text:<6}  {revision:<40}  {state:<14}  "
-            f"{verified_text:<20}  {openai_model:<30}  {detail}"
+            f"{verified_text:<20}  {openai_model:<30}  {openai_base_url:<48}  {detail}"
         )
     return 0
 

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/flash/cli/commands/deploy.py

@@ -302,6 +302,264 @@ def cmd_deploy(args) -> int:
     return 1 if dep.get("state") == "failed" or waited_but_unservable else 0
 
 
+def _hub_repo_missing_errors() -> tuple[type[BaseException], ...]:
+    """The hub errors that mean "the destination does not exist yet", not "you may not write".
+
+    Imported lazily and tolerantly for the same reason as flash/serve/export.py's `_hub_error_types`:
+    the CLI must stay importable without huggingface_hub. An empty tuple never matches, so a hub too
+    old to export these names fails closed on the strict branch rather than waving an export through.
+    """
+    for module in ("huggingface_hub.errors", "huggingface_hub.utils"):
+        try:
+            return (
+                __import__(module, fromlist=["RepositoryNotFoundError"]).RepositoryNotFoundError,
+            )
+        except (ImportError, AttributeError):
+            continue
+    return ()
+
+
+def _hf_status_code(exc: BaseException) -> int | None:
+    """The HTTP status behind a hub error, or None when the request never got an answer.
+
+    None is the whole point: it separates "the Hub said no" from "the Hub was unreachable", which
+    the preflight must treat differently.
+    """
+    code = getattr(getattr(exc, "response", None), "status_code", None)
+    try:
+        return int(code)
+    except (TypeError, ValueError):
+        return None
+
+
+def _hub_repo_gated_errors() -> tuple[type[BaseException], ...]:
+    """Gated-repo errors, which the hub models as a SUBCLASS of "repository not found".
+
+    So they match the missing-repo tuple and have to be subtracted from it. A gated destination
+    exists; it is simply not writable by this token, which is the opposite of creatable.
+    """
+    for module in ("huggingface_hub.errors", "huggingface_hub.utils"):
+        try:
+            return (__import__(module, fromlist=["GatedRepoError"]).GatedRepoError,)
+        except (ImportError, AttributeError):
+            continue
+    return ()
+
+
+def _hf_repo_confirmed_to_exist(api: object, repository: str, token: str) -> bool:
+    """Whether the Hub affirmatively said the destination is already there.
+
+    True only on an affirmative answer. A missing `repo_exists`, an error, or any other non-answer
+    is False, meaning "not confirmed", which leaves the creation rules in charge. That asymmetry is
+    deliberate: bypassing those rules is what lets an export reach a namespace nobody verified, so
+    it must be earned by a real answer rather than granted by the absence of one.
+    """
+    repo_exists = getattr(api, "repo_exists", None)
+    if not callable(repo_exists):
+        return False
+    try:
+        return bool(repo_exists(repository, repo_type="model", token=token))
+    except Exception:
+        return False
+
+
+# sub-500 statuses that describe the request's transport rather than this token's access: request
+# timeout, too-early replay, and rate limiting. 5xx is handled by the range check alongside these.
+_HUB_TRANSIENT_STATUSES = frozenset({408, 425, 429})
+
+
+def _hf_status_is_a_verdict(status: int | None) -> bool:
+    """Whether an HTTP status is the Hub answering the permission question about this token.
+
+    401/403/404 are answers: rejected, forbidden, or no such repo for this token. A missing status
+    (no response at all), 408, 425, 429, and 5xx are not -- they say the Hub was busy, slow or
+    broken, which is a fact about the Hub rather than about the caller's access.
+
+    408 and 425 carry a response, so they reach here rather than the statusless path, but a request
+    timeout and a too-early retry are transport outcomes: nothing about them says this token may not
+    write. Blocking on one would blame the user's permissions for the Hub being slow.
+    """
+    if status is None:
+        return False
+    return status < 500 and status not in _HUB_TRANSIENT_STATUSES
+
+
+def _without_token(text: str, token: str) -> str:
+    """`text` with the token removed, for the warnings that quote a hub exception.
+
+    A local credential rejection quotes what it was handed: httpx raises "Illegal header value
+    b'Bearer <token>'" for a token containing a newline, so interpolating the exception prints the
+    credential to stderr and into any log or pasted bug report. The exception is still worth showing
+    -- it is the only clue to what went wrong -- so redact rather than drop it.
+
+    The escaped renderings have to go too. httpx builds that message from the header BYTES, so a
+    token holding a real newline appears as the two characters `\\` and `n`, which a literal replace
+    of the token never matches -- the redaction silently does nothing in exactly the case it was
+    written for. Each form is removed longest-first so a shorter one cannot bite a piece out of a
+    longer one and leave the rest of the credential in place.
+    """
+    if not token:
+        return text
+    # repr() of the str and of the utf-8 bytes cover the escapings httpx and friends actually emit;
+    # the [1:-1] strips the quotes repr adds so the inner escaped text is what gets matched.
+    forms = {token, repr(token)[1:-1], repr(token.encode())[2:-1]}
+    for form in sorted(forms, key=len, reverse=True):
+        if form:
+            text = text.replace(form, "<redacted>")
+    return text
+
+
+def _hf_hub_version() -> str:
+    """The installed hub version for messages, without importing the package at module scope.
+
+    Falls back to a phrase, not a version-shaped string: this is only reached when the version could
+    not be read, and printing something that looks like a number would name a version nobody has.
+    """
+    try:
+        from huggingface_hub import __version__
+
+        return str(__version__)
+    except Exception:
+        return "(unknown version)"
+
+
+def _hf_identity_and_write_access(repository: str, token: str) -> str | None:
+    """return the token account after verifying the destination namespace when hub is installed."""
+    try:
+        from huggingface_hub import HfApi
+    except ModuleNotFoundError as exc:
+        if exc.name != "huggingface_hub":
+            raise
+        return None
+
+    import inspect
+
+    api = HfApi()
+    try:
+        identity = api.whoami(token=token)
+    except Exception as exc:
+        # a rejected token is the Hub answering, so refuse. a Hub that was unreachable, rate limited
+        # or broken is not an answer: the copy runs on the control plane, not here, so a CLI host
+        # without Hub egress would otherwise be unable to export at all -- while the same command
+        # skips this check entirely when the package is simply absent. degrade to that behaviour
+        # rather than invent a new hard blocker.
+        if not _hf_status_is_a_verdict(_hf_status_code(exc)):
+            print(
+                "warning: could not reach HuggingFace to verify the export namespace "
+                f"({_without_token(str(exc), token)}); proceeding without the check",
+                file=sys.stderr,
+            )
+            return None
+        raise ClientError(
+            "HuggingFace rejected the token before export. Check HF_TOKEN or --api-key and retry."
+        ) from exc
+    account = str(identity.get("name") or identity.get("username") or "").strip()
+    if not account:
+        raise ClientError(
+            "HuggingFace authenticated the token but returned no account name, so Flash could not "
+            "verify the export namespace. Update huggingface-hub or verify the token manually."
+        )
+    print(f"HuggingFace token resolves to account {account}", file=sys.stderr)
+
+    owner = repository.partition("/")[0].strip()
+
+    # the exact repo first: it is the only authoritative answer, and it is the one the export
+    # actually needs. asking the org role first would refuse a `contributor` who can write this
+    # very repo, because a role is a coarser fact than the permission being checked.
+    auth_check = getattr(api, "auth_check", None)
+    exact_probe = callable(auth_check) and "write" in inspect.signature(auth_check).parameters
+    if not exact_probe and _hf_repo_confirmed_to_exist(api, repository, token):
+        # `auth_check(..., write=True)` only exists from huggingface-hub 1.5, and this package still
+        # supports >=1.2, so on 1.2-1.4 there is no exact write probe. the rules below are CREATION
+        # rules and a destination that already exists is not being created, so applying them here
+        # would reject the org `contributor` this ordering was fixed to admit. degrade to a warning,
+        # exactly as this function already does when the Hub is unreachable or the package is absent.
+        # only a CONFIRMED existing repo takes this path. an unanswered lookup keeps the creation
+        # rules, which is what stops an unverified export into someone else's namespace.
+        print(
+            f"warning: huggingface-hub {_hf_hub_version()} cannot check write access to an "
+            f"existing repo; proceeding without verifying {repository}",
+            file=sys.stderr,
+        )
+        return account
+    if exact_probe:
+        try:
+            auth_check(repository, repo_type="model", token=token, write=True)
+            return account
+        except Exception as exc:
+            # a destination that is not there yet cannot be checked directly, so fall through to the
+            # creation rules below. GatedRepoError SUBCLASSES RepositoryNotFoundError, so it must be
+            # excluded first: a gated repo exists and this token may not write it, and reading it as
+            # "absent" would hand it to the weaker create-permission paths.
+            missing = _hub_repo_missing_errors()
+            absent = bool(missing) and isinstance(exc, missing)
+            if absent and isinstance(exc, _hub_repo_gated_errors()):
+                absent = False
+            if not absent and not _hf_status_is_a_verdict(_hf_status_code(exc)):
+                # no verdict about this token: a timeout or DNS failure (no status at all), a 429,
+                # or a 5xx. reporting any of those as "cannot write" blames the user's permissions
+                # for a transport fault, and the upload runs on the control plane anyway. warn and
+                # proceed, exactly as the whoami path above already does for the same class of
+                # failure. 401/403/404 DO answer the question and still fall through to the error.
+                print(
+                    f"warning: could not verify write access to {repository} "
+                    f"({_without_token(str(exc), token)}); proceeding without the check",
+                    file=sys.stderr,
+                )
+                return account
+            if not absent:
+                raise ClientError(
+                    f"HuggingFace token resolves to account {account}, but it cannot write to "
+                    f"{repository}. Grant this token write access to that model repo or set HF_TOKEN "
+                    "to a token that can write there."
+                ) from exc
+
+    # only reached for a destination that does not exist yet, so the question is now whether this
+    # token may CREATE it in that namespace. that is what the org role legitimately answers.
+    org_role = ""
+    for org in identity.get("orgs") or ():
+        if not isinstance(org, dict) or str(org.get("name") or "").casefold() != owner.casefold():
+            continue
+        org_role = str(org.get("role") or org.get("roleInOrg") or "").lower()
+        break
+    if owner.casefold() != account.casefold() and org_role not in {"write", "admin"}:
+        raise ClientError(
+            f"HuggingFace token resolves to account {account}, which cannot create "
+            f"{repository} in the namespace {owner}. Use --repository {account}/<repo>, choose an "
+            "org where this account has write access, or set HF_TOKEN to the intended account."
+        )
+
+    access_token = (identity.get("auth") or {}).get("accessToken") or {}
+    token_role = str(access_token.get("role") or "").lower()
+    if token_role == "write":
+        return account
+    if token_role != "fineGrained".lower():
+        raise ClientError(
+            f"HuggingFace token resolves to account {account}, but Flash could not verify write "
+            f"scope for the new destination {repository}. Use a write token for that namespace, "
+            "or create the repo first so Flash can check its exact write permission."
+        )
+
+    permissions = set(access_token.get("fineGrained", {}).get("global") or ())
+    for scope in access_token.get("fineGrained", {}).get("scoped") or ():
+        if not isinstance(scope, dict):
+            continue
+        entity = scope.get("entity") or {}
+        entity_name = str(entity.get("name") or entity.get("id") or "")
+        # only a scope naming the destination counts. crediting every user-typed scope would accept
+        # a token whose write grant covers some unrelated repo of its own, which is the silent
+        # wrong-namespace export this preflight exists to stop.
+        if entity_name.casefold() in {owner.casefold(), repository.casefold()}:
+            permissions.update(scope.get("permissions") or ())
+    if not ({"repo.write", "repo.content.write"} & permissions):
+        raise ClientError(
+            f"HuggingFace token resolves to account {account}, but its fine-grained scopes do not "
+            f"verify write access for {repository}. Add repository-content write access for that "
+            "namespace or use a write token."
+        )
+    return account
+
+
 def cmd_export(args) -> int:
     from flash.client.runtime_secrets import resolve_hf_token
 
@@ -311,9 +569,16 @@ def cmd_export(args) -> int:
             "no HuggingFace token: pass `--api-key <hf_...>`, or set HF_TOKEN "
             "(export it in your shell or put it in a local .env / .env.local)"
         )
+    if args.api_key:
+        print(
+            "warning: --api-key is visible in process listings; prefer HF_TOKEN or a local "
+            ".env / .env.local",
+            file=sys.stderr,
+        )
+    _hf_identity_and_write_access(args.repository, hf_token)
     client = _commands().client_from_config()
     progress = (
-        f"exporting adapter {args.adapter_id} to {args.repository} — "
+        f"exporting adapter {args.adapter_id} to {args.repository}; "
         "downloading then re-uploading; this can take a minute..."
     )
     print(render.note(progress) if render.styled() else progress, file=sys.stderr)

{freesolo_flash_dev-1.1.95 → freesolo_flash_dev-1.2.7}/flash/cli/scaffold/TRAINING.md

@@ -25,7 +25,8 @@ command.
 
 ```bash
 pip install freesolo-flash          # installs the `flash` CLI (import name is also `flash`)
-flash login --api-key fslo_...       # or: export FREESOLO_API_KEY=fslo_...  (create a key at https://freesolo.co)
+export FREESOLO_API_KEY=fslo_...     # create a key at https://freesolo.co
+flash login                          # validates and stores the key without exposing it in argv
 flash whoami                         # confirm the identity behind your key
 flash projects create "my project"     # prints the canonical project UUID
 flash models list                     # supported base model ids
@@ -544,12 +545,11 @@ current hub — both swallow paths are present in every version Flash supports.)
 
 Two more details that make the difference between a probe and a placebo:
 
-- **Pass the same token the export will use.** Flash resolves the export token as
-  `--api-key` > `HF_TOKEN` in the environment > a local `.env` / `.env.local`, and forwards
-  exactly that value. `huggingface_hub` does none of that — with no `token=` it falls back to
-  your ambient cached login, so the probe can pass on one credential while the export fails
-  on a different one. If you are exporting with `--api-key`, or with a token that lives only
-  in `.env`, pass that literal value here.
+- **Pass the same token the export will use.** Prefer `HF_TOKEN` in the environment or a local
+  `.env` / `.env.local`; `--api-key` still wins when supplied, but exposes the token in process
+  listings. Flash forwards exactly the resolved value. `huggingface_hub` does none of that; with
+  no `token=` it falls back to your ambient cached login, so the probe can pass on one credential
+  while the export fails on a different one. Pass the resolved token explicitly to the probe.
 - **Ask for `private=True`.** The real export creates the repo private and only flips it
   public afterwards if you passed `--public`. A probe that omits this can leave a brand-new
   repo publicly visible until the export catches up, and it fails outright under an org
@@ -683,7 +683,7 @@ spending another GPU run:
 | Wrong identity spends the money                              | Push/train lands in an org you did not expect, or a run id you know is valid comes back "unknown"                                                                                        | `FREESOLO_API_KEY` in the environment silently overrides `flash login`. Run `flash whoami` first. Run visibility is scoped to the key that created the run, so archive result baselines to disk rather than relying on `flash runs list` to find them later.                                                                                                                                                                    |
 | `flash env test` passes but the run trains on the wrong data | Local validation is green; the remote run loads a different split                                                                                                                        | `flash env test` loads `environment.py` with **no** `[environment.params]`, so a params-driven split selection is not exercised. Assert the split inside your own test, or default to the split you actually train on.                                                                                                                                                                                                          |
 | Final checkpoint regresses                                   | Last step is worse than an earlier checkpoint                                                                                                                                            | Run `flash runs checkpoint <run-id>`, deploy a specific step with `flash models deploy <run-id>/step-N`, and compare with held-out probes before exporting or relying on the final adapter.                                                                                                                                                                                                                                     |
-| Export fails before upload                                   | CLI says no HuggingFace token                                                                                                                                                            | Pass `flash models export --api-key hf_...`, or set `HF_TOKEN` in your shell, `.env`, or `.env.local`. Exports are private unless you pass `--public`.                                                                                                                                                                                                                                                                          |
+| Export fails before upload                                   | CLI says no HuggingFace token                                                                                                                                                            | Set `HF_TOKEN` in your shell, `.env`, or `.env.local`, then run `flash models export`; avoid `--api-key` because argument values are visible in process listings. Exports are private unless you pass `--public`.                                                                                                                                                                                                               |
 | Exported adapter is a silent no-op locally                   | peft warns about missing adapter keys and local eval matches the bare base model                                                                                                         | The adapter's key namespace does not match the loaded model class. `model.layers.*` keys pair with `AutoModelForCausalLM`; `model.language_model.layers.*` keys pair with `Qwen3_5ForConditionalGeneration` / `Qwen3_5MoeForConditionalGeneration` (via `AutoModelForImageTextToText`). See "Loading an exported adapter locally".                                                                                              |
 | SFT loss improves but quality does not                       | Train loss falls while held-out behavior stalls or degrades                                                                                                                              | Keep a held-out split outside training. Deploy and score that split; if quality drops, reduce epochs or improve data instead of adding more passes.                                                                                                                                                                                                                                                                             |
 | Cost surprises                                               | A quick experiment uses more GPU time than intended                                                                                                                                      | Start with `--dry-run` and `--cost`, keep `epochs` and `max_examples` small for smoke tests, and scale only after reward/data wiring is proven. Setup time is reported for observability; customer cost is based on training-loop GPU time.                                                                                                                                                                                     |