Praison AI

Hierarchical Summaries

Multi-level summaries for efficient navigation of large knowledge bases

python
from praisonaiagents import Agent

agent = Agent(name="summariser", instructions="Create hierarchical summaries of long documents.")
agent.start("Summarise this 50-page report into a 3-level hierarchy.")

Hierarchical summaries build file → folder → project abstractions so agents route queries efficiently across large knowledge bases.

The user asks a broad or specific question; routing picks the right summary level.

Diagram

Hierarchical Summaries

specific

folder

broad

📄 Files

📁 Folder summaries

🏗️ Project summary

❓ Query

Route level

How It Works

Diagram
Hierarchical SummariesAgentUserHierarchical SummariesAgentUserRequestProcess requestResult Agent–>>User: Response

Quick Start

  1. Build a three-level hierarchy
    python
    from praisonaiagents.rag import HierarchicalSummarizer

summarizer = HierarchicalSummarizer(max_levels=3)

files = ["./docs/api.md", "./docs/auth.md", "./docs/config.md"]
summarizer.build_hierarchy(files, base_path="./docs")

answer = summarizer.query("How do I authenticate?")
print(answer)
  2. Persist and reload
    python
    summarizer.save("./summaries/hierarchy.json")
summarizer.load("./summaries/hierarchy.json")

Overview

The HierarchicalSummarizer provides:

  • Multi-level summaries at file, folder, and project levels
  • Query routing to appropriate summary levels
  • Incremental updates when files change
  • Persistent storage of summary hierarchies

Building Hierarchies

From Directory

python
import os
from praisonaiagents.rag import HierarchicalSummarizer

summarizer = HierarchicalSummarizer(max_levels=3)

files = []
for root, _, filenames in os.walk("./docs"):
    for f in filenames:
        if f.endswith(('.md', '.txt', '.py')):
            files.append(os.path.join(root, f))

result = summarizer.build_hierarchy(files, base_path="./docs")

print(f"Files processed: {len(files)}")
print(f"Summary nodes: {len(result.nodes)}")

Summary Levels

LevelScopeDescription
1FileSummary of individual file content
2FolderSummary of all files in a folder
3ProjectSummary of entire project/corpus
python
summarizer = HierarchicalSummarizer(
    max_levels=3,
    file_summary_tokens=500,
    folder_summary_tokens=1000,
    project_summary_tokens=2000,
)

Query Routing

Automatic Routing

python
answer = summarizer.query("What parameters does the auth function accept?")
answer = summarizer.query("What authentication methods are available?")
answer = summarizer.query("What is this project about?")

Manual Level Selection

python
answer = summarizer.query("Overview of the project", level="project")
answer = summarizer.query("What's in the API folder?", level="folder", path="api/")

Persistence

python
summarizer.save("./summaries/hierarchy.json")
summarizer.load("./summaries/hierarchy.json")

summarizer.update_file("./docs/new_file.md")
summarizer.rebuild_folder("./docs/api/")

Durable persistence

The hierarchy JSON written by build_hierarchy() is saved atomically as of PR #6111.

A crash, OOM kill, or non-serialisable value during the save cannot truncate the previous hierarchy file — the last-known-good hierarchy survives, and the failure is logged at WARNING level (Failed to save hierarchy ...).

CLI Usage

bash
praisonai knowledge summarize ./docs
praisonai knowledge summarize ./docs --levels 2 --output ./summaries
praisonai knowledge summarize ./docs -i "*.md,*.txt" -e "test_*" --verbose

Integration with Agents

python
from praisonaiagents import Agent

agent = Agent(
    name="HierarchicalAgent",
    instructions="Answer questions using the knowledge base.",
    knowledge={
        "sources": ["./docs"],
        "retrieval_k": 5,
    },
)

response = agent.start("What is this project about?")
response = agent.start("What are the auth function parameters?")

Best Practices

Use three levels for most projects

File, folder, and project summaries balance routing precision with build cost for typical documentation corpora.

Set token limits per level

Keep file summaries shorter than folder summaries, and folder summaries shorter than the project root — avoids bloated parent nodes.

Persist hierarchies to disk

Save to JSON after the initial build so startup skips re-summarising unchanged files.

Rebuild incrementally on change

Call update_file() or rebuild_folder() instead of rebuilding the entire tree when only part of the corpus changes.

Related

Knowledge

Knowledge sources and retrieval

 Smart Retrieval

Query routing and relevance strategies

 Context Compression

Compress long contexts before LLM calls

 RAG Overview

Retrieval-augmented generation patterns