— Hierarchical Recursive Summarization

UMAP + GMM clustering + LLM summarization in a tree

RAPTOR algorithm: recursive clustering (UMAP, Gaussian Mixture), LLM summarization at each level, tree traversal.

Classes

Files

~N k

Lines

Key Metric

❓ What is this & why?

The raptor module recursively clusters and summarizes chunks into a tree. This solves the context explosion problem: when retrieval returns 1000 chunks (too large for the LLM), RAPTOR provides a compressed tree where the LLM can explore at different abstraction levels.

💡 Real-world analogy

Like an outline for a book. The full book (1000 chunks) is too long to memorize. A chapter outline (100 cluster summaries) is more manageable. A book outline (10 meta-summaries) fits in your head. You read the outline, dive into relevant chapters, dive into relevant sections. RAPTOR builds this outline automatically.

🤔 Why Is It Designed This Way?

{{DESIGN_RATIONALE}} — 150+ words explaining the design choices: what pattern does this follow and why? What constraints shaped the implementation? What trade-offs were made and what was sacrificed?

Design Choice	What Was Chosen	What Was Rejected	Why
Example: data layout	Array of structs	Struct of arrays	Random access pattern dominates; cache locality for single items matters more than SIMD sweeps

Architecture

flowchart TD
    subgraph Input["Chunks 1..N"]
        I["Leaf Nodes"]
    end
    subgraph Cluster["Clustering"]
        C1["UMAP Projection"]
        C2["GMM Clustering"]
    end
    subgraph Summarize["Summarization"]
        S["LLM Summary per Cluster"]
    end
    subgraph Recurse["Recursion"]
        R["Re-cluster Summaries"]
    end
    subgraph Tree["Summary Tree"]
        T["Root (max abstraction)"]
    end
    Input --> Cluster
    Cluster --> Summarize
    Summarize --> Recurse
    Recurse --> Tree

Key Classes

Class / Function	File	Purpose
`ClassName`	file.h	Brief description

Data Structures

Type	Name	Description
enum	`EnumName`	Brief description

Interactions

Direction	Partner	Interface	Description
→	Other Module	`methodName()`	Brief description

Configuration

Knob / Parameter	Default	Description
`param_name`	value	What it controls

Directory Map

Source tree for raptor

submod_name/
├── file_a.ext                 ← Role: brief annotation
├── file_b.ext                 ← Role: brief annotation
├── file_c.ext                 ← Role: brief annotation
└── index.ext                  ← Role: entry point

📑 Annotated Code Walkthrough

The most important code in this sub-module, annotated with WHY each piece exists:

// Replace with actual code from the source
void key_function() {
    // ← WHY: Explain the purpose of this line
    // ← WHY: What constraint or requirement drives this?
}

Line-by-line:

Line N: What this does and WHY — what would break if removed
Line M: The design choice here — why this approach over the obvious alternative

⚠️ Edge Cases & Boundaries

Edge Case	What Happens	Where in Code	Risk Level
Empty input	How it's handled	function_name:line	🟢 Low
Concurrent access	How it's handled	function_name:line	🔴 High

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Hierarchical Summarization

sequenceDiagram
    participant Chunks as Chunks
    participant Cluster as Clustering
    participant LLM as Summarizer
    participant Tree as Summary Tree
    Chunks->>Cluster: Embed
    Cluster->>Cluster: Dimension reduction
    Cluster->>LLM: Summarize clusters
    LLM->>Tree: Level 1
    Tree->>Cluster: Re-cluster
    Cluster->>LLM: Meta-summaries
    LLM->>Tree: Level 2 (root)

Code Examples

Example: Typical Usage

// Replace with actual code example
void example() {
    // ...
}