ASCII Graphics in Documentation¶
This document summarizes all the ASCII diagrams added to enhance the documentation.
Overview¶
ASCII graphics help visualize complex concepts throughout the documentation. They provide: - System architecture understanding - Data flow visualization - Concept illustration - Network topology examples
Graphics Added¶
1. System Architecture (README.md)¶
Location: Main README.md, after "Key Features"
Purpose: Shows how the three interfaces (API, CLI, REPL) connect to the YAML DSL core
┌─────────────────────────────────────────────────────────────────┐
│ Three User Interfaces │
├───────────────────┬─────────────────────┬──────────────────────┤
│ Fluent API │ CLI Commands │ Interactive REPL │
│ (Python) │ (Bash/Scripts) │ (Exploration) │
└─────────┬─────────┴──────────┬──────────┴───────────┬──────────┘
│ │ │
└────────────────────┼───────────────────────┘
│
┌────────▼────────┐
│ YAML DSL │◀── Core Abstraction
└─────────────────┘
│
[Components Below]
Key insight: All interfaces converge on the YAML DSL as the single source of truth.
2. Traditional vs Complex Network RAG (docs/CONCEPTS.md)¶
Location: CONCEPTS.md, beginning
Purpose: Compare traditional RAG architecture with Complex Network RAG
Traditional RAG:
┌──────────┐ ┌───────────┐ ┌─────────┐ ┌─────────────┐
│ Document │───▶│ Embed │───▶│ Vector │───▶│ Top-K │
│ (Text) │ │ (Single) │ │ DB │ │ Similarity │
└──────────┘ └───────────┘ └─────────┘ └─────────────┘
Complex Network RAG:
┌──────────────────┐
│ Document │
│ {title: "...", │
│ abstract: "..."|
│ tags: [...]} │
└────────┬─────────┘
│
▼
┌─────────────────────────────────────┐
│ Structured Similarity │
│ ┌───────────┐ ┌───────────┐ │
│ │ Field │ │ Attribute │ │
│ │Embeddings │ │Similarity │ │
│ └─────┬─────┘ └─────┬─────┘ │
└───────────────┼───────────────────┘
▼
[Similarity Graph & Topology-Aware Retrieval]
Key insight: Shows progression from simple to structured approach.
3. Similarity Matrix to Graph (docs/CONCEPTS.md)¶
Location: CONCEPTS.md, "Network Topology" section
Purpose: Illustrate how similarity matrices are filtered into graphs
Step 1: Compute Pairwise Similarity
┌─────┬─────┬─────┬─────┐
│ │ A │ B │ C │
├─────┼─────┼─────┼─────┤
│ A │ 1.0 │ 0.7 │ 0.3 │
│ B │ 0.7 │ 1.0 │ 0.5 │
│ C │ 0.3 │ 0.5 │ 1.0 │
└─────┴─────┴─────┴─────┘
Step 2: Filter by Threshold (≥ 0.4)
A ────── B
│
C
Key insight: Threshold filters weak connections, creating meaningful structure.
4. Component Weight Visualization (docs/CONCEPTS.md)¶
Location: CONCEPTS.md, "Weight Normalization" section
Purpose: Visual representation of how weights combine
Title [██████████████████████████████] 30%
Abstract [██████████████████████████████████████████████████] 50%
Tags [████████████████████] 20%
Combined Similarity = 0.3×sim(title) + 0.5×sim(abstract) + 0.2×sim(tags)
Key insight: Makes weight proportions immediately visible.
5. Network Topology with Communities (docs/CONCEPTS.md)¶
Location: CONCEPTS.md, "Communities" section
Purpose: Show communities, hubs, and bridges in action
Community 0 (ML) Community 1 (Medical)
┌─────────────────────┐ ┌─────────────────────┐
│ A ─── B ─── C │ │ G ─── H ─── I │
│ │ │ │ │ │ │ │ │ │
│ D ─── E ─── F ────┼──────┼─→ J ─── K ─── L │
│ │ │Bridge│ │ │
│ M (Hub) │ │ N │
│ │ │ │ │ │ │
│ O P Q │ └─────────────────────┘
└─────────────────────┘
Legend:
• Nodes (A-Q): Documents
• ─── : Strong similarity edge
• Hub (M): High degree (connects many docs)
• Bridge (F-J): Connects communities (cross-domain)
• Dense clusters: Communities (related topics)
Key insight: Visualizes the three key network properties: communities, hubs, bridges.
6. YAML Data Flow (docs/YAML_DSL_REFERENCE.md)¶
Location: YAML_DSL_REFERENCE.md, after "Overview"
Purpose: Show how YAML flows through the entire system
┌──────────────────┐
│ YAML File │
│ papers.yaml │
└────────┬─────────┘
│ parse
▼
┌─────────────────────────────────┐
│ YAMLConfigParser │
│ • Validates syntax │
│ • Checks required fields │
└────────┬────────────────────────┘
│ builds
▼
┌─────────────────────────────────┐
│ StructuredSimilaritySpec │
│ • DocumentSpec │
│ • List[SimilarityComponent] │
└────────┬────────────────────────┘
│ passed to
▼
┌─────────────────────────────────┐
│ NetworkRAG │
└────────┬────────────────────────┘
│ processes
▼
┌─────────────────────────────────┐
│ Documents │
│ {title: "...", abstract: "..."}│
└────────┬────────────────────────┘
│ computes
▼
┌─────────────────────────────────┐
│ Field-Specific Embeddings │
└────────┬────────────────────────┘
│ combines
▼
┌─────────────────────────────────┐
│ Similarity Scores │
└────────┬────────────────────────┘
│ builds
▼
┌─────────────────────────────────┐
│ Knowledge Graph │
└─────────────────────────────────┘
Key insight: Complete end-to-end data transformation pipeline.
7. Learning Pathway (docs/GETTING_STARTED.md)¶
Location: GETTING_STARTED.md, after Table of Contents
Purpose: Show progressive learning levels with time estimates
Level 1: Simple Text Documents
┌──────────────────────────────┐
│ Plain text → Embeddings → │
│ Basic similarity matching │
└──────────┬───────────────────┘
│
▼
Level 2: Network Structure
┌──────────────────────────────┐
│ Similarity graph → │
│ Communities, hubs, bridges │
└──────────┬───────────────────┘
│
▼
Level 3: Structured Documents
┌──────────────────────────────┐
│ Field-specific embeddings → │
│ Hybrid similarity (YAML) │
└──────────┬───────────────────┘
│
▼
Level 4: Production Use
┌──────────────────────────────┐
│ Choose your interface: │
│ • REPL (exploration) │
│ • CLI (automation) │
│ • API (integration) │
└──────────────────────────────┘
Key insight: Clear progression from beginner to advanced user with time estimates.
Design Principles for ASCII Graphics¶
1. Clarity Over Complexity¶
- Use simple box-drawing characters (┌─┐│└┘├┤┬┴┼)
- Avoid overly dense diagrams
- Leave whitespace for readability
2. Consistent Style¶
- Boxes for components/modules
- Arrows (→, ▼) for data flow
- Double lines for emphasis where needed
3. Annotations¶
- Always include legends when symbols are ambiguous
- Add brief explanations below diagrams
- Use bullet points for key insights
4. Progressive Detail¶
- Start with high-level overview
- Add detail in subsequent diagrams
- Reference previous diagrams when building on concepts
Benefits¶
For New Users¶
- Visual learning: Many people understand diagrams faster than text
- Concrete examples: Abstract concepts become tangible
- Navigation: Graphics act as visual anchors in long documents
For Documentation Quality¶
- Professional appearance: Well-crafted ASCII art signals attention to detail
- Self-contained: No external image dependencies
- Version control friendly: Text-based diagrams diff well in Git
- Terminal compatible: Readable in CLI, web browsers, and text editors
For Complex Concepts¶
- Network topology: Impossible to explain hubs/bridges without visual
- Data flow: Shows transformations step-by-step
- Architecture: System structure at a glance
- Comparisons: Side-by-side traditional vs new approach
Files Modified¶
- README.md: System architecture diagram
- docs/CONCEPTS.md: 4 diagrams
- Traditional vs Complex Network RAG
- Similarity matrix to graph
- Component weight bars
- Network topology with communities
- docs/YAML_DSL_REFERENCE.md: YAML data flow
- docs/GETTING_STARTED.md: Learning pathway
Total: 7 major ASCII graphics across 4 files
Maintenance¶
ASCII graphics should be: - Updated when architecture changes - Simplified if feedback suggests they're too complex - Extended as new features are added - Tested in different terminal widths (80, 120 columns)
Future Enhancements¶
Potential additional graphics: - Chunking strategies visualization (sentence vs fixed vs sliding) - Aggregation method comparisons (weighted_avg vs max_pool) - Retrieval strategy flowcharts - Performance scaling graphs (ASCII bar charts) - Configuration template comparisons
Impact: ASCII graphics transform the documentation from text-heavy to visual-first, making complex concepts immediately graspable and significantly improving the learning experience.