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 +10 -0
- package/README.md +9 -3
- package/docs/README.zh-CN.md +8 -3
- package/docs/providers.md +6 -3
- package/docs/publishing.md +6 -6
- package/docs/search-apis.md +28 -9
- package/docs/testing.md +4 -3
- package/lib/providers/exa.ts +2 -1
- package/lib/providers/keenable.ts +3 -2
- package/lib/providers/perplexity.ts +2 -1
- package/lib/providers/response-metadata.ts +10 -0
- package/lib/providers/types.ts +1 -1
- package/package.json +1 -1
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.
|
|
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
|
|
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.
|
|
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
|
package/docs/README.zh-CN.md
CHANGED
|
@@ -53,7 +53,7 @@ Artificial Analysis Search Index 把差距画得很直观:虚线是**无搜索
|
|
|
53
53
|
|
|
54
54
|
## 安装,登录,开搜
|
|
55
55
|
|
|
56
|
-
**1.0.
|
|
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
|
|
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.
|
|
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
|
|
53
|
-
and each fetched raw document are preserved
|
|
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
|
|
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.
|
package/docs/publishing.md
CHANGED
|
@@ -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.
|
|
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.
|
|
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.
|
|
56
|
-
git push origin v1.0.
|
|
57
|
-
gh release create v1.0.
|
|
58
|
-
--title "v1.0.
|
|
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
|
|
package/docs/search-apis.md
CHANGED
|
@@ -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.
|
|
52
|
-
|
|
53
|
-
`
|
|
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
|
|
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`).
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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.
|
|
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,
|
|
37
|
-
|
|
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
|
package/lib/providers/exa.ts
CHANGED
|
@@ -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
|
+
}
|
package/lib/providers/types.ts
CHANGED
|
@@ -23,7 +23,7 @@ export class QueryLengthError extends Error {
|
|
|
23
23
|
}
|
|
24
24
|
|
|
25
25
|
export interface ProviderSearchResult {
|
|
26
|
-
/** Preserve
|
|
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.
|
|
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",
|