# How to Define or Override Research Profiles in Hyperresearch

> Learn to define or override research profiles in Hyperresearch by customizing your config.toml file. Control research depth and agent behavior with simple configuration.

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

---

**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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```toml

# ~/.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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```toml

# ~/.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):

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

```

In [`src/hyperresearch/core/render.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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:

```bash
hpr profile list

```

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

```bash
hpr profile show dissertation -j

```

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

```json
{
  "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:

```python
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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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`](https://github.com/jordan-gibbs/hyperresearch/blob/main/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.