chore(release): v0.4.2 — embedding NaN fix + configurable max_tokens + MXFP8 infrastructure

Fixes the `Qwen3-Embedding-4B-4bit-DWQ` all-NaN embedding bug (P@1 0.200
→ 1.000 on the 25-prompt labeled-corpus quality eval). MLX's DWQ rebuild
ships scales/biases as BF16 instead of the original AFFINE F16 convention;
the embedding loader was reading both as F16, which silently misinterpreted
the 5-vs-8-bit exponent layout and propagated NaN through every projection.
Loader now dispatches on the safetensors dtype and handles both formats.

Other user-visible changes:
- Configurable default `max_tokens` in the CONTEXT card (schema v6 → v7).
  Was hardcoded server-side at 2048 for any chat/completion request that
  omitted the field; now mirrors a UI input via `LUMEN_DEFAULT_MAX_TOKENS`.
  Existing configs migrate stamped at 2048 so behavior is preserved.
- `scan_local` now strictly matches the HuggingFace repo-id grammar
  (`[A-Za-z0-9._-]+`). Filters Finder duplicates (`mlx-community--…-8bit 2`)
  and other scratch dirs so the periodic update check stops emitting 401
  Unauthorized log lines for repo ids that aren't real.

Under-the-hood (no catalog recommendation yet):
- Full MXFP8 (OCP) Metal kernel — E4M3 elements + E8M0 byte scales,
  group_size=32, no biases. Naive + qmv_fast cooperative simdgroup
  variants; GPU↔CPU bit-identical parity on random inputs. Loader path
  + `QuantProj::M8` wired through so a future `mxfp8` catalog entry
  works end-to-end without further plumbing. Validated against
  `mlx-community/Qwen3-Embedding-4B-mxfp8` (P@1 = 1.000, mean cosine
  0.948 vs the DWQ 4B reference) — implementation is correct but DWQ is
  faster (2.8×) and uses half the memory at equivalent quality, so the
  catalog stays DWQ-only for the 4B slot.

Author: rabbitson87

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "lumen-app"
-version = "0.4.1"
+version = "0.4.2"
 edition.workspace = true
 rust-version.workspace = true
 license.workspace = true

crates/lumen-app/Cargo.toml

@@ -1,7 +1,7 @@
 {
   "name": "lumen-app-frontend",
   "private": true,
-  "version": "0.4.1",
+  "version": "0.4.2",
   "type": "module",
   "scripts": {
     "predev": "cargo build --manifest-path ../../../Cargo.toml -p lumen-server --release",

crates/lumen-app/frontend/package.json

@@ -938,6 +938,21 @@
         {t("context.hint.prefill")}{#if config.quant.turboquant_enabled}, ~{turboquantKvRatio.toFixed(1)}×{/if}).
         {t("context.hint.max.env")} <code class={inlineCode}>LUMEN_PREFILL_CHUNK</code>.
       </div>
+
+      <div class={kvRow}>
+        <span class="dim">{t("context.defaultMaxTokens")}</span>
+        <input
+          type="number"
+          min="1"
+          step="256"
+          bind:value={config.context.default_max_tokens}
+          onchange={saveContext}
+        />
+      </div>
+      <div class={ctxHint}>
+        {t("context.hint.defaultMaxTokens")}
+        {t("context.hint.max.env")} <code class={inlineCode}>LUMEN_DEFAULT_MAX_TOKENS</code>.
+      </div>
     {/if}
   </section>
 

crates/lumen-app/frontend/src/App.svelte

@@ -48,6 +48,11 @@ export interface ContextConfig {
   max: number;
   sliding: number;
   prefill: number;
+  /** Default `max_tokens` (generation budget) for OpenAI-compatible chat /
+   *  completion requests that omit the field. Default 2048. Emitted as the
+   *  `LUMEN_DEFAULT_MAX_TOKENS` env var; explicit `max_tokens` in the request
+   *  body always wins. */
+  default_max_tokens: number;
 }
 
 export type BackendMode = "auto" | "candle" | "mlx-native" | "mlx-pyo3";

crates/lumen-app/frontend/src/lib/api.ts

@@ -94,6 +94,7 @@ export const en: Record<string, string> = {
   "context.max": "Max",
   "context.sliding": "Sliding",
   "context.prefill": "Prefill",
+  "context.defaultMaxTokens": "Default max_tokens",
   "context.turboquant.on": "TurboQuant:",
   "context.turboquant.off": "· baseline KV memory (no compression)",
   "context.recommended": "Recommended max on this Mac",
@@ -183,6 +184,8 @@ export const en: Record<string, string> = {
     "Stacks with TurboQuant — sliding bounds which tokens are kept, TurboQuant compresses how they're stored.",
   "context.hint.prefill":
     "Prompt-processing chunk cap. Server rejects prompts longer than this with a \"prompt too large\" error. Larger = accepts long prompts but more peak memory during prefill (attention QK·T = chunk × KV",
+  "context.hint.defaultMaxTokens":
+    "Generation budget applied to OpenAI-compatible chat / completion requests that omit `max_tokens`. Request bodies that explicitly set `max_tokens` always win — this is only the server-side fallback.",
 
   // ── SERVER memory explainer ─────────────────────────────────────
   "server.memory.explainer.intro":

crates/lumen-app/frontend/src/messages/en.ts

@@ -89,6 +89,7 @@ export const ko: Record<string, string> = {
   "context.max": "최대",
   "context.sliding": "슬라이딩",
   "context.prefill": "프리필",
+  "context.defaultMaxTokens": "기본 max_tokens",
   "context.turboquant.on": "TurboQuant:",
   "context.turboquant.off": "· 기본 KV 메모리 (압축 없음)",
   "context.recommended": "이 Mac 권장 최대",
@@ -177,6 +178,8 @@ export const ko: Record<string, string> = {
     "TurboQuant와 함께 적용됩니다 — 슬라이딩은 어떤 토큰을 유지할지 결정, TurboQuant는 어떻게 저장할지 결정.",
   "context.hint.prefill":
     "프롬프트 처리 청크 상한. 이 값보다 긴 프롬프트는 \"prompt too large\" 오류로 거부됩니다. 클수록 긴 프롬프트를 받지만 프리필 동안 피크 메모리도 증가 (어텐션 QK·T = 청크 × KV",
+  "context.hint.defaultMaxTokens":
+    "OpenAI 호환 chat/completion 요청에서 `max_tokens`가 빠졌을 때 서버가 적용하는 생성 토큰 예산. 요청 본문에 `max_tokens`가 명시되어 있으면 그 값이 항상 우선합니다 — 이 값은 서버 측 폴백일 뿐입니다.",
 
   // ── SERVER 메모리 설명 ──────────────────────────────────────────
   "server.memory.explainer.intro":

crates/lumen-app/frontend/src/messages/ko.ts

@@ -9,7 +9,7 @@ use serde::{Deserialize, Serialize};
 /// chain in `migrate_in_place` is keyed by this number — incrementing it
 /// without adding a corresponding migration step is a deserialization
 /// landmine for anyone with an older config.toml.
-pub const CURRENT_SCHEMA_VERSION: u32 = 6;
+pub const CURRENT_SCHEMA_VERSION: u32 = 7;
 
 /// On-disk persistent config. Lives at
 /// `~/Library/Application Support/ai.lumen.app/config.toml` on macOS.
@@ -162,6 +162,16 @@ pub struct ContextConfig {
     pub max: usize,
     pub sliding: usize,
     pub prefill: usize,
+    /// Default `max_tokens` (generation budget) applied to chat / completion
+    /// requests that omit the field. Emitted as `LUMEN_DEFAULT_MAX_TOKENS`;
+    /// `lumen-server` reads it in `types.rs::default_max_tokens()`. `0` means
+    /// "unbounded — generate until EOS / stop / context budget".
+    #[serde(default = "default_default_max_tokens")]
+    pub default_max_tokens: u32,
+}
+
+fn default_default_max_tokens() -> u32 {
+    2048
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -258,6 +268,7 @@ impl Default for PersistentConfig {
                 max: 81920,
                 sliding: 1024,
                 prefill: 40960,
+                default_max_tokens: 2048,
             },
             advanced: AdvancedConfig {
                 backend_mode: BackendMode::Auto,
@@ -411,6 +422,19 @@ fn migrate_in_place(cfg: &mut PersistentConfig) {
         }
         cfg.schema_version = 6;
     }
+    // v6 -> v7: introduced `context.default_max_tokens` so the OpenAI-compat
+    // server-side default for chat/completion `max_tokens` (when the client
+    // omits the field) is user-configurable instead of hardcoded to 2048.
+    // Existing configs that serialized without the field deserialize as 0
+    // (serde's u32 default) — that would silently mean "unbounded" and is a
+    // behaviour change from v6. Stamp the legacy 2048 default explicitly so
+    // upgraders see no surprise.
+    if cfg.schema_version < 7 {
+        if cfg.context.default_max_tokens == 0 {
+            cfg.context.default_max_tokens = 2048;
+        }
+        cfg.schema_version = 7;
+    }
     // Future migrations append here.
 }
 

crates/lumen-app/src/config.rs

@@ -77,6 +77,31 @@ fn read_sha_marker(model_dir: &Path) -> Option<String> {
 ///    actual files under `snapshots/<commit_sha>/` (symlinks to `blobs/`).
 ///    `id` = `<org>/<repo>`.
 ///
+/// HuggingFace Hub repo id grammar: `<org>/<repo>` where each segment is
+/// `[A-Za-z0-9._-]+`. Rejects empty parts, missing slash, multiple slashes,
+/// and any character HF wouldn't accept in a repo URL — notably whitespace
+/// (Finder's "Item 2" duplicate convention) which would 401 every update
+/// check and never resolve to a real Hub URL.
+fn is_valid_hf_repo_id(id: &str) -> bool {
+    let mut parts = id.split('/');
+    let (Some(org), Some(repo), None) = (parts.next(), parts.next(), parts.next()) else {
+        return false;
+    };
+    !org.is_empty() && !repo.is_empty() && is_hf_segment(org) && is_hf_segment(repo)
+}
+
+/// Plain flat (no-org) local-only model directory name. Same character class
+/// as an HF segment — no whitespace, no slash. Skips Finder duplicates and
+/// scratch dirs that would otherwise surface as bogus model entries.
+fn is_valid_flat_id(name: &str) -> bool {
+    !name.is_empty() && is_hf_segment(name)
+}
+
+fn is_hf_segment(s: &str) -> bool {
+    s.chars()
+        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-')
+}
+
 /// `catalog` is consulted to set the `supported` / `label` flags.
 pub fn scan_local(models_dir: &Path, catalog: &Catalog) -> Result<Vec<ModelEntry>> {
     if !models_dir.exists() {
@@ -100,6 +125,9 @@ pub fn scan_local(models_dir: &Path, catalog: &Catalog) -> Result<Vec<ModelEntry
         let (id, scan_dir) = if let Some(rest) = name.strip_prefix("models--") {
             // hf-hub cache layout: `models--<org>--<repo>/snapshots/<sha>/<files>`
             let id = rest.replacen("--", "/", 1);
+            if !is_valid_hf_repo_id(&id) {
+                continue;
+            }
             let snapshot = resolve_hf_snapshot(&path);
             match snapshot {
                 Some(snap) => (id, snap),
@@ -111,9 +139,22 @@ pub fn scan_local(models_dir: &Path, catalog: &Catalog) -> Result<Vec<ModelEntry
             // canonical `<org>/<repo>` id so catalog matching works the
             // same as for hf-hub-style caches.
             let id = name.replacen("--", "/", 1);
+            // Strict HF naming check filters Finder duplicates (`… 2`),
+            // .DS_Store siblings, and anything else that wouldn't round-trip
+            // to a valid Hub URL. Avoids spamming HF API with 401s on the
+            // periodic update check.
+            if !is_valid_hf_repo_id(&id) {
+                continue;
+            }
             (id, path.clone())
         } else {
             // Plain flat (README convention, no org prefix in dir name).
+            // Skip names with whitespace or other non-HF-id characters —
+            // these are almost always Finder duplicates or scratch dirs,
+            // never real local-only models.
+            if !is_valid_flat_id(&name) {
+                continue;
+            }
             (name, path.clone())
         };
 

crates/lumen-app/src/models.rs

@@ -739,6 +739,13 @@ fn apply_env(
     if cfg.context.sliding > 0 {
         cmd.env("LUMEN_SLIDING_WINDOW", cfg.context.sliding.to_string());
     }
+    // Default `max_tokens` budget when the API client omits the field on
+    // /v1/chat/completions or /v1/completions. `0` is forwarded as "unbounded
+    // — generate until EOS / stop / context budget".
+    cmd.env(
+        "LUMEN_DEFAULT_MAX_TOKENS",
+        cfg.context.default_max_tokens.to_string(),
+    );
 
     // ── Advanced ───────────────────────────────────────────────────
     match cfg.advanced.backend_mode {
@@ -833,6 +840,7 @@ pub const TYPED_ENV_KEYS: &[&str] = &[
     "LUMEN_MAX_CTX",
     "LUMEN_SLIDING_WINDOW",
     "LUMEN_PREFILL_CHUNK",
+    "LUMEN_DEFAULT_MAX_TOKENS",
     "LUMEN_WIRED_LIMIT_BYTES",
     "LUMEN_MLX_BACKEND",
     "LUMEN_SPEC",