@rolemodel/omlx — Dynamic oMLX Model Discovery

This extension auto-discovers models from an oMLX (OpenAI-compatible) endpoint and registers them with the pi provider system. It provides an interactive UI via /omlx-models to toggle model visibility — hide models you don't need without deleting configuration. It is an alias layer on top of pi's provider system: it fetches available models from your omlx server, registers them, and lets you show/hide them interactively.

Table of Contents

• Quick Start
• Provider Configuration
• Model Visibility Command
• Configuration Options
• Model Overrides
• Exclusion Patterns

---

Quick Start

# Install this extension
pi install npm:@rolemodel/pi-omlx

Set up your omlx provider in ~/.pi/agent/models.json with your API key and endpoint:

{
  "providers": {
    "omlx": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "<api-key>",
      "autoDiscover": true
    }
  }
}

Reload and start using discovered models:

/reload

---

Provider Configuration

The extension looks for an omlx provider entry under providers in ~/.pi/agent/models.json. Create the file if it doesn't exist, or add the omlx key to an existing providers object.

Minimal Setup (Authentication)

The only required fields for authentication are baseUrl and apiKey:

{
  "providers": {
    "omlx": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "<api-key>"
    }
  }
}

The apiKey is the credential used to authenticate requests to your omlx server. Visit the admin dashboard for oMLX and navigate to the global settings to find the api key or check "Skip API key verification" to by pass security check.

In oMLX it is possible to disable API key verification which would allow omitting the API key from the config file. This is not recommended when exposing oMLX to the internet but is perfectly fine for local use.

Full Configuration

{
  "providers": {
    "omlx": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "<api-key>",
      "api": "openai-completions",
      "autoDiscover": true,
      "excludePatterns": [],
      "modelOverrides": {},
      "defaultContextWindow": 256000,
      "defaultMaxTokens": 56000
    }
  }
}

---

Model Visibility Command

Run /omlx-models to open an interactive panel that lists all discovered models with their visibility status. This toggles the model's inclusion in the /model selector to limit visible models and narrow down long lists of downloaded models.

oMLX Model Visibility
────────────────────────────
> [✓] llama-3-70b-instruct
  [✓] mistral-large-24b
  [✓] phi-3-mini
  [✗] tiny-model-not-needed
  [✓] custom-finetuned-model

          [Cancel]            [Save]
↑↓ navigate • enter toggle/save • esc cancel

• ↑↓ — Navigate the list
• Enter — Toggle a model's visibility (✓ = visible, ✗ = hidden)
• [Save] — Write the changes back to ~/.pi/agent/models.json
• [Cancel] — Discard changes and exit
• Escape — Exit without saving

The extension respects exclusion patterns (see below), so models excluded by glob rules appear pre-hidden in the UI.

---

Configuration Options

Option	Type	Default	Description
baseUrl	string	http://localhost:8000/v1	The omlx server endpoint. Must include the /v1 prefix for OpenAI-compatible API.
apiKey	string	(none)	Required. Your API key for authenticating requests. Stored in ~/.pi/agent/models.json.
api	string	"openai-completions"	The API mode to use. Determines how requests are formatted when calling the endpoint.
autoDiscover	boolean	true	When true, the extension fetches available models from GET /v1/models on startup and on /reload. Set to false to skip discovery.
excludePatterns	string[]	[]	Glob patterns to exclude specific models from discovery and the visibility list.
modelOverrides	object	{}	Per-model overrides to customize properties like name, contextWindow, maxTokens, cost, etc.
defaultContextWindow	number	256000	Default context window in tokens for discovered models that don't specify one.
defaultMaxTokens	number	56000	Default max output tokens for discovered models.

---

Model Overrides

When you need custom properties for a specific model (e.g., a finetuned model with a smaller context window or a multimodal model), add it to modelOverrides keyed by model ID:

{
  "providers": {
    "omlx": {
      "baseUrl": "http://localhost:8000/v1",
      "apiKey": "<api-key>",
      "modelOverrides": {
        "custom-llama-70b": {
          "name": "Custom Llama 70B",
          "contextWindow": 128000,
          "maxTokens": 8192,
          "reasoning": true,
          "input": ["text", "image"],
        },
        "custom-mistral-8x7b": {
          "name": "Mistral 8x7B MoE",
          "maxTokens": 4096,
          "thinkingLevelMap": {
            "minimal": null,
            "low": null,
            "medium": "medium",
            "high": "high",
            "xhigh": null
          }
        }
      }
    }
  }
}

Available Override Properties (including thinkingLevelMap)

Property	Type	Default	Description
name	string	Model ID	Display name shown in the model selector.
reasoning	boolean	false	Whether this is a reasoning model (affects prompt formatting).
input	string[]	["text"]	Supported input modalities. Use ["text", "image"] for multimodal.
contextWindow	number	defaultContextWindow	Max context tokens.
maxTokens	number	defaultMaxTokens	Max output tokens.
thinkingLevelMap	object	defaultThinkingLevelMap	Map pi thinking levels to provider effort values. Set to null to hide.
api	string	(inherited)	API override for this specific model.
headers	object	{}	Additional HTTP headers to include in requests for this model.
compat	string	(none)	Compatibility mode string.

Overrides are applied after discovery, so they work for both discovered models and manually listed ones.

---

Exclusion Patterns

Use excludePatterns to filter out models you never want to see — models matching these patterns will be excluded from discovery and hidden by default in the visibility UI.

Patterns support glob syntax (* and ? wildcards). To exclude a specific model by exact ID, wrap it with ^ and $:

/omlx-models is the best way to customize this but manual globs can be added to.

Here's some examples:

• ^tiny-model$ — excludes only the model with the exact ID tiny-model
• gpt-4-32k* — excludes all models starting with gpt-4-32k
• *-instruct-* — excludes all models containing instruct anywhere in the ID