pi-better-web-search 0.1.2 → 0.1.5

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 CHANGED
@@ -1,5 +1,40 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.5
4
+
5
+ - Rank models inside a provider family by capability tier first (cheapest tier
6
+ wins) and version number second, newest first. OpenAI tiers are
7
+ `luna → sol → astra` and Claude tiers are `haiku → sonnet → opus → fable`;
8
+ other families have no named tiers and sort purely by version. This replaces
9
+ the previous regex-based "likely search-capable" ordering, so legacy models
10
+ no longer win a lexicographic tie-break and large tiers are not called while
11
+ a cheaper sibling is available.
12
+ - Add a deeper fallback pass: after one candidate per family, alternate models
13
+ from other families are tried round-robin, so a provider account that rejects
14
+ a specific model (legacy id, account tier, regional availability) can still
15
+ serve a sibling model. Only the current model's provider id is excluded; a
16
+ different provider id in the same family is still tried.
17
+ - Classify failures for both search and fetch: provider-wide errors
18
+ (401/403/429, 5xx, insufficient balance, network failure, timeout, malformed
19
+ request header) skip the rest of that provider, while model-specific errors
20
+ keep trying sibling models.
21
+
22
+ ## 0.1.4
23
+
24
+ - Return `Failed: This tool is not available in this conversation.` when all
25
+ search providers fail during execution, preventing leaking internal provider
26
+ attempt errors to the model.
27
+ - Return `Failed: URL fetch is not available in this conversation.` when URL
28
+ fetching is requested but no URL-capable provider is available.
29
+ - Technical attempt errors and provider routing remain recorded in
30
+ `details.attempts` for logs and UI inspection.
31
+
32
+ ## 0.1.3
33
+
34
+ - Simplify error message when no supported provider is available: return
35
+ `Failed: This tool is not available in this conversation.` instead of exposing
36
+ internal provider and credential configuration instructions to the model.
37
+
3
38
  ## 0.1.2
4
39
 
5
40
  - Remove provider/model routing metadata from the model-facing JSON output
package/README.md CHANGED
@@ -8,7 +8,7 @@ provider supports it, automatically falls back across authenticated providers,
8
8
  and returns provider data as-is.
9
9
 
10
10
  [![CI](https://github.com/zhexusun10/pi-better-web-search/actions/workflows/ci.yml/badge.svg)](https://github.com/zhexusun10/pi-better-web-search/actions/workflows/ci.yml)
11
- [![npm](https://img.shields.io/badge/npm-v0.1.1-blue)](https://www.npmjs.com/package/pi-better-web-search)
11
+ [![npm](https://img.shields.io/badge/npm-v0.1.5-blue)](https://www.npmjs.com/package/pi-better-web-search)
12
12
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
13
13
  [![Pi 1.3](https://img.shields.io/badge/Pi-1.3-blue.svg)](https://pi.dev)
14
14
  [![Node](https://img.shields.io/badge/node-%3E%3D22.19-339933.svg)](https://nodejs.org)
@@ -142,10 +142,17 @@ For a search:
142
142
  when the cache fingerprint is current.
143
143
  3. The remaining provider families are tried in this fixed order:
144
144
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
145
- 4. Within a family, a likely search-capable authenticated model is selected
146
- first, with a deterministic tie-break. Remaining attempt slots are filled
147
- with other authenticated provider interfaces, but a failed provider id is
148
- never retried.
145
+ 4. Within a family, models are ordered by capability tier first (cheapest
146
+ available tier wins) and then by version number, newest first. OpenAI tiers
147
+ are `luna → sol → astra` and Claude tiers are
148
+ `haiku → sonnet → opus → fable`; other families have no named tiers and are
149
+ ordered purely by version. Ties are deterministic.
150
+ 5. Alternate models from other providers are tried round-robin, so a provider
151
+ that rejects one specific model can still serve a sibling. Only the current
152
+ model's provider id is excluded; a different provider id in the same family
153
+ is still tried. A provider-wide failure (auth, balance, network, timeout,
154
+ malformed request) skips the rest of that provider; a model-specific
155
+ failure keeps trying sibling models.
149
156
 
150
157
  URL fetching uses the same idea, but considers only providers that implement
151
158
  URL fetching.
@@ -120,8 +120,14 @@ Provider 识别顺序:
120
120
  2. 缓存指纹有效时,使用记住的搜索 provider。
121
121
  3. 其余 provider family 按固定顺序尝试:
122
122
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**。
123
- 4. 同一 family 内优先选择看起来支持搜索的已认证模型。剩余槽位用其他已认证
124
- provider 接口填充;同一个 provider id 不会用不同模型重复尝试。
123
+ 4. 同一 family 内先按能力等级排序(便宜的等级优先,未知等级排最后):
124
+ OpenAI 为 `luna → sol → astra`,Claude 为 `haiku → sonnet → opus → fable`;
125
+ 其他 family 没有命名等级,直接按版本号从新到旧排序。同级内版本号大的优先。
126
+ 5. 除当前模型的 provider id 外,其他 provider 的备用模型会按 round-robin 继续尝试,
127
+ 这样即使某个账号拒绝某个具体模型,也能换用同 provider 的其他模型。
128
+ 同一 family 下不同 provider id(如 `openai` 与 `openai-codex`)仍会尝试。
129
+ provider 级失败(鉴权、余额、网络、超时、请求头异常)会跳过该 provider 的
130
+ 其余模型;模型级失败则继续尝试同 provider 的其他模型。
125
131
 
126
132
  URL 抓取使用同样的思路,但只考虑实现了 URL 抓取的 provider。
127
133
 
@@ -72,15 +72,22 @@ Search candidates:
72
72
  2. The remembered search provider when the cache fingerprint is current.
73
73
  3. One candidate per remaining family in this order:
74
74
  **DeepSeek → Ollama → Google → OpenAI → xAI → Anthropic**.
75
- 4. Remaining authenticated provider interfaces, up to 12 attempts.
75
+ 4. Alternate models from every provider except the current model's provider
76
+ id, round-robin across families, up to 12 attempts. A different provider id
77
+ in the same family (for example `openai` vs `openai-codex`) is still tried.
76
78
 
77
79
  Fetch candidates use the same shape but include only adapters with
78
80
  `supportsUrls` and a `fetch` implementation. The fetch cap is 6 attempts.
79
81
 
80
- Within a family, likely search-capable model IDs rank first (for example
81
- `gpt-5`/`gpt-4.1`/`gpt-4o` for OpenAI, `gemini` for Google, `claude` for
82
- Anthropic, `grok` for xAI). Ties are deterministic. A provider id that was
83
- already selected is not retried with another model.
82
+ Within a family, models are ordered by capability tier first and version
83
+ second. Named tiers rank cheapest first and unknown ids rank last: OpenAI uses
84
+ `luna → sol → astra` and Claude uses `haiku → sonnet → opus → fable`. Other
85
+ families have no named tiers. Version numbers are compared as tuples with the
86
+ newest first (`gpt-7.0` before `gpt-6.1` before `gpt-4.1`, `gemini-3.8` before
87
+ `gemini-2.5`). Ties fall back to the deterministic `provider/id@baseUrl` order.
88
+ A provider id is only retried with another model when the first failure was
89
+ model-specific; provider-wide failures (auth, balance, network, timeout,
90
+ malformed request) skip the rest of that provider.
84
91
 
85
92
  The current model is preferred when it supports search. The cache is a fallback,
86
93
  not an override. When the current model is unsupported, the cached provider is
@@ -30,7 +30,7 @@ local `pi-web-search` reference checkout, `.env` files, and `DESIGN.md`.
30
30
  npm run build
31
31
  ```
32
32
 
33
- This produces `dist/pi-better-web-search-0.1.2.tgz`. The tarball is not
33
+ This produces `dist/pi-better-web-search-0.1.4.tgz`. The tarball is not
34
34
  committed.
35
35
 
36
36
  ## Publish
@@ -42,7 +42,7 @@ npm publish --access public
42
42
  Alternatively, publish the verified tarball directly:
43
43
 
44
44
  ```bash
45
- npm publish dist/pi-better-web-search-0.1.2.tgz --access public
45
+ npm publish dist/pi-better-web-search-0.1.4.tgz --access public
46
46
  ```
47
47
 
48
48
  `prepublishOnly` reruns the checks, tests, and package verification. npm may
@@ -51,10 +51,10 @@ require browser or OTP authentication.
51
51
  ## Tag and release
52
52
 
53
53
  ```bash
54
- git tag -a v0.1.2 -m "v0.1.2"
55
- git push origin v0.1.2
56
- gh release create v0.1.2 dist/pi-better-web-search-0.1.2.tgz \
57
- --title "v0.1.2" \
54
+ git tag -a v0.1.4 -m "v0.1.4"
55
+ git push origin v0.1.4
56
+ gh release create v0.1.4 dist/pi-better-web-search-0.1.4.tgz \
57
+ --title "v0.1.4" \
58
58
  --notes-file /path/to/release-notes.md
59
59
  ```
60
60
 
package/lib/candidates.ts CHANGED
@@ -52,15 +52,53 @@ export const MAX_FETCH_CANDIDATES = FETCH_ATTEMPT_CAP;
52
52
  export const SEARCH_CAP = SEARCH_ATTEMPT_CAP;
53
53
  export const FETCH_CAP = FETCH_ATTEMPT_CAP;
54
54
 
55
- const PREFERRED_MODEL_PATTERNS: Record<ProviderFamily, RegExp> = {
56
- deepseek: /deepseek/i,
57
- ollama: /gpt-oss|qwen|llama|deepseek|mistral/i,
58
- google: /gemini/i,
59
- openai: /gpt-5|gpt-4\.1|gpt-4o|o[134]/i,
60
- xai: /grok/i,
61
- anthropic: /claude/i,
55
+ /**
56
+ * Cheapest-first capability tiers per family, ordered small to large. The
57
+ * first matching tier wins and ids that match no tier rank last, so fallback
58
+ * does not burn a large model when a small one is available. Version numbers
59
+ * are compared separately, newest first. Only families whose provider uses
60
+ * tier names need an entry; everywhere else every model shares tier 0.
61
+ */
62
+ function tierMatcher(name: string): RegExp {
63
+ return new RegExp(`(?:^|[^a-z0-9])${name}(?:$|[^a-z0-9])`, "i");
64
+ }
65
+
66
+ const MODEL_TIERS: Partial<Record<ProviderFamily, readonly RegExp[]>> = {
67
+ openai: ["luna", "sol", "astra"].map(tierMatcher),
68
+ anthropic: ["haiku", "sonnet", "opus", "fable"].map(tierMatcher),
62
69
  };
63
70
 
71
+ function modelTier(candidate: Candidate): number {
72
+ const patterns = MODEL_TIERS[candidate.family];
73
+ if (!patterns) return 0;
74
+ for (let index = 0; index < patterns.length; index += 1) {
75
+ if (patterns[index].test(candidate.model.id)) return index;
76
+ }
77
+ return patterns.length;
78
+ }
79
+
80
+ /**
81
+ * Parse the first version-like run in a model id into a numeric tuple.
82
+ * `gpt-6.1` -> [6, 1], `claude-opus-4-5` -> [4, 5], `gpt-oss:120b` -> [120].
83
+ * Ids without a number return an empty tuple and rank below versioned ones.
84
+ */
85
+ function versionTuple(id: string): number[] {
86
+ const match = id.match(/\d+(?:[.-]\d+)*/);
87
+ if (!match) return [];
88
+ return match[0].split(/[.-]/).map((part) => Number.parseInt(part, 10));
89
+ }
90
+
91
+ /** Compare version tuples so that a larger, newer version sorts first. */
92
+ function compareVersionsDesc(left: number[], right: number[]): number {
93
+ const length = Math.max(left.length, right.length);
94
+ for (let index = 0; index < length; index += 1) {
95
+ const a = left[index] ?? 0;
96
+ const b = right[index] ?? 0;
97
+ if (a !== b) return b - a;
98
+ }
99
+ return 0;
100
+ }
101
+
64
102
  function isCandidate(value: Candidate | Model<Api>): value is Candidate {
65
103
  return "model" in value && "family" in value && "adapter" in value;
66
104
  }
@@ -140,15 +178,12 @@ function compareText(left: string, right: string): number {
140
178
  return left < right ? -1 : left > right ? 1 : 0;
141
179
  }
142
180
 
143
- function modelRank(candidate: Candidate): number {
144
- return PREFERRED_MODEL_PATTERNS[candidate.family].test(candidate.model.id) ? 0 : 1;
145
- }
146
-
147
181
  /** Rank candidates inside one family independently of registry order. */
148
182
  export function rankFamilyCandidates(candidates: Candidate[]): Candidate[] {
149
183
  return [...candidates].sort(
150
184
  (left, right) =>
151
- modelRank(left) - modelRank(right)
185
+ modelTier(left) - modelTier(right)
186
+ || compareVersionsDesc(versionTuple(left.model.id), versionTuple(right.model.id))
152
187
  || compareText(candidateKey(left), candidateKey(right))
153
188
  || compareText(left.model.baseUrl ?? "", right.model.baseUrl ?? ""),
154
189
  );
@@ -193,6 +228,16 @@ function addUnique(
193
228
  return true;
194
229
  }
195
230
 
231
+ function usableFamilyCandidates(
232
+ resolution: ResolutionContext,
233
+ family: ProviderFamily,
234
+ isUsable: (candidate: Candidate) => boolean,
235
+ ): Candidate[] {
236
+ return rankFamilyCandidates(
237
+ resolution.available.filter((candidate) => candidate.family === family && isUsable(candidate)),
238
+ );
239
+ }
240
+
196
241
  function buildCandidates(
197
242
  resolution: ResolutionContext,
198
243
  isUsable: (candidate: Candidate) => boolean,
@@ -223,23 +268,44 @@ function buildCandidates(
223
268
  if (selected.length >= cap) break;
224
269
  if (representedFamilies.has(family)) continue;
225
270
 
226
- const candidates = rankFamilyCandidates(
227
- resolution.available.filter((candidate) => candidate.family === family && isUsable(candidate)),
228
- );
271
+ const candidates = usableFamilyCandidates(resolution, family, isUsable);
229
272
  if (candidates[0] && addUnique(selected, candidates[0], seen, cap)) {
230
273
  representedFamilies.add(family);
231
274
  }
232
275
  }
233
276
 
234
- // Fill any remaining attempts with other available provider interfaces. A
235
- // provider id is never retried with a different model, and the fixed family
236
- // priority above still determines which interface comes first.
237
- for (const candidate of resolution.available) {
238
- if (selected.length >= cap) break;
239
- if (!isUsable(candidate)) continue;
240
- if (seen.has(candidateKey(candidate))) continue;
241
- if (selected.some((entry) => entry.model.provider === candidate.model.provider)) continue;
242
- addUnique(selected, candidate, seen, cap);
277
+ // Deeper fallback: alternate models from providers other than the current
278
+ // model's provider. Providers frequently reject one specific model (legacy
279
+ // IDs, account tiers, regional availability) while serving a sibling, so a
280
+ // single interface per family is too fragile. Round-robin across families so
281
+ // every family gets a second chance before any family gets a third, keeping
282
+ // the broad cross-provider coverage that the one-per-family pass provides.
283
+ //
284
+ // Only the current model's provider id is excluded: a different provider id
285
+ // in the same family (for example `openai` vs `openai-codex`, or `anthropic`
286
+ // vs `opencode-go`) has its own credentials and endpoint and is still worth
287
+ // trying. This mirrors the original "never repeat a provider id" rule while
288
+ // still allowing sibling models of a fallback provider.
289
+ const currentProvider = resolution.current?.model.provider;
290
+ const queues = new Map<ProviderFamily, Candidate[]>();
291
+ for (const family of PROVIDER_FAMILIES) {
292
+ const queue = usableFamilyCandidates(resolution, family, isUsable).filter(
293
+ (candidate) =>
294
+ candidate.model.provider !== currentProvider
295
+ && !seen.has(candidateKey(candidate)),
296
+ );
297
+ if (queue.length > 0) queues.set(family, queue);
298
+ }
299
+
300
+ let progressed = true;
301
+ while (selected.length < cap && progressed) {
302
+ progressed = false;
303
+ for (const family of PROVIDER_FAMILIES) {
304
+ if (selected.length >= cap) break;
305
+ const queue = queues.get(family);
306
+ const next = queue?.shift();
307
+ if (next && addUnique(selected, next, seen, cap)) progressed = true;
308
+ }
243
309
  }
244
310
 
245
311
  return selected;
package/lib/search.ts CHANGED
@@ -173,6 +173,33 @@ function attemptKey(candidate: Candidate): ProviderRef {
173
173
  return { provider: candidate.model.provider, model: candidate.model.id };
174
174
  }
175
175
 
176
+ /**
177
+ * Provider-wide failures cannot be fixed by trying another model from the same
178
+ * provider: the credential, balance, network path, or request shape is broken.
179
+ * Model-specific failures (an unsupported or missing model, or a rejected
180
+ * legacy model) can be, so the orchestrator keeps trying sibling models for
181
+ * those. The classifier is intentionally conservative: anything it does not
182
+ * recognize is treated as model-specific, which only costs an extra attempt.
183
+ */
184
+ const PROVIDER_WIDE_FAILURE_PATTERNS: readonly RegExp[] = [
185
+ // HTTP status codes as adapters format them: `(401 Unauthorized)`,
186
+ // `(500 Internal Server Error)`, `HTTP 429`, `status code 403`.
187
+ /(?:\(|HTTP\s+|status(?:\s+code)?\s*)(?:401|403|429)\b/i,
188
+ /(?:\(|HTTP\s+|status(?:\s+code)?\s*)5\d{2}\b/i,
189
+ /\bunauthoriz(?:ed|ation)?\b/i,
190
+ /\bforbidden\b/i,
191
+ /\binsufficient\b[^.]*\b(?:balance|quota|credit|credits|funds|billing)\b/i,
192
+ /\brate.?limit/i,
193
+ /\b(?:ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH)\b/,
194
+ /\bfetch failed\b/i,
195
+ /\btimed?\s?out\b/i,
196
+ /\bbytestring\b/i,
197
+ ];
198
+
199
+ export function isProviderWideFailure(message: string): boolean {
200
+ return PROVIDER_WIDE_FAILURE_PATTERNS.some((pattern) => pattern.test(message));
201
+ }
202
+
176
203
  function resultCount(result: { results?: unknown }): number | undefined {
177
204
  return Array.isArray(result.results) ? result.results.length : undefined;
178
205
  }
@@ -222,8 +249,14 @@ async function runSearch(
222
249
  const candidates = getSearchCandidates(resolution);
223
250
  if (candidates.length === 0) return undefined;
224
251
 
252
+ // Providers whose failure was not model-specific are not retried with a
253
+ // different model, so a dead credential or network path does not burn the
254
+ // whole attempt budget on one interface.
255
+ const failedProviders = new Set<string>();
256
+
225
257
  for (const candidate of candidates) {
226
258
  if (externalSignal?.aborted) throw abortReason(externalSignal);
259
+ if (failedProviders.has(candidate.model.provider)) continue;
227
260
 
228
261
  const timeout = timeoutMs();
229
262
  const signal = attemptSignal(externalSignal, timeout);
@@ -238,12 +271,14 @@ async function runSearch(
238
271
  return { candidate, result: result ?? {} };
239
272
  } catch (error) {
240
273
  if (externalSignal?.aborted) throw abortReason(externalSignal);
274
+ const message = errorMessage(error);
241
275
  attempts.push({
242
276
  phase: "search",
243
277
  provider: candidate.model.provider,
244
278
  model: candidate.model.id,
245
- message: errorMessage(error),
279
+ message,
246
280
  });
281
+ if (isProviderWideFailure(message)) failedProviders.add(candidate.model.provider);
247
282
  }
248
283
  }
249
284
 
@@ -309,9 +344,14 @@ async function runFetch(
309
344
  let preferred: Candidate | undefined;
310
345
  let preferredSuccessful = 0;
311
346
 
347
+ // As with search, a provider-wide failure is not retried with another model
348
+ // from the same provider id.
349
+ const failedProviders = new Set<string>();
350
+
312
351
  for (const candidate of candidates) {
313
352
  if (remaining.length === 0) break;
314
353
  if (externalSignal?.aborted) throw abortReason(externalSignal);
354
+ if (failedProviders.has(candidate.model.provider)) continue;
315
355
 
316
356
  const timeout = timeoutMs();
317
357
  const signal = attemptSignal(externalSignal, timeout);
@@ -356,6 +396,7 @@ async function runFetch(
356
396
  model: candidate.model.id,
357
397
  message,
358
398
  });
399
+ if (isProviderWideFailure(message)) failedProviders.add(candidate.model.provider);
359
400
  for (const index of remaining) {
360
401
  states[index].error = message;
361
402
  }
@@ -416,26 +457,20 @@ export async function runWebSearch(
416
457
  if (searchRequested) {
417
458
  const candidates = getSearchCandidates(resolution);
418
459
  if (candidates.length === 0) {
419
- const message =
420
- "No supported web search provider is available. Configure a supported model or credentials and try again.";
460
+ const message = "This tool is not available in this conversation.";
421
461
  return formatError(message, { attempts, error: message });
422
462
  }
423
463
 
424
464
  searchSuccess = await runSearch(resolution, query, signal, onUpdate, attempts);
425
465
  if (!searchSuccess) {
426
- const failure = attemptSummary(attempts, "search") || "No provider returned a result.";
427
- const message = `Web search failed. ${failure}`;
466
+ const message = "This tool is not available in this conversation.";
428
467
  return formatError(message, { attempts, error: message });
429
468
  }
430
469
  }
431
470
 
432
471
  const fetchCandidates = validFetchRequested ? getFetchCandidates(resolution) : [];
433
472
  if (validFetchRequested && fetchCandidates.length === 0) {
434
- const requestedUrls = [
435
- ...urls,
436
- ...urlErrors.map((entry) => `${entry.url} (${entry.error})`),
437
- ];
438
- const message = `URL fetch failed. No URL fetch provider is available for: ${requestedUrls.join(", ")}`;
473
+ const message = "URL fetch is not available in this conversation.";
439
474
  // The search half succeeded; remember it even though the URL half did not.
440
475
  const cache = nextCache(resolution, searchSuccess?.candidate, undefined);
441
476
  if (cache) writeCache(cache);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-web-search",
3
- "version": "0.1.2",
3
+ "version": "0.1.5",
4
4
  "description": "A better provider-native web_search tool for pi: raw results, automatic provider fallback, URL analysis, and native DeepSeek Search/Fetch.",
5
5
  "type": "module",
6
6
  "license": "MIT",