Support provider extensions with model aliases and improve search

[mindplay-dk]

What happened?

Since there's no UI to configure OpenRouter providers, I configured models.json with an override:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-63139...",
      "modelOverrides": {
        "minimax/minimax-m3": {
          "name": "MiniMax M3 [rasmus@openrouter, parasail]",
          "compat": {
            "openRouterRouting": {
              "only": ["parasail/fp8"],
              "allow_fallbacks": false
            }
          }
        },
        "deepseek/deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash [rasmus@openrouter, baidu|gmicloud]",
          "compat": {
            "openRouterRouting": {
              "only": ["baidu/fp8", "gmicloud/fp8"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

I just want to choose my providers on OpenRouter - and I want "proof" that it's working, so I'm overriding the name.

Unfortunately, this has no effect on search - so you can see:

It does have the name override, so at least I have proof the config is working.

However:

It does not seem to query the name? I can't find or keep track of my overrides.

I don't even know why any results come up at all? surely none of these have "rasmus" in the name. 😅

Could we either:

1. just make the search work for names (why doesn't it?)
   1.b. display the names on the list (why do we have names that aren't displayed?)
2. allow an id override, so we can change the ID that's actually visible on the list

I guess, ideally, I think the built-in providers should actually provide configuration UI? Since apparently it is very difficult to find documentation for the right keys/values to put in openrouter configuration.

I also tried adding a new openrouter provider, but neither Pi or I could find any way to make it respect the thinking option in Pi - it even plowed through the source code, and eventually concluded it couldn't make this work reliable with a custom provider.

So one other approach to consider: what if we could extend existing providers? Like an extends key for custom providers - which would make it work just like modelOverrides, but effectively creating a new provider in the listing rather than overriding. This would solve the search problem, and at the same time would give you easier and more reliable custom providers without needing to figure out how to replicate what Pi does internally.

It would probably fit the use case of "I just want to specify allowed providers on OpenRouter" better? Or really any scenario where you want to configure something without replacing the built-in options.

Steps to reproduce

🙂

Expected behavior

No response

Version

0.79.8

[github-actions]

This issue was auto-closed. All issues from new contributors are auto-closed by default.

Maintainers review auto-closed issues daily and reopen worthwhile ones. Issues that do not meet the quality bar in CONTRIBUTING.md will not be reopened or receive a reply.

If a maintainer replies lgtmi on one of your issues, your future issues will stay open. If a maintainer replies lgtm, your future issues and PRs will stay open.

See CONTRIBUTING.md.

[mitsuhiko]

The state of the name field is a bit unexplored. It does not even show up in the list and I seems to me that what you actually want anyways is to rename the id? I'm going to open this issue for brain storming.

[mitsuhiko]

I had some back and forth with the clanker to see what we could do here. Note that the rest of the commend is entirely AI generated:

I think the better shape here is probably not to make name behave like an ID. There are two separate concepts conflated today:

• Pi's local model ID: what is shown, selected, stored in settings/sessions.
• The upstream/provider model ID: what is sent as the API model value and used to inherit built-in metadata.

An extends design could keep the existing modelOverrides mapping shape, where the key is the local/visible Pi model ID, and an optional upstreamId points at the inherited upstream model:

{
  "providers": {
    "openrouter-parasail": {
      "extends": "openrouter",
      "name": "OpenRouter (Parasail)",
      "modelOverrides": {
        "minimax-m3-parasail": {
          "upstreamId": "minimax/minimax-m3",
          "name": "MiniMax M3 (Parasail)",
          "compat": {
            "openRouterRouting": {
              "only": ["parasail/fp8"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

Possible semantics:

• extends: "openrouter" inherits the base provider's API type, base URL, auth/login behavior, headers, default compat, and built-in model metadata.
• Each modelOverrides key is the local/visible Pi model ID used in /model, defaults, sessions, and the footer.
• upstreamId is the provider model identifier sent in the request payload and the lookup key for inherited built-in metadata.
• If upstreamId is omitted, it defaults to the override key, preserving today's in-place override behavior.
• On an extended provider, modelOverrides entries can create separate aliases/variants instead of mutating the original built-in provider.

I would lean toward upstreamId rather than canonicalId: canonicalId is ambiguous here, while upstreamId says clearly that this is the provider-facing model ID.

Does this match the workflow you had in mind?

[mindplay-dk]

Yeah, sort of... the semantics of that example is a bit confusing - I mean, these are models, not modelOverrides, right? you're extending/inheriting rather than overriding something, I think?

so maybe:

{
  "providers": {
    "my-provider": {
      "apiKey": "sk-or-v1-63139...",
      "extendsProvider": "openrouter",
      "models": [
        {
          "id": "rasmus/minimax-m3",
          "extendsModel": "minimax/minimax-m3",
          "reasoning": false,
          "compat": {
            "openRouterRouting": {
              "only": ["parasail/fp8"],
              "allow_fallbacks": false
            }
          }
        }
      ]
    }
  }
}

Or perhaps even more explicitly, define the base provider and model for every model:

{
  "providers": {
    "my-provider": {
      "apiKey": "sk-or-v1-63139...",
      "models": [
        {
          "id": "rasmus/minimax-m3",
          "extendsProvider": "openrouter",
          "extendsModel": "minimax/minimax-m3",
          "reasoning": false,
          "compat": {
            "openRouterRouting": {
              "only": ["parasail/fp8"],
              "allow_fallbacks": false
            }
          }
        }
      ]
    }
  }
}

Or perhaps a basic syntax like openrouter:minimax/minimax-m3 so you need to specify both:

{
  "providers": {
    "my-provider": {
      "apiKey": "sk-or-v1-63139...",
      "models": [
        {
          "id": "rasmus/minimax-m3",
          "extendsModel": "openrouter:minimax/minimax-m3",
          "reasoning": false,
          "compat": {
            "openRouterRouting": {
              "only": ["parasail/fp8"],
              "allow_fallbacks": false
            }
          }
        }
      ]
    }
  }
}

[mitsuhiko]

Something like this. But I will say that once you're down that path I do wonder if this is not better solved by custom extensions that register providers instead of faffing around in models.json. You can get pi create you a custom extension that extends providers probably pretty easily.

[mindplay-dk]

Heh, well honestly my thinking is the exact opposite 😅

I think it's already overwhelming as is, having to dig through documentation and edit a JSON file, just to configure something.

I might be getting a bit sidetracked here, but picking the OpenRouter provider, or configuring other details of other providers, I honestly think these things should have a UI. Even just something simple, like a schema driven standard UI like VS Code has for configuration.

Does configuration and providers have schema? I mean like a JSON schema or Zod or something else reflective? I don't expect every provider to have a custom built UI, but having declarative schema you can validate would be a big UX improvement either way, and just a basic schema driven UI with a few basic input types with descriptions would be a huge UX boon. 😊

[mindplay-dk]

I mean, I don't think the need to pick OpenRouter providers is exotic? without it, you don't even know if you're getting the real model or a heavily quantized version - and you also have no idea what you're going to pay for it. 😅