hyperresearch

Phase 0 is a structural cleanup phase designed to remove technical debt before implementing new features. The primary goals are to move agent prompts from Python constants to markdown files, unify the fetch engine, and remove dead code.

Key outcomes for developers:

• Prompts: Agent prompts are now stored as .md files with YAML frontmatter in src/hyperresearch/agents/ instead of being trapped in core/hooks.py.
• Fetch Engine: There is now a single, unified fetch engine located in core/fetcher.py. Both the CLI and MCP server route through this core engine.
• Vocabulary: The project has transitioned from 'Layer N' terminology to the 'V8 16-step pipeline' (e.g., 'step N').
• Retirements: The hyperresearch research command is retired; users should use the /hyperresearch command instead. Certain legacy modules like models/graph.py and models/search.py have been removed.

To resolve failures in trajectory planning (such as the Policy Bifurcation problem where continuous policies cannot span different homotopy classes), use one or a combination of these four architectural escapes:

1. Multi-modal proposer: Enumerates discrete homotopy classes (e.g., a vehicle choosing to go 'left' or 'right' around an obstacle). Examples include MUPO (Gaussian mixture) or diffusion planners.
2. Geometric projector: Refines candidates onto the constraint manifold (e.g., ATACOM, CBF-QP, or Safety Layers for joint limits and obstacle distance).
3. Runtime filter: Provides per-step safety for online stochasticity (e.g., CBF-QP or RMPS shielding).
4. External topological decomposition: A separate planner (like Topological Path Search) enumerates homotopy classes, and a continuous-policy RL agent optimizes within the chosen corridor (e.g., RLTT).

Pipeline profiles allow you to control the scale and depth of a research run by adjusting a single set of parameters. Profiles are defined in .hyperresearch/config.toml under the [profile.<name>] section.

Built-in Profiles

• light: A lightweight research tier (steps [1,2,10,15,16]) designed for speed and lower resource usage.
• full: The standard high-depth research tier (all 16 steps) that uses the full suite of agents and skills.

Profile Structure

A profile consists of two main parts:

1. Parameters: A flat set of values governing research scale (e.g., source_min, planned_searches, batch_size, word_targets).
2. Model Map: A mapping that assigns specific LLM models to different agent roles (e.g., fetcher = "sonnet", synthesizer = "opus").

CLI Commands for Profiles

Use the hpr CLI to manage profiles:

• hpr profile list: List available profiles.
• hpr profile show <name> -j: Show the resolved parameters for a specific profile in JSON format.
• hpr profile validate: Validate your profile configuration against the schema.

[profile.full]
steps = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]
source_min = 45
source_target_low = 55
source_target_high = 80
planned_searches = [40, 100]
candidate_urls = [80, 120]
batch_size = [8, 12]
wave1_fetchers = [10, 12]
adversarial_searches_min = 5
utility_scoring = true
source_analyst_cap = 6
source_analyst_word_trigger = 5000
loci_analysts = 2
loci_max = 6
depth_budget_total = 40
depth_budget_brackets = [[30, 15], [20, 10], [10, 5], [0, 3]]
investigator_max = 6
comparisons_tensions = [3, 5]
source_tensions = [3, 7]
tension_full_reads = [8, 12]
corpus_critic_gaps = [3, 8]
claims_cap = [80, 120]
claims_min = 30
draft_count = 3
must_read = { argumentative = [35, 50], structured = [25, 40], short = [20, 30] }
word_targets = { short = [500, 2000], structured = [2000, 5000], argumentative = [5000, 10000] }
citation_density_min = 2.0
critic_finding_caps = { dialectic = 12, depth = 12, width = 10, instruction = 15 }
gap_fetch_cap = 5
readability_rec_cap = 50
vault_check_interval_s = 60
wave_done_ratio = 0.8

[profile.full.models]
fetcher = "sonnet"
source_analyst = "sonnet"
loci_analyst = "sonnet"
depth_investigator = "sonnet"
corpus_critic = "sonnet"
draft_orchestrator = "opus"
synthesizer = "opus"
critics = "opus"
patcher = "opus"
polish_auditor = "opus"
readability_recommender = "opus"

The quality_score is a composite metric used to rank sources during retrieval. It is computed during sync/score time using the following components and weights (configurable via [ranking]):

• Tier Weight (w_tier): Based on the note's tier (e.g., ground_truth = 1.0, commentary = 0.4).
• Utility Score (w_util): Derived from the step-2 fetch utility (normalized 0–18).
• Authority Score (w_auth): Derived from citation counts (normalized within the vault).
• Centrality Score (w_cent): Derived from vault PageRank.
• Retraction Penalty: If is_retracted is true, the quality_score is hard-set to 0.05.

Default Weights:

• tier: 0.35
• utility: 0.2
• authority: 0.25
• centrality: 0.2

If any component is missing (e.g., a non-academic source missing an authority score), the remaining components are re-normalized rather than zeroing out the total score.

When reviewing research/runs/<vault_tag>/readability-recommendations.json, use the following heuristics to decide which changes to apply via the Edit tool:

Hyperresearch can generate high-fidelity research reports by running a full 16-step pipeline. This process involves:

1. Data Fetching & Indexing: Fetching and indexing academic sources (e.g., from Semantic Scholar, arXiv, OpenAlex).
2. Loci-Analysis: Running parallel analysts to identify dialectical questions where evidence forks.
3. Depth Investigation: Spawning multiple depth-investigators that commit to specific positions.
4. Reconciliation: Reconciling positions into a 'tensions document'.
5. Parallel Drafting: Drafting multiple angle-specific reports in parallel.
6. Synthesis: Synthesizing the drafted reports.
7. Adversarial Criticism: Running multiple adversarial critics (e.g., Opus critics).
8. Surgical Editing: Applying findings via a 'Read+Edit-locked patcher'.
9. Hygiene & Readability: Final passes for quality control.

Reports generated this way include inline citations [N] and a ## Sources section. Performance is measured using benchmarks like DeepResearch-Bench RACE.