@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