dash-improve-my-llms 0.1.0

Automatic llms.txt, page.json, and architecture.txt generation for Dash applications

Dash LLMS Plugin

Automatic llms.txt, page.json, and architecture.txt generation for Dash applications, making your Dash apps LLM-friendly and comprehensively documented.

Overview

This plugin automatically generates three types of comprehensive metadata for your Dash application:

1. llms.txt - Comprehensive, context-rich description optimized for LLM understanding

   • Application context and related pages
   • Page purpose (Data Input, Visualization, Navigation, Interactive)
   • Interactive elements with detailed input/output information
   • Key content (important sections and additional content)
   • Navigation links (internal and external)
   • Component breakdown and statistics
   • Data flow and callback information
   • Technical details and narrative summary

2. page.json - Detailed architecture with interactivity and data flow

   • Complete component tree with IDs and properties
   • Component categorization (inputs, outputs, containers, navigation, display)
   • Interactivity metadata (callbacks, interactive components)
   • Navigation data (links with counts)
   • Callback information (inputs, outputs, state, data flow graph)
   • Component statistics (total, interactive, static, unique types)
   • Metadata flags (contains forms, visualizations, navigation)

3. architecture.txt - ASCII art representation of entire application

   • Environment information (Python version, Dash version)
   • Dependencies (dash-mantine-components, plotly, pandas, etc.)
   • Application configuration (multi-page, callback exceptions)
   • Callback information (total count, breakdown by module)
   • Page details (components, interactive elements, callbacks per page)
   • Route documentation
   • Application-wide statistics
   • Top component types

Features

• ✨ Automatic generation - Three comprehensive documentation files generated automatically
• 🎯 Mark important sections - Highlight key content for LLMs
• 🔄 Cascading importance - Child components inherit importance automatically
• 📄 Triple format support - llms.txt (comprehensive context), page.json (detailed architecture), architecture.txt (app overview)
• 🚀 Easy integration - One function call to enable all features
• 🔌 Compatible with Dash Pages and manual routing
• 📦 No dependencies beyond Dash itself
• 🧠 Smart context - llms.txt uses both page.json and architecture.txt data for comprehensive understanding
• 🔗 Dependency tracking - Automatically detects and documents Python packages and versions
• ⚡ Callback intelligence - Extracts and documents all callbacks with inputs, outputs, and state
• 🎨 Component categorization - Automatically categorizes components by purpose (inputs, outputs, navigation, etc.)
• 🗺️ Navigation mapping - Tracks all internal and external links
• 📊 Rich metadata - Interactivity flags, form detection, visualization detection, and more

Installation

From Source

pip install -e .

Build and Install

python -m build
pip install dist/dash_llms_plugin-0.1.0-py3-none-any.whl

Quick Start

Basic Setup with Dash Pages

from dash import Dash, html, register_page
from dash_llms_plugin import add_llms_routes

# Create your Dash app
app = Dash(__name__, use_pages=True)

# Add LLMS routes - that's it!
add_llms_routes(app)

# Define your pages as normal
register_page("home", path="/", layout=html.Div([
    html.H1("Welcome to My App")
]))

if __name__ == '__main__':
    app.run(debug=True)

Now visit:

• http://localhost:8050/llms.txt - Comprehensive LLM-friendly page context
• http://localhost:8050/page.json - Detailed technical architecture with callbacks
• http://localhost:8050/architecture.txt - ASCII art overview of entire application

Marking Important Sections

Use mark_important() to highlight key content for LLMs. All children are automatically considered important:

from dash import html
from dash_llms_plugin import mark_important

layout = html.Div([
    html.H1("My Dashboard"),
    
    # Mark this entire section as important
    mark_important(
        html.Div([
            html.H2("Critical Metrics"),
            html.P("Revenue: $1.2M"),
            html.P("Users: 50,000"),
        ], id="key-metrics")
    ),
    
    # This section won't be marked as important
    html.Div([
        html.H2("Additional Info"),
        html.P("Some supplementary information"),
    ])
])

Adding Page Metadata

Provide custom descriptions for better llms.txt generation:

from dash_llms_plugin import register_page_metadata

register_page_metadata(
    path="/dashboard",
    name="Analytics Dashboard",
    description="Real-time analytics dashboard showing key business metrics and performance indicators"
)

Complete Example

See app.py for a full working example with:

• Multiple pages (Home, Equipment, Analytics)
• Important section marking
• Custom metadata
• Integration with dash-mantine-components
• Interactive callbacks

Run it with:

python app.py

API Reference

add_llms_routes(app, config=None)

Add LLMS routes to your Dash app.

Parameters:

• app (Dash): Your Dash application instance
• config (LLMSConfig, optional): Configuration object

Example:

from dash_llms_plugin import add_llms_routes, LLMSConfig

config = LLMSConfig(
    enabled=True,
    include_css=True,
    include_callbacks=True,
    max_depth=20
)

add_llms_routes(app, config)

mark_important(component, component_id=None)

Mark a component as important for LLM context. All children inherit importance.

Parameters:

• component: Dash component to mark
• component_id (str, optional): Optional ID to track the component

Returns:

• The same component (for chaining)

Example:

important_section = mark_important(
    html.Div([
        html.H2("Key Information"),
        html.P("Critical details here")
    ], id="main-content")
)

register_page_metadata(path, name=None, description=None, **kwargs)

Register custom metadata for a page.

Parameters:

• path (str): Page URL path
• name (str, optional): Display name
• description (str, optional): Page description
• **kwargs: Additional custom metadata

Example:

register_page_metadata(
    path="/analytics",
    name="Analytics Dashboard",
    description="Interactive dashboard for business analytics",
    category="reporting",
    access_level="admin"
)

LLMSConfig

Configuration class for the LLMS plugin.

Parameters:

• enabled (bool): Enable/disable plugin (default: True)
• auto_detect_pages (bool): Auto-detect pages (default: True)
• include_css (bool): Include CSS in page.json (default: True)
• include_callbacks (bool): Include callbacks in page.json (default: True)
• max_depth (int): Maximum component tree depth (default: 20)
• exclude_patterns (list, optional): URL patterns to exclude

How It Works

llms.txt Generation

The enhanced llms.txt generation creates comprehensive, context-rich documentation by:

1. Generating page.json data first to extract complete architecture
2. Analyzing application context from Dash page registry
3. Inferring page purpose from component types (forms, visualizations, navigation)
4. Extracting interactivity information (callbacks, inputs, outputs)
5. Categorizing components by purpose and tracking all IDs
6. Mapping navigation (internal and external links)
7. Creating narrative summary that tells the "truth" of the page

Example comprehensive output:

# Equipment Catalog

> Browse and filter the complete equipment catalog with search and category filters

---

## Application Context

This page is part of a multi-page Dash application with 3 total pages.

**Related Pages:**
- Home (`/`)
- Analytics Dashboard (`/analytics`)

## Page Purpose

- **Data Input**: Contains form elements for user data entry
- **Navigation**: Provides links to other sections of the application
- **Interactive**: Responds to user interactions with dynamic updates

## Interactive Elements

This page contains **2 interactive components** with **4 callback(s)** that respond to user actions.

**User Inputs:**
- TextInput (ID: `equipment-search`) - Search equipment...
- Select (ID: `equipment-category`) - Select category

## Key Content

**Primary Information (marked as important):**
- Filters
- Search equipment...
- Select category

**Additional Content:**
- Equipment Catalog
- Equipment List
- Statistics
...

## Navigation

**Internal Links:**
- ← Back to Home → `/`
- View Analytics → → `/analytics`

## Component Breakdown

**Total Components**: 23
- Interactive: 2
- Static/Display: 21

**Component Types:**
- Div: 6
- H2: 2
- Link: 2
...

## Data Flow & Callbacks

This page has **4 callback(s)** that handle user interactions:

**Callback 1:**
- Updates: `equipment-list.children`
- Triggered by: `equipment-search.value`, `equipment-category.value`

## Technical Details

- **Path**: `/equipment`
- **Max Component Depth**: 3
- **Has Important Sections**: Yes
- **Full Architecture**: Available at `/equipment/page.json`
- **Global App Architecture**: Available at `/architecture.txt`

---

## Summary

The **Equipment Catalog** page browse and filter the complete equipment catalog...
It contains 2 interactive component(s) that allow users to input data and trigger 4 callback(s).
Users can navigate to 2 other page(s) from here.

---

*Generated with https://pip-install-python.com | dash-improve-my-llms hook*
Pip Install Python LLC | https://plotly.pro

page.json Generation

The enhanced page.json provides comprehensive technical documentation:

1. Traverses component tree recursively with full property extraction
2. Extracts all component IDs with their types, modules, and properties
3. Categorizes components by purpose (inputs, outputs, containers, navigation, display, interactive)
4. Extracts navigation links with text and destinations
5. Analyzes callbacks from the app instance (inputs, outputs, state)
6. Generates interactivity metadata (callback count, interactive component count)
7. Creates callback data flow graph showing trigger relationships

Example comprehensive output:

{
  "path": "/equipment",
  "name": "Equipment Catalog",
  "description": "Browse and filter equipment...",
  "architecture": {
    "type": "Div",
    "children_count": 4,
    "children": [...]
  },
  "components": {
    "ids": {
      "equipment-search": {
        "type": "TextInput",
        "module": "dash_mantine_components",
        "important": true,
        "props": {"placeholder": "Search equipment..."}
      }
    },
    "categories": {
      "inputs": ["equipment-search", "equipment-category"],
      "outputs": [],
      "containers": ["filters", "..."],
      "navigation": ["Link-...", "..."],
      "interactive": ["equipment-search", "equipment-category"]
    },
    "types": {
      "Div": 6,
      "TextInput": 1,
      "Select": 1
    },
    "counts": {
      "total": 23,
      "interactive": 2,
      "static": 21,
      "unique_types": 8
    }
  },
  "interactivity": {
    "has_callbacks": true,
    "callback_count": 4,
    "interactive_components": 2,
    "inputs": ["equipment-search", "equipment-category"],
    "outputs": []
  },
  "navigation": {
    "links": [
      {"href": "/", "text": "← Back to Home", "type": "Link"},
      {"href": "/analytics", "text": "View Analytics →", "type": "Link"}
    ],
    "outbound_count": 2,
    "external_count": 0
  },
  "metadata": {
    "has_important_sections": true,
    "max_depth": 3,
    "contains_forms": true,
    "contains_visualizations": false,
    "contains_navigation": true
  },
  "callbacks": {
    "list": [
      {
        "output": "equipment-list.children",
        "inputs": ["equipment-search.value", "equipment-category.value"],
        "state": []
      }
    ],
    "graph": {
      "equipment-list.children": {
        "triggers": ["equipment-search.value", "equipment-category.value"]
      }
    }
  }
}

architecture.txt Generation

The architecture.txt provides a bird's-eye view of your entire application:

1. Detects environment (Python version, Dash version)
2. Scans dependencies (automatically detects dash-mantine-components, plotly, pandas, etc.)
3. Analyzes application config (multi-page, callback exceptions)
4. Extracts callback information grouped by module
5. Summarizes all pages with component counts, interactive elements, callbacks
6. Documents routes (pages and documentation routes)
7. Generates statistics (total pages, callbacks, components, interactive components)
8. Lists top components across the entire application

Example output:

================================================================================
                         DASH APPLICATION ARCHITECTURE
================================================================================

┌─ ENVIRONMENT
│
├─── Python Version: 3.11.8
├─── Dash Version: 3.3.0
├─── Key Dependencies:
│    ├─── dash-mantine-components==2.3.0
│    ├─── plotly==6.0.1
│    └─── pandas==2.2.3
│
├─ APPLICATION
│
├─── Name: Dash
├─── Server: app
├─── Multi-Page: Yes
├─── Suppress Callback Exceptions: True
│
├─ CALLBACKS
│
├─── Total Callbacks: 4
├─── By Module:
│    ├─── pages.equipment: 1 callback(s)
│    ├─── pages.analytics: 1 callback(s)
│    └─── dash.dash: 1 callback(s)
│
├─ PAGES
│  ├── Home
│      ├─ Path: /
│      ├─ Module: pages.home
│      ├─ Description: Welcome page for the Equipment Management System...
│      ├─ Components: 35
│      ├─ Interactive: 0
│      ├─ Callbacks: 0
│      └─ Types: Div, H1, text, P, H2
│
│  ├── Equipment Catalog
│      ├─ Path: /equipment
│      ├─ Module: pages.equipment
│      ├─ Description: Browse and filter the complete equipment catalog...
│      ├─ Components: 23
│      ├─ Interactive: 2
│      ├─ Callbacks: 1
│      └─ Types: Div, H1, text, H2, TextInput
│
├─ ROUTES
│  ├── Documentation Routes:
│  │   ├── /llms.txt (current page context)
│  │   ├── /page.json (current page architecture)
│  │   ├── /architecture.txt (global architecture)
│  │   └── /<page_path>/llms.txt (specific page)
│  ├── Page Routes:
│  │   ├─── / (Home)
│  │   ├─── /equipment (Equipment Catalog)
│  │   └─── /analytics (Analytics Dashboard)
│
├─ STATISTICS
│  ├── Total Pages: 3
│  ├── Total Callbacks: 4
│  ├── Total Components: 99
│  ├── Interactive Components: 3
│  └── Unique Component Types: 11
│
├─ TOP COMPONENTS
│  ├── Div: 45
│  ├── text: 38
│  ├── P: 8
│  ├── Li: 7
│  └── H2: 5
│
└─ END

================================================================================
*Generated with https://pip-install-python.com | dash-improve-my-llms hook*
Pip Install Python LLC | https://plotly.pro
================================================================================

Use Cases

For AI Assistants

LLMs can use these files to:

• Understand page structure and content
• Answer questions about your app
• Help debug layout issues
• Generate documentation
• Suggest improvements

For Documentation

• Auto-generate API docs
• Create user guides
• Build sitemaps
• Generate component inventories

For Development

• Understand page complexity
• Track component usage
• Identify optimization opportunities
• Document application architecture

Compatibility

• Dash: 3.2.0+
• Dash Mantine Components: 2.3.0+ (optional)
• Python: 3.8+

Works with:

• ✅ Dash Pages (dash.register_page)
• ✅ Manual routing (dcc.Location)
• ✅ Multi-page apps
• ✅ Single-page apps
• ✅ All Dash component libraries

Advanced Usage

Custom Content Extraction

You can customize how content is extracted by extending the plugin:

from dash_llms_plugin import extract_text_content

# Custom extraction for your components
def my_custom_extractor(component):
    texts = extract_text_content(component)
    # Add custom logic here
    return texts

Integration with Existing Routes

The plugin uses Dash hooks to add routes non-invasively:

# Your existing routes work unchanged
@app.server.route('/api/data')
def get_data():
    return jsonify({"status": "ok"})

# LLMS routes are added automatically
add_llms_routes(app)

Programmatic Access

Access the generated content programmatically:

from dash_llms_plugin import generate_llms_txt, generate_page_json

# Generate for a specific layout
llms_content = generate_llms_txt("/mypage", my_layout_function)
page_arch = generate_page_json("/mypage", my_layout_function)

print(llms_content)
print(json.dumps(page_arch, indent=2))

Troubleshooting

Routes not working?

Make sure you call add_llms_routes() after creating your app:

app = Dash(__name__, use_pages=True)
add_llms_routes(app)  # Add this!

Content not showing?

Check that your page is registered correctly:

import dash
print(dash.page_registry)  # Should show your pages

Important sections not marked?

Verify the component has an id:

mark_important(
    html.Div([...], id="my-section")  # ID is important!
)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Credits

Built for the Dash community. Inspired by the llms.txt specification and the dmc-docs.

Related Projects

• llms-txt - Original llms.txt Python library
• Dash - Python framework for building web apps
• Dash Mantine Components - Modern component library

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Dash Community Forum

---

Made with ❤️ for the Dash community