pi-better-web-search 1.0.1 → 1.0.2

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,15 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.2 — Cleaner search results
4
+
5
+ ### Fixes
6
+
7
+ - Omit Keenable search/fetch billing `usage`, Perplexity request `id` and
8
+ `server_time`, and Exa search `requestId`, `costDollars`, `searchTime`,
9
+ `warnings` and deprecated `resolvedSearchType` from model-facing results.
10
+ Preserve source content, dates, scores, citations, truncation indicators,
11
+ Exa `notices`, unknown fields and nested fields with the same names.
12
+
3
13
  ## 1.0.1 — Your pi login, your search tools
4
14
 
5
15
  ### Fixes
package/README.md CHANGED
@@ -63,7 +63,7 @@ Built to be the web-search tool you reach for first:
63
63
 
64
64
  ## Install and search
65
65
 
66
- **Version 1.0.1 is available.** [Release notes and package download](https://github.com/zhexusun10/pi-better-web-search/releases/tag/v1.0.1).
66
+ **Version 1.0.2 is available.** [Release notes and package download](https://github.com/zhexusun10/pi-better-web-search/releases/tag/v1.0.2).
67
67
 
68
68
  ```bash
69
69
  pi install npm:pi-better-web-search
@@ -464,7 +464,9 @@ tool call.
464
464
 
465
465
  ## Raw provider results
466
466
 
467
- Provider data is returned in a JSON wrapper without cleanup. A search looks like
467
+ Provider content is returned in a JSON wrapper, with known billing, request
468
+ tracking and timing fields omitted from standalone API responses. Search results,
469
+ page text and source evidence retain their provider fields. A search looks like
468
470
  this:
469
471
 
470
472
  ```json
@@ -492,6 +494,10 @@ this:
492
494
  - Citation markers are not inserted, and no "Sources" or "Additional results"
493
495
  sections are appended.
494
496
  - Redirects are not resolved and sources are not derived.
497
+ - Known standalone API bookkeeping is omitted: Keenable `usage`, Perplexity
498
+ `id` / `server_time`, and Exa `requestId` / `costDollars` / `searchTime` /
499
+ `warnings` / `resolvedSearchType`. Exa `notices` remain available to the model.
500
+ See [response metadata handling](docs/search-apis.md#interfaces).
495
501
  - Unknown provider fields are preserved when the result fits the size guard.
496
502
 
497
503
  A final output-size guard limits model-facing results and errors to **96,000
@@ -648,7 +654,7 @@ npm run build
648
654
  ```
649
655
 
650
656
  `npm run build` runs the checks and tests, verifies the npm file list, and packs
651
- `dist/pi-better-web-search-1.0.1.tgz`. Nothing is published automatically.
657
+ `dist/pi-better-web-search-1.0.2.tgz`. Nothing is published automatically.
652
658
 
653
659
  The test suite uses plain `.mjs` files that import the `.ts` sources directly.
654
660
  It mocks `globalThis.fetch`, uses a temporary cache file, and exercises
@@ -53,7 +53,7 @@ Artificial Analysis Search Index 把差距画得很直观:虚线是**无搜索
53
53
 
54
54
  ## 安装,登录,开搜
55
55
 
56
- **1.0.1 已可用。** [查看更新说明与下载安装包](https://github.com/zhexusun10/pi-better-web-search/releases/tag/v1.0.1)。
56
+ **1.0.2 已可用。** [查看更新说明与下载安装包](https://github.com/zhexusun10/pi-better-web-search/releases/tag/v1.0.2)。
57
57
 
58
58
  ```bash
59
59
  pi install npm:pi-better-web-search
@@ -395,7 +395,8 @@ rm ~/.pi/agent/better-web-search.json
395
395
 
396
396
  ## 原始结果
397
397
 
398
- Provider 数据放在 JSON 外层中返回,不做清理。示例:
398
+ Provider 内容放在 JSON 外层中返回。独立 API 响应中已知的计费、请求追踪和
399
+ 耗时字段会裁掉;搜索结果、网页正文和来源证据保留 provider 的原始字段。示例:
399
400
 
400
401
  ```json
401
402
  {
@@ -421,6 +422,10 @@ Provider 数据放在 JSON 外层中返回,不做清理。示例:
421
422
  - 结果不重排、不总结。
422
423
  - 不插入 citation 标记,不追加 "Sources" 或 "Additional results"。
423
424
  - 不解析 redirect,不派生 sources。
425
+ - 裁掉独立 API 的已知无关字段:Keenable 的 `usage`,Perplexity 的
426
+ `id` / `server_time`,以及 Exa 的 `requestId` / `costDollars` / `searchTime` /
427
+ `warnings` / `resolvedSearchType`。Exa 的 `notices` 解释结果生成方式,继续保留。
428
+ 只处理响应外层,不递归删除结果或正文中的同名字段,详见[响应元数据处理](search-apis.md#interfaces)。
424
429
  - 未超出大小限制时,provider 的未知字段也会保留。
425
430
 
426
431
  最终大小保护默认限制结果及错误文本不超过 **96,000 个 Unicode code point**。
@@ -544,7 +549,7 @@ npm run build
544
549
  ```
545
550
 
546
551
  `npm run build` 会运行检查、测试、包内容验证,并生成
547
- `dist/pi-better-web-search-1.0.1.tgz`。不会自动发布。
552
+ `dist/pi-better-web-search-1.0.2.tgz`。不会自动发布。
548
553
 
549
554
  测试是 `.mjs` 文件,直接导入 `.ts` 源码,mock `globalThis.fetch`,使用临时缓存
550
555
  目录。详见 [测试](testing.md) 和 [发布](publishing.md)。
package/docs/providers.md CHANGED
@@ -49,8 +49,10 @@ failures; only unresolved URLs proceed to fallback.
49
49
  Configured **Keenable → Exa → Perplexity → standalone DeepSeek** precede
50
50
  automatic model routing (fetch skips Perplexity); explicit per-phase preferences
51
51
  still win and fallback remains enabled. Health cooldowns reorder automatic
52
- native routes only, not the explicit or standalone priorities. Search responses
53
- and each fetched raw document are preserved. These services do not participate in model-tier ranking.
52
+ native routes only, not the explicit or standalone priorities. Search content
53
+ and each fetched raw document are preserved, with known API bookkeeping omitted
54
+ as described in [response metadata handling](search-apis.md#interfaces). These
55
+ services do not participate in model-tier ranking.
54
56
  The [skill comparison](search-skills.md) explains the approved Exa options and
55
57
  why no additional model-facing parameter or prompt injection was added.
56
58
 
@@ -286,6 +288,7 @@ a per-URL error.
286
288
  preservation, search evidence, errors, aborts, and URL behavior.
287
289
  6. Update this document, `README.md`, and `CHANGELOG.md`.
288
290
 
289
- Keep provider results raw. If the provider returns an answer, keep it as the
291
+ Keep provider content raw, apart from the documented response-level API
292
+ bookkeeping omissions. If the provider returns an answer, keep it as the
290
293
  provider returned it. If it returns result objects, preserve their fields and
291
294
  order. Do not add a normalization layer.
@@ -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-1.0.1.tgz`. The tarball is not
33
+ This produces `dist/pi-better-web-search-1.0.2.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-1.0.1.tgz --access public
45
+ npm publish dist/pi-better-web-search-1.0.2.tgz --access public
46
46
  ```
47
47
 
48
48
  When publishing from the checkout, `prepublishOnly` reruns the checks, tests,
@@ -52,10 +52,10 @@ build` first to verify it. npm may require browser or OTP authentication.
52
52
  ## Tag and release
53
53
 
54
54
  ```bash
55
- git tag -a v1.0.1 -m "v1.0.1"
56
- git push origin v1.0.1
57
- gh release create v1.0.1 dist/pi-better-web-search-1.0.1.tgz \
58
- --title "v1.0.1" \
55
+ git tag -a v1.0.2 -m "v1.0.2"
56
+ git push origin v1.0.2
57
+ gh release create v1.0.2 dist/pi-better-web-search-1.0.2.tgz \
58
+ --title "v1.0.2" \
59
59
  --notes-file /path/to/release-notes.md
60
60
  ```
61
61
 
@@ -21,6 +21,23 @@ Web Search scores **74**. See the [original screenshot](../assets/search-index.p
21
21
  | Keenable | `POST https://api.keenable.ai/v1/search` | `GET https://api.keenable.ai/v1/fetch` | `KEENABLE_API_KEY` or explicit public access |
22
22
  | Exa | `POST https://api.exa.ai/search` | `POST https://api.exa.ai/contents` | `EXA_API_KEY` |
23
23
 
24
+ Successful responses omit known API bookkeeping before reaching the model:
25
+
26
+ | Provider | Omitted fields |
27
+ |---|---|
28
+ | Keenable search and fetch | `usage` (billing, credits and remaining balance) |
29
+ | Perplexity search | `id`, `server_time` (request tracking and server timing) |
30
+ | Exa search | `requestId`, `costDollars`, `searchTime`, `warnings`, `resolvedSearchType` |
31
+
32
+ This filtering is shallow and provider-specific. Result objects, page text,
33
+ source dates, scores, citations, truncation indicators and unknown fields remain
34
+ unchanged. Exa `notices` are retained because they explain how results were
35
+ produced; `warnings` are request diagnostics and `resolvedSearchType` is deprecated.
36
+ Exa fetch already returns individual documents rather than the response envelope.
37
+ Native model adapters select search results, answers and source evidence without
38
+ forwarding response-level token usage. HTTP errors retain their diagnostic details
39
+ for normal fallback and troubleshooting.
40
+
24
41
  ### DeepSeek: native Search/Fetch
25
42
 
26
43
  Terminal login works without a pi chat model. Both native endpoints use the
@@ -48,9 +65,9 @@ The request is exactly:
48
65
 
49
66
  Authorization is `Bearer <PERPLEXITY_API_KEY>`. **Fast search is not used.**
50
67
  There is no `effort`, `preset`, `model`, `tools`, conversation state or generated
51
- answer. Neither Agent nor Orchestrator APIs are called. The whole response,
52
- including `results`, `id`, `server_time` and unknown fields, is returned inside
53
- `search` without rewriting the results.
68
+ answer. Neither Agent nor Orchestrator APIs are called. `results` and unknown
69
+ fields are returned inside `search` without rewriting the results; the outer
70
+ request `id` and `server_time` are omitted.
54
71
 
55
72
  Perplexity alone exposes a query-only schema. Configure Keenable or an existing
56
73
  URL-capable provider to add `urls`; a combined call can search with Perplexity
@@ -65,7 +82,8 @@ unauthenticated Perplexity request.
65
82
 
66
83
  Search sends `{ "query": "...", "mode": "pro", "max_results": 10 }`, not the
67
84
  fast `realtime` mode. Fetch uses GET with URL-encoded `url` and `live=true`,
68
- without an LLM extraction `prompt`. Response objects and metadata are preserved.
85
+ without an LLM extraction `prompt`. Response content and source metadata are
86
+ preserved; the outer billing `usage` object is omitted from both operations.
69
87
  Keyed requests use `X-API-Key: <KEENABLE_API_KEY>`.
70
88
 
71
89
  Without a key, explicit public access uses `/v1/search/public` and
@@ -95,11 +113,12 @@ With `X-API-Key: <EXA_API_KEY>`, search sends the user-approved request:
95
113
  }
96
114
  ```
97
115
 
98
- `type` is omitted (server default `auto`). The complete response, including
99
- `requestId`, raw `results`/highlights, `costDollars`, `searchTime` and unknown
100
- fields, is preserved. There is no chat model, SDK, Answer/Agent API or generated
101
- objective. The model-facing contract stays `query` / `urls`; other advanced
102
- options remain off. See the [skill comparison and decision table](search-skills.md).
116
+ `type` is omitted (server default `auto`). Raw `results`/highlights, `notices`
117
+ and unknown fields are preserved. Request tracking, cost, timing, request
118
+ warnings and the deprecated resolved search type are omitted as listed above.
119
+ There is no chat model, SDK, Answer/Agent API or generated objective. The
120
+ model-facing contract stays `query` / `urls`; other advanced options remain
121
+ off. See the [skill comparison and decision table](search-skills.md).
103
122
 
104
123
  URL-only calls use `POST /contents` without performing a search:
105
124
 
package/docs/testing.md CHANGED
@@ -17,7 +17,7 @@ npm run verify:package
17
17
  tarball contains runtime sources, docs, assets, and metadata, while excluding
18
18
  tests, scripts, CI files, the local reference checkout, and `DESIGN.md`.
19
19
  - `npm run build` runs the checks, tests, package verification, and packs
20
- `dist/pi-better-web-search-1.0.1.tgz`.
20
+ `dist/pi-better-web-search-1.0.2.tgz`.
21
21
 
22
22
  Tests import the TypeScript sources directly. The suite mocks `globalThis.fetch`
23
23
  and uses temporary cache directories. Coverage includes:
@@ -33,8 +33,9 @@ and uses temporary cache directories. Coverage includes:
33
33
  - dedicated API protocols, standard Perplexity search (no fast/effort/Agent API),
34
34
  Keenable keyed/public pro search and live GET fetch, Exa 10-result highlights
35
35
  search and full-text `/contents` fetch, per-URL statuses, reordered/redirected
36
- results, duplicate URLs, raw metadata, standalone
37
- exposure, explicit/configured/native ordering and fallback;
36
+ results, duplicate URLs, source metadata, omission of response-level billing,
37
+ request tracking and timing fields, retained Exa notices and nested same-name
38
+ fields, standalone exposure, explicit/configured/native ordering and fallback;
38
39
  - API configuration menus, public-access consent, secret-free persistence,
39
40
  credential redaction and Retry-After seconds/HTTP-date behavior;
40
41
  - atomic settings/cache replacement with injected partial-write and rename
@@ -1,6 +1,7 @@
1
1
  import { dedicatedKey } from "../dedicated-config.ts";
2
2
  import { redactSecrets } from "../redact.ts";
3
3
  import { dedicatedRequest } from "./dedicated-http.ts";
4
+ import { omitResponseMetadata } from "./response-metadata.ts";
4
5
  import type { ProviderAdapter } from "./types.ts";
5
6
 
6
7
  function isRecord(value: unknown): value is Record<string, unknown> {
@@ -31,7 +32,7 @@ export const exaAdapter: ProviderAdapter = {
31
32
  body: JSON.stringify({ query, numResults: 10, contents: { highlights: true } }),
32
33
  }, signal);
33
34
  if (!Array.isArray(data.results)) throw new Error("Exa Search returned no results array");
34
- return data;
35
+ return omitResponseMetadata(data, ["requestId", "costDollars", "searchTime", "warnings", "resolvedSearchType"]);
35
36
  },
36
37
  async fetch(_ctx, _model, urls, _query, signal) {
37
38
  // Capture the credential before awaiting HTTP; login may rotate it while
@@ -1,6 +1,7 @@
1
1
  import { readProviderPreferences } from "../preferences.ts";
2
2
  import { dedicatedRequest } from "./dedicated-http.ts";
3
3
  import { errorMessage, HttpError, isAbortError } from "./http.ts";
4
+ import { omitResponseMetadata } from "./response-metadata.ts";
4
5
  import type { ProviderAdapter, ProviderFetchEntry } from "./types.ts";
5
6
 
6
7
  function endpoint(operation: "search" | "fetch", hasKey: boolean): string {
@@ -27,7 +28,7 @@ export const keenableAdapter: ProviderAdapter = {
27
28
  body: JSON.stringify({ query, mode: "pro", max_results: 10 }),
28
29
  }, signal);
29
30
  if (!Array.isArray(data.results)) throw new Error("Keenable returned no results array");
30
- return data;
31
+ return omitResponseMetadata(data, ["usage"]);
31
32
  },
32
33
  async fetch(_ctx, _model, urls, _query, signal) {
33
34
  const entries: ProviderFetchEntry[] = [];
@@ -42,7 +43,7 @@ export const keenableAdapter: ProviderAdapter = {
42
43
  if (typeof data.content !== "string" || typeof data.url !== "string") {
43
44
  entries.push({ url, error: "Keenable returned no URL or page content" });
44
45
  } else {
45
- entries.push({ url, data });
46
+ entries.push({ url, data: omitResponseMetadata(data, ["usage"]) });
46
47
  }
47
48
  } catch (error) {
48
49
  if (isAbortError(error, signal)) throw error;
@@ -1,4 +1,5 @@
1
1
  import { dedicatedRequest } from "./dedicated-http.ts";
2
+ import { omitResponseMetadata } from "./response-metadata.ts";
2
3
  import type { ProviderAdapter } from "./types.ts";
3
4
 
4
5
  /** Raw Search API only. No Agent API, inference model, fetch, or effort setting. */
@@ -15,6 +16,6 @@ export const perplexityAdapter: ProviderAdapter = {
15
16
  body: JSON.stringify({ query, search_type: "web", max_results: 10 }),
16
17
  }, signal);
17
18
  if (!Array.isArray(data.results)) throw new Error("Perplexity Search returned no results array");
18
- return data;
19
+ return omitResponseMetadata(data, ["id", "server_time"]);
19
20
  },
20
21
  };
@@ -0,0 +1,10 @@
1
+ /** Remove known API bookkeeping only at the response root. Result objects and
2
+ * page content may use the same field names and must remain untouched. */
3
+ export function omitResponseMetadata(
4
+ data: Record<string, unknown>,
5
+ fields: readonly string[],
6
+ ): Record<string, unknown> {
7
+ const result = { ...data };
8
+ for (const field of fields) delete result[field];
9
+ return result;
10
+ }
@@ -23,7 +23,7 @@ export class QueryLengthError extends Error {
23
23
  }
24
24
 
25
25
  export interface ProviderSearchResult {
26
- /** Preserve standalone API metadata and unknown provider fields as-is. */
26
+ /** Preserve result content and unknown fields, omitting known API bookkeeping. */
27
27
  [key: string]: unknown;
28
28
  answer?: string;
29
29
  results?: unknown;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-web-search",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "Give pi agents the web: native Keenable, Exa, Perplexity and DeepSeek search APIs, URL fetch, raw results, and automatic provider fallback.",
5
5
  "type": "module",
6
6
  "license": "MIT",