Contributing

RAG Doctor is open source and actively maintained. Contributions are welcome and encouraged — whether that means fixing a bug, improving documentation, writing a new rule, or building an adapter for a trace format we don't yet support.

Before you start

Please check the open issues and discussions before opening a new one. For larger features, it's worth opening a discussion first to align on approach.

Getting started

Clone the repository

bash
git clone https://github.com/rag-doctor/rag-doctor.git
cd rag-doctor

Install dependencies

bash
# Install all workspace dependencies
npm install
 
# Or with pnpm (recommended for monorepo)
pnpm install

Build all packages

bash
npm run build
 
# Or build a specific package
npm run build --workspace=packages/rules

Run the test suite

bash
# Run all tests
npm test
 
# Run tests in watch mode
npm run test:watch
 
# Run tests for a specific package
npm test --workspace=packages/rules

Project structure

text
rag-doctor/
├── packages/
│   ├── types/          # @rag-doctor/types
│   ├── ingestion/      # @rag-doctor/ingestion
│   ├── rules/          # @rag-doctor/rules
│   ├── core/           # @rag-doctor/core
│   ├── diagnostics/    # @rag-doctor/diagnostics
│   └── reporters/      # @rag-doctor/reporters
├── apps/
│   └── cli/            # rag-doctor CLI
├── docs/               # Documentation site
├── examples/           # Usage examples
└── package.json        # Root workspace config

Where to contribute

Adding a new rule

New rules go in packages/rules/src/rules/. Each rule is a single TypeScript file that exports a rule definition object:

my-new-rule.ts
1// packages/rules/src/rules/my-new-rule.ts
2import type { Rule } from "@rag-doctor/types";
3 
4export const myNewRule: Rule = {
5  id: "my-new-rule",
6  name: "My New Rule",
7  description: "Detects something specific about the trace",
8  defaultSeverity: "warning",
9  defaultOptions: {
10    threshold: 0.5,
11  },
12  evaluate(ctx, options) {
13    const findings = [];
14    // ... rule logic
15    return findings;
16  },
17};

Then register it in packages/rules/src/index.ts and add it to the appropriate rule packs in packages/rules/src/packs/. Add tests in packages/rules/src/__tests__/.

Improving diagnostics

The heuristic graph lives in packages/diagnostics/src/graph.ts. You can add new cause entries, improve recommendation text, or adjust priority weights. All changes must include unit tests.

Adding a trace adapter

Adapters convert third-party trace formats to RAG Doctor's normalized trace shape. Add adapters to packages/ingestion/src/adapters/:

langsmith.ts
1// packages/ingestion/src/adapters/langsmith.ts
2import type { RagTrace } from "@rag-doctor/types";
3import type { LangSmithRun } from "./langsmith-types";
4 
5export function fromLangSmith(run: LangSmithRun): RagTrace {
6  return {
7    query: run.inputs.question,
8    chunks: run.outputs.documents.map((doc, i) => ({
9      id: doc.metadata.id ?? `chunk-${i}`,
10      content: doc.pageContent,
11      score: doc.metadata.score ?? 0,
12      tokens: doc.metadata.tokenCount ?? 0,
13      source: doc.metadata.source,
14    })),
15    model: run.extra?.modelName,
16    totalTokens: run.extra?.totalTokens,
17  };
18}

Improving documentation

Documentation lives alongside the code in the docs/ directory. We especially welcome:

  • Real-world examples and use cases
  • Integration guides for specific frameworks
  • Corrections and clarifications to existing docs
  • Translations

Code standards

  • All code is TypeScript with strict mode enabled
  • Tests are required for all rule changes and new features
  • Follow the existing naming conventions in each package
  • Run npm run lint before submitting a pull request
  • Add a changeset entry for user-facing changes

Thank you

Every contribution — no matter how small — makes RAG Doctor better for the entire community building on top of RAG systems. We appreciate your time and expertise.

Next

Changelog