pi-research 1.0.0 → 1.0.2

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.
Files changed (3) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +129 -36
  3. package/package.json +16 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Black-Knight
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -4,23 +4,65 @@
4
4
  [![tests](https://img.shields.io/badge/tests-33%2F33-brightgreen)](https://github.com/endgegnerbert-tech/pi-research)
5
5
  [![Pi package](https://img.shields.io/badge/pi-package-blueviolet)](https://pi.ai)
6
6
 
7
- `pi-research` is a Pi extension for web research.
7
+ `pi-research` is a Pi extension for fast, local-first web research inside the agent.
8
+
9
+ It searches the live web, ranks sources, reads the most relevant pages, and synthesizes a grounded answer with citations.
10
+ It does **not** require an external research API or API key, and it is not a browser automation tool.
11
+
12
+ ## Why it exists
13
+
14
+ Agents usually need two things to answer well:
15
+
16
+ 1. a way to search the web efficiently
17
+ 2. a way to turn sources into a usable answer
18
+
19
+ `pi-research` does both inside Pi, so the agent can research topics without relying on a separate hosted research service.
20
+
21
+ ## What it does
22
+
23
+ - searches the live web
24
+ - scores and deduplicates sources
25
+ - prefers official docs, READMEs, and papers when relevant
26
+ - follows up when the first pass is not enough
27
+ - extracts code blocks for code-focused questions
28
+ - supports local files as additional sources
29
+ - returns a structured result with citations and confidence metadata
30
+
31
+ ## What it is not
32
+
33
+ - not a browser interaction tool
34
+ - not an offline knowledge base
35
+ - not a replacement for page navigation
8
36
 
9
37
  ## Install
10
38
 
39
+ ### For Pi
40
+
11
41
  ```bash
12
42
  pi install npm:pi-research
13
43
  ```
14
44
 
45
+ ### For npm-based workflows
46
+
47
+ ```bash
48
+ npm install pi-research
49
+ ```
50
+
15
51
  GitHub repository: https://github.com/endgegnerbert-tech/pi-research
16
52
 
17
- You can also fork the repository and install it from a local path while developing.
53
+ ## Quick start
54
+
55
+ ```text
56
+ What are the trade-offs between B-trees and LSM-trees?
57
+ ```
18
58
 
19
- ## What it is for
59
+ ```text
60
+ Show me the best way to add health checks to Docker Compose.
61
+ ```
20
62
 
21
- Use `pi-research` when you want the agent to search and synthesize the web.
22
- It is designed for research, not browser navigation.
23
- Use `browser_action` for clicks, screenshots, DOM inspection, or page interaction.
63
+ ```text
64
+ Compare React Server Components with traditional SSR.
65
+ ```
24
66
 
25
67
  ## Modes
26
68
 
@@ -28,18 +70,68 @@ Use `browser_action` for clicks, screenshots, DOM inspection, or page interactio
28
70
  | --- | --- |
29
71
  | `fast` | quick answers with a quality floor |
30
72
  | `deep` | broader retrieval with follow-up rounds |
31
- | `code` | official docs, READMEs, repos, and code snippets |
32
- | `academic` | scholarly sources like arXiv, Semantic Scholar, and DOI papers |
73
+ | `code` | docs, READMEs, repositories, and code snippets |
74
+ | `academic` | scholarly sources and paper-heavy topics |
75
+
76
+ ## Public tool parameters
77
+
78
+ - `query` — research question to answer
79
+ - `mode` — `fast`, `deep`, `code`, or `academic`
80
+ - `force` — bypass cached sufficiency checks
81
+ - `isolate` — run without session/query cache reuse
82
+ - `options.allowedSources` — prefer only the listed source hints
83
+ - `options.requireAuthoritative` — bias toward authoritative sources
84
+ - `options.maxTurns` — limit follow-up rounds
85
+ - `options.maxSites` — limit how many sources are read
86
+ - `options.minYear` / `options.maxYear` — constrain source dates
87
+ - `options.preferRecent` — prefer newer sources
88
+ - `options.files` — include local files as sources
89
+ - `options.format` — output format: `markdown`, `json`, `table`, or `latex`
90
+ - `options.deepResearchConfig` — depth/breadth/concurrency tuning for deeper runs
91
+
92
+ ## Example calls
33
93
 
34
- ## Key features
94
+ ### Fast mode
95
+
96
+ ```text
97
+ query: What is the difference between HTTP and HTTPS?
98
+ mode: fast
99
+ ```
35
100
 
36
- - query-isolated caching and sufficiency gating
37
- - source scoring with visible `sourceType`, `authoritative`, `score`, and `freshness`
38
- - `openSubQuestions`, `missingAspects`, `conflictSummary`
39
- - inline citations in the final answer
40
- - `minYear`, `maxYear`, and `preferRecent` support
41
- - `files[]` for local source input
42
- - `codeBlocks[]` extraction for code-focused answers
101
+ ### Deep mode
102
+
103
+ ```text
104
+ query: Compare PostgreSQL and MySQL for multi-tenant SaaS
105
+ mode: deep
106
+ options:
107
+ preferRecent: true
108
+ maxTurns: 2
109
+ ```
110
+
111
+ ### Code mode
112
+
113
+ ```text
114
+ query: How do I add retries to a Node.js fetch wrapper?
115
+ mode: code
116
+ ```
117
+
118
+ ### Academic mode
119
+
120
+ ```text
121
+ query: Retrieval augmented generation evaluation methods
122
+ mode: academic
123
+ ```
124
+
125
+ ### Local files as sources
126
+
127
+ ```text
128
+ query: Summarize the key points from these notes
129
+ mode: fast
130
+ options:
131
+ files:
132
+ - ./notes/project-notes.md
133
+ - ./docs/spec.md
134
+ ```
43
135
 
44
136
  ## Output
45
137
 
@@ -54,37 +146,38 @@ The tool returns structured data including:
54
146
  - `confidenceScore`
55
147
  - `sufficient`
56
148
  - `authoritativeSourcesFound`
57
- - `followupRounds`
58
- - `followupQuery`
59
149
  - `openSubQuestions`
60
150
  - `missingAspects`
61
151
  - `conflictSummary`
62
- - `conflictingSourcePairs`
63
152
  - `unverifiedClaims`
153
+ - `sourceTypes`
154
+ - `meta`
64
155
 
65
- ## Examples
156
+ ## How it works
66
157
 
67
- ```text
68
- What are the trade-offs between B-trees and LSM-trees?
69
- ```
70
-
71
- ```text
72
- Show me the best way to add health checks to Docker Compose.
73
- ```
158
+ - **query-isolated caching**: repeated identical research can be skipped when the previous result was already sufficient
159
+ - **source scoring**: official docs, READMEs, papers, and local files are preferred over weak sources
160
+ - **follow-up planning**: unclear or conflicting results trigger another round of research
161
+ - **conflict detection**: opposing claims are surfaced explicitly
162
+ - **fact checking**: unsupported answer sentences are marked as unverified
163
+ - **local source input**: files can be added directly to the research context
74
164
 
75
- ```text
76
- Compare React Server Components with traditional SSR.
77
- ```
165
+ ## Limitations
78
166
 
79
- ## Package manifest
167
+ - it still depends on live web access for web research
168
+ - it does not browse pages like a human user
169
+ - it is not fully offline unless you only use local files
170
+ - it is not a browser interaction tool
80
171
 
81
- This repo is a Pi package. The extension entrypoint is:
172
+ ## Package info
82
173
 
83
- - `extensions/pi-research.ts`
174
+ - Package name: `pi-research`
175
+ - Entry point: `extensions/pi-research.ts`
176
+ - Tool name: `pi-research`
177
+ - License: MIT
84
178
 
85
179
  ## Release notes
86
180
 
87
- - Package name: `pi-research`
88
- - Install command: `pi install npm:pi-research`
181
+ - Pi install: `pi install npm:pi-research`
182
+ - npm install: `npm install pi-research`
89
183
  - GitHub: `https://github.com/endgegnerbert-tech/pi-research`
90
- - Tool name: `pi-research`
package/package.json CHANGED
@@ -1,20 +1,29 @@
1
1
  {
2
2
  "name": "pi-research",
3
- "version": "1.0.0",
3
+ "version": "1.0.2",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Pi extension for web research.",
7
+ "license": "MIT",
7
8
  "main": "./index.js",
8
- "files": ["extensions", "index.js", "lib", "README.md", "package.json"],
9
+ "files": [
10
+ "extensions",
11
+ "index.js",
12
+ "lib",
13
+ "README.md",
14
+ "package.json"
15
+ ],
9
16
  "repository": {
10
17
  "type": "git",
11
- "url": "https://github.com/endgegnerbert-tech/pi-research.git"
18
+ "url": "git+https://github.com/endgegnerbert-tech/pi-research.git"
12
19
  },
13
20
  "homepage": "https://github.com/endgegnerbert-tech/pi-research#readme",
14
21
  "bugs": {
15
22
  "url": "https://github.com/endgegnerbert-tech/pi-research/issues"
16
23
  },
17
- "keywords": ["pi-package"],
24
+ "keywords": [
25
+ "pi-package"
26
+ ],
18
27
  "scripts": {
19
28
  "test": "node --test"
20
29
  },
@@ -28,6 +37,8 @@
28
37
  "typebox": "*"
29
38
  },
30
39
  "pi": {
31
- "extensions": ["./extensions/pi-research.ts"]
40
+ "extensions": [
41
+ "./extensions/pi-research.ts"
42
+ ]
32
43
  }
33
44
  }