Skip to content

🏗️ Consolidate multiple launch scripts into unified launcher with enhanced UX #537

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

🏗️ Consolidate multiple launch scripts into unified launcher with enhanced UX #537

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dcd5d2a
Initial plan
Copilot Sep 14, 2025
81f4516
Enhanced unified launcher with comprehensive migration support and va…
Copilot Sep 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
225 changes: 164 additions & 61 deletions UNIFIED_LAUNCHER_README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,205 @@
# Unified Launcher for Deep Tree Echo

This document describes the unified launcher system that consolidates the multiple launch scripts in the Deep Tree Echo project.
This document describes the enhanced unified launcher system that consolidates multiple launch scripts in the Deep Tree Echo project into a single, powerful entry point.

## Overview

The unified launcher system addresses the architecture gap of having multiple launch scripts by providing a single, configurable backend that all launch scripts can use. This reduces code duplication while maintaining backward compatibility.
The unified launcher system addresses the architecture gap of having multiple launch scripts by providing a single, comprehensive frontend (`launch.py`) backed by the `unified_launcher.py` module. This dramatically reduces code duplication while maintaining backward compatibility and providing enhanced user experience.

## Components
## Enhanced Features

### 🚀 Single Entry Point
- **Primary launcher**: `python launch.py [mode] [options]`
- **Comprehensive help**: Includes migration examples and mode-specific guidance
- **Interactive validation**: `--validate-config` for dry-run testing
- **Migration guidance**: `--migration-guide` for detailed transition help

### Core Module
- `unified_launcher.py` - The main unified launcher implementation
### 📋 Configuration Management
- **Robust validation**: Port conflicts, invalid paths, and option compatibility checking
- **Enhanced error messages**: Clear, actionable feedback with emoji indicators
- **Dry-run mode**: Test configurations without launching

### Launch Scripts (Updated to use unified launcher)
- `launch_deep_tree_echo.py` - Main async system launcher
- `launch_dashboards.py` - Dashboard process manager
- `launch_gui.py` - Comprehensive GUI launcher
- `launch_gui_standalone.py` - Simplified GUI launcher
### 🔄 Migration Support
- **Backward compatibility**: All legacy scripts work with deprecation warnings
- **Clear migration path**: Step-by-step guidance for transitioning from old scripts
- **Enhanced warnings**: Legacy scripts show detailed migration instructions

## Components

## Usage
### Core Modules
- `launch.py` - Enhanced primary entry point with comprehensive UX
- `unified_launcher.py` - The unified launcher backend implementation

All existing launch scripts continue to work with their original command-line interfaces:
### Legacy Scripts (Deprecated but Functional)
- `launch_deep_tree_echo.py` - **Use**: `python launch.py deep-tree-echo`
- `launch_dashboards.py` - **Use**: `python launch.py dashboards`
- `launch_gui.py` - **Use**: `python launch.py gui`
- `launch_gui_standalone.py` - **Use**: `python launch.py gui-standalone`

## Usage Examples

### Quick Start
```bash
# Launch Deep Tree Echo with GUI and browser
python launch_deep_tree_echo.py --gui --browser --debug
# Show all available modes with migration guidance
python launch.py --list-modes

# Launch both dashboards
python launch_dashboards.py --web-port 8080 --gui-port 5000
# Get comprehensive help
python launch.py --help

# Launch GUI dashboard only
python launch_gui.py --debug --no-activity
# Show detailed migration guide
python launch.py --migration-guide

# Launch standalone GUI
python launch_gui_standalone.py --no-activity
# Validate configuration without launching (dry-run)
python launch.py gui --validate-config --debug
```

## Unified Launcher Modes
### Launch Modes
```bash
# Full Deep Tree Echo system with GUI and browser automation
python launch.py deep-tree-echo --gui --browser --debug

# GUI dashboard with activity monitoring disabled
python launch.py gui --no-activity --debug

The unified launcher supports the following modes:
# Lightweight standalone GUI
python launch.py gui-standalone --no-activity

1. **deep-tree-echo** - Full async system with all components
2. **gui** - GUI dashboard with full component initialization
3. **gui-standalone** - Simplified GUI with minimal dependencies
4. **web** - Web dashboard only
5. **dashboards** - Process manager for multiple dashboards
# Web dashboard on custom port
python launch.py web --port 9000

## Configuration
# Both dashboards with custom ports
python launch.py dashboards --web-port 8080 --gui-port 5000

The `LauncherConfig` class provides a unified configuration interface:
# Dashboard manager - web only
python launch.py dashboards --web-only --web-port 8080
```

### Migration Examples
```bash
# OLD: python launch_deep_tree_echo.py --gui --browser --debug
# NEW: python launch.py deep-tree-echo --gui --browser --debug

# OLD: python launch_dashboards.py --web-port 8080 --gui-port 5000 --gui-only
# NEW: python launch.py dashboards --web-port 8080 --gui-port 5000 --gui-only

```python
from unified_launcher import LauncherConfig, LaunchMode
# OLD: python launch_gui.py --debug --no-activity --log-file gui.log
# NEW: python launch.py gui --debug --no-activity --log-file gui.log

config = LauncherConfig(
mode=LaunchMode.DEEP_TREE_ECHO,
debug=True,
gui=True,
browser=True,
storage_dir="custom_storage"
)
# OLD: python launch_gui_standalone.py --no-activity
# NEW: python launch.py gui-standalone --no-activity
```

## Benefits
## Enhanced Benefits

### ✅ User Experience
- **Single command to remember**: `python launch.py`
- **Comprehensive help system**: Context-sensitive guidance
- **Configuration validation**: Catch errors before launching
- **Clear migration path**: Step-by-step transition guidance

### ✅ Technical Improvements
- **Code consolidation**: Reduced from 943+ lines across 4 scripts to unified backend
- **Consistent argument parsing**: Standardized across all modes
- **Enhanced error handling**: Better validation and user feedback
- **Maintainability**: Single source of truth for launch logic

### ✅ Developer Benefits
- **Extensible architecture**: Easy to add new launch modes
- **Comprehensive testing**: 23+ tests covering all functionality
- **Backward compatibility**: No breaking changes to existing workflows
- **Future-proof design**: Foundation for additional enhancements

✅ **Code Consolidation**: Reduced from 943 lines across 4 scripts to 671 total lines
✅ **Unified Configuration**: Single configuration system for all launch modes
✅ **Consistent Error Handling**: Standardized logging and error management
✅ **Backward Compatibility**: All existing scripts work unchanged
✅ **Maintainability**: Single source of truth for launch logic
✅ **Extensibility**: Easy to add new launch modes
## Configuration Options

The enhanced launcher supports comprehensive configuration validation:

### Port Validation
- **Range checking**: Ports must be 1-65535
- **Privilege warnings**: Alerts for ports < 1024
- **Conflict detection**: Prevents same port for different services

### Path Validation
- **Storage directory**: Validates and creates if needed
- **Log file paths**: Checks writability and creates directories

### Option Compatibility
- **Mode-specific validation**: Ensures options match selected mode
- **Conflict detection**: Catches incompatible option combinations
- **Warning system**: Non-fatal issues reported as warnings

## Testing

Run the test suite to verify functionality:
The launcher includes comprehensive test coverage:

```bash
# Test unified launcher backend
python test_unified_launcher.py

# Test main launcher frontend
python test_main_launcher.py

# Test enhanced features
python test_enhanced_launcher_features.py
```

### Test Coverage
- ✅ Configuration validation (11 test cases)
- ✅ Mode selection and argument parsing (8 test cases)
- ✅ Backend launcher functionality (4 test cases)
- ✅ Legacy script compatibility
- ✅ Migration guidance features
- ✅ Error handling and validation

## Architecture

The unified launcher uses a strategy pattern with different launch modes:
The enhanced unified launcher uses a layered architecture:

```
unified_launcher.py
├── LauncherConfig (configuration)
├── UnifiedLauncher (main class)
├── LaunchMode (enum of available modes)
└── Mode-specific launch methods
├── _launch_deep_tree_echo()
├── _launch_gui_dashboard()
├── _launch_web_dashboard()
└── _launch_dashboard_manager()
launch.py (Enhanced Frontend)
├── Enhanced UX Features
│ ├── Migration guidance (--migration-guide)
│ ├── Mode listing (--list-modes)
│ ├── Configuration validation (--validate-config)
│ └── Enhanced help and error messages
├── Configuration Management
│ ├── validate_configuration()
│ ├── create_main_parser()
│ └── Enhanced argument validation
└── unified_launcher.py (Backend)
├── LauncherConfig (configuration)
├── UnifiedLauncher (main class)
├── LaunchMode (enum of available modes)
└── Mode-specific launch methods
├── _launch_deep_tree_echo()
├── _launch_gui_dashboard()
├── _launch_web_dashboard()
└── _launch_dashboard_manager()
```

Each existing launch script now acts as a thin wrapper that:
1. Parses command-line arguments using the unified parser
2. Creates a configuration object
3. Delegates to the unified launcher
## Migration Strategy

### Phase 1: Awareness (Current)
- ✅ Legacy scripts show deprecation warnings
- ✅ Enhanced warnings include migration examples
- ✅ Documentation updated with migration guidance

### Phase 2: Transition (Recommended)
- Update documentation to use new launcher
- Update deployment scripts and CI/CD pipelines
- Train users on new interface

### Phase 3: Deprecation (Future)
- Remove legacy scripts
- Archive old documentation
- Update integration points

## Deep Tree Echo Integration

The unified launcher maintains full compatibility with Deep Tree Echo's neural architecture:

- **Echo State Networks**: Preserved in all launch modes
- **P-System Hierarchies**: Maintained through configuration system
- **Hypergraph Memory**: Consistent across launch methods
- **Recursive Architecture**: Reflected in modular design

This approach maintains the original interfaces while eliminating code duplication and providing a foundation for future enhancements.
This consolidation strengthens the Deep Tree Echo framework by providing a single, reliable entry point that embodies the system's principles of recursive enhancement and adaptive integration.
Loading
Loading