v1.0.2 — the Hub is reachable from the command line, and is not a chain

The hf/ extension existed and was complete, but nothing outside a Python import could reach it. New `mindxtrain hf` group: whoami / pull / warm / publish / lineage / dataset / space, each exiting nonzero when the result says ok:false so the ascent loop can warm a base and check $?.

huggingface-hub moves out of the `chain` extra into its own `hf` extra — reaching the Hub no longer means installing web3 and the Algorand SDK. `chain` pulls `mindxtrain[hf]` so existing installs keep working.

push_space dropped its commit receipt; it reports it now. First tests for the module.

765 tests pass (was 750).

docs/CHANGELOG.md

@@ -6,6 +6,38 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.0.2] — 2026-09-15
+
+### Added
+
+- **mindXtrain can use Hugging Face from the command line.** The `mindxtrain/hf/` extension
+  existed and was complete — `account`, `pull_base`, `warm`, `publish_generation`,
+  `push_dataset`, `lineage`, `push_space` — but nothing outside a Python import could reach
+  it: there was no CLI verb, so on a node the Hub was effectively unavailable. New
+  `mindxtrain hf` group: `whoami · pull · warm · publish · lineage · dataset · space`.
+  Each prints the extension's own result dict and **exits nonzero when it reports
+  `ok: false`**, so the ascent loop can warm a base, check `$?`, and refuse to start a
+  three-hour run that would otherwise discover the missing base at the end of it.
+- **Tests for the Hub extension**, which had none: token precedence across the three
+  accepted environment variables, the missing-dependency path (genuinely missing here, not
+  mocked), the `RepoFolder` trap that makes a scan report an empty repo, the guards that
+  must not need a network, and the CLI wiring including the nonzero exit.
+
+### Changed
+
+- **`huggingface-hub` moved out of the `chain` extra into its own `hf` extra.** Reaching the
+  Hub used to mean installing `web3` and the Algorand SDK, because the Hub was filed under
+  "chain". It is not a chain. `chain` now pulls `mindxtrain[hf]` so existing installs keep
+  working, `all` includes it, and every "not installed" message names `--extra hf` — the
+  extra that actually installs it — instead of sending the reader to the blockchain one.
+- The `hf` module is ruff clean under the house config.
+
+### Fixed
+
+- **`push_space` captured the upload's commit receipt and discarded it**, while its two
+  sibling publishers both return it. A Space push now reports its commit like everything
+  else, so what was pushed is identifiable afterwards.
+
 ## [1.0.1] — 2026-09-15
 
 

docs/NAV.md

@@ -164,8 +164,9 @@ Target metrics + framework comparison.
 - [What's not measured (yet)](benchmarks.md#whats-not-measured-yet)
 
 ### [CHANGELOG](CHANGELOG.md)
-Version history (current: v1.0.1).
+Version history (current: v1.0.2).
 - [[Unreleased]](CHANGELOG.md#unreleased)
+- [[1.0.2] — 2026-09-15](CHANGELOG.md#102--2026-09-15)
 - [[1.0.1] — 2026-09-15](CHANGELOG.md#101--2026-09-15)
 - [[1.0.0] — 2026-06-11](CHANGELOG.md#100--2026-06-11)
 - [[0.1.0] — 2026-05-06](CHANGELOG.md#010--2026-05-06)

mindxtrain/__init__.py

@@ -16,4 +16,4 @@ Layout per mindXtrain2.md §Part 4 "Repository layout":
     budget/      psutil-derived ResourceBudget (carry-over from aGLM)
 """
 
-__version__ = "1.0.1"
+__version__ = "1.0.2"

mindxtrain/cli/main.py

@@ -25,10 +25,16 @@ mei_app = typer.Typer(
     help="mindX Efficiency Index — score, history, promotion checks.",
     no_args_is_help=True,
 )
+hf_app = typer.Typer(
+    name="hf",
+    help="Hugging Face — who the token is, warm a base, publish a generation, read the lineage.",
+    no_args_is_help=True,
+)
 app.add_typer(dataset_app)
 app.add_typer(github_app)
 app.add_typer(droplet_app)
 app.add_typer(mei_app)
+app.add_typer(hf_app)
 console = Console()
 
 
@@ -710,6 +716,120 @@ def research(
     console.print(f"[green]{result.summary()}[/green]")
 
 
+
+# ---- hugging face (the Hub as mindXtrain uses it) -----------------------------
+
+
+def _hf_report(result: dict, *, quiet: bool = False) -> None:
+    """Print a result dict and exit nonzero when it says `ok: false`.
+
+    Every `mindxtrain.hf` function returns `{"ok": bool, ...}` rather than raising, so the exit
+    code is what makes it scriptable: the ascent loop can warm a base, check `$?`, and refuse to
+    start a three-hour run that would only discover the missing base at the end.
+    """
+    import json as _json
+
+    if not quiet:
+        console.print_json(_json.dumps(result, default=str))
+    if not result.get("ok"):
+        raise typer.Exit(code=1)
+
+
+@hf_app.command("whoami")
+def hf_whoami(
+    token: str = typer.Option("", "--token", help="Defaults to HF_TOKEN in the environment."),
+) -> None:
+    """Who the token is — and, separately, the namespaces it can actually WRITE.
+
+    Org membership is not write scope; the two are reported apart because assuming they are the
+    same is how a publish fails after the training finished.
+    """
+    from mindxtrain.hf import account
+
+    _hf_report(account(token or None))
+
+
+@hf_app.command("pull")
+def hf_pull(
+    model_id: str = typer.Argument(..., help="Base model repo id, e.g. HuggingFaceTB/SmolLM2-135M."),
+    token: str = typer.Option("", "--token"),
+    allow: list[str] = typer.Option(None, "--allow", help="Glob to restrict the download."),
+) -> None:
+    """Fetch a base model into the local cache before training needs it."""
+    from mindxtrain.hf import pull_base
+
+    _hf_report(pull_base(model_id, token=token or None, allow_patterns=list(allow) if allow else None))
+
+
+@hf_app.command("warm")
+def hf_warm(
+    config: Path = typer.Argument(..., help="run.yaml — its model.name is what gets pulled."),
+    token: str = typer.Option("", "--token"),
+) -> None:
+    """Pull whatever a run config says it needs, so `train` starts cold-free."""
+    from mindxtrain.hf import warm
+
+    _hf_report(warm(config, token=token or None))
+
+
+@hf_app.command("publish")
+def hf_publish(
+    run_dir: Path = typer.Argument(..., help="A finished run directory."),
+    repo_id: str = typer.Argument(..., help="Target model repo, e.g. PYTHAI/mindXascension."),
+    token: str = typer.Option("", "--token"),
+    private: bool = typer.Option(False, "--private", help="Create the repo private."),
+    no_merged: bool = typer.Option(False, "--no-merged", help="Adapter only; skip merged weights."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Report what would upload; touch nothing."),
+) -> None:
+    """Publish a finished run as a model repo: weights, adapter, train.log, Modelfile, card."""
+    from mindxtrain.hf import publish_generation
+
+    _hf_report(publish_generation(run_dir, repo_id, token=token or None, private=private,
+                                  include_merged=not no_merged, dry_run=dry_run))
+
+
+@hf_app.command("lineage")
+def hf_lineage(
+    repo_id: str = typer.Argument(..., help="Repo to scan."),
+    repo_type: str = typer.Option("model", "--repo-type", help="model | dataset | space."),
+    local_runs: Path = typer.Option(None, "--local-runs", help="Run root, to list what is unpublished."),
+    token: str = typer.Option("", "--token"),
+) -> None:
+    """What is on the Hub for a project, reconciled against local runs."""
+    from mindxtrain.hf import lineage
+
+    _hf_report(lineage(repo_id, repo_type=repo_type, token=token or None, local_runs=local_runs))
+
+
+@hf_app.command("dataset")
+def hf_dataset(
+    path: Path = typer.Argument(..., help="A corpus folder or one JSONL."),
+    repo_id: str = typer.Argument(..., help="Target dataset repo."),
+    token: str = typer.Option("", "--token"),
+    private: bool = typer.Option(False, "--private"),
+    path_in_repo: str = typer.Option("", "--path-in-repo"),
+) -> None:
+    """Push a training corpus to a dataset repo."""
+    from mindxtrain.hf import push_dataset
+
+    _hf_report(push_dataset(path, repo_id, token=token or None, private=private,
+                            path_in_repo=path_in_repo))
+
+
+@hf_app.command("space")
+def hf_space(
+    folder: Path = typer.Argument(..., help="A Gradio folder (must contain app.py)."),
+    space_id: str = typer.Argument(..., help="Target Space id."),
+    token: str = typer.Option("", "--token"),
+    public: bool = typer.Option(False, "--public", help="Public Space. Never park a write token on one."),
+    hardware: str = typer.Option("zero-a10g", "--hardware", help="Empty string for the free CPU tier."),
+) -> None:
+    """Push a Gradio folder as a Space."""
+    from mindxtrain.hf import push_space
+
+    _hf_report(push_space(folder, space_id, token=token or None, private=not public,
+                          hardware=hardware or None))
+
 # ---- github / droplet (source-tree publishing + remote provision) -------
 
 

mindxtrain/hf/__init__.py

@@ -12,9 +12,9 @@ the rest of the Hub as mindXtrain needs it, and nothing more:
 - `datasets` — push/pull a training corpus with its manifest
 
 Every function returns a plain dict: `{"ok": bool, …}`. Nothing here raises at import time, and
-`huggingface_hub` is imported lazily so a CPU-only install without `--extra chain` still loads.
+`huggingface_hub` is imported lazily so a CPU-only install without `--extra hf` still loads.
 """
-from .extension import (  # noqa: F401
+from .extension import (
     account,
     lineage,
     publish_generation,

mindxtrain/hf/extension.py

@@ -20,12 +20,12 @@ import os
 import re
 import time
 from pathlib import Path
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 _HF_ENV = ("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "HUGGINGFACEHUB_API_TOKEN")
 
 
-def _token(explicit: Optional[str] = None) -> Optional[str]:
+def _token(explicit: str | None = None) -> str | None:
     if explicit:
         return explicit
     for k in _HF_ENV:
@@ -35,26 +35,26 @@ def _token(explicit: Optional[str] = None) -> Optional[str]:
     return None
 
 
-def _api(token: Optional[str] = None):
+def _api(token: str | None = None):
     """(HfApi, None) or (None, {"ok": False, …}) — never raises."""
     try:
         from huggingface_hub import HfApi
     except ImportError:
-        return None, {"ok": False, "reason": "huggingface_hub not installed — `uv sync --extra chain`"}
+        return None, {"ok": False, "reason": "huggingface_hub not installed — `uv sync --extra hf`"}
     tok = _token(token)
     if not tok:
         return None, {"ok": False, "reason": f"no token — set one of {', '.join(_HF_ENV)}"}
     return HfApi(token=tok), None
 
 
-def tree_paths(api, repo_id: str, **kw) -> List[str]:
+def tree_paths(api, repo_id: str, **kw) -> list[str]:
     """File paths of a repo tree (folders skipped). See the module docstring: the tree's entries
     carry `.path`, not `.rfilename`."""
     return [f.path for f in api.list_repo_tree(repo_id, **kw) if type(f).__name__ != "RepoFolder"]
 
 
 # ── who the token is ──────────────────────────────────────────────────────────
-def account(token: Optional[str] = None) -> Dict[str, Any]:
+def account(token: str | None = None) -> dict[str, Any]:
     """The identity behind the token, its role, the orgs it belongs to, and — separately — the
     namespaces it can actually write."""
     api, err = _api(token)
@@ -62,7 +62,7 @@ def account(token: Optional[str] = None) -> Dict[str, Any]:
         return err
     try:
         me = api.whoami()
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "reason": f"whoami failed: {type(e).__name__}: {str(e)[:200]}"}
     auth = (me.get("auth") or {}).get("accessToken") or {}
     perms = auth.get("fineGrained") or {}
@@ -82,29 +82,29 @@ def account(token: Optional[str] = None) -> Dict[str, Any]:
 
 
 # ── bases, fetched before the run rather than during it ───────────────────────
-def pull_base(model_id: str, *, token: Optional[str] = None, allow_patterns: Optional[List[str]] = None) -> Dict[str, Any]:
+def pull_base(model_id: str, *, token: str | None = None, allow_patterns: list[str] | None = None) -> dict[str, Any]:
     """Download a base model to the local cache. Do this BEFORE training: a run that discovers a
     missing base three hours in has wasted three hours."""
     try:
         from huggingface_hub import snapshot_download
     except ImportError:
-        return {"ok": False, "reason": "huggingface_hub not installed — `uv sync --extra chain`"}
+        return {"ok": False, "reason": "huggingface_hub not installed — `uv sync --extra hf`"}
     t0 = time.time()
     try:
         path = snapshot_download(model_id, token=_token(token), allow_patterns=allow_patterns)
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "model": model_id, "reason": f"{type(e).__name__}: {str(e)[:200]}"}
     p = Path(path)
     return {"ok": True, "model": model_id, "path": str(p), "seconds": round(time.time() - t0, 1),
             "bytes": sum(f.stat().st_size for f in p.rglob("*") if f.is_file())}
 
 
-def warm(config: Path | str, *, token: Optional[str] = None) -> Dict[str, Any]:
+def warm(config: Path | str, *, token: str | None = None) -> dict[str, Any]:
     """Pull whatever a run.yaml says it needs (the base model) so `train` starts cold-free."""
     try:
         import yaml
         cfg = yaml.safe_load(Path(config).read_text())
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "reason": f"unreadable config: {type(e).__name__}: {str(e)[:160]}"}
     base = ((cfg or {}).get("model") or {}).get("name")
     if not base:
@@ -113,11 +113,11 @@ def warm(config: Path | str, *, token: Optional[str] = None) -> Dict[str, Any]:
 
 
 # ── a finished run, published ─────────────────────────────────────────────────
-def _card(repo_id: str, meta: Dict[str, Any]) -> str:
+def _card(repo_id: str, meta: dict[str, Any]) -> str:
     """A model card written from the run's own numbers. No claim that is not in `meta`."""
     m = meta
     fm = {"license": m.get("license", "apache-2.0"), "library_name": "transformers",
-          "pipeline_tag": "text-generation", "tags": ["mindxtrain", "lora"] + list(m.get("tags") or [])}
+          "pipeline_tag": "text-generation", "tags": ["mindxtrain", "lora", *list(m.get("tags") or [])]}
     if m.get("base"):
         fm["base_model"] = m["base"]
     if m.get("dataset"):
@@ -137,9 +137,9 @@ def _card(repo_id: str, meta: Dict[str, Any]) -> str:
               "the training log ships beside the weights.\n")
 
 
-def publish_generation(run_dir: Path | str, repo_id: str, *, token: Optional[str] = None, private: bool = False,
-                       meta: Optional[Dict[str, Any]] = None, persona_system: Optional[str] = None,
-                       include_merged: bool = True, dry_run: bool = False) -> Dict[str, Any]:
+def publish_generation(run_dir: Path | str, repo_id: str, *, token: str | None = None, private: bool = False,
+                       meta: dict[str, Any] | None = None, persona_system: str | None = None,
+                       include_merged: bool = True, dry_run: bool = False) -> dict[str, Any]:
     """A finished run as a model repo: merged weights at the root (if present), the LoRA delta under
     `adapter/`, `train.log`, a `Modelfile` for Ollama, and a card built from `meta`.
 
@@ -149,14 +149,14 @@ def publish_generation(run_dir: Path | str, repo_id: str, *, token: Optional[str
         return {"ok": False, "reason": f"no run dir at {run}"}
     ck = run / "checkpoint"
     merged = run / "ollama_push" / "merged"
-    staged: Dict[str, Path] = {}
+    staged: dict[str, Path] = {}
     if include_merged and merged.is_dir():
         for f in merged.iterdir():
             if f.is_file():
                 staged[f.name] = f
     if ck.is_dir():
         for f in ck.iterdir():
-            if f.is_file() and f.name != "training_args.bin" or f.name == "training_args.bin":
+            if (f.is_file() and f.name != "training_args.bin") or f.name == "training_args.bin":
                 staged[f"adapter/{f.name}"] = f
     log = run / "train.log"
     if log.is_file():
@@ -167,21 +167,21 @@ def publish_generation(run_dir: Path | str, repo_id: str, *, token: Optional[str
     if not meta.get("base"):
         try:
             meta["base"] = json.loads((ck / "adapter_config.json").read_text()).get("base_model_name_or_path")
-        except Exception:  # noqa: BLE001
+        except Exception:
             pass
     card = _card(repo_id, meta)
     modelfile = ("# ollama create <name> -f Modelfile   (from this repo's directory)\nFROM .\n"
                  + (f'SYSTEM """{persona_system}"""\n' if persona_system else "")
                  + 'PARAMETER temperature 0.7\nPARAMETER repeat_penalty 1.3\nPARAMETER stop "<|im_end|>"\n')
-    plan = {"repo": repo_id, "private": private, "files": sorted(staged) + ["README.md", "Modelfile"],
+    plan = {"repo": repo_id, "private": private, "files": [*sorted(staged), "README.md", "Modelfile"],
             "bytes": sum(f.stat().st_size for f in staged.values())}
     if dry_run:
         return {"ok": True, "dry_run": True, "would_upload": plan, "card_preview": card[:400]}
     api, err = _api(token)
     if err:
         return err
-    import tempfile
     import shutil
+    import tempfile
     with tempfile.TemporaryDirectory() as tmp:
         stage = Path(tmp)
         for rel, src in staged.items():
@@ -194,15 +194,15 @@ def publish_generation(run_dir: Path | str, repo_id: str, *, token: Optional[str
             api.create_repo(repo_id, repo_type="model", private=private, exist_ok=True)
             ci = api.upload_folder(folder_path=str(stage), repo_id=repo_id, repo_type="model",
                                    commit_message=meta.get("commit_message") or "mindXtrain: a run, published with its evidence")
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:
             return {"ok": False, "repo": repo_id, "reason": f"{type(e).__name__}: {str(e)[:300]}"}
     return {"ok": True, "repo": repo_id, "url": f"https://huggingface.co/{repo_id}",
             "commit": str(getattr(ci, "oid", ci))[:12], "uploaded": plan}
 
 
 # ── the corpus ────────────────────────────────────────────────────────────────
-def push_dataset(path: Path | str, repo_id: str, *, token: Optional[str] = None, private: bool = False,
-                 path_in_repo: str = "", manifest: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+def push_dataset(path: Path | str, repo_id: str, *, token: str | None = None, private: bool = False,
+                 path_in_repo: str = "", manifest: dict[str, Any] | None = None) -> dict[str, Any]:
     """Push a training corpus (a folder or one JSONL) with an optional manifest beside it."""
     api, err = _api(token)
     if err:
@@ -222,7 +222,7 @@ def push_dataset(path: Path | str, repo_id: str, *, token: Optional[str] = None,
             api.upload_file(path_or_fileobj=json.dumps(manifest, indent=1).encode(),
                             path_in_repo=f"{path_in_repo}/MANIFEST.json".lstrip("/"),
                             repo_id=repo_id, repo_type="dataset", commit_message="mindXtrain: corpus manifest")
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "repo": repo_id, "reason": f"{type(e).__name__}: {str(e)[:300]}"}
     return {"ok": True, "repo": repo_id, "url": f"https://huggingface.co/datasets/{repo_id}",
             "commit": str(getattr(ci, "oid", ci))[:12]}
@@ -232,8 +232,8 @@ def push_dataset(path: Path | str, repo_id: str, *, token: Optional[str] = None,
 _GEN = re.compile(r"(?:^|/)gen(\d+)(?:/|$)")
 
 
-def lineage(repo_id: str, *, repo_type: str = "model", token: Optional[str] = None,
-            local_runs: Optional[Path | str] = None) -> Dict[str, Any]:
+def lineage(repo_id: str, *, repo_type: str = "model", token: str | None = None,
+            local_runs: Path | str | None = None) -> dict[str, Any]:
     """Generations present in a repo, and — when `local_runs` is given — which local runs are not
     published yet. Uses `tree_paths`, so folders never break the scan."""
     api, err = _api(token)
@@ -241,9 +241,9 @@ def lineage(repo_id: str, *, repo_type: str = "model", token: Optional[str] = No
         return err
     try:
         paths = tree_paths(api, repo_id, repo_type=repo_type, recursive=True)
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "repo": repo_id, "reason": f"{type(e).__name__}: {str(e)[:200]}"}
-    gens: Dict[int, List[str]] = {}
+    gens: dict[int, list[str]] = {}
     for p in paths:
         m = _GEN.search(p)
         if m:
@@ -262,9 +262,9 @@ def lineage(repo_id: str, *, repo_type: str = "model", token: Optional[str] = No
 
 
 # ── Spaces ────────────────────────────────────────────────────────────────────
-def push_space(folder: Path | str, space_id: str, *, token: Optional[str] = None, private: bool = True,
-               hardware: Optional[str] = "zero-a10g", variables: Optional[Dict[str, str]] = None,
-               secrets: Optional[Dict[str, str]] = None) -> Dict[str, Any]:
+def push_space(folder: Path | str, space_id: str, *, token: str | None = None, private: bool = True,
+               hardware: str | None = "zero-a10g", variables: dict[str, str] | None = None,
+               secrets: dict[str, str] | None = None) -> dict[str, Any]:
     """Push a Gradio folder as a Space. Existence is checked BEFORE creation (the Hub tests the
     ZeroGPU quota first and answers 402 on a repo that already exists), and a README
     `short_description` longer than 60 characters is refused by the Hub, so it is checked here."""
@@ -292,9 +292,10 @@ def push_space(folder: Path | str, space_id: str, *, token: Optional[str] = None
         for k, v in (secrets or {}).items():
             api.add_space_secret(space_id, k, v)
         rt = api.get_space_runtime(space_id)
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:
         return {"ok": False, "space": space_id, "reason": f"{type(e).__name__}: {str(e)[:300]}"}
     return {"ok": True, "space": space_id, "existed": exists, "stage": str(rt.stage),
+            "commit": str(getattr(ci, "oid", ci))[:12],
             "url": f"https://huggingface.co/spaces/{space_id}",
             "host": "https://" + space_id.replace("/", "-").replace("_", "-").lower() + ".hf.space",
             "note": "free personal accounts host 2 ZeroGPU Spaces; a free org hosts none (402)"}

mindxtrain/storage/hf_hub.py

@@ -1,6 +1,6 @@
 """Push checkpoint + model card to Hugging Face Hub.
 
-Lazy `import huggingface_hub` so users without `--extra chain` can still
+Lazy `import huggingface_hub` so users without `--extra hf` can still
 import this module. `HF_TOKEN` is read from env (or the token kwarg).
 """
 
@@ -24,7 +24,7 @@ def publish_to_hf(
     try:
         from huggingface_hub import HfApi
     except ImportError as exc:
-        msg = "huggingface_hub not installed; run `uv sync --extra chain`."
+        msg = "huggingface_hub not installed; run `uv sync --extra hf`."
         raise RuntimeError(msg) from exc
 
     api = HfApi(token=token or os.environ.get("HF_TOKEN"))
@@ -56,7 +56,7 @@ class HfHubProvider(StorageProvider):
         try:
             from huggingface_hub import snapshot_download
         except ImportError as exc:
-            msg = "huggingface_hub not installed; run `uv sync --extra chain`."
+            msg = "huggingface_hub not installed; run `uv sync --extra hf`."
             raise RuntimeError(msg) from exc
         # ref.uri is `https://huggingface.co/<repo_id>` — extract repo_id.
         repo_id = ref.uri.removeprefix("https://huggingface.co/")

mindxtrain/ui/app.py

@@ -36,7 +36,7 @@ import gradio as gr
 from .metrics import RunMetrics, parse_log  # noqa: F401  (parse_log re-exported for tests)
 from .theme import CSS, theme
 
-VERSION = "1.0.1"
+VERSION = "1.0.2"
 HOME = Path(os.environ.get("MINDXTRAIN_HOME") or Path(__file__).resolve().parents[2])
 RECIPES = HOME / "mindxtrain" / "train" / "recipes"
 TIERS = ["Basic", "Advanced", "Scientific"]

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mindxtrain"
-version = "1.0.1"
+version = "1.0.2"
 description = "Production training framework for fine-tuning open-weight LLMs on AMD MI300X and serving them through an OpenAI-compatible API."
 requires-python = ">=3.12,<3.13"
 license = { text = "Apache-2.0" }
@@ -45,10 +45,14 @@ ui = [
     "gradio[mcp]>=5.0",
     "pyyaml>=6.0",
 ]
+# The Hub is not a chain. It had been living inside `chain`, so reaching Hugging Face
+# meant installing web3 and the Algorand SDK; `chain` still pulls it so existing
+# installs keep working.
+hf = ["huggingface-hub>=0.26"]
 chain = [
     "web3>=7.5",
     "py-algorand-sdk>=2.7",
-    "huggingface-hub>=0.26",
+    "mindxtrain[hf]",
 ]
 obs = [
     "opentelemetry-sdk>=1.28",
@@ -56,7 +60,7 @@ obs = [
     "psutil>=6.1",
 ]
 all = [
-    "mindxtrain[ml,eval,data,serve,chain,obs,ui]",
+    "mindxtrain[ml,eval,data,serve,chain,obs,ui,hf]",
 ]
 
 [build-system]

tests/test_hf_extension.py

@@ -0,0 +1,159 @@
+"""Units for the Hugging Face extension and its CLI surface.
+
+`huggingface_hub` is an optional extra and is NOT installed in this environment, which makes
+the missing-dependency path a real test rather than a mocked one. Everything else runs against
+stubs: no token, no network, no Hub.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+from typer.testing import CliRunner
+
+from mindxtrain.cli.main import app
+from mindxtrain.hf import extension as ext
+
+runner = CliRunner()
+
+
+@pytest.fixture(autouse=True)
+def no_ambient_token(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A developer's real HF_TOKEN must not change what these tests assert."""
+    for name in ext._HF_ENV:
+        monkeypatch.delenv(name, raising=False)
+
+
+# --- token resolution --------------------------------------------------------------------
+
+
+def test_explicit_token_beats_the_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HF_TOKEN", "from-env")
+    assert ext._token("explicit") == "explicit"
+
+
+def test_environment_names_are_tried_in_order(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HUGGINGFACEHUB_API_TOKEN", "third")
+    assert ext._token() == "third"
+    monkeypatch.setenv("HF_TOKEN", "first")
+    assert ext._token() == "first"
+
+
+def test_no_token_anywhere_is_none() -> None:
+    assert ext._token() is None
+
+
+# --- the optional dependency is reported, never raised -----------------------------------
+
+
+def test_missing_dependency_is_a_result_not_an_exception() -> None:
+    """`huggingface_hub` is genuinely absent here — this asserts the real path."""
+    api, err = ext._api("a-token")
+    assert api is None
+    assert err["ok"] is False
+    assert "--extra hf" in err["reason"]  # the extra that actually installs it
+
+
+def test_pull_base_reports_the_missing_dependency() -> None:
+    out = ext.pull_base("HuggingFaceTB/SmolLM2-135M")
+    assert out["ok"] is False and "huggingface_hub" in out["reason"]
+
+
+def test_no_token_names_the_variables_to_set(monkeypatch: pytest.MonkeyPatch) -> None:
+    """With the library present but no token, the error must say which env vars are read."""
+    monkeypatch.setattr(ext, "_api", ext._api)  # keep the real function
+    fake_hub = type("m", (), {"HfApi": lambda **kw: None})
+    monkeypatch.setitem(__import__("sys").modules, "huggingface_hub", fake_hub)
+    api, err = ext._api()
+    assert api is None
+    assert "HF_TOKEN" in err["reason"]
+
+
+# --- tree_paths: the RepoFolder trap -----------------------------------------------------
+
+
+# The filter matches on the CLASS NAME, so these stubs must carry the Hub's exact names —
+# `tree_paths` deliberately avoids importing the optional type just to check it.
+class RepoFile:
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+
+class RepoFolder:
+    def __init__(self, path: str) -> None:
+        self.path = path
+
+
+def test_tree_paths_skips_folders() -> None:
+    """Folders and files both carry `.path`; counting folders as files corrupts any scan."""
+    api = type("A", (), {"list_repo_tree": lambda self, r, **kw: [
+        RepoFile("gen1/adapter.safetensors"), RepoFolder("gen1"), RepoFile("README.md"),
+    ]})()
+    assert ext.tree_paths(api, "PYTHAI/x") == ["gen1/adapter.safetensors", "README.md"]
+
+
+def test_tree_paths_on_a_tree_of_only_folders_is_empty() -> None:
+    """The bug this guards: a scan reporting "nothing on the Hub" while the repo is full."""
+    api = type("A", (), {"list_repo_tree": lambda self, r, **kw: [RepoFolder("gen1"), RepoFolder("gen2")]})()
+    assert ext.tree_paths(api, "PYTHAI/x") == []
+
+
+# --- guards that must not need a network -------------------------------------------------
+
+
+def test_warm_refuses_a_config_without_a_model(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    cfg = tmp_path / "run.yaml"
+    cfg.write_text("train:\n  epochs: 1\n", encoding="utf-8")
+    out = ext.warm(cfg)
+    assert out["ok"] is False
+    assert "model.name" in out["reason"] or "huggingface_hub" in out["reason"]
+
+
+def test_publish_refuses_a_missing_run_dir(tmp_path) -> None:  # type: ignore[no-untyped-def]
+    out = ext.publish_generation(tmp_path / "nope", "PYTHAI/x")
+    assert out["ok"] is False and "no run dir" in out["reason"]
+
+
+# --- the CLI surface ---------------------------------------------------------------------
+
+
+def test_hf_is_registered_as_a_command_group() -> None:
+    result = runner.invoke(app, ["--help"])
+    assert "hf" in result.stdout
+
+
+def test_every_hf_verb_is_reachable() -> None:
+    result = runner.invoke(app, ["hf", "--help"])
+    for verb in ("whoami", "pull", "warm", "publish", "lineage", "dataset", "space"):
+        assert verb in result.stdout
+
+
+def test_failure_exits_nonzero_so_a_script_can_branch() -> None:
+    """The ascent loop warms a base and checks $? — an `ok:false` that exits 0 would be a trap."""
+    result = runner.invoke(app, ["hf", "whoami"])
+    assert result.exit_code == 1
+    assert "huggingface_hub" in result.stdout
+
+
+def test_success_exits_zero_and_prints_the_result(monkeypatch: pytest.MonkeyPatch) -> None:
+    import mindxtrain.hf as hf_pkg
+
+    monkeypatch.setattr(hf_pkg, "account", lambda tok=None: {"ok": True, "name": "Gregory-L",
+                                                             "can_write": ["PYTHAI"]})
+    result = runner.invoke(app, ["hf", "whoami"])
+    assert result.exit_code == 0
+    assert "Gregory-L" in result.stdout
+
+
+def test_token_option_is_passed_through(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: dict[str, Any] = {}
+    import mindxtrain.hf as hf_pkg
+
+    def fake_account(tok=None):  # type: ignore[no-untyped-def]
+        seen["token"] = tok
+        return {"ok": True}
+
+    monkeypatch.setattr(hf_pkg, "account", fake_account)
+    assert runner.invoke(app, ["hf", "whoami", "--token", "abc"]).exit_code == 0
+    assert seen["token"] == "abc"