Skip to content

AGENTS.md

Latest commit

 

History

History
552 lines (391 loc) · 17.5 KB

AGENTS.md

File metadata and controls

552 lines (391 loc) · 17.5 KB
Raw

Advanced Visualization Module - Agent Scaffolding

Module Overview

Purpose: Advanced visualization artifact generation for GNN models: statistical panels, POMDP plots, network metrics, optional Plotly/HTML dashboards, and optional D2 diagrams

Pipeline Step: Step 9: Advanced visualization (9_advanced_viz.py)

Category: Advanced Visualization / Interactive Analysis

Status: Maintained

Version: 1.6.0

Last Updated: 2026-04-16

Core Functionality

Primary Responsibilities

  1. Generate 3D-style visualization artifacts
  2. Create optional HTML dashboard artifacts
  3. Produce advanced statistical plots
  4. Generate optional interactive HTML visualizations when dependencies and flags allow
  5. Provide multi-dimensional model summaries
  6. Generate professional D2 (Declarative Diagramming) diagrams

Key Capabilities

  • 3D network topology visualization
  • Interactive Plotly dashboards
  • Multi-panel comparative analysis
  • HTML-based interactive reports
  • D2 diagram generation for GNN models and pipeline architecture

API Reference

Public Functions

process_advanced_viz(target_dir, output_dir, logger, **kwargs) -> bool | int

Description: Main advanced visualization processing function called by orchestrator (9_advanced_viz.py). Implementation: processor.py.

Parameters:

  • target_dir (Path): Directory containing GNN files
  • output_dir (Path): Output directory for visualizations
  • logger (Logger): Logger instance
  • viz_type (str): Visualization type ("all", "3d", "interactive", "dashboard", "d2", "diagrams", "pipeline", "statistical", "pomdp", "network", default: "all")
  • interactive (bool): Enable interactive features (default: True)
  • export_formats (List[str]): Export formats ["html", "json", "png"], default: ["html", "json"]
  • `kwargs: Additional options

Returns: True when at least one advanced visualization artifact is produced, 2 when the step completes with warning-only recovery such as missing Step 3 model data or optional-only skips, and False for hard failures.

Example:

from advanced_visualization.processor import process_advanced_viz

success = process_advanced_viz(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/9_advanced_viz_output"),
    logger=logger,
    viz_type="all",
    interactive=True,
    export_formats=["html", "json"]
)

Visualization Types

3D Visualization

  • Network topology in 3D space with semantic positioning
  • State space visualization with force-directed layout
  • Connection strength representation with real POMDP data
  • Interactive hover information with variable details

Statistical Analysis Plots

  • Variable type distribution pie charts
  • Variable dimension distribution analysis
  • Scalar parameter value histograms
  • Matrix size distribution analysis
  • Matrix correlation heatmaps between all matrices
  • Comprehensive statistical overview panels

POMDP-Specific Visualizations

  • Transition Matrix Analysis: B matrix visualization with action-specific slices
  • Policy Visualization: Policy distribution over actions (π and E matrices)
  • 3D Transition Visualization: Multi-action transition matrix heatmaps
  • State-Action Relationships: Visual representation of POMDP dynamics

Network Analysis Visualizations

  • Network Metrics: Node count, edge count, density, clustering coefficients
  • Centrality Analysis: Degree centrality and node importance rankings
  • Network Graph Visualization: Force-directed layout with connection visualization
  • Connection Strength Analysis: Edge weight and connection pattern analysis
  • Network Statistics: Comprehensive network topology metrics

Interactive Plotly Dashboards

  • Multi-Panel Dashboard: Variable types, matrix overview, network graph, statistics
  • Interactive Matrix Explorer: Zoom, pan, and explore matrix heatmaps
  • Export Support: HTML output when requested and available
  • Static Fallbacks: Recorded skips or static artifacts when optional dependencies are unavailable

Interactive Dashboard

  • Model-summary dashboard artifacts when requested and interactive=True
  • Multi-view reports assembled from extracted model data
  • HTML-based interactive reports

D2 Diagram Generation (NEW)

  • GNN Model Structure: Visualize state space components, connections, and Active Inference ontology
  • POMDP Diagrams: Generative model components (A, B, C, D, E matrices) and inference processes
  • Pipeline Architecture: Complete 25-step pipeline flow with data dependencies
  • Framework Integration: Mapping of GNN models to PyMDP, RxInfer.jl, ActiveInference.jl, DisCoPy, JAX
  • Active Inference Concepts: Free Energy Principle, perception-action loops, belief updating
  • Multiple Output Formats: SVG, PNG, PDF with professional themes
  • Layout Engines: Dagre (fast), ELK (quality), TALA (advanced)

See D2_README.md for comprehensive D2 integration documentation.

Configuration

Configuration Options

Visualization Type Selection

  • viz_type (str): Type of visualization to generate
    • "all": Generate all visualization types (default)
    • "3d": Only 3D network visualizations
    • "interactive": Only interactive Plotly dashboards
    • "dashboard": Only dashboard interfaces
    • "d2" or "diagrams": Only D2 diagram generation
    • "pipeline": Only pipeline D2 diagrams
    • "statistical": Statistical analysis plots (distributions, correlations, histograms)
    • "pomdp": POMDP-specific visualizations (transitions, policies, beliefs)
    • "network": Network analysis visualizations (metrics, centrality, connection strength)

Interactive Features

  • interactive (bool): Enable interactive features (default: True)
    • When True: Allows interactive/dashboard branches for matching viz_type values
    • When False: Skips interactive/dashboard branches

Export Formats

  • export_formats (List[str]): Formats to export (default: ["html", "json"])
    • Supported by Step 9 core outputs: ["html", "json", "png"]
    • D2 diagrams support additional formats when the D2 CLI is installed

No model data is a warning-only outcome, not artifact success. viz_type and interactive gate output creation; interactive dashboards are generated only when an interactive type is requested and interactive=True.

D2 Configuration

  • d2_layout_engine (str): Layout engine for D2 diagrams (default: "dagre")
    • Options: "dagre" (fast), "elk" (quality), "tala" (advanced)
  • d2_theme (str): Theme for D2 diagrams (default: "default")
    • Options: "default", "dark", "light", "professional"

No additional public performance-tuning flags are documented for this module. Generate a narrower viz_type or use interactive=False to reduce work.

Dependencies

Required Dependencies

  • matplotlib - Basic plotting
  • numpy - Numerical operations

Optional Dependencies

  • plotly - Interactive visualizations (recovery: static plots)
  • seaborn - Enhanced statistical plots (recovery: matplotlib)
  • d2 CLI - D2 diagram compilation (recovery: skip D2 diagrams, log warning)

Usage Examples

Basic Usage

from advanced_visualization.processor import process_advanced_viz

success = process_advanced_viz(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/9_advanced_viz_output"),
    logger=logger,
    viz_type="all"
)

Interactive Dashboard

success = process_advanced_viz(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/9_advanced_viz_output"),
    logger=logger,
    viz_type="dashboard",
    interactive=True,
    export_formats=["html", "json"]
)

D2 Diagram Generation (NEW)

# Generate only D2 diagrams
success = process_advanced_viz(
    target_dir=Path("input/gnn_files"),
    output_dir=Path("output/9_advanced_viz_output"),
    logger=logger,
    viz_type="d2"  # or "diagrams" or "pipeline"
)

# Programmatic D2 usage
from advanced_visualization.d2_visualizer import D2Visualizer

visualizer = D2Visualizer(logger=logger)
if visualizer.d2_available:
    # Generate all diagrams for a model
    results = visualizer.generate_all_diagrams_for_model(
        model_data,
        output_dir,
        formats=["svg", "png"]
    )

Output Specification

Output Products

  • {model}_3d_visualization.html - 3D interactive plot
  • {model}_dashboard.html - Interactive dashboard
  • {model}_statistical_analysis.png - Statistical plots
  • {model}_visualization_data.json - Underlying data
  • d2_diagrams/{model}/ - D2 diagram files (.d2, .svg, .png)
  • d2_diagrams/pipeline/ - Pipeline architecture D2 diagrams
  • advanced_viz_summary.json - Processing summary

Output Directory Structure

output/9_advanced_viz_output/
├── model_name_3d_visualization.html
├── model_name_dashboard.html
├── model_name_statistical_analysis.png
├── model_name_visualization_data.json
├── d2_diagrams/
│   ├── model_name/
│   │   ├── model_name_structure.d2
│   │   ├── model_name_structure.svg
│   │   ├── model_name_structure.png
│   │   ├── model_name_pomdp.d2
│   │   ├── model_name_pomdp.svg
│   │   └── model_name_pomdp.png
│   └── pipeline/
│       ├── gnn_pipeline_flow.d2
│       ├── gnn_pipeline_flow.svg
│       ├── framework_integration.d2
│       ├── framework_integration.svg
│       ├── active_inference_concepts.d2
│       └── active_inference_concepts.svg
└── advanced_viz_summary.json

Performance Characteristics

Measurement Policy

  • This document is not the source of fixed runtime or memory numbers.
  • Measure current performance from a fresh local or CI run when making a performance claim.
  • Use narrower viz_type values or interactive=False when a run should avoid optional dashboard work.
  • Treat optional dependency skips and no-data outcomes through the documented warning-code path rather than as artifact success.

Error Handling

Graceful Degradation

  • No Plotly: Generate static/matplotlib artifacts where supported
  • No D2 CLI: Skip D2-specific diagram rendering and report the optional dependency state
  • Large Models: Prefer narrower viz_type runs and recorded warnings
  • Parsing Failures: Return structured error information
  • Missing Dependencies: Use available libraries with fallbacks

Robust Error Recovery

  • Data Loading: Multiple recovery paths for finding GNN models
  • Visualization Generation: Individual method error isolation
  • File I/O: Safe file operations with proper cleanup
  • Memory Management: Proper resource cleanup and monitoring

Recent Improvements

Comprehensive Module Enhancement

Major Fixes Applied:

  1. Data Loading: Fixed GNN model discovery and loading from processing results
  2. Visualization Implementation: Uses real matplotlib-based visualizations
  3. Import Structure: Corrected module imports and dependencies
  4. Error Handling: Added comprehensive error handling and recovery mechanisms
  5. Test Coverage: Created 17 comprehensive tests covering all functionality

Key Improvements:

  • 3D-style scatter plots with variable type color coding
  • Statistical analysis with pie charts, bar charts, and model metrics
  • Data extraction with graceful error handling
  • Optional HTML dashboard generation with interactive components
  • Matplotlib backend configuration for noninteractive execution environments

Latest Major Enhancement (October 13, 2025)

Expanded from 2 to 8 comprehensive visualization types:

  1. 3D Visualization - Network topology in 3D space with semantic positioning and real connections
  2. Statistical Analysis - POMDP-specific statistical analysis with real data and metrics
  3. State Transitions - Conceptual state transition diagrams with real POMDP relationships
  4. Belief Evolution - Belief state evolution over time, free energy landscape, policy confidence
  5. Policy Visualization - Policy distribution, expected free energy analysis, policy convergence
  6. Matrix Correlations - Matrix size comparison, correlation heatmaps, matrix type distribution
  7. Timeline Visualization - POMDP model development timeline, computational complexity evolution
  8. State Space Analysis - Comprehensive state space connectivity and manifold analysis
  9. Belief Flow Visualization - Information flow diagrams and belief update process visualization

Integration Points

Pipeline Integration

  • Input: Receives processed GNN models from Step 3 (gnn processing)
  • Output: Generates visualizations consumed by Step 20 (website generation) and Step 23 (report generation)
  • Dependencies: Requires GNN parsing results from 3_gnn.py output

Module Dependencies

  • gnn/: Reads parsed GNN model data and structure
  • visualization/: Complements basic visualization with advanced features
  • export/: Uses export formats for visualization data serialization

External Integration

  • D2 CLI: Integrates with D2 diagramming tool for professional diagrams
  • Plotly: Optional integration for interactive visualizations

Data Flow

3_gnn.py (GNN parsing)
  ↓
9_advanced_viz.py (Advanced visualization)
  ↓
  ├→ 20_website.py (HTML integration)
  ├→ 23_report.py (Report generation)
  └→ output/9_advanced_viz_output/ (Standalone visualizations)

Testing

Test Files

  • src/tests/advanced_visualization/test_advanced_visualization_overall.py ✅
  • src/tests/advanced_visualization/test_advanced_visualization_shared.py ✅

Test Coverage

Measure on demand:

uv run --extra dev python -m pytest src/tests/test_advanced_visualization*.py \
    --cov=src/advanced_visualization --cov-report=term-missing

Test Categories

  • Unit: module imports, instantiation, basic API surface
  • Integration: data extraction, end-to-end visualization generation
  • Error handling: missing dependencies, malformed content, degraded paths
  • Performance: execution time / resource usage smoke tests

MCP Integration

Tools Registered

  • process_advanced_visualization - Run Step 9 advanced visualization processing for a target directory
  • check_visualization_capabilities - Report optional dependency and feature availability
  • list_d2_visualization_types - List D2 diagram categories and D2 requirements
  • get_advanced_visualization_module_info - Return module metadata, feature flags, and tool inventory

Tool Endpoints

def process_advanced_visualization_mcp(
    target_directory: str,
    output_directory: str,
    verbose: bool = False,
    generate_d2: bool = True,
) -> Dict[str, Any]:
    """Process advanced visualization for GNN files."""

MCP File Location

  • src/advanced_visualization/mcp.py - MCP tool registrations

Troubleshooting

Common Issues

Issue 1: D2 diagram generation fails

Symptom: D2 diagrams not generated or errors during generation
Cause: Missing D2 CLI tool or invalid diagram syntax
Solution:

  • Install D2: brew install d2 (macOS) or download from d2lang.com
  • Verify D2 installation: d2 --version
  • Check diagram syntax in generated D2 files
  • Use --verbose flag for detailed error messages

Issue 2: Interactive visualizations not displaying

Symptom: HTML files generated but visualizations not interactive
Cause: Missing Plotly JavaScript or browser compatibility
Solution:

  • Ensure Plotly is installed: uv pip install plotly
  • Open HTML files in modern browser (Chrome, Firefox, Safari)
  • Check browser console for JavaScript errors

Issue 3: 3D visualizations fail to render

Symptom: 3D visualization generation errors
Cause: Missing 3D plotting dependencies or insufficient resources
Solution:

  • Install required dependencies: uv pip install plotly numpy
  • Reduce model complexity for 3D rendering
  • Use 2D recovery visualizations

Performance Issues

Slow Dashboard Generation

Symptoms: Dashboard generation takes longer than expected
Diagnosis:

# Enable verbose logging
python src/9_advanced_viz.py --target-dir input/ --verbose

Solutions:

  • Generate specific visualization types instead of "all"
  • Disable interactive features if not needed
  • Process files individually instead of batch

Version History

Current Version: 1.6.0

Features:

  • 3D network visualization
  • Interactive Plotly dashboards
  • D2 diagram generation
  • Statistical analysis plots
  • POMDP-specific visualizations
  • Network analysis visualizations

Known Issues:

  • None currently

Roadmap

  • Next Version: Enhanced D2 diagram features
  • Future: Explicit live or streaming contracts only after implementation and tests exist

References

Related Documentation

External Resources

Last Updated: 2026-05-12 Maintainer: GNN Pipeline Team Status: Maintained Version: 1.6.0 Architecture Compliance: Thin Orchestrator Pattern

Documentation

  • README: Module Overview
  • AGENTS: Agentic Workflows
  • SPEC: Architectural Specification
  • SKILL: Capability API