Class RaptorTree

RAPTOR — Recursive Abstractive Processing for Tree-Organized Retrieval.

Builds a hierarchical summary tree over document chunks, enabling retrieval at multiple levels of abstraction. Leaf nodes contain original chunks while higher layers contain progressively more abstract summaries.

Example: Building and searching a RAPTOR tree

const raptor = new RaptorTree({
  llmCaller: async (prompt) => {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o-mini',
      messages: [{ role: 'user', content: prompt }],
    });
    return response.choices[0].message.content ?? '';
  },
  embeddingManager: myEmbeddingManager,
  vectorStore: myVectorStore,
  clusterSize: 8,
  maxDepth: 3,
});

// Build tree from 100 document chunks
const stats = await raptor.build(chunks);
console.log(`Built ${stats.totalLayers} layers with ${stats.totalNodes} total nodes`);

// Search all layers simultaneously
const results = await raptor.search('What are the main themes?', 10);
for (const r of results) {
  console.log(`[Layer ${r.layer}] ${r.id}: ${r.score.toFixed(3)} — ${r.text.slice(0, 80)}...`);
}

Constructors

constructor

Methods

build search getStats

Constructors

constructor

  • new RaptorTree(config): RaptorTree

  • Creates a new RaptorTree.

    Parameters

    • config: RaptorTreeConfig

      Configuration including LLM caller, embedding manager, vector store, and clustering parameters.

    Returns RaptorTree

    Example

    const raptor = new RaptorTree({
      llmCaller: myLlm,
      embeddingManager: myEmbeddings,
      vectorStore: myStore,
      clusterSize: 8,
      maxDepth: 4,
    });

Methods

build

  • build(chunks): Promise<RaptorTreeStats>

  • Builds the RAPTOR tree from a set of leaf chunks.

    Pipeline for each layer:

    1. Embed all current-layer chunks
    2. Cluster similar chunks using k-means
    3. Summarize each cluster using the LLM with chain-of-thought
    4. Embed summaries and store in vector store with layer metadata
    5. Treat summaries as the next layer's input and repeat

    Stops when:

    • Fewer than minChunksForLayer summaries were produced
    • Maximum depth is reached
    • Only one cluster remains (root summary)

    Parameters

    Returns Promise<RaptorTreeStats>

    Statistics about the constructed tree.

    Throws

    If embedding or storage fails critically.

    Example

    const chunks = documents.map((doc, i) => ({
      id: `chunk-${i}`,
      text: doc.content,
      metadata: { source: doc.source },
    }));
    const stats = await raptor.build(chunks);
    console.log(`Tree has ${stats.totalLayers} layers`);

search

  • search(query, topK?): Promise<RaptorResult[]>

  • Searches ALL layers of the RAPTOR tree simultaneously.

    This is the key advantage of RAPTOR: a detail query will match leaf chunks, while a thematic query will match higher-layer summaries. Both types of results are returned together, sorted by relevance.

    Parameters

    • query: string

      The search query.

    • Optional topK: number = 10

      Maximum number of results across all layers.

    Returns Promise<RaptorResult[]>

    Results from all layers, sorted by score.

    Throws

    If embedding or vector search fails.

    Example

    const results = await raptor.search('authentication architecture', 10);
    // May return:
    // - Layer 0 chunks about specific auth implementations
    // - Layer 1 summaries about auth patterns
    // - Layer 2 high-level summary about security architecture

getStats

  • getStats(): RaptorTreeStats

  • Returns statistics about the last tree build.

    Returns RaptorTreeStats

    Tree statistics including layer counts, node counts, cluster counts, and build time.

    Example

    const stats = raptor.getStats();
    console.log(`Layers: ${stats.totalLayers}, Nodes: ${stats.totalNodes}`);

Settings

Member Visibility

Theme

On This Page

constructorbuildsearchgetStats