dflash-console 0.3.232__tar.gz → 0.3.240__tar.gz

{dflash_console-0.3.232 → dflash_console-0.3.240}/.gitignore

@@ -46,6 +46,7 @@ runtimes/*
 # Generated by tools/dflash-setup-ui/build.ps1 from package.json
 tools/dflash-setup-ui/SetupVersion.cs
 tools/dflash-setup-ui/bin/
+tools/dflash-setup-ui/bin_payload/
 
 # Python package build
 dist-pypi/

{dflash_console-0.3.232 → dflash_console-0.3.240}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dflash-console
-Version: 0.3.232
+Version: 0.3.240
 Summary: Local control panel and terminal CLI for DFlash stacks and local model runtimes
 Project-URL: Homepage, https://github.com/ilan4ever/Dflash-Console
 Project-URL: Repository, https://github.com/ilan4ever/Dflash-Console
@@ -674,7 +674,7 @@ from one UI, then talk to them through a single OpenAI-compatible port.
 > supported platform**; Linux and macOS are not supported or tested (see
 > [Platform support](#platform-support) below).
 
-**Developer:** ILAN AVIV · **UI:** [http://127.0.0.1:8900/](http://127.0.0.1:8900/) · **Version:** v0.3.232
+**Developer:** ILAN AVIV · **UI:** [http://127.0.0.1:8900/](http://127.0.0.1:8900/) · **Version:** v0.3.240
 
 ## Download (Windows)
 
@@ -753,7 +753,7 @@ Typical first session:
 3. For a DFlash GGUF, right-click and **Find and attach draft** if you want speculative decoding.
 4. Chat in the **Playground**, or point any OpenAI client at `http://127.0.0.1:8001/v1` with optional `X-DFlash-Client: YourApp` so **Engines** shows who is using each model.
 
-### Recent improvements (v0.3.232)
+### Recent improvements (v0.3.240)
 
 - **Engine standby** — Running toggle gates load/chat until you arm the pipeline
 - **External GPU cards** — OneVoice, LM Studio, and other apps on the GPU; compact mobile layout; loading state expires when models are ready
@@ -797,6 +797,8 @@ http://127.0.0.1:8001/v1
 ```
 
 The gateway routes chat, embeddings, TTS, and STT to the loaded engine.
+
+**Concurrent chat:** multiple OpenAI-compatible clients may call `chat/completions` on the same loaded model at once (Harness agent turn + title, or two UI actions). The Console serializes ready/JIT per engine, then lets llama-server use parallel slots. You should not see `upstream HTTP 409` for that steady-state overlap. HTTP 409 is still used for strict model mismatch (`X-DFlash-Strict-Model`), a checkpoint already loaded on a *different* engine, and stack/vision repair.
 Model names are tolerant (engine id, file name, or an alias such as `gpt-4o`).
 
 **Client identity:** send `X-DFlash-Client: YourApp` on load and chat requests so the

{dflash_console-0.3.232 → dflash_console-0.3.240}/README.md

@@ -8,7 +8,7 @@ from one UI, then talk to them through a single OpenAI-compatible port.
 > supported platform**; Linux and macOS are not supported or tested (see
 > [Platform support](#platform-support) below).
 
-**Developer:** ILAN AVIV · **UI:** [http://127.0.0.1:8900/](http://127.0.0.1:8900/) · **Version:** v0.3.232
+**Developer:** ILAN AVIV · **UI:** [http://127.0.0.1:8900/](http://127.0.0.1:8900/) · **Version:** v0.3.240
 
 ## Download (Windows)
 
@@ -87,7 +87,7 @@ Typical first session:
 3. For a DFlash GGUF, right-click and **Find and attach draft** if you want speculative decoding.
 4. Chat in the **Playground**, or point any OpenAI client at `http://127.0.0.1:8001/v1` with optional `X-DFlash-Client: YourApp` so **Engines** shows who is using each model.
 
-### Recent improvements (v0.3.232)
+### Recent improvements (v0.3.240)
 
 - **Engine standby** — Running toggle gates load/chat until you arm the pipeline
 - **External GPU cards** — OneVoice, LM Studio, and other apps on the GPU; compact mobile layout; loading state expires when models are ready
@@ -131,6 +131,8 @@ http://127.0.0.1:8001/v1
 ```
 
 The gateway routes chat, embeddings, TTS, and STT to the loaded engine.
+
+**Concurrent chat:** multiple OpenAI-compatible clients may call `chat/completions` on the same loaded model at once (Harness agent turn + title, or two UI actions). The Console serializes ready/JIT per engine, then lets llama-server use parallel slots. You should not see `upstream HTTP 409` for that steady-state overlap. HTTP 409 is still used for strict model mismatch (`X-DFlash-Strict-Model`), a checkpoint already loaded on a *different* engine, and stack/vision repair.
 Model names are tolerant (engine id, file name, or an alias such as `gpt-4o`).
 
 **Client identity:** send `X-DFlash-Client: YourApp` on load and chat requests so the

{dflash_console-0.3.232 → dflash_console-0.3.240}/api/app.py

@@ -3067,10 +3067,57 @@ def _ensure_server_ready_for_chat(
             },
         )
 
+    from core.inference_stats import is_proxy_generating
+
+    def _status_as_loaded(status: dict[str, Any]) -> dict[str, Any]:
+        if status.get('status') != 'loaded':
+            status = {**status, 'status': 'loaded'}
+        return status
+
+    def _synthetic_loaded_from_config() -> dict[str, Any]:
+        """When a probe fails under concurrent load, trust the configured id."""
+        model_id = str(server.get('model_id') or '').strip()
+        loaded = [model_id] if model_id else []
+        return {
+            **server,
+            'running': True,
+            'status': 'loaded' if loaded else 'running',
+            'booting': False,
+            'loaded_models': loaded,
+            'active_model_id': loaded[0] if loaded else '',
+            'ready_for_chat': bool(loaded),
+        }
+
     live = build_server_status(server, cfg=cfg)
+
+    # Another chat is already mid-flight on this engine: never JIT-load (that
+    # path raises model_already_loaded_elsewhere / stack-repair 409s and can
+    # stop_server under DFlash draft profiles). Share the live or configured id.
+    if is_proxy_generating(server_id):
+        if not live.get('loaded_models'):
+            live = _synthetic_loaded_from_config()
+        live = _status_as_loaded(live)
+        if required_context and cfg.get('context_auto_grow') is not False:
+            loaded_ctx = _loaded_per_slot_context(server)
+            if loaded_ctx and required_context > loaded_ctx:
+                # Growing reloads the engine — wait until the active turn ends.
+                deadline = time.time() + 180.0
+                while time.time() < deadline and is_proxy_generating(server_id):
+                    time.sleep(0.05)
+                if not is_proxy_generating(server_id):
+                    return _ensure_server_ready_for_chat(
+                        server_id,
+                        server,
+                        cfg,
+                        client_label=client_label,
+                        required_context=required_context,
+                    )
+                # Still busy after wait: serve with current context rather than 409.
+        note_engine_active_client(server_id, client_label=client_label)
+        return live
+
     if live.get('loaded_models'):
-        if live.get('status') != 'loaded':
-            live = {**live, 'status': 'loaded'}
+        live = _status_as_loaded(live)
         # Already loaded.  Auto-grow if this request needs more context than
         # the loaded model provides; otherwise share the model as-is.
         if required_context and cfg.get('context_auto_grow') is not False:
@@ -3080,6 +3127,23 @@ def _ensure_server_ready_for_chat(
         note_engine_active_client(server_id, client_label=client_label)
         return live
 
+    # Probe can return empty loaded_models while llama is busy serving another
+    # client. Retry briefly before treating the engine as idle for JIT load.
+    host = str(server.get('host') or '127.0.0.1').strip() or '127.0.0.1'
+    port = int(server.get('port') or 0)
+    if port > 0 and tcp_port_open(host, port):
+        for _ in range(6):
+            time.sleep(0.05)
+            live = build_server_status(server, cfg=cfg)
+            if live.get('loaded_models') or is_proxy_generating(server_id):
+                break
+        if is_proxy_generating(server_id) and not live.get('loaded_models'):
+            live = _synthetic_loaded_from_config()
+        if live.get('loaded_models'):
+            live = _status_as_loaded(live)
+            note_engine_active_client(server_id, client_label=client_label)
+            return live
+
     if live.get('status') == 'booting':
         return _wait_until_loaded()
 
@@ -3421,6 +3485,9 @@ async def proxy_chat_completions(server_id: str, request: Request):
     import json
     import urllib.error
 
+    _chat_gate = None
+    _chat_gate_held = False
+
     from core.chat_proxy import (
         apply_reasoning_policy,
         chat_upstream_read_timeout,
@@ -3481,6 +3548,9 @@ async def proxy_chat_completions(server_id: str, request: Request):
             body_json = None
         required_context = 0
     else:
+        server = _require_server(cfg, server_id)
+        _arm_server_engine_for_api(server_id, cfg)
+        cfg = load_config()
         server = _require_server(cfg, server_id)
         raw = await request.body()
         try:
@@ -3528,17 +3598,31 @@ async def proxy_chat_completions(server_id: str, request: Request):
         header_context = request_load_context_size(request) or 0
         body_context = chat_body_load_context_size(body_json) or 0
         required_context = max(estimated_context or 0, header_context or 0, body_context or 0)
-        live = _ensure_server_ready_for_chat(
-            server_id,
-            server,
-            cfg,
-            client_label=_request_client_label(request),
-            required_context=required_context or None,
-        )
+        from core.chat_queue import chat_server_gate
+
+        _chat_gate = chat_server_gate(server_id)
+        await _chat_gate.acquire()
+        _chat_gate_held = True
+        try:
+            live = _ensure_server_ready_for_chat(
+                server_id,
+                server,
+                cfg,
+                client_label=_request_client_label(request),
+                required_context=required_context or None,
+            )
+        except Exception:
+            if _chat_gate_held:
+                _chat_gate.release()
+                _chat_gate_held = False
+            raise
 
     api_url = str(server.get('api_url') or '')
     base = api_base_url(api_url)
     if not base:
+        if _chat_gate_held and _chat_gate is not None:
+            _chat_gate.release()
+            _chat_gate_held = False
         raise HTTPException(status_code=400, detail='engine api_url not configured')
     # Non-reasoning models never negotiate reasoning: strip reasoning_effort and
     # thinking toggles so the API returns the regular chat behaviour.
@@ -3551,6 +3635,9 @@ async def proxy_chat_completions(server_id: str, request: Request):
         attributed_client=attributed,
     )
     if reasoning_error:
+        if _chat_gate_held and _chat_gate is not None:
+            _chat_gate.release()
+            _chat_gate_held = False
         raise HTTPException(
             status_code=400,
             detail={
@@ -3595,6 +3682,9 @@ async def proxy_chat_completions(server_id: str, request: Request):
                 and requested_model
                 and not model_ids_compatible(requested_model, upstream_model_id)
             ):
+                if _chat_gate_held and _chat_gate is not None:
+                    _chat_gate.release()
+                    _chat_gate_held = False
                 raise HTTPException(
                     status_code=409,
                     detail={
@@ -3640,11 +3730,20 @@ async def proxy_chat_completions(server_id: str, request: Request):
             )
         except urllib.error.HTTPError as exc:
             mark_inference_end(server_id, client_label=client_label)
+            if _chat_gate_held and _chat_gate is not None:
+                _chat_gate.release()
+                _chat_gate_held = False
             detail = exc.read().decode('utf-8', errors='replace')
             raise HTTPException(status_code=exc.code, detail=detail) from exc
         except Exception as exc:
             mark_inference_end(server_id, client_label=client_label)
+            if _chat_gate_held and _chat_gate is not None:
+                _chat_gate.release()
+                _chat_gate_held = False
             raise HTTPException(status_code=502, detail=str(exc)) from exc
+        if _chat_gate_held and _chat_gate is not None:
+            _chat_gate.release()
+            _chat_gate_held = False
 
         keepalive_interval = 15.0
 
@@ -3717,6 +3816,9 @@ async def proxy_chat_completions(server_id: str, request: Request):
         model_id=str(live.get('active_model_id') or server.get('model_id') or ''),
         client_label=client_label,
     )
+    if _chat_gate_held and _chat_gate is not None:
+        _chat_gate.release()
+        _chat_gate_held = False
     active_model = str(live.get('active_model_id') or server.get('model_id') or '')
     disconnect_task = asyncio.create_task(
         _abort_upstream_when_client_disconnects(

{dflash_console-0.3.232 → dflash_console-0.3.240}/api/gateway.py

@@ -15,6 +15,13 @@ Routes:
     GET  /health                  gateway + console health
     GET  /                        info
 
+Concurrent OpenAI clients on the same loaded engine (for example DeepSeek Harness
+main turn + session title) are accepted: the Console queues the ready/start
+section per ``server_id``, then llama-server multiplexes within ``parallel_slots``.
+Steady-state overlaps must not return HTTP 409. Intentional 409s remain for
+``X-DFlash-Strict-Model`` mismatches, duplicate checkpoint on another engine,
+DFlash stack / vision repair, and load/unload conflicts.
+
 The default chat engine is ``config.json -> gateway_server_id`` (falls back to
 the first enabled non-embedding engine); embeddings route to the first enabled
 embedding engine. The gateway is started on the UI process lifespan, so it is
@@ -41,6 +48,7 @@ from core.gateway_routing import (
     enabled_chat_servers,
     gateway_model_aliases,
     gateway_public_model_ids,
+    is_cursor_compat_model_id,
     resolve_chat_server,
     _advertised_engine_server,
 )
@@ -51,6 +59,11 @@ logger = logging.getLogger(__name__)
 
 gateway_app = FastAPI(title='DFlash Console OpenAI Gateway', version='0.1.0')
 
+
+def gateway_cloud_chat_enabled(cfg: dict[str, Any]) -> bool:
+    """Allow active Settings cloud models unless explicitly disabled."""
+    return cfg.get('gateway_cloud_chat_enabled') is not False
+
 _FORWARD_HEADERS = {
     'content-type',
     'accept',
@@ -383,6 +396,9 @@ async def list_models() -> dict[str, Any]:
         pass
     from core.api_providers import cloud_model_entries, with_api_label
 
+    if not gateway_cloud_chat_enabled(cfg):
+        return {'object': 'list', 'data': data}
+
     for entry in cloud_model_entries(cfg):
         mid = str(entry.get('id') or '').strip()
         if not mid or mid.lower() in listed_ids:
@@ -432,14 +448,29 @@ async def _forward_chat(
         try:
             async with httpx.AsyncClient(timeout=None) as client:
                 async with client.stream('POST', url, content=body, headers=headers) as upstream:
-                    upstream.raise_for_status()
+                    if upstream.status_code >= 400:
+                        raw_err = await upstream.aread()
+                        # Re-raise as HTTPStatusError with body already buffered.
+                        response = httpx.Response(
+                            upstream.status_code,
+                            content=raw_err,
+                            request=upstream.request,
+                            headers=upstream.headers,
+                        )
+                        raise httpx.HTTPStatusError(
+                            f'Client error {upstream.status_code}',
+                            request=upstream.request,
+                            response=response,
+                        )
                     async for chunk in upstream.aiter_bytes():
                         yield chunk
         except httpx.HTTPStatusError as exc:
             status = int(exc.response.status_code or 500)
             logger.warning('gateway chat upstream HTTP %s for %s', status, url)
             try:
-                raw = await exc.response.aread()
+                raw = exc.response.content or b''
+                if not raw:
+                    raw = await exc.response.aread()
             except Exception:
                 raw = b''
             try:  # DFLASH_LOG_400_BODIES (stream path)
@@ -569,20 +600,58 @@ async def chat_completions(request: Request) -> Response:
         if not isinstance(model, str):
             model = ''
     from core.api_providers import resolve_cloud_provider_for_model
-
-    cloud_provider = resolve_cloud_provider_for_model(cfg, model)
+    from core.client_identity import resolve_client_label
+    from core.gateway_access_log import record_gateway_route
+
+    # A cloud model selected as the gateway default must also handle clients
+    # that omit ``model`` or send a Cursor-compatible placeholder.
+    configured_model = str(cfg.get('gateway_server_id') or '').strip()
+    if (
+        gateway_cloud_chat_enabled(cfg)
+        and configured_model
+        and (not model or is_cursor_compat_model_id(model))
+        and resolve_cloud_provider_for_model(cfg, configured_model) is not None
+    ):
+        model = configured_model
+
+    client_label = resolve_client_label(request)
+    cloud_provider = (
+        resolve_cloud_provider_for_model(cfg, model)
+        if gateway_cloud_chat_enabled(cfg)
+        else None
+    )
     if cloud_provider is not None:
+        provider_id = str(cloud_provider.get('id') or 'cloud')
+        record_gateway_route(
+            model=model,
+            route='cloud',
+            target=provider_id,
+            client=client_label,
+            note=str(cloud_provider.get('base_url') or ''),
+        )
         body: bytes | None = None
         if isinstance(payload, dict):
+            payload['model'] = model
             try:
                 body = json.dumps(payload).encode('utf-8')
             except Exception:
                 body = None
         if body is None:
             body = await request.body()
-        return await _forward_cloud_chat(request, provider=cloud_provider, body=body)
+        response = await _forward_cloud_chat(request, provider=cloud_provider, body=body)
+        if isinstance(response, Response):
+            response.headers['X-DFlash-Route'] = 'cloud'
+            response.headers['X-DFlash-Provider-Id'] = provider_id
+        return response
     server, upstream = await _resolve_chat_target(cfg, model)
     sid = str(server.get('id') or '')
+    record_gateway_route(
+        model=model,
+        route='local',
+        target=sid or str(server.get('label') or ''),
+        client=client_label,
+        note=str(upstream or ''),
+    )
     if sid:
         from core.engine_state import note_engine_on
 
@@ -603,6 +672,10 @@ async def chat_completions(request: Request) -> Response:
         reasoning_model = model_has_reasoning(server)
         client_label = resolve_client_label(request)
         attributed = bool(client_label) and client_label != LABEL_UNKNOWN_API
+        # External OpenAI clients (Cursor, SDKs) use the gateway without X-DFlash-Client.
+        # Treat them like attributed clients so low max_tokens disables reasoning instead of 400.
+        if not attributed:
+            attributed = True
         disable_reasoning, reasoning_error = resolve_disable_reasoning_for_chat(
             body,
             reasoning=reasoning_model,
@@ -641,6 +714,7 @@ async def chat_completions(request: Request) -> Response:
     filter_reasoning = disable_reasoning
     response = await _forward_chat(request, url, body, filter_reasoning=filter_reasoning)
     if isinstance(response, Response):
+        response.headers['X-DFlash-Route'] = 'local'
         response.headers['X-DFlash-Server-Id'] = sid
     return response
 

dflash_console-0.3.240/core/chat_queue.py

@@ -0,0 +1,55 @@
+"""Per-engine chat gates so concurrent OpenAI clients share one loaded model safely.
+
+Steady-state overlapping ``/v1/chat/completions`` (e.g. DeepSeek Harness main turn +
+session title) must not re-enter JIT load and raise HTTP 409. Callers hold the
+gate through ready-check + ``mark_inference_start`` (and opening an upstream
+stream); llama-server then multiplexes within ``parallel_slots``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Any
+
+_GATE_GUARD = threading.Lock()
+_GATES: dict[str, asyncio.Lock] = {}
+
+
+def chat_server_gate(server_id: str) -> asyncio.Lock:
+    """Return the asyncio lock for this engine id (created on first use)."""
+    sid = str(server_id or '').strip() or '_'
+    with _GATE_GUARD:
+        lock = _GATES.get(sid)
+        if lock is None:
+            lock = asyncio.Lock()
+            _GATES[sid] = lock
+        return lock
+
+
+@asynccontextmanager
+async def hold_chat_server_gate(server_id: str) -> AsyncIterator[None]:
+    """Acquire the per-engine chat gate for the critical ready/start section."""
+    lock = chat_server_gate(server_id)
+    await lock.acquire()
+    try:
+        yield
+    finally:
+        lock.release()
+
+
+def reset_chat_server_gates_for_tests() -> None:
+    """Drop all gates (unit tests only)."""
+    with _GATE_GUARD:
+        _GATES.clear()
+
+
+def chat_gate_snapshot() -> dict[str, Any]:
+    """Debug helper: which engines currently hold a gate."""
+    with _GATE_GUARD:
+        return {
+            sid: {'locked': lock.locked()}
+            for sid, lock in _GATES.items()
+        }

{dflash_console-0.3.232 → dflash_console-0.3.240}/core/config.py

@@ -905,6 +905,11 @@ def normalize_server(entry: dict[str, Any]) -> dict[str, Any]:
         result['target_path'] = target_path
     if draft_path:
         result['draft_path'] = draft_path
+    if entry.get('dflash_draft_disabled') is True:
+        result['dflash_draft_disabled'] = True
+        reason = str(entry.get('dflash_draft_disabled_reason') or '').strip()
+        if reason:
+            result['dflash_draft_disabled_reason'] = reason
     mmproj_path = str(entry.get('mmproj_path') or '').strip()
     if mmproj_path:
         result['mmproj_path'] = mmproj_path

{dflash_console-0.3.232 → dflash_console-0.3.240}/core/embedding_server.py

@@ -43,8 +43,10 @@ def llama_server_binary(*, cfg: dict[str, Any] | None = None) -> Path:
 
 
 def resolve_embedding_model_path(server: dict[str, Any], *, cfg: dict[str, Any] | None = None) -> Path:
-    entry = normalize_server(server)
-    target = str(entry.get('target_path') or '').strip()
+    # Read the field directly: this function is reachable from
+    # resolve_model_stack -> normalize_server, and re-normalizing here
+    # would recurse back into the same clamp_server_context_fields path.
+    target = str(server.get('target_path') or '').strip()
     if target:
         path = Path(target)
         if path.is_file():

dflash_console-0.3.240/core/gateway_access_log.py

@@ -0,0 +1,39 @@
+"""Append-only log of OpenAI gateway chat routing (local engine vs cloud provider)."""
+
+from __future__ import annotations
+
+import threading
+import time
+from pathlib import Path
+
+from core.log_utils import rotate_log
+
+ROOT = Path(__file__).resolve().parent.parent
+LOG_PATH = ROOT / 'logs' / 'gateway-access.log'
+_lock = threading.Lock()
+
+
+def record_gateway_route(
+    *,
+    model: str,
+    route: str,
+    target: str,
+    client: str = '',
+    status: int = 0,
+    duration_ms: float = 0.0,
+    note: str = '',
+) -> None:
+    stamp = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())
+    line = (
+        f'[{stamp}] model={model!r} route={route} target={target!r} '
+        f'status={int(status or 0)} ms={round(float(duration_ms or 0.0), 2)}'
+    )
+    if client:
+        line += f' client={client!r}'
+    if note:
+        line += f' note={note!r}'
+    with _lock:
+        LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+        rotate_log(LOG_PATH)
+        with LOG_PATH.open('a', encoding='utf-8') as fh:
+            fh.write(line + '\n')

{dflash_console-0.3.232 → dflash_console-0.3.240}/core/gateway_routing.py

@@ -25,12 +25,27 @@ def is_cursor_compat_model_id(model: str) -> bool:
 
 def default_gateway_chat_server(cfg: dict[str, Any]) -> dict[str, Any]:
     """Default chat engine for empty model or Cursor-compat aliases."""
+    wanted = str(cfg.get('gateway_server_id') or '').strip()
+    if wanted:
+        from core.api_providers import cloud_model_entries, with_api_label
+
+        for entry in cloud_model_entries(cfg):
+            if str(entry.get('id') or '').strip().lower() != wanted.lower():
+                continue
+            label = str(entry.get('label') or wanted).strip() or wanted
+            return {
+                'id': wanted,
+                'model_id': wanted,
+                'label': with_api_label(label),
+                'cloud': True,
+                'enabled': True,
+                'context_size': 8192,
+            }
     servers = enabled_chat_servers(cfg)
     if not servers:
         from fastapi import HTTPException
 
         raise HTTPException(status_code=503, detail='no enabled chat engine available')
-    wanted = str(cfg.get('gateway_server_id') or '').strip()
     if wanted:
         for server in servers:
             if str(server.get('id') or '') == wanted:

dflash_console-0.3.240/core/hf_catalog_draft.py

@@ -0,0 +1,100 @@
+"""Detect MTP / llama.cpp draft sidecars in Hugging Face catalog rows."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_DRAFT_NAME_RE = re.compile(
+    r'(?:^|[._-])(?:draft|fastmtp|mtp-head|mtp-draft)(?:[._-]|\.gguf$)',
+    re.I,
+)
+_PARAM_B_RE = re.compile(r'(\d+(?:\.\d+)?)\s*b\b', re.I)
+
+
+def _repo_slug(row: dict[str, Any]) -> str:
+    repo_id = str(row.get('id') or row.get('label') or '').strip()
+    return repo_id.split('/')[-1].lower() if '/' in repo_id else repo_id.lower()
+
+
+def _param_billions(slug: str) -> float | None:
+    matches = [float(value) for value in _PARAM_B_RE.findall(slug or '')]
+    if not matches:
+        return None
+    return max(matches)
+
+
+def _display_size_gb(row: dict[str, Any]) -> float | None:
+    size_gb = row.get('size_gb')
+    if isinstance(size_gb, (int, float)) and float(size_gb) > 0:
+        return float(size_gb)
+    return None
+
+
+def _bytes_implied_gb(row: dict[str, Any]) -> float | None:
+    try:
+        size_bytes = int(row.get('size_bytes') or 0)
+    except (TypeError, ValueError):
+        return None
+    if size_bytes <= 0:
+        return None
+    return size_bytes / (1024 ** 3)
+
+
+def catalog_draft_primary_row(
+    row: dict[str, Any],
+    *,
+    gguf_files: list[dict[str, Any]] | None = None,
+) -> bool:
+    """True when the catalog row is dominated by an MTP/draft sidecar, not a full target GGUF."""
+    if not isinstance(row, dict):
+        return False
+    if row.get('accelerator_only'):
+        return False
+    if not (row.get('has_gguf') or gguf_files):
+        return False
+
+    slug = _repo_slug(row)
+    params_b = _param_billions(slug)
+    display_gb = _display_size_gb(row)
+    bytes_gb = _bytes_implied_gb(row)
+
+    from core.hf_local_match import is_auxiliary_gguf_filename
+    from core.hf_model_fit import quant_sizes_gb
+
+    files = gguf_files if isinstance(gguf_files, list) else row.get('gguf_files')
+    non_aux = [
+        item for item in (files or [])
+        if isinstance(item, dict)
+        and not is_auxiliary_gguf_filename(str(item.get('filename') or ''))
+    ]
+    target_sizes = quant_sizes_gb(non_aux) if non_aux else []
+    max_target_gb = max(target_sizes) if target_sizes else None
+
+    if params_b and params_b >= 7:
+        if display_gb is not None and display_gb < 6:
+            return True
+        if max_target_gb is not None and max_target_gb < 6:
+            return True
+        if (
+            display_gb is not None
+            and display_gb < 6
+            and bytes_gb is not None
+            and bytes_gb >= 8
+        ):
+            return True
+
+    if non_aux and all(
+        _DRAFT_NAME_RE.search(str(item.get('filename') or ''))
+        for item in non_aux
+    ):
+        return True
+
+    if len(non_aux) == 1:
+        name = str(non_aux[0].get('filename') or '').lower()
+        if _DRAFT_NAME_RE.search(name):
+            return True
+        if 'fastmtp' in name and (max_target_gb or display_gb or 0) < 6:
+            return True
+
+    return False