pi-better-model-select 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 msenebald
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# pi-better-model-select
+
+A searchable, usage-ranked model picker for [pi](https://pi.dev).
+
+`/bms` opens the effective model list from `models.json` plus the optional
+`models.local.json` overlay, sorted by how often you pick each model. Start
+typing to filter; press enter to switch the session to the highlighted model.
+Add, update and delete live on ctrl-chords so plain keystrokes always go to the
+search box.
+
+## Install
+
+```bash
+pi install npm:pi-better-model-select
+```
+
+If you installed the package under its old name, migrate with:
+
+```bash
+pi remove npm:@msenebald/better-model-select
+pi install npm:pi-better-model-select
+```
+
+## Commands
+
+| Command    | What it does                                        |
+| ---------- | --------------------------------------------------- |
+| `/bms`     | Open the searchable, usage-ranked picker            |
+| `/bms-add` | Jump straight to the add-a-model flow               |
+
+## Keys
+
+| Key        | Action                                              |
+| ---------- | --------------------------------------------------- |
+| `↑` `↓`    | Move through the list                               |
+| *type*     | Fuzzy filter by display name, model id or provider  |
+| `enter`    | Load the highlighted model                          |
+| `ctrl+a`   | Add a model                                         |
+| `ctrl+u`   | Update the highlighted model                        |
+| `ctrl+x`   | Delete the highlighted model                        |
+| `ctrl+r`   | Reset usage statistics                              |
+| `esc`      | Close                                               |
+
+## Ranking
+
+Every model loaded through `/bms` increments a counter in
+`<agent-dir>/bms-usage.json`. The list sorts by count, then by most recent use,
+then alphabetically — so an unused config starts in plain alphabetical order and
+drifts toward your habits.
+
+Only `/bms` selections count. Switching via `/model`, `ctrl+p` cycling, or a
+session restore does not, which keeps the ranking a record of deliberate choices
+rather than of how often you restart pi.
+
+Stats for models that disappear from the effective configuration are pruned
+when the picker opens. `ctrl+r` clears everything.
+
+## Metadata discovery
+
+When adding or updating, the extension tries to fill in context window, output
+cap, reasoning support and input modalities from, in order:
+
+1. `GET {baseUrl}/model/info` — LiteLLM proxies
+2. `GET {baseUrl}/models/{id}` — OpenAI-style, plus proxy-specific fields
+3. The public LiteLLM model cost map on GitHub
+
+Each step is best-effort. A plain OpenAI-compatible endpoint usually yields
+nothing from steps 1 and 2, and the flow falls back to name-based heuristics
+with editable defaults. Before a write, BMS asks you to choose
+`models.local.json` or `models.json`. The local file is listed first and acts as
+a personal BMS overlay. The selected file is re-read immediately before the
+write so a concurrent edit in another pi session is not clobbered.
+
+## Paths
+
+All files resolve through pi's `getAgentDir()`, so `PI_CODING_AGENT_DIR` and
+rebranded distributions work without special handling:
+
+- `<agent-dir>/models.json` is Pi's documented compatible-endpoint configuration.
+- `<agent-dir>/models.local.json` is an optional personal overlay managed by BMS.
+- `<agent-dir>/bms-usage.json` stores selection counters.
+
+Pi does not currently document or load `models.local.json` itself. BMS merges it
+over `models.json` by provider and model id, then registers the merged providers
+through Pi's extension API at session start and whenever `/bms` opens. If the
+same model exists in both files, fields from `models.local.json` win.
+
+Deleting a model that exists only in `models.json` leaves that file untouched.
+BMS writes `{ "id": "...", "bmsDeleted": true }` to the local overlay instead.
+This BMS-owned tombstone keeps generated or externally managed model entries
+hidden across restarts. Delete the tombstone from `models.local.json` to restore
+the inherited model.
+
+Writes are atomic using a temporary file and rename, so an interrupted write
+cannot truncate either configuration file.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+node --experimental-strip-types --test extensions/lib/picker.test.ts
+pi -e . -p "say OK"      # load the extension without installing it
+```
+
+## Publishing
+
+Set the new version in `package.json` and `package-lock.json`, then run:
+
+```bash
+make publish
+```
+
+The target runs the full package gate, checks npm authentication, opens npm's
+browser login when needed, skips the upload if that exact version already
+exists, publishes the public scoped package, and waits for npm to expose the
+new version. npm can take several minutes to process a package. If verification
+times out, rerun `make verify-publish`; do not publish the same version again.
+
+## License
+
+MIT

package/extensions/bms.ts

@@ -0,0 +1,214 @@
+// pi-better-model-select — /bms
+//
+// A searchable model picker ranked by how often you actually pick each model,
+// with add / update / delete wired to ctrl-chords so plain typing always goes
+// to the search box.
+
+import { DynamicBorder, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Text } from "@earendil-works/pi-tui";
+import { addFlow, deleteFlow, updateFlow, type FlowCtx } from "./lib/flows.ts";
+import { ModelPicker, rankModels, type PickerAction } from "./lib/picker.ts";
+import {
+  loadConfig,
+  loadConfigFile,
+  pruneUsage,
+  recordUsage,
+  saveUsage,
+  type ModelEntry,
+  type ModelsConfig,
+  type ProviderEntry,
+} from "./lib/store.ts";
+
+const registeredLocalProviders = new Set<string>();
+
+function providerConfig(
+  ctx: any,
+  providerName: string,
+  provider: ProviderEntry,
+): Record<string, unknown> {
+  const models = (provider.models ?? []).map((entry: ModelEntry) => {
+    const current = ctx.modelRegistry.find(providerName, entry.id);
+    return {
+      ...entry,
+      name: entry.name ?? current?.name ?? entry.id,
+      api: entry.api ?? provider.api ?? current?.api,
+      baseUrl: entry.baseUrl ?? provider.baseUrl ?? current?.baseUrl,
+      reasoning: entry.reasoning ?? current?.reasoning ?? false,
+      input: entry.input ?? current?.input ?? ["text"],
+      cost: entry.cost ?? current?.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: entry.contextWindow ?? current?.contextWindow ?? 128000,
+      maxTokens: entry.maxTokens ?? current?.maxTokens ?? 16384,
+    };
+  });
+
+  const { models: _models, ...settings } = provider;
+  return { ...settings, models };
+}
+
+/** Apply the personal BMS overlay as extension providers. */
+function syncLocalConfig(pi: ExtensionAPI, ctx: any): ModelsConfig | null {
+  const local = loadConfigFile(ctx, "models.local.json", true);
+  const effective = loadConfig(ctx);
+  if (!local || !effective) return null;
+
+  const next = new Set(Object.keys(local.providers ?? {}));
+  for (const providerName of registeredLocalProviders) {
+    if (!next.has(providerName)) pi.unregisterProvider(providerName);
+  }
+
+  for (const providerName of next) {
+    const provider = effective.providers?.[providerName];
+    if (!provider) continue;
+    try {
+      pi.registerProvider(providerName, providerConfig(ctx, providerName, provider) as any);
+    } catch (e) {
+      ctx.ui.notify(`Cannot apply ${providerName} from models.local.json: ${e}`, "error");
+      return null;
+    }
+  }
+
+  registeredLocalProviders.clear();
+  for (const providerName of next) registeredLocalProviders.add(providerName);
+  return effective;
+}
+
+/** Re-read model configuration from disk and switch the session to the given model. */
+async function loadModel(
+  pi: ExtensionAPI,
+  ctx: any,
+  provider: string,
+  modelId: string,
+): Promise<void> {
+  try {
+    await ctx.modelRegistry.refresh();
+  } catch (e) {
+    ctx.ui.notify(`Could not reload model configuration: ${e}`, "error");
+    return;
+  }
+
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) {
+    ctx.ui.notify(
+      `Model "${provider}/${modelId}" not found after reload — check the config.`,
+      "warning",
+    );
+    return;
+  }
+
+  // pi.setModel lives on the ExtensionAPI, not on the command context.
+  const ok = await pi.setModel(model);
+  if (ok) {
+    // Counted here rather than in model_select so /bms picks are ranked but
+    // session restores are not, which would otherwise inflate every startup.
+    recordUsage(provider, modelId);
+    ctx.ui.notify(`Loaded model: ${provider}/${modelId}`, "info");
+  } else {
+    ctx.ui.notify(
+      `Could not switch to ${provider}/${modelId} (no API key?). It is still available via /model.`,
+      "warning",
+    );
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx: any) => {
+    syncLocalConfig(pi, ctx);
+  });
+
+  pi.registerCommand("bms", {
+    description: "Better model select — searchable, usage-ranked model picker",
+    handler: async (_args, ctx: any) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/bms needs an interactive terminal.", "warning");
+        return;
+      }
+
+      // Loop so the picker reappears after each add / update / delete.
+      for (;;) {
+        const config = syncLocalConfig(pi, ctx);
+        if (!config) return;
+        pruneUsage(config);
+
+        const rows = rankModels(config);
+        if (rows.length === 0) {
+          const add = await ctx.ui.confirm(
+            "No models configured",
+            "The effective model configuration has no models. Add one now?",
+          );
+          if (!add) return;
+          await addFlow(ctx as FlowCtx);
+          continue;
+        }
+
+        const action: PickerAction | undefined = await ctx.ui.custom((tui: any, theme: any, _kb: any, done: any) => {
+          const container = new Container();
+          const accent = (s: string) =>
+            typeof theme?.fg === "function" ? theme.fg("accent", s) : s;
+
+          container.addChild(new DynamicBorder(accent));
+          container.addChild(new Text(accent("Better Model Select"), 1, 0));
+
+          const picker = new ModelPicker(
+            rows,
+            theme,
+            () => tui.requestRender(),
+            (a: PickerAction) => done(a),
+          );
+          picker.focused = true;
+          container.addChild(picker);
+          container.addChild(new DynamicBorder(accent));
+
+          return {
+            render: (w: number) => container.render(w),
+            invalidate: () => container.invalidate(),
+            handleInput: (data: string) => picker.handleInput(data),
+          };
+        });
+
+        switch (action?.kind) {
+          case "load":
+            await loadModel(pi, ctx, action.provider, action.modelId);
+            return;
+          case "add":
+            await addFlow(ctx as FlowCtx);
+            break;
+          case "update":
+            await updateFlow(
+              ctx as FlowCtx,
+              action.provider && action.modelId
+                ? { provider: action.provider, modelId: action.modelId }
+                : undefined,
+            );
+            break;
+          case "delete":
+            await deleteFlow(
+              ctx as FlowCtx,
+              action.provider && action.modelId
+                ? { provider: action.provider, modelId: action.modelId }
+                : undefined,
+            );
+            break;
+          case "reset": {
+            const ok = await ctx.ui.confirm(
+              "Reset usage statistics?",
+              "Model ranking falls back to alphabetical order.",
+            );
+            if (ok) {
+              saveUsage({ version: 1, counts: {}, lastUsed: {} });
+              ctx.ui.notify("Usage statistics cleared.", "info");
+            }
+            break;
+          }
+          default:
+            return; // "close" or ESC
+        }
+      }
+    },
+  });
+
+  // Standalone add, kept for muscle memory and non-interactive convenience.
+  pi.registerCommand("bms-add", {
+    description: "Add a model from a provider's endpoint to a selected config file",
+    handler: async (_args, ctx: any) => addFlow(ctx as FlowCtx),
+  });
+}