Add first-class oMLX provider support

[Gautam-Diwan]

Summary

Add first-class oMLX provider support in Open Notebook Settings, similar to how Ollama is exposed as a dedicated provider.

Background

oMLX is an OpenAI-compatible local inference server for Apple Silicon (MLX). Users can already point a generic OpenAI-compatible credential at it, but a first-class provider improves discoverability, defaults, and docs—especially around the default port conflict with SurrealDB.

Proposed / implemented behavior

• First-class Settings provider entry for oMLX (alongside Ollama and other providers)
• Runtime maps oMLX credentials to Esperanto’s openai-compatible provider
• Default base URL: http://localhost:11435/v1 (avoids SurrealDB’s port 8000)
• Supports language and embedding model types
• Documentation for setup and configuration

Status

Implementation is ready on branch feature/omlx-provider and will be submitted as a draft PR linked to this issue.

Acceptance criteria

• oMLX appears as a first-class provider in Settings
• Credentials validate and resolve via openai-compatible at runtime
• Sensible default URL documented and used
• Language + embedding supported
• Docs cover install/config and the SurrealDB port note
• Relevant unit tests pass

[lfnovo]

Thanks for the well-structured proposal — and I appreciate that you've already got an implementation ready. Before you open the draft PR, though, I'd like to hold this at the product-decision level (marking as needs-vision).

The concern isn't oMLX itself — it's the precedent: a first-class Settings entry for one OpenAI-compatible server invites the same for LM Studio, vLLM, llama.cpp, LocalAI, and every future one, each becoming permanent surface in Settings, docs, and tests. The alternative worth weighing is improving the generic openai-compatible provider's UX instead (e.g. named presets/templates with sensible default base URLs and docs notes — which would cover oMLX, including the SurrealDB port-8000 conflict callout, without a dedicated provider).

I'd suggest holding off on the draft PR until we settle that direction, so your effort doesn't get burned on an approach we might not take. Will follow up here once decided — and input on the preset idea is very welcome.

[lfnovo]

Design input: esperanto (since v2.20.0) ships exactly the mechanism this needs — OpenAI-compatible provider profiles (OpenAICompatibleProfile in providers/llm/profiles.py). A profile is a declarative alias over the openai-compatible provider: name, default base_url, api_key_env, optional base_url_env, default model. DeepSeek, xAI and DashScope are already implemented this way, and new ones can be registered at runtime via AIFactory.register_openai_compatible_profile(...) — no new provider class in esperanto, no fork of the provider list.

So the likely shape for oMLX is: a profile (built-in upstream or registered by Open Notebook at startup) with base_url="http://localhost:11435/v1", plus the Settings/docs exposure here. That resolves the precedent concern from my earlier comment — profiles are cheap, declarative, and don't multiply provider classes.

One real gap to resolve in design: profiles currently apply to language models only — AIFactory.create_language() consults the profile registry, create_embedding() doesn't. Since this issue wants language and embedding, either (a) esperanto extends profiles to the embedding factory (probably the right upstream fix), or (b) the embedding side maps to the generic openai-compatible embedding provider with the oMLX base URL. To be settled in the design pass.

[lfnovo]

Direction settled: oMLX support will go through esperanto's OpenAI-compatible profile mechanism, not an Open Notebook-internal alias.

Plan:

1. Upstream (blocking): feat: add built-in oMLX profile + requires_api_key flag for no-auth endpoints esperanto#228 — extend profiles to the embedding factory (today they only apply to create_language()) and add an omlx profile (base_url_env=OMLX_API_BASE, api_key_env=OMLX_API_KEY).
2. This repo (after upstream lands): thin exposure — omlx provider entry in Settings, docs (including the port-8000/SurrealDB conflict note, default http://localhost:11435/v1), model discovery. No provider remapping, no OPENAI_COMPATIBLE_* env mirroring.

PR #1049 was closed with a full explanation — the implementation quality was good, but it created the identity inside Open Notebook via runtime remapping, which is the design this issue paused. The SSRF-hardening work from that PR (prepare_pinned_http_target) is invited back as a standalone PR.

Updating the label to reflect that this is now designed and blocked on the upstream issue.

[Gautam-Diwan]

Following up on @lfnovo's direction (profile in Esperanto first; thin Open Notebook exposure after) and the close note on #1049:

Status of salvage work from #1049

• SSRF hardening standalone PR: fix: pin DNS for outbound provider HTTP requests #1063
• .env.example OLLAMA_API_BASE one-liner: fix: correct Ollama env var name in .env.example #1064

oMLX product work

• Leaving this issue open as planned, blocked on upstream lfnovo/esperanto#228 (embeddings + omlx profile).
• Once that lands, I'll open the thin Open Notebook PR (Settings entry + docs including the SurrealDB port-8000 note / default http://localhost:11435/v1) with no remapping / no OPENAI_COMPATIBLE_* env mirroring.

[Gautam-Diwan]

Implementation for the thin Open Notebook exposure is up, following Esperanto #228 (merged in esperanto#239):

• Native omlx provider identity via Esperanto’s built-in OpenAICompatibleProfile — no Open Notebook remapping to openai-compatible, no OPENAI_COMPATIBLE_* env mirroring (the approach rejected in feat: add first-class oMLX provider #1049).
• Settings entry, default http://localhost:11435/v1, optional API key, language + embedding, connection test + /v1/models discovery, docs.

New PR (fresh branch from main, not a reopen of #1049): will link here once created.

Note: Issue is currently unassigned. Esperanto oMLX is on main but not yet on PyPI (latest release still 2.24.0); the PR pins Esperanto to the #239 merge commit until a release ships.

[Gautam-Diwan]

New PR opened (clean branch from main, no remapping): #1164

Follows Esperanto #228 — native omlx profile identity only.