Michael Freno
c3e0770cc4
- Per-query result grouping: findings analyzed under the query that produced them, with angle + query provenance carried through to synthesis - Cross-query corroboration via multi-query URL counts (before global dedup); same-query findings no longer corroborate each other - Robust LLM JSON parsing (code fences, trailing commas, prose prefixes) - Expanded domain authority map to 90+ domains + LOW_AUTHORITY_DOMAINS floor; authority-aware source truncation in analysis prompts - Citation integrity: authoritative bibliography replaces LLM references, hallucinated inline citations stripped - Near-duplicate title detection for syndicated articles; cross-round finding dedup with quality-ranked 30-finding synthesis cap - Junk result filtering, retry-with-backoff, fixed successfulSearches count - Standalone harness (scripts/run-harness.ts) for cache-bypassing iteration
123 lines
5.8 KiB
Markdown
123 lines
5.8 KiB
Markdown
# Deep Research
|
||
|
||
Multi-round deep web research powered by Firecrawl with iterative query refinement.
|
||
|
||
```bash
|
||
pi install npm:@mikefreno/deep-research
|
||
```
|
||
|
||
## Features
|
||
|
||
- **Multi-round iteration**: Each round generates follow-up queries based on previous findings (depth 1-3)
|
||
- **Parallel query expansion**: Multiple diverse search queries per round (breadth 1-5) covering technical, practical, comparative, critical, and forward-looking angles
|
||
- **Sub-question decomposition**: Broad questions are broken into focused sub-topics before query generation (depth > 1)
|
||
- **Round-robin parallel execution**: Searches and analyses run concurrently within each round using bounded-concurrency worker pools, dramatically reducing total research time
|
||
- **LLM-driven analysis**: Each query's results are analyzed by its own agent session (per-query provenance) to extract structured findings with confidence ratings
|
||
- **Source authority scoring**: Every source is scored by domain authority; low-quality SEO domains are penalized with a hard floor; findings are ranked by authority × confidence before synthesis
|
||
- **Cross-query corroboration**: A finding is corroborated only when its sources were independently surfaced by multiple different search queries
|
||
- **Citation integrity**: References are rebuilt from the authoritative bibliography (never the LLM's), and hallucinated inline citation numbers are stripped
|
||
- **Near-duplicate detection**: Syndicated copies of the same article are removed by title similarity, and duplicate findings across rounds are merged
|
||
- **Automatic deduplication**: Search results are deduplicated by URL across all queries
|
||
- **Robust LLM output parsing**: JSON output with code fences, prose prefixes, or trailing commas is parsed reliably
|
||
- **Graceful degradation**: Individual search or analysis failures don't crash the full research — partial results are preserved, with retry-with-backoff for transient Firecrawl errors
|
||
- **Progress streaming**: Real-time progress widget with spinner, phase indicators, and progress bar
|
||
- **Abort support**: Research can be cancelled mid-flight via `AbortSignal`
|
||
- **Rich TUI rendering**: Compact collapsed view and detailed expanded view in the terminal UI
|
||
- **Fallback resilience**: Built-in fallback query generation and report synthesis when LLM calls fail
|
||
|
||
## Usage
|
||
|
||
### Tool (LLM-callable)
|
||
|
||
Registers the `deep_research` tool for AI agent use:
|
||
|
||
```
|
||
deep_research — multi-round deep web research via Firecrawl with iterative query refinement
|
||
```
|
||
|
||
Parameters:
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `question` | string | — | The research question to investigate |
|
||
| `depth` | integer (1-3) | 2 | Number of research rounds |
|
||
| `breadth` | integer (1-5) | 3 | Search queries per round |
|
||
| `format` | "markdown" \| "structured" | "markdown" | Output format for the report |
|
||
| `audience` | "general" \| "expert" \| "executive" | "general" | Tone and depth for the report audience |
|
||
| `details.showRoundDetails` | boolean | false | Include per-round search metadata (incl. failed searches) in output |
|
||
|
||
### Command (interactive)
|
||
|
||
```
|
||
/deepi-research <your research question>
|
||
```
|
||
|
||
Prompts for depth (1-3 rounds) and breadth (1-5 queries) interactively, then runs the research and sends the final report as a user message.
|
||
|
||
### Recommended usage
|
||
|
||
- Use `deep_research` for complex, multi-faceted questions that benefit from multiple search angles and iterative refinement.
|
||
- The tool handles query generation, web search, result analysis, and report synthesis automatically.
|
||
- For simple fact-finding questions, use `firecrawl_search` directly instead.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Research Flow:
|
||
|
||
Question
|
||
↓
|
||
┌─ Round 1 ───────────────────────────┐
|
||
│ LLM → generate queries (N angles) │
|
||
│ Firecrawl → search each query │
|
||
│ LLM → analyze results → findings │
|
||
└──────────────┬───────────────────────┘
|
||
↓ (follow-up queries)
|
||
┌─ Round 2 ───────────────────────────┐
|
||
│ LLM → identify knowledge gaps │
|
||
│ Firecrawl → search follow-ups │
|
||
│ LLM → analyze → new findings │
|
||
└──────────────┬───────────────────────┘
|
||
↓ (iterate depth times)
|
||
┌─ Synthesis ─────────────────────────┐
|
||
│ LLM → synthesize all findings │
|
||
│ → comprehensive research report │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
## Configuration
|
||
|
||
Deep Research reads Firecrawl configuration from pi's settings.json files, with the following resolution order (later wins):
|
||
|
||
1. Environment variables (`FIRECRAWL_BASE_URL`, `FIRECRAWL_API_KEY`)
|
||
2. Global settings (`$agentDir/settings.json`) → `firecrawl.*`
|
||
3. Project settings (`.pi/settings.json`) → `firecrawl.*`
|
||
4. Default `http://localhost:3002` (if nothing else sets baseUrl)
|
||
|
||
The agent directory (`$agentDir`) defaults to `~/.pi/agent` and respects the `PI_CODING_AGENT_DIR` environment variable.
|
||
|
||
**Global settings** (`~/.pi/agent/settings.json`):
|
||
|
||
```json
|
||
{
|
||
"firecrawl": {
|
||
"baseUrl": "http://localhost:3002",
|
||
}
|
||
}
|
||
```
|
||
|
||
**Project settings** (`.pi/settings.json` — overrides global):
|
||
|
||
```json
|
||
{
|
||
"firecrawl": {
|
||
"baseUrl": "https://firecrawl.team.internal"
|
||
"apiKey": "your-api-key"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Session startup check
|
||
|
||
On `session_start`, the extension checks whether the Firecrawl endpoint is reachable. If not, it shows a warning notification so you know searches will fail before you try to use it.
|