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

> Master report voice in Hyperresearch by configuring run levers. Learn how the register lever controls narrative tone across four modes with this complete guide.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**You control report voice in Hyperresearch by configuring "run levers" in [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json) that determine how Hyperresearch agents interpret and execute research tasks. According to the source code in [`src/hyperresearch/core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/research.md), [`drafting.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/drafting.md), [`critics.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/critics.md), and [`polish.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/levers_cmd.py) provides direct commands for inspecting and modifying voice settings.

Render the current levers for a specific run:

```bash
hpr levers render my-run --json

```

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

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

```

Switch the inference depth to **Deep** for more exhaustive research:

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

```

Combine multiple levers in a single command:

```bash
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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/runs.py) validates these settings during run initialization.

```python
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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/research.md), [`drafting.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/drafting.md), [`critics.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/critics.md), [`polish.md`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json)** file under the `"levers"` block. The [`src/hyperresearch/core/runs.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/core/runs.py) module manages integration of these settings into the run manifest, while [`src/hyperresearch/core/levers.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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.