# Benchmarking System

The Local Deep Research benchmarking system evaluates search configurations, models, and strategies using standardized datasets to help you optimize performance.

**Important**: Benchmark results are indicators for configuration testing, not predictors of performance on your specific research topics. What works well on SimpleQA may perform differently on your actual research questions.

## Quick Start

### Web Interface
1. Navigate to **Benchmark** in the web interface
2. Configure your test:
   - Select datasets (SimpleQA recommended)
   - Set number of examples (start with 20-50)
   - Uses your current Settings configuration
3. Click **Start Benchmark** and monitor progress
4. View results in **Benchmark Results** page

## Datasets

### SimpleQA (Recommended)
- Fact-based questions with clear answers
- Best for testing general knowledge retrieval
- Good baseline for comparing configurations

### BrowseComp (Advanced)
- Complex browsing and comparison tasks
- Currently limited performance - use max 20 examples for testing

## Configuration Options

### Search Engines
- **Tavily**: AI-optimized commercial API
- **SearXNG**: Meta-search aggregating multiple engines
- **Brave**: Independent search engine
- **Specialized engines** (ArXiv, PubMed, Wikipedia): Not suitable for general SimpleQA testing

### Strategies
- **Focused Iteration**: Best for SimpleQA fact-based questions
- **Source-Based**: Better for comprehensive research

## Interpreting Results

### Key Metrics
- **Accuracy**: Percentage of correct answers
- **Processing Time**: Time per question (30-60s is typical)
- **Search Results**: Number of search results retrieved per query

### Performance Expectations
- **Focused iteration with SimpleQA**: Around 95% potential with optimal setup
- **Source-based strategy**: Around 70% accuracy, more comprehensive results

## Interpretation

Benchmark numbers are estimates, not exact measurements. This section helps reason about how much to trust a result and when a difference between two runs is meaningful.

### Confidence Intervals for a Single Run

A reported accuracy of "91%" is a point estimate with uncertainty that depends on how many examples you tested. The **Wilson score interval** gives the true range at 95% confidence (it behaves correctly near 0% and 100%, unlike the simpler normal approximation):

```
center    = (p̂ + z²/2n) / (1 + z²/n)
half-width = z × sqrt(p̂(1−p̂)/n + z²/4n²) / (1 + z²/n)

where p̂ = observed accuracy, n = examples run, z = 1.96 for 95% CI
```

**95% confidence margin of error by sample size:**

| Examples (n) | ~70% accuracy | ~85% accuracy | ~91% accuracy | ~95% accuracy |
|:---:|:---:|:---:|:---:|:---:|
| 20  | ±21% | ±17% | ±14% | ±10% |
| 50  | ±13% | ±10% | ±8%  | ±6%  |
| 100 | ±9%  | ±7%  | ±6%  | ±4%  |
| 200 | ±6%  | ±5%  | ±4%  | ±3%  |
| 500 | ±4%  | ±3%  | ±3%  | ±2%  |

> **Key takeaway:** A run of 20 examples has an uncertainty window of ±14–21%. A reported score of "91%" could plausibly be anywhere from 77% to 100%. Use at least 100 examples before drawing any conclusions, and 200+ before comparing configurations.

### Comparing Two Configurations

To tell whether config A is better than config B, you need enough examples that the observed difference is larger than the noise. The table below shows how many examples each configuration needs (run independently, same question set via the same seed) to reliably detect a given absolute accuracy difference at 80% statistical power (α = 0.05, two-sided):

| Difference to detect | Examples needed per config |
|:---|:---:|
| 5 pp (e.g., 85% vs 90%)  | ~680 |
| 10 pp (e.g., 80% vs 90%) | ~200 |
| 15 pp (e.g., 75% vs 90%) | ~90  |

**Rule of thumb:** If the observed difference between two runs is smaller than the margin of error for either run (see the table above), treat the results as a tie.

### When Two Runs Cannot Be Compared

Even with large sample sizes, cross-run comparison is unreliable if any of the following differ between the runs:

- **LDR version** — search logic, prompt templates, and result filtering may have changed between releases
- **Strategy** — `focused_iteration` and `source_based` answer questions differently by design; their scores measure different things
- **Grader model** — changing the evaluation LLM changes what "correct" means; the same system response may grade differently under different graders
- **Random seed / question sample** — some subsets of SimpleQA are inherently easier than others; always use `--seed 42` (or any fixed seed) consistently across compared runs
- **Search engine** — Tavily, SearXNG, and Brave retrieve different content; engine latency also affects what gets retrieved within per-query time limits

Treat each combination of (LDR version, strategy, search engine, grader model, seed) as a distinct experimental condition. Comparisons are only valid within the same condition.

### Evaluator LLM Error

The grader LLM (default: Claude 3.7 Sonnet via OpenRouter) is not perfect. On SimpleQA-style questions it mis-grades approximately **1% of responses** — consistent with calibration results reported in the original SimpleQA paper for similarly capable graders.

What this means in practice:

- **100 examples:** ~1 question is graded wrong. A 1 percentage-point difference (e.g., 91% vs 92%) is indistinguishable from grader noise alone.
- **500 examples:** ~5 questions are graded wrong. A 1% gap is still inside grader noise; differences of 3–4 pp start to be interpretable.
- The grader tends to be **conservative** — it marks ambiguous or partially-correct matches as incorrect — so reported accuracy is a slight underestimate of true accuracy.

**Don't optimize for differences smaller than ~2–3 pp on runs under 500 examples.** The signal is not there.

### Decision Checklist

Before acting on a benchmark result:

```
[ ] n ≥ 100 examples (use ≥ 200 when comparing two configurations)
[ ] Same random seed used across all compared runs
[ ] Same LDR version, strategy, search engine, and grader model
[ ] Observed difference > margin of error for each run (see table above)
[ ] Observed difference > ~2 pp (minimum meaningful above grader noise)
```

---

## Best Practices

### Testing Workflow
1. Start with 20 examples to verify configuration
2. Check that search results are being retrieved
3. Scale to 50-100 examples for reliable metrics
4. Adjust settings based on results

### Troubleshooting
- **Low accuracy**: Verify API keys and search engine connectivity
- **No search results**: Check API credentials and rate limiting
- **Very fast processing**: Usually indicates configuration issues

## Requirements

### API Keys Needed
- **Evaluation**: OpenRouter API key for automatic grading
- **Search**: API key for your chosen search engine
- **LLM**: API key for your language model provider

## Responsible Usage

- Start with small tests to verify configuration
- Use moderate example counts for shared resources
- Monitor API usage in the Metrics page
- Respect rate limits and shared infrastructure

## Important Limitations

Benchmarks test standardized questions and may not reflect performance on:
- Your specific domain or research topics
- Complex, multi-step research questions
- Real-time or recent information queries
- Specialized knowledge areas

Use benchmarks as configuration guidance, then test with your actual research topics to validate performance.

---

The benchmarking system helps you find starting configurations for reliable research results.
