{"_id":"@cltec/pi-ollama-web-search","_rev":"4-5ec484449cf2e15e119139d14196c1d8","name":"@cltec/pi-ollama-web-search","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@cltec/pi-ollama-web-search","version":"0.1.0","keywords":["pi-package","pi-extension","ollama","web-search"],"license":"MIT","_id":"@cltec/pi-ollama-web-search@0.1.0","maintainers":[{"name":"cirius1792","email":"cirius1792@msn.com"}],"homepage":"https://github.com/Cirius1792/pi-ollama-web-search#readme","bugs":{"url":"https://github.com/Cirius1792/pi-ollama-web-search/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"da5f4419a8cafd9665a102d37262c8b94cf11cae","tarball":"https://registry.npmjs.org/@cltec/pi-ollama-web-search/-/pi-ollama-web-search-0.1.0.tgz","fileCount":8,"integrity":"sha512-fxESeTNf96r5cJ3j94KuL7nDfVsVpqIHuhv1KrJqD6GPiaJZMTGT8qWYl6uwey/9BQzaPzx+BtPGqNsNyqgy/A==","signatures":[{"sig":"MEYCIQCObYb9EAKLBRCDLnUmxQnhyN3SPjkTdF+e+hl38cuVQwIhANPBKILonwSne6dnt/L92hWGS25nkpSwxP3b1F+hQ9Yq","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":12999},"type":"module","gitHead":"402b64e435e789c2bb9406900c4040cf11267054","scripts":{"test":"vitest run --passWithNoTests","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"cirius1792","email":"cirius1792@msn.com"},"repository":{"url":"git+https://github.com/Cirius1792/pi-ollama-web-search.git","type":"git"},"_npmVersion":"11.7.0","description":"A pi extension package that exposes Ollama Web Search as a custom tool.","directories":{},"_nodeVersion":"22.17.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typebox":"^1.1.24","typescript":"^5.9.0","@types/node":"^22.0.0","@mariozechner/pi-coding-agent":"^0.72.1"},"peerDependencies":{"typebox":"*","@mariozechner/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-ollama-web-search_0.1.0_1777826713032_0.9945194327053155","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@cltec/pi-ollama-web-search","version":"0.1.2","keywords":["pi-package","pi-extension","ollama","web-search","web-fetch"],"license":"MIT","_id":"@cltec/pi-ollama-web-search@0.1.2","maintainers":[{"name":"cirius1792","email":"cirius1792@msn.com"}],"homepage":"https://github.com/Cirius1792/pi-ollama-web-search#readme","bugs":{"url":"https://github.com/Cirius1792/pi-ollama-web-search/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"612434715c6e1edef3c38f19218c03949e8cc796","tarball":"https://registry.npmjs.org/@cltec/pi-ollama-web-search/-/pi-ollama-web-search-0.1.2.tgz","fileCount":13,"integrity":"sha512-PbKn9739CwEXgKotdn2D6q6QBoNMAeZ5sMa1yVGydR0rUp+FFkSb/G7cexXcKI0pW06HvQWoctxs0Y58/aua2A==","signatures":[{"sig":"MEYCIQDA/vmNDMXD2gEBn0ziAOIUzQOY2tXlTPA6fWSSnni1xgIhAJmkeTOFDj8n5pzz6kEOJtKGb6GnQ/FBUlIRjgwNMrfq","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62728},"type":"module","gitHead":"55de5989b283fd5013dbaa46d5d78daadcc19b2b","scripts":{"test":"vitest run --passWithNoTests","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"cirius1792","email":"cirius1792@msn.com"},"repository":{"url":"git+https://github.com/Cirius1792/pi-ollama-web-search.git","type":"git"},"_npmVersion":"11.7.0","description":"A pi extension package that exposes Ollama Web Search and Web Fetch as custom tools.","directories":{},"_nodeVersion":"22.17.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typebox":"^1.1.24","typescript":"^5.9.0","@types/node":"^22.0.0","@earendil-works/pi-coding-agent":"^0.74.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"^0.74.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-ollama-web-search_0.1.2_1778522646073_0.07597169184250308","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@cltec/pi-ollama-web-search","version":"0.2.0","keywords":["pi-package","pi-extension","ollama","web-search","web-fetch"],"license":"MIT","_id":"@cltec/pi-ollama-web-search@0.2.0","maintainers":[{"name":"cirius1792","email":"cirius1792@msn.com"}],"homepage":"https://github.com/Cirius1792/pi-ollama-web-search#readme","bugs":{"url":"https://github.com/Cirius1792/pi-ollama-web-search/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"1a02f6a0756dd862f81087fbb0d0a944a7b479bc","tarball":"https://registry.npmjs.org/@cltec/pi-ollama-web-search/-/pi-ollama-web-search-0.2.0.tgz","fileCount":13,"integrity":"sha512-nkO5yDXqj7ZJGiNy5EsyXicirpYb059wBW2LX5auzY7XneOmF0OaEZfbCMgFoZ0grN2LlaimpZgvXYrr80A+6w==","signatures":[{"sig":"MEYCIQDi3CVPej6rS5B3cC6Lu6R4CAnUcUri+2NVxhpAEJr5SAIhAK6xoIZoRZOWLk2GqNBPR3ADv0SlZaKIIYXWmd1BY7kg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82884},"type":"module","gitHead":"1fcde290f1e92aa7aa3cbcf0a87e68d7da16b1a3","scripts":{"test":"vitest run --passWithNoTests","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"cirius1792","email":"cirius1792@msn.com"},"repository":{"url":"git+https://github.com/Cirius1792/pi-ollama-web-search.git","type":"git"},"_npmVersion":"11.7.0","description":"A pi extension package that exposes Ollama Web Search and Web Fetch as custom tools.","directories":{},"_nodeVersion":"22.17.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.0.0","typebox":"^1.1.24","typescript":"^5.9.0","@types/node":"^22.0.0","@earendil-works/pi-coding-agent":"^0.74.0"},"peerDependencies":{"typebox":"*","@earendil-works/pi-coding-agent":"^0.74.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-ollama-web-search_0.2.0_1778522664886_0.050582954237383015","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@cltec/pi-ollama-web-search","version":"1.0.0","description":"A local-first, context-safe pi extension package for Ollama web search and fetch.","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/Cirius1792/pi-ollama-web-search.git"},"bugs":{"url":"https://github.com/Cirius1792/pi-ollama-web-search/issues"},"homepage":"https://github.com/Cirius1792/pi-ollama-web-search#readme","keywords":["pi-package","pi-extension","ollama","web-search","web-fetch","local-first","context-safe","local-models"],"publishConfig":{"access":"public"},"scripts":{"test":"vitest run --passWithNoTests","test:watch":"vitest","typecheck":"tsc --noEmit"},"pi":{"extensions":["./src/index.ts"]},"peerDependencies":{"@earendil-works/pi-coding-agent":"^0.74.0","typebox":"*"},"devDependencies":{"@earendil-works/pi-coding-agent":"^0.74.0","@types/node":"^22.0.0","typebox":"^1.1.24","typescript":"^5.9.0","vitest":"^4.0.0"},"gitHead":"9c150e4c047b197bed8bac3c9626248e46b6cde8","_id":"@cltec/pi-ollama-web-search@1.0.0","_nodeVersion":"22.17.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-r18AJ7MEpPQ6VPWJQ9hfICkEM9wzEfwiPlGOgRt8mOCeTa7JPrN91q1XlWyWeyuG6FnvTQasjW30n+5dg5z7pg==","shasum":"cf2f0dabac8b8c3b8c211be3e9d18a551f4cbf99","tarball":"https://registry.npmjs.org/@cltec/pi-ollama-web-search/-/pi-ollama-web-search-1.0.0.tgz","fileCount":13,"unpackedSize":103624,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIADC7KeJ4+oTPwOYOaL8mVtmpo2XxrP2G+li1n8tyJrAAiAZg5wF6NygceLvVjL3CE0nD4nMbV5nnAhGB0nfg870LA=="}]},"_npmUser":{"name":"cirius1792","email":"cirius1792@msn.com"},"directories":{},"maintainers":[{"name":"cirius1792","email":"cirius1792@msn.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-ollama-web-search_1.0.0_1778586396092_0.9019349513488524"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T16:45:12.915Z","modified":"2026-05-12T11:46:36.374Z","0.1.0":"2026-05-03T16:45:13.161Z","0.1.2":"2026-05-11T18:04:06.340Z","0.2.0":"2026-05-11T18:04:25.022Z","1.0.0":"2026-05-12T11:46:36.236Z"},"bugs":{"url":"https://github.com/Cirius1792/pi-ollama-web-search/issues"},"license":"MIT","homepage":"https://github.com/Cirius1792/pi-ollama-web-search#readme","keywords":["pi-package","pi-extension","ollama","web-search","web-fetch","local-first","context-safe","local-models"],"repository":{"type":"git","url":"git+https://github.com/Cirius1792/pi-ollama-web-search.git"},"description":"A local-first, context-safe pi extension package for Ollama web search and fetch.","maintainers":[{"name":"cirius1792","email":"cirius1792@msn.com"}],"readme":"# @cltec/pi-ollama-web-search\n\nA local-first, context-safe [pi](https://pi.dev) package that exposes Ollama web APIs as custom pi tools.\n\nThis package is designed for workflows where model context is scarce, especially when you are running local models. It keeps discovery output compact by default, supports selective follow-up retrieval, and lets fetched content be exported to files when you do not want large payloads in the main model context.\n\n## What it provides\n\nThis package registers three production tools:\n\n- `ollama_web_search`\n- `ollama_web_fetch`\n- `ollama_web_read_full`\n\nTool behavior:\n\n- `ollama_web_search` accepts a search query and returns compact search results with title, URL, and content snippets.\n  - When results are present, tool `details` includes:\n    - `fullContentRef`: opaque ref used for follow-up retrieval.\n    - `retrieval`: per-result metadata (`resultIndex` + available sections with character counts).\n    - `appliedProfile`: the active local-first profile values chosen for the current model.\n- `ollama_web_fetch` accepts a URL and returns fetched page title, content, and discovered links.\n  - Successful fetch responses include:\n    - `fullContentRef`: opaque ref used for follow-up retrieval.\n    - target metadata for `title`, `content`, and `links`, including visibility/truncation information.\n    - `appliedProfile`: the active fetch budget metadata, including the selected value source and winning matcher when one applies.\n- `ollama_web_read_full` accepts a `ref` returned by `ollama_web_search` or `ollama_web_fetch`.\n  - Search refs (`ws_s_*`) read exactly one section (`title`, `url`, or `content`) for a 1-based `resultIndex`.\n  - Fetch refs (`fetch:*`) read one section (`title`, `content`, or `links`) inline, or export the full section in `mode: \"file\"`.\n    - If `path` is omitted, the tool writes to a generated temp file outside the repo and deletes it at session shutdown.\n    - If `path` is provided, the tool resolves it like pi file tools (relative to the current working directory, absolute paths allowed, leading `@` tolerated), creates parent directories automatically, and refuses to overwrite unless `overwrite: true` is passed.\n    - `outputPath` is still accepted as a backward-compatible alias, but `path` is canonical.\n  - Read-full responses include structured retrieval details.\n    - `servedFrom: \"cache\"` means the ref was still available in memory.\n    - `servedFrom: \"replay\"` means the extension replayed the original search or fetch request after cache loss, so the retrieved web content may have changed.\n  - Replay behavior is best-effort: the ref stays stable, but replay can still fail if upstream content changed, the original target can no longer be reconstructed, or the upstream request itself fails.\n\n## Why local-first\n\nWeb results can consume context quickly, especially on smaller local models. This package is opinionated about that trade-off:\n\n- keep search output compact by default;\n- favor a few useful results over broad, noisy output;\n- fetch only when you already know the page you want;\n- read one field at a time when you need more detail;\n- export large fetched sections to a file instead of forcing them into model context.\n\nThe extension does not implement downstream orchestration such as summarization agents or file-analysis pipelines, but it is intentionally shaped to support those workflows cleanly.\n\n## Install\n\nInstall from npm:\n\n```bash\npi install npm:@cltec/pi-ollama-web-search\n```\n\nOr install directly from GitHub:\n\n```bash\npi install git:github.com/Cirius1792/pi-ollama-web-search\n```\n\nThen start or reload pi.\n\n## Authentication\n\nCreate an Ollama API key at:\n\nhttps://ollama.com/settings/keys\n\nExport it before starting pi:\n\n```bash\nexport OLLAMA_API_KEY=\"your_api_key_here\"\npi\n```\n\nFor persistent setup, add the export to your shell profile such as `~/.profile`, `~/.bashrc`, or `~/.zshrc`.\n\n## Configuration\n\nThe extension uses a dedicated config file named `pi-ollama-web-search.json`.\n\n### Global config\n\nOn startup, the extension creates a global config file automatically if it does not already exist.\n\nThat file lives in pi's active config directory and starts with conservative local-first defaults plus a top-level config version derived from the installed package version:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"default\": {\n    \"maxResults\": 3,\n    \"maxOutputChars\": 12000\n  }\n}\n```\n\n### Project override config\n\nA repository can override the global defaults with:\n\n```text\n.pi/pi-ollama-web-search.json\n```\n\nProject config is merged on top of global config, so repository-local policy wins when both are present.\n\n### Model-aware profiles\n\nYou can define exact model matches and simple `*` glob patterns using the canonical model key format `provider/id`.\n\nExample:\n\n```json\n{\n  \"version\": \"1.0\",\n  \"default\": {\n    \"maxResults\": 3,\n    \"maxOutputChars\": 12000\n  },\n  \"models\": {\n    \"ollama/qwen3:14b\": {\n      \"maxResults\": 2,\n      \"maxOutputChars\": 9000\n    },\n    \"ollama/qwen3*\": {\n      \"maxResults\": 4,\n      \"maxOutputChars\": 20000\n    }\n  }\n}\n```\n\nMatching rules:\n\n- exact match wins over pattern match;\n- among matching patterns, the most specific pattern wins;\n- if nothing matches, the `default` profile is used.\n\n### Complete overrides, not patches\n\nEach model override must be a complete profile. In other words, model entries are not partial patches: include both `maxResults` and `maxOutputChars` for each override.\n\n### Version field\n\nAuto-generated global configs include a top-level `version` string in `major.minor` form based on the installed package version.\n\nYou can also include `version` in manually managed config files. Legacy configs without a `version` field remain valid and load without warnings. If the config major version does not match the installed package major version, the extension warns and still uses the config when it is otherwise structurally valid.\n\n### Invalid config behavior\n\nInvalid config is non-blocking:\n\n- invalid global config falls back to local-first defaults;\n- invalid project config falls back to global/default values;\n- missing model matches quietly use the default profile;\n- if pi cannot determine the current model, the extension warns and uses the default profile.\n\n## Local-first workflow\n\nThe intended workflow is:\n\n1. Run `ollama_web_search` first for compact discovery.\n2. Use `ollama_web_fetch` only when you have a specific URL or need a fuller page after search.\n3. Use `ollama_web_read_full` only with the returned ref, one field at a time.\n4. Use `mode: \"file\"` for large fetch sections you want to inspect outside the main model context.\n\n### Search retrieval flow\n\n1. Run `ollama_web_search` with a query.\n2. Read `details.fullContentRef` and `details.retrieval` from the search response.\n3. Call `ollama_web_read_full` with:\n   - `ref`: the `fullContentRef` value,\n   - `resultIndex`: 1-based result number,\n   - `section`: one of `title`, `url`, or `content`.\n4. If the in-memory search payload has been evicted, `ollama_web_read_full` may replay the original search request and remap the requested `resultIndex` by the original URL occurrence rather than blindly trusting the replayed numeric position.\n\n### Fetch retrieval flow\n\n1. Run `ollama_web_fetch` with a URL.\n2. Read `details.fullContentRef` from the fetch response.\n3. Call `ollama_web_read_full` with:\n   - `ref`: the `fullContentRef` value,\n   - `section`: one of `title`, `content`, or `links`.\n4. Use `mode: \"file\"` when you want the full fetch section written to disk instead of returned inline.\n5. Optional file-mode controls:\n   - Omit `path` to create a temporary export file that is cleaned up at session shutdown.\n   - Set `path` to keep a persistent export that remains on disk until you delete it.\n   - Set `overwrite: true` only when you intentionally want to replace an existing explicit export file.\n6. If the in-memory fetch payload has been evicted, `ollama_web_read_full` may replay the original fetch request. Replay keeps the same ref but can return changed web content, and `details.servedFrom` will be `\"replay\"`.\n\n## Example prompts\n\n```text\nSearch for recent Ollama engine updates. Keep the results compact. If the output is truncated, use the returned full-content ref to read the full content for result 1.\n```\n\n```text\nSearch for the latest pi extension docs about themes, then fetch the most relevant result if the snippets are not enough.\n```\n\n```text\nFetch https://ollama.com and list the most important links from the page. If the page output is truncated, use the returned ref with ollama_web_read_full section=links.\n```\n\n```text\nFetch https://ollama.com/blog and if the content is too large, use ollama_web_read_full with the returned ref in mode=file so the full content is written to a temp file.\n```\n\n```text\nFetch https://ollama.com/blog and export the full page content to @artifacts/ollama-blog.txt with ollama_web_read_full mode=file. If the file already exists, only overwrite it when I ask.\n```\n\n## Dev mode\n\nDebug slash commands are available only when dev mode is enabled.\n\nEnable it before starting pi:\n\n```bash\nexport PI_OLLAMA_SEARCH_DEV=1\npi\n```\n\nThen run:\n\n```text\n/ollama-search what is ollama?\n/ollama-fetch https://ollama.com\n/ollama-read-full {\"ref\":\"fetch:...\",\"section\":\"content\"}\n```\n\n`/ollama-read-full` accepts a JSON object matching the production tool parameters. This gives developers a direct way to verify inline reads, file exports, replay behavior, and temp-file cleanup through the same retrieval path used by `ollama_web_read_full`.\n\nExamples:\n\n```text\n/ollama-read-full {\"ref\":\"ws_s_...\",\"resultIndex\":1,\"section\":\"content\"}\n/ollama-read-full {\"ref\":\"fetch:...\",\"section\":\"links\"}\n/ollama-read-full {\"ref\":\"fetch:...\",\"section\":\"content\",\"mode\":\"file\"}\n/ollama-read-full {\"ref\":\"fetch:...\",\"section\":\"content\",\"mode\":\"file\",\"path\":\"@artifacts/page.txt\"}\n```\n\nDebug commands are intended for local testing and troubleshooting. They are not part of the normal user workflow.\n\nCleanup expectations:\n\n- Temp exports created by `ollama_web_read_full` without `path` are deleted automatically at session shutdown.\n- Persistent exports created with explicit `path` are left in place and should be deleted when no longer needed.\n\nChanging `PI_OLLAMA_SEARCH_DEV` requires restarting pi or reloading extensions.\n\n## Troubleshooting\n\n### `OLLAMA_API_KEY is not set`\n\nSet the API key before starting pi:\n\n```bash\nexport OLLAMA_API_KEY=\"your_api_key_here\"\n```\n\nIf you added it to `~/.profile`, reload your shell or source the file before starting pi:\n\n```bash\nsource ~/.profile\npi\n```\n\n### HTTP 401 or 403\n\nThe API key is present but Ollama rejected it. Create a new key at `https://ollama.com/settings/keys` and restart pi with the new value.\n\n### Network errors\n\nCheck that your network can reach:\n\n```text\nhttps://ollama.com/api/web_search\nhttps://ollama.com/api/web_fetch\n```\n\n### Config warnings\n\nConfig warnings are non-blocking. If a config file is invalid, the extension continues with safe defaults or higher-level fallback values and surfaces warnings through pi's UI when available.\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nRun checks:\n\n```bash\nnpm run typecheck\nnpm test\n```\n\nFor release/package changes, also run:\n\n```bash\nnpm pack --dry-run\n```\n\nRelease instructions are in [`docs/release.md`](docs/release.md).\n\nThe test suite uses unit tests and a local mock HTTP server. CI does not call the live Ollama API.\n\nManual live verification is optional:\n\n```bash\nsource ~/.profile\nexport PI_OLLAMA_SEARCH_DEV=1\npi -e ./src/index.ts\n```\n\nThen run:\n\n```text\n/ollama-search what is ollama?\n/ollama-fetch https://ollama.com\n/ollama-read-full {\"ref\":\"fetch:...\",\"section\":\"content\"}\n```\n","readmeFilename":"README.md"}