UI: Server lifecycle — Start/Stop, network, copyable OpenAI endpoints

[Som23Git]

Summary

Parent: #33

Build the MVP control surface: one primary action to start and stop a local VeloxQuant-backed inference server, plus the network + endpoint chrome users expect from oMLX's Server tab.

Why this is its own issue

Start/Stop is the adoption hook. Method education and live KV telemetry are valuable but should not block a working launcher. This issue is the thinnest vertical slice that makes VeloxQuant runnable for non-Python users.

Depends on

• #27 — backend must expose something the UI can spawn (thin veloxquant serve → mlx_lm.server wrapper at minimum). Until RFC: OpenAI-compatible server — mlx_lm.server already serves 35/40 caches, but compression is accounting-only at runtime #27 decides (d) vs documented accounting-only launcher, the UI must show an honest status banner matching whatever the server can actually promise.

Scope (MVP)

Header / lifecycle

• Status pill: Stopped / Starting / Running / Error
• Primary button: Start Server ↔ Stop Server
• Show app/library version (e.g. VeloxQuant-MLX 0.41.0)
• Surface subprocess stderr on failure (port in use, unsupported method, model load OOM)

Network

• Listen address: 127.0.0.1 (default, safer) and 0.0.0.0 (LAN)
• Port (default 8000); changing while running prompts restart
• Persist settings across launches (local config file)

API endpoints (copy to clipboard)

• OpenAI-compatible: http://127.0.0.1:{port}/v1
• Health: http://127.0.0.1:{port}/health
• Include metrics / Anthropic base URL only if the backend actually serves them (do not invent endpoints)

Minimal model bind

• Model id or local path required before Start (cannot start an empty server)
• Optional: last-used model remembered

Default generation knobs (lightweight; deeper method UI is #35 placeholder)

• Max tokens, temperature, top-p, context window — passed through as server/profile defaults
• Method + bits fields present but may be a simple dropdown until the method panel lands

Non-goals

• Full method library browser / paper-deviation callouts → child method UI
• Live compression charts / /v1/kv/stats dashboard → child telemetry UI
• Model download manager, appearance themes, security/auth panels
• Reimplementing mlx_lm.server inside the UI process

Acceptance criteria

1. Clicking Start Server brings health endpoint to 200 with a small mlx-community model and a RFC: OpenAI-compatible server — mlx_lm.server already serves 35/40 caches, but compression is accounting-only at runtime #27-supported method.
2. Clicking Stop Server terminates the child process; port is free afterward.
3. Copy buttons produce the correct URLs for the configured host/port.
4. Starting with an unsupported method (RFC: OpenAI-compatible server — mlx_lm.server already serves 35/40 caches, but compression is accounting-only at runtime #27 crash tier, e.g. standalone caches without adapter) fails at Start with a readable error — no silent fp16 fallback.
5. README / docs-site getting-started links this as the non-library first-run path once shipped.

Implementation notes

• Prefer managing a subprocess (veloxquant serve … or equivalent) over embedding HTTP in the UI process.
• Keep optional packaging: do not force UI deps on the core PyPI package (#33 stack discussion).

Reference

oMLX 0.5.3 → Settings → Server: status header, Network (listen + port), API Endpoints list with copy icons, Default Profile knobs.

[Som23Git]

Cross-links (filed): method panel → #35; telemetry → #36; parent → #33.

[rajveer43]

Implemented in #37 — Start/Stop lifecycle, network settings, copyable endpoints, log pane, and honest refusal of crash-tier methods.

Acceptance criteria status:

1. ✅ Start Server brings the endpoint up with a small mlx-community model and a RFC: OpenAI-compatible server — mlx_lm.server already serves 35/40 caches, but compression is accounting-only at runtime #27-supported method (verified end-to-end on Llama-3.2-1B-Instruct-4bit).
2. ✅ Stop Server terminates the child; port is free afterward.
3. ✅ Copy buttons produce correct URLs — rendered from the server's own READY handshake, so the panel cannot advertise an endpoint the backend doesn't serve.
4. ✅ Crash-tier methods fail at Start with a readable reason — no silent fp16 fallback. They stay visible but disabled in the UI rather than being hidden.
5. ✅ README links the panel as the non-library first-run path.

Note: /health is not exposed, because mlx_lm.server doesn't serve it. Rather than invent it, the panel uses the VELOXQUANT_READY stdout handshake to distinguish "starting" from "running" — which is also more truthful than a health poll, since it can't report ready mid-model-load.