pi-research 1.0.1 → 1.1.0

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

@@ -1,20 +1,48 @@
 # pi-research
 
 [![npm version](https://img.shields.io/npm/v/pi-research?color=blue)](https://www.npmjs.com/package/pi-research)
-[![tests](https://img.shields.io/badge/tests-33%2F33-brightgreen)](https://github.com/endgegnerbert-tech/pi-research)
+[![tests](https://img.shields.io/badge/tests-56%2F56-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?
+```
+
+```text
+Show me the best way to add health checks to Docker Compose.
+```
 
-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
+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
 
-## Key features
+## Example calls
 
-- 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
+### Fast mode
+
+```text
+query: What is the difference between HTTP and HTTPS?
+mode: fast
+```
+
+### Deep mode
+
+```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
+
+```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,79 @@ The tool returns structured data including:
 - `confidenceScore`
 - `sufficient`
 - `authoritativeSourcesFound`
-- `followupRounds`
-- `followupQuery`
 - `openSubQuestions`
 - `missingAspects`
 - `conflictSummary`
-- `conflictingSourcePairs`
 - `unverifiedClaims`
-
-## Examples
-
-```text
-What are the trade-offs between B-trees and LSM-trees?
+- `sourceTypes`
+- `meta`
+
+## How it works
+
+- **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
+
+## Limits
+
+- 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
+
+## Domain packs
+
+- `web`
+- `github`
+- `security`
+- `papers`
+- `specs`
+- `changelog`
+- `forums`
+- `package-registry`
+- `vendor-status`
+
+## Community packs
+
+You can add your own domain pack by copying `lib/domains/template.js`, adapting the `run()` function, and registering it in `lib/domains/index.js`.
+
+Minimal starter example:
+
+```js
+export default {
+  name: "boxing-training",
+  sourceHints: ["web"],
+  async run(question) {
+    return {
+      claims: [
+        {
+          text: `Starter pack example for ${question}`,
+          evidence: [{ type: "web", source: "https://example.com", snippet: "Example" }],
+          confidence: "medium",
+        },
+      ],
+    };
+  },
+};
 ```
 
-```text
-Show me the best way to add health checks to Docker Compose.
-```
+## Eval
 
-```text
-Compare React Server Components with traditional SSR.
-```
-
-## Package manifest
+Run `npm run eval` to execute the eval harness.
 
-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`
+- Community packs: copy the template pack and register it in `lib/domains/index.js`

package/lib/domains/changelog.js

@@ -0,0 +1,10 @@
+export default {
+  name: "changelog",
+  sourceHints: ["changelog", "release notes", "releases"],
+  allowedSources: ["github.com", "docs.", "release notes"],
+  queryHints: ["release notes", "changelog", "site:github.com/releases"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "changelog" };
+  },
+};

package/lib/domains/forums.js

@@ -0,0 +1,9 @@
+export default {
+  name: "forums",
+  sourceHints: ["stackoverflow", "discourse", "reddit"],
+  allowedSources: ["stackoverflow.com", "discourse", "reddit.com"],
+  queryHints: ["site:stackoverflow.com", "discourse", "site:reddit.com"],
+  async run() {
+    return { name: "forums" };
+  },
+};

package/lib/domains/github.js

@@ -0,0 +1,9 @@
+export default {
+  name: "github",
+  sourceHints: ["issues", "discussions", "pull requests", "readme"],
+  allowedSources: ["github.com"],
+  queryHints: ["site:github.com", "issues", "discussions", "readme"],
+  async run() {
+    return { name: "github" };
+  },
+};

package/lib/domains/index.js

@@ -0,0 +1,46 @@
+import web from "./web.js";
+import github from "./github.js";
+import forums from "./forums.js";
+import security from "./security.js";
+import packageRegistry from "./package-registry.js";
+import changelog from "./changelog.js";
+import papers from "./papers.js";
+import specs from "./specs.js";
+import vendorStatus from "./vendor-status.js";
+
+const PACKS = {
+  web,
+  github,
+  forums,
+  security,
+  "package-registry": packageRegistry,
+  changelog,
+  papers,
+  specs,
+  "vendor-status": vendorStatus,
+};
+
+const DOMAIN_NAMES = ["web", "github", "security", "papers", "specs", "changelog", "forums", "package-registry", "vendor-status"];
+
+export function listDomainPacks() {
+  return [...DOMAIN_NAMES];
+}
+
+export function getDomainPack(name = "web") {
+  return PACKS[name] || web;
+}
+
+import { classifyQuestionDomain } from "../research-intent.js";
+
+export function resolveDomainConfig(questionOrDomain = "web") {
+  const name = PACKS[questionOrDomain] ? questionOrDomain : classifyQuestionDomain(questionOrDomain);
+  const pack = PACKS[name] || PACKS.web;
+  return {
+    domain: name,
+    allowedSources: pack.allowedSources || [],
+    allowedSourceTypes: pack.allowedSourceTypes || [],
+    queryHints: pack.queryHints || [],
+    requireAuthoritative: Boolean(pack.requireAuthoritative),
+    format: pack.format || "markdown",
+  };
+}

package/lib/domains/package-registry.js

@@ -0,0 +1,11 @@
+export default {
+  name: "package-registry",
+  sourceHints: ["npm", "pypi", "cargo", "maven"],
+  allowedSources: ["npmjs.com", "pypi.org", "crates.io", "mvnrepository.com"],
+  allowedSourceTypes: ["official_doc", "github_readme"],
+  queryHints: ["site:npmjs.com", "site:pypi.org", "site:crates.io", "site:mvnrepository.com"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "package-registry" };
+  },
+};

package/lib/domains/papers.js

@@ -0,0 +1,11 @@
+export default {
+  name: "papers",
+  sourceHints: ["arxiv", "semanticscholar", "doi"],
+  allowedSources: ["arxiv.org", "semanticscholar.org", "doi.org", "pubmed.ncbi.nlm.nih.gov"],
+  allowedSourceTypes: ["paper"],
+  queryHints: ["site:arxiv.org", "site:semanticscholar.org", "site:doi.org"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "papers" };
+  },
+};

package/lib/domains/security.js

@@ -0,0 +1,11 @@
+export default {
+  name: "security",
+  sourceHints: ["cve", "advisory", "security bulletin"],
+  allowedSources: ["nvd.nist.gov", "cisa.gov", "mitre.org", "ubuntu.com", "redhat.com", "debian.org", "suse.com"],
+  allowedSourceTypes: ["official_doc", "paper"],
+  queryHints: ["nvd", "cisa", "mitre", "advisory", "cve"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "security" };
+  },
+};

package/lib/domains/specs.js

@@ -0,0 +1,11 @@
+export default {
+  name: "specs",
+  sourceHints: ["rfc", "spec", "standard"],
+  allowedSources: ["rfc-editor.org", "datatracker.ietf.org", "w3.org"],
+  allowedSourceTypes: ["official_doc"],
+  queryHints: ["site:rfc-editor.org", "site:datatracker.ietf.org", "RFC"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "specs" };
+  },
+};

package/lib/domains/template.js

@@ -0,0 +1,26 @@
+export default {
+  name: "template",
+  description: "Minimal domain pack example for pi-research",
+  sourceHints: ["web"],
+  queryHints: ["site:example.com"],
+  async run(question, options) {
+    return {
+      claims: [
+        {
+          text: `This is a minimal example for a domain pack: ${question}`,
+          evidence: [
+            {
+              type: "web",
+              source: "https://example.com",
+              snippet: "Minimal example",
+            },
+          ],
+          confidence: "medium",
+          confidenceDescription: "Just an example",
+        },
+      ],
+      evidenceSummary: "Starter example only.",
+      sourceTypes: ["other"],
+    };
+  },
+};

package/lib/domains/vendor-status.js

@@ -0,0 +1,10 @@
+export default {
+  name: "vendor-status",
+  sourceHints: ["status", "incident", "outage"],
+  allowedSources: ["status", "statuspage.io", "status.github.com"],
+  queryHints: ["status page", "incident", "outage"],
+  requireAuthoritative: true,
+  async run() {
+    return { name: "vendor-status" };
+  },
+};

package/lib/domains/web.js

@@ -0,0 +1,7 @@
+export default {
+  name: "web",
+  sourceHints: ["official docs", "readme", "overview"],
+  async run() {
+    return { name: "web" };
+  },
+};

package/lib/eval/case-loader.js

@@ -0,0 +1,13 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function loadEvalCases(domain) {
+  const dir = join(process.cwd(), "eval", "cases", domain);
+  try {
+    return readdirSync(dir)
+      .filter((file) => file.endsWith(".json"))
+      .map((file) => JSON.parse(readFileSync(join(dir, file), "utf8")));
+  } catch {
+    return [];
+  }
+}

package/lib/eval/runner.js

@@ -0,0 +1,8 @@
+import { loadEvalCases } from "./case-loader.js";
+
+export async function runEvalSuite({ domain }) {
+  const cases = loadEvalCases(domain);
+  const passed = cases.filter((item) => item.expectedDomain === domain).length;
+  const total = cases.length;
+  return { total, passed, passRate: total ? passed / total : 0 };
+}

package/lib/research-evidence.js

@@ -0,0 +1,21 @@
+export function createEvidence(evidence = {}) {
+  return {
+    type: evidence.type || "web",
+    source: evidence.source || "",
+    snippet: evidence.snippet || "",
+  };
+}
+
+export function createClaim(claim = {}) {
+  return {
+    text: claim.text || "",
+    confidence: claim.confidence || "low",
+    evidence: Array.isArray(claim.evidence) ? claim.evidence.map(createEvidence) : [],
+  };
+}
+
+export function explainConfidence(confidence = "low", evidenceCount = 0) {
+  if (confidence === "high" && evidenceCount >= 2) return "Multiple sources support this claim.";
+  if (confidence === "medium") return "Some supporting evidence was found.";
+  return "Limited supporting evidence was found.";
+}

package/lib/research-intent.js

@@ -0,0 +1,20 @@
+function text(value) {
+  return String(value || "").toLowerCase();
+}
+
+export function classifyQuestionDomain(question) {
+  const q = text(question);
+  if (/(cve-|cve\b|advisory|security|vulnerability|exploit)/.test(q)) return "security";
+  if (/(status page|status|outage|incident)/.test(q)) return "vendor-status";
+  if (/(changelog|release notes?|releases?|version history)/.test(q)) return "changelog";
+  if (/(github|issue|issues|pull request|repo\b|repository\b|discussions?)/.test(q)) return "github";
+  if (/(arxiv|paper|papers|study|(?<!pi-)research|scientific|scholar)/.test(q)) return "papers";
+  if (/(rfc|spec|specification|standard|standards)/.test(q)) return "specs";
+  if (/(stackoverflow|stack overflow|discourse|reddit|forum|forums)/.test(q)) return "forums";
+  if (/(npm|pypi|cargo|maven|package registry|package|library)/.test(q)) return "package-registry";
+  return "web";
+}
+
+export function normalizeResearchMode(input = {}, fallback = "fast") {
+  return input && typeof input === "object" && input.mode ? input.mode : fallback;
+}

package/lib/research-output.js

@@ -0,0 +1,7 @@
+export function resolveOutputFormat(input = {}, fallback = "markdown") {
+  return input && typeof input === "object" && input.format ? input.format : fallback;
+}
+
+export function shouldRequireAuthoritativeSources(input = {}, fallback = false) {
+  return Boolean(input && typeof input === "object" && input.requireAuthoritative) || Boolean(fallback);
+}

package/lib/research.js

@@ -386,6 +386,25 @@ export function rankFetchedPages(pages, query, limit = pages.length, config = {}
   return [...pages].sort((a, b) => scoreFetchedPage(b, query, config) - scoreFetchedPage(a, query, config)).slice(0, limit);
 }
 
+export function detectClaimConflicts(claims = []) {
+  const texts = claims.map((claim) => String(claim?.text || claim || "").toLowerCase());
+  const hasPositive = texts.some((text) => /\b(supported|works|available|recommended|yes|stable|compatible)\b/.test(text));
+  const hasNegative = texts.some((text) => /\b(not supported|unsupported|does not|no support|broken|incompatible|removed)\b/.test(text));
+  return {
+    detected: hasPositive && hasNegative,
+    conflictSummary: hasPositive && hasNegative ? "Claims conflict." : "",
+  };
+}
+
+export function detectCoverageGaps(input = {}) {
+  const claims = Array.isArray(input.claims) ? input.claims : [];
+  const authoritativeSourcesFound = claims.some((claim) => Array.isArray(claim?.evidence) && claim.evidence.length > 0);
+  return {
+    detected: !authoritativeSourcesFound,
+    missingAspects: authoritativeSourcesFound ? [] : ["authoritative sources"],
+  };
+}
+
 export function detectConflictSignals(pages) {
   if (!Array.isArray(pages) || pages.length < 2) {
     return { detected: false, reason: null, conflictSummary: "", conflictingSourcePairs: [] };
@@ -592,15 +611,17 @@ export function extractCodeBlocks(text) {
 export function evaluateSufficiency(input, legacyPages, legacyConflictDetected = false) {
   const payload = typeof input === "string"
     ? { query: input, sources: legacyPages || [], conflictDetected: legacyConflictDetected }
-    : { query: input?.query || "", sources: input?.sources || [], conflictDetected: Boolean(input?.conflictDetected), confidence: input?.confidence, minSources: input?.minSources };
+    : { query: input?.query || "", sources: input?.sources || [], claims: input?.claims || [], conflictDetected: Boolean(input?.conflictDetected), confidence: input?.confidence, minSources: input?.minSources };
 
   const scoredSources = payload.sources.map((page) => scoreSourceEntry(page, payload.query || ""));
   const authoritativeCount = scoredSources.filter((scored) => Boolean(scored.authoritative)).length;
   const authoritativeSourcesFound = authoritativeCount > 0;
   const conflict = detectConflictSignals(payload.sources);
-  const conflictDetected = payload.conflictDetected || conflict.detected;
+  const claimConflict = detectClaimConflicts(payload.claims);
+  const coverage = detectCoverageGaps(payload);
+  const conflictDetected = payload.conflictDetected || conflict.detected || claimConflict.detected;
   const missingAspects = [];
-  if (!authoritativeSourcesFound) missingAspects.push("authoritative sources");
+  if (!authoritativeSourcesFound || coverage.detected) missingAspects.push("authoritative sources");
   if (conflictDetected) missingAspects.push("conflict resolution");
   if (!payload.sources.length) missingAspects.push("readable sources");
 
@@ -654,6 +675,16 @@ export function compactResearchPayload(payload) {
           ...(typeof source.local === "boolean" ? { local: source.local } : {}),
         }))
       : [],
+    claims: Array.isArray(payload.claims) ? payload.claims.slice(0, 8).map((claim) => ({
+      text: claim.text,
+      confidence: claim.confidence,
+      evidence: Array.isArray(claim.evidence) ? claim.evidence.slice(0, 5).map((evidence) => ({
+        type: evidence.type,
+        source: evidence.source,
+        snippet: evidence.snippet,
+      })) : [],
+    })) : [],
+    evidenceSummary: payload.evidenceSummary || "",
     sourceTypes: Array.isArray(payload.sourceTypes) ? payload.sourceTypes.slice(0, 8) : [],
     unverifiedClaims: Array.isArray(payload.unverifiedClaims) ? payload.unverifiedClaims.slice(0, 8) : [],
     meta: payload.meta && typeof payload.meta === "object" ? payload.meta : undefined,
@@ -675,12 +706,20 @@ export function extractPageSnapshot(html, url) {
   return { title, url, text: stripTags(body), codeBlocks: extractCodeBlocks(html) };
 }
 
-export function formatResearchResponse({ answer, bullets, sources, confidence }) {
+export function formatResearchResponse({ answer, bullets, sources, confidence, format = "markdown" }) {
+  const list = Array.isArray(sources) ? sources : [];
+  if (format === "json") {
+    return JSON.stringify({ answer: String(answer || "").trim(), bullets: bullets || [], confidence: confidence || "", sources: list });
+  }
+  if (format === "table") {
+    const rows = list.map((source, index) => `| ${index + 1} | ${source.title} | ${source.url} |`).join("\n");
+    return ["| # | Title | URL |", "|---|---|---|", rows].filter(Boolean).join("\n").trim();
+  }
   const parts = ["## Answer", "", String(answer || "").trim(), "", "## Key points"];
   for (const bullet of bullets || []) parts.push(`- ${bullet}`);
   if (confidence) parts.push("", "## Confidence", "", confidence);
   parts.push("", "## Sources");
-  (sources || []).forEach((source, index) => {
+  list.forEach((source, index) => {
     const freshness = source.freshness ? ` (${source.freshness})` : "";
     const meta = [];
     if (source.sourceType) meta.push(source.sourceType);

package/lib/types.js

@@ -36,6 +36,8 @@ export function createResearchResult(result = {}) {
     bullets: Array.isArray(result.bullets) ? result.bullets : [],
     citations: Array.isArray(result.citations) ? result.citations : [],
     sources: Array.isArray(result.sources) ? result.sources.map(createResearchSource) : [],
+    claims: Array.isArray(result.claims) ? result.claims : [],
+    evidenceSummary: result.evidenceSummary || "",
     codeBlocks: Array.isArray(result.codeBlocks) ? result.codeBlocks : [],
     sufficient: Boolean(result.sufficient),
     missingAspects: Array.isArray(result.missingAspects) ? result.missingAspects : [],

package/lib/web-research.js

@@ -5,6 +5,8 @@ import { complete } from "@mariozechner/pi-ai";
 
 import profiles from "./research-profiles.json" with { type: "json" };
 import { createResearchResult } from "./types.js";
+import { resolveDomainConfig } from "./domains/index.js";
+import { classifyQuestionDomain } from "./research-intent.js";
 import {
   buildConfidenceSummary,
   buildDeepQueries,
@@ -33,6 +35,7 @@ import {
   scoreSourceEntry,
   selectRelevantChunks,
 } from "./research.js";
+import { resolveOutputFormat, shouldRequireAuthoritativeSources } from "./research-output.js";
 import { planResearch } from "./planner.js";
 import {
   clearResearchMemory,
@@ -79,15 +82,18 @@ export function resolveResearchConfig(input = "fast") {
   const options = normalizeResearchOptions(input);
   const base = profiles[options.mode] || profiles.fast;
   const deep = options.deepResearchConfig || {};
+  const domainConfig = resolveDomainConfig(options.domain || "web");
 
   return {
     ...base,
+    ...domainConfig,
     ...options,
     mode: base.mode,
     maxTurns: options.maxTurns ?? (deep.depth ? Math.max(base.maxTurns || 1, deep.depth) : (base.maxTurns || 1)),
     maxQueries: options.maxQueries ?? (deep.breadth ? Math.max(base.maxQueries || 2, deep.breadth * (deep.depth || 1)) : (base.maxQueries || 2)),
     maxPages: options.maxSites ?? options.maxPages ?? base.maxPages,
-    allowedSourceTypes: options.allowedSourceTypes ?? base.allowedSourceTypes,
+    allowedSourceTypes: options.allowedSourceTypes ?? (Array.isArray(domainConfig.allowedSourceTypes) && domainConfig.allowedSourceTypes.length ? domainConfig.allowedSourceTypes : base.allowedSourceTypes),
+    allowedSources: options.allowedSources ?? (Array.isArray(domainConfig.allowedSources) && domainConfig.allowedSources.length ? domainConfig.allowedSources : base.allowedSources),
     searchProvider: options.searchProvider ?? base.searchProvider,
     concurrentQueries: deep.concurrency ?? options.concurrentQueries ?? 3,
     depth: deep.depth ?? 1,
@@ -101,7 +107,10 @@ export function resolveResearchConfig(input = "fast") {
     files: Array.isArray(options.files) ? options.files : [],
     isolate: Boolean(options.isolate || process.env.RESEARCH_ISOLATE === "1"),
     force: Boolean(options.force),
-    format: options.format ?? "markdown",
+    format: resolveOutputFormat(options, domainConfig.format || "markdown"),
+    queryHints: Array.isArray(domainConfig.queryHints) ? domainConfig.queryHints : [],
+    requireAuthoritative: Boolean(options.requireAuthoritative ?? domainConfig.requireAuthoritative),
+    domain: domainConfig.domain,
   };
 }
 
@@ -150,8 +159,11 @@ async function completeWithResearchModel(ctx, signal, prompt, reasoningEffort =
 
 export async function buildQueries(query, mode = "fast", ctx, signal) {
   const config = getResearchConfig(mode);
+  const hintedQueries = Array.isArray(config.queryHints) && config.queryHints.length
+    ? config.queryHints.map((hint) => `${query} ${hint}`)
+    : [];
   if (config.mode === "code") {
-    return planResearch(query, "code").subqueries.slice(0, config.maxQueries);
+    return [...new Set([...planResearch(query, "code").subqueries, ...hintedQueries])].slice(0, config.maxQueries);
   }
   if (config.mode === "deep" || config.mode === "academic") {
     const prompt = [
@@ -165,15 +177,15 @@ export async function buildQueries(query, mode = "fast", ctx, signal) {
 
     try {
       const text = await completeWithResearchModel(ctx, signal, prompt, "low");
-      if (text) return parseDeepQueryPlan(text, query, config.maxQueries);
+      if (text) return [...new Set([...parseDeepQueryPlan(text, query, config.maxQueries), ...hintedQueries])].slice(0, config.maxQueries);
     } catch {
       // fall through
     }
 
-    return buildDeepQueries(query, config.maxQueries);
+    return [...new Set([...buildDeepQueries(query, config.maxQueries), ...hintedQueries])].slice(0, config.maxQueries);
   }
 
-  return buildFastQueries(query, config.maxQueries);
+  return [...new Set([...buildFastQueries(query, config.maxQueries), ...hintedQueries])].slice(0, config.maxQueries);
 }
 
 function withTimeoutSignal(signal, timeoutMs) {
@@ -499,8 +511,8 @@ function planSubqueries(rootQuery, currentQuery, config, sufficiency) {
   return [...new Set(queries.filter(Boolean))].slice(0, Math.max(1, config.breadth || 2));
 }
 
-function formatResultText(result) {
-  return formatResearchResponse({ answer: result.answer, bullets: result.bullets, sources: result.sources, confidence: result.confidence });
+function formatResultText(result, format) {
+  return formatResearchResponse({ answer: result.answer, bullets: result.bullets, sources: result.sources, confidence: result.confidence, format });
 }
 
 function modeCacheKey(query, config) {
@@ -520,7 +532,8 @@ function modeCacheKey(query, config) {
 }
 
 export async function runWebResearch(query, ctx, signal, onUpdate, mode = "fast") {
-  const config = getResearchConfig(mode);
+  const domain = classifyQuestionDomain(query);
+  const config = getResearchConfig(typeof mode === "object" ? { ...mode, domain } : { mode, domain });
   const cacheKey = modeCacheKey(query, config);
 
   if (!config.isolate && !config.force) {
@@ -546,7 +559,7 @@ export async function runWebResearch(query, ctx, signal, onUpdate, mode = "fast"
   let conflictSummary = "";
   let conflictingSourcePairs = [];
   let sufficiency = { sufficient: false, confidenceScore: 0.1, missingAspects: [], openSubQuestions: [] };
-  let currentQueries = await buildQueries(query, config.mode, ctx, signal);
+  let currentQueries = await buildQueries(query, config, ctx, signal);
   subqueries = [...currentQueries];
 
   const localPages = await readLocalFiles(config.files || [], config);
@@ -665,7 +678,7 @@ export async function runWebResearch(query, ctx, signal, onUpdate, mode = "fast"
     citations: synthesis.citations || [],
     sources,
     codeBlocks,
-    sufficient: sufficiency.sufficient && unverifiedRatio <= 0.2,
+    sufficient: sufficiency.sufficient && unverifiedRatio <= 0.2 && (!shouldRequireAuthoritativeSources(config) || sufficiency.authoritativeSourcesFound),
     missingAspects: sufficiency.missingAspects,
     openSubQuestions,
     conflictSummary: conflictSummary || sufficiency.conflictSummary || "",
@@ -698,6 +711,7 @@ export async function runWebResearch(query, ctx, signal, onUpdate, mode = "fast"
     sources: normalizedResult.sources,
     sourceTypes,
     codeBlocks: normalizedResult.codeBlocks,
+    format: config.format,
     confidence,
     meta: normalizedResult.meta,
     confidenceScore: sufficiency.confidenceScore,
@@ -707,7 +721,7 @@ export async function runWebResearch(query, ctx, signal, onUpdate, mode = "fast"
     openSubQuestions: normalizedResult.openSubQuestions,
     missingAspects: normalizedResult.missingAspects,
     unverifiedClaims: normalizedResult.unverifiedClaims,
-    contentText: formatResultText({ answer: normalizedResult.answer, bullets: normalizedResult.bullets, sources: normalizedResult.sources, confidence }),
+    contentText: formatResultText({ answer: normalizedResult.answer, bullets: normalizedResult.bullets, sources: normalizedResult.sources, confidence }, config.format),
   };
 
   setResearchMemory(cacheKey, result);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "pi-research",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "private": false,
   "type": "module",
   "description": "Pi extension for web research.",
+  "license": "MIT",
   "main": "./index.js",
   "files": [
     "extensions",
@@ -24,11 +25,13 @@
     "pi-package"
   ],
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "eval": "node --test test/eval-runner.test.js"
   },
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.69.0",
-    "typebox": "^1.1.32"
+    "@mariozechner/pi-ai": "*",
+    "pi-research": "^1.0.2",
+    "typebox": "*"
   },
   "peerDependencies": {
     "@mariozechner/pi-ai": "*",