gui

GUI Module (Interactive GNN Constructors)

Overview

The GUI module provides three distinct interactive interfaces for constructing and editing GNN models:

GUI 1: Form-based Interactive GNN Constructor

• Interactive two-pane editor for GNN models
• Left panel (Controls):
  • Components tab: add/remove components, set type (observation/hidden/action/policy), and manage states
  • State Space tab: live list of state-space entries with name, dimensions, type; add/update/remove entries
• Right panel: synchronized plaintext GNN markdown editor
• Edits are immediately reflected in the markdown
• Access: http://localhost:7860

GUI 2: Visual Matrix Editor

• Visual drag-and-drop matrix editing interface
• Interactive heatmaps and plots for matrix visualization
• Real-time GNN markdown generation from visual edits
• POMDP template-based initialization
• Multi-tab interface for A, B, C, D matrices
• Matrix validation and consistency checking
• Access: http://localhost:7861

GUI 3: State Space Design Studio

• 🎨 Visual state space designer with interactive diagrams
• 📚 Ontology term editor for Active Inference concepts
• 🔗 Connection graph interface with SVG visualization
• ⚙️ Parameter tuning controls (states, observations, actions)
• 💾 Real-time GNN export and preview functionality
• 🎯 Low-dependency HTML/CSS design approach
• Access: http://localhost:7862

Usage

# Run all available GUIs (default)
python src/22_gui.py --target-dir input/gnn_files --output-dir output --verbose

# Run specific GUI
python src/22_gui.py --gui-mode gui_1 --target-dir input/gnn_files --output-dir output --verbose
python src/22_gui.py --gui-mode gui_2 --target-dir input/gnn_files --output-dir output --verbose
python src/22_gui.py --gui-mode gui_3 --target-dir input/gnn_files --output-dir output --verbose

# Run multiple specific GUIs
python src/22_gui.py --gui-mode "gui_1,gui_2,gui_3" --target-dir input/gnn_files --output-dir output --verbose

• With dependencies available, local web UIs launch (in-browser). Otherwise, headless artifacts are generated.

Headless Mode

• If GUIs cannot be launched (or headless=True):
  • GUI-specific status JSON files summarize backend availability and export paths
  • Starter GNN markdown files are created for each GUI
  • Visual matrix data exported as JSON (GUI 2)

Output Structure

• Standard pipeline mapping: output/22_gui_output/
  • constructed_model_gui1.md: GUI 1 output - Form-based constructed GNN model
  • visual_model_gui2.md: GUI 2 output - Visual matrix editor GNN model
  • visual_matrices.json: GUI 2 output - Matrix data and visualizations
  • gui_status.json: GUI execution status and backend information
  • gui_processing_summary.json: Overall processing summary with results from all GUIs
  • navigation.html: Comprehensive HTML navigation page linking to all pipeline outputs

Navigation.html

The navigation.html file provides a centralized navigation interface for all pipeline outputs:

• Pipeline Overview: Summary statistics (total steps, total files)
• Output Sections: Organized by all 25 pipeline steps with file listings
• File Metadata: File type, size, and direct links to all artifacts
• Integration: Links to comprehensive reports and visualizations
• Access: Open output/22_gui_output/navigation.html in a web browser

Public API

from gui import (
  # Main processing function
  process_gui,
  
  # Individual GUI runners
  gui_1,
  gui_2,
  gui_3,
  
  # Information functions
  get_available_guis,
  get_gui_1_info,
  get_gui_2_info,
  get_gui_3_info,
  
  # Navigation generation
  generate_html_navigation,
  
  # GUI 1 utilities
  add_component_to_markdown,
  update_component_states,
  remove_component_from_markdown,
  parse_components_from_markdown,
  parse_state_space_from_markdown,
  add_state_space_entry,
  update_state_space_entry,
  remove_state_space_entry,
)

Individual GUI Functions

gui_1(target_dir: Path, output_dir: Path, logger: Logger, **kwargs) -> Dict[str, Any]
gui_2(target_dir: Path, output_dir: Path, logger: Logger, **kwargs) -> Dict[str, Any]
gui_3(target_dir: Path, output_dir: Path, logger: Logger, **kwargs) -> Dict[str, Any]

• Launch specific GUI implementations
• Returns execution results and status information

process_gui (Main Function)

process_gui(
  target_dir: Path,
  output_dir: Path,
  verbose: bool = False,
  gui_types: List[str] = ['gui_1', 'gui_2'],  # Which GUIs to run
  headless: bool = False,
  open_browser: bool = True,
  **kwargs
) -> bool

• Orchestrates execution of multiple GUI implementations
• Returns True if all requested GUIs succeed

Architecture

Modular Structure

graph TD
    User([User]) --> Selector{GUI Selector}
    
    Selector -->|GUI 1| Form[Form-based Editor]
    Selector -->|GUI 2| Visual[Matrix Editor]
    Selector -->|GUI 3| Design[Design Studio]
    
    Form --> API[GUI API]
    Visual --> API
    Design --> API
    
    API --> GNN[GNN Markdown]
    API --> JSON[JSON Models]
    
    API -->|Validation| Check[Consistency Check]
    Check -->|Valid| Save[Save Model]
    Check -->|Invalid| Feedback[Error Feedback]

Loading

Adding New GUIs

To add a new GUI (e.g., gui_4):

1. Create gui_4/ subfolder with implementation
2. Add gui_4() function in gui_4/__init__.py
3. Update gui/__init__.py to import and expose gui_4
4. Update 22_gui.py to handle gui_4 in processing logic
5. Add port assignment and URL mapping

Example completed: GUI 3 (State Space Design Studio) follows this pattern.

Setup via UV

• Step 1 installs GUI extras (--extra gui) to include Gradio. To install manually:

uv sync --extra gui

Notes

• Degrades gracefully if Gradio is not installed (headless artifact generation).
• Designed for modularity: logic isolated in markdown.py, UI wiring in ui.py, thin orchestration in processor.py.

---

Documentation

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