@vipinsights/gemini-web-search-grounding 0.0.0-stage → 1.0.0
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/README.md +60 -2
- package/package.json +41 -4
- package/src/index.ts +12 -0
- package/src/web_search.ts +89 -0
package/README.md
CHANGED
|
@@ -1,3 +1,61 @@
|
|
|
1
|
-
#
|
|
1
|
+
# gemini-web-search-grounding
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Minimal `web_search` tool for [pi](https://pi.dev) using Gemini's Grounding with Google Search. Derived from [ttttmr/pi-web-search](https://github.com/ttttmr/pi-web-search) (MIT).
|
|
4
|
+
|
|
5
|
+
## Scope
|
|
6
|
+
|
|
7
|
+
- One tool: `web_search(query)`. Returns a grounded answer plus source links.
|
|
8
|
+
- Gemini only: runs on pi's current model, and only when it uses the `google-generative-ai` API. Any other model returns an error.
|
|
9
|
+
- Auth: the env var pi uses for Gemini (`GEMINI_API_KEY`). No `/login` credentials, no config files.
|
|
10
|
+
- No `url_context`, no URL parameters, no URL fetching, no other vendors.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
Requires Pi 1.5.0 or newer. Do not load it alongside `pi-web-search`; both register `web_search`.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
pi install npm:gemini-web-search-grounding
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Replace the previous web search tool
|
|
21
|
+
|
|
22
|
+
1. List installed packages and find the old one (e.g. `pi-web-search`):
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
pi list
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
2. Remove it:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
pi remove npm:pi-web-search
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
3. Install this one:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pi install npm:gemini-web-search-grounding
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
4. Set `GEMINI_API_KEY`, restart Pi, and select a Gemini model.
|
|
41
|
+
5. If `web_search` is still registered twice, check `packages` and `extensions` in `~/.pi/agent/settings.json` (and the project's `.pi/settings.json`) for leftover `pi-web-search` entries and delete them.
|
|
42
|
+
|
|
43
|
+
## Publish to npm
|
|
44
|
+
|
|
45
|
+
1. Log in (once): `npm login`
|
|
46
|
+
2. Confirm `name` and `version` in `package.json`; the name must be unused on npm.
|
|
47
|
+
3. Run checks: `npm test && npm run typecheck`
|
|
48
|
+
4. Preview the tarball: `npm pack --dry-run` (only `src` and `README.md` should ship)
|
|
49
|
+
5. Publish: `npm publish` (add `--access public` for a scoped name like `@vtinfo/...`)
|
|
50
|
+
6. Verify: `pi install npm:gemini-web-search-grounding`
|
|
51
|
+
7. For later releases: `npm version patch|minor|major`, then `npm publish`
|
|
52
|
+
|
|
53
|
+
The `pi-package` keyword in `package.json` makes it discoverable as a Pi package.
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
## Test
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
npm test
|
|
60
|
+
npm run typecheck
|
|
61
|
+
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vipinsights/gemini-web-search-grounding",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Minimal web_search for pi using Gemini's Grounding with Google Search. Gemini models only; no URL fetching.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "src/index.ts",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"pi",
|
|
9
|
+
"pi-extension",
|
|
10
|
+
"pi-package",
|
|
11
|
+
"web-search",
|
|
12
|
+
"gemini",
|
|
13
|
+
"google",
|
|
14
|
+
"grounding"
|
|
15
|
+
],
|
|
16
|
+
"author": "vipinsights",
|
|
17
|
+
"license": "MIT",
|
|
18
|
+
"files": [
|
|
19
|
+
"src",
|
|
20
|
+
"README.md"
|
|
21
|
+
],
|
|
22
|
+
"scripts": {
|
|
23
|
+
"test": "node --test tests/*.test.mjs",
|
|
24
|
+
"typecheck": "tsc --noEmit"
|
|
25
|
+
},
|
|
26
|
+
"devDependencies": {
|
|
27
|
+
"@earendil-works/pi-ai": "^1.5.0",
|
|
28
|
+
"@earendil-works/pi-coding-agent": "^1.5.0",
|
|
29
|
+
"@types/node": "^25.9.1",
|
|
30
|
+
"typebox": "^1.1.38",
|
|
31
|
+
"typescript": "^6.0.3"
|
|
32
|
+
},
|
|
33
|
+
"pi": {
|
|
34
|
+
"extensions": [
|
|
35
|
+
"./src/index.ts"
|
|
36
|
+
]
|
|
37
|
+
},
|
|
38
|
+
"peerDependencies": {
|
|
39
|
+
"@earendil-works/pi-ai": ">=1.5.0",
|
|
40
|
+
"@earendil-works/pi-coding-agent": ">=1.5.0",
|
|
41
|
+
"typebox": "*"
|
|
42
|
+
}
|
|
43
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { webSearch, WebSearchSchema } from "./web_search.ts";
|
|
3
|
+
|
|
4
|
+
export default function (pi: ExtensionAPI) {
|
|
5
|
+
pi.registerTool({
|
|
6
|
+
name: "web_search",
|
|
7
|
+
label: "Web Search",
|
|
8
|
+
description: "Search the web with Google Search grounding via the current Gemini model. Returns an answer with source links. Does not fetch or read specific URLs.",
|
|
9
|
+
parameters: WebSearchSchema,
|
|
10
|
+
execute: (_id, params, signal, _onUpdate, ctx) => webSearch(params, signal, ctx),
|
|
11
|
+
});
|
|
12
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { getEnvApiKey } from "@earendil-works/pi-ai/compat";
|
|
3
|
+
import { Type, type Static } from "typebox";
|
|
4
|
+
|
|
5
|
+
const TIMEOUT_MS = 60_000;
|
|
6
|
+
|
|
7
|
+
export const WebSearchSchema = Type.Object({
|
|
8
|
+
query: Type.String({ minLength: 1, description: "The search query or question to answer" }),
|
|
9
|
+
});
|
|
10
|
+
export type WebSearchInput = Static<typeof WebSearchSchema>;
|
|
11
|
+
|
|
12
|
+
type GeminiResponse = {
|
|
13
|
+
candidates?: Array<{
|
|
14
|
+
content?: { parts?: Array<{ text?: string; thought?: boolean }> };
|
|
15
|
+
finishReason?: string;
|
|
16
|
+
groundingMetadata?: {
|
|
17
|
+
webSearchQueries?: string[];
|
|
18
|
+
groundingChunks?: Array<{ web?: { uri?: string; title?: string } }>;
|
|
19
|
+
};
|
|
20
|
+
}>;
|
|
21
|
+
promptFeedback?: { blockReason?: string };
|
|
22
|
+
error?: { message?: string };
|
|
23
|
+
};
|
|
24
|
+
|
|
25
|
+
// Failures throw: pi reports a thrown error as a failed tool call (isError).
|
|
26
|
+
export async function webSearch(
|
|
27
|
+
params: WebSearchInput,
|
|
28
|
+
signal: AbortSignal | undefined,
|
|
29
|
+
ctx: ExtensionContext,
|
|
30
|
+
): Promise<AgentToolResult<any>> {
|
|
31
|
+
const model = ctx.model;
|
|
32
|
+
if (model?.api !== "google-generative-ai") {
|
|
33
|
+
const current = model ? `${model.id} (${model.provider}/${model.api})` : "none";
|
|
34
|
+
throw new Error(`web_search requires a Gemini model (google-generative-ai). Current model: ${current}.`);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// Same env var pi uses for its own Gemini calls (GEMINI_API_KEY).
|
|
38
|
+
const apiKey = getEnvApiKey(model.provider);
|
|
39
|
+
if (!apiKey) throw new Error(`web_search: set the environment variable pi uses for provider "${model.provider}" (GEMINI_API_KEY).`);
|
|
40
|
+
|
|
41
|
+
const timeout = AbortSignal.timeout(TIMEOUT_MS);
|
|
42
|
+
const res = await fetch(`${model.baseUrl}/models/${encodeURIComponent(model.id)}:generateContent`, {
|
|
43
|
+
method: "POST",
|
|
44
|
+
headers: { "Content-Type": "application/json", "x-goog-api-key": apiKey },
|
|
45
|
+
body: JSON.stringify({
|
|
46
|
+
contents: [{ role: "user", parts: [{ text: params.query }] }],
|
|
47
|
+
// The only tool enabled. No url_context.
|
|
48
|
+
tools: [{ google_search: {} }],
|
|
49
|
+
}),
|
|
50
|
+
signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
const data = (await res.json().catch(() => ({}))) as GeminiResponse;
|
|
54
|
+
if (!res.ok) {
|
|
55
|
+
throw new Error(`web_search: Gemini ${res.status} ${data.error?.message ?? res.statusText}`);
|
|
56
|
+
}
|
|
57
|
+
if (data.promptFeedback?.blockReason) {
|
|
58
|
+
throw new Error(`web_search: blocked by Gemini (${data.promptFeedback.blockReason})`);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const candidate = data.candidates?.[0];
|
|
62
|
+
const answer = (candidate?.content?.parts ?? [])
|
|
63
|
+
.filter((part) => !part.thought)
|
|
64
|
+
.map((part) => part.text ?? "")
|
|
65
|
+
.join("")
|
|
66
|
+
.trim();
|
|
67
|
+
if (!answer) {
|
|
68
|
+
throw new Error(`web_search: empty response (finishReason: ${candidate?.finishReason ?? "unknown"})`);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const metadata = candidate?.groundingMetadata;
|
|
72
|
+
const seen = new Set<string>();
|
|
73
|
+
const sources: Array<{ title: string; url: string }> = [];
|
|
74
|
+
for (const chunk of metadata?.groundingChunks ?? []) {
|
|
75
|
+
const url = chunk.web?.uri;
|
|
76
|
+
if (!url || seen.has(url)) continue;
|
|
77
|
+
seen.add(url);
|
|
78
|
+
sources.push({ title: chunk.web?.title || url, url });
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const sourceText = sources.length
|
|
82
|
+
? "\n\nSources:\n" + sources.map((s, i) => `${i + 1}. ${s.title}: ${s.url}`).join("\n")
|
|
83
|
+
: "\n\n(No grounding sources returned.)";
|
|
84
|
+
|
|
85
|
+
return {
|
|
86
|
+
content: [{ type: "text", text: answer + sourceText }],
|
|
87
|
+
details: { modelId: model.id, queries: metadata?.webSearchQueries ?? [], sources },
|
|
88
|
+
};
|
|
89
|
+
}
|