bankml: the verified CPU engine as backend, serve target and imprint probe

CLAUDE.md

@@ -98,7 +98,7 @@ mindX artifacts (dream corpus, persona) through boundaries, it does not vendor m
 
 - **New recipe** → drop YAML at `mindxtrain/train/recipes/<name>.yaml`; `test_all_recipes_validate` picks it up.
 - **New training backend** → add `mindxtrain/train/backend_<name>.py` exposing `run_<name>(cfg, plan, out_dir) -> Path`; wire into `train/dispatch.py`; add to `TrainingBackend` literal in `config/schema.py`.
-- **New operator backend** → subclass `Backend` in `mindxtrain/operator/backends/<name>.py` decorated `@register_backend("<name>")`; side-effect import from `models/registry.py`; add runtime branch in `operator/app.py::chat_completions`.
+- **New operator backend** → subclass `Backend` in `mindxtrain/operator/backends/<name>.py` decorated `@register_backend("<name>")`; side-effect import from `models/registry.py`; add its base-URL branch to `operator/app.py::backend_kwargs` (shared by the operator route and the Coach chat stream) and, if it can be probed, to `backend_reachable` / `backend_first_model`. Registered backends: `openai_compat`, `ollama`, `vllm`, `bankml` ([docs/bankml.md](docs/bankml.md) — the verified CPU engine, reached over HTTP/CLI only; receipts on `ChatResponse.receipt`, HTTP 400 → `BankmlRefusal`, never retried).
 - **New training method** → add `_MethodBase` subclass in `config/schema.py` with `kind: Literal["<name>"]`; extend `TrainMethod` discriminated union; add `train/<name>.py` runner; update dispatch; add a recipe.
 
 ## Documentation hub
@@ -115,4 +115,5 @@ mindX artifacts (dream corpus, persona) through boundaries, it does not vendor m
 | `docs/yaml_schema.md` | Every field of the 10-section `XTrainConfig`. |
 | `docs/coach.md` | Interactive `/coach/` web UI bundled in the operator. |
 | `docs/governance.md` | classroom / boardroom (any-N consensus) / dojo (prime-N dispute settlement). |
+| `docs/bankml.md` | bankml ([github.com/cryptoAGI/bankml](https://github.com/cryptoAGI/bankml)): `serve --to bankml`, the `bankml` backend, `imprint-bankml` (not comparable with the canonical gate). |
 | `docs/blueprints/` | Frozen source design briefs (the spec the project was built against). |

README.md

@@ -93,6 +93,35 @@ GPU steps (`bench` without `--dry-run`, `train`, `quantize`, `serve`) require
 an AMD MI300X with ROCm 7.2.1; run inside `rocm/primus:v26.2`. The full
 operator checklist lives in [`HANDOFF.md`](docs/HANDOFF.md).
 
+## Serving on vLLM / SGLang
+
+`mindxtrain serve run.yaml --to vllm` (or `--to sglang`) launches the OpenAI-compatible server on
+the trained run — the LoRA served natively over the base, or merged with `--merge` — detached, with
+its log and pid under `out/runs/<run>/serve/<to>/`, and returns once `/v1/models` lists the tag.
+`--dry-run` prints the exact argv; `--stop` ends it; `--register-as-fallback` hands it to mindX.
+On a host without a GPU it uses the CPU backends and refuses configs that need a GPU, with the
+reason. vLLM: `uv sync --extra serve`; SGLang: install it yourself. Full page: [`docs/serve.md`](docs/serve.md).
+
+## bankml (verified CPU engine)
+
+[bankml](https://github.com/cryptoAGI/bankml) is a zero-dependency Rust runtime, token-identical to
+llama.cpp b11192, that serves OpenAI `/v1` and Ollama `/api` from its own forward pass and puts a
+**receipt** (model / request / response sha256) on every answer. mindXtrain reaches it over HTTP and
+its CLI only — nothing is vendored. Full page: [`docs/bankml.md`](docs/bankml.md).
+
+- `mindxtrain serve run.yaml --to bankml` merges the LoRA and runs `bankml create` (bankml 0.3.5+),
+  which converts the merged SmolLM2 / mindx-genN weights to GGUF F16 byte-identically to llama.cpp
+  and pins them by sha256. It **refuses**, with the reason: quantized configs (FP8, MXFP4, GPTQ,
+  Q8_0, Q4_K), non-Llama architectures, and Modelfile instructions bankml does not reproduce —
+  `ADAPTER`, a foreign `TEMPLATE`, penalties, mirostat, `typical_p`, resource options. An older
+  bankml is reported as too old, not crashed on.
+- `MINDXTRAIN_BACKEND=bankml` routes the operator and Coach chat to `bankml serve`
+  (`MINDXTRAIN_BANKML_BASE_URL`, default `http://127.0.0.1:18093/v1`); answers carry the receipt,
+  and a bankml 400 comes back as a typed `BankmlRefusal`, never retried with altered parameters.
+- `mindxtrain imprint-bankml` probes before/after tags greedily, seeded and unpenalised, with a receipt
+  per utterance — reproducible and auditable, and explicitly **not comparable** with the canonical
+  `mindxtrain imprint` gate (repetition penalty 1.3).
+
 ## Layout
 
 ```
@@ -118,6 +147,8 @@ scripts/          dev helpers
 | [`docs/coach.md`](docs/coach.md) | Interactive `/coach/` web UI bundled in the operator. |
 | [`docs/dcoach.md`](docs/dcoach.md) | The dcoach proof loop — prove a CPU model recalls its training; decentralized-training fit. |
 | [`docs/cli.md`](docs/cli.md) | Every `mindxtrain` verb with synopsis, options, exit codes. |
+| [`docs/serve.md`](docs/serve.md) | `serve --to vllm\|sglang`: native-LoRA or merged launch, readiness, stop, CPU vs GPU, and where every flag was verified. |
+| [`docs/bankml.md`](docs/bankml.md) | bankml as serve target, operator backend and receipt-auditable imprint probe — what it takes and what it refuses. [bankml on GitHub](https://github.com/cryptoAGI/bankml). |
 | [`docs/yaml_schema.md`](docs/yaml_schema.md) | Every field of the 10-section `XTrainConfig`. |
 | [`docs/benchmarks.md`](docs/benchmarks.md) | Target metrics + the 7-cell framework comparison. |
 | [`docs/development.md`](docs/development.md) | Toolchain, optional-deps, lazy-import pattern, invariants. |

docs/CHANGELOG.md

@@ -6,6 +6,51 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **bankml, the verified CPU engine** ([github.com/cryptoAGI/bankml](https://github.com/cryptoAGI/bankml),
+  [`docs/bankml.md`](bankml.md)), reached over HTTP and its CLI only — nothing vendored.
+  - `operator/backends/bankml.py`: `@register_backend("bankml")`, `MINDXTRAIN_BANKML_BASE_URL`
+    (default `http://127.0.0.1:18093/v1`). Keeps bankml's receipt (`ChatResponse.receipt`, new
+    optional field; `last_receipt` for streams, parsed from the final SSE receipt event). HTTP 400
+    → `BankmlRefusal(reason)`, never retried with altered parameters.
+  - Operator wiring: `backend_kwargs(name)` replaces the duplicated per-backend branches in
+    `operator/app.py` and `coach/api.py`; health probes `GET /bankml` and `/v1/models`;
+    auto-detect tries bankml after ollama and vllm, so existing hosts resolve as before; the
+    governance panel's env chain gains `MINDXTRAIN_BANKML_BASE_URL` last, only when set.
+  - `deploy/bankml_push.py` and `mindxtrain serve --to bankml [--bankml-bin] [--bankml-convert]`:
+    merge → Modelfile through `bankml_sanitize` (refuses `ADAPTER`, a foreign `TEMPLATE`,
+    penalties, mirostat, `typical_p`, resource options, rather than dropping them) →
+    `bankml create`; records the model sha256; refuses quantized configs and non-Llama
+    architectures; detects a bankml without `create`/`convert` (pre-0.3.5) as `bankml_too_old`.
+  - `eval/imprint_bankml.py` and `mindxtrain imprint-bankml`: seeded, unpenalised greedy probes with
+    a receipt per utterance, scored by `score_imprint`, tagged `<scorer>/bankml-greedy` and marked
+    **not comparable** with the canonical 1.3-penalty gate.
+  - MEI `InferenceEngineIdent.name` accepts `"bankml"`; the Gradio Serve room offers `bankml`.
+
+- **`serve --to vllm|sglang` are real deploy targets** ([`docs/serve.md`](serve.md)), no longer
+  print-only. `deploy/openai_server_push.py`: `launch_openai_server` serves a LoRA natively over
+  the base (vLLM `--enable-lora --lora-modules`, SGLang `--enable-lora --lora-paths`) or merged
+  (`--merge`, `merge_lora_adapter`), launches detached (own session; `server.log`, `server.pid`,
+  `launch.json` under `out/runs/<run>/serve/<to>/`), waits for `/v1/models` (+ vLLM `/health`),
+  and optionally swaps mindX's fallback (`provider="vllm"|"sglang"`); `stop_openai_server` SIGTERMs
+  the process group and verifies it is gone. CPU hosts get bfloat16, `VLLM_CPU_KVCACHE_SPACE`,
+  SGLang `--device cpu`; quantized checkpoints and `tensor_parallel > 1` are refused without a
+  GPU; a missing server is reported with its install hint. Every outcome is a
+  `ServerLaunchResult` / `ServerStopResult`. New CLI options: `--dry-run`, `--stop`, `--merge`,
+  `--host`, `--port`, `--dtype`, `--server-bin`, `--server-arg`, `--ready-timeout`,
+  `--cpu-kvcache-gib`. The Gradio Serve room offers `sglang`. vLLM / SGLang are reached as a
+  subprocess and over HTTP only.
+
+### Changed
+
+- `ui/console.py` omits penalty / mirostat options left at the engine's own default, so bankml
+  accepts default console requests. For Ollama a Modelfile's `repeat_penalty` now applies where
+  the console used to override it with 1.1.
+- `hf.extension.publish_generation(repeat_penalty=…)`: `None` publishes a Modelfile without the
+  penalty line (default unchanged, 1.3); the Modelfile text is `published_modelfile()`.
+- `cli imprint`: the script-probe extraction is `_script_probes`, shared with `imprint-bankml`.
+
 ## [1.0.4] — 2026-09-16
 
 ### Added

docs/NAV.md

@@ -123,6 +123,16 @@ The interactive `/coach/` operator UI: create-script, live-training diagnostics,
 - [How mindXtrain fits decentralized training](dcoach.md#how-mindxtrain-fits-decentralized-training)
 - [Why this matters](dcoach.md#why-this-matters)
 
+### [Serving on vLLM and SGLang](serve.md)
+
+- [What runs](serve.md#what-runs) · [CPU and GPU](serve.md#cpu-and-gpu) · [Exit codes](serve.md#exit-codes) · [Where each flag comes from](serve.md#where-each-flag-comes-from)
+
+### [bankml — the verified CPU engine](bankml.md)
+[bankml](https://github.com/cryptoAGI/bankml) as serve target, operator backend and receipt-auditable imprint probe.
+- [What bankml runs, and what it refuses](bankml.md#what-bankml-runs-and-what-it-refuses)
+- [Operator backend](bankml.md#operator-backend--mindxtrain_backendbankml) · [`serve --to bankml`](bankml.md#serving-a-trained-run--mindxtrain-serve---to-bankml) · [The Modelfile subset](bankml.md#the-modelfile-subset-bankml_sanitize)
+- [`imprint-bankml` (not comparable with the canonical gate)](bankml.md#a-second-imprint-instrument--mindxtrain-imprint-bankml)
+
 ### [Governance](governance.md)
 classroom (graduation) / boardroom (any-N consensus) / dojo (prime-N dispute settlement), model-backed deliberation.
 - [The model](governance.md#the-model) · [Flow](governance.md#flow) · [Why prime](governance.md#why-prime)

docs/bankml.md

@@ -0,0 +1,133 @@
+# bankml — the verified CPU engine
+
+[bankml](https://github.com/cryptoAGI/bankml) is a zero-dependency Rust runtime for 1-bit (`Q1_0`),
+ternary (`Q2_0_g64`) and F16 GGUF models, **token-identical to llama.cpp b11192** on every oracle in
+its release gate. `bankml serve --native` answers OpenAI `/v1/chat/completions` and Ollama `/api/*`
+from its own forward pass on `127.0.0.1:18093`, and puts a **receipt** on every answer. mindXtrain
+uses it as a serve target, an operator backend and a second imprint instrument.
+
+mindXtrain reaches bankml **only over HTTP and as a CLI subprocess**. No bankml code is vendored
+(the clean-room policy in [`CLAUDE.md`](../CLAUDE.md)). bankml's own docs:
+[README](https://github.com/cryptoAGI/bankml#readme) ·
+[usage](https://github.com/cryptoAGI/bankml/blob/main/docs/usage.md) ·
+[bankML as mindX's Ollama](https://github.com/cryptoAGI/bankml/blob/main/docs/OLLAMA.md).
+
+## What bankml runs, and what it refuses
+
+| | bankml |
+|---|---|
+| **Architectures** | Qwen3 (`Q1_0`, `Q2_0_g64`: the Bonsai family) and Llama in F16 (SmolLM2-135M, mindX's `mindx-genN`) |
+| **Sampling it reproduces** | `temperature`, `top_k`, `top_p`, `min_p`, `seed`, JSON mode; `num_ctx`, `num_predict`, `stop` |
+| **Refused with HTTP 400 and a reason** | repeat / presence / frequency penalties (non-neutral), `mirostat`, `typical_p`, `tools`, images, a replacement `template`, unknown architectures, `Q8_0` / `Q4_K` / `BF16` |
+| **Receipt** (`bankml_receipt`) | `bankml` version, `engine`, `model_sha256`, `guard`, `prompt_tokens`, `completion_tokens`, `ttft_ms`, `wall_ms`, `response_sha256`, `request_sha256`, `signed: false` |
+
+A refusal is the product, not a defect: bankml answers only what its verified forward pass does.
+mindXtrain mirrors that — it **never retries a refused request with altered parameters**, and never
+drops a Modelfile instruction to make bankml accept it.
+
+## Operator backend — `MINDXTRAIN_BACKEND=bankml`
+
+`mindxtrain/operator/backends/bankml.py` registers `bankml` (a subclass of `openai_compat`).
+
+```bash
+bankml serve MODEL.gguf --fork MODEL.gguf.FORK.json --native --registry   # 127.0.0.1:18093
+MINDXTRAIN_BACKEND=bankml uv run uvicorn mindxtrain.operator.app:app --port 8080
+```
+
+- `MINDXTRAIN_BANKML_BASE_URL` (default `http://127.0.0.1:18093/v1`).
+- `POST /v1/chat/completions` returns `ChatResponse.receipt`; the backend also keeps `last_receipt`.
+  Streamed answers parse bankml's final `data: {"bankml_receipt": …}` event.
+- HTTP 400 → `BankmlRefusal(reason)` → the operator answers 400 with bankml's reason. Other non-2xx
+  and a mid-stream `{"error": …}` → `BankmlError`.
+- Health: `/health`, `/readyz` and `/coach/api/health` probe `GET /bankml` (the identity endpoint) and
+  list the model from `/v1/models`.
+- **Auto-detect** (no `MINDXTRAIN_BACKEND`): ollama → vllm → bankml → vllm. bankml is chosen only
+  when ollama is down, `GET /bankml` answers and vLLM does not, so a host that resolved to ollama or
+  vllm before keeps doing so.
+- Governance panels (`resolve_chat_base_url`): `MINDXTRAIN_BACKEND=bankml` uses bankml's URL; else
+  `MINDXTRAIN_BANKML_BASE_URL` is appended *last* to the OPENAI → VLLM → OLLAMA chain, and only
+  when it is set.
+
+## Serving a trained run — `mindxtrain serve --to bankml`
+
+```bash
+uv run mindxtrain serve run.yaml --to bankml [--tag mindx-gen80] [--checkpoint DIR] \
+    [--bankml-bin PATH] [--bankml-convert] [--register-as-fallback]
+```
+
+1. **Refuses up front** (exit 2): `quantize.enabled` with a scheme other than `none` (bankml serves
+   the merged weights as GGUF F16; it does not reproduce FP8, MXFP4, GPTQ, Q8_0 or Q4_K), and base
+   families bankml cannot convert (Qwen, Mistral, Phi, Gemma, GLM, DeepSeek, Instella).
+2. Checks the binary: `bankml version` and the verbs in `bankml --help`. `bankml create` and
+   `bankml convert` arrive in **bankml 0.3.5**; an older binary is reported as
+   `bankml_too_old` (exit 2), never as a crash. The verbs are the truth — an unreleased build may
+   still say 0.3.4 and already carry them.
+3. Merges the LoRA (`merge_lora_adapter`, needs `uv sync --extra ml`), or takes the checkpoint as an
+   already-merged directory when it holds `config.json` and no `adapter_config.json`.
+4. Re-checks the merged `config.json`: only `LlamaForCausalLM` converts.
+5. Writes a Modelfile through `bankml_sanitize` and runs `bankml create <tag> -f Modelfile`, which
+   converts the merged safetensors to GGUF F16 byte-identically to llama.cpp b11192 and pins it.
+   `--bankml-convert` runs `bankml convert` (GGUF + `FORK.json`) first and writes `FROM <gguf>`.
+6. Records the model sha256 bankml prints for the base it verified, and the derived model's digest.
+7. `--register-as-fallback` PATCHes mindX's fallback model to `{provider: "bankml", model: <tag>}`
+   (best-effort, as for ollama).
+
+### The Modelfile subset (`bankml_sanitize`)
+
+| instruction | bankml |
+|---|---|
+| `FROM` merged dir / pinned GGUF / registry name | taken |
+| `SYSTEM`, `MESSAGE`, `LICENSE`, `REQUIRES` | taken (recorded) |
+| `PARAMETER` temperature, top_k, top_p, min_p, seed, num_ctx, num_predict; `stop` | taken |
+| `ADAPTER` | **refused** — merge first (`push_to_bankml` does) |
+| `TEMPLATE` | **refused** unless equal to the base's own chat template |
+| penalties, `repeat_last_n`, mirostat*, `typical_p` | **refused** — not reproduced |
+| `num_gpu`, `num_thread`, `num_batch`, `num_keep`, `draft_num_predict` | **refused** — a resource option is not part of a model |
+
+Each refusal is returned with its reason; nothing is dropped silently. Python API:
+`mindxtrain.deploy.bankml_push.push_to_bankml(...) -> BankmlPushResult` (never raises; `status` is
+one of `created`, `refused`, `bankml_missing`, `bankml_too_old`, `merge_failed`, `failed`, `error`).
+
+## A second imprint instrument — `mindxtrain imprint-bankml`
+
+```bash
+uv run mindxtrain imprint-bankml run.yaml --before smollm2-135m-instruct --after mindx-gen80 \
+    [--seed 0] [--num-predict 48] [--system "…"] [--base-url http://127.0.0.1:18093/v1]
+```
+
+Poses the script's user-turns to two tags on bankml's `/api/chat` with `temperature 0`, a fixed
+`seed`, `num_predict 48` and **no penalties**, then scores with the existing `score_imprint`. The
+report (`BankmlImprintReport`) carries the decoding, every utterance's receipt and the distinct
+`model_sha256` values, and `report.method` is tagged `<scorer>/bankml-greedy`.
+
+**It is not comparable with the canonical gate.** `mindxtrain imprint` decodes with transformers
+greedy, `repetition_penalty 1.3` and `no_repeat_ngram_size 3`; every number in an ascent log comes
+from that. A bankml-greedy score is compared only with bankml-greedy scores, and the report says so
+(`canonical_gate: false`, `comparable_with: "bankml-greedy only"`). What it buys:
+
+- **reproducible** — the same seed and weights give the same tokens, identical to llama.cpp;
+- **auditable** — a score is tied to the exact weights by sha256, not to a tag name;
+- **cheap** — a 135M F16 actor answers on one CPU core, with no torch in the probing process.
+
+Observed on mindx-gen39 (2026-10-02): unpenalised greedy decoding degenerates on short probes
+without a system turn (runs of `,` and `?||`), which is the very behaviour the 1.3 penalty in the
+canonical gate suppresses. Expect low bankml-greedy voice scores until the actor itself stops
+repeating; pass the persona's `--system` as the coach does.
+
+## Console and published Modelfiles
+
+- `mindxtrain/ui/console.py` no longer sends a penalty or mirostat option left at the engine's own
+  default (`repeat_penalty 1.1`, presence / frequency `0`, `typical_p 1`, `mirostat 0` and its
+  tau / eta while it is off), so bankml accepts a console request with default settings. A
+  deliberate value is always sent; bankml then refuses it visibly. For Ollama an absent key means
+  its own default, except that a Modelfile's `PARAMETER repeat_penalty` now applies where the
+  console used to override it with 1.1.
+- `hf.extension.publish_generation(..., repeat_penalty=None)` publishes a Modelfile without the
+  penalty line, which bankml can load. The default stays 1.3.
+
+## Tests
+
+`tests/test_bankml_backend.py`, `tests/test_bankml_push.py`, `tests/test_imprint_bankml.py` — no
+network and no binary: `httpx.MockTransport`, monkeypatched `subprocess.run` / `shutil.which`.
+`tests/conftest.py` pins the bankml auto-detect probe to "absent" so a developer box running bankml
+cannot change what the other auto-detect tests resolve to.

docs/cli.md

@@ -131,19 +131,46 @@ Requires the `amd-quark` package — typically only available inside the
 `rocm/primus:v26.2` container or per
 [Quark docs](https://quark.docs.amd.com/).
 
-## `serve` — print the vLLM-ROCm launch command
+## `serve` — launch vLLM / SGLang (default `--to vllm`)
 
 ```
-mindxtrain serve <config.yaml> [--checkpoint <path>]
+mindxtrain serve <config.yaml> [--to vllm|sglang] [--checkpoint <path>] [--tag NAME] [--merge]
+                 [--host 127.0.0.1] [--port N] [--dtype auto] [--server-bin PATH]
+                 [--server-arg ARG ...] [--ready-timeout 600] [--cpu-kvcache-gib 4]
+                 [--register-as-fallback] [--dry-run | --stop]
 ```
 
-Builds the `vllm serve` argv from `cfg.serve` and prints it. We deliberately
-don't `exec` — the user pipes it into their own orchestrator (or
-`ops/compose/compose_dev.yaml`).
+Launches `vllm serve` / `python -m sglang.launch_server` detached (log, pid and `launch.json` under
+`out/runs/<run>/serve/<to>/`), serving a LoRA natively over the base (`--merge` merges it first),
+waits until `/v1/models` lists the tag (and vLLM's `/health` is 200), and with
+`--register-as-fallback` swaps mindX's fallback model to it. `--dry-run` prints the exact argv and
+runs nothing; `--stop` sends SIGTERM to the recorded server's process group and verifies it is
+gone. On a GPU-less host the CPU backends are used (bfloat16, `VLLM_CPU_KVCACHE_SPACE`,
+SGLang `--device cpu`); a quantized checkpoint or `tensor_parallel > 1` is refused there. Exit
+codes: 1 checkpoint missing · 2 refused (server missing, GPU needed, already running) · 3 merge
+failed / exited early / error · 4 not ready in time (left running). Full page: [serve.md](serve.md).
 
-The chat-template parsers map per `serve.reasoning_parser` (`qwen3` for Qwen3,
-`deepseek_r1` for DeepSeek-style) and `serve.tool_call_parser` (`hermes`,
-`qwen3_coder`).
+### `serve --to ollama` / `--to bankml`
+
+```
+mindxtrain serve <config.yaml> --to bankml [--tag NAME] [--checkpoint DIR] [--bankml-bin PATH] [--bankml-convert] [--register-as-fallback]
+```
+
+`--to ollama` merges the LoRA and runs `ollama create`. `--to bankml` does the same through
+[bankml](https://github.com/cryptoAGI/bankml) (`bankml create`, 0.3.5+) and refuses what bankml does
+not reproduce — see [bankml.md](bankml.md). Exit codes for `--to bankml`: 1 checkpoint missing ·
+2 refused (quantized config, architecture, Modelfile subset, bankml missing or too old) ·
+3 merge or create failed.
+
+## `imprint-bankml` — receipt-auditable imprint probes
+
+```
+mindxtrain imprint-bankml <config.yaml> --before TAG --after TAG [--n 5] [--seed 0] [--num-predict 48] [--system TEXT] [--base-url URL]
+```
+
+Greedy, seeded, unpenalised probes through `bankml serve --native`, scored with `score_imprint`;
+every utterance carries bankml's receipt. **Not comparable** with `imprint` (repetition penalty
+1.3). Exit 3 on a bankml refusal or error, 4 when no imprint is detected.
 
 ## `publish` — push to HF + Lighthouse + register
 
@@ -203,6 +230,8 @@ $ uv run mindxtrain receipt out/runs/<run_id>/manifest.json --config run.yaml
 | `dataset prep`    | `mindxtrain.cli.main.dataset_prep` + `mindxtrain.data.{curate,filter,tokenize,pack}`  |
 | `eval`            | `mindxtrain.cli.main.eval_` + `mindxtrain.eval.harness.run_lm_eval`                   |
 | `quantize`        | `mindxtrain.cli.main.quantize` + `mindxtrain.deploy.quark.quark_fp8`                  |
-| `serve`           | `mindxtrain.cli.main.serve` + `mindxtrain.deploy.vllm_launcher.build_vllm_command`    |
+| `serve --to vllm\|sglang` | `mindxtrain.cli.main._serve_openai_server` + `mindxtrain.deploy.openai_server_push.launch_openai_server` |
+| `serve --to bankml` | `mindxtrain.cli.main._serve_bankml` + `mindxtrain.deploy.bankml_push.push_to_bankml` |
+| `imprint-bankml`  | `mindxtrain.cli.main.imprint_bankml` + `mindxtrain.eval.imprint_bankml.imprint_via_bankml` |
 | `publish`         | `mindxtrain.cli.main.publish` + `mindxtrain.storage.{hf_hub,lighthouse}` + `mindxtrain.deploy.api_client` |
 | `receipt`         | `mindxtrain.cli.main.receipt` + `mindxtrain.provenance.verify.verify_receipt`         |

docs/development.md

@@ -198,8 +198,10 @@ RTX is the intended consumer GPU.
    decorated `@register_backend("<name>")`.
 2. Side-effect import it from `mindxtrain/models/registry.py` so registration
    runs on package import.
-3. Add a runtime branch in `mindxtrain/operator/app.py::chat_completions` for
-   the env-var-driven kwargs.
+3. Add its env-var-driven kwargs to `mindxtrain/operator/app.py::backend_kwargs`
+   (the operator route and the Coach chat stream both read it), and a probe to
+   `backend_reachable` / `backend_first_model` if it has one. Example:
+   `operator/backends/bankml.py` ([bankml.md](bankml.md)).
 
 ## Adding a new training method
 

docs/serve.md

@@ -0,0 +1,89 @@
+# Serving on vLLM and SGLang
+
+`mindxtrain serve <config.yaml> --to vllm|sglang` launches an OpenAI-compatible server on the
+trained checkpoint, waits until it answers, and can hand it to mindX as the fallback model. It sits
+beside `--to ollama` (merge + `ollama create`) and `--to bankml` (merge + `bankml create`, see
+[bankml.md](bankml.md)). Code: `mindxtrain/deploy/openai_server_push.py`.
+
+vLLM and SGLang are reached **only** as a subprocess and over HTTP — neither is imported by
+mindXtrain (clean-room policy). SGLang's presence is checked with `importlib.util.find_spec`,
+which does not import it.
+
+```
+mindxtrain serve run.yaml --to vllm   [--tag NAME] [--checkpoint DIR] [--merge] [--host 127.0.0.1]
+                                      [--port N] [--dtype auto] [--server-bin PATH]
+                                      [--server-arg ARG ...] [--ready-timeout 600]
+                                      [--cpu-kvcache-gib 4] [--register-as-fallback]
+mindxtrain serve run.yaml --to sglang ...same options...
+mindxtrain serve run.yaml --to vllm --dry-run      # print the argv (and env); run nothing
+mindxtrain serve run.yaml --to vllm --stop         # SIGTERM the recorded server, verify it is gone
+```
+
+## What runs
+
+1. **Checkpoint.** `--checkpoint`, else `out/runs/<run>/quantized/` when the config quantizes and
+   that directory exists, else `out/runs/<run>/checkpoint/`.
+2. **LoRA, native or merged.** A directory with `adapter_config.json` is a LoRA. By default it is
+   served **natively over the base** (no merge):
+   - vLLM: `--enable-lora --lora-modules <tag>=<adapter> --max-lora-rank R` (R = the adapter's `r`
+     rounded up to a vLLM choice: 1, 8, 16, 32, 64, 128, 256, 320, 512). The base is served as
+     `<tag>-base`; the adapter is listed on `/v1/models` as `<tag>`, which is the client's `model`.
+   - SGLang: `--enable-lora --lora-paths <tag>=<adapter> --max-lora-rank r`. The base is served as
+     `<tag>-base`; a client selects the adapter with `model: "<tag>-base:<tag>"`.
+
+   `--merge` folds the adapter in first (`merge_lora_adapter`, needs `uv sync --extra ml`) and
+   serves the merged directory as `<tag>`.
+3. **argv.** vLLM: `vllm serve <model> --served-model-name … --host --port --dtype
+   --max-model-len <serve.max_model_len> --tensor-parallel-size <serve.tensor_parallel>
+   [--quantization fp8|mxfp4|gptq]`. SGLang: `python -m sglang.launch_server --model-path …
+   --served-model-name … --host --port --dtype --context-length <serve.max_model_len>
+   --tp <serve.tensor_parallel>` plus `--device cpu` on CPU or `--mem-fraction-static 0.85` on GPU.
+   Anything else goes through `--server-arg`, verbatim (e.g. `--server-arg=--enforce-eager`).
+4. **Detached.** The server runs in its own session; stdout+stderr go to
+   `out/runs/<run>/serve/<to>/server.log`, its pid to `server.pid`, and the argv/env/time to
+   `launch.json`. It outlives the CLI.
+5. **Ready.** `/v1/models` is polled (and, for vLLM, `/health` must be 200) until the expected
+   name is listed, the process exits, or `--ready-timeout` passes. On a timeout the server is
+   **left running** (big models load slowly) — watch the log or `--stop` it.
+6. **mindX.** With `--register-as-fallback`, mindX's fallback model is swapped to
+   `{provider: "vllm"|"sglang", model: <client model>}` (best-effort, as for Ollama).
+
+## CPU and GPU
+
+With no `/dev/kfd` (ROCm) or `/dev/nvidia0` the CPU backends are used: `--dtype auto` becomes
+`bfloat16` (the vLLM CPU guide's recommendation; float16 is unstable or unsupported on CPU), vLLM
+gets `VLLM_CPU_KVCACHE_SPACE=<--cpu-kvcache-gib>` unless the environment already sets it (other
+CPU knobs such as `VLLM_CPU_OMP_THREADS_BIND` pass through from your env), and SGLang gets
+`--device cpu`. A config that needs a GPU is **refused** on such a host, with the reason: an FP8 /
+MXFP4 / GPTQ checkpoint, or `serve.tensor_parallel > 1`. Neither upstream documents LoRA on CPU;
+if your build rejects it, use `--merge`.
+
+## Installing the servers
+
+- vLLM: `uv sync --extra serve` (GPU / ROCm). CPU-only per the
+  [vLLM CPU guide](https://docs.vllm.ai/en/latest/getting_started/installation/cpu.html), e.g.
+  `uv pip install vllm --torch-backend cpu`. Or point `--server-bin` at a `vllm` elsewhere.
+- SGLang is not a mindXtrain extra: install it into the interpreter that will run it
+  (`uv pip install sglang`, [docs.sglang.io](https://docs.sglang.io)) and pass that interpreter as
+  `--server-bin` if it is not this one.
+
+## Exit codes
+
+`0` ready / dry run / stopped / not running · `1` checkpoint missing · `2` refused: server missing,
+GPU needed, already running · `3` merge failed, server exited early, stop failed, error ·
+`4` not ready before `--ready-timeout` (still running).
+
+## Where each flag comes from
+
+vLLM: the [`vllm serve` CLI reference](https://docs.vllm.ai/en/latest/cli/serve.html)
+(`--served-model-name`, `--host`, `--port`, `--dtype`, `--max-model-len`, `--tensor-parallel-size`,
+`--quantization`, `--enable-lora`, `--lora-modules`, `--max-lora-rank` and its choices), the
+[LoRA page](https://docs.vllm.ai/en/latest/features/lora.html) (`name=path`, adapters on
+`/v1/models`), the [CPU installation page](https://docs.vllm.ai/en/latest/getting_started/installation/cpu.html)
+(`VLLM_CPU_KVCACHE_SPACE`, bfloat16), and [online serving](https://docs.vllm.ai/en/latest/serving/online_serving/)
+(`/health`, `/v1/models`). SGLang: [Server Arguments](https://docs.sglang.io/advanced_features/server_arguments.html)
+(`--model-path`, `--served-model-name`, `--host`, `--port`, `--dtype`, `--context-length`,
+`--device`, `--tp`, `--mem-fraction-static`, `--enable-lora`, `--lora-paths`, `--max-lora-rank`)
+and the [LoRA page](https://docs.sglang.io/advanced_features/lora.html) (`base:adapter` model
+syntax). Checked against the docs current on 2026-10-02 (`uv.lock` resolves vLLM 0.20.1); no
+server was installed or launched to write this.

llm.txt

@@ -81,6 +81,18 @@ uv run python -m mindxtrain.ui.app    # the UI at :7862
 comparable. The floor is calibrated against a **null** (an untrained random-init adapter), not chosen.
 A run that fails the gate is recorded as failed and is not served. *That refusal is the product.*
 
+`mindxtrain imprint-bankml` is a **second instrument**, not the gate: probes through
+[bankml](https://github.com/cryptoAGI/bankml) (`bankml serve --native`, token-identical to llama.cpp
+b11192) at temperature 0, a fixed seed and **no penalties**, a receipt (model sha256) per utterance.
+Its scores are tagged `<scorer>/bankml-greedy` and are **not comparable** with the gate's. Never mix
+them. Backends the operator knows: `openai_compat`, `ollama`, `vllm`, `bankml` — see `docs/bankml.md`;
+a bankml HTTP 400 is a `BankmlRefusal` with its reason, and is never retried with altered parameters.
+
+Serve targets: `mindxtrain serve run.yaml --to ollama|bankml|vllm|sglang`. `vllm` / `sglang` launch the
+OpenAI-compatible server detached (LoRA native over the base by default, `--merge` to merge; log + pid
+under `out/runs/<run>/serve/<to>/`), return once `/v1/models` lists the tag, `--dry-run` prints the
+argv, `--stop` ends it; GPU-only configs are refused on a CPU host — see `docs/serve.md`.
+
 ## The teaching artifacts
 
 Published beside the weights at `PYTHAI/mindXtrain39`, and mirrored in mindX at

mindxtrain/cli/main.py

@@ -11,6 +11,7 @@ from mindxtrain import __version__
 from mindxtrain.autotune.benchmark import run_autotune
 from mindxtrain.autotune.plan import AutotunePlan
 from mindxtrain.config.loader import list_recipes, load_config, render_recipe
+from mindxtrain.config.schema import XTrainConfig
 
 app = typer.Typer(
     name="mindxtrain",
@@ -301,28 +302,243 @@ def quantize(
     console.print(f"[green]quantized:[/green] {path}")
 
 
+def _serve_openai_server(
+    cfg: XTrainConfig,
+    flavour: str,
+    checkpoint: Path | None,
+    *,
+    tag: str | None,
+    stop: bool,
+    dry_run: bool,
+    merge: bool,
+    host: str,
+    port: int | None,
+    dtype: str,
+    server_bin: str | None,
+    server_args: list[str],
+    ready_timeout: float,
+    cpu_kvcache_gib: int,
+    register_as_fallback: bool,
+    mindx_base_url: str | None,
+) -> None:
+    """`serve --to vllm|sglang`: launch detached, wait for /v1/models, or `--stop` it."""
+    from mindxtrain.deploy.openai_server_push import (
+        VLLM_QUANTIZATION,
+        launch_openai_server,
+        stop_openai_server,
+    )
+
+    fl = "vllm" if flavour == "vllm" else "sglang"
+    run_dir = Path("./out/runs") / cfg.meta.run_name
+    if stop:
+        res = stop_openai_server(fl, run_dir)
+        colour = "green" if res.ok else "red"
+        console.print(f"[{colour}]{fl} {res.status}[/{colour}] "
+                      f"{('pid ' + str(res.pid)) if res.pid else ''} {res.reason}".rstrip())
+        raise typer.Exit(code=0 if res.ok else 3)
+
+    quantized = run_dir / "quantized"
+    if checkpoint is None:
+        use_quant = (cfg.quantize.enabled and cfg.quantize.scheme != "none"
+                     and quantized.exists())
+        checkpoint = quantized if use_quant else run_dir / "checkpoint"
+    if not checkpoint.exists():
+        console.print(f"[red]checkpoint not found:[/red] {checkpoint}")
+        raise typer.Exit(code=1)
+    is_adapter = (checkpoint / "adapter_config.json").exists()
+    is_quant = checkpoint.resolve() == quantized.resolve() or checkpoint.name == "quantized"
+    quant = VLLM_QUANTIZATION.get(cfg.quantize.scheme) if is_quant else None
+
+    result = launch_openai_server(
+        fl,
+        base_model=cfg.model.name,
+        tag=tag or cfg.meta.run_name,
+        run_dir=run_dir,
+        adapter_dir=checkpoint if is_adapter else None,
+        model_dir=None if is_adapter else checkpoint,
+        merge=merge,
+        host=host,
+        port=port or cfg.serve.port,
+        dtype=dtype,  # type: ignore[arg-type]
+        max_model_len=cfg.serve.max_model_len,
+        tensor_parallel=cfg.serve.tensor_parallel,
+        quantization=quant,
+        cpu_kvcache_gib=cpu_kvcache_gib,
+        extra_args=tuple(server_args),
+        server_bin=server_bin,
+        dry_run=dry_run,
+        ready_timeout_s=ready_timeout,
+        register_with_mindx=register_as_fallback,
+        mindx_base_url=mindx_base_url,
+        sink=lambda line: console.print(line, markup=False, highlight=False),
+    )
+    if result.status == "dry_run":
+        console.print(f"[green]{fl} cmd:[/green] {' '.join(result.argv)}",
+                      highlight=False, soft_wrap=True)
+        return
+    if not result.ok:
+        console.print(f"[red]serve --to {fl} {result.status}:[/red] {result.reason}",
+                      highlight=False, soft_wrap=True)
+        refused = ("refused", "missing", "no_gpu", "already_running")
+        raise typer.Exit(code=2 if result.status in refused
+                         else 4 if result.status == "timeout" else 3)
+    console.print(f"[green]{fl} ready:[/green] model {result.client_model!r} at "
+                  f"{result.base_url}/v1 (pid {result.pid}, log {result.log_path})",
+                  highlight=False)
+    console.print(f"stop it: mindxtrain serve <config.yaml> --to {fl} --stop")
+    if result.mindx_fallback_swap:
+        console.print(
+            f"[green]mindX fallback swapped:[/green] "
+            f"{result.mindx_fallback_swap.get('previous', '?')} -> "
+            f"{result.mindx_fallback_swap.get('current', '?')}",
+        )
+
+
+def _serve_bankml(
+    cfg: XTrainConfig,
+    checkpoint: Path | None,
+    *,
+    tag: str | None,
+    bankml_bin: str | None,
+    convert: bool,
+    register_as_fallback: bool,
+    mindx_base_url: str | None,
+) -> None:
+    """`serve --to bankml`: refuse what bankml cannot serve, else merge + `bankml create`.
+
+    Exit codes: 1 checkpoint missing · 2 refused (quantized config, architecture, Modelfile
+    subset, bankml missing or too old) · 3 merge / create failed.
+    """
+    from mindxtrain.deploy.bankml_push import base_family_refusal, push_to_bankml
+
+    quant = cfg.quantize
+    if quant.enabled and quant.scheme != "none":
+        console.print(
+            f"[red]bankml refuses quantize.scheme={quant.scheme}:[/red] bankml serves the merged "
+            "weights as GGUF F16 (and pinned Q1_0 / Q2_0_g64); it does not reproduce FP8, MXFP4, "
+            "GPTQ, Q8_0 or Q4_K. Set `quantize.scheme: none` (or `enabled: false`), or serve "
+            "with --to vllm.",
+        )
+        raise typer.Exit(code=2)
+    base_model = cfg.model.name
+    family = base_family_refusal(base_model)
+    if family:
+        console.print(f"[red]bankml refuses:[/red] {family}")
+        raise typer.Exit(code=2)
+
+    run_name = cfg.meta.run_name
+    ckpt = checkpoint or Path("./out/runs") / run_name / "checkpoint"
+    if not ckpt.exists():
+        console.print(f"[red]checkpoint not found:[/red] {ckpt}")
+        raise typer.Exit(code=1)
+    is_adapter = (ckpt / "adapter_config.json").exists() or not (ckpt / "config.json").exists()
+    result = push_to_bankml(
+        base_model,
+        tag or run_name,
+        adapter_dir=ckpt if is_adapter else None,
+        merged_dir=None if is_adapter else ckpt,
+        bankml_bin=bankml_bin,
+        convert=convert,
+        register_with_mindx=register_as_fallback,
+        mindx_base_url=mindx_base_url,
+        sink=lambda line: console.print(line, markup=False, highlight=False),
+    )
+    if not result.ok:
+        console.print(f"[red]push-to-bankml {result.status}:[/red] {result.reason}")
+        for r in result.refusals:
+            console.print(f"  - {r}", markup=False)
+        refused = ("refused", "bankml_missing", "bankml_too_old")
+        raise typer.Exit(code=2 if result.status in refused else 3)
+    console.print(
+        f"[green]pushed:[/green] {result.tag} on bankml {result.bankml_version} "
+        f"(model sha256 {result.model_sha256 or '?'}, Modelfile: {result.modelfile})",
+    )
+    console.print("serve it: bankml serve <pinned.gguf> --fork <FORK.json> --native --registry")
+    if result.mindx_fallback_swap:
+        console.print(
+            f"[green]mindX fallback swapped:[/green] "
+            f"{result.mindx_fallback_swap.get('previous', '?')} -> "
+            f"{result.mindx_fallback_swap.get('current', '?')}",
+        )
+
+
 @app.command()
 def serve(
     config: Path = typer.Argument(...),
     checkpoint: Path = typer.Option(None, "--checkpoint", "-c"),
     to: str = typer.Option(
         "vllm", "--to",
-        help="Serve target: vllm (default, builds vllm-rocm launch cmd), "
-             "sglang (builds sglang-rocm launch cmd), or "
-             "ollama (merges LoRA + calls `ollama create`).",
+        help="Serve target: vllm (default; launches `vllm serve` detached and waits for "
+             "/v1/models), sglang (launches `python -m sglang.launch_server` the same way), "
+             "ollama (merges LoRA + calls `ollama create`), or "
+             "bankml (merges LoRA + calls `bankml create`; the verified CPU engine, "
+             "https://github.com/cryptoAGI/bankml).",
     ),
     tag: str = typer.Option(
         None, "--tag",
-        help="Ollama tag for `--to ollama`. Defaults to run_name when omitted.",
+        help="Model tag (Ollama/bankml tag; vLLM/SGLang served or LoRA name). "
+             "Defaults to run_name when omitted.",
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run",
+        help="`--to vllm|sglang`: print the exact launch argv (and env) and do nothing.",
+    ),
+    stop: bool = typer.Option(
+        False, "--stop",
+        help="`--to vllm|sglang`: SIGTERM the server recorded in "
+             "out/runs/<run>/serve/<to>/server.pid and verify it is gone.",
+    ),
+    merge: bool = typer.Option(
+        False, "--merge",
+        help="`--to vllm|sglang`: merge the LoRA into the base first (needs `uv sync --extra ml`) "
+             "instead of serving base + adapter natively (the default; no merge).",
+    ),
+    host: str = typer.Option(
+        "127.0.0.1", "--host", help="`--to vllm|sglang`: bind address (loopback by default).",
+    ),
+    port: int = typer.Option(
+        None, "--port", help="`--to vllm|sglang`: port; defaults to serve.port in the config.",
+    ),
+    dtype: str = typer.Option(
+        "auto", "--dtype",
+        help="`--to vllm|sglang`: auto|half|float16|bfloat16|float|float32. "
+             "auto becomes bfloat16 on a GPU-less host (the CPU backends' recommendation).",
+    ),
+    server_bin: str = typer.Option(
+        None, "--server-bin",
+        help="`--to vllm`: the vllm executable; `--to sglang`: a Python interpreter with "
+             "sglang installed. Defaults: `vllm` on PATH / this interpreter.",
+    ),
+    server_arg: list[str] = typer.Option(
+        None, "--server-arg",
+        help="`--to vllm|sglang`: an extra argument passed verbatim to the server "
+             "(repeatable), e.g. --server-arg=--enforce-eager.",
+    ),
+    ready_timeout: float = typer.Option(
+        600.0, "--ready-timeout",
+        help="`--to vllm|sglang`: seconds to wait for /v1/models to list the tag.",
+    ),
+    cpu_kvcache_gib: int = typer.Option(
+        4, "--cpu-kvcache-gib",
+        help="`--to vllm` on CPU: VLLM_CPU_KVCACHE_SPACE in GiB, unless already set in the env.",
     ),
     ollama_bin: str = typer.Option(
         None, "--ollama-bin",
         help="Override the ollama binary path (defaults to PATH lookup).",
     ),
+    bankml_bin: str = typer.Option(
+        None, "--bankml-bin",
+        help="Override the bankml binary path for `--to bankml` (defaults to PATH lookup).",
+    ),
+    bankml_convert: bool = typer.Option(
+        False, "--bankml-convert",
+        help="With `--to bankml`: run `bankml convert` (GGUF F16 + FORK.json pin) before "
+             "`bankml create`, instead of letting create convert the merged directory.",
+    ),
     register_as_fallback: bool = typer.Option(
         False, "--register-as-fallback",
         help=(
-            "After --to ollama succeeds, PATCH the new tag into mindX as "
+            "After --to ollama|bankml|vllm|sglang succeeds, PATCH the new tag into mindX as "
             "the local-fallback model (PATCH /v1/config/fallback-model). "
             "Best-effort — a failure logs but does NOT fail the push."
         ),
@@ -338,16 +554,34 @@ def serve(
 ) -> None:
     """Serve the trained checkpoint locally.
 
-    `--to vllm` (default) prints a vllm-rocm launch command against the
-    quantized checkpoint — wire it into your orchestrator.
+    `--to vllm` (default) / `--to sglang` launch an OpenAI-compatible server
+    detached (log + pid under out/runs/<run>/serve/<to>/), serving the LoRA
+    natively over the base (or the merged weights with `--merge`, or the
+    quantized checkpoint when one exists), wait until `/v1/models` lists the
+    tag, and optionally swap mindX's fallback model to it. `--dry-run` prints
+    the argv; `--stop` ends the server. A GPU-less host uses the CPU backends;
+    a config that needs a GPU is refused with the reason.
 
     `--to ollama` runs the local-learning loop: merges the LoRA adapter
     into the base weights, writes an ollama Modelfile, and calls
     `ollama create <tag>` so the trained model is immediately available
     on the loopback (the same backend Coach probes for its chat card).
+
+    `--to bankml` does the same through bankml (`bankml create`, 0.3.5+):
+    the merged weights converted to GGUF F16 byte-identically to llama.cpp,
+    served by `bankml serve --native` with a receipt on every answer. It
+    refuses quantized configs (bankml serves F16 conversions, not FP8 /
+    MXFP4 / GPTQ / Q8_0 / Q4_K) and non-Llama architectures, with the reason.
     """
     cfg = load_config(config)
 
+    if to == "bankml":
+        _serve_bankml(
+            cfg, checkpoint, tag=tag, bankml_bin=bankml_bin, convert=bankml_convert,
+            register_as_fallback=register_as_fallback, mindx_base_url=mindx_base_url,
+        )
+        return
+
     if to == "ollama":
         from mindxtrain.deploy.ollama_push import push_to_ollama
 
@@ -388,23 +622,12 @@ def serve(
         console.print(f"[red]unknown serve target:[/red] {to}")
         raise typer.Exit(code=2)
 
-    ckpt = checkpoint or Path("./out/runs") / cfg.meta.run_name / "quantized"
-    if not ckpt.exists():
-        console.print(f"[red]quantized checkpoint not found:[/red] {ckpt}")
-        raise typer.Exit(code=1)
-
-    if to == "sglang":
-        from mindxtrain.deploy.sglang_rocm import build_sglang_command
-
-        cmd = build_sglang_command(cfg.serve, ckpt)
-        console.print(f"[green]sglang cmd:[/green] {' '.join(cmd)}")
-        return
-
-    from mindxtrain.deploy.vllm_launcher import build_vllm_command
-
-    cmd = build_vllm_command(cfg.serve, ckpt, cfg.quantize)
-    console.print(f"[green]vllm cmd:[/green] {' '.join(cmd)}")
-    # Caller can pipe the cmd into their orchestrator; we don't exec by default.
+    _serve_openai_server(
+        cfg, to, checkpoint, tag=tag, stop=stop, dry_run=dry_run, merge=merge, host=host,
+        port=port, dtype=dtype, server_bin=server_bin, server_args=server_arg or [],
+        ready_timeout=ready_timeout, cpu_kvcache_gib=cpu_kvcache_gib,
+        register_as_fallback=register_as_fallback, mindx_base_url=mindx_base_url,
+    )
 
 
 # ---- dataset prep ---------------------------------------------------------
@@ -600,34 +823,12 @@ def receipt(
         raise typer.Exit(code=2)
 
 
-@app.command()
-def imprint(
-    config: Path = typer.Argument(..., help="recipe whose checkpoint to measure"),
-    out: Path = typer.Option(Path("./out/runs"), "--out", "-o"),
-    max_inquiries: int = typer.Option(5, "--n", help="number of recall probes"),
-    trigger_dream: bool = typer.Option(
-        False, "--trigger-dream",
-        help="hand the imprinted actor to mindX's machine.dream 8hr cycle",
-    ),
-) -> None:
-    """Measure a persona imprint: recall before vs after training.
-
-    Poses the script's own user-turns back to the actor, comparing the base
-    model (before) and the trained adapter (after) against the script's
-    assistant voice. Prints an ImprintReport; exit 4 if no imprint was detected.
-    """
+def _script_probes(cfg: XTrainConfig, max_inquiries: int) -> tuple[list[str], list[str]]:
+    """Inquiries (the script's user-turns, at most `max_inquiries`) and the baseline voice (its
+    assistant-turns) from the local script the actor trained on; default probes otherwise."""
     import json as _json
 
-    cfg = load_config(config)
-    run_dir = (out / cfg.meta.run_name) if out.name == "runs" else out
-    adapter_dir = run_dir / "checkpoint"
-    if not adapter_dir.exists():
-        console.print(f"[red]no checkpoint to measure:[/red] {adapter_dir}")
-        raise typer.Exit(code=1)
-
-    # Build inquiries (user-turns) + baseline voice (assistant-turns) from the
-    # local script the actor trained on. Falls back to default probes.
-    from mindxtrain.eval.imprint import default_inquiries, probe_recall, score_imprint
+    from mindxtrain.eval.imprint import default_inquiries
 
     inquiries: list[str] = []
     baseline: list[str] = []
@@ -652,6 +853,37 @@ def imprint(
                     baseline.append(a)
     if not inquiries:
         inquiries = default_inquiries(cfg.meta.project)[:max_inquiries]
+    return inquiries, baseline
+
+
+@app.command()
+def imprint(
+    config: Path = typer.Argument(..., help="recipe whose checkpoint to measure"),
+    out: Path = typer.Option(Path("./out/runs"), "--out", "-o"),
+    max_inquiries: int = typer.Option(5, "--n", help="number of recall probes"),
+    trigger_dream: bool = typer.Option(
+        False, "--trigger-dream",
+        help="hand the imprinted actor to mindX's machine.dream 8hr cycle",
+    ),
+) -> None:
+    """Measure a persona imprint: recall before vs after training.
+
+    Poses the script's own user-turns back to the actor, comparing the base
+    model (before) and the trained adapter (after) against the script's
+    assistant voice. Prints an ImprintReport; exit 4 if no imprint was detected.
+    """
+    cfg = load_config(config)
+    run_dir = (out / cfg.meta.run_name) if out.name == "runs" else out
+    adapter_dir = run_dir / "checkpoint"
+    if not adapter_dir.exists():
+        console.print(f"[red]no checkpoint to measure:[/red] {adapter_dir}")
+        raise typer.Exit(code=1)
+
+    # Build inquiries (user-turns) + baseline voice (assistant-turns) from the
+    # local script the actor trained on. Falls back to default probes.
+    from mindxtrain.eval.imprint import probe_recall, score_imprint
+
+    inquiries, baseline = _script_probes(cfg, max_inquiries)
 
     console.print(f"[cyan]probing {len(inquiries)} inquiries (before/after)…[/cyan]")
     try:
@@ -681,6 +913,51 @@ def imprint(
         raise typer.Exit(code=4)
 
 
+@app.command("imprint-bankml")
+def imprint_bankml(
+    config: Path = typer.Argument(..., help="recipe whose script supplies inquiries + voice"),
+    before: str = typer.Option(..., "--before", help="bankml tag of the base actor"),
+    after: str = typer.Option(..., "--after", help="bankml tag of the imprinted actor"),
+    max_inquiries: int = typer.Option(5, "--n", help="number of recall probes"),
+    seed: int = typer.Option(0, "--seed", help="sampler seed (recorded; greedy at temperature 0)"),
+    num_predict: int = typer.Option(48, "--num-predict", help="tokens per utterance"),
+    system: str = typer.Option("", "--system", help="system turn prepended to every probe"),
+    base_url: str = typer.Option(
+        None, "--base-url",
+        help="bankml server (default MINDXTRAIN_BANKML_BASE_URL or http://127.0.0.1:18093/v1)",
+    ),
+) -> None:
+    """Measure an imprint through bankml: reproducible, receipt-auditable CPU probes.
+
+    Poses the script's user-turns to two tags served by `bankml serve --native` (temperature 0,
+    fixed seed, no penalties) and scores them with the same `score_imprint`. Every utterance
+    carries bankml's receipt (model / request / response sha256). NOT comparable with
+    `mindxtrain imprint` (the canonical gate decodes with repetition_penalty 1.3); the report
+    says so. Exit 3 if bankml refuses or errs, 4 if no imprint was detected.
+    """
+    import httpx
+
+    from mindxtrain.eval.imprint_bankml import imprint_via_bankml
+    from mindxtrain.operator.backends.bankml import BankmlError
+
+    cfg = load_config(config)
+    inquiries, baseline = _script_probes(cfg, max_inquiries)
+    console.print(f"[cyan]probing {len(inquiries)} inquiries through bankml (before/after)…[/cyan]")
+    try:
+        result = imprint_via_bankml(
+            before, after, inquiries, baseline, system=system or None, seed=seed,
+            num_predict=num_predict, base_url=base_url,
+        )
+    except (BankmlError, httpx.HTTPError) as exc:
+        console.print(f"[red]bankml imprint probe failed:[/red] {exc}")
+        raise typer.Exit(code=3) from exc
+    console.print_json(data=result.model_dump())
+    console.print(f"[yellow]{result.note}[/yellow]")
+    if not result.report.imprinted:
+        console.print("[yellow]no imprint detected (delta<=0 or no shift)[/yellow]")
+        raise typer.Exit(code=4)
+
+
 # ---- research (autoresearch search over one editable file) --------------
 
 

mindxtrain/deploy/bankml_push.py

@@ -0,0 +1,439 @@
+"""Serve a trained model through bankml — the verified CPU engine.
+
+`push_to_bankml` is the bankml twin of `ollama_push.push_to_ollama`: merge the LoRA (or take an
+already-merged directory) → write a Modelfile that bankml can reproduce → `bankml create`, so the
+tag answers on `bankml serve --native` (OpenAI `/v1` + Ollama `/api`, a receipt on every answer).
+
+bankml (https://github.com/cryptoAGI/bankml) is reached **only** as a CLI subprocess here and as
+HTTP in `operator/backends/bankml.py`; none of its code is vendored (clean-room policy).
+
+What bankml takes, and what this module therefore refuses *before* running anything (it never
+drops an instruction silently — a dropped PARAMETER would serve a model that answers differently
+from the one described):
+
+- **Taken:** `FROM` (the merged safetensors directory, which `bankml create` converts to GGUF F16
+  byte-identically to llama.cpp b11192, or a GGUF `bankml convert` already pinned), `SYSTEM`,
+  `MESSAGE`, `LICENSE`, `REQUIRES`, `PARAMETER` temperature / top_k / top_p / min_p / seed /
+  num_ctx / num_predict, and `stop`.
+- **Refused:** `ADAPTER` (merge first — this module does it for you given `adapter_dir`), a
+  `TEMPLATE` other than the base's own, the penalties (repeat / presence / frequency,
+  repeat_last_n), mirostat*, typical_p, resource options (num_gpu, num_thread, num_batch,
+  num_keep, draft_num_predict), and any architecture other than Llama (SmolLM2 = mindx-genN):
+  bankml converts Llama safetensors only; Qwen3 it serves only as a pinned Q1_0/Q2_0_g64 GGUF.
+
+`bankml create` / `bankml convert` arrive in bankml 0.3.5. An older binary is detected from
+`bankml --help` (the verbs it lists) and reported as `status="bankml_too_old"`, never raised.
+
+Every public function returns a result; nothing here raises past `BankmlPushResult`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+from mindxtrain.deploy.modelfile import ModelfileSpec, render_modelfile
+
+BANKML_URL = "https://github.com/cryptoAGI/bankml"
+
+# PARAMETERs bankml reproduces token-for-token (plus `stop`, carried on ModelfileSpec.stop).
+BANKML_PARAMS: frozenset[str] = frozenset(
+    {"temperature", "top_k", "top_p", "min_p", "seed", "num_ctx", "num_predict"},
+)
+
+_PENALTY = frozenset({"repeat_penalty", "presence_penalty", "frequency_penalty", "repeat_last_n"})
+_MIROSTAT = frozenset({"mirostat", "mirostat_tau", "mirostat_eta"})
+_RESOURCE = frozenset({"num_gpu", "num_thread", "num_batch", "num_keep", "draft_num_predict"})
+
+# Architectures `bankml convert` / `bankml create FROM <dir>` accept (config.json `architectures`).
+BANKML_CONVERT_ARCHS: frozenset[str] = frozenset({"LlamaForCausalLM"})
+
+_NAME = re.compile(r"^[a-z0-9_][a-z0-9._-]{0,127}$")
+_SHA = r"[0-9a-f]{64}"
+
+PushStatus = Literal[
+    "created", "refused", "bankml_missing", "bankml_too_old", "merge_failed", "failed", "error",
+]
+
+
+def _param_refusal(name: str) -> str:
+    if name in _PENALTY:
+        return (f"PARAMETER {name}: penalties are not reproduced by bankml's verified sampler "
+                "(llama.cpp's top-k, top-p, min-p and temperature are); leave it out")
+    if name in _MIROSTAT:
+        return f"PARAMETER {name}: mirostat is not reproduced by bankml; leave it out"
+    if name == "typical_p":
+        return "PARAMETER typical_p: locally-typical sampling is not reproduced by bankml"
+    if name in _RESOURCE:
+        return (f"PARAMETER {name}: a resource option is not part of a bankml model "
+                "(bankml's answer does not depend on threads, batch or GPU layers)")
+    if name == "stop":
+        return "PARAMETER stop: pass stop sequences as ModelfileSpec.stop, not in parameters"
+    return f"PARAMETER {name}: not a parameter bankml reproduces"
+
+
+# ---- capability probe -------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BankmlCapabilities:
+    """What the local `bankml` binary can do. `reason` is set when it cannot do what was asked."""
+
+    binary: str | None
+    version: str = ""
+    has_create: bool = False
+    has_convert: bool = False
+    reason: str = ""
+
+    @property
+    def found(self) -> bool:
+        return self.binary is not None
+
+
+def bankml_capabilities(bankml_bin: str | None = None, *, timeout_s: float = 30.0) -> BankmlCapabilities:
+    """Locate `bankml` and read its version and verbs (`bankml version`, `bankml --help`).
+
+    The verbs listed in the usage text are the truth — an unreleased build may still say 0.3.4
+    and already carry `create`. Never raises.
+    """
+    binary = bankml_bin or shutil.which("bankml")
+    if not binary:
+        return BankmlCapabilities(
+            binary=None,
+            reason=(f"`bankml` not found on PATH; install it from {BANKML_URL} "
+                    "(or pass --bankml-bin)"),
+        )
+    try:
+        ver = subprocess.run([binary, "version"], capture_output=True, text=True,
+                             timeout=timeout_s, check=False)
+        usage = subprocess.run([binary, "--help"], capture_output=True, text=True,
+                               timeout=timeout_s, check=False)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return BankmlCapabilities(binary=binary, reason=f"cannot run {binary}: {exc}")
+    m = re.search(r"bankml\s+(\d+\.\d+\.\d+\S*)", ver.stdout + ver.stderr)
+    text = usage.stdout + usage.stderr
+    return BankmlCapabilities(
+        binary=binary,
+        version=m.group(1) if m else "",
+        has_create="bankml create" in text,
+        has_convert="bankml convert" in text,
+    )
+
+
+# ---- the Modelfile subset ----------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BankmlSanitizeResult:
+    """`ok` → `spec` is exactly what bankml will reproduce; else `refusals` say why, one per line."""
+
+    spec: ModelfileSpec
+    refusals: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return not self.refusals
+
+
+def bankml_sanitize(spec: ModelfileSpec, *, base_template: str | None = None) -> BankmlSanitizeResult:
+    """Check a ModelfileSpec against the subset `bankml create` reproduces.
+
+    Refuses (and names) every instruction bankml would not honour; it never drops one, because a
+    silently dropped PARAMETER serves a model that answers differently from the spec. A
+    `TEMPLATE` passes only when it equals `base_template` (the base GGUF's own chat template).
+    """
+    refusals: list[str] = []
+    if spec.adapter:
+        refusals.append("ADAPTER: bankml does not merge a LoRA at create time; merge it first "
+                        "(push_to_bankml does, given adapter_dir) and FROM the merged directory")
+    if spec.template and spec.template != base_template:
+        refusals.append("TEMPLATE: bankml renders the base model's own chat template "
+                        "(byte-identical to llama.cpp); a different template is not reproduced — "
+                        "leave TEMPLATE out")
+    for name in sorted(spec.parameters):
+        if name not in BANKML_PARAMS:
+            refusals.append(_param_refusal(name))
+    for label, value in (("SYSTEM", spec.system), ("TEMPLATE", spec.template),
+                         ("LICENSE", spec.license)):
+        if '"""' in value:
+            refusals.append(f'{label}: contains """, which a Modelfile cannot quote')
+    for stop in spec.stop:
+        if '"' in stop or "\n" in stop:
+            refusals.append(f"stop {stop!r}: a quote or newline cannot be written as PARAMETER stop")
+    return BankmlSanitizeResult(spec=spec, refusals=tuple(refusals))
+
+
+def check_merged_arch(merged_dir: Path) -> str | None:
+    """None when `merged_dir/config.json` names an architecture bankml converts (or has none to
+    read — then bankml decides); else the refusal reason."""
+    try:
+        cfg = json.loads((merged_dir / "config.json").read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    archs = cfg.get("architectures") or []
+    if not archs or any(a in BANKML_CONVERT_ARCHS for a in archs):
+        return None
+    return (f"architecture {', '.join(map(str, archs))}: bankml converts Llama-architecture "
+            "safetensors only (SmolLM2 / mindx-genN); Qwen3 it serves only as a pinned "
+            "Q1_0/Q2_0_g64 GGUF — use `serve --to ollama` or `--to vllm` for this model")
+
+
+# Families mindXtrain trains that bankml cannot convert (checked by name before a merge is spent).
+_UNCONVERTIBLE_FAMILIES = ("qwen", "mistral", "phi", "gemma", "glm", "deepseek", "instella")
+
+
+def base_family_refusal(base_model: str) -> str | None:
+    """A cheap, name-based pre-check (before merging): None unless `base_model` names a family
+    bankml cannot convert. The merged `config.json` is still checked afterwards."""
+    low = base_model.lower()
+    if "smollm" in low or "llama" in low:
+        return None
+    hit = next((f for f in _UNCONVERTIBLE_FAMILIES if f in low), None)
+    if hit is None:
+        return None
+    return (f"base {base_model}: the {hit} family is not a Llama-architecture model bankml can "
+            "convert (bankml converts SmolLM2 / mindx-genN; Qwen3 only as a pinned "
+            "Q1_0/Q2_0_g64 GGUF) — use `serve --to ollama` or `--to vllm`")
+
+
+def bankml_registry_dir(registry_dir: Path | None = None) -> Path:
+    """bankml's registry (pins + derived models): `--registry`, else $BANKML_FORKS, else
+    ~/.local/share/bankml/forks — the same resolution `bankml create` uses."""
+    if registry_dir is not None:
+        return Path(registry_dir).expanduser()
+    env = os.environ.get("BANKML_FORKS")
+    if env:
+        return Path(env).expanduser()
+    return Path.home() / ".local" / "share" / "bankml" / "forks"
+
+
+# ---- push --------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class BankmlPushResult:
+    """Outcome of `push_to_bankml`. `status == "created"` is the only success."""
+
+    status: PushStatus
+    tag: str
+    reason: str = ""
+    refusals: tuple[str, ...] = ()
+    bankml_version: str = ""
+    merged_dir: Path | None = None
+    gguf: Path | None = None
+    modelfile: Path | None = None
+    model_sha256: str = ""
+    digest: str = ""
+    output: str = ""
+    mindx_fallback_swap: dict[str, str] | None = None
+    log: tuple[str, ...] = field(default=())
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "created"
+
+
+def _run(cmd: list[str], timeout_s: float) -> tuple[int, str, str]:
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_s, check=False)
+    return proc.returncode, proc.stdout or "", proc.stderr or ""
+
+
+def push_to_bankml(
+    base_model: str,
+    tag: str,
+    *,
+    adapter_dir: Path | None = None,
+    merged_dir: Path | None = None,
+    system: str | None = None,
+    params: dict[str, float | int | str] | None = None,
+    stop: list[str] | None = None,
+    bankml_bin: str | None = None,
+    convert: bool = False,
+    work_dir: Path | None = None,
+    registry_dir: Path | None = None,
+    register_with_mindx: bool = False,
+    mindx_base_url: str | None = None,
+    sink: Callable[[str], None] | None = None,
+    timeout_s: float = 1800.0,
+) -> BankmlPushResult:
+    """Merge (if given an adapter) → Modelfile (bankml subset) → `bankml create <tag>`.
+
+    Give exactly one of `adapter_dir` (a PEFT LoRA over `base_model`; merging needs
+    `uv sync --extra ml`) or `merged_dir` (an already-merged HF safetensors directory).
+
+    `convert=False` (default) writes `FROM <merged dir>` and lets `bankml create` convert and pin
+    it. `convert=True` runs `bankml convert` first (GGUF + FORK.json into the registry) and
+    writes `FROM <gguf>` — the explicit, inspectable two-step.
+
+    The model sha256 recorded is the one bankml prints for the base it pinned and verified.
+    With `register_with_mindx`, mindX's fallback model is swapped to `{provider: "bankml",
+    model: tag}` (best-effort; a failure is logged, the push still stands).
+    """
+    lines: list[str] = []
+
+    def emit(line: str) -> None:
+        lines.append(line)
+        if sink:
+            sink(line)
+
+    def done(status: PushStatus, **kw: object) -> BankmlPushResult:
+        return BankmlPushResult(status=status, tag=tag, log=tuple(lines), **kw)  # type: ignore[arg-type]
+
+    name = tag.strip().lower().removesuffix(":latest")
+    if not _NAME.match(name) or name.endswith(".gguf"):
+        return done("refused", reason=(f"tag {tag!r}: bankml names use letters, digits, '.', '_' "
+                                       "and '-' (at most 128, no ':tag', not ending in .gguf)"))
+    if (adapter_dir is None) == (merged_dir is None):
+        return done("error", reason="give exactly one of adapter_dir or merged_dir")
+
+    # 1. the subset — checked before anything expensive runs
+    spec = ModelfileSpec(from_model="<merged>", system=system or "", parameters=dict(params or {}),
+                         stop=list(stop or []))
+    checked = bankml_sanitize(spec)
+    if not checked.ok:
+        for r in checked.refusals:
+            emit(f"[push-bankml] refuse: {r}")
+        return done("refused", reason="the Modelfile asks for what bankml does not reproduce",
+                    refusals=checked.refusals)
+
+    # 2. the binary, and whether it has the verbs
+    caps = bankml_capabilities(bankml_bin)
+    if not caps.found:
+        return done("bankml_missing", reason=caps.reason)
+    if caps.reason:
+        return done("error", reason=caps.reason, bankml_version=caps.version)
+    missing = [v for v, have in (("create", caps.has_create), ("convert", caps.has_convert))
+               if (v == "create" or convert) and not have]
+    if missing:
+        return done("bankml_too_old", bankml_version=caps.version, reason=(
+            f"bankml {caps.version or '(unknown version)'} has no `{'`/`'.join(missing)}` verb "
+            f"(they arrive in bankml 0.3.5); upgrade from {BANKML_URL}"))
+    emit(f"[push-bankml] bankml {caps.version} at {caps.binary}")
+
+    work = Path(work_dir) if work_dir else (
+        (adapter_dir or merged_dir).parent / "bankml_push")  # type: ignore[union-attr]
+
+    # 3. merge, when given an adapter
+    if adapter_dir is not None:
+        try:
+            from mindxtrain.deploy.ollama_push import merge_lora_adapter
+
+            merged = merge_lora_adapter(base_model, Path(adapter_dir), work / "merged", sink=emit)
+        except ImportError as exc:
+            return done("merge_failed", bankml_version=caps.version, reason=(
+                f"{exc} — merging a LoRA needs `uv sync --extra ml`"))
+        except Exception as exc:  # a merge failure is a result, not a crash
+            return done("merge_failed", bankml_version=caps.version,
+                        reason=f"{type(exc).__name__}: {exc}")
+    else:
+        merged = Path(merged_dir)  # type: ignore[arg-type]
+        if not merged.is_dir():
+            return done("error", bankml_version=caps.version,
+                        reason=f"merged_dir {merged} is not a directory")
+
+    arch_refusal = check_merged_arch(merged)
+    if arch_refusal:
+        emit(f"[push-bankml] refuse: {arch_refusal}")
+        return done("refused", bankml_version=caps.version, merged_dir=merged,
+                    reason=arch_refusal, refusals=(arch_refusal,))
+
+    registry = bankml_registry_dir(registry_dir)
+    reg_args = ["--registry", str(registry)] if registry_dir is not None else []
+    gguf: Path | None = None
+    model_sha = ""
+    try:
+        # 4. optional explicit conversion
+        source = str(merged.resolve())
+        if convert:
+            registry.mkdir(parents=True, exist_ok=True)
+            gguf = registry / f"{name}-base-F16.gguf"
+            cmd = [str(caps.binary), "convert", source, "-o", str(gguf),
+                   "--fork", str(registry / f"{gguf.name}.FORK.json"), "--source", source]
+            emit(f"[push-bankml] $ {' '.join(cmd)}")
+            code, out, err = _run(cmd, timeout_s)
+            if err.strip():
+                emit(err.rstrip())
+            if code != 0:
+                status: PushStatus = "refused" if code == 2 else "failed"
+                return done(status, bankml_version=caps.version, merged_dir=merged,
+                            reason=_last_line(err) or f"bankml convert exited {code}",
+                            output=(out + err)[-2000:])
+            m = re.search(rf"^({_SHA})\s", out, re.MULTILINE)
+            model_sha = m.group(1) if m else ""
+
+        # 5. the Modelfile and `bankml create`
+        spec = spec.model_copy(update={"from_model": str(gguf) if gguf else source})
+        modelfile = work / name / "Modelfile"
+        modelfile.parent.mkdir(parents=True, exist_ok=True)
+        modelfile.write_text(render_modelfile(spec), encoding="utf-8")
+        cmd = [str(caps.binary), "create", name, "-f", str(modelfile), *reg_args]
+        emit(f"[push-bankml] $ {' '.join(cmd)}")
+        code, out, err = _run(cmd, timeout_s)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return done("error", bankml_version=caps.version, merged_dir=merged, gguf=gguf,
+                    reason=f"{type(exc).__name__}: {exc}")
+    for chunk in (out, err):
+        if chunk.strip():
+            emit(chunk.rstrip())
+    if code != 0:
+        return done("refused" if code == 2 else "failed", bankml_version=caps.version,
+                    merged_dir=merged, gguf=gguf, modelfile=modelfile,
+                    reason=_last_line(err) or f"bankml create exited {code}",
+                    output=(out + err)[-2000:])
+
+    both = out + "\n" + err
+    over = re.search(rf"over (\S+) \(sha256 ({_SHA})\)", both)
+    digest = re.search(rf"digest sha256:({_SHA})", both)
+    if over:
+        model_sha = over.group(2)
+        if gguf is None:
+            gguf = registry / over.group(1)
+    elif not model_sha and gguf is not None:
+        code_s, out_s, _ = _run([str(caps.binary), "sha256", str(gguf)], 600.0)
+        m = re.match(rf"({_SHA})\s", out_s)
+        model_sha = m.group(1) if (code_s == 0 and m) else ""
+
+    swap: dict[str, str] | None = None
+    if register_with_mindx:
+        try:
+            from mindxtrain.deploy.api_client import swap_mindx_fallback_model
+
+            swap = swap_mindx_fallback_model(provider="bankml", model=name, api_url=mindx_base_url)
+            emit(f"[push-bankml] mindX swap: {swap.get('previous', '?')} -> "
+                 f"{swap.get('current', '?')}")
+        except Exception as exc:  # best-effort, as push_to_ollama
+            emit(f"[push-bankml] mindX registration failed (push still ok): {exc}")
+            swap = None
+
+    emit(f"[push-bankml] created {name} over sha256 {model_sha or '(not reported)'}")
+    return done("created", bankml_version=caps.version, merged_dir=merged, gguf=gguf,
+                modelfile=modelfile, model_sha256=model_sha,
+                digest=digest.group(1) if digest else "", output=both.strip()[-2000:],
+                mindx_fallback_swap=swap)
+
+
+def _last_line(text: str) -> str:
+    rows = [r.strip() for r in text.strip().splitlines() if r.strip()]
+    return rows[-1] if rows else ""
+
+
+__all__ = [
+    "BANKML_CONVERT_ARCHS",
+    "BANKML_PARAMS",
+    "BankmlCapabilities",
+    "BankmlPushResult",
+    "BankmlSanitizeResult",
+    "bankml_capabilities",
+    "bankml_registry_dir",
+    "bankml_sanitize",
+    "base_family_refusal",
+    "check_merged_arch",
+    "push_to_bankml",
+]

mindxtrain/deploy/openai_server_push.py

@@ -0,0 +1,568 @@
+"""Serve a trained model on vLLM or SGLang — an OpenAI-compatible server, launched and watched.
+
+`launch_openai_server` is the vLLM / SGLang twin of `ollama_push.push_to_ollama` and
+`bankml_push.push_to_bankml`: resolve the launcher → build the exact argv → start it detached
+(own session, log file and pid file under the run dir) → poll until the tag answers on
+`/v1/models` (and `/health` for vLLM) → optionally swap mindX's fallback model to it.
+`stop_openai_server` reads the pid file, sends SIGTERM to the server's process group and
+verifies it is gone.
+
+Two ways to serve a LoRA, chosen per call:
+
+- **native (default — no merge):** the base model plus the adapter, as the server loads it.
+  vLLM: `--enable-lora --lora-modules <tag>=<adapter> --max-lora-rank R`; the adapter is listed
+  on `/v1/models` under `<tag>`. SGLang: `--enable-lora --lora-paths <tag>=<adapter>
+  --max-lora-rank R`; a client selects it as `model: "<served-name>:<tag>"`.
+- **merged (`merge=True`):** `merge_lora_adapter` folds the adapter into the base weights
+  (`uv sync --extra ml`) and the merged directory is served under `<tag>`.
+
+On a host without a GPU the CPU backends are used: vLLM's CPU build reads
+`VLLM_CPU_KVCACHE_SPACE` (GiB; set here unless the environment already sets it) and wants
+`--dtype bfloat16`; SGLang takes `--device cpu`. A config that needs a GPU (an FP8 / MXFP4 /
+GPTQ checkpoint, or tensor parallel > 1) is refused on a GPU-less host, with the reason.
+
+Every flag below is from the upstream server-argument docs (vLLM `vllm serve` CLI reference and
+LoRA / CPU-installation pages; SGLang "Server Arguments" and LoRA pages). Anything else a site
+needs goes through `extra_args`, verbatim — this module does not guess at flags.
+
+Clean-room: vLLM and SGLang are reached only as a subprocess and over HTTP. Neither is imported
+here (SGLang's presence is checked with `importlib.util.find_spec`, which does not import it).
+
+Every public function returns a result; nothing here raises past `ServerLaunchResult` /
+`ServerStopResult`.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Literal
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+Flavour = Literal["vllm", "sglang"]
+Dtype = Literal["auto", "half", "float16", "bfloat16", "float", "float32"]
+
+VLLM_INSTALL_HINT = (
+    "install vLLM with `uv sync --extra serve` (GPU / ROCm), or CPU-only per "
+    "https://docs.vllm.ai/en/latest/getting_started/installation/cpu.html "
+    "(e.g. `uv pip install vllm --torch-backend cpu`); or pass --server-bin"
+)
+SGLANG_INSTALL_HINT = (
+    "SGLang is not a mindXtrain extra; install it into the interpreter that will run it "
+    "(`uv pip install sglang`, see https://docs.sglang.io) or pass --server-bin <python>"
+)
+
+# vLLM `--max-lora-rank` choices (vllm serve CLI reference); SGLang takes any int (default 16).
+VLLM_LORA_RANKS: tuple[int, ...] = (1, 8, 16, 32, 64, 128, 256, 320, 512)
+
+# `quantize.scheme` → vLLM `--quantization` (as vllm_launcher.build_vllm_command maps it).
+VLLM_QUANTIZATION: dict[str, str] = {"quark_fp8": "fp8", "quark_mxfp4": "mxfp4",
+                                     "gptq_rocm": "gptq"}
+
+LaunchStatus = Literal[
+    "ready", "dry_run", "refused", "missing", "no_gpu", "merge_failed", "already_running",
+    "exited", "timeout", "error",
+]
+StopStatus = Literal["stopped", "not_running", "still_running", "error"]
+
+
+class OpenAIServerSpec(BaseModel):
+    """What to serve and how. `build_argv` / `build_env` turn it into the exact launch."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    flavour: Flavour
+    model: str = Field(min_length=1, description="Model dir or HF repo id (the base, for LoRA).")
+    tag: str = Field(min_length=1, description="The name clients use (served name or LoRA name).")
+    lora_path: str | None = Field(default=None, description="Adapter dir served natively.")
+    lora_rank: int | None = Field(default=None, ge=1, description="Adapter rank (`r`).")
+    host: str = "127.0.0.1"
+    port: int = Field(default=8000, ge=1024, le=65535)
+    dtype: Dtype = "auto"
+    max_model_len: int = Field(default=8192, ge=512)
+    tensor_parallel: int = Field(default=1, ge=1)
+    quantization: str | None = None
+    cpu: bool = False
+    cpu_kvcache_gib: int = Field(default=4, ge=1)
+    extra_args: tuple[str, ...] = ()
+
+    @property
+    def served_name(self) -> str:
+        """The name the base (or merged) model is served under."""
+        return f"{self.tag}-base" if self.lora_path else self.tag
+
+    @property
+    def client_model(self) -> str:
+        """What an OpenAI client puts in `model` to reach the tag."""
+        if self.lora_path and self.flavour == "sglang":
+            return f"{self.served_name}:{self.tag}"
+        return self.tag
+
+    @property
+    def base_url(self) -> str:
+        return f"http://{self.host}:{self.port}"
+
+
+def _vllm_rank(r: int) -> int:
+    return next((c for c in VLLM_LORA_RANKS if c >= r), VLLM_LORA_RANKS[-1])
+
+
+def default_launcher(flavour: Flavour) -> list[str]:
+    """The launcher prefix assumed when none is resolved (used by dry runs)."""
+    if flavour == "vllm":
+        return ["vllm"]
+    return [sys.executable, "-m", "sglang.launch_server"]
+
+
+def build_argv(spec: OpenAIServerSpec, launcher: list[str] | None = None) -> list[str]:
+    """The exact argv for `spec`. `launcher` is `["vllm"]` or `[python, "-m", "sglang.launch_server"]`."""
+    prefix = list(launcher or default_launcher(spec.flavour))
+    dtype = "bfloat16" if (spec.cpu and spec.dtype == "auto") else spec.dtype
+    if spec.flavour == "vllm":
+        argv = [*prefix, "serve", spec.model,
+                "--served-model-name", spec.served_name,
+                "--host", spec.host, "--port", str(spec.port),
+                "--dtype", dtype,
+                "--max-model-len", str(spec.max_model_len),
+                "--tensor-parallel-size", str(spec.tensor_parallel)]
+        if spec.quantization:
+            argv += ["--quantization", spec.quantization]
+        if spec.lora_path:
+            argv += ["--enable-lora", "--lora-modules", f"{spec.tag}={spec.lora_path}",
+                     "--max-lora-rank", str(_vllm_rank(spec.lora_rank or 16))]
+    else:
+        argv = [*prefix, "--model-path", spec.model,
+                "--served-model-name", spec.served_name,
+                "--host", spec.host, "--port", str(spec.port),
+                "--dtype", dtype,
+                "--context-length", str(spec.max_model_len),
+                "--tp", str(spec.tensor_parallel)]
+        if spec.cpu:
+            argv += ["--device", "cpu"]
+        else:
+            argv += ["--mem-fraction-static", "0.85"]
+        if spec.lora_path:
+            argv += ["--enable-lora", "--lora-paths", f"{spec.tag}={spec.lora_path}",
+                     "--max-lora-rank", str(spec.lora_rank or 16)]
+    return [*argv, *spec.extra_args]
+
+
+def build_env(spec: OpenAIServerSpec, base_env: dict[str, str] | None = None) -> dict[str, str]:
+    """Environment variables this launch adds (the CPU backend's), without overriding the caller's."""
+    env = dict(os.environ if base_env is None else base_env)
+    added: dict[str, str] = {}
+    if spec.cpu and spec.flavour == "vllm" and "VLLM_CPU_KVCACHE_SPACE" not in env:
+        added["VLLM_CPU_KVCACHE_SPACE"] = str(spec.cpu_kvcache_gib)
+    return added
+
+
+def gpu_refusal(spec: OpenAIServerSpec) -> str | None:
+    """None when `spec` can run without a GPU; else why it cannot."""
+    if spec.quantization:
+        return (f"the checkpoint is {spec.quantization}-quantized, which {spec.flavour} serves "
+                "on a GPU only — serve the unquantized checkpoint (--checkpoint .../checkpoint)")
+    if spec.tensor_parallel > 1:
+        return f"tensor_parallel={spec.tensor_parallel} needs that many GPUs"
+    return None
+
+
+def detect_gpu() -> str | None:
+    """A GPU this host exposes (ROCm `/dev/kfd`, NVIDIA `/dev/nvidia0`), or None."""
+    for dev, name in (("/dev/kfd", "rocm"), ("/dev/nvidia0", "cuda")):
+        if Path(dev).exists():
+            return name
+    return None
+
+
+def adapter_rank(adapter_dir: Path) -> int | None:
+    """The LoRA rank `r` from `adapter_config.json`, or None."""
+    try:
+        r = json.loads((Path(adapter_dir) / "adapter_config.json").read_text("utf-8")).get("r")
+    except (OSError, ValueError):
+        return None
+    return int(r) if isinstance(r, int) and r > 0 else None
+
+
+def resolve_launcher(flavour: Flavour, server_bin: str | None = None) -> tuple[list[str] | None, str]:
+    """(launcher argv prefix, "") or (None, reason with the install hint). Never raises.
+
+    vLLM: `server_bin` or `vllm` on PATH. SGLang: `server_bin` is a Python interpreter that has
+    `sglang` (checked in a subprocess), else this interpreter when `find_spec("sglang")` finds it.
+    """
+    if flavour == "vllm":
+        binary = server_bin or shutil.which("vllm")
+        if not binary or not (shutil.which(binary) or Path(binary).is_file()):
+            return None, f"`vllm` not found on PATH — {VLLM_INSTALL_HINT}"
+        return [binary], ""
+    if server_bin:
+        probe = "import importlib.util,sys; sys.exit(importlib.util.find_spec('sglang') is None)"
+        try:
+            rc = subprocess.run([server_bin, "-c", probe], capture_output=True, timeout=60,
+                                check=False).returncode
+        except (OSError, subprocess.SubprocessError) as exc:
+            return None, f"cannot run {server_bin}: {exc} — {SGLANG_INSTALL_HINT}"
+        if rc != 0:
+            return None, f"{server_bin} has no `sglang` package — {SGLANG_INSTALL_HINT}"
+        return [server_bin, "-m", "sglang.launch_server"], ""
+    try:
+        found = importlib.util.find_spec("sglang") is not None
+    except (ImportError, ValueError):
+        found = False
+    if not found:
+        return None, f"`sglang` is not importable from {sys.executable} — {SGLANG_INSTALL_HINT}"
+    return [sys.executable, "-m", "sglang.launch_server"], ""
+
+
+def server_dir(run_dir: Path, flavour: Flavour) -> Path:
+    """Where the log, pid file and launch record live: `<run_dir>/serve/<flavour>/`."""
+    return Path(run_dir) / "serve" / flavour
+
+
+def _alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    # A zombie still answers kill(0); /proc says whether it is really running.
+    try:
+        stat = Path(f"/proc/{pid}/stat").read_text()
+        return stat.rsplit(")", 1)[1].split()[0] != "Z"
+    except (OSError, IndexError):
+        return True
+
+
+def _read_pid(pid_file: Path) -> int | None:
+    try:
+        return int(pid_file.read_text().strip())
+    except (OSError, ValueError):
+        return None
+
+
+def _tail(path: Path, n: int = 2000) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")[-n:]
+    except OSError:
+        return ""
+
+
+# ---- results ------------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ServerLaunchResult:
+    """Outcome of `launch_openai_server`. `ready` (or `dry_run`) is success."""
+
+    status: LaunchStatus
+    flavour: Flavour
+    tag: str
+    reason: str = ""
+    argv: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+    pid: int | None = None
+    base_url: str = ""
+    client_model: str = ""
+    models: tuple[str, ...] = ()
+    log_path: Path | None = None
+    pid_file: Path | None = None
+    merged_dir: Path | None = None
+    mindx_fallback_swap: dict[str, str] | None = None
+    log: tuple[str, ...] = ()
+
+    @property
+    def ok(self) -> bool:
+        return self.status in ("ready", "dry_run")
+
+
+@dataclass(frozen=True)
+class ServerStopResult:
+    status: StopStatus
+    flavour: Flavour
+    pid: int | None = None
+    reason: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status in ("stopped", "not_running")
+
+
+# ---- readiness ----------------------------------------------------------------------------
+
+
+def wait_ready(
+    spec: OpenAIServerSpec,
+    *,
+    timeout_s: float,
+    poll_interval_s: float = 2.0,
+    proc: Any = None,
+    http_client: httpx.Client | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+) -> tuple[str, tuple[str, ...]]:
+    """Poll until `/v1/models` lists the expected id (and vLLM's `/health` is 200).
+
+    Returns ("ready" | "exited" | "timeout", model ids last seen). The expected id is the tag
+    for vLLM (served or LoRA name) and the served name for SGLang.
+    """
+    expect = spec.tag if spec.flavour == "vllm" else spec.served_name
+    client = http_client or httpx.Client(timeout=5.0)
+    seen: tuple[str, ...] = ()
+    deadline = time.monotonic() + timeout_s
+    try:
+        while True:
+            if proc is not None and proc.poll() is not None:
+                return "exited", seen
+            try:
+                healthy = True
+                if spec.flavour == "vllm":
+                    healthy = client.get(f"{spec.base_url}/health").status_code == 200
+                if healthy:
+                    resp = client.get(f"{spec.base_url}/v1/models")
+                    if resp.status_code == 200:
+                        data = resp.json().get("data") or []
+                        seen = tuple(str(m.get("id")) for m in data if isinstance(m, dict))
+                        if expect in seen:
+                            return "ready", seen
+            except (httpx.HTTPError, ValueError, AttributeError):
+                pass
+            if time.monotonic() >= deadline:
+                return "timeout", seen
+            sleep(poll_interval_s)
+    finally:
+        if http_client is None:
+            client.close()
+
+
+# ---- launch / stop ------------------------------------------------------------------------
+
+
+def launch_openai_server(
+    flavour: Flavour,
+    *,
+    base_model: str,
+    tag: str,
+    run_dir: Path,
+    adapter_dir: Path | None = None,
+    model_dir: Path | None = None,
+    merge: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    dtype: Dtype = "auto",
+    max_model_len: int = 8192,
+    tensor_parallel: int = 1,
+    quantization: str | None = None,
+    cpu: bool | None = None,
+    cpu_kvcache_gib: int = 4,
+    extra_args: tuple[str, ...] | list[str] = (),
+    server_bin: str | None = None,
+    dry_run: bool = False,
+    ready_timeout_s: float = 600.0,
+    poll_interval_s: float = 2.0,
+    register_with_mindx: bool = False,
+    mindx_base_url: str | None = None,
+    http_client: httpx.Client | None = None,
+    sleep: Callable[[float], None] = time.sleep,
+    sink: Callable[[str], None] | None = None,
+) -> ServerLaunchResult:
+    """Launch vLLM / SGLang on a trained checkpoint, detached, and wait for it to answer.
+
+    Give exactly one of `adapter_dir` (a PEFT LoRA over `base_model`; served natively unless
+    `merge`) or `model_dir` (a full model directory — merged or quantized). `cpu=None` decides
+    from `detect_gpu()`. `dry_run` builds and returns the argv and touches nothing.
+
+    The server runs in its own session with stdout+stderr in `<run_dir>/serve/<flavour>/
+    server.log` and its pid in `server.pid`; it outlives this call (stop it with
+    `stop_openai_server`). On `timeout` it is left running — big models load slowly.
+    """
+    lines: list[str] = []
+
+    def emit(line: str) -> None:
+        lines.append(line)
+        if sink:
+            sink(line)
+
+    def done(status: LaunchStatus, **kw: Any) -> ServerLaunchResult:
+        return ServerLaunchResult(status=status, flavour=flavour, tag=tag, log=tuple(lines), **kw)
+
+    try:
+        if (adapter_dir is None) == (model_dir is None):
+            return done("error", reason="give exactly one of adapter_dir or model_dir")
+        gpu = detect_gpu() if cpu is None else (None if cpu else "given")
+        on_cpu = gpu is None
+        sdir = server_dir(run_dir, flavour)
+        lora = None if (adapter_dir is None or merge) else Path(adapter_dir)
+        spec = OpenAIServerSpec(
+            flavour=flavour,
+            model=base_model if lora else str(model_dir or sdir / "merged"),
+            tag=tag, lora_path=str(lora.resolve()) if lora else None,
+            lora_rank=adapter_rank(lora) if lora else None,
+            host=host, port=port, dtype=dtype, max_model_len=max_model_len,
+            tensor_parallel=tensor_parallel,
+            quantization=quantization if flavour == "vllm" else None,
+            cpu=on_cpu, cpu_kvcache_gib=cpu_kvcache_gib, extra_args=tuple(extra_args),
+        )
+        needs_gpu = gpu_refusal(spec) if on_cpu else None
+        if flavour == "sglang" and quantization and on_cpu:
+            needs_gpu = (f"the checkpoint is {quantization}-quantized, which sglang serves on a "
+                         "GPU only — serve the unquantized checkpoint (--checkpoint .../checkpoint)")
+
+        if dry_run:
+            launcher, why = resolve_launcher(flavour, server_bin)
+            argv = build_argv(spec, launcher)
+            env = build_env(spec)
+            if merge and adapter_dir is not None:
+                emit(f"[serve-{flavour}] would merge {adapter_dir} into {sdir / 'merged'} first")
+            for note in (why, needs_gpu and f"needs a GPU: {needs_gpu}"):
+                if note:
+                    emit(f"[serve-{flavour}] note: {note}")
+            if env:
+                emit(f"[serve-{flavour}] env: " + " ".join(f"{k}={v}" for k, v in env.items()))
+            return done("dry_run", argv=tuple(argv), env=env, base_url=spec.base_url,
+                        client_model=spec.client_model, reason=why or (needs_gpu or ""))
+
+        if needs_gpu:
+            return done("no_gpu", reason=f"no GPU on this host and {needs_gpu}")
+        launcher, why = resolve_launcher(flavour, server_bin)
+        if launcher is None:
+            return done("missing", reason=why)
+
+        pid_file, log_path = sdir / "server.pid", sdir / "server.log"
+        old = _read_pid(pid_file)
+        if old is not None and _alive(old):
+            return done("already_running", pid=old, pid_file=pid_file, log_path=log_path,
+                        reason=(f"{flavour} already running as pid {old} ({pid_file}); "
+                                f"stop it first (`serve --to {flavour} --stop`)"))
+
+        merged: Path | None = None
+        if merge and adapter_dir is not None:
+            try:
+                from mindxtrain.deploy.ollama_push import merge_lora_adapter
+
+                merged = merge_lora_adapter(base_model, Path(adapter_dir), sdir / "merged",
+                                            sink=emit)
+            except ImportError as exc:
+                return done("merge_failed", reason=f"{exc} — merging needs `uv sync --extra ml`")
+            except Exception as exc:  # a merge failure is a result, not a crash
+                return done("merge_failed", reason=f"{type(exc).__name__}: {exc}")
+            spec = spec.model_copy(update={"model": str(merged)})
+        elif model_dir is not None and not Path(model_dir).is_dir():
+            return done("error", reason=f"model_dir {model_dir} is not a directory")
+
+        argv = build_argv(spec, launcher)
+        added = build_env(spec)
+        sdir.mkdir(parents=True, exist_ok=True)
+        emit(f"[serve-{flavour}] $ {' '.join(argv)}")
+        with log_path.open("ab") as logf:
+            proc = subprocess.Popen(argv, stdout=logf, stderr=subprocess.STDOUT,
+                                    stdin=subprocess.DEVNULL, start_new_session=True,
+                                    env={**os.environ, **added})
+        pid_file.write_text(f"{proc.pid}\n", encoding="utf-8")
+        (sdir / "launch.json").write_text(json.dumps({
+            "flavour": flavour, "tag": tag, "pid": proc.pid, "argv": argv, "env": added,
+            "base_url": spec.base_url, "client_model": spec.client_model,
+            "started_at": datetime.now(tz=UTC).isoformat(),
+        }, indent=1), encoding="utf-8")
+        emit(f"[serve-{flavour}] pid {proc.pid}, log {log_path}; waiting for {spec.base_url}")
+
+        state, models = wait_ready(spec, timeout_s=ready_timeout_s,
+                                   poll_interval_s=poll_interval_s, proc=proc,
+                                   http_client=http_client, sleep=sleep)
+        common: dict[str, Any] = dict(argv=tuple(argv), env=added, pid=proc.pid,
+                                      base_url=spec.base_url, client_model=spec.client_model,
+                                      models=models, log_path=log_path, pid_file=pid_file,
+                                      merged_dir=merged)
+        if state == "exited":
+            pid_file.unlink(missing_ok=True)
+            return done("exited", reason=(f"{flavour} exited with code {proc.poll()} before "
+                                          f"answering; log tail:\n{_tail(log_path, 1200)}"),
+                        **common)
+        if state == "timeout":
+            return done("timeout", reason=(
+                f"{spec.base_url} did not list {spec.client_model!r} within {ready_timeout_s:g}s "
+                f"(seen: {', '.join(models) or 'nothing'}); still running as pid {proc.pid} — "
+                f"watch {log_path}, or `serve --to {flavour} --stop`"), **common)
+
+        swap: dict[str, str] | None = None
+        if register_with_mindx:
+            try:
+                from mindxtrain.deploy.api_client import swap_mindx_fallback_model
+
+                swap = swap_mindx_fallback_model(provider=flavour, model=spec.client_model,
+                                                 api_url=mindx_base_url)
+                emit(f"[serve-{flavour}] mindX swap: {swap.get('previous', '?')} -> "
+                     f"{swap.get('current', '?')}")
+            except Exception as exc:  # best-effort, as push_to_ollama
+                emit(f"[serve-{flavour}] mindX registration failed (server still up): {exc}")
+        emit(f"[serve-{flavour}] ready: {spec.client_model} at {spec.base_url}/v1")
+        common["mindx_fallback_swap"] = swap
+        return done("ready", **common)
+    except Exception as exc:  # never past the result
+        return done("error", reason=f"{type(exc).__name__}: {exc}")
+
+
+def stop_openai_server(
+    flavour: Flavour,
+    run_dir: Path,
+    *,
+    timeout_s: float = 30.0,
+    poll_interval_s: float = 0.5,
+    sleep: Callable[[float], None] = time.sleep,
+) -> ServerStopResult:
+    """SIGTERM the server recorded in `<run_dir>/serve/<flavour>/server.pid` (its whole process
+    group — it was started in its own session) and verify it is gone. Never raises."""
+    pid_file = server_dir(run_dir, flavour) / "server.pid"
+    try:
+        pid = _read_pid(pid_file)
+        if pid is None:
+            return ServerStopResult("not_running", flavour, reason=f"no pid file at {pid_file}")
+        if not _alive(pid):
+            pid_file.unlink(missing_ok=True)
+            return ServerStopResult("not_running", flavour, pid,
+                                    reason=f"pid {pid} was not running (stale pid file removed)")
+        try:
+            os.killpg(pid, signal.SIGTERM)
+        except (ProcessLookupError, PermissionError):
+            os.kill(pid, signal.SIGTERM)
+        deadline = time.monotonic() + timeout_s
+        while _alive(pid):
+            if time.monotonic() >= deadline:
+                return ServerStopResult("still_running", flavour, pid, reason=(
+                    f"pid {pid} still alive {timeout_s:g}s after SIGTERM; "
+                    f"`kill -KILL -{pid}` ends its group"))
+            sleep(poll_interval_s)
+        pid_file.unlink(missing_ok=True)
+        return ServerStopResult("stopped", flavour, pid)
+    except Exception as exc:
+        return ServerStopResult("error", flavour, reason=f"{type(exc).__name__}: {exc}")
+
+
+__all__ = [
+    "VLLM_LORA_RANKS",
+    "VLLM_QUANTIZATION",
+    "OpenAIServerSpec",
+    "ServerLaunchResult",
+    "ServerStopResult",
+    "adapter_rank",
+    "build_argv",
+    "build_env",
+    "default_launcher",
+    "detect_gpu",
+    "gpu_refusal",
+    "launch_openai_server",
+    "resolve_launcher",
+    "server_dir",
+    "stop_openai_server",
+    "wait_ready",
+]

mindxtrain/eval/imprint_bankml.py

@@ -0,0 +1,156 @@
+"""Imprint probes through bankml — reproducible, receipt-auditable, cheap on a CPU.
+
+The canonical imprint gate is `eval.imprint.probe_recall`: transformers greedy decoding with
+`repetition_penalty=1.3` and `no_repeat_ngram_size=3`. Every number in an ascent log was measured
+that way, and that gate stays canonical.
+
+This module is a **second instrument**, not a replacement. It poses the same inquiries to tags
+served by `bankml serve --native` (https://github.com/cryptoAGI/bankml) over Ollama's `/api/chat`
+with `temperature 0`, a fixed `seed`, `num_predict 48` and **no penalties** — bankml refuses
+penalties because its sampler reproduces llama.cpp b11192's temperature / top-k / top-p / min-p
+token-for-token and nothing it cannot prove. What that buys:
+
+- **Reproducible**: the same seed and weights give the same tokens, identical to llama.cpp.
+- **Auditable**: every utterance carries a `bankml_receipt` — the model's sha256, the request's
+  and the response's — so a score is tied to exact weights, not to a tag name.
+- **Cheap**: a 135M F16 actor answers on one CPU core without torch in this process.
+
+Because the decoding differs (no 1.3 repetition penalty, no n-gram block), a score from here is
+**NOT comparable** with the canonical gate's numbers. The report says so in `comparable_with`,
+`note` and the `method` tag (`<scorer>/bankml-greedy`), so the two can never be mixed silently.
+
+bankml is reached over HTTP only (clean-room policy); nothing here imports torch.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field
+
+from mindxtrain.eval.imprint import ImprintReport, score_imprint
+from mindxtrain.operator.backends.bankml import bankml_root_url, raise_for_bankml
+
+NOT_COMPARABLE_NOTE = (
+    "bankml-greedy probe: temperature 0, fixed seed, no repetition penalty, no n-gram block. "
+    "NOT comparable with the canonical imprint gate (transformers greedy, repetition_penalty 1.3, "
+    "no_repeat_ngram_size 3); compare bankml-greedy scores only with bankml-greedy scores."
+)
+
+
+class BankmlDecoding(BaseModel):
+    """The exact decoding every probe was sent with — part of the evidence."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    engine: str = "bankml"
+    endpoint: str = "/api/chat"
+    temperature: float = 0.0
+    seed: int = 0
+    num_predict: int = 48
+    penalties: str = "none (bankml refuses them; not reproduced)"
+
+
+class BankmlProbe(BaseModel):
+    """One tag's utterances for the inquiries, each with bankml's receipt."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    model: str
+    utterances: list[str]
+    receipts: list[dict[str, Any] | None]
+    model_sha256: list[str] = Field(description="distinct model_sha256 values the receipts name")
+
+
+class BankmlImprintReport(BaseModel):
+    """An ImprintReport measured through bankml, with its decoding and receipts attached."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    report: ImprintReport
+    decoding: BankmlDecoding
+    before: BankmlProbe
+    after: BankmlProbe
+    comparable_with: str = "bankml-greedy only"
+    canonical_gate: bool = False
+    note: str = NOT_COMPARABLE_NOTE
+
+
+def probe_recall_via_bankml(
+    model_tag: str,
+    inquiries: list[str],
+    *,
+    system: str | None = None,
+    seed: int = 0,
+    num_predict: int = 48,
+    base_url: str | None = None,
+    timeout_s: float = 600.0,
+    transport: httpx.BaseTransport | None = None,
+) -> BankmlProbe:
+    """Ask `model_tag` each inquiry through bankml's `/api/chat`; keep text and receipt.
+
+    Same prompts, same decoding for every tag → a fair before/after comparison *within* this
+    instrument. Raises `BankmlRefusal` (HTTP 400, with bankml's reason) or `BankmlError`; it never
+    re-sends a refused request with altered options.
+    """
+    root = bankml_root_url(base_url)
+    options = {"temperature": 0.0, "seed": int(seed), "num_predict": int(num_predict)}
+    utterances: list[str] = []
+    receipts: list[dict[str, Any] | None] = []
+    with httpx.Client(timeout=timeout_s, transport=transport) as client:
+        for inquiry in inquiries:
+            msgs = [{"role": "user", "content": inquiry}]
+            if system and system.strip():
+                msgs.insert(0, {"role": "system", "content": system.strip()})
+            resp = client.post(
+                f"{root}/api/chat",
+                json={"model": model_tag, "messages": msgs, "stream": False, "options": options},
+            )
+            raise_for_bankml(resp)
+            body = resp.json()
+            utterances.append(((body.get("message") or {}).get("content") or "").strip())
+            rec = body.get("bankml_receipt")
+            receipts.append(rec if isinstance(rec, dict) else None)
+    shas = sorted({str(r["model_sha256"]) for r in receipts if r and r.get("model_sha256")})
+    return BankmlProbe(model=model_tag, utterances=utterances, receipts=receipts,
+                       model_sha256=shas)
+
+
+def imprint_via_bankml(
+    before_tag: str,
+    after_tag: str,
+    inquiries: list[str],
+    baseline: list[str],
+    *,
+    system: str | None = None,
+    seed: int = 0,
+    num_predict: int = 48,
+    base_url: str | None = None,
+    transport: httpx.BaseTransport | None = None,
+) -> BankmlImprintReport:
+    """Probe the base tag (before) and the imprinted tag (after) through bankml, then score with
+    the existing `score_imprint`. `report.method` is tagged `<scorer>/bankml-greedy`."""
+    kw: dict[str, Any] = {"system": system, "seed": seed, "num_predict": num_predict,
+                          "base_url": base_url, "transport": transport}
+    before = probe_recall_via_bankml(before_tag, inquiries, **kw)
+    after = probe_recall_via_bankml(after_tag, inquiries, **kw)
+    report = score_imprint(inquiries, before.utterances, after.utterances,
+                           baseline or before.utterances)
+    report = report.model_copy(update={"method": f"{report.method}/bankml-greedy"})
+    return BankmlImprintReport(
+        report=report,
+        decoding=BankmlDecoding(seed=int(seed), num_predict=int(num_predict)),
+        before=before,
+        after=after,
+    )
+
+
+__all__ = [
+    "NOT_COMPARABLE_NOTE",
+    "BankmlDecoding",
+    "BankmlImprintReport",
+    "BankmlProbe",
+    "imprint_via_bankml",
+    "probe_recall_via_bankml",
+]

mindxtrain/eval/mei/record.py

@@ -58,7 +58,7 @@ class InferenceEngineIdent(BaseModel):
 
     model_config = ConfigDict(extra="forbid", frozen=True)
 
-    name: Literal["llama.cpp", "ollama", "vllm", "sglang", "transformers"] = Field(
+    name: Literal["llama.cpp", "ollama", "vllm", "sglang", "transformers", "bankml"] = Field(
         description="Which serving engine collected the timings.",
     )
     commit_sha: str = Field(min_length=1, description="Engine binary commit SHA or version string.")

mindxtrain/governance/panel.py

@@ -37,10 +37,25 @@ _VERDICT_RE = re.compile(r"verdict\s*[:\-]?\s*(approve|reject|abstain)", re.IGNO
 
 
 def resolve_chat_base_url(base_url: str | None = None) -> str:
-    """Resolve the OpenAI-compatible chat base URL the operator/backends use."""
+    """Resolve the OpenAI-compatible chat base URL the operator/backends use.
+
+    Order: an explicit `base_url`; bankml when `MINDXTRAIN_BACKEND=bankml` (its
+    configured URL, else its default 127.0.0.1:18093/v1); then the env chain
+    OPENAI -> VLLM -> OLLAMA -> BANKML (bankml only when its URL is set, and last,
+    so existing hosts resolve as before); else local ollama.
+    """
     if base_url:
         return base_url.rstrip("/")
-    for env in ("MINDXTRAIN_OPENAI_BASE_URL", "MINDXTRAIN_VLLM_BASE_URL", "MINDXTRAIN_OLLAMA_BASE_URL"):
+    if os.environ.get("MINDXTRAIN_BACKEND") == "bankml":
+        from mindxtrain.operator.backends.bankml import bankml_base_url
+
+        return bankml_base_url()
+    for env in (
+        "MINDXTRAIN_OPENAI_BASE_URL",
+        "MINDXTRAIN_VLLM_BASE_URL",
+        "MINDXTRAIN_OLLAMA_BASE_URL",
+        "MINDXTRAIN_BANKML_BASE_URL",
+    ):
         val = os.environ.get(env)
         if val:
             return val.rstrip("/")

mindxtrain/hf/extension.py

@@ -137,13 +137,29 @@ def _card(repo_id: str, meta: dict[str, Any]) -> str:
               "the training log ships beside the weights.\n")
 
 
+def published_modelfile(persona_system: str | None = None, *,
+                        repeat_penalty: float | None = 1.3) -> str:
+    """The Modelfile shipped beside a published run. `repeat_penalty=None` leaves the penalty out,
+    so engines that refuse penalties (bankml) load the same file."""
+    return ("# 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\n"
+            + (f"PARAMETER repeat_penalty {repeat_penalty}\n" if repeat_penalty is not None else "")
+            + 'PARAMETER stop "<|im_end|>"\n')
+
+
 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]:
+                       include_merged: bool = True, dry_run: bool = False,
+                       repeat_penalty: float | None = 1.3) -> 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`.
 
-    `dry_run=True` reports exactly what would be uploaded and touches nothing."""
+    `dry_run=True` reports exactly what would be uploaded and touches nothing.
+
+    `repeat_penalty` is written into the Modelfile (default 1.3, the imprint gate's decoding);
+    `None` leaves it out, so the same Modelfile also loads in engines that refuse penalties
+    (bankml reproduces temperature/top-k/top-p/min-p, not penalties)."""
     run = Path(run_dir)
     if not run.is_dir():
         return {"ok": False, "reason": f"no run dir at {run}"}
@@ -170,9 +186,7 @@ def publish_generation(run_dir: Path | str, repo_id: str, *, token: str | None =
         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')
+    modelfile = published_modelfile(persona_system, repeat_penalty=repeat_penalty)
     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:

mindxtrain/models/registry.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Callable
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -43,6 +43,10 @@ class ChatResponse(BaseModel):
     finish_reason: Literal["stop", "length", "error"] = "stop"
     prompt_tokens: int = 0
     completion_tokens: int = 0
+    # Engine-issued provenance for this answer, when the engine gives one (bankml's
+    # `bankml_receipt`: model_sha256, request_sha256, response_sha256, engine, tokens,
+    # wall_ms, ...). None for backends that issue no receipt.
+    receipt: dict[str, Any] | None = None
 
 
 class Backend(ABC):
@@ -155,6 +159,7 @@ from mindxtrain.models import glm51 as _glm51  # noqa: E402, F401
 from mindxtrain.models import mistral3 as _mistral3  # noqa: E402, F401
 from mindxtrain.models import phi4_mini as _phi4_mini  # noqa: E402, F401
 from mindxtrain.models import qwen35 as _qwen35  # noqa: E402, F401
+from mindxtrain.operator.backends import bankml as _bankml  # noqa: E402, F401
 from mindxtrain.operator.backends import ollama as _ollama  # noqa: E402, F401
 from mindxtrain.operator.backends import openai_compat as _openai_compat  # noqa: E402, F401
 from mindxtrain.operator.backends import vllm as _vllm  # noqa: E402, F401

mindxtrain/operator/app.py

@@ -104,12 +104,45 @@ def _vllm_first_model() -> str | None:
         return None
 
 
+def _bankml_reachable(timeout_s: float = 1.0) -> bool:
+    """Probe `bankml serve --native` at MINDXTRAIN_BANKML_BASE_URL.
+
+    Hits the server's own `GET /bankml` identity endpoint (not `/health`, which any
+    llama-server-shaped engine answers), so a 200 means bankml specifically is there.
+    """
+    from mindxtrain.operator.backends.bankml import bankml_root_url
+
+    try:
+        with httpx.Client(timeout=timeout_s) as client:
+            return client.get(bankml_root_url() + "/bankml").status_code == 200
+    except (httpx.HTTPError, OSError):
+        return False
+
+
+def _bankml_first_model() -> str | None:
+    """The model id bankml lists at `/v1/models` (the resident or startup model), or None."""
+    from mindxtrain.operator.backends.bankml import bankml_base_url
+
+    try:
+        with httpx.Client(timeout=1.0) as client:
+            resp = client.get(bankml_base_url() + "/models")
+            if resp.status_code != 200:
+                return None
+            models = resp.json().get("data", [])
+        first = models[0] if models else None
+        return first.get("id") if isinstance(first, dict) else None
+    except (httpx.HTTPError, OSError, ValueError, IndexError):
+        return None
+
+
 def backend_reachable(name: str) -> bool:
     """Live probe for a backend by name. Used by both /health and /coach health."""
     if name == "ollama":
         return _ollama_reachable()
     if name == "vllm":
         return _vllm_reachable()
+    if name == "bankml":
+        return _bankml_reachable()
     # openai_compat and unknown backends: we don't have a generic probe,
     # so the chat-completions failure path remains the authoritative signal.
     return False
@@ -121,6 +154,8 @@ def backend_first_model(name: str) -> str | None:
         return ollama_first_model()
     if name == "vllm":
         return _vllm_first_model()
+    if name == "bankml":
+        return _bankml_first_model()
     return None
 
 
@@ -130,7 +165,10 @@ def resolve_backend_name() -> str:
     Resolution order:
     1. Explicit `MINDXTRAIN_BACKEND` env var (canonical).
     2. Legacy `AUTOMINDX_BACKEND` (back-compat with the pre-rename code).
-    3. Auto-detect: ollama if reachable on localhost:11434, else vllm.
+    3. Auto-detect: ollama if reachable on localhost:11434; else bankml if
+       `bankml serve` answers on its port *and* vLLM does not; else vllm.
+       bankml comes after ollama and vllm, so a host that ran ollama or vllm
+       before bankml existed resolves exactly as it did.
     """
     explicit = (
         os.environ.get("MINDXTRAIN_BACKEND")
@@ -140,9 +178,43 @@ def resolve_backend_name() -> str:
         return explicit
     if _ollama_reachable():
         return "ollama"
+    if _bankml_reachable() and not _vllm_reachable():
+        return "bankml"
     return "vllm"
 
 
+def backend_kwargs(name: str, *, strict: bool = False) -> dict[str, object]:
+    """Constructor kwargs (base URL, key) for the backend registered as `name`.
+
+    One place for the per-backend env lookups the operator chat route and the Coach
+    chat stream both need. `strict=True` keeps the operator's original contract that
+    `openai_compat` without `MINDXTRAIN_OPENAI_BASE_URL` is a configuration error
+    (KeyError); the Coach passes `strict=False` and gets an empty URL instead.
+    """
+    kwargs: dict[str, object] = {}
+    if name == "vllm":
+        kwargs["base_url"] = os.environ.get(
+            "MINDXTRAIN_VLLM_BASE_URL",
+            os.environ.get("AUTOMINDX_VLLM_BASE_URL", "http://localhost:8000/v1"),
+        )
+    elif name == "ollama":
+        kwargs["base_url"] = os.environ.get(
+            "MINDXTRAIN_OLLAMA_BASE_URL", "http://localhost:11434/v1",
+        )
+    elif name == "bankml":
+        from mindxtrain.operator.backends.bankml import bankml_base_url
+
+        kwargs["base_url"] = bankml_base_url()
+    elif name == "openai_compat":
+        kwargs["base_url"] = (
+            os.environ["MINDXTRAIN_OPENAI_BASE_URL"]
+            if strict
+            else os.environ.get("MINDXTRAIN_OPENAI_BASE_URL", "")
+        )
+        kwargs["api_key"] = os.environ.get("MINDXTRAIN_OPENAI_API_KEY", "")
+    return kwargs
+
+
 def ollama_first_model() -> str | None:
     """Return the name of the first model ollama lists, or None on failure.
 
@@ -275,28 +347,21 @@ async def readyz() -> dict[str, object]:
 
 @app.post("/v1/chat/completions", response_model=ChatResponse)
 async def chat_completions(request: ChatRequest) -> ChatResponse:
+    from mindxtrain.operator.backends.bankml import BankmlRefusal
+
     backend_name = resolve_backend_name()
-    backend_kwargs: dict[str, object] = {}
-    if backend_name == "vllm":
-        backend_kwargs["base_url"] = os.environ.get(
-            "MINDXTRAIN_VLLM_BASE_URL",
-            os.environ.get("AUTOMINDX_VLLM_BASE_URL", "http://localhost:8000/v1"),
-        )
-    elif backend_name == "ollama":
-        backend_kwargs["base_url"] = os.environ.get(
-            "MINDXTRAIN_OLLAMA_BASE_URL", "http://localhost:11434/v1",
-        )
-    elif backend_name == "openai_compat":
-        backend_kwargs["base_url"] = os.environ["MINDXTRAIN_OPENAI_BASE_URL"]
-        backend_kwargs["api_key"] = os.environ.get("MINDXTRAIN_OPENAI_API_KEY", "")
+    kwargs = backend_kwargs(backend_name, strict=True)
 
     try:
-        backend = build_backend(backend_name, **backend_kwargs)
+        backend = build_backend(backend_name, **kwargs)
         return await backend.chat(request)
     except NotImplementedError as exc:
         raise HTTPException(status_code=501, detail=str(exc)) from exc
     except KeyError as exc:
         raise HTTPException(status_code=400, detail=str(exc)) from exc
+    except BankmlRefusal as exc:
+        # bankml's reason, passed through verbatim; never retried with altered params.
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
 
 
 @app.post("/v1/agentic")

mindxtrain/operator/backends/bankml.py

@@ -0,0 +1,197 @@
+"""bankml backend — the verified CPU engine, reached over HTTP only.
+
+bankml (https://github.com/cryptoAGI/bankml, Apache-2.0 OR MIT) is a zero-dependency Rust
+runtime whose `bankml serve --native` answers OpenAI `/v1/chat/completions` and Ollama `/api/*`
+from its own forward pass, token-identical to llama.cpp b11192, on 127.0.0.1:18093 by default.
+mindXtrain never vendors it: this module speaks its documented wire protocol and nothing else
+(clean-room policy, CLAUDE.md).
+
+What this backend adds over `openai_compat`:
+
+- **Receipts.** Every bankml answer carries a `bankml_receipt` (model_sha256, request_sha256,
+  response_sha256, engine, tokens, wall_ms, ...). Non-streamed it is a top-level object and lands
+  in `ChatResponse.receipt`; streamed it arrives as one extra `data: {"bankml_receipt": ...}`
+  event before `data: [DONE]`. Either way the latest receipt is also kept on `last_receipt`.
+- **Refusals are typed, never retried.** bankml answers HTTP 400 with a plain-text reason when a
+  request asks for something its verified forward pass does not reproduce (repeat / presence /
+  frequency penalties, mirostat, typical_p, tools, an unknown architecture, Q8_0 / Q4_K / BF16).
+  That becomes `BankmlRefusal(reason)`. The request is never re-sent with altered parameters:
+  a changed request would be a different, unreceipted question.
+
+Env: `MINDXTRAIN_BANKML_BASE_URL` (default `http://127.0.0.1:18093/v1`).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+
+from mindxtrain.models.registry import ChatRequest, ChatResponse, register_backend
+from mindxtrain.operator.backends.openai_compat import OpenAICompatBackend
+
+DEFAULT_BANKML_BASE_URL = "http://127.0.0.1:18093/v1"
+
+
+def bankml_base_url() -> str:
+    """The configured bankml OpenAI base URL (`.../v1`)."""
+    return os.environ.get("MINDXTRAIN_BANKML_BASE_URL", DEFAULT_BANKML_BASE_URL).rstrip("/")
+
+
+def bankml_root_url(base_url: str | None = None) -> str:
+    """The server root (no `/v1`) — where `/health`, `/bankml` and `/api/*` live."""
+    return (base_url or bankml_base_url()).rstrip("/").removesuffix("/v1")
+
+
+class BankmlError(RuntimeError):
+    """bankml answered, but not with an answer (an engine error, a broken stream)."""
+
+    label = "error"
+
+    def __init__(self, reason: str, status_code: int = 0) -> None:
+        self.reason = reason.strip()
+        self.status_code = status_code
+        super().__init__(f"bankml {self.label} ({status_code}): {self.reason}")
+
+
+class BankmlRefusal(BankmlError):
+    """bankml refused the request (HTTP 400) and said why.
+
+    The reason is bankml's own text, e.g. ``mirostat: not reproduced; ...``. Callers must not
+    retry with parameters stripped or altered — change the request deliberately instead.
+    """
+
+    label = "refused"
+
+    def __init__(self, reason: str, status_code: int = 400) -> None:
+        super().__init__(reason, status_code)
+
+
+def refusal_reason(resp: httpx.Response) -> str:
+    """bankml's reason from an error body: `/v1` sends text/plain, `/api` sends `{"error": ...}`."""
+    text = resp.text or ""
+    try:
+        body = json.loads(text)
+    except ValueError:
+        return text.strip() or f"HTTP {resp.status_code}"
+    if isinstance(body, dict) and body.get("error"):
+        err = body["error"]
+        return str(err.get("message", err) if isinstance(err, dict) else err)
+    return text.strip() or f"HTTP {resp.status_code}"
+
+
+def raise_for_bankml(resp: httpx.Response) -> None:
+    """400 → `BankmlRefusal`; any other non-2xx → `BankmlError`."""
+    if resp.status_code == 400:
+        raise BankmlRefusal(refusal_reason(resp))
+    if resp.status_code >= 400:
+        raise BankmlError(refusal_reason(resp), resp.status_code)
+
+
+@register_backend("bankml")
+class BankmlBackend(OpenAICompatBackend):
+    """OpenAI-compatible client for `bankml serve --native`, keeping receipts and refusals."""
+
+    name = "bankml"
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        timeout_s: float = 300.0,
+        *,
+        seed: int | None = None,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        super().__init__(base_url=base_url or bankml_base_url(), api_key=None, timeout_s=timeout_s)
+        # `api_key or env` in the parent would pick up an OpenAI key; bankml is loopback, keyless.
+        self.api_key = ""
+        self.seed = seed
+        self._transport = transport
+        self.last_receipt: dict[str, Any] | None = None
+
+    def _client(self) -> httpx.AsyncClient:
+        return httpx.AsyncClient(timeout=self.timeout_s, transport=self._transport)
+
+    def _payload(self, request: ChatRequest, *, stream: bool) -> dict[str, object]:
+        payload = super()._payload(request, stream=stream)
+        if self.seed is not None:
+            payload["seed"] = self.seed
+        return payload
+
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        async with self._client() as client:
+            resp = await client.post(
+                f"{self.base_url}/chat/completions",
+                json=self._payload(request, stream=False),
+                headers=self._headers(),
+            )
+        raise_for_bankml(resp)
+        data = resp.json()
+        choice = (data.get("choices") or [{}])[0]
+        usage = data.get("usage") or {}
+        receipt = data.get("bankml_receipt")
+        self.last_receipt = receipt if isinstance(receipt, dict) else None
+        finish = choice.get("finish_reason") or "stop"
+        return ChatResponse(
+            model=data.get("model", request.model),
+            content=(choice.get("message") or {}).get("content", "") or "",
+            finish_reason=finish if finish in ("stop", "length", "error") else "stop",
+            prompt_tokens=int(usage.get("prompt_tokens", 0)),
+            completion_tokens=int(usage.get("completion_tokens", 0)),
+            receipt=self.last_receipt,
+        )
+
+    async def stream_chat(self, request: ChatRequest) -> AsyncIterator[str]:
+        self.last_receipt = None
+
+        async def _gen() -> AsyncIterator[str]:
+            async with self._client() as client:
+                async with client.stream(
+                    "POST",
+                    f"{self.base_url}/chat/completions",
+                    json=self._payload(request, stream=True),
+                    headers=self._headers(),
+                ) as resp:
+                    if resp.status_code >= 400:
+                        await resp.aread()
+                        raise_for_bankml(resp)
+                    async for raw in resp.aiter_lines():
+                        if not raw or not raw.startswith("data:"):
+                            continue
+                        data = raw[5:].strip()
+                        if data == "[DONE]":
+                            return
+                        try:
+                            chunk = json.loads(data)
+                        except json.JSONDecodeError:
+                            continue
+                        if not isinstance(chunk, dict):
+                            continue
+                        if "bankml_receipt" in chunk:
+                            rec = chunk["bankml_receipt"]
+                            self.last_receipt = rec if isinstance(rec, dict) else None
+                            continue
+                        if "error" in chunk:
+                            # bankml stops a stream it cannot finish with `data: {"error": ...}`
+                            raise BankmlError(str(chunk["error"]), resp.status_code)
+                        delta = (chunk.get("choices") or [{}])[0].get("delta", {})
+                        token = delta.get("content")
+                        if token:
+                            yield token
+
+        return _gen()
+
+
+__all__ = [
+    "DEFAULT_BANKML_BASE_URL",
+    "BankmlBackend",
+    "BankmlError",
+    "BankmlRefusal",
+    "bankml_base_url",
+    "bankml_root_url",
+    "raise_for_bankml",
+    "refusal_reason",
+]

mindxtrain/operator/coach/api.py

@@ -1081,23 +1081,12 @@ async def api_models() -> dict[str, Any]:
 
 
 def _resolve_chat_backend() -> Any:
-    """Build the active chat backend (ollama / vllm / openai_compat)."""
+    """Build the active chat backend (ollama / vllm / bankml / openai_compat)."""
     from mindxtrain.models.registry import build_backend
-    from mindxtrain.operator.app import resolve_backend_name
+    from mindxtrain.operator.app import backend_kwargs, resolve_backend_name
 
     name = resolve_backend_name()
-    kwargs: dict[str, Any] = {}
-    if name == "vllm":
-        kwargs["base_url"] = os.environ.get(
-            "MINDXTRAIN_VLLM_BASE_URL",
-            os.environ.get("AUTOMINDX_VLLM_BASE_URL", "http://localhost:8000/v1"),
-        )
-    elif name == "ollama":
-        kwargs["base_url"] = os.environ.get("MINDXTRAIN_OLLAMA_BASE_URL", "http://localhost:11434/v1")
-    elif name == "openai_compat":
-        kwargs["base_url"] = os.environ.get("MINDXTRAIN_OPENAI_BASE_URL", "")
-        kwargs["api_key"] = os.environ.get("MINDXTRAIN_OPENAI_API_KEY", "")
-    return build_backend(name, **kwargs)
+    return build_backend(name, **backend_kwargs(name))
 
 
 @router.post("/api/chat/stream")

mindxtrain/ui/app.py

@@ -241,7 +241,7 @@ def build() -> gr.Blocks:
                 with gr.Row():
                     s_cfg = gr.Textbox(value="run.yaml", label="config", scale=2)
                     s_ckpt = gr.Textbox(value="", label="checkpoint", scale=2)
-                    s_to = gr.Radio(["ollama", "vllm"], value="ollama", label="to", scale=1)
+                    s_to = gr.Radio(["ollama", "bankml", "vllm", "sglang"], value="ollama", label="to", scale=1)
                     s_tag = gr.Textbox(value="", label="tag", scale=1)
                     s_btn = gr.Button("serve", variant="primary", scale=1)
                 with gr.Group(visible=False) as adv_serve:

mindxtrain/ui/console.py

@@ -36,6 +36,31 @@ DEFAULTS: dict[str, Any] = {
 GATE_DECODING: dict[str, Any] = {"temperature": 0.0, "repeat_penalty": 1.3, "top_p": 1.0, "top_k": 0}
 
 
+# Options whose value here is also the engine's own default when the key is absent. Sending them
+# changes nothing for Ollama, but an engine that refuses penalties / mirostat outright (bankml:
+# "not reproduced") would refuse the whole request — so `chat` leaves them out at these values.
+# A deliberate non-default value is always sent; the engine then honours or refuses it, visibly.
+ENGINE_DEFAULTS: dict[str, Any] = {
+    "repeat_penalty": 1.1, "presence_penalty": 0.0, "frequency_penalty": 0.0, "typical_p": 1.0,
+    "mirostat": 0,
+}
+
+
+def wire_options(options: dict[str, Any] | None) -> dict[str, Any]:
+    """The options actually sent: empties dropped, and penalty/mirostat keys left at the engine's
+    own default omitted (mirostat's tau/eta only matter, and are only sent, when mirostat is on)."""
+    opts = {k: v for k, v in (options or {}).items() if v not in (None, "", [])}
+    miro_on = bool(opts.get("mirostat"))
+    out: dict[str, Any] = {}
+    for k, v in opts.items():
+        if k in ("mirostat_tau", "mirostat_eta") and not miro_on:
+            continue
+        if k in ENGINE_DEFAULTS and v == ENGINE_DEFAULTS[k]:
+            continue
+        out[k] = v
+    return out
+
+
 def models(host: str = "", timeout: float = 4.0) -> list[str]:
     """Tags the daemon is serving, local first. Empty when it is down — never an exception."""
     try:
@@ -95,10 +120,11 @@ def unreachable(host: str = "") -> str:
 def chat(messages: list[dict[str, str]], model: str, *, options: dict[str, Any] | None = None,
          keep_alive: str = "10m", host: str = "", timeout: float = 900.0) -> Iterator[tuple[str, dict[str, Any]]]:
     """Stream `(text_so_far, stats)`. `stats` is empty until the final object, which carries the real
-    counts. Options are passed through verbatim; the engine implements them, so none are dropped."""
+    counts. Options are passed through as `wire_options` leaves them: a penalty or mirostat key at
+    the engine's own default is omitted (identical for Ollama, and accepted by bankml)."""
     host = (host or HOST).rstrip("/")
     body = {"model": model, "messages": messages, "stream": True, "keep_alive": keep_alive,
-            "options": {k: v for k, v in (options or {}).items() if v not in (None, "", [])}}
+            "options": wire_options(options)}
     req = urllib.request.Request(f"{host}/api/chat", data=json.dumps(body).encode(), method="POST",
                                  headers={"Content-Type": "application/json"})
     acc = ""

tests/conftest.py

@@ -0,0 +1,18 @@
+"""Suite-wide hermeticity for the operator's backend auto-detect.
+
+`resolve_backend_name()` probes `bankml serve` on 127.0.0.1:18093 when ollama is not
+reachable. A developer box that happens to run bankml would otherwise change what the
+auto-detect tests resolve to, so the probe is pinned to "absent" for every test; the
+bankml tests that exercise the probe itself monkeypatch it back explicitly.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _no_live_bankml_probe(monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.operator import app as operator_app
+
+    monkeypatch.setattr(operator_app, "_bankml_reachable", lambda *a, **k: False)

tests/test_bankml_backend.py

@@ -0,0 +1,341 @@
+"""bankml operator backend: registry, env, receipts, typed refusals, SSE streaming, wiring.
+
+No network: every HTTP exchange goes through httpx.MockTransport.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+from fastapi.testclient import TestClient
+
+from mindxtrain.governance import panel as P
+from mindxtrain.models.registry import ChatMessage, ChatRequest, build_backend, list_backends
+from mindxtrain.operator import app as operator_app
+from mindxtrain.operator.backends.bankml import (
+    DEFAULT_BANKML_BASE_URL,
+    BankmlBackend,
+    BankmlError,
+    BankmlRefusal,
+    bankml_root_url,
+)
+
+_REAL_BANKML_REACHABLE = operator_app._bankml_reachable  # captured before conftest patches it
+
+RECEIPT = {
+    "bankml": "0.3.4",
+    "engine": "native",
+    "model_sha256": "6b64c748d96ad26fd72402299bd27b2ae82f489bd0469498dd18eb6054058266",
+    "guard": "play",
+    "prompt_tokens": 12,
+    "completion_tokens": 3,
+    "ttft_ms": 40,
+    "wall_ms": 90,
+    "response_sha256": "a" * 64,
+    "request_sha256": "b" * 64,
+    "signed": False,
+}
+
+
+def _req(stream: bool = False) -> ChatRequest:
+    return ChatRequest(
+        model="mindx-gen39",
+        messages=[ChatMessage(role="user", content="Who are you?")],
+        temperature=0.0,
+        max_tokens=16,
+        stream=stream,
+    )
+
+
+def _completion() -> dict[str, object]:
+    return {
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": "I am mindX."},
+                     "finish_reason": "stop"}],
+        "model": "mindx-gen39-F16.gguf",
+        "object": "chat.completion",
+        "usage": {"completion_tokens": 3, "prompt_tokens": 12, "total_tokens": 15},
+        "bankml_receipt": RECEIPT,
+    }
+
+
+# ---- registry + env -----------------------------------------------------------
+
+
+def test_registered_and_built_by_name() -> None:
+    assert "bankml" in list_backends()
+    assert isinstance(build_backend("bankml"), BankmlBackend)
+
+
+def test_default_and_env_base_url(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MINDXTRAIN_BANKML_BASE_URL", raising=False)
+    assert BankmlBackend().base_url == DEFAULT_BANKML_BASE_URL
+    monkeypatch.setenv("MINDXTRAIN_BANKML_BASE_URL", "http://127.0.0.1:9999/v1/")
+    b = BankmlBackend()
+    assert b.base_url == "http://127.0.0.1:9999/v1"
+    assert bankml_root_url() == "http://127.0.0.1:9999"
+
+
+def test_never_sends_an_openai_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MINDXTRAIN_OPENAI_API_KEY", "sk-should-not-leak")
+    assert "Authorization" not in BankmlBackend()._headers()
+
+
+# ---- chat ---------------------------------------------------------------------
+
+
+def test_chat_keeps_the_receipt() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["url"] = str(request.url)
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json=_completion())
+
+    b = BankmlBackend(seed=7, transport=httpx.MockTransport(handler))
+    resp = asyncio.run(b.chat(_req()))
+    assert seen["url"] == "http://127.0.0.1:18093/v1/chat/completions"
+    body = seen["body"]
+    assert isinstance(body, dict)
+    assert body["seed"] == 7 and body["temperature"] == 0.0 and body["stream"] is False
+    assert resp.content == "I am mindX."
+    assert resp.prompt_tokens == 12 and resp.completion_tokens == 3
+    assert resp.receipt == RECEIPT
+    assert b.last_receipt == RECEIPT
+
+
+def test_chat_400_is_a_typed_refusal_and_is_not_retried() -> None:
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(400, text="mirostat: not reproduced; bankML reproduces llama.cpp's "
+                                        "top-k, top-p, min-p and temperature")
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    with pytest.raises(BankmlRefusal) as info:
+        asyncio.run(b.chat(_req()))
+    assert info.value.status_code == 400
+    assert info.value.reason.startswith("mirostat: not reproduced")
+    assert "bankml refused (400)" in str(info.value)
+    assert calls["n"] == 1
+
+
+def test_ollama_style_json_error_body_is_read() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(400, json={"error": "tools: tool calling ... not reproduced yet"})
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    with pytest.raises(BankmlRefusal) as info:
+        asyncio.run(b.chat(_req()))
+    assert info.value.reason.startswith("tools:")
+
+
+def test_non_400_errors_are_bankml_errors_not_refusals() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(503, text="model changed since bankml verified it")
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    with pytest.raises(BankmlError) as info:
+        asyncio.run(b.chat(_req()))
+    assert not isinstance(info.value, BankmlRefusal)
+    assert info.value.status_code == 503
+
+
+# ---- stream -------------------------------------------------------------------
+
+
+def _sse(*events: str) -> bytes:
+    return "".join(f"data: {e}\n\n" for e in events).encode()
+
+
+def _collect(b: BankmlBackend) -> list[str]:
+    async def run() -> list[str]:
+        out: list[str] = []
+        async for tok in await b.stream_chat(_req(stream=True)):
+            out.append(tok)
+        return out
+
+    return asyncio.run(run())
+
+
+def test_stream_yields_tokens_and_keeps_the_final_receipt() -> None:
+    def chunk(text: str) -> str:
+        return json.dumps({"choices": [{"index": 0, "delta": {"content": text},
+                                        "finish_reason": None}]})
+
+    final = json.dumps({"choices": [{"index": 0, "delta": {}, "finish_reason": "stop"}],
+                        "usage": {"completion_tokens": 2, "prompt_tokens": 12}})
+    body = _sse(chunk("I am"), chunk(" mindX."), final,
+                json.dumps({"bankml_receipt": RECEIPT}), "[DONE]")
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert json.loads(request.content)["stream"] is True
+        return httpx.Response(200, content=body, headers={"content-type": "text/event-stream"})
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    assert _collect(b) == ["I am", " mindX."]
+    assert b.last_receipt == RECEIPT
+
+
+def test_stream_400_raises_refusal() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(400, text="repeat_penalty: not reproduced")
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    with pytest.raises(BankmlRefusal):
+        _collect(b)
+
+
+def test_stream_error_event_raises() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=_sse(json.dumps({"error": "context full"})))
+
+    b = BankmlBackend(transport=httpx.MockTransport(handler))
+    with pytest.raises(BankmlError, match="context full"):
+        _collect(b)
+
+
+# ---- operator wiring ---------------------------------------------------------
+
+
+def test_backend_kwargs_for_bankml(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MINDXTRAIN_BANKML_BASE_URL", "http://127.0.0.1:18100/v1")
+    assert operator_app.backend_kwargs("bankml") == {"base_url": "http://127.0.0.1:18100/v1"}
+
+
+def test_backend_kwargs_openai_strict_contract(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MINDXTRAIN_OPENAI_BASE_URL", raising=False)
+    with pytest.raises(KeyError):
+        operator_app.backend_kwargs("openai_compat", strict=True)
+    assert operator_app.backend_kwargs("openai_compat")["base_url"] == ""
+
+
+def test_bankml_probe_hits_the_identity_endpoint(monkeypatch: pytest.MonkeyPatch) -> None:
+    seen: list[str] = []
+
+    class _Client:
+        def __init__(self, *a: object, **k: object) -> None: ...
+        def __enter__(self) -> _Client:
+            return self
+        def __exit__(self, *a: object) -> None: ...
+        def get(self, url: str) -> httpx.Response:
+            seen.append(url)
+            return httpx.Response(200, json={"bankml": "0.3.4"})
+
+    monkeypatch.delenv("MINDXTRAIN_BANKML_BASE_URL", raising=False)
+    monkeypatch.setattr(operator_app.httpx, "Client", _Client)
+    assert _REAL_BANKML_REACHABLE() is True
+    assert seen == ["http://127.0.0.1:18093/bankml"]
+
+
+def test_bankml_probe_false_on_connection_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    class _Client:
+        def __init__(self, *a: object, **k: object) -> None: ...
+        def __enter__(self) -> _Client:
+            return self
+        def __exit__(self, *a: object) -> None: ...
+        def get(self, url: str) -> httpx.Response:
+            raise httpx.ConnectError("refused")
+
+    monkeypatch.setattr(operator_app.httpx, "Client", _Client)
+    assert _REAL_BANKML_REACHABLE() is False
+
+
+def test_autodetect_order(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("MINDXTRAIN_BACKEND", raising=False)
+    monkeypatch.delenv("AUTOMINDX_BACKEND", raising=False)
+    monkeypatch.setattr(operator_app, "_bankml_reachable", lambda: True)
+    # ollama first, always
+    monkeypatch.setattr(operator_app, "_ollama_reachable", lambda: True)
+    monkeypatch.setattr(operator_app, "_vllm_reachable", lambda: False)
+    assert operator_app.resolve_backend_name() == "ollama"
+    # vllm before bankml
+    monkeypatch.setattr(operator_app, "_ollama_reachable", lambda: False)
+    monkeypatch.setattr(operator_app, "_vllm_reachable", lambda: True)
+    assert operator_app.resolve_backend_name() == "vllm"
+    # bankml only when it is the one answering
+    monkeypatch.setattr(operator_app, "_vllm_reachable", lambda: False)
+    assert operator_app.resolve_backend_name() == "bankml"
+    # nothing answering: unchanged fallback
+    monkeypatch.setattr(operator_app, "_bankml_reachable", lambda: False)
+    assert operator_app.resolve_backend_name() == "vllm"
+
+
+def test_health_dispatch(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(operator_app, "_bankml_reachable", lambda: True)
+    monkeypatch.setattr(operator_app, "_bankml_first_model", lambda: "mindx-gen39-F16.gguf")
+    assert operator_app.backend_reachable("bankml") is True
+    assert operator_app.backend_first_model("bankml") == "mindx-gen39-F16.gguf"
+
+
+def test_operator_route_passes_refusal_through_as_400(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MINDXTRAIN_BACKEND", "bankml")
+
+    async def refuse(self: BankmlBackend, request: ChatRequest) -> object:
+        raise BankmlRefusal("repeat_penalty: not reproduced")
+
+    monkeypatch.setattr(BankmlBackend, "chat", refuse)
+    client = TestClient(operator_app.app)
+    r = client.post("/v1/chat/completions", json={
+        "model": "mindx-gen39", "messages": [{"role": "user", "content": "hi"}]})
+    assert r.status_code == 400
+    assert "repeat_penalty: not reproduced" in r.json()["detail"]
+
+
+def test_operator_route_returns_receipt(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MINDXTRAIN_BACKEND", "bankml")
+    real_client = httpx.AsyncClient
+    transport = httpx.MockTransport(lambda req: httpx.Response(200, json=_completion()))
+    monkeypatch.setattr(
+        "mindxtrain.operator.backends.bankml.httpx.AsyncClient",
+        lambda **kw: real_client(timeout=kw.get("timeout"), transport=transport),
+    )
+    client = TestClient(operator_app.app)
+    r = client.post("/v1/chat/completions", json={
+        "model": "mindx-gen39", "messages": [{"role": "user", "content": "hi"}]})
+    assert r.status_code == 200
+    assert r.json()["receipt"]["model_sha256"] == RECEIPT["model_sha256"]
+
+
+# ---- governance panel env chain -----------------------------------------------
+
+
+def test_panel_bankml_url_only_when_set_and_last(monkeypatch: pytest.MonkeyPatch) -> None:
+    for e in ("MINDXTRAIN_OPENAI_BASE_URL", "MINDXTRAIN_VLLM_BASE_URL",
+              "MINDXTRAIN_OLLAMA_BASE_URL", "MINDXTRAIN_BANKML_BASE_URL", "MINDXTRAIN_BACKEND"):
+        monkeypatch.delenv(e, raising=False)
+    assert P.resolve_chat_base_url() == "http://localhost:11434/v1"
+    monkeypatch.setenv("MINDXTRAIN_BANKML_BASE_URL", "http://127.0.0.1:18093/v1")
+    assert P.resolve_chat_base_url() == "http://127.0.0.1:18093/v1"
+    monkeypatch.setenv("MINDXTRAIN_OLLAMA_BASE_URL", "http://localhost:11434/v1")
+    assert P.resolve_chat_base_url() == "http://localhost:11434/v1"
+    monkeypatch.setenv("MINDXTRAIN_BACKEND", "bankml")
+    assert P.resolve_chat_base_url() == "http://127.0.0.1:18093/v1"
+
+
+# ---- console + HF Modelfile: neutral defaults are not sent ----------------------
+
+
+def test_console_wire_options_omits_engine_defaults() -> None:
+    from mindxtrain.ui import console
+
+    sent = console.wire_options(dict(console.DEFAULTS))
+    for k in ("repeat_penalty", "presence_penalty", "frequency_penalty", "mirostat",
+              "mirostat_tau", "mirostat_eta", "stop"):
+        assert k not in sent, k
+    assert sent["temperature"] == 0.7 and sent["top_k"] == 40
+    # a deliberate value is always sent — the engine then honours or refuses it, visibly
+    deliberate = console.wire_options({"repeat_penalty": 1.3, "mirostat": 2, "mirostat_tau": 4.0})
+    assert deliberate == {"repeat_penalty": 1.3, "mirostat": 2, "mirostat_tau": 4.0}
+
+
+def test_hf_published_modelfile_repeat_penalty_is_optional() -> None:
+    from mindxtrain.hf.extension import published_modelfile
+
+    default = published_modelfile("You are mindX.")
+    assert "PARAMETER repeat_penalty 1.3" in default  # default unchanged
+    assert default.endswith('PARAMETER stop "<|im_end|>"\n')
+    assert "repeat_penalty" not in published_modelfile("You are mindX.", repeat_penalty=None)

tests/test_bankml_push.py

@@ -0,0 +1,305 @@
+"""push_to_bankml: the Modelfile subset, the capability probe, and `bankml create` — no binary.
+
+subprocess.run and shutil.which are monkeypatched; the LoRA merge is replaced by a stub.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+import pytest
+from typer.testing import CliRunner
+
+from mindxtrain.deploy import bankml_push as BP
+from mindxtrain.deploy.modelfile import ModelfileSpec, render_modelfile
+
+SHA = "6b64c748d96ad26fd72402299bd27b2ae82f489bd0469498dd18eb6054058266"
+DIGEST = "c" * 64
+USAGE_035 = (
+    "usage: bankml usage [PID …]\n"
+    "       bankml create NAME -f Modelfile [--registry DIR] [--models DIR]\n"
+    "       bankml convert SAFETENSORS_DIR -o OUT.gguf [--outtype f16]\n"
+    "       bankml version"
+)
+USAGE_034 = "usage: bankml usage [PID …]\n       bankml serve FILE --fork FORK.json\n       bankml version"
+
+
+class FakeBankml:
+    """Records argv; answers `version`, `--help`, `convert`, `create`, `sha256` like bankml."""
+
+    def __init__(self, usage: str = USAGE_035, create_rc: int = 0, create_err: str = "") -> None:
+        self.calls: list[list[str]] = []
+        self.usage = usage
+        self.create_rc = create_rc
+        self.create_err = create_err
+        self.modelfile_text = ""
+
+    def __call__(self, cmd: list[str], **_: Any) -> subprocess.CompletedProcess[str]:
+        self.calls.append(list(cmd))
+        verb = cmd[1]
+        if verb == "version":
+            return subprocess.CompletedProcess(cmd, 0, "bankml 0.3.5\n", "")
+        if verb == "--help":
+            return subprocess.CompletedProcess(cmd, 1, "", self.usage)
+        if verb == "convert":
+            out = cmd[cmd.index("-o") + 1]
+            return subprocess.CompletedProcess(cmd, 0, f"{SHA}  {out}\n", "bankml convert: ok\n")
+        if verb == "create":
+            self.modelfile_text = Path(cmd[cmd.index("-f") + 1]).read_text()
+            if self.create_rc:
+                return subprocess.CompletedProcess(cmd, self.create_rc, "parsing modelfile\n",
+                                                   self.create_err)
+            name = cmd[2]
+            return subprocess.CompletedProcess(
+                cmd, 0, f"parsing modelfile\npinned {name}-F16.gguf sha256:{SHA}\n",
+                f"bankml create: {name} (digest sha256:{DIGEST}) over {name}-F16.gguf "
+                f"(sha256 {SHA})\n")
+        if verb == "sha256":
+            return subprocess.CompletedProcess(cmd, 0, f"{SHA}  {cmd[2]}\n", "")
+        raise AssertionError(cmd)
+
+
+@pytest.fixture
+def fake(monkeypatch: pytest.MonkeyPatch) -> FakeBankml:
+    f = FakeBankml()
+    monkeypatch.setattr(BP.shutil, "which", lambda name: "/usr/local/bin/bankml")
+    monkeypatch.setattr(BP.subprocess, "run", f)
+    return f
+
+
+def _merged(tmp_path: Path, arch: str = "LlamaForCausalLM") -> Path:
+    d = tmp_path / "merged"
+    d.mkdir()
+    (d / "config.json").write_text(json.dumps({"architectures": [arch]}))
+    return d
+
+
+# ---- sanitize: the refusal table ----------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("spec_kw", "needle"),
+    [
+        ({"adapter": "./lora"}, "ADAPTER"),
+        ({"template": "{{ .Prompt }}"}, "TEMPLATE"),
+        ({"parameters": {"repeat_penalty": 1.3}}, "PARAMETER repeat_penalty: penalties"),
+        ({"parameters": {"presence_penalty": 0.0}}, "PARAMETER presence_penalty"),
+        ({"parameters": {"frequency_penalty": 0.5}}, "PARAMETER frequency_penalty"),
+        ({"parameters": {"repeat_last_n": 64}}, "PARAMETER repeat_last_n"),
+        ({"parameters": {"mirostat": 2}}, "mirostat is not reproduced"),
+        ({"parameters": {"mirostat_tau": 5.0}}, "mirostat is not reproduced"),
+        ({"parameters": {"typical_p": 0.9}}, "typical_p"),
+        ({"parameters": {"num_thread": 4}}, "resource option"),
+        ({"parameters": {"num_gpu": 0}}, "resource option"),
+        ({"parameters": {"stop": "x"}}, "ModelfileSpec.stop"),
+        ({"parameters": {"weird": 1}}, "not a parameter bankml reproduces"),
+        ({"system": 'say """hi"""'}, "SYSTEM"),
+    ],
+)
+def test_sanitize_refuses_and_names_it(spec_kw: dict[str, Any], needle: str) -> None:
+    res = BP.bankml_sanitize(ModelfileSpec(from_model="x", **spec_kw))
+    assert not res.ok
+    assert any(needle in r for r in res.refusals), res.refusals
+
+
+def test_sanitize_accepts_the_subset_unchanged() -> None:
+    spec = ModelfileSpec(
+        from_model="/m", system="You are mindX.", license="Apache-2.0",
+        parameters={"temperature": 0.0, "top_k": 40, "top_p": 0.9, "min_p": 0.05, "seed": 42,
+                    "num_ctx": 2048, "num_predict": 128},
+        stop=["<|im_end|>"],
+        messages=[{"role": "user", "content": "hi"}, {"role": "assistant", "content": "hello"}],
+    )
+    res = BP.bankml_sanitize(spec)
+    assert res.ok and res.spec == spec
+    text = render_modelfile(res.spec)
+    assert "PARAMETER seed 42" in text and 'PARAMETER stop "<|im_end|>"' in text
+
+
+def test_template_passes_only_when_equal_to_base() -> None:
+    spec = ModelfileSpec(from_model="x", template="T")
+    assert BP.bankml_sanitize(spec, base_template="T").ok
+    assert not BP.bankml_sanitize(spec, base_template="U").ok
+
+
+def test_arch_checks(tmp_path: Path) -> None:
+    assert BP.check_merged_arch(_merged(tmp_path)) is None
+    q = tmp_path / "q"
+    q.mkdir()
+    (q / "config.json").write_text(json.dumps({"architectures": ["Qwen3ForCausalLM"]}))
+    assert "Llama-architecture" in (BP.check_merged_arch(q) or "")
+    assert BP.base_family_refusal("HuggingFaceTB/SmolLM2-135M") is None
+    assert "qwen" in (BP.base_family_refusal("Qwen/Qwen3-1.7B") or "")
+
+
+# ---- capability probe ----------------------------------------------------------
+
+
+def test_missing_binary(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setattr(BP.shutil, "which", lambda name: None)
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path))
+    assert res.status == "bankml_missing"
+    assert "github.com/cryptoAGI/bankml" in res.reason
+
+
+def test_too_old_bankml_is_reported_not_raised(fake: FakeBankml, tmp_path: Path) -> None:
+    fake.usage = USAGE_034
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path))
+    assert res.status == "bankml_too_old"
+    assert "0.3.5" in res.reason and "create" in res.reason
+    assert not any(c[1] == "create" for c in fake.calls)
+
+
+def test_capabilities_read_from_usage(fake: FakeBankml) -> None:
+    caps = BP.bankml_capabilities()
+    assert caps.version == "0.3.5" and caps.has_create and caps.has_convert
+
+
+# ---- push ---------------------------------------------------------------------
+
+
+def test_push_from_merged_dir(fake: FakeBankml, tmp_path: Path) -> None:
+    merged = _merged(tmp_path)
+    res = BP.push_to_bankml(
+        "HuggingFaceTB/SmolLM2-135M", "mindx-gen99", merged_dir=merged,
+        system="You are mindX.", params={"temperature": 0.0, "seed": 1}, stop=["<|im_end|>"],
+        registry_dir=tmp_path / "forks", work_dir=tmp_path / "work",
+    )
+    assert res.ok, res
+    assert res.model_sha256 == SHA and res.digest == DIGEST
+    create = next(c for c in fake.calls if c[1] == "create")
+    assert create[2] == "mindx-gen99" and "--registry" in create
+    assert fake.modelfile_text.startswith(f"FROM {merged.resolve()}")
+    assert 'SYSTEM """You are mindX."""' in fake.modelfile_text
+    assert "repeat_penalty" not in fake.modelfile_text
+
+
+def test_push_with_convert_first(fake: FakeBankml, tmp_path: Path) -> None:
+    res = BP.push_to_bankml("b", "gen7", merged_dir=_merged(tmp_path), convert=True,
+                            registry_dir=tmp_path / "forks", work_dir=tmp_path / "work")
+    assert res.ok
+    conv = next(c for c in fake.calls if c[1] == "convert")
+    assert conv[conv.index("-o") + 1].endswith("gen7-base-F16.gguf") and "--fork" in conv
+    assert fake.modelfile_text.startswith("FROM ") and "gen7-base-F16.gguf" in fake.modelfile_text
+
+
+def test_refused_params_never_reach_bankml(fake: FakeBankml, tmp_path: Path) -> None:
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path),
+                            params={"repeat_penalty": 1.3, "temperature": 0.7})
+    assert res.status == "refused"
+    assert any("repeat_penalty" in r for r in res.refusals)
+    assert fake.calls == []  # refused before even probing the binary
+
+
+def test_non_llama_merged_dir_refused(fake: FakeBankml, tmp_path: Path) -> None:
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path, "Qwen3ForCausalLM"))
+    assert res.status == "refused" and "Llama-architecture" in res.reason
+    assert not any(c[1] == "create" for c in fake.calls)
+
+
+def test_create_refusal_is_a_result(fake: FakeBankml, tmp_path: Path) -> None:
+    fake.create_rc = 2
+    fake.create_err = "bankml create: refuse: FROM /x: tokenizer not seen\n"
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path), work_dir=tmp_path / "w")
+    assert res.status == "refused"
+    assert "tokenizer not seen" in res.reason
+
+
+def test_bad_tag_and_bad_inputs(tmp_path: Path) -> None:
+    assert BP.push_to_bankml("b", "Bad:tag", merged_dir=tmp_path).status == "refused"
+    assert BP.push_to_bankml("b", "ok").status == "error"
+
+
+def test_adapter_merge_and_import_error(fake: FakeBankml, tmp_path: Path,
+                                        monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.deploy import ollama_push
+
+    def merged_stub(base: str, adapter: Path, out: Path, *, sink: Any = None) -> Path:
+        out.mkdir(parents=True)
+        (out / "config.json").write_text(json.dumps({"architectures": ["LlamaForCausalLM"]}))
+        return out
+
+    adapter = tmp_path / "checkpoint"
+    adapter.mkdir()
+    monkeypatch.setattr(ollama_push, "merge_lora_adapter", merged_stub)
+    res = BP.push_to_bankml("HuggingFaceTB/SmolLM2-135M", "g", adapter_dir=adapter,
+                            work_dir=tmp_path / "w", registry_dir=tmp_path / "r")
+    assert res.ok and res.merged_dir == tmp_path / "w" / "merged"
+
+    def no_ml(*a: Any, **k: Any) -> Path:
+        raise ImportError("push-to-ollama needs `peft` + `transformers`")
+
+    monkeypatch.setattr(ollama_push, "merge_lora_adapter", no_ml)
+    res = BP.push_to_bankml("b", "g2", adapter_dir=adapter, work_dir=tmp_path / "w2")
+    assert res.status == "merge_failed" and "uv sync --extra ml" in res.reason
+
+
+def test_register_with_mindx_uses_bankml_provider(fake: FakeBankml, tmp_path: Path,
+                                                  monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.deploy import api_client
+
+    seen: dict[str, Any] = {}
+
+    def swap(**kw: Any) -> dict[str, str]:
+        seen.update(kw)
+        return {"previous": "ollama:x", "current": "bankml:t"}
+
+    monkeypatch.setattr(api_client, "swap_mindx_fallback_model", swap)
+    res = BP.push_to_bankml("b", "t", merged_dir=_merged(tmp_path), register_with_mindx=True,
+                            work_dir=tmp_path / "w", registry_dir=tmp_path / "r")
+    assert res.ok and seen["provider"] == "bankml" and seen["model"] == "t"
+    assert res.mindx_fallback_swap == {"previous": "ollama:x", "current": "bankml:t"}
+
+
+# ---- CLI: serve --to bankml ------------------------------------------------------
+
+
+def _recipe(tmp_path: Path, **overrides: Any) -> Path:
+    import yaml
+
+    from mindxtrain.config.loader import render_recipe
+
+    data = yaml.safe_load(render_recipe("mindx_fallback_qwen3_1_5b_cpu_real"))
+    for dotted, value in overrides.items():
+        node = data
+        *parents, leaf = dotted.split(".")
+        for p in parents:
+            node = node[p]
+        node[leaf] = value
+    path = tmp_path / "run.yaml"
+    path.write_text(yaml.safe_dump(data))
+    return path
+
+
+def test_cli_refuses_quantized_config(tmp_path: Path) -> None:
+    from mindxtrain.cli.main import app
+
+    cfg = _recipe(tmp_path, **{"quantize.enabled": True, "quantize.scheme": "quark_fp8"})
+    r = CliRunner().invoke(app, ["serve", str(cfg), "--to", "bankml"])
+    assert r.exit_code == 2
+    assert "bankml refuses quantize.scheme=quark_fp8" in r.output
+
+
+def test_cli_refuses_unconvertible_family(tmp_path: Path) -> None:
+    from mindxtrain.cli.main import app
+
+    cfg = _recipe(tmp_path, **{"model.name": "Qwen/Qwen3-1.7B"})
+    r = CliRunner().invoke(app, ["serve", str(cfg), "--to", "bankml"])
+    assert r.exit_code == 2
+    assert "qwen" in r.output.lower()
+
+
+def test_cli_too_old_exits_2(tmp_path: Path, fake: FakeBankml) -> None:
+    from mindxtrain.cli.main import app
+
+    fake.usage = USAGE_034
+    ckpt = tmp_path / "ck"
+    ckpt.mkdir()
+    (ckpt / "config.json").write_text(json.dumps({"architectures": ["LlamaForCausalLM"]}))
+    cfg = _recipe(tmp_path)
+    r = CliRunner().invoke(app, ["serve", str(cfg), "--to", "bankml", "--checkpoint", str(ckpt)])
+    assert r.exit_code == 2
+    assert "bankml_too_old" in r.output

tests/test_cli_smoke.py

@@ -100,7 +100,7 @@ def test_receipt_detects_checkpoint_tamper(tmp_path, monkeypatch):
     assert result.exit_code == 2, result.stdout
 
 
-def test_serve_to_sglang_prints_command(tmp_path, monkeypatch):
+def test_serve_to_sglang_dry_run_prints_command(tmp_path, monkeypatch):
     from mindxtrain.config.loader import load_config, render_recipe
 
     monkeypatch.chdir(tmp_path)
@@ -110,7 +110,7 @@ def test_serve_to_sglang_prints_command(tmp_path, monkeypatch):
     quant = tmp_path / "out" / "runs" / cfg.meta.run_name / "quantized"
     quant.mkdir(parents=True)
 
-    result = runner.invoke(app, ["serve", str(recipe), "--to", "sglang"])
+    result = runner.invoke(app, ["serve", str(recipe), "--to", "sglang", "--dry-run"])
     assert result.exit_code == 0, result.stdout
     assert "sglang cmd" in result.stdout
     assert "sglang.launch_server" in result.stdout

tests/test_imprint_bankml.py

@@ -0,0 +1,94 @@
+"""Imprint probes through bankml: decoding sent, receipts kept, refusals typed, never mixed with
+the canonical gate. MockTransport only — no server, no torch."""
+
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from mindxtrain.eval.imprint_bankml import (
+    NOT_COMPARABLE_NOTE,
+    imprint_via_bankml,
+    probe_recall_via_bankml,
+)
+from mindxtrain.operator.backends.bankml import BankmlRefusal
+
+BASE_SHA = "1" * 64
+GEN_SHA = "2" * 64
+VOICE = ["I am mindX, the sovereign workshop of the professor."]
+ANSWERS = {
+    "smollm2-base": ("Hello, how can I help you today?", BASE_SHA),
+    "mindx-gen99": ("I am mindX, the sovereign workshop.", GEN_SHA),
+}
+
+
+def _transport(seen: list[dict[str, object]]) -> httpx.MockTransport:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/chat"
+        body = json.loads(request.content)
+        seen.append(body)
+        text, sha = ANSWERS[body["model"]]
+        return httpx.Response(200, json={
+            "model": body["model"], "message": {"role": "assistant", "content": text},
+            "done": True, "done_reason": "stop", "eval_count": 9,
+            "bankml_receipt": {"model_sha256": sha, "request_sha256": "r" * 64,
+                               "response_sha256": "s" * 64, "engine": "native"},
+        })
+
+    return httpx.MockTransport(handler)
+
+
+def test_probe_sends_greedy_seeded_unpenalised_decoding() -> None:
+    seen: list[dict[str, object]] = []
+    probe = probe_recall_via_bankml(
+        "mindx-gen99", ["Who are you?", "Say hello."], system="You are mindX.", seed=42,
+        transport=_transport(seen),
+    )
+    assert probe.utterances == ["I am mindX, the sovereign workshop."] * 2
+    assert probe.model_sha256 == [GEN_SHA]
+    assert all(r and r["model_sha256"] == GEN_SHA for r in probe.receipts)
+    for body in seen:
+        assert body["stream"] is False
+        assert body["options"] == {"temperature": 0.0, "seed": 42, "num_predict": 48}
+        msgs = body["messages"]
+        assert isinstance(msgs, list) and msgs[0] == {"role": "system", "content": "You are mindX."}
+
+
+def test_imprint_report_is_tagged_and_not_comparable() -> None:
+    res = imprint_via_bankml("smollm2-base", "mindx-gen99", ["Who are you?"], VOICE,
+                             seed=3, transport=_transport([]))
+    assert res.report.method.endswith("/bankml-greedy")
+    assert res.report.imprint_delta > 0 and res.report.imprinted
+    assert res.canonical_gate is False
+    assert res.note == NOT_COMPARABLE_NOTE and "NOT comparable" in res.note
+    assert res.decoding.seed == 3 and res.decoding.temperature == 0.0
+    assert res.before.model_sha256 == [BASE_SHA] and res.after.model_sha256 == [GEN_SHA]
+    # the whole thing serialises (it is what the CLI prints)
+    assert json.loads(res.model_dump_json())["comparable_with"] == "bankml-greedy only"
+
+
+def test_refusal_is_raised_typed_and_not_retried() -> None:
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return httpx.Response(400, json={"error": "options.weird: not an option bankML knows"})
+
+    with pytest.raises(BankmlRefusal, match="not an option bankML knows"):
+        probe_recall_via_bankml("x", ["a", "b"], transport=httpx.MockTransport(handler))
+    assert calls["n"] == 1
+
+
+def test_base_url_root_is_derived_from_v1(monkeypatch: pytest.MonkeyPatch) -> None:
+    urls: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        urls.append(str(request.url))
+        return httpx.Response(200, json={"message": {"content": "ok"}, "done": True})
+
+    monkeypatch.setenv("MINDXTRAIN_BANKML_BASE_URL", "http://127.0.0.1:18111/v1")
+    probe = probe_recall_via_bankml("x", ["a"], transport=httpx.MockTransport(handler))
+    assert urls == ["http://127.0.0.1:18111/api/chat"]
+    assert probe.receipts == [None] and probe.model_sha256 == []

tests/test_openai_server_push.py

@@ -0,0 +1,365 @@
+"""launch_openai_server / stop_openai_server: argv, readiness, refusals, stop — no real server.
+
+subprocess.Popen, shutil.which and the GPU probe are monkeypatched; readiness is answered by an
+httpx MockTransport. Nothing here installs or imports vLLM or SGLang.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+from pathlib import Path
+from typing import Any
+
+import httpx
+import pytest
+from typer.testing import CliRunner
+
+from mindxtrain.deploy import openai_server_push as OS
+
+
+class FakeProc:
+    def __init__(self, pid: int = 4242, exit_code: int | None = None) -> None:
+        self.pid = pid
+        self._exit = exit_code
+
+    def poll(self) -> int | None:
+        return self._exit
+
+
+class PopenRecorder:
+    def __init__(self, exit_code: int | None = None) -> None:
+        self.calls: list[dict[str, Any]] = []
+        self.exit_code = exit_code
+
+    def __call__(self, argv: list[str], **kw: Any) -> FakeProc:
+        self.calls.append({"argv": argv, **kw})
+        return FakeProc(exit_code=self.exit_code)
+
+
+def _client(models: list[str], *, health: int = 200, seen: list[str] | None = None) -> httpx.Client:
+    def handler(req: httpx.Request) -> httpx.Response:
+        if seen is not None:
+            seen.append(req.url.path)
+        if req.url.path == "/health":
+            return httpx.Response(health)
+        if req.url.path == "/v1/models":
+            return httpx.Response(200, json={"object": "list",
+                                             "data": [{"id": m} for m in models]})
+        return httpx.Response(404)
+
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def _adapter(tmp: Path, r: int = 8) -> Path:
+    d = tmp / "out" / "runs" / "run" / "checkpoint"
+    d.mkdir(parents=True)
+    (d / "adapter_config.json").write_text(json.dumps({"r": r}))
+    return d
+
+
+@pytest.fixture
+def env(monkeypatch: pytest.MonkeyPatch) -> PopenRecorder:
+    rec = PopenRecorder()
+    monkeypatch.setattr(OS.subprocess, "Popen", rec)
+    monkeypatch.setattr(OS.shutil, "which", lambda name: f"/usr/bin/{name}")
+    monkeypatch.setattr(OS, "detect_gpu", lambda: None)
+    monkeypatch.delenv("VLLM_CPU_KVCACHE_SPACE", raising=False)
+    return rec
+
+
+def _launch(tmp: Path, flavour: OS.Flavour = "vllm", **kw: Any) -> OS.ServerLaunchResult:
+    adapter = kw.pop("adapter_dir", None) or _adapter(tmp, kw.pop("rank", 8))
+    base: dict[str, Any] = dict(base_model="HuggingFaceTB/SmolLM2-135M", tag="mindx-gen9",
+                                run_dir=adapter.parent, adapter_dir=adapter, port=8123,
+                                ready_timeout_s=1.0, poll_interval_s=0.0, sleep=lambda _s: None)
+    base.update(kw)
+    return OS.launch_openai_server(flavour, **base)
+
+
+# ---- argv ----------------------------------------------------------------------------------
+
+
+def test_vllm_native_lora_argv_on_cpu(tmp_path: Path, env: PopenRecorder) -> None:
+    res = _launch(tmp_path, rank=24, http_client=_client(["mindx-gen9-base", "mindx-gen9"]))
+    assert res.status == "ready", res.reason
+    argv = env.calls[0]["argv"]
+    assert argv[:3] == ["/usr/bin/vllm", "serve", "HuggingFaceTB/SmolLM2-135M"]
+    s = " ".join(argv)
+    assert "--served-model-name mindx-gen9-base" in s
+    assert "--host 127.0.0.1 --port 8123" in s
+    assert "--dtype bfloat16" in s  # auto → bfloat16 on CPU
+    assert "--max-model-len 8192" in s
+    assert "--enable-lora --lora-modules mindx-gen9=" in s
+    assert argv[argv.index("--max-lora-rank") + 1] == "32"  # 24 rounded up to a vLLM choice
+    assert env.calls[0]["start_new_session"] is True
+    assert env.calls[0]["env"]["VLLM_CPU_KVCACHE_SPACE"] == "4"
+    assert res.env == {"VLLM_CPU_KVCACHE_SPACE": "4"}
+    assert res.client_model == "mindx-gen9"
+    assert res.pid_file is not None and res.pid_file.read_text().strip() == "4242"
+    launch = json.loads((res.pid_file.parent / "launch.json").read_text())
+    assert launch["argv"] == argv
+
+
+def test_sglang_native_lora_argv_on_cpu(tmp_path: Path, env: PopenRecorder,
+                                        monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(OS.importlib.util, "find_spec", lambda name: object())
+    res = _launch(tmp_path, "sglang", http_client=_client(["mindx-gen9-base"]))
+    assert res.status == "ready", res.reason
+    argv = env.calls[0]["argv"]
+    assert argv[1:3] == ["-m", "sglang.launch_server"]
+    s = " ".join(argv)
+    assert "--model-path HuggingFaceTB/SmolLM2-135M" in s
+    assert "--context-length 8192" in s and "--tp 1" in s
+    assert "--device cpu" in s and "--mem-fraction-static" not in s
+    assert "--enable-lora --lora-paths mindx-gen9=" in s
+    assert argv[argv.index("--max-lora-rank") + 1] == "8"
+    assert res.client_model == "mindx-gen9-base:mindx-gen9"
+    assert res.env == {}
+
+
+def test_extra_args_and_gpu_quantized_full_model(tmp_path: Path, env: PopenRecorder,
+                                                 monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(OS, "detect_gpu", lambda: "rocm")
+    qdir = tmp_path / "quantized"
+    qdir.mkdir()
+    res = OS.launch_openai_server(
+        "vllm", base_model="Qwen/Qwen3-8B", tag="q8", run_dir=tmp_path, model_dir=qdir,
+        quantization="fp8", extra_args=["--enforce-eager"], ready_timeout_s=1.0,
+        poll_interval_s=0.0, sleep=lambda _s: None, http_client=_client(["q8"]))
+    assert res.status == "ready", res.reason
+    argv = env.calls[0]["argv"]
+    assert argv[2] == str(qdir) and "--enable-lora" not in argv
+    assert argv[argv.index("--quantization") + 1] == "fp8"
+    assert argv[argv.index("--dtype") + 1] == "auto"
+    assert argv[-1] == "--enforce-eager"
+    assert res.env == {}  # no CPU env on a GPU host
+
+
+# ---- readiness ---------------------------------------------------------------------------
+
+
+def test_ready_polls_health_and_models_and_swaps_mindx(tmp_path: Path, env: PopenRecorder,
+                                                       monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.deploy import api_client
+
+    swapped: dict[str, Any] = {}
+
+    def fake_swap(**kw: Any) -> dict[str, str]:
+        swapped.update(kw)
+        return {"previous": "old", "current": kw["model"]}
+
+    monkeypatch.setattr(api_client, "swap_mindx_fallback_model", fake_swap)
+    paths: list[str] = []
+    res = _launch(tmp_path, http_client=_client(["mindx-gen9"], seen=paths),
+                  register_with_mindx=True, mindx_base_url="http://mindx.test")
+    assert res.status == "ready"
+    assert paths[:2] == ["/health", "/v1/models"]
+    assert swapped == {"provider": "vllm", "model": "mindx-gen9", "api_url": "http://mindx.test"}
+    assert res.mindx_fallback_swap == {"previous": "old", "current": "mindx-gen9"}
+
+
+def test_timeout_leaves_server_running(tmp_path: Path, env: PopenRecorder) -> None:
+    res = _launch(tmp_path, ready_timeout_s=0.0, http_client=_client(["something-else"]))
+    assert res.status == "timeout"
+    assert "something-else" in res.reason and "--stop" in res.reason
+    assert res.pid == 4242 and res.pid_file is not None and res.pid_file.exists()
+
+
+def test_unhealthy_vllm_never_ready(tmp_path: Path, env: PopenRecorder) -> None:
+    res = _launch(tmp_path, ready_timeout_s=0.0, http_client=_client(["mindx-gen9"], health=503))
+    assert res.status == "timeout"
+
+
+def test_exited_early_reports_log_tail(tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+                                       env: PopenRecorder) -> None:
+    env.exit_code = 1
+    res = _launch(tmp_path, http_client=_client([]))
+    assert res.status == "exited" and "code 1" in res.reason
+    assert res.pid_file is not None and not res.pid_file.exists()
+
+
+# ---- refusals ------------------------------------------------------------------------------
+
+
+def test_missing_vllm_binary(tmp_path: Path, env: PopenRecorder,
+                             monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(OS.shutil, "which", lambda name: None)
+    res = _launch(tmp_path)
+    assert res.status == "missing" and not res.ok
+    assert "uv sync --extra serve" in res.reason
+    assert env.calls == []
+
+
+def test_missing_sglang(tmp_path: Path, env: PopenRecorder,
+                        monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(OS.importlib.util, "find_spec", lambda name: None)
+    res = _launch(tmp_path, "sglang")
+    assert res.status == "missing" and "uv pip install sglang" in res.reason
+    assert env.calls == []
+
+
+def test_gpu_config_refused_without_gpu(tmp_path: Path, env: PopenRecorder) -> None:
+    qdir = tmp_path / "quantized"
+    qdir.mkdir()
+    for flavour in ("vllm", "sglang"):
+        res = OS.launch_openai_server(flavour, base_model="b", tag="t", run_dir=tmp_path,  # type: ignore[arg-type]
+                                      model_dir=qdir, quantization="fp8")
+        assert res.status == "no_gpu" and "GPU" in res.reason
+    tp = _launch(tmp_path, tensor_parallel=2)
+    assert tp.status == "no_gpu" and "tensor_parallel=2" in tp.reason
+    assert env.calls == []
+
+
+def test_already_running(tmp_path: Path, env: PopenRecorder) -> None:
+    adapter = _adapter(tmp_path)
+    sdir = OS.server_dir(adapter.parent, "vllm")
+    sdir.mkdir(parents=True)
+    (sdir / "server.pid").write_text(str(os.getpid()))
+    res = _launch(tmp_path, adapter_dir=adapter)
+    assert res.status == "already_running" and res.pid == os.getpid()
+    assert env.calls == []
+
+
+def test_merge_failure_is_a_result(tmp_path: Path, env: PopenRecorder,
+                                   monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.deploy import ollama_push
+
+    def boom(*_a: Any, **_k: Any) -> Path:
+        raise ImportError("needs peft")
+
+    monkeypatch.setattr(ollama_push, "merge_lora_adapter", boom)
+    res = _launch(tmp_path, merge=True)
+    assert res.status == "merge_failed" and "uv sync --extra ml" in res.reason
+
+
+def test_merge_serves_merged_dir(tmp_path: Path, env: PopenRecorder,
+                                 monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.deploy import ollama_push
+
+    def fake_merge(base: str, adapter: Path, out: Path, **_k: Any) -> Path:
+        out.mkdir(parents=True)
+        return out
+
+    monkeypatch.setattr(ollama_push, "merge_lora_adapter", fake_merge)
+    res = _launch(tmp_path, merge=True, http_client=_client(["mindx-gen9"]))
+    assert res.status == "ready", res.reason
+    argv = env.calls[0]["argv"]
+    assert argv[2].endswith("serve/vllm/merged") and "--enable-lora" not in argv
+    assert argv[argv.index("--served-model-name") + 1] == "mindx-gen9"
+
+
+def test_bad_inputs_never_raise(tmp_path: Path, env: PopenRecorder) -> None:
+    res = OS.launch_openai_server("vllm", base_model="b", tag="t", run_dir=tmp_path)
+    assert res.status == "error"
+    res = OS.launch_openai_server("vllm", base_model="b", tag="t", run_dir=tmp_path,
+                                  model_dir=tmp_path / "nope", ready_timeout_s=0.0)
+    assert res.status == "error" and "not a directory" in res.reason
+
+
+# ---- dry run ---------------------------------------------------------------------------------
+
+
+def test_dry_run_builds_argv_and_does_nothing(tmp_path: Path, env: PopenRecorder,
+                                              monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(OS.shutil, "which", lambda name: None)  # even with no vllm installed
+    res = _launch(tmp_path, dry_run=True)
+    assert res.status == "dry_run" and res.ok
+    assert res.argv[:2] == ("vllm", "serve")
+    assert "uv sync --extra serve" in res.reason
+    assert env.calls == []
+    assert not (tmp_path / "out" / "runs" / "run" / "serve").exists()
+
+
+# ---- stop ------------------------------------------------------------------------------------
+
+
+def _pidfile(tmp_path: Path, pid: int) -> Path:
+    sdir = OS.server_dir(tmp_path, "vllm")
+    sdir.mkdir(parents=True)
+    (sdir / "server.pid").write_text(f"{pid}\n")
+    return sdir / "server.pid"
+
+
+def test_stop_sigterms_group_and_verifies(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    pf = _pidfile(tmp_path, 777)
+    alive = {"v": True}
+    sent: list[tuple[int, int]] = []
+
+    def killpg(pid: int, sig: int) -> None:
+        sent.append((pid, sig))
+        alive["v"] = False
+
+    monkeypatch.setattr(OS, "_alive", lambda pid: alive["v"])
+    monkeypatch.setattr(OS.os, "killpg", killpg)
+    res = OS.stop_openai_server("vllm", tmp_path, sleep=lambda _s: None)
+    assert res.status == "stopped" and res.pid == 777
+    assert sent == [(777, signal.SIGTERM)]
+    assert not pf.exists()
+
+
+def test_stop_still_running(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    pf = _pidfile(tmp_path, 778)
+    monkeypatch.setattr(OS, "_alive", lambda pid: True)
+    monkeypatch.setattr(OS.os, "killpg", lambda pid, sig: None)
+    res = OS.stop_openai_server("vllm", tmp_path, timeout_s=0.0, sleep=lambda _s: None)
+    assert res.status == "still_running" and not res.ok
+    assert pf.exists()
+
+
+def test_stop_without_pidfile_or_stale(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    assert OS.stop_openai_server("sglang", tmp_path).status == "not_running"
+    pf = _pidfile(tmp_path, 779)
+    monkeypatch.setattr(OS, "_alive", lambda pid: False)
+    res = OS.stop_openai_server("vllm", tmp_path)
+    assert res.status == "not_running" and not pf.exists()
+
+
+# ---- CLI -------------------------------------------------------------------------------------
+
+
+def _recipe(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> tuple[Path, Path]:
+    from mindxtrain.config.loader import load_config, render_recipe
+
+    monkeypatch.chdir(tmp_path)
+    recipe = tmp_path / "run.yaml"
+    recipe.write_text(render_recipe("qwen3_8b_sft_lora"))
+    run_dir = tmp_path / "out" / "runs" / load_config(recipe).meta.run_name
+    ckpt = run_dir / "checkpoint"
+    ckpt.mkdir(parents=True)
+    (ckpt / "adapter_config.json").write_text(json.dumps({"r": 16}))
+    return recipe, run_dir
+
+
+def test_cli_dry_run_vllm_prefers_adapter_without_quantized(
+        tmp_path: Path, monkeypatch: pytest.MonkeyPatch, env: PopenRecorder) -> None:
+    from mindxtrain.cli.main import app
+
+    recipe, _ = _recipe(tmp_path, monkeypatch)
+    out = CliRunner().invoke(app, ["serve", str(recipe), "--to", "vllm", "--dry-run",
+                                   "--tag", "t1", "--port", "8124"])
+    assert out.exit_code == 0, out.stdout
+    assert "vllm cmd" in out.stdout and "--lora-modules" in out.stdout
+    assert "--port 8124" in out.stdout
+    assert env.calls == []
+
+
+def test_cli_missing_binary_exits_2(tmp_path: Path, monkeypatch: pytest.MonkeyPatch,
+                                    env: PopenRecorder) -> None:
+    from mindxtrain.cli.main import app
+
+    monkeypatch.setattr(OS.shutil, "which", lambda name: None)
+    recipe, _ = _recipe(tmp_path, monkeypatch)
+    out = CliRunner().invoke(app, ["serve", str(recipe), "--to", "vllm"])
+    assert out.exit_code == 2, out.stdout
+    assert "missing" in out.stdout and "uv sync --extra serve" in out.stdout
+
+
+def test_cli_stop(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    from mindxtrain.cli.main import app
+
+    recipe, _ = _recipe(tmp_path, monkeypatch)
+    out = CliRunner().invoke(app, ["serve", str(recipe), "--to", "sglang", "--stop"])
+    assert out.exit_code == 0, out.stdout
+    assert "not_running" in out.stdout