Topics

Language breakdown

No language data available.

▸ Files click to expand

README

Mindmap Generator

An intelligent document analysis tool that uses Large Language Models to generate comprehensive, hierarchical mindmaps from any text document.

Interactive Mermaid Diagram	Markdown Outline

Interactive HTML visualization with expandable nodes	Hierarchical Markdown output for easy reference

🧠 Overview

The Mindmap Generator is a sophisticated document analysis system that extracts the core concepts, relationships, and details from text documents and organizes them into intuitive, hierarchical mindmaps. Unlike simple text summarization, this tool:

Intelligently adapts to different document types (legal, technical, scientific, narrative, etc.)
Creates multi-level hierarchical representations (topics, subtopics, details)
Ensures factual accuracy by verifying against the source document
Eliminates redundant or overlapping concepts
Generates outputs in multiple formats (Mermaid syntax, HTML, Markdown)
See an example Mermaid Diagram in the live editor here

The system is built to work with a variety of LLM providers (OpenAI, Anthropic/Claude, DeepSeek, Google Gemini) and optimizes for both cost-efficiency and output quality.

You can read a detailed blog post about the making of this project and the various challenges and design considerations that went into the design and engineering of it here.

📋 Features

Document Type Detection: Automatically adapts extraction strategies based on document type
Hierarchical Content Extraction: Builds three-level hierarchies (topics → subtopics → details)
Reality Checking: Verifies generated content against the source document to prevent confabulation
Duplicate Detection: Uses both fuzzy matching and semantic similarity to avoid redundancy
Multi-format Output:

- Mermaid mindmap syntax - Interactive HTML with Mermaid rendering - Markdown outline

Cost Optimization: Designed to work efficiently with value-priced LLMs
Rich Logging: Detailed, color-coded progress tracking (see an example here)

⚙️ Installation

Install Pyenv and Python 3.12 (if needed):

# Install Pyenv and python 3.12 if needed and then use it to create venv:
if ! command -v pyenv &> /dev/null; then
    sudo apt-get update
    sudo apt-get install -y build-essential libssl-dev zlib1g-dev libbz2-dev \
    libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev \
    xz-utils tk-dev libffi-dev liblzma-dev python3-openssl git
git clone https://github.com/pyenv/pyenv.git ~/.pyenv     echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc     echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc     echo 'eval "$(pyenv init --path)"' >> ~/.zshrc     source ~/.zshrc fi cd ~/.pyenv && git pull && cd - pyenv install 3.12

Set up the project:

# Use pyenv to create virtual environment:
git clone https://github.com/Dicklesworthstone/mindmap-generator    
cd mindmap-generator          
pyenv local 3.12
python -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
python -m pip install wheel
python -m pip install --upgrade setuptools wheel
pip install -r requirements.txt

Set up your environment:

Create a .env file with your API keys:

OPENAIAPIKEY="your-key"
ANTHROPICAPIKEY="your-key" 
DEEPSEEKAPIKEY="your-key"
GEMINIAPIKEY="your-key"
API_PROVIDER="OPENAI"  # Options: "OPENAI", "CLAUDE", "DEEPSEEK", or "GEMINI"

🚀 Usage

Edit the mindmap_generator.py file to specify your input document:

inputfile = "sampleinputdocumentasmarkdowndurnovomemo.md"  # <-- Change

Run the generator:

python mindmap_generator.py

Find your generated outputs in the mindmap_outputs directory:

- {filename}mindmap_{provider}.txt - Mermaid syntax - {filename}mindmap_{provider}.html - Interactive HTML visualization - {filename}mindmapoutline__{provider}.md - Markdown outline

📜 The Durnovo Memo: A Test Case Across LLM Providers

This repository includes a fascinating historical document as a test case - the famous Durnovo memo from 1914, which remarkably predicted World War I and the Russian Revolution. For more about this incredible document, see my article about it here.

Historical Significance

The Durnovo Memorandum was written by Pyotr Durnovo, a Russian statesman, to Tsar Nicholas II in February 1914 - months before the outbreak of World War I. With astonishing prescience, Durnovo warned about:

The inevitability of war between Germany and Russia if European tensions continued
How such a war would lead to social revolution in Russia
The collapse of monarchies across Europe
The specific dangers Russia faced in a prolonged European conflict

The memo has been hailed as one of the most accurate political predictions in modern history, making it an excellent test document for our mindmap generator.

Cross-Provider Comparison

We've processed this document using all four supported LLM providers to demonstrate how each handles the complex historical content. The results showcase each provider's strengths and unique approaches to concept extraction and organization.

OpenAI (GPT-4o-mini)

OpenAI's model produced a concise, well-structured mindmap with clear hierarchical organization:

Mermaid Syntax (2.8 KB)
Interactive HTML (5.7 KB)
Markdown Outline (2.5 KB)

GPT-4o-mini excels at producing compact, efficient mindmaps that capture essential concepts without redundancy. Its output is characterized by clear categorization and precise language.

Anthropic (Claude)

Claude produced a more detailed mindmap with richer contextual information:

Mermaid Syntax (4.1 KB)
Interactive HTML (7.3 KB)
Markdown Outline (3.8 KB)

Claude's approach tends to include more nuanced historical context and captures subtle relationships between concepts. Its output is particularly strong in preserving the memo's analytical reasoning.

DeepSeek

DeepSeek generated the most comprehensive mindmap with extensive subtopics and details:

DeepSeek's output is notable for its thoroughness and depth of analysis. It extracts more subtleties from the document but occasionally at the cost of some redundancy.

Google Gemini

Gemini created a balanced mindmap with strong thematic organization:

Mermaid Syntax (5.5 KB)
Interactive HTML (9.6 KB)
Markdown Outline (5.0 KB)

Gemini's approach focuses on thematic coherence, with particularly strong extraction of geopolitical concepts and causal relationships between events.

Key Observations from Cross-Provider Testing

This multi-provider approach reveals interesting patterns:

Content Organization Differences: Each provider structures the document's concepts differently, revealing their unique approaches to conceptual organization
Detail Granularity Variance: The level of detail varies significantly, with DeepSeek providing the most comprehensive extraction and OpenAI the most concise
Emoji Selection Patterns: Each model has distinct tendencies in selecting representative emojis for concepts
Historical Context Sensitivity: Models differ in how they handle historical context, with Claude showing particular strength in preserving historical nuance
Structured Knowledge Representation: The differences highlight various approaches to knowledge organization from the different AI research teams

The sample outputs serve as both demonstration of the tool's capabilities and an interesting comparative study of how different LLM providers approach the same complex historical document.

🔍 How It Works: The Architecture

Unlike traditional LLM applications that operate linearly, the Mindmap Generator employs a sophisticated, non-linear architecture that resembles an undirected graph of exploration. Here's an in-depth look at how the system works:

📊 The Non-Linear Exploration Model

Traditional LLM applications typically follow a simple pattern:

Input → LLM Prompt → Output

Or perhaps a pipeline:

Input → LLM Prompt 1 → Output 1 → LLM Prompt 2 → Output 2 → Final Result

The Mindmap Generator, however, operates as a multi-dimensional exploration system, where:

Multiple parallel processes explore different aspects of the document simultaneously
Feedback loops evaluate the quality and uniqueness of extracted information
Heuristic-guided decisions determine when to explore deeper or stop exploration
Verification mechanisms ensure factual accuracy throughout

This approach allows the system to efficiently navigate the vast conceptual space of the document while maintaining coherence and accuracy.

🧩 Document Type Detection System

The system begins by analyzing a sample of the document to determine its fundamental type, which guides subsequent extraction strategies:

Technical documents focus on system components, interfaces, and implementations
Scientific documents emphasize research methodologies, results, and theoretical frameworks
Narrative documents highlight plot elements, character development, and thematic elements
Business documents extract strategic initiatives, market opportunities, and implementation plans
Legal documents identify legal principles, rights, obligations, and procedural requirements
Academic documents focus on theoretical frameworks, scholarly arguments, and evidence
Instructional documents extract learning objectives, skill development, and assessment methods

Each document type has specialized prompt templates optimized for extracting the most relevant information. Rather than a simple classification, the system uses specific detection heuristics that identify key indicators of document structure and purpose.

🌐 Intelligent Chunking System

A key innovation is how the system handles large documents:

Overlapping Chunk Creation: Documents are divided into manageable chunks with deliberate overlap to preserve context at boundaries
Boundary Optimization: Chunk boundaries are adjusted to coincide with natural breaks (e.g., end of sentences) rather than arbitrary character counts
Context Preservation: The overlap between chunks ensures that concepts that span chunk boundaries aren't fragmented
Progressive Exploration: Chunks are processed in a way that builds cumulative understanding of the document

This approach solves the fundamental limitation of LLM context windows while ensuring no important information is lost at chunk boundaries.

🎯 Topic Extraction Engine

The topic extraction process employs a sophisticated multi-stage approach:

Parallel Initial Extraction: Multiple chunks are analyzed simultaneously to identify potential topics
Frequency Analysis: Topics that appear across multiple chunks receive higher significance
Consolidation Phase: Similar topics are merged into cohesive, distinct concepts
Semantic Deduplication: Multiple similarity detection methods (including LLM-based semantic analysis) ensure topics are genuinely distinct
Importance Ranking: Topics are weighted based on document coverage, frequency, and semantic significance

This multi-phase approach ensures that the extracted topics provide balanced coverage of the document's content while avoiding redundancy or over-fragmentation.

🔄 Adaptive Exploration Strategy

The system employs an adaptive strategy that optimizes resource usage:

Priority-Based Processing: More important topics receive deeper exploration
Diminishing Returns Detection: The system recognizes when additional processing yields minimal new insights
Breadth-Depth Balancing: The exploration automatically adjusts between breadth (covering more topics) and depth (exploring topics in greater detail) based on document complexity
Completion Thresholds: Sophisticated heuristics determine when sufficient information has been extracted

This adaptive approach ensures that the system allocates computational resources efficiently, focusing effort where it will provide the most value.

🧠 Semantic Redundancy Detection

One of the most challenging aspects of mindmap generation is eliminating redundancy while preserving unique information. The system employs a multi-layered approach:

Textual Similarity: Basic string matching identifies obvious duplicates
Fuzzy Matching: Fuzzy string algorithms detect near-duplicate content with variations
Token-Based Analysis: Comparing token patterns identifies structural similarities
LLM-Based Semantic Analysis: For conceptually similar but textually different content, the system uses the LLM itself to evaluate semantic similarity
Hierarchical Redundancy Checking: Redundancy is checked within levels (e.g., between topics) and across levels (e.g., between a topic and a subtopic)

This comprehensive approach prevents the mindmap from containing repetitive information while ensuring nothing important is lost.

🔍 The Reality Check System

To prevent confabulation (the generation of factually incorrect information), the system implements a sophisticated verification mechanism:

Content Verification: Each generated node is compared against the source document to ensure it's either explicitly stated or logically derivable
Confidence Scoring: Verification results include confidence metrics that influence node inclusion
Structural Preservation: The system balances factual accuracy with maintaining a coherent mindmap structure
Verification Statistics: Detailed metrics track verification success rates across different node types

This reality check ensures that the mindmap remains a faithful representation of the source document, even when dealing with complex or abstract content.

🎨 Semantic Emoji Selection

The system enriches the visual representation of the mindmap through intelligent emoji selection:

Context-Aware Selection: Emojis are chosen based on the semantic content of each node
Hierarchical Differentiation: Different node types (topics, subtopics, details) use visually distinct emoji styles
Importance Indicators: Special markers indicate the importance level of details
Persistent Caching: Emoji selections are cached to ensure consistency across generations
Fallback Hierarchy: If optimal emoji selection fails, the system follows a thoughtful fallback strategy

This visual enhancement makes the mindmap more engaging and easier to navigate, with visual cues that communicate additional meaning.

🛠️ Technical Challenges and Solutions

Preventing Cognitive Overload in Value-Priced LLMs

A significant challenge was making the system work effectively with more affordable LLM models:

Prompt Optimization: Each prompt is carefully crafted to be concise yet comprehensive
Context Limitation: The system deliberately limits context to prevent cognitive overload
Task Isolation: Complex tasks are broken down into simpler, focused sub-tasks
Progressive Refinement: Results are incrementally improved rather than attempting perfect outputs in one step
Error Recovery: The system detects and handles cases where LLM outputs are inconsistent or low-quality

These strategies allow the system to leverage less expensive models while maintaining high-quality outputs.

Asynchronous Processing Architecture

The system employs a sophisticated asynchronous architecture:

Task Orchestration: Complex dependency graphs manage the flow of tasks
Semaphore-Based Rate Limiting: Prevents overwhelming API rate limits
Exponential Backoff with Jitter: Intelligent retry logic for handling failures
Cooperative Task Scheduling: Efficient resource utilization across concurrent operations
Dynamic Priority Adjustment: More important tasks receive processing priority

This asynchronous design dramatically improves throughput while maintaining control over execution flow.

Content Balance Heuristics

The system employs sophisticated heuristics to ensure balanced content extraction:

Minimum Coverage Requirements: Ensures sufficient breadth across the document
Distribution Balancing: Prevents over-representation of specific sections
Hierarchical Proportion Control: Maintains appropriate ratios between topics, subtopics, and details
Importance-Weighted Selection: More significant content receives greater representation
Content Type Diversity: Ensures a mix of conceptual, factual, and supporting information

These heuristics ensure that the final mindmap provides a balanced representation of the document's content.

Error Recovery and Resilience

The system incorporates multiple layers of error handling:

Graceful Degradation: The system continues operating effectively even when some components fail
Result Validation: All LLM outputs are validated before being incorporated
Fallback Strategies: Alternative approaches are employed when primary methods fail
State Preservation: Intermediate results are cached to prevent lost work
Comprehensive Logging: Detailed error information facilitates debugging and improvement

This resilience ensures reliable operation even with unreliable LLM responses or API limitations.

📊 Performance Optimization and Cost Management

Comprehensive Token Usage Tracking

The system implements detailed token usage tracking:

Category-Based Tracking: Usage is broken down by functional categories
Cost Calculation: Token counts are converted to cost estimates based on provider pricing
Comparative Analysis: Usage patterns are analyzed to identify optimization opportunities
Trend Monitoring: Usage patterns over time help identify shifts in performance

This tracking provides transparency and supports ongoing optimization efforts. You can see an example of what it looks like here.

Cost Efficiency Strategies

Several strategies minimize costs while maintaining output quality:

Early Stopping: Processing halts when sufficient quality is achieved
Tiered Processing: Less expensive models handle simpler tasks
Caching: Frequently used results are cached to prevent redundant API calls
Content Batching: Multiple items are processed in single API calls where possible
Similarity Pre-filtering: Cheaper computational methods filter candidates before expensive LLM-based comparisons

These strategies significantly reduce the total cost of generating comprehensive mindmaps.

Performance Metrics and Dashboards

The system provides rich performance visualization:

Color-Coded Progress: Visual indicators show processing status at a glance
Hierarchical Metrics: Performance is tracked at multiple levels of granularity
Completion Ratios: Progress toward completion is continuously updated
Cost Projections: Running cost estimates provide financial transparency
Quality Indicators: Verification rates and confidence scores indicate output reliability

These visual tools make it easy to monitor long-running processes and understand system behavior.

📈 Advanced Functionality

Incremental Improvement Cycles

The system can iteratively improve mindmaps through targeted refinement:

Quality Assessment: Existing mindmaps are evaluated for balance and coverage
Targeted Enhancement: Specific areas are identified for improvement
Differential Processing: Only areas requiring enhancement are reprocessed
Consolidation: New insights are integrated with existing content
Before/After Comparison: Changes are tracked to evaluate improvement

This approach allows efficient enhancement of existing mindmaps without complete regeneration.

Multi-Provider Support

The system is designed to work with multiple LLM providers:

Provider-Specific Optimization: Prompt templates are tailored to each provider's strengths
Unified Interface: A consistent interface abstracts provider differences
Dynamic Selection: The optimal provider can be chosen based on task requirements
Cost Balancing: Tasks are allocated to minimize overall cost across providers
Fallback Chains: If one provider fails, the system can automatically retry with alternatives

This flexibility ensures the system remains viable as the LLM landscape evolves.

Document Type-Specific Enhancement

Different document types receive specialized processing:

Technical Documents: Function diagrams and dependency mappings
Scientific Documents: Methodology flowcharts and result visualizations
Narrative Documents: Character relationship maps and plot progression
Business Documents: Strategic frameworks and implementation timelines
Legal Documents: Requirement hierarchies and procedural workflows

These specialized enhancements maximize the value of the generated mindmaps for different document types.

📝 Output Examples

Mermaid Syntax

mindmap
    ((📄))
        ((🏛️ Constitutional Framework))
            (📜 Historical Context)
                [🔸 The memo begins by examining the historical context of constitutional interpretation]
                [🔹 References to the Federalist Papers and early American political thought]
                [🔸 Discussion of how the Constitution was designed to balance power]
            (⚖️ Separation of Powers)
                [♦️ Detailed analysis of the three branches of government and their distinct roles]
                [🔸 Examination of checks and balances between branches]
                [🔹 Historical examples of power struggles between branches]

Markdown Outline

# Constitutional Framework
Historical Context
The memo begins by examining the historical context of constitutional interpretation
References to the Federalist Papers and early American political thought
Discussion of how the Constitution was designed to balance power
Separation of Powers
Detailed analysis of the three branches of government and their distinct roles
Examination of checks and balances between branches
Historical examples of power struggles between branches

📚 Applications and Use Cases

The Mindmap Generator excels in various scenarios:

Academic Research

Literature Review: Quickly understand the key concepts and relationships in academic papers
Thesis Organization: Structure complex research findings into coherent frameworks
Concept Mapping: Visualize theoretical relationships across multiple sources

Business Intelligence

Strategic Document Analysis: Extract actionable insights from lengthy business reports
Competitive Research: Organize information about market competitors
Policy Implementation: Break down complex policies into implementable components

Legal Analysis

Case Brief Creation: Distill lengthy legal opinions into structured hierarchies
Regulatory Compliance: Map complex regulatory requirements
Contract Review: Identify key obligations and provisions in legal documents

Educational Content

Curriculum Development: Organize educational materials into logical learning paths
Study Guide Creation: Generate comprehensive study guides from textbooks
Knowledge Mapping: Create visual representations of subject matter domains