refactor(cli): improve user messaging and code documentation

Update config validation error message to be path-agnostic since users
can pass config files from any location via command line, not just
ini/run_ini/. Remove emojis from user-facing error messages in run_gui
and run_train for cleaner output. Update TODO entries to clarify that
GUI and multi-processing features need full implementation. Standardize
docstring formatting across all CLI modules for consistency.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ryanmccann1024

fusion/cli/TODO.md

@@ -8,9 +8,9 @@
 - **Solution**: Create custom CLI error module with specific exception types (SimulationError, ConfigurationError, ResourceError, ValidationError) and user-friendly error messages
 
 ### GUI Interface Development
-- **Issue**: GUI parameter system needs expansion (`parameters/gui.py:26`)
-- **Missing**: Window sizing, themes, display options, interactive controls, real-time monitoring
-- **Solution**: Design and implement GUI-specific argument structure integrated with existing parameter system
+- **Issue**: GUI is not supported at this time and needs to be fully developed
+- **Missing**: Complete GUI implementation including window sizing, themes, display options, interactive controls, real-time monitoring, parameter configuration interface
+- **Solution**: Design and implement complete GUI system with parameter management integrated with existing CLI infrastructure
 
 ### CLI Argument Validation Enhancement
 - **Issue**: Need comprehensive CLI argument validation
@@ -21,3 +21,8 @@
 - **Issue**: CLI needs improved user experience features
 - **Missing**: Tab completion, interactive help, example suggestions, configuration file completion
 - **Solution**: Research and implement CLI completion framework with interactive help system
+
+### Multi-Processing Support
+- **Issue**: Multi-processing functionality is no longer supported in the current implementation
+- **Impact**: Users cannot run parallel simulations across multiple processes, limiting scalability for large-scale experiments
+- **Solution**: Re-implement multi-processing support with proper process management, configuration handling, and result aggregation

fusion/cli/__init__.py

@@ -1,4 +1,5 @@
-"""fusion.cli: Command-line interface entry points and argument parsing.
+"""
+fusion.cli: Command-line interface entry points and argument parsing.
 
 Provides a clean CLI architecture following the FUSION refactor plan with
 modern Python practices, comprehensive error handling, and maintainable code

fusion/cli/config_setup.py

@@ -33,7 +33,8 @@
 
 
 def normalize_config_path(config_path: str) -> str:
-    """Normalize the config file path.
+    """
+    Normalize the config file path.
 
     :param config_path: Path to config file (relative or absolute)
     :type config_path: str
@@ -55,7 +56,8 @@ def normalize_config_path(config_path: str) -> str:
 
 
 def setup_config_from_cli(args: Any) -> dict[str, Any]:
-    """Set up configuration from command line input.
+    """
+    Set up configuration from command line input.
 
     :param args: Parsed command line arguments
     :type args: Any
@@ -163,8 +165,8 @@ def _validate_config_structure(config: ConfigParser) -> None:
     if not config.has_section(REQUIRED_SECTION):
         create_directory(CONFIG_DIR_PATH)
         raise ConfigParseError(
-            f"Missing '{REQUIRED_SECTION}' section in config file. "
-            "Ensure config.ini exists in ini/run_ini/."
+            f"Missing required '{REQUIRED_SECTION}' section in config file. "
+            "Ensure your config file exists and contains all required options."
         )
 
 
@@ -192,7 +194,8 @@ def _resolve_config_path(config_path: str | None) -> str:
 def load_config(
     config_path: str | None, args_dict: dict[str, Any] | None = None
 ) -> dict[str, Any]:
-    """Load an existing config from a config file.
+    """
+    Load an existing config from a config file.
 
     This function handles the complete configuration loading process:
     1. Resolves and validates the config file path
@@ -313,7 +316,8 @@ def _find_category(
 
 
 def load_and_validate_config(args: Any) -> dict[str, Any]:
-    """Load and validate configuration from CLI arguments.
+    """
+    Load and validate configuration from CLI arguments.
 
     :param args: Parsed command line arguments
     :type args: Any
@@ -325,15 +329,17 @@ def load_and_validate_config(args: Any) -> dict[str, Any]:
 
 
 class ConfigManager:
-    """Centralized configuration management for FUSION simulator.
+    """
+    Centralized configuration management for FUSION simulator.
 
     Provides a unified interface for accessing configuration from both
     INI files and command-line arguments, with proper validation and
     error handling. Supports multi-threaded configuration sections.
     """
 
     def __init__(self, config_dict: dict[str, Any], args: Any) -> None:
-        """Initialize ConfigManager with configuration dictionary and arguments.
+        """
+        Initialize ConfigManager with configuration dictionary and arguments.
 
         :param config_dict: Parsed configuration dictionary
         :type config_dict: Dict[str, Any]
@@ -352,7 +358,8 @@ def _validate_config(self) -> None:
 
     @classmethod
     def from_args(cls, args: Any) -> "ConfigManager":
-        """Load arguments from command line input.
+        """
+        Load arguments from command line input.
 
         :param args: Parsed command line arguments
         :type args: Any
@@ -373,7 +380,8 @@ def from_args(cls, args: Any) -> "ConfigManager":
     def from_file(
         cls, config_path: str, args_dict: dict[str, Any] | None = None
     ) -> "ConfigManager":
-        """Create ConfigManager from config file path.
+        """
+        Create ConfigManager from config file path.
 
         :param config_path: Path to configuration file
         :type config_path: str
@@ -388,15 +396,17 @@ def from_file(
         return cls(config_dict, args)
 
     def as_dict(self) -> dict[str, Any]:
-        """Get config as dict.
+        """
+        Get config as dict.
 
         :return: Configuration dictionary
         :rtype: Dict[str, Any]
         """
         return self._config
 
     def get(self, thread: str = DEFAULT_THREAD_NAME) -> dict[str, Any]:
-        """Return a single config thread.
+        """
+        Return a single config thread.
 
         :param thread: Thread identifier, defaults to 's1'
         :type thread: str
@@ -409,7 +419,8 @@ def get(self, thread: str = DEFAULT_THREAD_NAME) -> dict[str, Any]:
     def get_value(
         self, key: str, thread: str = DEFAULT_THREAD_NAME, default: Any = None
     ) -> Any:
-        """Get a specific configuration value.
+        """
+        Get a specific configuration value.
 
         :param key: Configuration key
         :type key: str
@@ -424,7 +435,8 @@ def get_value(
         return thread_config.get(key, default)
 
     def has_thread(self, thread: str) -> bool:
-        """Check if a thread exists in configuration.
+        """
+        Check if a thread exists in configuration.
 
         :param thread: Thread identifier
         :type thread: str
@@ -434,15 +446,17 @@ def has_thread(self, thread: str) -> bool:
         return thread in self._config
 
     def get_threads(self) -> list[str]:
-        """Get list of all configured threads.
+        """
+        Get list of all configured threads.
 
         :return: List of thread identifiers
         :rtype: List[str]
         """
         return list(self._config.keys())
 
     def get_args(self) -> Any:
-        """Get args.
+        """
+        Get args.
 
         :return: Command line arguments
         :rtype: Any

fusion/cli/constants.py

@@ -1,4 +1,5 @@
-"""CLI-specific constants for FUSION command-line interfaces.
+"""
+CLI-specific constants for FUSION command-line interfaces.
 
 Provides shared constants used across CLI entry points including exit codes,
 argument configurations, and common CLI settings to ensure consistency

fusion/cli/main_parser.py

@@ -21,7 +21,8 @@
 
 
 def build_main_argument_parser() -> ArgumentParser:
-    """Build the main CLI argument parser with all subcommands configured.
+    """
+    Build the main CLI argument parser with all subcommands configured.
 
     Creates the primary argument parser that handles all CLI interactions
     for the FUSION simulator, including subcommands for different operations
@@ -34,7 +35,8 @@ def build_main_argument_parser() -> ArgumentParser:
 
 
 def create_training_argument_parser() -> Namespace:
-    """Create and parse arguments for training simulations (RL or ML).
+    """
+    Create and parse arguments for training simulations (RL or ML).
 
     Builds a specialized argument parser configured for machine learning
     and reinforcement learning training workflows. Includes all necessary
@@ -57,7 +59,8 @@ def create_training_argument_parser() -> Namespace:
 
 
 def create_gui_argument_parser() -> Namespace:
-    """Create and parse arguments for GUI-based simulator interface.
+    """
+    Create and parse arguments for GUI-based simulator interface.
 
     Builds a specialized argument parser configured for graphical user
     interface operations. Includes GUI-specific settings, debug options,
@@ -75,7 +78,8 @@ def create_gui_argument_parser() -> Namespace:
 
 # Backward compatibility functions
 def build_parser() -> ArgumentParser:
-    """Legacy function name for building main argument parser.
+    """
+    Legacy function name for building main argument parser.
 
     :return: Configured main parser
     :rtype: ArgumentParser
@@ -85,7 +89,8 @@ def build_parser() -> ArgumentParser:
 
 
 def get_train_args() -> Namespace:
-    """Legacy function name for creating training argument parser.
+    """
+    Legacy function name for creating training argument parser.
 
     :return: Parsed arguments for training
     :rtype: Namespace
@@ -95,7 +100,8 @@ def get_train_args() -> Namespace:
 
 
 def get_gui_args() -> Namespace:
-    """Legacy function name for creating GUI argument parser.
+    """
+    Legacy function name for creating GUI argument parser.
 
     :return: Parsed arguments for GUI
     :rtype: Namespace

fusion/cli/run_gui.py

@@ -1,4 +1,5 @@
-"""CLI entry point for launching the FUSION GUI interface.
+"""
+CLI entry point for launching the FUSION GUI interface.
 
 This module provides the command-line interface for launching the graphical
 user interface. It handles GUI dependency validation, display configuration,
@@ -15,7 +16,8 @@
 
 
 def main() -> int:
-    """Launch the FUSION GUI interface.
+    """
+    Launch the FUSION GUI interface.
 
     Parses command line arguments and delegates GUI launch operations
     to the appropriate GUI pipeline module. Handles user interruptions
@@ -32,21 +34,21 @@ def main() -> int:
 
     except KeyboardInterrupt:
         logger.info("GUI launch interrupted by user")
-        print("\n🛑 GUI launch interrupted by user")  # User-facing message
+        print("\nGUI launch interrupted by user")  # User-facing message
         return INTERRUPT_EXIT_CODE
     except (ImportError, ModuleNotFoundError) as e:
         logger.error(f"Missing GUI dependencies: {e}")
-        print(f"❌ Missing GUI dependencies: {e}")  # User-facing message
-        print("💡 Try installing GUI dependencies with: pip install -e .[gui]")
+        print(f"Missing GUI dependencies: {e}")  # User-facing message
+        print("Try installing GUI dependencies with: pip install -e .[gui]")
         return ERROR_EXIT_CODE
     except (OSError, RuntimeError) as e:
         logger.error(f"GUI framework error: {e}")
-        print(f"❌ GUI framework error: {e}")  # User-facing message
-        print("💡 Check your display settings and GUI framework installation")
+        print(f"GUI framework error: {e}")  # User-facing message
+        print("Check your display settings and GUI framework installation")
         return ERROR_EXIT_CODE
     except (ValueError, TypeError) as e:
         logger.error(f"Configuration error launching GUI: {e}")
-        print(f"❌ Configuration error launching GUI: {e}")  # User-facing message
+        print(f"Configuration error launching GUI: {e}")  # User-facing message
         return ERROR_EXIT_CODE
 
     return SUCCESS_EXIT_CODE

fusion/cli/run_sim.py

@@ -1,4 +1,5 @@
-"""CLI entry point for running simulations.
+"""
+CLI entry point for running simulations.
 
 Follows architecture best practice: entry points should have no logic.
 """
@@ -15,7 +16,8 @@
 
 
 def main(stop_flag: Any = None) -> int:
-    """Entry point for running simulations from the command line.
+    """
+    Entry point for running simulations from the command line.
 
     Delegates all logic to appropriate modules following the clean architecture
     pattern where entry points contain minimal logic and delegate to pipelines.

fusion/cli/run_train.py

@@ -1,4 +1,5 @@
-"""CLI entry point for training FUSION agents (RL or ML).
+"""
+CLI entry point for training FUSION agents (RL or ML).
 
 This module provides the command-line interface for training machine learning
 and reinforcement learning agents. It supports multiple training algorithms
@@ -15,7 +16,8 @@
 
 
 def main() -> int:
-    """Train FUSION agents using RL or ML algorithms.
+    """
+    Train FUSION agents using RL or ML algorithms.
 
     Parses command line arguments and delegates training execution to the
     appropriate training pipeline module. Supports both reinforcement learning
@@ -32,30 +34,29 @@ def main() -> int:
 
     except KeyboardInterrupt:
         logger.info("Training interrupted by user")
-        print("\n🛑 Training interrupted by user")  # User-facing message
-        print("💾 Training progress has been saved where possible")
+        print("\nTraining interrupted by user")  # User-facing message
+        print("Training progress has been saved where possible")
         return INTERRUPT_EXIT_CODE
     except (ImportError, ModuleNotFoundError) as e:
         logger.error(f"Missing training dependencies: {e}")
-        print(f"❌ Missing training dependencies: {e}")  # User-facing message
-        print("💡 Try installing ML/RL dependencies with: pip install -e .[ml,rl]")
+        print(f"Missing training dependencies: {e}")  # User-facing message
+        print("Try installing ML/RL dependencies with: pip install -e .[ml,rl]")
         return ERROR_EXIT_CODE
     except OSError as e:
         logger.error(f"File system error during training: {e}")
-        print(f"❌ File system error during training: {e}")  # User-facing message
-        print("💡 Check file permissions and available disk space for model storage")
+        print(f"File system error during training: {e}")  # User-facing message
+        print("Check file permissions and available disk space for model storage")
         return ERROR_EXIT_CODE
     except (ValueError, TypeError) as e:
         logger.error(f"Training configuration error: {e}")
-        print(f"❌ Training configuration error: {e}")  # User-facing message
-        print("💡 Check your training parameters and agent configuration")
+        print(f"Training configuration error: {e}")  # User-facing message
+        print("Check your training parameters and agent configuration")
         return ERROR_EXIT_CODE
     except (RuntimeError, MemoryError) as e:
         logger.error(f"Training runtime error: {e}")
-        print(f"❌ Training runtime error: {e}")  # User-facing message
+        print(f"Training runtime error: {e}")  # User-facing message
         print(
-            "💡 Consider reducing batch size, model complexity, "
-            "or check system resources"
+            "Consider reducing batch size, model complexity, or check system resources"
         )
         return ERROR_EXIT_CODE