v1.0.4 — close the limitations 1.0.3 listed, and correct the ones it overstated

Correction first: 1.0.3 called every write endpoint and SSE-under-a-real-producer untested. True of its probes, not of the project — the suite already covers both (test_runs_sse.py and a dozen test_coach_*_api.py), and it passed on the refreshed lock. A new module written for those endpoints was deleted once that was checked, rather than shipped as duplicate coverage.

Real gaps closed: the Gradio surface is tested (Blocks tree built, rooms and version parity checked, launched for real under gradio 6.27) and had no coverage at all; the Hub tests no longer trust the environment for the missing-dependency path (they inverted silently once the ui extra brought huggingface-hub in); httpx2 joins the dev group so starlette 1.6 stops deprecating TestClient.

Training path verified under the refreshed lock: dream corpus tokenized, SFT run on CPU (loss 3.938, 512 tokens), a real 22 MB LoRA checkpoint written. 767 pass with the ml extra. ROCm/MI300X, multi-GPU, vLLM serving, full-length runs and the imprint->serve tail remain untested and are named as such.

docs/CHANGELOG.md

@@ -6,6 +6,65 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.0.4] — 2026-09-16
+
+### Added
+
+- **The Gradio surface is tested.** `mindxtrain ui` had no coverage at all — gradio is an
+  optional extra, so a base install cannot import the module, and every release note listed the
+  UI as untested. `tests/test_ui_app_builds.py` constructs the whole Blocks tree (which
+  exercises every component definition in `ui/app.py`), checks the rooms the docs promise,
+  asserts the surface version matches the package, and confirms the PEP 562 lazy export
+  resolves. It skips cleanly where the extra is absent. The UI was also launched for real
+  under gradio 6.27.0 and served its page and config.
+
+### Fixed
+
+- **The Hub tests asserted the missing-dependency path by trusting the environment.** They
+  passed on a bare install and inverted silently the moment the `ui` extra arrived, because
+  gradio depends on huggingface-hub — three tests failed the first time they met an
+  environment that had it. Absence is now *forced* (`sys.modules[name] = None` makes the
+  import raise), so the contract holds whatever is installed, and it is verified both ways.
+  Introduced in 1.0.2, where the note "tested for real rather than mocked" was true only of a
+  bare install.
+
+### Changed
+
+- **`httpx2` added to the dev group.** starlette 1.6 deprecates driving its `TestClient` with
+  `httpx`; 24 test modules use `TestClient`, so the dependency moves rather than the tests.
+  The deprecation is gone; the two warnings that remain are upstream typer → click 9.0.
+
+### Notes — a correction to v1.0.3, and what is now verified
+
+**v1.0.3 overstated its own limitations.** It listed "every write endpoint" and "SSE under a
+real producer" as untested. That was true of the dependency-refresh *probes* run for that
+release; it was **not** true of the project. The suite already covers the coach's write
+endpoints — bench, compile, cost, eval/prompt, modelfile build and create, ollama start and
+stop, boardroom, dojo, datasets, mei promote, classroom, autotune feedback, dcoach, chat
+stream — and SSE under a real producer, in `tests/test_runs_sse.py` and a dozen
+`test_coach_*_api.py` modules, including buffer replay on late subscribe, log-kind filtering,
+ingest and cancel. All of it passed on the refreshed lock. A new test module was written for
+those endpoints before that was checked; every endpoint turned out to be covered already and
+the in-stream error contract already asserted, so it was deleted rather than added as
+duplicate coverage.
+
+**The training path is now verified under the refreshed lock** (torch 2.11.0, transformers
+5.8.0, trl 1.3.0, peft 0.19.1, alongside starlette 1.6.0 and the pydantic downgrade). The
+dream-corpus loop was run end to end on CPU — corpus read, tokenized, SFT executed
+(loss 3.938, mean_token_accuracy 0.370, 512 tokens), and a real 22 MB LoRA checkpoint written
+with `adapter_model.safetensors`, `adapter_config.json`, tokenizer and chat template. With the
+ml extra installed the suite is **767 passed** (the two tokenizer tests stop skipping).
+
+**Still not tested, and not claimed:**
+
+- **MI300X / ROCm, multi-GPU, and vLLM serving.** No such hardware here; the CPU lane is what
+  was exercised.
+- **A full-length run.** The shipped 32-sample smoke recipe projects ~70 minutes on this
+  shared box (8.7 min/step at 50% CPU), so the loop was closed with a reduced variant — 4
+  samples at seq 128, the same code path, fewer tokens. Multi-hour and multi-day behaviour is
+  unchanged and unverified here.
+- **The `imprint` → `serve --to ollama` tail**, which needs a running daemon.
+
 ## [1.0.3] — 2026-09-15
 
 ### Changed

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.3).
+Version history (current: v1.0.4).
 - [[Unreleased]](CHANGELOG.md#unreleased)
+- [[1.0.4] — 2026-09-16](CHANGELOG.md#104--2026-09-16)
 - [[1.0.3] — 2026-09-15](CHANGELOG.md#103--2026-09-15)
 - [[1.0.2] — 2026-09-15](CHANGELOG.md#102--2026-09-15)
 - [[1.0.1] — 2026-09-15](CHANGELOG.md#101--2026-09-15)

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.3"
+__version__ = "1.0.4"

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.3"
+VERSION = "1.0.4"
 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.3"
+version = "1.0.4"
 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" }
@@ -74,6 +74,9 @@ packages = ["mindxtrain"]
 dev = [
     "pytest>=8.3",
     "pytest-asyncio>=0.24",
+    # starlette 1.6 deprecates driving its TestClient with httpx and asks for httpx2.
+    # 24 test modules use TestClient, so the dependency moves rather than the tests.
+    "httpx2>=2.13",
     "ruff>=0.7",
     "mypy>=1.13",
     "types-PyYAML>=6.0",

tests/test_hf_extension.py

@@ -1,12 +1,15 @@
 """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.
+`huggingface_hub` is an optional extra, so the missing-dependency path is asserted by FORCING
+its absence (`sys.modules[name] = None` makes `import` raise) rather than by trusting the
+ambient environment. It was trusted once: these tests passed on a bare install and inverted
+silently the moment the `ui` extra arrived, because gradio depends on huggingface-hub.
+Everything else runs against stubs: no token, no network, no Hub.
 """
 
 from __future__ import annotations
 
+import sys
 from typing import Any
 
 import pytest
@@ -25,6 +28,16 @@ def no_ambient_token(monkeypatch: pytest.MonkeyPatch) -> None:
         monkeypatch.delenv(name, raising=False)
 
 
+@pytest.fixture
+def hub_absent(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Force `import huggingface_hub` to fail, whatever is installed.
+
+    A `None` entry in `sys.modules` makes the import raise ImportError, so the
+    not-installed contract is testable on a machine where the extra IS installed.
+    """
+    monkeypatch.setitem(sys.modules, "huggingface_hub", None)
+
+
 # --- token resolution --------------------------------------------------------------------
 
 
@@ -47,15 +60,15 @@ def test_no_token_anywhere_is_none() -> 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."""
+def test_missing_dependency_is_a_result_not_an_exception(hub_absent: None) -> None:
+    """A missing optional extra is reported as a result; it must never raise at the caller."""
     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:
+def test_pull_base_reports_the_missing_dependency(hub_absent: None) -> None:
     out = ext.pull_base("HuggingFaceTB/SmolLM2-135M")
     assert out["ok"] is False and "huggingface_hub" in out["reason"]
 
@@ -129,7 +142,7 @@ def test_every_hf_verb_is_reachable() -> None:
         assert verb in result.stdout
 
 
-def test_failure_exits_nonzero_so_a_script_can_branch() -> None:
+def test_failure_exits_nonzero_so_a_script_can_branch(hub_absent: None) -> 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

tests/test_ui_app_builds.py

@@ -0,0 +1,44 @@
+"""The Gradio surface: does it actually build?
+
+`mindxtrain ui` had no coverage at all — gradio is an optional extra, so a base install
+cannot import the module, and every release note honestly listed the UI as untested. This
+closes that: where the extra IS installed the whole Blocks tree is constructed, which
+exercises every component definition in `ui/app.py`; where it is not, the test skips and the
+lazy-import contract is checked instead.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+gradio = pytest.importorskip("gradio", reason="the `ui` extra is not installed")
+
+from mindxtrain import __version__  # noqa: E402
+from mindxtrain.ui import app as ui_app  # noqa: E402
+
+
+def test_the_ui_builds_without_launching() -> None:
+    """Constructing the Blocks tree is what catches a broken component definition."""
+    demo = ui_app.build()
+    assert isinstance(demo, gradio.Blocks)
+
+
+def test_the_ui_reports_the_package_version() -> None:
+    """The surface must not drift from the package it ships with."""
+    assert ui_app.VERSION == __version__
+
+
+def test_the_rooms_are_present() -> None:
+    """Basic / Advanced / Scientific and the named rooms the docs promise."""
+    demo = ui_app.build()
+    labels = {getattr(b, "label", None) for b in demo.blocks.values()}
+    for room in ("Console · talk to it", "Dataset", "Quantize · CPU", "Science · MEI + research"):
+        assert room in labels, f"missing room: {room}"
+
+
+def test_build_is_reachable_from_the_package_root() -> None:
+    """The PEP 562 lazy export resolves once gradio is importable."""
+    import mindxtrain.ui as ui_pkg
+
+    assert callable(ui_pkg.build)
+    assert ui_pkg.VERSION == __version__

uv.lock

@@ -1365,6 +1365,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
 ]
 
+[[package]]
+name = "httpcore2"
+version = "2.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "h11", marker = "sys_platform != 'emscripten'" },
+    { name = "truststore", marker = "sys_platform != 'emscripten'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/15/8c/e925b1c92018abb3a1863ce1549d76d2381e334d21d65d4ac8f65dabd78a/httpcore2-2.13.0.tar.gz", hash = "sha256:2adc8be4fb285fbcd6d894298db3b52c177e74b6674eda3a76bd36be3292a3db", size = 67740, upload-time = "2026-09-14T14:18:04.717Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7e/0d/117a771a2bb91df334b66bf4da14cd02f21aefbcfe53180f336ce55e8f90/httpcore2-2.13.0-py3-none-any.whl", hash = "sha256:35ae5be347aa40467b4a5dc032ac67ebb6d27189fc97e8cebcf99616f6a1bb9e", size = 83162, upload-time = "2026-09-14T14:18:02.529Z" },
+]
+
 [[package]]
 name = "httptools"
 version = "0.7.1"
@@ -1404,6 +1417,32 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
 ]
 
+[[package]]
+name = "httpx2"
+version = "2.13.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio", marker = "sys_platform != 'emscripten'" },
+    { name = "httpcore2", marker = "sys_platform != 'emscripten'" },
+    { name = "httpx2-jsfetch", marker = "sys_platform == 'emscripten'" },
+    { name = "idna" },
+    { name = "truststore", marker = "sys_platform != 'emscripten'" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b9/a0/e9deef4654132857b5a5dbe4eddd0ac59c2814500e11f2f5044cd81103ee/httpx2-2.13.0.tar.gz", hash = "sha256:81bd07dc67a3701729ef1f777a3c00c915d4539604fdb5afd327f8682f6b7b44", size = 100290, upload-time = "2026-09-14T14:18:05.486Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fe/d1/a0c72b0e006df654709fbc366cc5bcb53e5aee13e1e3395152c6dd293376/httpx2-2.13.0-py3-none-any.whl", hash = "sha256:fc12720cedf72faa26cca6b4ca394e05c894e7d7933fc45cafe767960804e49a", size = 95565, upload-time = "2026-09-14T14:18:03.553Z" },
+]
+
+[[package]]
+name = "httpx2-jsfetch"
+version = "1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/cd/c4/0e5636363151a2a1795e0a77617168b9ca438e1748ec05fc9b5687f93d64/httpx2_jsfetch-1.0.tar.gz", hash = "sha256:70a0e3eabfef7cce5ad9c629f7d01ca05e418f586646f4ddf14782e4c1454c60", size = 6872, upload-time = "2026-08-07T00:13:07.492Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9b/43/832f631d32e4f1211caa2ba368317739fe71f0b8530e4c9d15dc454bac2a/httpx2_jsfetch-1.0-py3-none-any.whl", hash = "sha256:cb916b707601e69a07721aabc8f3f6659be3a6893bc1ff5c6f9e02241df2da32", size = 6382, upload-time = "2026-08-07T00:13:06.567Z" },
+]
+
 [[package]]
 name = "huggingface-hub"
 version = "1.31.0"
@@ -1431,11 +1470,11 @@ hf-xet = [
 
 [[package]]
 name = "idna"
-version = "3.13"
+version = "3.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ce/cc/762dfb036166873f0059f3b7de4565e1b5bc3d6f28a414c13da27e442f99/idna-3.13.tar.gz", hash = "sha256:585ea8fe5d69b9181ec1afba340451fba6ba764af97026f92a91d4eef164a242", size = 194210, upload-time = "2026-04-22T16:42:42.314Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5f/f7/abb373e5757eaec4b922b92f97ec8d6d7e057cf06778247604fbc4e7c3f3/idna-3.19.tar.gz", hash = "sha256:5e0811a4383b21dc5838069f801c4fb62113b7447663d2530d2bd6e77b49bf15", size = 215237, upload-time = "2026-08-18T05:14:24.27Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/5d/13/ad7d7ca3808a898b4612b6fe93cde56b53f3034dcde235acb1f0e1df24c6/idna-3.13-py3-none-any.whl", hash = "sha256:892ea0cde124a99ce773decba204c5552b69c3c67ffd5f232eb7696135bc8bb3", size = 68629, upload-time = "2026-04-22T16:42:40.909Z" },
+    { url = "https://files.pythonhosted.org/packages/57/b0/0e52c878c53f245edd3a11020f20979b3f490f245af532c7cae3027754b5/idna-3.19-py3-none-any.whl", hash = "sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4", size = 68550, upload-time = "2026-08-18T05:14:22.343Z" },
 ]
 
 [[package]]
@@ -1971,7 +2010,7 @@ wheels = [
 
 [[package]]
 name = "mindxtrain"
-version = "1.0.3"
+version = "1.0.4"
 source = { editable = "." }
 dependencies = [
     { name = "blake3" },
@@ -2051,6 +2090,7 @@ ui = [
 
 [package.dev-dependencies]
 dev = [
+    { name = "httpx2" },
     { name = "mypy" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
@@ -2097,6 +2137,7 @@ provides-extras = ["ml", "eval", "data", "serve", "ui", "hf", "chain", "obs", "a
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "httpx2", specifier = ">=2.13" },
     { name = "mypy", specifier = ">=1.13" },
     { name = "pytest", specifier = ">=8.3" },
     { name = "pytest-asyncio", specifier = ">=0.24" },
@@ -4255,6 +4296,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/cf/38/d13f2bc31ce1071eaf519f16f0d2e51d92d08c01895992b05ebe801385d9/trl-1.3.0-py3-none-any.whl", hash = "sha256:55d5bed9983aa3e781c2d0af3b500ea78706247ae7c1852f76ea80417a3f7d5e", size = 721624, upload-time = "2026-04-26T15:28:25.872Z" },
 ]
 
+[[package]]
+name = "truststore"
+version = "0.10.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/a3/1585216310e344e8102c22482f6060c7a6ea0322b63e026372e6dcefcfd6/truststore-0.10.4.tar.gz", hash = "sha256:9d91bd436463ad5e4ee4aba766628dd6cd7010cf3e2461756b3303710eebc301", size = 26169, upload-time = "2025-08-12T18:49:02.73Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/19/97/56608b2249fe206a67cd573bc93cd9896e1efb9e98bce9c163bcdc704b88/truststore-0.10.4-py3-none-any.whl", hash = "sha256:adaeaecf1cbb5f4de3b1959b42d41f6fab57b2b1666adb59e89cb0b53361d981", size = 18660, upload-time = "2025-08-12T18:49:01.46Z" },
+]
+
 [[package]]
 name = "typepy"
 version = "1.3.5"