hyperresearch 0.7.0__tar.gz → 0.8.3__tar.gz

{hyperresearch-0.7.0 → hyperresearch-0.8.3}/.gitignore

@@ -14,6 +14,7 @@ build/
 .env
 bench/
 codex_bench/
+draco-bench/
 
 # Agent install outputs — generated per-user by `hyperresearch install`.
 # These files contain absolute paths resolved to the installing user's

{hyperresearch-0.7.0 → hyperresearch-0.8.3}/CHANGELOG.md

@@ -1,14 +1,62 @@
 # Changelog
 
+## [0.8.3] - 2026-04-29
+
+### Quieter global install — step skills lazy-load per-project
+
+Global install (`hyperresearch install --global`) used to write all 16 step skills to `~/.claude/skills/`, advertising them in the available-skills system reminder of every Claude Code session — ~3K tokens of noise on sessions where `/hyperresearch` is never used.
+
+- **Global install now writes only the entry skill + agents to `~/.claude/`.** The 16 step skills (`hyperresearch-1-decompose` … `hyperresearch-16-readability-audit`) install per-project, lazily.
+- **Entry skill bootstrap step 0** now also runs `hyperresearch install --steps-only .` if step skills aren't found in the project's `.claude/skills/`. First `/hyperresearch` invocation in a fresh project materializes the step skills there. Subsequent invocations no-op.
+- **New `hyperresearch install --steps-only [PATH]`** flag — installs only the 16 step skills to `<path>/.claude/skills/`. Used by the bootstrap, also available manually.
+- **Upgrade prune** — `hyperresearch install --global` removes any `hyperresearch-N-*` step-skill dirs left in `~/.claude/skills/` by 0.8.2-and-earlier global installs.
+
+Net effect: sessions in projects that never use hyperresearch see only the entry skill + agent descriptions in their available-skills/agents lists. Step-skill noise is scoped to projects that actually use the tool.
+
+## [0.8.2] - 2026-04-29
+
+### Global install
+
+- **`hyperresearch install --global`** writes the Claude Code skills + agents to `~/.claude/` so `/hyperresearch` is available in every Claude Code session anywhere on the machine, with no per-project setup. Skips vault init and CLAUDE.md injection (those happen automatically per-project on first `/hyperresearch` invocation).
+- New `install_global_hooks()` in `core/hooks.py` that targets `~/.claude/` and skips the PreToolUse hook script (would otherwise fire on every Claude Code session).
+- Entry skill bootstrap now auto-runs `hyperresearch init .` if no vault exists in cwd, so the global-install workflow is fully seamless: pip install + `hyperresearch install --global` once, then `/hyperresearch` works everywhere and materializes the vault + `research/` folder + `CLAUDE.md` in whatever project root you're in on first use.
+
+## [0.8.1] - 2026-04-29
+
+### Surface cleanup
+
+- **`/research` alias retired.** Only `/hyperresearch` remains. The `research` skill dir is now in `_RETIRED_SKILL_DIRS` and is pruned automatically on the next `hyperresearch install`.
+- **`standard` tier removed.** Only `light` and `full` remain. Step 1's classifier folds the previous standard-tier signals (surveys, multi-entity comparisons, landscape overviews) into `light`. Mid-tier fan-out (3 critics, 60–100 URLs, 40–60 claims) is gone — the simplification is intentional.
+- **Time estimates re-calibrated.** Light: ~30–40 minutes (was 3–8 min). Full: ~1.5–2.5 hours (was 25–60 min). Numbers reflect realistic wall-clock times observed across recent runs, not theoretical floors.
+- **README tier table** drops the cost column.
+
+## [0.8.0] - 2026-04-29
+
+### Architecture — V8.3 deployment release
+
+The flagship pipeline ships as a tier-adaptive 16-step chain. The `/research-layercake` slash command is retired; the entry skill is now invokable as both `/hyperresearch` and `/research`. Internal codename "layercake" is gone — everywhere — replaced by the product name. The simple V1 single-pass research skill and its four modality variants are removed; the V8 `light` tier replaces them as the fast path for bounded queries.
+
+### Changed
+- **Entry skill aliasing.** `hyperresearch install` now writes the entry skill to both `.claude/skills/hyperresearch/SKILL.md` and `.claude/skills/research/SKILL.md` so Claude Code registers `/hyperresearch` and `/research` as independent triggers for the same V8 pipeline.
+- **Step skills renamed.** All 16 step skills moved from `layercake-N-name` to `hyperresearch-N-name`. The Skill-tool invocations in every step file route to the new names. Pre-existing `layercake-*` skill directories are pruned automatically on the next `hyperresearch install`.
+- **V1 skills removed.** `research.md`, `research-collect.md`, `research-compare.md`, `research-forecast.md`, `research-synthesize.md` deleted from the source tree. The V8 `light` tier (steps 1 → 2 → 10 → 15 → 16) is the fast path for short bounded queries.
+- **Light tier coherence.** Step 10's light path now has explicit guidance for vault-driven evidence sourcing, structural-heading compliance, citation rendering, and hygiene rules. Step 15's integrity gate is tier-conditional — it no longer demands critic-findings or patch-log artifacts when those steps were tier-skipped.
+- **Lint workflow rule** renamed from "Layercake artifacts missing" to "Hyperresearch artifacts missing" (cosmetic).
+
+### Pruned on upgrade
+- Skill dir `research-layercake` deleted (superseded by `/hyperresearch` alias).
+- V1 modality files (`SKILL-collect.md`, `SKILL-synthesize.md`, `SKILL-compare.md`, `SKILL-forecast.md`) removed from the install dir.
+- Legacy `layercake-*` step-skill directories cleaned up.
+
 ## [0.7.0] - 2026-04-17
 
-### Architecture — `/research-ensemble` retired, `/research-layercake` introduced
+### Architecture — `/research-ensemble` retired, `/hyperresearch` introduced
 
 This release replaces the three-parallel-drafts-plus-merger ensemble design with a seven-phase layered pipeline. Width is discovered first, depth loci are derived from the width corpus (not pre-assigned framings), one draft is written from the combined evidence, three adversarial critics run in parallel against it, and the draft is then modified ONLY by surgical Edit hunks — never regenerated.
 
 ### New
 
-- **7-phase layercake pipeline** — (1) width sweep via parallel fetchers, (2) two parallel loci-analysts identify 1–8 depth loci from the corpus, (3) one depth-investigator per locus writes an `interim-<locus>.md` note, (4) orchestrator writes ONE draft, (5) dialectic / depth / width critics return structured findings JSONs, (6) the patcher applies findings as Edit hunks, (7) the polish auditor cuts filler and strips hygiene leaks via more Edit hunks. Protocol lives at `.claude/skills/research-layercake/SKILL.md`.
+- **7-phase hyperresearch pipeline** — (1) width sweep via parallel fetchers, (2) two parallel loci-analysts identify 1–8 depth loci from the corpus, (3) one depth-investigator per locus writes an `interim-<locus>.md` note, (4) orchestrator writes ONE draft, (5) dialectic / depth / width critics return structured findings JSONs, (6) the patcher applies findings as Edit hunks, (7) the polish auditor cuts filler and strips hygiene leaks via more Edit hunks. Protocol lives at `.claude/skills/hyperresearch/SKILL.md`.
 - **Tool-locked patcher + polish auditor** — both agents register with tools `[Read, Edit]` ONLY. They physically cannot Write. Every hunk is capped at 500 chars of net expansion — any critic that proposes a larger patch escalates to the orchestrator instead of triggering a rewrite. This is the load-bearing invariant that enforces PATCH-NOT-REGEN at the tool level, not the prompt level.
 - **`NoteType.INTERIM`** — new first-class note type for depth-investigator outputs. Persisted in the vault with `type: interim` and tagged `locus-<name>` for indexability. Added to the SQLite CHECK constraint via migration v7.
 - **`locus-coverage` lint rule** — reads `research/loci.json` (Layer 2 output) and verifies every identified locus has a corresponding interim-report note. Missing interims flag as errors.
@@ -23,7 +71,7 @@ This release replaces the three-parallel-drafts-plus-merger ensemble design with
 
 - **`/research-ensemble` skill** — the three-parallel-sub-run ensemble protocol is gone. The slash command no longer registers.
 - **Retired subagents** — `hyperresearch-analyst`, `hyperresearch-auditor`, `hyperresearch-rewriter`, `hyperresearch-subrun`, `hyperresearch-merger` are no longer installed. On reinstall, any vault that had them gets them pruned automatically by `_prune_retired_agents()`.
-- **`analyst-coverage` lint rule** — superseded by `locus-coverage` (extracts were the ensemble era's per-source deep-read artifact; interim notes are the layercake equivalent scoped per locus).
+- **`analyst-coverage` lint rule** — superseded by `locus-coverage` (extracts were the ensemble era's per-source deep-read artifact; interim notes are the hyperresearch equivalent scoped per locus).
 
 ### New subagent roster (9 agents)
 

hyperresearch-0.8.3/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: hyperresearch
+Version: 0.8.3
+Summary: Claude Code harness for disciplined, adversarially-audited deep research with full provenance.
+Project-URL: Homepage, https://github.com/jordan-gibbs/hyperresearch
+Project-URL: Repository, https://github.com/jordan-gibbs/hyperresearch
+Project-URL: Issues, https://github.com/jordan-gibbs/hyperresearch/issues
+Author-email: Jordan Gibbs <jordan@jordangibbs.xyz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,cli,knowledge-base,llm,markdown,research,wiki,zettelkasten
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: <3.14,>=3.11
+Requires-Dist: crawl4ai>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pymupdf>=1.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.6; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.3; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.6; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/banner.png" alt="HYPERRESEARCH" width="700">
+</p>
+
+<h3 align="center">The Most Powerful Deep Research Harness</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/pyversions/hyperresearch" alt="Python 3.11+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/jordan-gibbs/hyperresearch" alt="License: MIT"></a>
+  <a href="https://github.com/jordan-gibbs/hyperresearch"><img src="https://img.shields.io/github/stars/jordan-gibbs/hyperresearch?style=social" alt="GitHub stars"></a>
+</p>
+
+---
+
+**Hyperresearch turns Claude Code into a deep research agent. and currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally).** A tier-adaptive 16-step pipeline produces adversarially-audited reports with full source provenance. Every fetched source lands in a persistent, searchable vault that compounds across sessions.
+
+<p align="center">
+  <img src="assets/benchmark.png" alt="DeepResearch-Bench top-5 — hyperresearch leads the chart ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research" width="780">
+</p>
+
+<p align="center"><sub>Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot (https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard). Third party validation is pending.</sub></p>
+
+## Install
+
+```bash
+cd your-project
+pip install hyperresearch && hyperresearch install
+```
+
+Then `/hyperresearch <anything>` in Claude Code.
+
+> Python 3.11–3.13. (3.14 not yet supported — use `pyenv install 3.13`, `uv venv -p 3.13`, or `py -3.13 -m venv .venv`.)
+>
+> Power users: `hyperresearch install --global` makes `/hyperresearch` reachable from every Claude Code session anywhere, at the cost of ~15 lines in every session's system reminder. Per-project install (above) keeps unrelated CC sessions clean.
+
+---
+
+## The 16-step research pipeline
+
+The entry skill is a thin router. It bootstraps the canonical research query, then invokes one step skill per pipeline phase via Claude Code's `Skill` tool. Each step's procedure is loaded fresh into context only when needed defeating context-rot problems that makes long pipelines silently drop steps.
+
+| # | Step | What it does | Tiers |
+|---|---|---|---|
+| 1 | Decompose | Canonical query → atomic items + coverage matrix + tier classification | both |
+| 2 | Width sweep | Multi-perspective search plan + parallel fetcher waves (Haiku) | both |
+| 3 | Contradiction graph | Pair contradictions across the corpus into ranked clusters | full |
+| 4 | Loci analysis | Two parallel loci-analysts → scored loci with source budgets | full |
+| 5 | Depth investigation | K parallel depth-investigators → interim notes with committed positions | full |
+| 6 | Cross-locus reconcile | Reconcile committed positions → comparisons.md | full |
+| 7 | Source tensions | Extract expert disagreements → source-tensions.json | full |
+| 8 | Corpus critic | "What source would overturn this?" + targeted gap-fill fetch | full |
+| 9 | Evidence digest | Top claims + verbatim quotes → evidence-digest.md | full |
+| 10 | Triple draft | Per-angle source curation + 3 parallel draft sub-orchestrators (light: single draft) | both |
+| 11 | Synthesize | Plan + outline + spawn synthesizer subagent → final_report.md | full |
+| 12 | Critics | 4 adversarial critics in parallel → findings JSONs | full |
+| 13 | Gap-fetch | Targeted fetch wave for critic-identified vault gaps | full |
+| 14 | Patcher | Surgical Edit hunks applied to draft (tool-locked Read+Edit) | full |
+| 15 | Polish | Hygiene + filler pass (tool-locked Read+Edit subagent) | both |
+| 16 | Readability audit | Recommender writes JSON suggestions; orchestrator selectively applies | both |
+
+### Depth Modes 
+
+In your prompt, you can request one of two tiers and the rest of the pipeline scales accordingly. Full mode is default.
+
+| Tier | Steps that run | Typical time |
+|---|---|---|
+| `light` | bounded factual queries, surveys, comparisons — 1 → 2 → 10 → 15 → 16 | ~30–40 min |
+| `full` | deep argumentative analysis with adversarial review — all 16 steps | ~1.5–2.5 hours |
+
+### The two load-bearing principles
+
+1. **Patch, never regenerate.** After step 11 produces the synthesized report (or step 10 for light tier), the only modifications are surgical Edit hunks. The patcher and polish auditor are tool-locked to `[Read, Edit]` at the Claude Code allowlist level so they physically cannot Write a new draft. Per-hunk caps make "just rewrite it" mechanically impossible. Critic findings that don't fit a small hunk escalate as structural issues.
+
+2. **Canonical research query is gospel.** The verbatim user prompt is persisted to `research/query-<vault_tag>.md` once and re-read by every subsequent step and every spawned subagent. Wrapper requirements (save paths, citation format, terminal sections) are a separate contract.
+
+### Subagent roster
+
+| Agent | Model | Role |
+|---|---|---|
+| `hyperresearch-fetcher` | Sonnet | URL fetching via crawl4ai; runs 8–12 in parallel per wave |
+| `hyperresearch-source-analyst` | Sonnet (1M ctx) | End-to-end digest of any single long source >5000 words |
+| `hyperresearch-loci-analyst` | Sonnet | Reads the width corpus, returns 1–8 depth loci with rationale |
+| `hyperresearch-depth-investigator` | Sonnet | Investigates one locus, writes one interim note with a committed position |
+| `hyperresearch-corpus-critic` | Sonnet | "What source would overturn the current direction?" pre-draft gap analysis |
+| `hyperresearch-draft-orchestrator` | Opus | One per draft angle; reads its curated source list and writes one draft |
+| `hyperresearch-synthesizer` | Opus | Reads all 3 drafts, writes the final report (two-pass write, Read+Write locked) |
+| `hyperresearch-dialectic-critic` | Opus | Counter-evidence the draft missed |
+| `hyperresearch-depth-critic` | Opus | Shallow spots interim notes could fill |
+| `hyperresearch-width-critic` | Opus | Topical corners the corpus supports but the draft ignores |
+| `hyperresearch-instruction-critic` | Opus | Structural mismatches against the prompt's atomic items |
+| `hyperresearch-patcher` | Opus | Tool-locked `[Read, Edit]`. Applies critic findings as surgical Edit hunks |
+| `hyperresearch-polish-auditor` | Opus | Tool-locked `[Read, Edit]`. Cuts filler, strips hygiene leaks |
+| `hyperresearch-readability-recommender` | Opus | Writes JSON suggestions for paragraph rhythm and list/table conversion |
+
+---
+
+## The vault: persistent, searchable, compounding
+
+Hyperresearch is not a one-shot report generator like most other Deep research harnesses. Every fetched source lands in a SQLite-indexed vault that every future research session can reuse.
+
+```bash
+hyperresearch search "ion-trap gate fidelity" -j           # Full-text search
+hyperresearch search "quantum" --include-body -j           # Full-body search
+hyperresearch note show <id1> <id2> <id3> -j               # Batch-read notes
+hyperresearch graph hubs -j                                # Most-connected notes
+hyperresearch graph backlinks <id> -j                      # Reverse links
+hyperresearch lint -j                                      # Health check (broken links, missing tags)
+```
+
+**Markdown is truth, SQLite is cache.** Notes live as plain markdown with YAML frontmatter in `research/notes/`. The SQLite index is fully rebuildable. Delete it and `hyperresearch sync` reconstructs it from the markdown. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed.
+
+**PDFs fetch directly.** `hyperresearch fetch` auto-detects PDF URLs (arXiv, NBER, SSRN, direct `.pdf` links) and extracts full text via pymupdf. Raw PDFs land in `research/raw/<note-id>.pdf` and the note's `raw_file:` frontmatter links back.
+
+**Provenance breadcrumbs.** Every fetched source carries a `--suggested-by` link back to whatever surfaced it. The chain forms a rooted tree from seed fetches; the `provenance` lint rule catches disconnected components.
+
+---
+
+## What's structurally enforced
+
+- **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks if the scaffold doesn't open with the user's exact prompt
+- **Locus coverage** — every step 4 locus must have a step 5 interim note; missing interims flag as errors
+- **Patch-only modification** — steps 14, 15, 16 are tool-locked to `[Read, Edit]`. They cannot regenerate the draft
+- **Critical findings never silently skip** — `patch-surgery` lint surfaces any critical finding the patcher couldn't apply
+- **Schema integrity** — `tier`, `content_type`, and `type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
+- **Hygiene leaks caught on the way out** — scaffold sections, YAML frontmatter, and prompt echoes are stripped by step 15 before ship
+
+---
+
+## Authenticated crawling
+
+Fetch from LinkedIn, Twitter, paywalled sites or anything you can log into:
+
+```bash
+hyperresearch setup       # Browser opens. Log into your sites. Done.
+```
+
+LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills.
+
+---
+
+## Academic APIs before web search
+
+For any topic with a research literature, hit academic APIs BEFORE web search. They return citation-ranked canonical papers; web search returns derivative commentary.
+
+- **Semantic Scholar** — `https://api.semanticscholar.org/graph/v1/paper/search`
+- **arXiv** — `https://export.arxiv.org/api/query`
+- **OpenAlex** — `https://api.openalex.org/works`
+- **PubMed** — `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`
+
+After the academic sweep, run web searches for context, news, non-academic angles, and at least one adversarial search ("criticism of X", "limitations of X").
+
+---
+
+## What it doesn't do
+
+- It doesn't replace your judgment on which sources matter. The agent picks, you steer.
+- It can't fetch what's behind a paywall you haven't logged into.
+- It runs on Anthropic models Opus + Sonnet + Haiku via the subagent roster. Costs scale with tier and corpus size. If anyone wants to port this to Codex, put up a PR! 
+- The lint gate catches **structural** failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy, that's still your call.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude Code](https://claude.com/claude-code)
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=jordan-gibbs/hyperresearch&type=Date)](https://star-history.com/#jordan-gibbs/hyperresearch&Date)

hyperresearch-0.8.3/README.md

@@ -0,0 +1,179 @@
+<p align="center">
+  <img src="assets/banner.png" alt="HYPERRESEARCH" width="700">
+</p>
+
+<h3 align="center">The Most Powerful Deep Research Harness</h3>
+
+<p align="center">
+  <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/v/hyperresearch" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/hyperresearch/"><img src="https://img.shields.io/pypi/pyversions/hyperresearch" alt="Python 3.11+"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/jordan-gibbs/hyperresearch" alt="License: MIT"></a>
+  <a href="https://github.com/jordan-gibbs/hyperresearch"><img src="https://img.shields.io/github/stars/jordan-gibbs/hyperresearch?style=social" alt="GitHub stars"></a>
+</p>
+
+---
+
+**Hyperresearch turns Claude Code into a deep research agent. and currently leads the DeepResearch-Bench RACE leaderboard (benchmarked internally).** A tier-adaptive 16-step pipeline produces adversarially-audited reports with full source provenance. Every fetched source lands in a persistent, searchable vault that compounds across sessions.
+
+<p align="center">
+  <img src="assets/benchmark.png" alt="DeepResearch-Bench top-5 — hyperresearch leads the chart ahead of Grep Deep Research, Cellcog Max, nvidia-aiq, Gemini Deep Research, and OpenAI Deep Research" width="780">
+</p>
+
+<p align="center"><sub>Forward-looking projection from a stratified pilot against the DeepResearch-Bench leaderboard snapshot (https://huggingface.co/spaces/muset-ai/DeepResearch-Bench-Leaderboard). Third party validation is pending.</sub></p>
+
+## Install
+
+```bash
+cd your-project
+pip install hyperresearch && hyperresearch install
+```
+
+Then `/hyperresearch <anything>` in Claude Code.
+
+> Python 3.11–3.13. (3.14 not yet supported — use `pyenv install 3.13`, `uv venv -p 3.13`, or `py -3.13 -m venv .venv`.)
+>
+> Power users: `hyperresearch install --global` makes `/hyperresearch` reachable from every Claude Code session anywhere, at the cost of ~15 lines in every session's system reminder. Per-project install (above) keeps unrelated CC sessions clean.
+
+---
+
+## The 16-step research pipeline
+
+The entry skill is a thin router. It bootstraps the canonical research query, then invokes one step skill per pipeline phase via Claude Code's `Skill` tool. Each step's procedure is loaded fresh into context only when needed defeating context-rot problems that makes long pipelines silently drop steps.
+
+| # | Step | What it does | Tiers |
+|---|---|---|---|
+| 1 | Decompose | Canonical query → atomic items + coverage matrix + tier classification | both |
+| 2 | Width sweep | Multi-perspective search plan + parallel fetcher waves (Haiku) | both |
+| 3 | Contradiction graph | Pair contradictions across the corpus into ranked clusters | full |
+| 4 | Loci analysis | Two parallel loci-analysts → scored loci with source budgets | full |
+| 5 | Depth investigation | K parallel depth-investigators → interim notes with committed positions | full |
+| 6 | Cross-locus reconcile | Reconcile committed positions → comparisons.md | full |
+| 7 | Source tensions | Extract expert disagreements → source-tensions.json | full |
+| 8 | Corpus critic | "What source would overturn this?" + targeted gap-fill fetch | full |
+| 9 | Evidence digest | Top claims + verbatim quotes → evidence-digest.md | full |
+| 10 | Triple draft | Per-angle source curation + 3 parallel draft sub-orchestrators (light: single draft) | both |
+| 11 | Synthesize | Plan + outline + spawn synthesizer subagent → final_report.md | full |
+| 12 | Critics | 4 adversarial critics in parallel → findings JSONs | full |
+| 13 | Gap-fetch | Targeted fetch wave for critic-identified vault gaps | full |
+| 14 | Patcher | Surgical Edit hunks applied to draft (tool-locked Read+Edit) | full |
+| 15 | Polish | Hygiene + filler pass (tool-locked Read+Edit subagent) | both |
+| 16 | Readability audit | Recommender writes JSON suggestions; orchestrator selectively applies | both |
+
+### Depth Modes 
+
+In your prompt, you can request one of two tiers and the rest of the pipeline scales accordingly. Full mode is default.
+
+| Tier | Steps that run | Typical time |
+|---|---|---|
+| `light` | bounded factual queries, surveys, comparisons — 1 → 2 → 10 → 15 → 16 | ~30–40 min |
+| `full` | deep argumentative analysis with adversarial review — all 16 steps | ~1.5–2.5 hours |
+
+### The two load-bearing principles
+
+1. **Patch, never regenerate.** After step 11 produces the synthesized report (or step 10 for light tier), the only modifications are surgical Edit hunks. The patcher and polish auditor are tool-locked to `[Read, Edit]` at the Claude Code allowlist level so they physically cannot Write a new draft. Per-hunk caps make "just rewrite it" mechanically impossible. Critic findings that don't fit a small hunk escalate as structural issues.
+
+2. **Canonical research query is gospel.** The verbatim user prompt is persisted to `research/query-<vault_tag>.md` once and re-read by every subsequent step and every spawned subagent. Wrapper requirements (save paths, citation format, terminal sections) are a separate contract.
+
+### Subagent roster
+
+| Agent | Model | Role |
+|---|---|---|
+| `hyperresearch-fetcher` | Sonnet | URL fetching via crawl4ai; runs 8–12 in parallel per wave |
+| `hyperresearch-source-analyst` | Sonnet (1M ctx) | End-to-end digest of any single long source >5000 words |
+| `hyperresearch-loci-analyst` | Sonnet | Reads the width corpus, returns 1–8 depth loci with rationale |
+| `hyperresearch-depth-investigator` | Sonnet | Investigates one locus, writes one interim note with a committed position |
+| `hyperresearch-corpus-critic` | Sonnet | "What source would overturn the current direction?" pre-draft gap analysis |
+| `hyperresearch-draft-orchestrator` | Opus | One per draft angle; reads its curated source list and writes one draft |
+| `hyperresearch-synthesizer` | Opus | Reads all 3 drafts, writes the final report (two-pass write, Read+Write locked) |
+| `hyperresearch-dialectic-critic` | Opus | Counter-evidence the draft missed |
+| `hyperresearch-depth-critic` | Opus | Shallow spots interim notes could fill |
+| `hyperresearch-width-critic` | Opus | Topical corners the corpus supports but the draft ignores |
+| `hyperresearch-instruction-critic` | Opus | Structural mismatches against the prompt's atomic items |
+| `hyperresearch-patcher` | Opus | Tool-locked `[Read, Edit]`. Applies critic findings as surgical Edit hunks |
+| `hyperresearch-polish-auditor` | Opus | Tool-locked `[Read, Edit]`. Cuts filler, strips hygiene leaks |
+| `hyperresearch-readability-recommender` | Opus | Writes JSON suggestions for paragraph rhythm and list/table conversion |
+
+---
+
+## The vault: persistent, searchable, compounding
+
+Hyperresearch is not a one-shot report generator like most other Deep research harnesses. Every fetched source lands in a SQLite-indexed vault that every future research session can reuse.
+
+```bash
+hyperresearch search "ion-trap gate fidelity" -j           # Full-text search
+hyperresearch search "quantum" --include-body -j           # Full-body search
+hyperresearch note show <id1> <id2> <id3> -j               # Batch-read notes
+hyperresearch graph hubs -j                                # Most-connected notes
+hyperresearch graph backlinks <id> -j                      # Reverse links
+hyperresearch lint -j                                      # Health check (broken links, missing tags)
+```
+
+**Markdown is truth, SQLite is cache.** Notes live as plain markdown with YAML frontmatter in `research/notes/`. The SQLite index is fully rebuildable. Delete it and `hyperresearch sync` reconstructs it from the markdown. The vault is inspectable in any editor, version-controllable in git, and readable without the tool installed.
+
+**PDFs fetch directly.** `hyperresearch fetch` auto-detects PDF URLs (arXiv, NBER, SSRN, direct `.pdf` links) and extracts full text via pymupdf. Raw PDFs land in `research/raw/<note-id>.pdf` and the note's `raw_file:` frontmatter links back.
+
+**Provenance breadcrumbs.** Every fetched source carries a `--suggested-by` link back to whatever surfaced it. The chain forms a rooted tree from seed fetches; the `provenance` lint rule catches disconnected components.
+
+---
+
+## What's structurally enforced
+
+- **Verbatim prompt as gospel** — `scaffold-prompt` lint blocks if the scaffold doesn't open with the user's exact prompt
+- **Locus coverage** — every step 4 locus must have a step 5 interim note; missing interims flag as errors
+- **Patch-only modification** — steps 14, 15, 16 are tool-locked to `[Read, Edit]`. They cannot regenerate the draft
+- **Critical findings never silently skip** — `patch-surgery` lint surfaces any critical finding the patcher couldn't apply
+- **Schema integrity** — `tier`, `content_type`, and `type` are SQLite CHECK-constrained vocabularies; corrupted frontmatter cannot poison the index
+- **Hygiene leaks caught on the way out** — scaffold sections, YAML frontmatter, and prompt echoes are stripped by step 15 before ship
+
+---
+
+## Authenticated crawling
+
+Fetch from LinkedIn, Twitter, paywalled sites or anything you can log into:
+
+```bash
+hyperresearch setup       # Browser opens. Log into your sites. Done.
+```
+
+LinkedIn, Twitter, Facebook, Instagram, and TikTok automatically use a visible browser to avoid session kills.
+
+---
+
+## Academic APIs before web search
+
+For any topic with a research literature, hit academic APIs BEFORE web search. They return citation-ranked canonical papers; web search returns derivative commentary.
+
+- **Semantic Scholar** — `https://api.semanticscholar.org/graph/v1/paper/search`
+- **arXiv** — `https://export.arxiv.org/api/query`
+- **OpenAlex** — `https://api.openalex.org/works`
+- **PubMed** — `https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi`
+
+After the academic sweep, run web searches for context, news, non-academic angles, and at least one adversarial search ("criticism of X", "limitations of X").
+
+---
+
+## What it doesn't do
+
+- It doesn't replace your judgment on which sources matter. The agent picks, you steer.
+- It can't fetch what's behind a paywall you haven't logged into.
+- It runs on Anthropic models Opus + Sonnet + Haiku via the subagent roster. Costs scale with tier and corpus size. If anyone wants to port this to Codex, put up a PR! 
+- The lint gate catches **structural** failures (missing scaffold, broken provenance, unresolved CRITICALs). It cannot guarantee factual accuracy, that's still your call.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude Code](https://claude.com/claude-code)
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=jordan-gibbs/hyperresearch&type=Date)](https://star-history.com/#jordan-gibbs/hyperresearch&Date)

hyperresearch-0.8.3/assets/_generate_banner.py

@@ -0,0 +1,71 @@
+"""Generate banner.png (README inline) and banner_social.png (GitHub social preview).
+
+Source: assets/_banner_src.png — the pixel-art HYPERRESEARCH wordmark at its
+authored 584x250 resolution. Both output files are derived from it; never
+edit the outputs directly.
+
+- banner.png — 3x nearest-neighbor upscale of the source (1752x750). The
+  README references this and renders it at width=700, so the browser
+  downscales (crisp) instead of upscaling (blurry).
+- banner_social.png — wordmark on a 1280x640 dark canvas matching the
+  benchmark chart's background, wordmark filling 92% of the canvas width.
+  Upload at repo Settings → Social preview.
+
+Re-run when the source wordmark changes:
+    python assets/_generate_banner.py
+"""
+
+from pathlib import Path
+
+from PIL import Image
+
+ASSETS = Path(__file__).parent
+SRC = ASSETS / "_banner_src.png"
+README_OUT = ASSETS / "banner.png"
+SOCIAL_OUT = ASSETS / "banner_social.png"
+
+# Match the chart's dark background so README header + chart + social
+# preview share one visual treatment.
+BG = (14, 17, 22, 255)  # #0E1116
+SOCIAL_W, SOCIAL_H = 1280, 640
+README_SCALE = 3  # 584x250 → 1752x750
+
+src = Image.open(SRC).convert("RGBA")
+
+# --- README banner: pure 3x nearest-neighbor upscale, no canvas -----------
+readme_img = src.resize(
+    (src.width * README_SCALE, src.height * README_SCALE),
+    Image.NEAREST,
+)
+readme_img.convert("RGB").save(README_OUT, "PNG", optimize=True)
+print(f"wrote {README_OUT.name}  ({readme_img.width}x{readme_img.height})")
+
+# --- Social preview: wordmark on dark canvas at GitHub's required 1280x640
+# Start from the same source, upscale 2x for a base, then resize to fit.
+social_word = src.resize((src.width * 2, src.height * 2), Image.NEAREST)
+
+# Wordmark should DOMINATE the social card. Fill ~92% width.
+max_w = int(SOCIAL_W * 0.92)
+if social_word.width != max_w:
+    ratio = max_w / social_word.width
+    social_word = social_word.resize(
+        (max_w, int(social_word.height * ratio)),
+        Image.NEAREST,
+    )
+
+# Defensive height cap (source aspect 2.34:1 means width typically constrains)
+max_h = int(SOCIAL_H * 0.88)
+if social_word.height > max_h:
+    ratio = max_h / social_word.height
+    social_word = social_word.resize(
+        (int(social_word.width * ratio), max_h),
+        Image.NEAREST,
+    )
+
+# Compose onto target canvas, centered
+canvas = Image.new("RGBA", (SOCIAL_W, SOCIAL_H), BG)
+x = (SOCIAL_W - social_word.width) // 2
+y = (SOCIAL_H - social_word.height) // 2
+canvas.paste(social_word, (x, y), social_word)
+canvas.convert("RGB").save(SOCIAL_OUT, "PNG", optimize=True)
+print(f"wrote {SOCIAL_OUT.name}  ({SOCIAL_W}x{SOCIAL_H})")