mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
755 lines
36 KiB
HTML
755 lines
36 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>hierarchical-rag</title>
|
|
<meta name="color-scheme" content="dark">
|
|
<style>
|
|
/* Committed to one visual world: a dark instrument panel. No light variant —
|
|
the dot field and the hairline rules only read on black, and a naive
|
|
inversion would wash both out. Every colour is painted explicitly so the page
|
|
never borrows a host background. */
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
|
|
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
|
|
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
|
|
|
|
:root{
|
|
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
|
|
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
|
|
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
|
|
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
|
|
--font-zen-pixel-square:'Zen Pixel Square',monospace;
|
|
--mono:var(--font-zen-mono);
|
|
--sans:var(--font-zen-sans);
|
|
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
|
|
--r:999px; --r-soft:14px;
|
|
}
|
|
*{box-sizing:border-box}
|
|
html{-webkit-text-size-adjust:100%}
|
|
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
|
|
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
|
|
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
|
|
|
|
/* The dot field. A halftone made of one repeating radial-gradient, faded out
|
|
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
|
|
/* No overflow clip here: the dot field is inset to the box already, and a clip
|
|
would cut off the copy-prompt menu. */
|
|
.hero{position:relative;border-bottom:1px solid var(--line)}
|
|
.hero::before{content:"";position:absolute;inset:0;
|
|
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
|
|
background-size:7px 7px;
|
|
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
|
|
pointer-events:none}
|
|
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
|
|
|
|
nav{border-bottom:1px solid var(--line)}
|
|
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
|
|
justify-content:space-between;align-items:center;gap:1rem}
|
|
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--ink);text-decoration:none;
|
|
display:inline-flex;align-items:center;gap:.6rem}
|
|
.brand i{font-style:normal;color:var(--faint)}
|
|
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
|
|
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
|
|
text-transform:uppercase;color:var(--soft);text-decoration:none}
|
|
nav a.up:hover{color:var(--ink)}
|
|
|
|
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
|
|
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
|
|
h1 em{font-style:normal;color:var(--faint)}
|
|
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
|
|
|
|
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
|
|
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
|
|
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
|
|
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
|
|
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
|
|
line-height:1.2;font-weight:400}
|
|
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
|
|
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
|
|
.btn.solid:hover{background:#d8d8d4}
|
|
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
|
|
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
|
|
|
|
/* Copy-prompt selector. Each row copies the prompt for its own target. */
|
|
.copy{position:relative;display:inline-flex}
|
|
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
|
|
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
|
|
padding:.4rem;display:flex;flex-direction:column;
|
|
box-shadow:0 12px 32px rgba(0,0,0,.75)}
|
|
.menu[hidden]{display:none}
|
|
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
|
|
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
|
|
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
|
|
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
|
|
white-space:nowrap}
|
|
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
|
|
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
|
|
.mi:hover .mark{color:var(--ink)}
|
|
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
|
|
letter-spacing:.1em;text-transform:uppercase}
|
|
|
|
/* Works-with bar: one scrolling row, name and mark per agent. */
|
|
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
|
|
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
|
|
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
|
|
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
|
|
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
|
|
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
|
|
display:flex;align-items:center}
|
|
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
|
|
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
|
|
-webkit-overflow-scrolling:touch;
|
|
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
|
|
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
|
|
.bar::-webkit-scrollbar{display:none}
|
|
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
|
|
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
|
|
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
|
|
text-decoration:none;background:var(--ground)}
|
|
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
|
|
.agent .mark{width:.95rem;height:.95rem}
|
|
|
|
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
|
|
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
|
|
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
|
|
p{margin:0 0 1rem;max-width:70ch}
|
|
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
|
|
li{margin:.22rem 0}
|
|
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
|
|
text-decoration-color:var(--line-hi)}
|
|
a:hover{text-decoration-color:var(--ink)}
|
|
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
|
|
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
|
|
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
|
|
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
|
|
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
|
|
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
|
|
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
|
|
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
|
|
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
|
|
display:block;overflow-x:auto}
|
|
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
|
|
|
|
.curl{display:block;background:var(--panel);border:1px solid var(--line);
|
|
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
|
|
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
|
|
white-space:pre;line-height:1.9}
|
|
.curl b{color:var(--ink);font-weight:400}
|
|
.curl i{font-style:normal;color:var(--faint)}
|
|
|
|
/* index */
|
|
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
|
|
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
|
|
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
|
|
#q:focus{outline:none;border-color:var(--soft)}
|
|
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
|
|
text-transform:uppercase;margin:0 0 2rem}
|
|
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
|
|
padding-bottom:.45rem}
|
|
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
|
|
border-radius:var(--r-soft);text-decoration:none}
|
|
.row:hover{background:#0a0a0a}
|
|
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
|
|
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
|
|
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
|
|
color:var(--faint);font-size:.85rem}
|
|
footer a{color:var(--soft)}
|
|
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
|
|
margin:0 0 2rem;font-size:.85rem}
|
|
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
|
|
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
|
|
border-bottom:1px solid var(--line);padding-bottom:.4rem}
|
|
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
|
|
.fmap a:hover{text-decoration:underline}
|
|
.fmap div{color:var(--faint);line-height:1.5}
|
|
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
|
|
|
|
@media (max-width:640px){
|
|
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
|
|
.btns{gap:.5rem}
|
|
.btn{padding:.75rem 1.15rem;font-size:.68rem}
|
|
.copy,.copy .btn{width:100%;justify-content:center}
|
|
.menu{left:0;right:0;min-width:0}
|
|
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
|
|
.strip b{border-right:0;padding-right:0}
|
|
.bar{width:100%}
|
|
}
|
|
</style>
|
|
<link rel="alternate" type="text/markdown" href="/hierarchical-rag.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/hierarchical-rag">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/hierarchical-rag.md
|
|
Index: https://hanzoskills.com/llms.txt
|
|
Corpus: https://hanzoskills.com/all.md
|
|
Append .md to any path for the markdown twin. -->
|
|
<body>
|
|
<nav><div class="in">
|
|
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
|
|
<a class="up" href="/">All skills</a>
|
|
</div></nav>
|
|
|
|
<div class="wrap">
|
|
<h1>hierarchical-rag</h1><p class="lede">Multi-level retrieval with recursive summarization and parent-child document structures for improved context selection</p><h1>Hierarchical RAG</h1>
|
|
<p><strong>Scope</strong>: Multi-level document structures, recursive summarization, parent-child chunks, top-down/bottom-up retrieval <strong>Lines</strong>: ~420 <strong>Last Updated</strong>: 2025-10-26</p>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Activate this skill when:</p>
|
|
<ul><li>Documents have natural hierarchies (books → chapters → sections → paragraphs)</li><li>Need both high-level summaries and detailed content</li><li>Standard flat chunking loses document structure context</li><li>Queries vary in abstraction level ("summarize the book" vs "explain section 3.2")</li><li>Working with long-form content (technical docs, research papers, books)</li><li>Want to preserve document structure for better context</li><li>Need to zoom in/out between summary and detail levels</li><li>Using LlamaIndex or LangChain hierarchical document loaders</li><li>Evaluating retrieval quality with RAGAS hierarchical metrics</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>Hierarchical Document Structure</h3>
|
|
<p><strong>Levels</strong> (example: technical documentation):</p>
|
|
<pre><code>Level 0 (Root): Entire document
|
|
Level 1 (Chapter): "Chapter 3: Architecture"
|
|
Level 2 (Section): "3.2 Database Design"
|
|
Level 3 (Subsection): "3.2.1 Schema Optimization"
|
|
Level 4 (Paragraph): Individual paragraphs</code></pre>
|
|
<p><strong>Why hierarchy matters</strong>:</p>
|
|
<ul><li>Context: Section title provides context for paragraphs</li><li>Navigation: Can drill down from high-level to specific</li><li>Flexibility: Answer high-level or detailed queries</li></ul>
|
|
<h3>Flat vs Hierarchical Chunking</h3>
|
|
<p><strong>Flat chunking</strong> (standard RAG):</p>
|
|
<pre><code>Document → [Chunk 1, Chunk 2, Chunk 3, ...]</code></pre>
|
|
<ul><li>Each chunk independent</li><li>Loses document structure</li><li>Same chunk size for all content</li></ul>
|
|
<p><strong>Hierarchical chunking</strong>:</p>
|
|
<pre><code>Document (summary)
|
|
├─ Chapter 1 (summary)
|
|
│ ├─ Section 1.1 (summary)
|
|
│ │ ├─ Paragraph 1
|
|
│ │ └─ Paragraph 2
|
|
│ └─ Section 1.2 (summary)
|
|
└─ Chapter 2 (summary)</code></pre>
|
|
<ul><li>Parent-child relationships preserved</li><li>Each level has summaries</li><li>Can navigate up/down hierarchy</li></ul>
|
|
<h3>Recursive Summarization</h3>
|
|
<p><strong>Process</strong>: Bottom-up summary generation</p>
|
|
<pre><code>1. Leaf nodes: Original text (paragraphs)
|
|
2. Level 3: Summarize paragraphs → subsection summary
|
|
3. Level 2: Summarize subsections → section summary
|
|
4. Level 1: Summarize sections → chapter summary
|
|
5. Level 0: Summarize chapters → document summary</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul><li>Multi-resolution: Query at any abstraction level</li><li>Context propagation: Parent summaries provide context</li><li>Efficient: Can answer high-level queries without reading all details</li></ul>
|
|
<h3>Retrieval Strategies</h3>
|
|
<p><strong>Top-down</strong> (coarse-to-fine):</p>
|
|
<pre><code>1. Retrieve at high level (e.g., chapter summaries)
|
|
2. If relevant, drill down to sections
|
|
3. Continue until reaching paragraph level</code></pre>
|
|
<ul><li>Use: Exploratory queries, broad questions</li></ul>
|
|
<p><strong>Bottom-up</strong> (fine-to-coarse):</p>
|
|
<pre><code>1. Retrieve at paragraph level (detailed)
|
|
2. Include parent contexts (section, chapter)
|
|
3. Return combined context</code></pre>
|
|
<ul><li>Use: Specific queries, factual lookups</li></ul>
|
|
<p><strong>Hybrid</strong> (both directions):</p>
|
|
<pre><code>1. Retrieve at paragraph level
|
|
2. Include parent summaries (section, chapter)
|
|
3. Include sibling paragraphs (same section)
|
|
4. Return enriched context</code></pre>
|
|
<ul><li>Use: General-purpose (recommended)</li></ul>
|
|
<h3>Parent-Child Chunks</h3>
|
|
<p><strong>Parent</strong>: Higher-level summary or context <strong>Child</strong>: Detailed content within parent</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>Parent: "Section 3.2: Database Design (Summary: This section covers..."
|
|
Children: [
|
|
"Paragraph 1: PostgreSQL was chosen because...",
|
|
"Paragraph 2: The schema includes five main tables..."
|
|
]</code></pre>
|
|
<p><strong>Retrieval pattern</strong>:</p>
|
|
<ol><li>Embed and retrieve child chunks</li><li>When child matches, include parent context</li><li>LLM sees both detail and surrounding context</li></ol>
|
|
<hr>
|
|
<h2>Implementation Patterns</h2>
|
|
<h3>Pattern 1: Recursive Summarization with DSPy</h3>
|
|
<pre><code class="lang-python">import dspy
|
|
from typing import List, Dict
|
|
|
|
class RecursiveSummarizer(dspy.Module):
|
|
"""Build hierarchical summaries bottom-up."""
|
|
|
|
def __init__(self):
|
|
super().__init__()
|
|
self.summarize = dspy.ChainOfThought("text -> summary")
|
|
|
|
def forward(self, text: str):
|
|
return self.summarize(text=text)
|
|
|
|
|
|
class HierarchicalDocumentBuilder:
|
|
"""Build hierarchical document structure with summaries."""
|
|
|
|
def __init__(self):
|
|
self.summarizer = RecursiveSummarizer()
|
|
self.hierarchy = {}
|
|
|
|
def build_hierarchy(self, document: str, levels: List[str]) -> Dict:
|
|
"""
|
|
Build hierarchy from document.
|
|
|
|
Args:
|
|
document: Full document text
|
|
levels: Level definitions (e.g., ["chapter", "section", "paragraph"])
|
|
"""
|
|
# Parse document into hierarchy (simplified)
|
|
# In practice, use proper document parser
|
|
parsed = self._parse_document(document, levels)
|
|
|
|
# Build summaries bottom-up
|
|
self._build_summaries(parsed)
|
|
|
|
return parsed
|
|
|
|
def _parse_document(self, document: str, levels: List[str]) -> Dict:
|
|
"""Parse document into hierarchical structure."""
|
|
# Simplified: Split by headers/sections
|
|
# Real implementation: Use markdown parser, PDF parser, etc.
|
|
|
|
hierarchy = {
|
|
"level": "document",
|
|
"text": document,
|
|
"summary": None,
|
|
"children": []
|
|
}
|
|
|
|
# Example: Split into chapters (level 1)
|
|
chapters = document.split("\n# ") # Markdown H1
|
|
|
|
for chapter_text in chapters[1:]: # Skip first split
|
|
chapter_node = {
|
|
"level": "chapter",
|
|
"text": chapter_text,
|
|
"summary": None,
|
|
"children": []
|
|
}
|
|
|
|
# Split into sections (level 2)
|
|
sections = chapter_text.split("\n## ") # Markdown H2
|
|
|
|
for section_text in sections[1:]:
|
|
section_node = {
|
|
"level": "section",
|
|
"text": section_text,
|
|
"summary": None,
|
|
"children": []
|
|
}
|
|
|
|
# Split into paragraphs (level 3)
|
|
paragraphs = section_text.split("\n\n")
|
|
|
|
for para in paragraphs:
|
|
para_node = {
|
|
"level": "paragraph",
|
|
"text": para,
|
|
"summary": para, # Paragraphs are leaf nodes
|
|
"children": []
|
|
}
|
|
section_node["children"].append(para_node)
|
|
|
|
chapter_node["children"].append(section_node)
|
|
|
|
hierarchy["children"].append(chapter_node)
|
|
|
|
return hierarchy
|
|
|
|
def _build_summaries(self, node: Dict):
|
|
"""Recursively build summaries bottom-up."""
|
|
# Base case: leaf nodes (paragraphs)
|
|
if not node["children"]:
|
|
return
|
|
|
|
# Recursive case: summarize children first
|
|
for child in node["children"]:
|
|
self._build_summaries(child)
|
|
|
|
# Summarize this level from children
|
|
if node["children"]:
|
|
child_summaries = [child["summary"] for child in node["children"]]
|
|
combined = "\n\n".join(child_summaries)
|
|
|
|
summary_result = self.summarizer(text=combined)
|
|
node["summary"] = summary_result.summary
|
|
|
|
|
|
# Usage
|
|
lm = dspy.LM("openai/gpt-4o-mini")
|
|
dspy.configure(lm=lm)
|
|
|
|
document = """
|
|
# Chapter 1: Introduction
|
|
## Section 1.1: Background
|
|
This is paragraph 1 of section 1.1.
|
|
|
|
This is paragraph 2 of section 1.1.
|
|
|
|
## Section 1.2: Motivation
|
|
This is paragraph 1 of section 1.2.
|
|
|
|
# Chapter 2: Methods
|
|
## Section 2.1: Approach
|
|
This is paragraph 1 of section 2.1.
|
|
"""
|
|
|
|
builder = HierarchicalDocumentBuilder()
|
|
hierarchy = builder.build_hierarchy(document, levels=["chapter", "section", "paragraph"])
|
|
|
|
print("Document summary:", hierarchy["summary"])
|
|
print("Chapter 1 summary:", hierarchy["children"][0]["summary"])</code></pre>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Building multi-level summaries for navigation</li><li>Need to answer queries at different abstraction levels</li><li>Want to preserve document structure</li></ul>
|
|
<h3>Pattern 2: Parent-Child Chunk Retrieval with DSPy</h3>
|
|
<pre><code class="lang-python">import dspy
|
|
from typing import List, Dict, Tuple
|
|
|
|
class ParentChildRetriever:
|
|
"""Retrieve child chunks with parent context."""
|
|
|
|
def __init__(self, hierarchy: Dict):
|
|
self.hierarchy = hierarchy
|
|
self.chunks = []
|
|
self.parent_map = {}
|
|
|
|
# Flatten hierarchy into chunks with parent pointers
|
|
self._flatten_hierarchy(hierarchy, parent=None)
|
|
|
|
def _flatten_hierarchy(self, node: Dict, parent: Dict):
|
|
"""Flatten hierarchy into retrievable chunks."""
|
|
# Add this node as chunk (except root)
|
|
if node["level"] != "document":
|
|
chunk_id = len(self.chunks)
|
|
self.chunks.append({
|
|
"id": chunk_id,
|
|
"level": node["level"],
|
|
"text": node["text"],
|
|
"summary": node["summary"]
|
|
})
|
|
|
|
# Map to parent
|
|
if parent:
|
|
self.parent_map[chunk_id] = parent
|
|
|
|
# Recurse to children
|
|
for child in node["children"]:
|
|
self._flatten_hierarchy(child, parent=node)
|
|
|
|
def retrieve(self, query: str, k=5) -> List[Dict]:
|
|
"""Retrieve chunks with parent context."""
|
|
# Simplified: Use embedding similarity (in practice, use vector DB)
|
|
# For demo, just return top chunks
|
|
|
|
retrieved_chunks = []
|
|
|
|
for chunk in self.chunks[:k]: # Simplified selection
|
|
# Get parent context
|
|
parent_context = None
|
|
if chunk["id"] in self.parent_map:
|
|
parent = self.parent_map[chunk["id"]]
|
|
parent_context = parent["summary"]
|
|
|
|
retrieved_chunks.append({
|
|
"text": chunk["text"],
|
|
"summary": chunk["summary"],
|
|
"level": chunk["level"],
|
|
"parent_context": parent_context
|
|
})
|
|
|
|
return retrieved_chunks
|
|
|
|
|
|
class HierarchicalRAG(dspy.Module):
|
|
"""RAG with hierarchical retrieval."""
|
|
|
|
def __init__(self, retriever: ParentChildRetriever):
|
|
super().__init__()
|
|
self.retriever = retriever
|
|
self.generate = dspy.ChainOfThought("context, question -> answer")
|
|
|
|
def forward(self, question: str):
|
|
# Retrieve chunks with parent context
|
|
retrieved = self.retriever.retrieve(question, k=5)
|
|
|
|
# Format context with hierarchy
|
|
context_parts = []
|
|
for chunk in retrieved:
|
|
if chunk["parent_context"]:
|
|
context_parts.append(f"[Parent: {chunk['parent_context']}]\n{chunk['text']}")
|
|
else:
|
|
context_parts.append(chunk["text"])
|
|
|
|
context = "\n\n---\n\n".join(context_parts)
|
|
|
|
return self.generate(context=context, question=question)
|
|
|
|
|
|
# Usage
|
|
retriever = ParentChildRetriever(hierarchy)
|
|
rag = HierarchicalRAG(retriever)
|
|
|
|
result = rag(question="What is section 1.1 about?")
|
|
print(result.answer)</code></pre>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Want to preserve parent context in retrieval</li><li>Chunks benefit from surrounding section/chapter info</li><li>Standard flat retrieval loses important context</li></ul>
|
|
<h3>Pattern 3: Top-Down Hierarchical Retrieval</h3>
|
|
<pre><code class="lang-python">import dspy
|
|
|
|
class TopDownRetriever(dspy.Module):
|
|
"""Top-down coarse-to-fine retrieval."""
|
|
|
|
def __init__(self, hierarchy: Dict, max_depth=3):
|
|
super().__init__()
|
|
self.hierarchy = hierarchy
|
|
self.max_depth = max_depth
|
|
|
|
# LLM to decide if we need to drill down
|
|
self.should_drill = dspy.ChainOfThought(
|
|
"question, summary -> is_relevant: bool, drill_down: bool"
|
|
)
|
|
|
|
def forward(self, question: str, current_depth=0):
|
|
"""Recursively drill down if relevant."""
|
|
if current_depth >= self.max_depth:
|
|
return []
|
|
|
|
relevant_nodes = []
|
|
|
|
# Check each node at current level
|
|
for node in self._get_nodes_at_depth(self.hierarchy, current_depth):
|
|
# Check if node is relevant
|
|
decision = self.should_drill(
|
|
question=question,
|
|
summary=node["summary"]
|
|
)
|
|
|
|
if decision.is_relevant:
|
|
relevant_nodes.append(node)
|
|
|
|
# Drill down to children if needed
|
|
if decision.drill_down and node["children"]:
|
|
child_results = self._drill_down(question, node, current_depth + 1)
|
|
relevant_nodes.extend(child_results)
|
|
|
|
return relevant_nodes
|
|
|
|
def _get_nodes_at_depth(self, node: Dict, target_depth: int, current_depth=0):
|
|
"""Get all nodes at target depth."""
|
|
if current_depth == target_depth:
|
|
return [node]
|
|
|
|
nodes = []
|
|
for child in node["children"]:
|
|
nodes.extend(self._get_nodes_at_depth(child, target_depth, current_depth + 1))
|
|
|
|
return nodes
|
|
|
|
def _drill_down(self, question: str, node: Dict, depth: int):
|
|
"""Drill down into node's children."""
|
|
relevant = []
|
|
|
|
for child in node["children"]:
|
|
decision = self.should_drill(question=question, summary=child["summary"])
|
|
|
|
if decision.is_relevant:
|
|
relevant.append(child)
|
|
|
|
if decision.drill_down and child["children"]:
|
|
relevant.extend(self._drill_down(question, child, depth + 1))
|
|
|
|
return relevant
|
|
|
|
|
|
class TopDownRAG(dspy.Module):
|
|
"""RAG with top-down hierarchical retrieval."""
|
|
|
|
def __init__(self, hierarchy: Dict):
|
|
super().__init__()
|
|
self.retriever = TopDownRetriever(hierarchy, max_depth=3)
|
|
self.generate = dspy.ChainOfThought("context, question -> answer")
|
|
|
|
def forward(self, question: str):
|
|
# Top-down retrieval
|
|
relevant_nodes = self.retriever(question=question)
|
|
|
|
# Extract text from nodes
|
|
context_parts = [node["text"] for node in relevant_nodes]
|
|
context = "\n\n".join(context_parts)
|
|
|
|
return self.generate(context=context, question=question)</code></pre>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Exploratory queries (broad questions)</li><li>Want to avoid reading all details if high-level summary suffices</li><li>Efficient retrieval for large documents</li></ul>
|
|
<h3>Pattern 4: LlamaIndex Hierarchical Document Loader</h3>
|
|
<pre><code class="lang-python">import dspy
|
|
from llama_index.core import Document, VectorStoreIndex
|
|
from llama_index.core.node_parser import HierarchicalNodeParser
|
|
|
|
class LlamaIndexHierarchicalRAG:
|
|
"""Hierarchical RAG using LlamaIndex."""
|
|
|
|
def __init__(self, documents: List[str]):
|
|
# Parse documents hierarchically
|
|
parser = HierarchicalNodeParser.from_defaults(
|
|
chunk_sizes=[2048, 512, 128] # Level sizes: chapter, section, paragraph
|
|
)
|
|
|
|
# Create LlamaIndex documents
|
|
docs = [Document(text=doc) for doc in documents]
|
|
|
|
# Parse into hierarchical nodes
|
|
nodes = parser.get_nodes_from_documents(docs)
|
|
|
|
# Build index
|
|
self.index = VectorStoreIndex(nodes)
|
|
|
|
def query(self, question: str, similarity_top_k=5):
|
|
"""Query with hierarchical retrieval."""
|
|
query_engine = self.index.as_query_engine(
|
|
similarity_top_k=similarity_top_k,
|
|
response_mode="tree_summarize" # Use hierarchy for response
|
|
)
|
|
|
|
response = query_engine.query(question)
|
|
return response
|
|
|
|
|
|
# Usage
|
|
documents = [
|
|
"Large document 1 with chapters and sections...",
|
|
"Large document 2 with chapters and sections...",
|
|
]
|
|
|
|
rag = LlamaIndexHierarchicalRAG(documents)
|
|
response = rag.query("What are the main themes?")
|
|
print(response)</code></pre>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul><li>Using LlamaIndex ecosystem</li><li>Want built-in hierarchical parsing</li><li>Need tree summarization for responses</li></ul>
|
|
<h3>Pattern 5: RAGAS Hierarchical Evaluation</h3>
|
|
<pre><code class="lang-python">import dspy
|
|
from ragas import evaluate
|
|
from ragas.metrics import context_precision, context_recall, faithfulness
|
|
|
|
class HierarchicalRAGEvaluator:
|
|
"""Evaluate hierarchical RAG quality."""
|
|
|
|
def __init__(self, rag_system):
|
|
self.rag = rag_system
|
|
|
|
def evaluate(self, test_set):
|
|
"""Evaluate using RAGAS metrics."""
|
|
predictions = []
|
|
|
|
for example in test_set:
|
|
result = self.rag(question=example.question)
|
|
|
|
predictions.append({
|
|
"question": example.question,
|
|
"answer": result.answer,
|
|
"contexts": result.retrieved_contexts, # Hierarchical contexts
|
|
"ground_truth": example.ground_truth
|
|
})
|
|
|
|
# Evaluate with RAGAS
|
|
ragas_results = evaluate(
|
|
dataset=predictions,
|
|
metrics=[
|
|
context_precision, # Precision of retrieved contexts
|
|
context_recall, # Recall of relevant contexts
|
|
faithfulness # Answer faithfulness to context
|
|
]
|
|
)
|
|
|
|
print("RAGAS Results:")
|
|
print(f"Context Precision: {ragas_results['context_precision']:.3f}")
|
|
print(f"Context Recall: {ragas_results['context_recall']:.3f}")
|
|
print(f"Faithfulness: {ragas_results['faithfulness']:.3f}")
|
|
|
|
return ragas_results</code></pre>
|
|
<p><strong>Metrics</strong>:</p>
|
|
<ul><li><strong>Context precision</strong>: Are retrieved chunks relevant?</li><li><strong>Context recall</strong>: Did we retrieve all relevant chunks?</li><li><strong>Faithfulness</strong>: Is answer grounded in retrieved context?</li></ul>
|
|
<hr>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Retrieval Strategy Selection</h3>
|
|
<pre><code>Broad question → Top-down (coarse-to-fine)
|
|
Specific question → Bottom-up (fine-to-coarse)
|
|
General purpose → Hybrid (parent-child)</code></pre>
|
|
<h3>Hierarchy Levels (Typical)</h3>
|
|
<pre><code>Level 0: Document (1-10K tokens)
|
|
Level 1: Chapter (1K-3K tokens)
|
|
Level 2: Section (300-1K tokens)
|
|
Level 3: Subsection (100-300 tokens)
|
|
Level 4: Paragraph (50-150 tokens)</code></pre>
|
|
<h3>Summary Generation</h3>
|
|
<pre><code>Leaf nodes: Original text
|
|
Internal nodes: Summarize children (recursive)
|
|
Root: Overall document summary</code></pre>
|
|
<h3>Platform Support</h3>
|
|
<pre><code>LlamaIndex: HierarchicalNodeParser (built-in)
|
|
LangChain: RecursiveCharacterTextSplitter (custom)
|
|
DSPy: Custom hierarchy builders (this skill)</code></pre>
|
|
<hr>
|
|
<h2>Anti-Patterns</h2>
|
|
<p>❌ <strong>Losing parent context during retrieval</strong>:</p>
|
|
<pre><code class="lang-python"># Bad - retrieve paragraphs without parent context
|
|
chunks = retrieve(query, k=5) # Just paragraphs
|
|
context = "\n".join(chunks) # No section/chapter info</code></pre>
|
|
<p>✅ Include parent context:</p>
|
|
<pre><code class="lang-python"># Good - retrieve with parent summaries
|
|
chunks = retrieve_with_parents(query, k=5)
|
|
context = format_hierarchical_context(chunks) # Includes parent info</code></pre>
|
|
<p>❌ <strong>Flat chunking for hierarchical documents</strong>:</p>
|
|
<pre><code class="lang-python"># Bad - split book into equal 512-token chunks
|
|
chunks = split_text(book, chunk_size=512) # Loses structure</code></pre>
|
|
<p>✅ Preserve hierarchy:</p>
|
|
<pre><code class="lang-python"># Good - parse hierarchy first
|
|
hierarchy = parse_hierarchical(book) # Chapters → sections → paragraphs
|
|
chunks = hierarchical_chunks(hierarchy)</code></pre>
|
|
<p>❌ <strong>Not summarizing intermediate levels</strong>:</p>
|
|
<pre><code class="lang-python"># Bad - only store leaf paragraphs
|
|
for paragraph in document:
|
|
store(paragraph) # No chapter/section summaries</code></pre>
|
|
<p>✅ Build summaries at all levels:</p>
|
|
<pre><code class="lang-python"># Good - recursive summarization
|
|
hierarchy = build_hierarchy(document)
|
|
add_summaries_recursive(hierarchy) # All levels have summaries</code></pre>
|
|
<p>❌ <strong>Same chunk size for all levels</strong>:</p>
|
|
<pre><code class="lang-python"># Bad - 512 tokens for everything
|
|
chunks = [
|
|
{"level": "chapter", "size": 512}, # Too small!
|
|
{"level": "paragraph", "size": 512} # Too large!
|
|
]</code></pre>
|
|
<p>✅ Level-appropriate sizes:</p>
|
|
<pre><code class="lang-python"># Good - larger chunks for higher levels
|
|
chunks = [
|
|
{"level": "chapter", "size": 2048},
|
|
{"level": "section", "size": 512},
|
|
{"level": "paragraph", "size": 128}
|
|
]</code></pre>
|
|
<hr>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><code>dspy-rag.md</code> - Basic RAG patterns and flat retrieval</li><li><code>hybrid-search-rag.md</code> - Combining vector and BM25 retrieval</li><li><code>rag-reranking-techniques.md</code> - Multi-stage retrieval</li><li><code>graph-rag.md</code> - Graph-based retrieval for relationships</li><li><code>database/postgres-schema-design.md</code> - Storing hierarchical data</li></ul>
|
|
<hr>
|
|
<h2>Summary</h2>
|
|
<p>Hierarchical RAG preserves document structure for better context and flexible retrieval:</p>
|
|
<ul><li><strong>Architecture</strong>: Parse hierarchy → Recursive summarization → Multi-level retrieval</li><li><strong>Parent-child chunks</strong>: Retrieve detailed content with surrounding context</li><li><strong>Retrieval strategies</strong>: Top-down (coarse-to-fine), bottom-up (fine-to-coarse), hybrid</li><li><strong>Typical levels</strong>: Document → Chapter → Section → Subsection → Paragraph</li><li><strong>Platforms</strong>: LlamaIndex HierarchicalNodeParser, LangChain recursive splitters, custom DSPy</li><li><strong>Evaluation</strong>: RAGAS metrics (context precision, recall, faithfulness)</li><li><strong>Best practice</strong>: Use hierarchy for structured documents (books, docs, papers), flat chunking for unstructured text</li><li><strong>Key advantage</strong>: Answer queries at any abstraction level ("summarize book" or "explain section 3.2")</li></ul>
|
|
<p>Hierarchical RAG is most valuable for long-form, structured documents where context and navigation matter.</p>
|
|
<hr>
|
|
<p><strong>Last Updated</strong>: 2025-10-26 <strong>Format Version</strong>: 1.0 (Atomic)</p>
|
|
<footer>
|
|
<div class="fmap">
|
|
<div><b>Build</b>
|
|
<a href="https://hanzo.app">hanzo.app</a> app builder
|
|
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
|
|
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
|
|
<div><b>Run</b>
|
|
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
|
|
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
|
|
<div><b>Account</b>
|
|
<a href="https://hanzo.id">hanzo.id</a> sign in
|
|
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
|
|
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
|
|
<div><b>Company</b>
|
|
<a href="https://hanzo.ai">hanzo.ai</a> canonical
|
|
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
|
|
</div>
|
|
<div class="fend"><a href="/hierarchical-rag.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |