@juicesharp/rpiv-web-tools 1.1.4 → 1.2.0

package/README.md

@@ -17,10 +17,10 @@ Let the model search the web and read pages. `rpiv-web-tools` adds `web_search`
 
 ## Features
 
-- **Brave-backed search** — 1–10 ranked results per query with title and snippet.
-- **Read any URL** — fetch http/https pages, strip HTML to text, or get the raw HTML with `raw: true`.
-- **Large-page spillover** — oversized responses truncate inline and spill the full body to a temp file the model can read on demand.
-- **Interactive setup** — `/web-search-config` writes the key to `~/.config/rpiv-web-tools/config.json` (chmod 0600); env var `BRAVE_SEARCH_API_KEY` also works.
+- **Brave-backed search** - 1–10 ranked results per query with title and snippet.
+- **Read any URL** - fetch http/https pages, strip HTML to text, or get the raw HTML with `raw: true`.
+- **Large-page spillover** - oversized responses truncate inline and spill the full body to a temp file the model can read on demand.
+- **Interactive setup** - `/web-search-config` writes the key to `~/.config/rpiv-web-tools/config.json` (chmod 0600); env var `BRAVE_SEARCH_API_KEY` also works.
 
 ## Install
 
@@ -32,15 +32,67 @@ Then restart your Pi session.
 
 ## Tools
 
-- **`web_search`** — query the Brave Search API and return titled snippets.
+- **`web_search`** - query the Brave Search API and return titled snippets.
   1–10 results per call.
-- **`web_fetch`** — fetch an http/https URL, strip HTML to text (or return raw
+- **`web_fetch`** - fetch an http/https URL, strip HTML to text (or return raw
   HTML with `raw: true`), truncate large responses with a temp-file spill for
   the full content.
 
+### Schema - `web_search`
+
+```ts
+web_search({
+  query: string,                    // natural-language query
+  max_results?: number,             // 1-10, default 5
+})
+```
+
+Returns:
+
+```ts
+{
+  content: [{ type: "text", text: string }], // markdown list of "**title**\n url\n snippet"
+  details: {
+    query: string,
+    backend: "brave",
+    resultCount: number,
+    results?: Array<{ title: string, url: string, snippet: string }>,
+  }
+}
+```
+
+Throws when `BRAVE_SEARCH_API_KEY` is unset or the Brave API returns a non-2xx response.
+
+### Schema - `web_fetch`
+
+```ts
+web_fetch({
+  url: string,                      // http or https only
+  raw?: boolean,                    // true → return raw HTML; default false → strip to text
+})
+```
+
+Returns:
+
+```ts
+{
+  content: [{ type: "text", text: string }], // header (URL/title/content-type) + body
+  details: {
+    url: string,
+    title?: string,                 // <title> element, if present (HTML, non-raw)
+    contentType?: string,
+    contentLength?: number,         // from Content-Length header
+    truncation?: TruncationResult,  // present when body exceeded inline limits
+    fullOutputPath?: string,        // temp-file path containing the un-truncated body
+  }
+}
+```
+
+Throws on invalid URL, non-http(s) protocol, non-2xx response, or `image/` / `video/` / `audio/` content types.
+
 ## Commands
 
-- **`/web-search-config`** — set the Brave API key interactively. Writes to
+- **`/web-search-config`** - set the Brave API key interactively. Writes to
   `~/.config/rpiv-web-tools/config.json` (chmod 0600). Pass `--show` to see
   the current (masked) key and env var status.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juicesharp/rpiv-web-tools",
-  "version": "1.1.4",
-  "description": "Pi extension: lets the model search and read the web via the Brave Search API",
+  "version": "1.2.0",
+  "description": "Pi extension. Web search and fetch for the model, backed by the Brave Search API.",
   "keywords": [
     "pi-package",
     "pi-extension",