Skip to content

v1.0_plan.md

Latest commit

 

History

History
120 lines (97 loc) · 4.41 KB

v1.0_plan.md

File metadata and controls

120 lines (97 loc) · 4.41 KB
Raw

v1.0 Plan: Stable Scope and Release Readiness

v1.0 is the first stable documentation milestone for MLX Server Manager after the v0.1 through v0.9 implementation and distribution work.

The app remains Direct Mode:

OpenAI-compatible client -> mlx_lm.server

The app manages a local mlx_lm.server process but does not proxy inference traffic and does not provide Chat UI.

Goals

  • Clarify the README for stable users.
  • Document the stable v1.0 feature scope.
  • Document known limitations.
  • Document first-run workflow.
  • Document release and unsigned zip asset expectations.
  • Add a v1.0 stable regression checklist.
  • Preserve all safety boundaries from v0.1 through v0.9.

Stable Scope

v1.0 includes:

  • Start, Stop, and Restart for app-managed mlx_lm.server.
  • Managed-process-only Stop and Restart.
  • Port availability check.
  • Ready check through /v1/models.
  • Settings save and restore.
  • Model profile add, edit, delete, and selection.
  • Model switching with Restart-required state.
  • Menu bar quick actions.
  • Logs readability improvements.
  • Copy Logs.
  • Diagnostics summary and Copy Diagnostics Summary.
  • OpenAI-compatible connection settings copy.
  • Unsigned .app zip distribution documentation.

First-Run Workflow

  1. Prepare mlx-lm outside the app.
  2. Start MLX Server Manager.
  3. Configure mlx_lm.server executable path in Settings.
  4. Configure or add a Model Profile.
  5. Run Setup Diagnostics.
  6. Start the managed server.
  7. Confirm Ready status via /v1/models.
  8. Copy OpenAI-compatible connection settings.
  9. Configure an external OpenAI-compatible client.
  10. Stop or Restart from the app or menu bar when needed.

Release Documentation

v1.0 should point users to:

  • The unsigned local-use zip asset policy.
  • Gatekeeper and no-notarization caveats.
  • The requirement to provide mlx-lm and model files separately.
  • The rule that runtime settings, model profiles, model files, Hugging Face cache, logs, secrets, and build artifacts are not bundled or committed.

Non-Goals

  • Proxy mode.
  • Chat UI.
  • LAN Web UI.
  • App Intents.
  • Auto unload.
  • Hugging Face download manager.
  • Model download.
  • Model deletion.
  • Hugging Face cache deletion.
  • Multiple concurrent server management.
  • Multiple model simultaneous launch.
  • RAG.
  • Embedding manager.
  • Tool-call translation.
  • Telemetry, analytics, crash reporting, external log sending, or cloud logging.
  • Persistent file logging.
  • Notarization, Developer ID signing, DMG, App Store distribution, Homebrew cask, auto updater, or CI/CD release automation.

Safety Boundaries

  • Direct Mode only.
  • The app is not in the inference request path.
  • The app does not execute /v1/chat/completions.
  • Diagnostics are limited to safe checks and /v1/models readiness.
  • Stop and Restart target only the app-managed process.
  • Swift code must not use pkill, killall, or pgrep.
  • The app must not delete model files or Hugging Face cache.
  • The app must not handle secrets or tokens.
  • .env, HF_TOKEN, runtime settings, model files, .app, .zip, .dSYM, and build artifacts must stay outside Git.
  • Documentation and Swift code must not include personal fixed paths.

Exit Criteria

  • README describes the stable product clearly.
  • Stable scope and known limitations are documented.
  • v1.0 testing checklist is available.
  • Release note template covers Direct Mode, managed server behavior, diagnostics/logging, unsigned zip asset, known limitations, and safety boundaries.
  • Final Debug and Release builds pass before tagging.
  • Unsigned zip asset verification passes before publishing.

Final Verification Preparation

Before tagging v1.0.0, verify:

  • Git status is clean.
  • git diff --check passes.
  • v1.0.0 does not already exist.
  • Tags v0.1.0 through v0.9.0 exist.
  • Debug and Release builds succeed.
  • Start, Stop, Restart, Port Check, Ready Check, Diagnostics, Logs, model profiles, model switching, menu bar actions, and connection copy pass manual regression.
  • Ready Check and Diagnostics remain limited to /v1/models.
  • /v1/chat/completions remains copy-only text and is not executed by the app.
  • Stop and Restart remain limited to the app-managed process.
  • The unsigned zip asset contains only MLXServerManager.app/.
  • Runtime settings, model profiles, model files, Hugging Face cache, logs, secrets, .app, .zip, .dSYM, and build artifacts are not tracked by Git.
  • README, docs, AGENTS, and Swift code contain no personal fixed paths.