pi-research 1.0.1 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Black-Knight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,17 +4,45 @@
 [![tests](https://img.shields.io/badge/tests-33%2F33-brightgreen)](https://github.com/endgegnerbert-tech/pi-research)
 [![Pi package](https://img.shields.io/badge/pi-package-blueviolet)](https://pi.ai)
 
-`pi-research` is a Pi extension for web research.
+`pi-research` is a Pi extension for fast, local-first web research inside the agent.
+
+It searches the live web, ranks sources, reads the most relevant pages, and synthesizes a grounded answer with citations.
+It does **not** require an external research API or API key, and it is not a browser automation tool.
+
+## Why it exists
+
+Agents usually need two things to answer well:
+
+1. a way to search the web efficiently
+2. a way to turn sources into a usable answer
+
+`pi-research` does both inside Pi, so the agent can research topics without relying on a separate hosted research service.
+
+## What it does
+
+- searches the live web
+- scores and deduplicates sources
+- prefers official docs, READMEs, and papers when relevant
+- follows up when the first pass is not enough
+- extracts code blocks for code-focused questions
+- supports local files as additional sources
+- returns a structured result with citations and confidence metadata
+
+## What it is not
+
+- not a browser interaction tool
+- not an offline knowledge base
+- not a replacement for page navigation
 
 ## Install
 
-For Pi:
+### For Pi
 
 ```bash
 pi install npm:pi-research
 ```
 
-For npm-based workflows:
+### For npm-based workflows
 
 ```bash
 npm install pi-research
@@ -22,13 +50,19 @@ npm install pi-research
 
 GitHub repository: https://github.com/endgegnerbert-tech/pi-research
 
-You can also fork the repository and install it from a local path while developing.
+## Quick start
 
-## What it is for
+```text
+What are the trade-offs between B-trees and LSM-trees?
+```
 
-Use `pi-research` when you want the agent to search and synthesize the web.
-It is designed for research, not browser navigation.
-Use `browser_action` for clicks, screenshots, DOM inspection, or page interaction.
+```text
+Show me the best way to add health checks to Docker Compose.
+```
+
+```text
+Compare React Server Components with traditional SSR.
+```
 
 ## Modes
 
@@ -36,18 +70,68 @@ Use `browser_action` for clicks, screenshots, DOM inspection, or page interactio
 | --- | --- |
 | `fast` | quick answers with a quality floor |
 | `deep` | broader retrieval with follow-up rounds |
-| `code` | official docs, READMEs, repos, and code snippets |
-| `academic` | scholarly sources like arXiv, Semantic Scholar, and DOI papers |
+| `code` | docs, READMEs, repositories, and code snippets |
+| `academic` | scholarly sources and paper-heavy topics |
+
+## Public tool parameters
+
+- `query` — research question to answer
+- `mode` — `fast`, `deep`, `code`, or `academic`
+- `force` — bypass cached sufficiency checks
+- `isolate` — run without session/query cache reuse
+- `options.allowedSources` — prefer only the listed source hints
+- `options.requireAuthoritative` — bias toward authoritative sources
+- `options.maxTurns` — limit follow-up rounds
+- `options.maxSites` — limit how many sources are read
+- `options.minYear` / `options.maxYear` — constrain source dates
+- `options.preferRecent` — prefer newer sources
+- `options.files` — include local files as sources
+- `options.format` — output format: `markdown`, `json`, `table`, or `latex`
+- `options.deepResearchConfig` — depth/breadth/concurrency tuning for deeper runs
+
+## Example calls
+
+### Fast mode
+
+```text
+query: What is the difference between HTTP and HTTPS?
+mode: fast
+```
+
+### Deep mode
 
-## Key features
+```text
+query: Compare PostgreSQL and MySQL for multi-tenant SaaS
+mode: deep
+options:
+  preferRecent: true
+  maxTurns: 2
+```
+
+### Code mode
+
+```text
+query: How do I add retries to a Node.js fetch wrapper?
+mode: code
+```
+
+### Academic mode
 
-- query-isolated caching and sufficiency gating
-- source scoring with visible `sourceType`, `authoritative`, `score`, and `freshness`
-- `openSubQuestions`, `missingAspects`, `conflictSummary`
-- inline citations in the final answer
-- `minYear`, `maxYear`, and `preferRecent` support
-- `files[]` for local source input
-- `codeBlocks[]` extraction for code-focused answers
+```text
+query: Retrieval augmented generation evaluation methods
+mode: academic
+```
+
+### Local files as sources
+
+```text
+query: Summarize the key points from these notes
+mode: fast
+options:
+  files:
+    - ./notes/project-notes.md
+    - ./docs/spec.md
+```
 
 ## Output
 
@@ -62,38 +146,38 @@ The tool returns structured data including:
 - `confidenceScore`
 - `sufficient`
 - `authoritativeSourcesFound`
-- `followupRounds`
-- `followupQuery`
 - `openSubQuestions`
 - `missingAspects`
 - `conflictSummary`
-- `conflictingSourcePairs`
 - `unverifiedClaims`
+- `sourceTypes`
+- `meta`
 
-## Examples
+## How it works
 
-```text
-What are the trade-offs between B-trees and LSM-trees?
-```
+- **query-isolated caching**: repeated identical research can be skipped when the previous result was already sufficient
+- **source scoring**: official docs, READMEs, papers, and local files are preferred over weak sources
+- **follow-up planning**: unclear or conflicting results trigger another round of research
+- **conflict detection**: opposing claims are surfaced explicitly
+- **fact checking**: unsupported answer sentences are marked as unverified
+- **local source input**: files can be added directly to the research context
 
-```text
-Show me the best way to add health checks to Docker Compose.
-```
+## Limitations
 
-```text
-Compare React Server Components with traditional SSR.
-```
-
-## Package manifest
+- it still depends on live web access for web research
+- it does not browse pages like a human user
+- it is not fully offline unless you only use local files
+- it is not a browser interaction tool
 
-This repo is a Pi package. The extension entrypoint is:
+## Package info
 
-- `extensions/pi-research.ts`
+- Package name: `pi-research`
+- Entry point: `extensions/pi-research.ts`
+- Tool name: `pi-research`
+- License: MIT
 
 ## Release notes
 
-- Package name: `pi-research`
-- Install command for Pi: `pi install npm:pi-research`
-- Install command for npm: `npm install pi-research`
+- Pi install: `pi install npm:pi-research`
+- npm install: `npm install pi-research`
 - GitHub: `https://github.com/endgegnerbert-tech/pi-research`
-- Tool name: `pi-research`

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "pi-research",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "private": false,
   "type": "module",
   "description": "Pi extension for web research.",
+  "license": "MIT",
   "main": "./index.js",
   "files": [
     "extensions",