How to Set Report Voice in Hyperresearch: A Complete Guide to Run Levers

You control report voice in Hyperresearch by configuring "run levers" in prompt-decomposition.json, specifically the register lever which sets the narrative tone across four distinct modes.

Hyperresearch provides a flexible system for steering the tone, depth, and rhetorical stance of generated reports through configurable run levers. These settings live in each run's prompt-decomposition.json under the "levers" block and directly influence the four role-specific shim files that guide the downstream research agents. Understanding how to manipulate these levers allows you to shift the report voice from patient expert guidance to persuasive advocacy without rewriting core prompts.

Understanding Run Levers for Voice Control

Run levers act as high-level dials stored in prompt-decomposition.json that determine how Hyperresearch agents interpret and execute research tasks. According to the source code in src/hyperresearch/core/levers.py, these levers define enums, validation rules, and the composition logic that generates shim files.

When you initialize or modify a run, Hyperresearch reads these levers to automatically configure the behavior of the research pipeline. The system then embeds your selected voice parameters into four critical shim files: research.md, drafting.md, critics.md, and polish.md.

The Primary Voice Lever: Register

The register lever serves as the primary mechanism for changing report voice. Defined in src/hyperresearch/core/levers.py (lines 27‑30), this lever accepts four distinct options that dictate the overall narrative tone:

• teach – Adopts a patient-expert voice, guiding readers through concepts with instructional clarity.
• survey – Employs a neutral-cartographer tone, mapping the landscape without heavy editorializing.
• analyze – Uses an evaluative voice that critically assesses evidence and competing claims.
• advocate – Drives a thesis-forward, persuasive voice that argues for a specific position.

Each register selection injects specific wording into the shim files. For example, selecting teach adds "Voice: patient expert" to the agent instructions, fundamentally altering how the system presents findings compared to the advocate register.

Supporting Levers That Shape Output

While register controls the primary voice, three additional levers fine-tune the report's character and depth.

Inference Depth

The inference_depth lever (lines 28‑29 in src/hyperresearch/core/levers.py) controls how aggressively the system seeks evidence and synthesizes findings:

• surface – Quick, high-level scanning of sources.
• standard – Balanced research depth suitable for most reports.
• deep – Exhaustive evidence gathering with extensive synthesis.

Though not a voice setting per se, the depth level influences the argumentative density and thoroughness of the final report.

Register Confidence

The optional register_confidence lever accepts high or low to adjust how certain the system should sound when presenting the chosen register. This affects hedging language and epistemic markers throughout the text.

Domain Notes

The domain_notes lever accepts free-form text that all shim files inherit. Use this to inject brief, domain-specific guidance that shapes terminology and conceptual framing without changing the base register.

How Levers Compose the Shim Files

When you set a lever, Hyperresearch automatically regenerates the four role-scoped shim files located in your run directory. The composition logic in src/hyperresearch/core/levers.py embeds the selected register's wording and inference depth guidance directly into these files:

1. research.md – Guides source discovery and evidence extraction.
2. drafting.md – Controls initial content generation and structural flow.
3. critics.md – Sets the tone for internal review and quality checks.
4. polish.md – Determines final editing standards and stylistic consistency.

This architecture ensures that voice settings propagate consistently across the entire research pipeline, from initial query to final output.

Setting and Reading Levers via CLI

The CLI interface in src/hyperresearch/cli/levers_cmd.py provides direct commands for inspecting and modifying voice settings.

Render the current levers for a specific run:

hpr levers render my-run --json

Set the report voice to Teach (patient-expert tone) and regenerate the shims:

hpr levers set my-run register=teach --rerender

Switch the inference depth to Deep for more exhaustive research:

hpr levers set my-run inference_depth=deep --rerender

Combine multiple levers in a single command:

hpr levers set my-run register=advocate inference_depth=surface --rerender

Programmatic Access to Voice Settings

For automation and integration workflows, access levers programmatically using the core library. The integration logic in src/hyperresearch/core/runs.py validates these settings during run initialization.

from hyperresearch.core.levers import read_levers

levers = read_levers(vault, "my-run")
print(levers)   

# Output: {'register': 'advocate', 'inference_depth': 'surface', ...}

This approach allows you to dynamically adjust report voice based on external conditions or user preferences before triggering the research pipeline.

Summary

• Run levers stored in prompt-decomposition.json control report voice and research depth across all Hyperresearch agents.
• The register lever (teach, survey, analyze, advocate) provides the primary voice configuration, as defined in src/hyperresearch/core/levers.py lines 27‑30.
• inference_depth (surface, standard, deep) determines research thoroughness and argumentative density.
• Optional levers register_confidence and domain_notes offer fine-grained control over certainty levels and domain-specific terminology.
• Changes trigger automatic regeneration of the four shim files (research.md, drafting.md, critics.md, polish.md) to ensure consistent voice application.

Frequently Asked Questions

What is the difference between register and inference_depth in Hyperresearch?

The register lever controls the rhetorical voice and narrative tone of the final report—whether it teaches, surveys, analyzes, or advocates. The inference_depth lever controls the research process intensity—how thoroughly the system searches for and synthesizes evidence. While register shapes how the report sounds to readers, inference_depth determines how much evidence supports that voice.

How do I make my Hyperresearch report sound more authoritative versus neutral?

Set register=advocate to generate an authoritative, thesis-driven voice that argues positions forcefully. For a neutral, descriptive tone, use register=survey, which configures the system to act as a "neutral cartographer" mapping the field without heavy editorializing. You can further adjust certainty markers using register_confidence=high for more definitive statements or low for cautious, qualified claims.

Where does Hyperresearch store my voice settings after I set them?

Voice settings persist in the run's prompt-decomposition.json file under the "levers" block. The src/hyperresearch/core/runs.py module manages integration of these settings into the run manifest, while src/hyperresearch/core/levers.py handles validation and the composition of shim files that embed these voice parameters into agent instructions.

Can I change the report voice after the research has already started?

Yes. Use the hpr levers set command with the --rerender flag to update voice settings and regenerate the shim files at any point. However, changing the register mid-process primarily affects subsequent agent interactions and final drafting stages. For consistent voice throughout, configure levers before initiating the research phase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}