Configuration

RAG Doctor works out of the box with no configuration required. When you need to customize rule thresholds, switch between rule packs, or disable specific rules, you can provide a configuration file.

Configuration file

Create a .rag-doctor.json file in your project root (or any path you specify with --config):

.rag-doctor.json
1{
2  "pack": "recommended",
3  "ruleOptions": {
4    "duplicate-chunks": {
5      "enabled": true,
6      "similarityThreshold": 0.85
7    },
8    "low-retrieval-score": {
9      "enabled": true,
10      "minScore": 0.72
11    },
12    "oversized-chunk": {
13      "enabled": true,
14      "maxTokens": 512
15    },
16    "context-overload": {
17      "enabled": true,
18      "maxUtilizationPct": 90
19    }
20  }
21}

Rule packs

Rule packs are named collections of rules with predefined defaults. You can select a pack as a starting point and override individual rule options on top.

PackDescriptionRules included
recommendedDefault. Balanced thresholds for most production use cases.All 4 built-in rules
strictTighter thresholds. Suitable for high-accuracy applications.All 4 rules, stricter defaults
minimalOnly the two most impactful rules: low-retrieval-score and context-overload.2 rules

Strict pack example

.rag-doctor.strict.json
{
  "pack": "strict",
  "ruleOptions": {
    "duplicate-chunks": {
      "similarityThreshold": 0.80
    },
    "low-retrieval-score": {
      "minScore": 0.80
    },
    "oversized-chunk": {
      "maxTokens": 384
    },
    "context-overload": {
      "maxUtilizationPct": 80
    }
  }
}

Disabling individual rules

Set "enabled": false on any rule to disable it without switching packs:

json
{
  "pack": "recommended",
  "ruleOptions": {
    "oversized-chunk": {
      "enabled": false
    }
  }
}

Using config with CLI

bash
# Use a specific config file
rag-doctor analyze trace.json --config .rag-doctor.json
 
# Override pack at command line (takes precedence over config file)
rag-doctor analyze trace.json --pack strict

Config resolution order

When multiple sources provide the same option, the resolution order is: CLI flags → config file → pack defaults → built-in defaults.

Programmatic configuration

When embedding RAG Doctor in an application, pass config programmatically to the core API:

analyze.ts
1import { analyze } from "@rag-doctor/core";
2 
3const result = await analyze(trace, {
4  pack: "strict",
5  ruleOptions: {
6    "low-retrieval-score": {
7      minScore: 0.80,
8    },
9  },
10});
11 
12console.log(result.findings);

Next

Architecture