pi-better-web-search 0.1.0 → 0.1.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 CHANGED
@@ -1,5 +1,10 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.1
4
+
5
+ - Align directory structure with Pi extension conventions (`extensions/index.ts` and `lib/`), eliminating the `:src` suffix in Pi's startup banner.
6
+ - Highlight and expand documentation for all 10 supported provider classes: DeepSeek, Google Gemini, Google Antigravity, Ollama Cloud, OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode, and xAI Grok (plus Anthropic Messages).
7
+
3
8
  ## 0.1.0
4
9
 
5
10
  Initial release of `pi-better-web-search`.
package/CONTRIBUTING.md CHANGED
@@ -37,8 +37,8 @@ step and no runtime dependency to bundle.
37
37
 
38
38
  ## Provider work
39
39
 
40
- A provider adapter lives in `src/providers/<family>.ts` and follows the
41
- `ProviderAdapter` contract in `src/providers/types.ts`. Return provider data
40
+ A provider adapter lives in `lib/providers/<family>.ts` and follows the
41
+ `ProviderAdapter` contract in `lib/providers/types.ts`. Return provider data
42
42
  unchanged. `search()` should throw when the provider did not perform a search;
43
43
  `fetch()` should return one entry per URL and put per-URL failures in
44
44
  `entry.error`.
package/README.md CHANGED
@@ -8,12 +8,12 @@ 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.0-blue)](https://www.npmjs.com/package/pi-better-web-search)
11
+ [![npm](https://img.shields.io/badge/npm-v0.1.1-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)
15
15
 
16
- [简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](src/index.ts)
16
+ [简体中文](docs/README.zh-CN.md) · [Architecture](docs/architecture.md) · [Providers](docs/providers.md) · [Testing](docs/testing.md) · [Source](extensions/index.ts)
17
17
 
18
18
  ![pi-better-web-search architecture](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
19
19
 
@@ -99,14 +99,21 @@ invalid URLs alongside valid work are reported in the `fetched` entries.
99
99
 
100
100
  ## Provider support
101
101
 
102
- | Provider / family | Web search | URL analysis | Native interface |
103
- | --- | --- | --- | --- |
104
- | DeepSeek | Yes | Yes | Native Search and Fetch: `/v1/tools/search`, `/v1/tools/fetch` |
105
- | Ollama Cloud | Yes | Yes | `/api/web_search`, `/api/web_fetch` |
106
- | Google Gemini / Antigravity | Yes | Yes | `google_search` grounding and `url_context` |
107
- | OpenAI / Azure / Codex / Copilot / OpenCode | Yes | No | Responses API `web_search` tool |
108
- | xAI Grok | Yes | No | Responses API `web_search` tool |
109
- | Anthropic Messages | Yes | No | `web_search` server tool |
102
+ `pi-better-web-search` natively supports **10 distinct provider classes** (plus Anthropic Messages), automatically detecting authenticated credentials and routing each call through native provider protocols:
103
+
104
+ | # | Provider Class | Web Search | URL Analysis | Native Protocol & Endpoint |
105
+ |:---:|---|:---:|:---:|---|
106
+ | 1 | **DeepSeek** | Yes | Yes | Native REST `/v1/tools/search` & `/v1/tools/fetch` |
107
+ | 2 | **Google Gemini** | Yes | Yes | `google-generative-ai` SSE `google_search` grounding & `url_context` |
108
+ | 3 | **Google Antigravity** | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper body |
109
+ | 4 | **Ollama Cloud** | Yes | Yes | Hosted REST `/api/web_search` & `/api/web_fetch` (`ollama.com`) |
110
+ | 5 | **OpenAI** | Yes | No | Official Responses API `web_search` tool (`openai-responses`) |
111
+ | 6 | **Azure OpenAI** | Yes | No | Azure Responses API (`azure-openai-responses`) |
112
+ | 7 | **OpenAI Codex** | Yes | No | Specialized `/codex/responses` with Codex account tokens & headers |
113
+ | 8 | **GitHub Copilot** | Yes | No | Responses routing with Copilot auth tokens & proxy endpoints |
114
+ | 9 | **OpenCode** | Yes | No | Responses routing with Pi session tracking headers |
115
+ | 10 | **xAI (Grok)** | Yes | No | Grok dialect Responses API (`web_search_call.action.sources`) |
116
+ | * | **Anthropic Messages** | Yes | No | Messages API `web_search_20260209` tool & Claude Code OAuth |
110
117
 
111
118
  URL analysis is only exposed when at least one usable interface supports it.
112
119
  For example, a current OpenAI model with only OpenAI credentials gets a
@@ -115,13 +122,12 @@ credentials also gets `urls`.
115
122
 
116
123
  Provider detection follows the authenticated model's provider/API:
117
124
 
118
- 1. `deepseek` provider
119
- 2. Antigravity or Google Generative AI
125
+ 1. `deepseek` provider (DeepSeek native search/fetch)
126
+ 2. Antigravity or Google Generative AI (Google Gemini & Google Antigravity)
120
127
  3. Ollama Cloud (`ollama-cloud` provider or exact `ollama.com` host)
121
- 4. xAI with `openai-responses`
122
- 5. OpenAI-compatible Responses APIs (`openai-responses`,
123
- `azure-openai-responses`, `openai-codex-responses`)
124
- 6. Anthropic Messages
128
+ 4. xAI with `openai-responses` (xAI Grok)
129
+ 5. OpenAI-compatible Responses APIs (OpenAI, Azure OpenAI, OpenAI Codex, GitHub Copilot, OpenCode)
130
+ 6. Anthropic Messages (Claude)
125
131
 
126
132
  See [Providers](docs/providers.md) for request shapes, auth quirks, and URL
127
133
  support per family.
@@ -6,7 +6,7 @@
6
6
  `web_search`。它使用各家 provider 的原生搜索接口,在可用 provider 支持时
7
7
  分析 URL,自动在已登录的 provider 之间切换,并把 provider 数据原样返回。
8
8
 
9
- [English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../src/index.ts)
9
+ [English](../README.md) · [架构说明](architecture.md) · [Provider 细节](providers.md) · [测试](testing.md) · [源码](../extensions/index.ts)
10
10
 
11
11
  ![pi-better-web-search 架构](https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg)
12
12
 
@@ -81,28 +81,34 @@ provider 都失败时,工具返回错误(`isError: true`),不会静默
81
81
 
82
82
  ## Provider 支持
83
83
 
84
- | Provider / family | 网页搜索 | URL 分析 | 原生接口 |
85
- | --- | --- | --- | --- |
86
- | DeepSeek | 是 | 是 | 原生 Search/Fetch:`/v1/tools/search`、`/v1/tools/fetch` |
87
- | Ollama Cloud | 是 | 是 | `/api/web_search`、`/api/web_fetch` |
88
- | Google Gemini / Antigravity | 是 | 是 | `google_search` grounding 和 `url_context` |
89
- | OpenAI / Azure / Codex / Copilot / OpenCode | 是 | 否 | Responses API `web_search` |
90
- | xAI Grok | 是 | 否 | Responses API `web_search` |
91
- | Anthropic Messages | 是 | 否 | Messages `web_search` server tool |
84
+ `pi-better-web-search` 原生支持 **10 类主流 Provider**(及 Anthropic Messages),通过各家原生 API 协议接入,兼具最原汁原味的模型能力与极速体验:
85
+
86
+ | # | Provider 类别 | 网页搜索 | URL 分析 | 原生协议与端点接口 |
87
+ |:---:|---|:---:|:---:|---|
88
+ | 1 | **DeepSeek** | 是 | 是 | 原生 REST `/v1/tools/search` 与 `/v1/tools/fetch` |
89
+ | 2 | **Google Gemini** | 是 | 是 | `google-generative-ai` SSE `google_search` 与 `url_context` |
90
+ | 3 | **Google Antigravity** | 是 | 是 | Antigravity 企业级 Vertex 端点与专属包装体 |
91
+ | 4 | **Ollama Cloud** | 是 | 是 | 托管独立 REST `/api/web_search` 与 `/api/web_fetch`(`ollama.com`) |
92
+ | 5 | **OpenAI** | 是 | 否 | 官方 Responses API `web_search` 工具(`openai-responses`) |
93
+ | 6 | **Azure OpenAI** | 是 | 否 | Azure Responses API 专用端点(`azure-openai-responses`) |
94
+ | 7 | **OpenAI Codex** | 是 | 否 | 专有 `/codex/responses` 端点,支持 Codex 账号 Token 与 Originator 协议 |
95
+ | 8 | **GitHub Copilot** | 是 | 否 | Copilot 鉴权凭证路由与兼容代理端点 Responses 搜索 |
96
+ | 9 | **OpenCode** | 是 | 否 | 携带 Pi 会话追踪请求头的 Responses 搜索 |
97
+ | 10 | **xAI (Grok)** | 是 | 否 | 原生 Grok 方言 Responses API(`web_search_call.action.sources`) |
98
+ | * | **Anthropic Messages** | 是 | 否 | Messages API `web_search_20260209` 工具及 Claude Code OAuth 凭据 |
92
99
 
93
100
  只有至少一个可用接口支持 URL 分析时,`urls` 才会暴露。例如:当前模型是
94
101
  OpenAI 且只有 OpenAI 凭据时,schema 只有 `query`;同一会话只要还有
95
- DeepSeek、Ollama Cloud 或 Google 凭据,就会出现 `urls`。
102
+ DeepSeek、Google Gemini、Antigravity 或 Ollama Cloud 凭据,就会出现 `urls`。
96
103
 
97
104
  Provider 识别顺序:
98
105
 
99
- 1. `deepseek` provider
100
- 2. Antigravity 或 Google Generative AI
106
+ 1. `deepseek` provider(DeepSeek 原生 search/fetch)
107
+ 2. Antigravity 或 Google Generative AI(Google Gemini 与 Google Antigravity)
101
108
  3. Ollama Cloud(`ollama-cloud` provider,或 host 精确为 `ollama.com`)
102
- 4. xAI + `openai-responses`
103
- 5. OpenAI-compatible Responses API(`openai-responses`、
104
- `azure-openai-responses`、`openai-codex-responses`)
105
- 6. Anthropic Messages
109
+ 4. xAI + `openai-responses`(xAI Grok)
110
+ 5. OpenAI-compatible Responses API(OpenAI、Azure OpenAI、OpenAI Codex、GitHub Copilot、OpenCode)
111
+ 6. Anthropic Messages(Claude)
106
112
 
107
113
  各 provider 的请求形状、鉴权细节和 URL 支持见 [Provider 细节](providers.md)。
108
114
 
@@ -189,21 +189,21 @@ interface ProviderAdapter {
189
189
 
190
190
  `search()` throws when the provider did not perform a search. `fetch()` returns
191
191
  one entry per requested URL; per-URL failures go in `entry.error`. Both honor
192
- the abort signal and resolve credentials through `src/auth.ts`.
192
+ the abort signal and resolve credentials through `lib/auth.ts`.
193
193
 
194
194
  ## File map
195
195
 
196
196
  | Path | Responsibility |
197
197
  | --- | --- |
198
- | `src/index.ts` | Tool registration, exposure sync, lifecycle handlers |
199
- | `src/candidates.ts` | Current/available candidates, ordering, cache resolution |
200
- | `src/search.ts` | Input validation, search/fetch fallback, cache writes, output |
201
- | `src/auth.ts` | Credential resolution, header merging, env fallback |
202
- | `src/cache.ts` | Preference cache and model-set fingerprint |
203
- | `src/families.ts` | Provider family detection |
204
- | `src/schema.ts` | Query-only and query+urls schema variants |
205
- | `src/format.ts` | JSON wrapper, output guard, success/error results |
206
- | `src/providers/` | Provider adapters, SSE reader, HTTP helpers |
198
+ | `extensions/index.ts` | Tool registration, exposure sync, lifecycle handlers |
199
+ | `lib/candidates.ts` | Current/available candidates, ordering, cache resolution |
200
+ | `lib/search.ts` | Input validation, search/fetch fallback, cache writes, output |
201
+ | `lib/auth.ts` | Credential resolution, header merging, env fallback |
202
+ | `lib/cache.ts` | Preference cache and model-set fingerprint |
203
+ | `lib/families.ts` | Provider family detection |
204
+ | `lib/schema.ts` | Query-only and query+urls schema variants |
205
+ | `lib/format.ts` | JSON wrapper, output guard, success/error results |
206
+ | `lib/providers/` | Provider adapters, SSE reader, HTTP helpers |
207
207
 
208
208
  ## Non-goals
209
209
 
package/docs/providers.md CHANGED
@@ -1,17 +1,23 @@
1
1
  # Providers
2
2
 
3
- The extension selects a provider family from the authenticated model's
4
- provider id, API id, and base URL. Each adapter owns one family's request shape,
5
- authentication, stream parsing, and error behavior.
6
-
7
- | Family | Detection | Search | URL analysis | Interface |
8
- | --- | --- | --- | --- | --- |
9
- | DeepSeek | provider `deepseek` | Yes | Yes | Native `/v1/tools/search`, `/v1/tools/fetch` |
10
- | Ollama | provider `ollama-cloud` or host `ollama.com` | Yes | Yes | `/api/web_search`, `/api/web_fetch` |
11
- | Google | api `google-generative-ai`, provider/api `antigravity` | Yes | Yes | `google_search`, `url_context` |
12
- | OpenAI | api `openai-responses`, `azure-openai-responses`, `openai-codex-responses` | Yes | No | Responses `web_search` |
13
- | xAI | provider `xai` with `openai-responses` | Yes | No | Responses `web_search` |
14
- | Anthropic | api `anthropic-messages` | Yes | No | Messages `web_search` |
3
+ The extension selects an adapter from the authenticated model's provider id,
4
+ API id, and base URL. We natively support **10 distinct provider classes** (plus
5
+ Anthropic Messages), each mapped to its native request shape, authentication,
6
+ stream parsing, and error behavior:
7
+
8
+ | # | Provider Class | Detection | Search | URL Analysis | Interface & Endpoint |
9
+ |:---:|---|---|:---:|:---:|---|
10
+ | 1 | **DeepSeek** | provider `deepseek` | Yes | Yes | Native REST `/v1/tools/search`, `/v1/tools/fetch` |
11
+ | 2 | **Google Gemini** | api `google-generative-ai` | Yes | Yes | SSE `google_search`, `url_context` |
12
+ | 3 | **Google Antigravity** | provider/api `antigravity` | Yes | Yes | Antigravity enterprise Vertex endpoint & wrapper |
13
+ | 4 | **Ollama Cloud** | provider `ollama-cloud` or host `ollama.com` | Yes | Yes | Hosted REST `/api/web_search`, `/api/web_fetch` |
14
+ | 5 | **OpenAI** | api `openai-responses` | Yes | No | Responses API `web_search` |
15
+ | 6 | **Azure OpenAI** | api `azure-openai-responses` | Yes | No | Azure Responses API `/responses` |
16
+ | 7 | **OpenAI Codex** | api `openai-codex-responses` | Yes | No | Codex `/codex/responses` & account tokens |
17
+ | 8 | **GitHub Copilot** | Copilot provider/token with Responses | Yes | No | Copilot Responses with token routing & proxy endpoints |
18
+ | 9 | **OpenCode** | OpenCode provider with Responses | Yes | No | Responses API with Pi session tracking headers |
19
+ | 10 | **xAI (Grok)** | provider `xai` or model `grok*` with Responses | Yes | No | Grok dialect Responses (`action.sources`) |
20
+ | * | **Anthropic Messages** | api `anthropic-messages` | Yes | No | Messages API `web_search_20260209` tool & OAuth |
15
21
 
16
22
  A model whose API is `openai-completions` is not search-capable unless it is
17
23
  served by DeepSeek or Ollama Cloud. A local Ollama daemon is not supported;
@@ -207,10 +213,10 @@ a per-URL error.
207
213
 
208
214
  ## Adding a provider
209
215
 
210
- 1. Add a family to `src/providers/types.ts` if it is genuinely new.
211
- 2. Create `src/providers/<family>.ts` exporting a `ProviderAdapter`.
212
- 3. Register it in `src/providers/index.ts`.
213
- 4. Add family detection in `src/families.ts`.
216
+ 1. Add a family to `lib/providers/types.ts` if it is genuinely new.
217
+ 2. Create `lib/providers/<family>.ts` exporting a `ProviderAdapter`.
218
+ 3. Register it in `lib/providers/index.ts`.
219
+ 4. Add family detection in `lib/families.ts`.
214
220
  5. Add tests for request shape, auth/header preservation, raw result
215
221
  preservation, search evidence, errors, aborts, and URL behavior.
216
222
  6. Update this document, `README.md`, and `CHANGELOG.md`.
package/docs/testing.md CHANGED
@@ -80,7 +80,7 @@ search and a real DeepSeek credential:
80
80
  PI_BETTER_WEB_SEARCH_CACHE=/tmp/pi-bws-e2e/cache.json \
81
81
  pi --no-session --print --mode json \
82
82
  --provider mock-chat --model mock-chat/mock-chat-model \
83
- -e ./src/index.ts "please search the web"
83
+ -e ./extensions/index.ts "please search the web"
84
84
  ```
85
85
 
86
86
  5. Inspect the second model request. The tool result must be valid raw JSON with
@@ -4,11 +4,11 @@ import {
4
4
  hasExposedCandidate,
5
5
  hasUrlCandidate,
6
6
  resolveResolutionContext,
7
- } from "./candidates.ts";
8
- import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "./schema.ts";
9
- import { runWebSearch } from "./search.ts";
7
+ } from "../lib/candidates.ts";
8
+ import { buildWebSearchSchema, buildWebSearchToolDescription, WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
9
+ import { runWebSearch } from "../lib/search.ts";
10
10
 
11
- export { WEB_SEARCH_TOOL_NAME } from "./schema.ts";
11
+ export { WEB_SEARCH_TOOL_NAME } from "../lib/schema.ts";
12
12
 
13
13
  export function createWebSearchToolManager(
14
14
  pi: Pick<ExtensionAPI, "registerTool" | "getActiveTools" | "setActiveTools">,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-web-search",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
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",
@@ -30,7 +30,8 @@
30
30
  "url-context"
31
31
  ],
32
32
  "files": [
33
- "src/",
33
+ "extensions/",
34
+ "lib/",
34
35
  "docs/",
35
36
  "assets/",
36
37
  "README.md",
@@ -41,7 +42,7 @@
41
42
  ],
42
43
  "pi": {
43
44
  "extensions": [
44
- "./src/index.ts"
45
+ "./extensions/index.ts"
45
46
  ],
46
47
  "image": "https://raw.githubusercontent.com/zhexusun10/pi-better-web-search/main/assets/architecture.svg"
47
48
  },
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes