@bismawy/pi-vision-watcher 1.3.1 → 1.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.md +7 -6
- package/package.json +72 -72
- package/src/describer.ts +7 -0
- package/src/index.ts +77 -11
- package/src/router.ts +291 -0
- package/src/vision-model-selector.ts +378 -198
- package/vision-watcher.ts +222 -44
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [1.4.1] - 2026-11-16
|
|
4
|
+
|
|
5
|
+
### Fixed
|
|
6
|
+
- Detect text-only models behind routing proxies (such as Magpie, 9router, and omnirouter) using router capabilities and expanded model-family heuristics, so `/vision-watcher` filters them out and `autoHandoff` routes images through the vision model on first send.
|
|
7
|
+
- Skip vision handoff when the active chat model is vision-capable, and only warn about an inactive handoff when the active chat model is text-only without a configured `visionModel`.
|
|
8
|
+
- Treat short HTTP 200 provider quota, billing, auth, and JSON error messages (`isSoftProviderErrorText`) as failures in `callVision` so `fallbackModels` failover triggers automatically.
|
|
9
|
+
|
|
10
|
+
## [1.4.0] - 2026-11-13
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
- The `/vision-watcher` picker reads like the arnative providers dashboard. A header names the whole
|
|
14
|
+
configuration in model names (`Primary`, `Fallback` chain, `Thinking` level) so the picked models stay
|
|
15
|
+
visible even when their rows scroll out of view, instead of the old four-row status panel.
|
|
16
|
+
The per-row checkbox is gone: the choice is single, so a box promised multi-select. Each row hugs its ref
|
|
17
|
+
with a role marker instead: `✓ primary` in accent, `✓ fallback 1` in the primary tone, then the fact in
|
|
18
|
+
parentheses (`(thinking off)`, `(no thinking)`) in dim. The primary row keeps the accent colour when it is
|
|
19
|
+
not highlighted.
|
|
20
|
+
- `a` toggles async paste handoff and `r` resets the failover chain; `alt+a` / `ctrl+alt+a` and
|
|
21
|
+
`ctrl+shift+r` stay as aliases. Letters are commands, so a bare key is free: only `/` hands the keyboard
|
|
22
|
+
to the filter. The legend shows the new hints.
|
|
23
|
+
- `/` opens the filter; `enter` or `esc` closes it and keeps the query, so letters are commands again and a
|
|
24
|
+
multi-word query such as `gemini 3.8` stays typeable. Typing already owns the key, so `space` toggles the
|
|
25
|
+
primary whether or not a query is kept.
|
|
26
|
+
- The legend packs into rows that fit the frame and states each toggle next to its key (`[A] Async on`).
|
|
27
|
+
A narrow row truncates the ref first, then the parenthetical, and only then the role marker.
|
|
28
|
+
|
|
3
29
|
## [1.3.1] - 2026-11-13
|
|
4
30
|
|
|
5
31
|
### Fixed
|
package/README.md
CHANGED
|
@@ -37,18 +37,19 @@ pi --extension ./vision-watcher.ts
|
|
|
37
37
|
| --- | --- |
|
|
38
38
|
| `↑` · `↓` | Move the highlight up/down the list |
|
|
39
39
|
| `space` | Toggle highlighted model as primary describer |
|
|
40
|
-
| `tab` | Toggle highlighted model in/out of failover chain (
|
|
41
|
-
| `
|
|
40
|
+
| `tab` | Toggle highlighted model in/out of failover chain (max 3) |
|
|
41
|
+
| `r` | Reset failover chain (`ctrl+shift+r` also works) |
|
|
42
42
|
| `alt+↑` · `alt+↓` | Reorder the highlighted model (the chain follows list order) |
|
|
43
43
|
| `shift+tab` | Walk thinking ladder (`off` → `minimal` → `low` → `medium` → `high` → `xhigh` → `max`) |
|
|
44
|
-
|
|
|
44
|
+
| `/` | Open the filter; `enter` or `esc` closes it and keeps the query |
|
|
45
|
+
| `a` | Toggle async paste handoff (`alt+a`, or `ctrl+alt+a` on Linux) |
|
|
45
46
|
| `enter` · `ctrl+s` | Save configuration (primary describer and chain) |
|
|
46
47
|
| `esc` | Cancel and exit picker |
|
|
47
48
|
|
|
48
49
|
> **Notes:**
|
|
49
|
-
> -
|
|
50
|
-
> - The
|
|
51
|
-
> -
|
|
50
|
+
> - Letters are commands, not filter text: only `/` hands the keyboard to the filter. While it is open, `space` is a space character, so queries like `gemini 3.8` stay typeable; `enter` closes the filter and keeps the query, and a second `enter` saves.
|
|
51
|
+
> - The header names the whole configuration in model names (`Primary`, `Fallback` chain, `Thinking` level), so the picked models stay visible even when they sit outside the visible rows. Each row hugs its ref with a role marker: `✓ primary` in accent, `✓ fallback 1` in the primary tone, then the fact in parentheses (`(thinking off)`, `(no thinking)`). There is no per-row checkbox: the picker chooses one primary, so the role marker carries that and the primary row keeps the accent colour.
|
|
52
|
+
> - Letters are commands, so `a` and `r` are free: only `/` hands the keyboard to the filter. `tab` works on Windows Terminal/conhost, X11, macOS, tmux and SSH. `ctrl+s` is avoided because POSIX tty flow control (IXON) eats it on some terminals; `enter` does the same job.
|
|
52
53
|
|
|
53
54
|
## Commands
|
|
54
55
|
|
package/package.json
CHANGED
|
@@ -1,72 +1,72 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@bismawy/pi-vision-watcher",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "Intelligent vision watcher. Connected models. Zero workflow interruption. Text-only Pi models get background image descriptions with failover chains.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"author": "bismawy",
|
|
7
|
-
"license": "MIT",
|
|
8
|
-
"publishConfig": {
|
|
9
|
-
"access": "public"
|
|
10
|
-
},
|
|
11
|
-
"repository": {
|
|
12
|
-
"type": "git",
|
|
13
|
-
"url": "git+https://github.com/bismawy/pi-vision-watcher.git"
|
|
14
|
-
},
|
|
15
|
-
"homepage": "https://github.com/bismawy/pi-vision-watcher#readme",
|
|
16
|
-
"bugs": {
|
|
17
|
-
"url": "https://github.com/bismawy/pi-vision-watcher/issues"
|
|
18
|
-
},
|
|
19
|
-
"keywords": [
|
|
20
|
-
"pi-package",
|
|
21
|
-
"pi-extension",
|
|
22
|
-
"pi-vision-watcher",
|
|
23
|
-
"vision-watcher",
|
|
24
|
-
"pi",
|
|
25
|
-
"pi-coding-agent",
|
|
26
|
-
"vision",
|
|
27
|
-
"image-describer",
|
|
28
|
-
"image-description",
|
|
29
|
-
"multimodal",
|
|
30
|
-
"model-selector",
|
|
31
|
-
"model-picker",
|
|
32
|
-
"failover",
|
|
33
|
-
"accessibility"
|
|
34
|
-
],
|
|
35
|
-
"files": [
|
|
36
|
-
"*.ts",
|
|
37
|
-
"src/",
|
|
38
|
-
"CHANGELOG.md",
|
|
39
|
-
"LICENSE",
|
|
40
|
-
"README.md"
|
|
41
|
-
],
|
|
42
|
-
"scripts": {
|
|
43
|
-
"test": "vitest run",
|
|
44
|
-
"dev": "pi --extension ./vision-watcher.ts",
|
|
45
|
-
"test:watch": "vitest",
|
|
46
|
-
"test:coverage": "vitest run --coverage",
|
|
47
|
-
"typecheck": "tsc --noEmit",
|
|
48
|
-
"lint:dead": "knip --no-gitignore"
|
|
49
|
-
},
|
|
50
|
-
"devDependencies": {
|
|
51
|
-
"@earendil-works/pi-ai": "0.85.1",
|
|
52
|
-
"@earendil-works/pi-coding-agent": "0.85.1",
|
|
53
|
-
"@earendil-works/pi-tui": "0.85.1",
|
|
54
|
-
"@types/node": "25.9.1",
|
|
55
|
-
"@vitest/coverage-v8": "4.1.7",
|
|
56
|
-
"knip": "6.14.1",
|
|
57
|
-
"typescript": "6.0.3",
|
|
58
|
-
"vitest": "4.1.7"
|
|
59
|
-
},
|
|
60
|
-
"pi": {
|
|
61
|
-
"extensions": [
|
|
62
|
-
"./vision-watcher.ts"
|
|
63
|
-
],
|
|
64
|
-
"image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/banner.webp"
|
|
65
|
-
},
|
|
66
|
-
"peerDependencies": {
|
|
67
|
-
"@earendil-works/pi-ai": "*",
|
|
68
|
-
"@earendil-works/pi-coding-agent": "*",
|
|
69
|
-
"@earendil-works/pi-tui": "*"
|
|
70
|
-
},
|
|
71
|
-
"packageManager": "pnpm@11.20.0"
|
|
72
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@bismawy/pi-vision-watcher",
|
|
3
|
+
"version": "1.4.1",
|
|
4
|
+
"description": "Intelligent vision watcher. Connected models. Zero workflow interruption. Text-only Pi models get background image descriptions with failover chains.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"author": "bismawy",
|
|
7
|
+
"license": "MIT",
|
|
8
|
+
"publishConfig": {
|
|
9
|
+
"access": "public"
|
|
10
|
+
},
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/bismawy/pi-vision-watcher.git"
|
|
14
|
+
},
|
|
15
|
+
"homepage": "https://github.com/bismawy/pi-vision-watcher#readme",
|
|
16
|
+
"bugs": {
|
|
17
|
+
"url": "https://github.com/bismawy/pi-vision-watcher/issues"
|
|
18
|
+
},
|
|
19
|
+
"keywords": [
|
|
20
|
+
"pi-package",
|
|
21
|
+
"pi-extension",
|
|
22
|
+
"pi-vision-watcher",
|
|
23
|
+
"vision-watcher",
|
|
24
|
+
"pi",
|
|
25
|
+
"pi-coding-agent",
|
|
26
|
+
"vision",
|
|
27
|
+
"image-describer",
|
|
28
|
+
"image-description",
|
|
29
|
+
"multimodal",
|
|
30
|
+
"model-selector",
|
|
31
|
+
"model-picker",
|
|
32
|
+
"failover",
|
|
33
|
+
"accessibility"
|
|
34
|
+
],
|
|
35
|
+
"files": [
|
|
36
|
+
"*.ts",
|
|
37
|
+
"src/",
|
|
38
|
+
"CHANGELOG.md",
|
|
39
|
+
"LICENSE",
|
|
40
|
+
"README.md"
|
|
41
|
+
],
|
|
42
|
+
"scripts": {
|
|
43
|
+
"test": "vitest run",
|
|
44
|
+
"dev": "pi --extension ./vision-watcher.ts",
|
|
45
|
+
"test:watch": "vitest",
|
|
46
|
+
"test:coverage": "vitest run --coverage",
|
|
47
|
+
"typecheck": "tsc --noEmit",
|
|
48
|
+
"lint:dead": "knip --no-gitignore"
|
|
49
|
+
},
|
|
50
|
+
"devDependencies": {
|
|
51
|
+
"@earendil-works/pi-ai": "0.85.1",
|
|
52
|
+
"@earendil-works/pi-coding-agent": "0.85.1",
|
|
53
|
+
"@earendil-works/pi-tui": "0.85.1",
|
|
54
|
+
"@types/node": "25.9.1",
|
|
55
|
+
"@vitest/coverage-v8": "4.1.7",
|
|
56
|
+
"knip": "6.14.1",
|
|
57
|
+
"typescript": "6.0.3",
|
|
58
|
+
"vitest": "4.1.7"
|
|
59
|
+
},
|
|
60
|
+
"pi": {
|
|
61
|
+
"extensions": [
|
|
62
|
+
"./vision-watcher.ts"
|
|
63
|
+
],
|
|
64
|
+
"image": "https://raw.githubusercontent.com/bismawy/pi-vision-watcher/main/assets/banner.webp"
|
|
65
|
+
},
|
|
66
|
+
"peerDependencies": {
|
|
67
|
+
"@earendil-works/pi-ai": "*",
|
|
68
|
+
"@earendil-works/pi-coding-agent": "*",
|
|
69
|
+
"@earendil-works/pi-tui": "*"
|
|
70
|
+
},
|
|
71
|
+
"packageManager": "pnpm@11.20.0"
|
|
72
|
+
}
|
package/src/describer.ts
CHANGED
|
@@ -46,6 +46,7 @@ import {
|
|
|
46
46
|
DEFAULT_VISION_PROMPT,
|
|
47
47
|
describeTimeoutMs,
|
|
48
48
|
formatModelRef,
|
|
49
|
+
isSoftProviderErrorText,
|
|
49
50
|
markDescriptionTruncated,
|
|
50
51
|
parseBatchedDescriptions,
|
|
51
52
|
type ExtractedImage,
|
|
@@ -474,6 +475,12 @@ async function callVision<T>(
|
|
|
474
475
|
appendVisionError({ ...base, reason, config: configSnapshot(cfg) });
|
|
475
476
|
return null;
|
|
476
477
|
}
|
|
478
|
+
if (isSoftProviderErrorText(text)) {
|
|
479
|
+
const reason = `vision model returned an error message as text: ${text.slice(0, 200)}`;
|
|
480
|
+
deps.setLastError(reason);
|
|
481
|
+
appendVisionError({ ...base, reason, config: configSnapshot(cfg) });
|
|
482
|
+
return null;
|
|
483
|
+
}
|
|
477
484
|
return await finish(text, response.stopReason === "length");
|
|
478
485
|
} catch (err) {
|
|
479
486
|
const userAborted = abortWire.userAborted();
|
package/src/index.ts
CHANGED
|
@@ -265,18 +265,65 @@ export function isImageNotSupportedError(text: string): boolean {
|
|
|
265
265
|
);
|
|
266
266
|
}
|
|
267
267
|
|
|
268
|
+
/** Detect upstream provider/proxy errors returned as normal HTTP 200 text
|
|
269
|
+
* (`stopReason: "stop"`) — e.g. aihubmix quota exhaustion ("accounts that have
|
|
270
|
+
* not been recharged can only try 10 times"), raw JSON error bodies, or short
|
|
271
|
+
* billing/auth/rate-limit rejections. Rejecting these in `callVision` lets the
|
|
272
|
+
* dataloader's retry + `fallbackModels` chain take over.
|
|
273
|
+
*
|
|
274
|
+
* Guarded to short responses (`<= 500` chars) without batch delimiters so a
|
|
275
|
+
* real screenshot description that quotes an error message is not rejected. */
|
|
276
|
+
export function isSoftProviderErrorText(text: string): boolean {
|
|
277
|
+
const trimmed = text.trim();
|
|
278
|
+
if (!trimmed || trimmed.length > 500) return false;
|
|
279
|
+
if (/<<<IMAGE\s+\d+>>>/i.test(trimmed)) return false;
|
|
280
|
+
if (isImageNotSupportedError(trimmed)) return true;
|
|
281
|
+
if (/^\s*\{\s*"(?:error|code)"\s*:/i.test(trimmed)) return true;
|
|
282
|
+
if (
|
|
283
|
+
/accounts that have not been recharged can only try|insufficient[_ ]quota|exceeded your current quota|credit balance is too low|balance is insufficient|please recharge|top up your account/i.test(
|
|
284
|
+
trimmed,
|
|
285
|
+
)
|
|
286
|
+
) {
|
|
287
|
+
return true;
|
|
288
|
+
}
|
|
289
|
+
return /^(?:error|401|402|403|429|500|502|503)\s*[:\-]\s*(?:unauthorized|forbidden|rate limit|too many requests|insufficient|invalid api key|bad gateway|service unavailable)/i.test(
|
|
290
|
+
trimmed,
|
|
291
|
+
);
|
|
292
|
+
}
|
|
293
|
+
|
|
268
294
|
/** Models whose registry entries commonly declare image input while the
|
|
269
|
-
* backend rejects images (DeepSeek V4, GLM 4/5 non-V
|
|
270
|
-
*
|
|
271
|
-
*
|
|
272
|
-
*
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
295
|
+
* backend rejects images (DeepSeek V3/V4/R1, GLM 4/5 non-V, Mercury, SWE,
|
|
296
|
+
* GPT-OSS, Qwen Coder, Llama 3.1/3.3, Codestral/Devstral/Magistral).
|
|
297
|
+
* Conservative: VL / Vision / Janus / OCR / Omni / *V variants keep image
|
|
298
|
+
* input unless explicitly tagged text-only. Used for both `/vision-watcher`
|
|
299
|
+
* filtering and `autoHandoff` so text-only models hand off on FIRST send. */
|
|
300
|
+
export function isKnownTextOnlyFalselyVision(
|
|
301
|
+
id: string | undefined | null,
|
|
302
|
+
label?: string | null,
|
|
303
|
+
): boolean {
|
|
304
|
+
const combined = [id, label]
|
|
305
|
+
.filter((s): s is string => typeof s === "string" && s.trim().length > 0)
|
|
306
|
+
.join(" ");
|
|
307
|
+
if (!combined) return false;
|
|
308
|
+
const n = combined.toLowerCase();
|
|
309
|
+
if (/\btext[-_\s]?only\b/.test(n)) return true;
|
|
310
|
+
if (
|
|
311
|
+
n.includes("vl") ||
|
|
312
|
+
n.includes("vision") ||
|
|
313
|
+
n.includes("janus") ||
|
|
314
|
+
/\b(?:ocr|pixtral|llava|internvl|minicpm-v|cogvlm|molmo|qvq|omni)\b/.test(n)
|
|
315
|
+
) {
|
|
316
|
+
return false;
|
|
317
|
+
}
|
|
318
|
+
if (/\dv(?=[-_./\s:]|$)/.test(n)) return false; // glm-4v, glm-4.5v — vision variants
|
|
319
|
+
if (/deepseek[-_./\s]*(?:v[34]|r1|chat|coder|reasoner)/.test(n)) return true;
|
|
320
|
+
if (/glm[-_./\s]*[45]/.test(n)) return true;
|
|
321
|
+
if (/\bmercury[-_./\s]*(?:2|3|coder|decide|small|mini)\b/.test(n)) return true;
|
|
322
|
+
if (/\bswe[-_./\s]*[12]\b/.test(n)) return true;
|
|
323
|
+
if (/\bgpt[-_./\s]*oss\b/.test(n)) return true;
|
|
324
|
+
if (/\bqwen[-_./\s]*(?:2(?:\.5)?|3(?:\.\d+)?)[-_./\s]*coder\b/.test(n)) return true;
|
|
325
|
+
if (/\bllama[-_./\s]*3(?:\.[13])?(?=[-_./\s:]|$)/.test(n)) return true;
|
|
326
|
+
if (/\b(?:codestral|devstral|magistral)\b/.test(n)) return true;
|
|
280
327
|
return false;
|
|
281
328
|
}
|
|
282
329
|
|
|
@@ -340,6 +387,25 @@ export function isVisionModel(model: { input?: ("text" | "image")[] } | undefine
|
|
|
340
387
|
return !!model && Array.isArray(model.input) && model.input.includes("image");
|
|
341
388
|
}
|
|
342
389
|
|
|
390
|
+
/** Determine effective vision capability by combining Pi's registry `input`,
|
|
391
|
+
* optional live router `/models` metadata, explicit user `modelOverrides`, and
|
|
392
|
+
* false-vision model heuristics. */
|
|
393
|
+
export function isEffectiveVisionModel(
|
|
394
|
+
model: { id?: string; name?: string; input?: ("text" | "image")[] } | undefined | null,
|
|
395
|
+
routerCap?: { vision?: boolean; label?: string },
|
|
396
|
+
options?: { hasExplicitTextOverride?: boolean },
|
|
397
|
+
): boolean {
|
|
398
|
+
if (!model) return false;
|
|
399
|
+
if (options?.hasExplicitTextOverride) return false;
|
|
400
|
+
const label = [model.name, routerCap?.label]
|
|
401
|
+
.filter((s): s is string => typeof s === "string" && s.trim().length > 0)
|
|
402
|
+
.join(" ");
|
|
403
|
+
if (routerCap?.vision === false) return false;
|
|
404
|
+
if (isKnownTextOnlyFalselyVision(model.id, label)) return false;
|
|
405
|
+
if (routerCap?.vision === true) return true;
|
|
406
|
+
return isVisionModel(model);
|
|
407
|
+
}
|
|
408
|
+
|
|
343
409
|
/** Merge a parsed config object onto defaults, tolerating missing/invalid fields. */
|
|
344
410
|
export function normalizeConfig(raw: unknown): VisionHandoffConfig {
|
|
345
411
|
const base: VisionHandoffConfig = { ...DEFAULT_CONFIG };
|
package/src/router.ts
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Router capability discovery for OpenAI-compatible routing proxies (Magpie,
|
|
3
|
+
* 9router, omnirouter, OpenRouter, LiteLLM, etc.).
|
|
4
|
+
*
|
|
5
|
+
* Proxy entries in `models.json` frequently mark every model with
|
|
6
|
+
* `input: ["text", "image"]` (or omit `input` altogether), even when the
|
|
7
|
+
* router's own `/models` endpoint knows which models are text-only. Querying
|
|
8
|
+
* `/models` with a short timeout lets pi-vision-watcher distinguish
|
|
9
|
+
* vision-capable vs. text-only models automatically for both `/vision-watcher`
|
|
10
|
+
* and active-model handoff.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
import type { Api, Model } from "@earendil-works/pi-ai";
|
|
14
|
+
import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
|
|
15
|
+
|
|
16
|
+
/** Per-model capability metadata parsed from a router's `/models` endpoint. */
|
|
17
|
+
export interface RouterModelCapability {
|
|
18
|
+
id: string;
|
|
19
|
+
/** `true` = explicitly supports image input; `false` = explicitly text-only;
|
|
20
|
+
* `undefined` = omitted or unparseable. */
|
|
21
|
+
vision?: boolean;
|
|
22
|
+
/** Display name / router label / description used for false-vision heuristics
|
|
23
|
+
* on aliased models (e.g. `"Abliterated Large v2 (GLM-5.3, uncensored)"`). */
|
|
24
|
+
label?: string;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const DIRECT_VENDOR_HOSTS = new Set([
|
|
28
|
+
"api.openai.com",
|
|
29
|
+
"api.anthropic.com",
|
|
30
|
+
"generativelanguage.googleapis.com",
|
|
31
|
+
"api.deepseek.com",
|
|
32
|
+
"api.groq.com",
|
|
33
|
+
"api.mistral.ai",
|
|
34
|
+
"api.x.ai",
|
|
35
|
+
"api.cerebras.ai",
|
|
36
|
+
"api.together.xyz",
|
|
37
|
+
"api.fireworks.ai",
|
|
38
|
+
"api.minimax.io",
|
|
39
|
+
"api.moonshot.cn",
|
|
40
|
+
"api.moonshot.ai",
|
|
41
|
+
"open.bigmodel.cn",
|
|
42
|
+
"api.z.ai",
|
|
43
|
+
"dashscope.aliyuncs.com",
|
|
44
|
+
"dashscope-intl.aliyuncs.com",
|
|
45
|
+
]);
|
|
46
|
+
|
|
47
|
+
const DEFAULT_TIMEOUT_MS = 1_500;
|
|
48
|
+
const DEFAULT_TTL_MS = 5 * 60_000;
|
|
49
|
+
|
|
50
|
+
function firstStringArray(...candidates: unknown[]): string[] | undefined {
|
|
51
|
+
for (const c of candidates) {
|
|
52
|
+
if (!Array.isArray(c)) continue;
|
|
53
|
+
const strings = c.filter((v): v is string => typeof v === "string" && v.trim().length > 0);
|
|
54
|
+
if (strings.length > 0) return strings;
|
|
55
|
+
}
|
|
56
|
+
return undefined;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function firstBoolean(...candidates: unknown[]): boolean | undefined {
|
|
60
|
+
for (const c of candidates) {
|
|
61
|
+
if (typeof c === "boolean") return c;
|
|
62
|
+
}
|
|
63
|
+
return undefined;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function extractEntryVision(entry: Record<string, unknown>): boolean | undefined {
|
|
67
|
+
const modalities = entry.modalities as Record<string, unknown> | undefined;
|
|
68
|
+
const architecture = entry.architecture as Record<string, unknown> | undefined;
|
|
69
|
+
const capabilities = entry.capabilities as Record<string, unknown> | undefined;
|
|
70
|
+
|
|
71
|
+
const inputMods = firstStringArray(
|
|
72
|
+
modalities?.input,
|
|
73
|
+
architecture?.input_modalities,
|
|
74
|
+
entry.input_modalities,
|
|
75
|
+
capabilities?.input_modalities,
|
|
76
|
+
entry.input,
|
|
77
|
+
);
|
|
78
|
+
if (inputMods) {
|
|
79
|
+
return inputMods.some((m) => /^(?:image|vision|multimodal)$/i.test(m.trim()));
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
if (typeof architecture?.modality === "string" && architecture.modality.trim()) {
|
|
83
|
+
const [inputSide] = architecture.modality.split("->");
|
|
84
|
+
return /\bimage\b/i.test(inputSide ?? architecture.modality);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
return firstBoolean(
|
|
88
|
+
entry.supports_vision,
|
|
89
|
+
capabilities?.vision,
|
|
90
|
+
capabilities?.image,
|
|
91
|
+
capabilities?.multimodal,
|
|
92
|
+
entry.vision,
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
function extractEntryLabel(entry: Record<string, unknown>): string | undefined {
|
|
97
|
+
const parts: string[] = [];
|
|
98
|
+
const seen = new Set<string>();
|
|
99
|
+
for (const raw of [entry.magpie_label, entry.display_name, entry.name]) {
|
|
100
|
+
if (typeof raw !== "string") continue;
|
|
101
|
+
const trimmed = raw.trim();
|
|
102
|
+
if (!trimmed || seen.has(trimmed.toLowerCase())) continue;
|
|
103
|
+
seen.add(trimmed.toLowerCase());
|
|
104
|
+
parts.push(trimmed);
|
|
105
|
+
}
|
|
106
|
+
return parts.length > 0 ? parts.join(" · ") : undefined;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** Parse a router `/models` JSON payload into a map keyed by model id. */
|
|
110
|
+
export function parseRouterModelsPayload(payload: unknown): Map<string, RouterModelCapability> {
|
|
111
|
+
const out = new Map<string, RouterModelCapability>();
|
|
112
|
+
let list: unknown;
|
|
113
|
+
if (Array.isArray(payload)) {
|
|
114
|
+
list = payload;
|
|
115
|
+
} else if (payload && typeof payload === "object") {
|
|
116
|
+
const obj = payload as Record<string, unknown>;
|
|
117
|
+
list = Array.isArray(obj.data) ? obj.data : Array.isArray(obj.models) ? obj.models : undefined;
|
|
118
|
+
}
|
|
119
|
+
if (!Array.isArray(list)) return out;
|
|
120
|
+
|
|
121
|
+
for (const raw of list) {
|
|
122
|
+
if (!raw || typeof raw !== "object") continue;
|
|
123
|
+
const entry = raw as Record<string, unknown>;
|
|
124
|
+
if (typeof entry.id !== "string" || !entry.id.trim()) continue;
|
|
125
|
+
const id = entry.id.trim();
|
|
126
|
+
const vision = extractEntryVision(entry);
|
|
127
|
+
const label = extractEntryLabel(entry);
|
|
128
|
+
out.set(id, { id, vision, label });
|
|
129
|
+
}
|
|
130
|
+
return out;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** True when `baseUrl` points at a well-known direct cloud vendor API whose
|
|
134
|
+
* built-in Pi catalog already carries accurate capabilities. */
|
|
135
|
+
export function isDirectVendorBaseUrl(baseUrl: string | undefined | null): boolean {
|
|
136
|
+
if (!baseUrl) return false;
|
|
137
|
+
try {
|
|
138
|
+
const host = new URL(baseUrl).hostname.toLowerCase();
|
|
139
|
+
return DIRECT_VENDOR_HOSTS.has(host);
|
|
140
|
+
} catch {
|
|
141
|
+
return false;
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** Candidate `/models` URLs for an OpenAI-compatible `baseUrl`. */
|
|
146
|
+
export function routerModelsUrls(baseUrl: string): string[] {
|
|
147
|
+
const clean = baseUrl.trim().replace(/\/+$/, "");
|
|
148
|
+
if (!clean) return [];
|
|
149
|
+
if (/\/v\d+(?:[a-z0-9]*)?$/i.test(clean)) return [`${clean}/models`];
|
|
150
|
+
return [`${clean}/models`, `${clean}/v1/models`];
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Fetch and parse `/models` from a router `baseUrl`. Never throws; returns an
|
|
154
|
+
* empty map on network, timeout, auth, or parse failure. */
|
|
155
|
+
export async function fetchRouterCapabilities(
|
|
156
|
+
baseUrl: string,
|
|
157
|
+
headers?: Record<string, string>,
|
|
158
|
+
timeoutMs = DEFAULT_TIMEOUT_MS,
|
|
159
|
+
fetchImpl: typeof fetch = fetch,
|
|
160
|
+
): Promise<Map<string, RouterModelCapability>> {
|
|
161
|
+
const urls = routerModelsUrls(baseUrl);
|
|
162
|
+
for (const url of urls) {
|
|
163
|
+
const ac = new AbortController();
|
|
164
|
+
const timer = setTimeout(() => ac.abort(), timeoutMs);
|
|
165
|
+
try {
|
|
166
|
+
const res = await fetchImpl(url, {
|
|
167
|
+
method: "GET",
|
|
168
|
+
headers: { Accept: "application/json", ...headers },
|
|
169
|
+
signal: ac.signal,
|
|
170
|
+
});
|
|
171
|
+
if (!res.ok) continue;
|
|
172
|
+
const json = (await res.json()) as unknown;
|
|
173
|
+
return parseRouterModelsPayload(json);
|
|
174
|
+
} catch {
|
|
175
|
+
// Offline router, timeout, or non-JSON response: try next candidate or degrade.
|
|
176
|
+
} finally {
|
|
177
|
+
clearTimeout(timer);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
return new Map();
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
interface CacheEntry {
|
|
184
|
+
baseUrl: string;
|
|
185
|
+
fetchedAt: number;
|
|
186
|
+
models: Map<string, RouterModelCapability>;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/** Session-scoped cache of router `/models` capabilities keyed by provider id. */
|
|
190
|
+
export class RouterCapabilityCache {
|
|
191
|
+
private readonly entries = new Map<string, CacheEntry>();
|
|
192
|
+
private readonly inflight = new Map<string, Promise<void>>();
|
|
193
|
+
private readonly ttlMs: number;
|
|
194
|
+
private readonly timeoutMs: number;
|
|
195
|
+
private readonly fetchImpl?: typeof fetch;
|
|
196
|
+
|
|
197
|
+
constructor(options?: { ttlMs?: number; timeoutMs?: number; fetchImpl?: typeof fetch }) {
|
|
198
|
+
this.ttlMs = options?.ttlMs ?? DEFAULT_TTL_MS;
|
|
199
|
+
this.timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
|
|
200
|
+
this.fetchImpl = options?.fetchImpl;
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
clear(): void {
|
|
204
|
+
this.entries.clear();
|
|
205
|
+
this.inflight.clear();
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
get(provider: string | undefined, modelId: string | undefined): RouterModelCapability | undefined {
|
|
209
|
+
if (!provider || !modelId) return undefined;
|
|
210
|
+
return this.entries.get(provider)?.models.get(modelId);
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
hasFresh(provider: string | undefined): boolean {
|
|
214
|
+
if (!provider) return false;
|
|
215
|
+
const entry = this.entries.get(provider);
|
|
216
|
+
return !!entry && Date.now() - entry.fetchedAt < this.ttlMs;
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/** Refresh router capabilities for all (or specific) router providers in
|
|
220
|
+
* `modelRegistry`. Concurrent refreshes for the same provider share one
|
|
221
|
+
* request; failures degrade cleanly without throwing. */
|
|
222
|
+
async refreshProviders(
|
|
223
|
+
modelRegistry: Partial<ModelRegistry> | undefined | null,
|
|
224
|
+
options?: { providers?: string[]; force?: boolean },
|
|
225
|
+
): Promise<void> {
|
|
226
|
+
if (!modelRegistry?.getAvailable) return;
|
|
227
|
+
const targetSet = options?.providers ? new Set(options.providers) : null;
|
|
228
|
+
const force = options?.force ?? false;
|
|
229
|
+
|
|
230
|
+
const byProvider = new Map<string, { baseUrl: string; sampleModel: Model<Api> }>();
|
|
231
|
+
for (const model of modelRegistry.getAvailable()) {
|
|
232
|
+
if (!model.provider) continue;
|
|
233
|
+
if (targetSet && !targetSet.has(model.provider)) continue;
|
|
234
|
+
if (byProvider.has(model.provider)) continue;
|
|
235
|
+
const providerCfg = modelRegistry.getProvider?.(model.provider);
|
|
236
|
+
const baseUrl = model.baseUrl || providerCfg?.baseUrl;
|
|
237
|
+
if (!baseUrl || isDirectVendorBaseUrl(baseUrl)) continue;
|
|
238
|
+
byProvider.set(model.provider, { baseUrl, sampleModel: model });
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
const tasks: Promise<void>[] = [];
|
|
242
|
+
for (const [provider, { baseUrl, sampleModel }] of byProvider) {
|
|
243
|
+
const existing = this.entries.get(provider);
|
|
244
|
+
const fresh = existing && existing.baseUrl === baseUrl && Date.now() - existing.fetchedAt < this.ttlMs;
|
|
245
|
+
if (!force && fresh) continue;
|
|
246
|
+
|
|
247
|
+
const pending = this.inflight.get(provider);
|
|
248
|
+
if (pending) {
|
|
249
|
+
tasks.push(pending);
|
|
250
|
+
continue;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
const task = (async () => {
|
|
254
|
+
try {
|
|
255
|
+
const headers = await resolveRequestHeaders(modelRegistry, sampleModel);
|
|
256
|
+
const models = await fetchRouterCapabilities(baseUrl, headers, this.timeoutMs, this.fetchImpl ?? globalThis.fetch);
|
|
257
|
+
this.entries.set(provider, { baseUrl, fetchedAt: Date.now(), models });
|
|
258
|
+
} finally {
|
|
259
|
+
this.inflight.delete(provider);
|
|
260
|
+
}
|
|
261
|
+
})();
|
|
262
|
+
this.inflight.set(provider, task);
|
|
263
|
+
tasks.push(task);
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
await Promise.allSettled(tasks);
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
async function resolveRequestHeaders(
|
|
271
|
+
modelRegistry: Partial<ModelRegistry>,
|
|
272
|
+
sampleModel: Model<Api>,
|
|
273
|
+
): Promise<Record<string, string> | undefined> {
|
|
274
|
+
if (!modelRegistry.getApiKeyAndHeaders) return undefined;
|
|
275
|
+
try {
|
|
276
|
+
const auth = await modelRegistry.getApiKeyAndHeaders(sampleModel);
|
|
277
|
+
if (!auth?.ok) return undefined;
|
|
278
|
+
const headers: Record<string, string> = {};
|
|
279
|
+
if (auth.headers) {
|
|
280
|
+
for (const [k, v] of Object.entries(auth.headers)) {
|
|
281
|
+
if (typeof v === "string") headers[k] = v;
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
if (auth.apiKey && !Object.keys(headers).some((k) => k.toLowerCase() === "authorization")) {
|
|
285
|
+
headers.Authorization = `Bearer ${auth.apiKey}`;
|
|
286
|
+
}
|
|
287
|
+
return Object.keys(headers).length > 0 ? headers : undefined;
|
|
288
|
+
} catch {
|
|
289
|
+
return undefined;
|
|
290
|
+
}
|
|
291
|
+
}
|