How to Define or Override Research Profiles in Hyperresearch

Define or override research profiles in Hyperresearch by creating [profile.<name>] sections in your ~/.hyperresearch/config.toml file, utilizing the extends key to inherit from built-in profiles like full or light, and customizing parameters such as source_min, loci_max, and per-agent models to control research depth and agent behavior.

The open-source jordan-gibbs/hyperresearch framework orchestrates complex AI research pipelines through configurable profiles that govern everything from source collection to draft generation. Understanding how to define or override research profiles in Hyperresearch allows you to fine-tune the pipeline's aggressiveness, cost, and quality to match specific research tasks, from quick summaries to comprehensive dissertations.

Understanding Hyperresearch Pipeline Profiles

Hyperresearch encapsulates every tunable parameter of the research pipeline—source-count gates, fetcher fan-out, locus caps, depth budgets, and draft counts—into pipeline profiles. The framework ships with four built-in profiles (light, full, premier, dissertation) defined in src/hyperresearch/core/profiles.py, each representing a different trade-off between computational cost and research thoroughness.

These profiles control how many sources the system must gather before proceeding (source_min), the maximum number of research loci to explore (loci_max), and which AI models power specific agents in the pipeline.

Where Profiles Are Defined and Stored

Built-in Profile Defaults

The core profile logic and default definitions reside in src/hyperresearch/core/profiles.py. This module handles profile parsing, inheritance resolution, and Pydantic validation. The built-in profiles provide baseline configurations that users can extend or override without modifying source code.

User Configuration Location

Users define custom profiles or override existing ones in ~/.hyperresearch/config.toml (or any TOML file passed via CLI). The runtime merges user-defined [profile.<name>] sections with built-in defaults, with user configurations taking precedence.

Overriding Built-in Research Profiles

To modify an existing profile like full without creating a new one, add a section with the same name to your config file:

# ~/.hyperresearch/config.toml

[profile.full]
source_min = 60

This configuration preserves all other full profile settings while increasing the minimum source requirement to 60. The src/hyperresearch/core/profiles.py module validates these overrides at load time, rejecting unknown keys and raising errors for empty string values.

Creating Custom Research Profiles

Extending Existing Profiles with Inheritance

Rather than duplicating entire profile definitions, use the extends key to inherit from a base profile and override only specific fields. This approach keeps configurations DRY and makes maintenance easier:

# ~/.hyperresearch/config.toml

[profile.dissertation]
extends = "full"
source_min = 250
loci_max = 20

Here, the dissertation profile inherits all settings from full but increases the source minimum to 250 and caps loci at 20, creating a more exhaustive research configuration suitable for academic work.

Configuring Per-Agent Model Assignments

Profiles can specify which AI models individual agents use via the models mapping. This allows cost optimization (e.g., using lighter models for fetchers) or quality maximization (e.g., using premium models for orchestration):

[profile.premier]
models = { fetcher = "haiku", draft_orchestrator = "opus" }

In src/hyperresearch/core/render.py, these model assignments affect how prompts are constructed for installed agents, ensuring each pipeline component uses its designated model at runtime.

Inspecting and Validating Profiles

Hyperresearch provides CLI tools to verify your configurations before running expensive research jobs.

To list all available profiles:

hpr profile list

To view the fully resolved profile (including inherited values):

hpr profile show dissertation -j

This outputs JSON showing the merged configuration, confirming that your overrides applied correctly:

{
  "name": "dissertation",
  "extends": "full",
  "source_min": 250,
  "loci_max": 20,
  "models": {
    "fetcher": "haiku",
    "draft_orchestrator": "opus"
  }
}

Programmatic Profile Access

For custom scripts or extensions, access resolved profiles programmatically via the resolve_profile function:

from hyperresearch.core.profiles import resolve_profile

dissertation = resolve_profile("dissertation")
print(dissertation.source_min)          # → 250

print(dissertation.models.fetcher)      # → "haiku"

This function returns a Pydantic-validated object containing all profile fields, ready for use in agent initialization or prompt rendering logic.

How Profiles Impact the Research Pipeline

Profile configurations affect the pipeline at two critical consumption points in the src/hyperresearch/core/ module:

• Prompt Rendering: src/hyperresearch/core/render.py uses profile values when constructing prompt front-matter for installed agents, ensuring consistency between configuration and LLM instructions.
• Runtime Execution: Agents read the resolved profile when they need numeric thresholds (like source_min or depth budgets) to make routing decisions during the research process.

Summary

• Define custom profiles by adding [profile.<name>] sections to ~/.hyperresearch/config.toml.
• Override built-in profiles (light, full, premier, dissertation) by using the same profile name in your user config.
• Use extends = "<base-profile>" to inherit settings and avoid duplication.
• Configure per-agent models via the models map to optimize cost and quality.
• Validate configurations using hpr profile show <name> and access them programmatically via resolve_profile().
• Profile settings flow through src/hyperresearch/core/render.py into prompts and guide agent behavior at runtime.

Frequently Asked Questions

Where are the built-in profile definitions stored in Hyperresearch?

The built-in profiles (light, full, premier, dissertation) are defined in src/hyperresearch/core/profiles.py, which also handles profile inheritance resolution and Pydantic validation for all configuration files.

Can I use multiple config files or specify a custom location for profiles?

Yes. While the default location is ~/.hyperresearch/config.toml, you can pass any TOML file path to the CLI. The profile resolution system loads these files and merges them with the built-in definitions from src/hyperresearch/core/profiles.py.

What happens if I specify an invalid profile key or empty value?

Hyperresearch uses Pydantic for strict validation. Unknown keys in a profile section are rejected with a validation error, and empty string values raise specific validation exceptions to prevent misconfigured pipelines from executing.

How do I check which models are assigned to specific agents in my custom profile?

Run hpr profile show <profile-name> -j to output the fully resolved profile as JSON. This displays the models mapping, showing which LLM powers each agent (e.g., fetcher, draft_orchestrator) according to your configuration.

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