open-swarm 0.1.1743070217__py3-none-any.whl → 0.1.1743364176__py3-none-any.whl

swarm/extensions/blueprint/blueprint_discovery.py

@@ -1,112 +1,126 @@
-"""
-Blueprint Discovery Module for Open Swarm MCP.
-
-This module dynamically discovers and imports blueprints from specified directories.
-It identifies classes derived from BlueprintBase as valid blueprints and extracts their metadata.
-"""
-
+import os
+import importlib
 import importlib.util
 import inspect
-import logging
-import os
+import logging # Ensure logging is imported
+import sys
+from typing import Dict, Type, Any
 from pathlib import Path
-from typing import Dict, List, Any
-from swarm.settings import DEBUG
 
+# *** Define logger EARLIER ***
 logger = logging.getLogger(__name__)
-logger.setLevel(logging.DEBUG if DEBUG else logging.INFO)
 
+# *** Import the ACTUAL BlueprintBase from the likely correct path ***
 try:
-    from .blueprint_base import BlueprintBase
-except ImportError as e:
-    logger.critical(f"Failed to import BlueprintBase: {e}")
-    raise
-
-def discover_blueprints(directories: List[str]) -> Dict[str, Dict[str, Any]]:
+    # Adjust this path if BlueprintBase lives elsewhere
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError:
+    # This logger call is now safe
+    logger.error("Failed to import BlueprintBase from swarm.extensions.blueprint.blueprint_base. Using placeholder.", exc_info=True)
+    class BlueprintBase: # Fallback placeholder
+        metadata: Dict[str, Any] = {}
+        def __init__(self, *args, **kwargs): pass
+        async def run(self, *args, **kwargs): pass
+
+
+class BlueprintLoadError(Exception):
+    """Custom exception for errors during blueprint loading."""
+    pass
+
+def _get_blueprint_name_from_dir(dir_name: str) -> str:
+    """Converts directory name (e.g., 'blueprint_my_agent') to blueprint name (e.g., 'my_agent')."""
+    prefix = "blueprint_"
+    if dir_name.startswith(prefix):
+        return dir_name[len(prefix):]
+    return dir_name
+
+def discover_blueprints(blueprint_dir: str) -> Dict[str, Type[BlueprintBase]]:
     """
-    Discover and load blueprints from specified directories.
-    Extract metadata including title, description, and other attributes.
+    Discovers blueprints (subclasses of BlueprintBase) by looking for
+    'blueprint_{name}.py' files within subdirectories of the given blueprint directory.
 
     Args:
-        directories (List[str]): List of directories to search for blueprints.
+        blueprint_dir: The path to the directory containing blueprint subdirectories.
 
     Returns:
-        Dict[str, Dict[str, Any]]: Dictionary containing blueprint metadata.
+        A dictionary mapping blueprint names to their corresponding class objects.
     """
-    blueprints = {}
-    logger.info("Starting blueprint discovery.")
-    swarm_blueprints = os.getenv("SWARM_BLUEPRINTS", "").split(",")
-    if swarm_blueprints and swarm_blueprints[0]:
-        logger.debug(f"Filtering blueprints to: {swarm_blueprints}")
-
-    for directory in directories:
-        logger.debug(f"Searching for blueprints in: {directory}")
-        dir_path = Path(directory)
-
-        if not dir_path.exists() or not dir_path.is_dir():
-            logger.warning(f"Invalid directory: {directory}. Skipping...")
-            continue
-
-        for blueprint_file in dir_path.rglob("blueprint_*.py"):
-            module_name = blueprint_file.stem
-            blueprint_name = module_name.replace("blueprint_", "")
-            if swarm_blueprints and swarm_blueprints[0] and blueprint_name not in swarm_blueprints:
-                logger.debug(f"Skipping blueprint '{blueprint_name}' not in SWARM_BLUEPRINTS")
-                continue
-            module_path = str(blueprint_file.parent)
-
-            logger.debug(f"Found blueprint file: {blueprint_file}")
-            logger.debug(f"Module name: {module_name}, Blueprint name: {blueprint_name}, Module path: {module_path}")
-
-            try:
-                spec = importlib.util.spec_from_file_location(module_name, str(blueprint_file))
-                if spec is None or spec.loader is None:
-                    logger.error(f"Cannot load module spec for blueprint file: {blueprint_file}. Skipping.")
-                    continue
-                module = importlib.util.module_from_spec(spec)
-                spec.loader.exec_module(module)
-                logger.debug(f"Successfully imported module: {module_name}")
-
-                for name, obj in inspect.getmembers(module, inspect.isclass):
-                    if not issubclass(obj, BlueprintBase) or obj is BlueprintBase:
-                        continue
-
-                    logger.debug(f"Discovered blueprint class: {name}")
-
-                    try:
-                        metadata = obj.metadata
-                        if callable(metadata):
-                            metadata = metadata()
-                        elif isinstance(metadata, property):
-                            if metadata.fget is not None:
-                                metadata = metadata.fget(obj)
-                            else:
-                                logger.error(f"Blueprint '{blueprint_name}' property 'metadata' has no getter.")
-                                raise ValueError(f"Blueprint '{blueprint_name}' metadata is inaccessible.")
-
-                        if not isinstance(metadata, dict):
-                            logger.error(f"Metadata for blueprint '{blueprint_name}' is not a dictionary.")
-                            raise ValueError(f"Metadata for blueprint '{blueprint_name}' is invalid or inaccessible.")
-
-                        if "title" not in metadata or "description" not in metadata:
-                            logger.error(f"Required metadata fields (title, description) are missing for blueprint '{blueprint_name}'.")
-                            raise ValueError(f"Metadata for blueprint '{blueprint_name}' is invalid or inaccessible.")
-
-                    except Exception as e:
-                        logger.error(f"Error retrieving metadata for blueprint '{blueprint_name}': {e}")
-                        continue
-
-                    blueprints[blueprint_name] = {
-                        "blueprint_class": obj,
-                        "title": metadata["title"],
-                        "description": metadata["description"],
-                    }
-                    logger.debug(f"Added blueprint '{blueprint_name}' with metadata: {metadata}")
-            except ImportError as e:
-                logger.error(f"Failed to import module '{module_name}': {e}")
-            except Exception as e:
-                logger.error(f"Unexpected error importing '{module_name}': {e}", exc_info=True)
-
-    logger.info("Blueprint discovery complete.")
-    logger.debug(f"Discovered blueprints: {list(blueprints.keys())}")
+    logger.info(f"Starting blueprint discovery in directory: {blueprint_dir}")
+    blueprints: Dict[str, Type[BlueprintBase]] = {}
+    base_dir = Path(blueprint_dir).resolve()
+
+    if not base_dir.is_dir():
+        logger.error(f"Blueprint directory not found or is not a directory: {base_dir}")
+        return blueprints
+
+    # Iterate over items inside the base blueprint directory
+    for item_name in os.listdir(base_dir):
+        item_path = base_dir / item_name
+
+        if not item_path.is_dir():
+            continue # Skip files directly under blueprints/
+
+        # Use directory name as blueprint name (e.g., 'echocraft')
+        blueprint_name = item_name
+        logger.debug(f"Processing potential blueprint '{blueprint_name}' in directory: {item_name}")
+
+        # Look for the specific .py file, e.g., blueprint_echocraft.py
+        py_file_name = f"blueprint_{blueprint_name}.py"
+        py_file_path = item_path / py_file_name
+
+        if not py_file_path.is_file():
+            # Also check for just {blueprint_name}.py if that's a convention
+            alt_py_file_name = f"{blueprint_name}.py"
+            alt_py_file_path = item_path / alt_py_file_name
+            if alt_py_file_path.is_file():
+                 py_file_path = alt_py_file_path # Use the alternative path
+                 py_file_name = alt_py_file_name
+                 logger.debug(f"Found alternative blueprint file: {py_file_name}")
+            else:
+                 logger.warning(f"Skipping directory '{item_name}': Neither '{py_file_name}' nor '{alt_py_file_name}' found.")
+                 continue
+
+
+        # Construct module import path, e.g., blueprints.echocraft.blueprint_echocraft
+        module_import_path = f"{base_dir.name}.{item_name}.{py_file_path.stem}"
+
+        try:
+            # Ensure parent directory is in path
+            parent_dir = str(base_dir.parent)
+            if parent_dir not in sys.path:
+                 logger.debug(f"Adding '{parent_dir}' to sys.path for blueprint discovery.")
+                 sys.path.insert(0, parent_dir)
+
+            # Create module spec from file path
+            module_spec = importlib.util.spec_from_file_location(module_import_path, py_file_path)
+
+            if module_spec and module_spec.loader:
+                module = importlib.util.module_from_spec(module_spec)
+                sys.modules[module_import_path] = module
+                module_spec.loader.exec_module(module)
+                logger.debug(f"Successfully loaded module: {module_import_path}")
+
+                found_bp_class = None
+                for name, obj in inspect.getmembers(module):
+                    if inspect.isclass(obj) and obj.__module__ == module_import_path and issubclass(obj, BlueprintBase) and obj is not BlueprintBase:
+                        if found_bp_class:
+                            logger.warning(f"Multiple BlueprintBase subclasses found in {py_file_name}. Using the first: {found_bp_class.__name__}.")
+                        else:
+                            logger.debug(f"Found Blueprint class '{name}' in module '{module_import_path}'")
+                            found_bp_class = obj
+                            blueprints[blueprint_name] = found_bp_class
+                            # break
+
+                if not found_bp_class:
+                    logger.warning(f"No BlueprintBase subclass found directly defined in module: {module_import_path}")
+            else:
+                logger.warning(f"Could not create module spec for {py_file_path}")
+
+        except Exception as e:
+            logger.error(f"Error processing blueprint file '{py_file_path}': {e}", exc_info=True)
+            if module_import_path in sys.modules:
+                 del sys.modules[module_import_path]
+
+    logger.info(f"Blueprint discovery complete. Found: {list(blueprints.keys())}")
     return blueprints
+

swarm/extensions/blueprint/cli_handler.py

@@ -0,0 +1,185 @@
+import argparse
+import asyncio
+import json
+import logging
+import signal
+import sys
+from pathlib import Path
+from typing import Any, Dict, Optional, Type
+
+# Import BlueprintBase type hint carefully
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .blueprint_base import BlueprintBase
+
+logger = logging.getLogger("swarm.cli")
+
+async def _run_blueprint_async_with_shutdown(blueprint: 'BlueprintBase', instruction: str):
+    """Runs the blueprint's async method and handles graceful shutdown."""
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+
+    def signal_handler():
+        print("\n[bold yellow]Shutdown signal received. Attempting graceful exit...[/bold yellow]", file=sys.stderr)
+        logger.warning("Shutdown signal received.")
+        stop_event.set()
+
+    # Add signal handlers for SIGINT (Ctrl+C) and SIGTERM
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, signal_handler)
+        except NotImplementedError:
+            # Fallback for Windows or environments where add_signal_handler is not supported
+            try:
+                # signal.signal must be called in the main thread
+                signal.signal(sig, lambda s, f: loop.call_soon_threadsafe(signal_handler))
+                logger.debug(f"Registered signal handler for {sig.name} using signal.signal fallback.")
+            except ValueError as e:
+                 logger.error(f"Could not set signal handler for {sig.name} using fallback: {e}. Graceful shutdown via signal might not work.")
+            except Exception as e:
+                 logger.error(f"Unexpected error setting fallback signal handler for {sig.name}: {e}", exc_info=True)
+
+
+    # Wrap the main execution in a task to allow cancellation
+    main_task = loop.create_task(blueprint._run_non_interactive(instruction), name=f"BlueprintRun_{blueprint.__class__.__name__}")
+
+    # Wait for either the main task or the stop event
+    done, pending = await asyncio.wait(
+        [main_task, loop.create_task(stop_event.wait(), name="ShutdownWatcher")],
+        return_when=asyncio.FIRST_COMPLETED
+    )
+
+    # Cleanup signal handlers after wait returns
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.remove_signal_handler(sig)
+        except NotImplementedError:
+            try:
+                signal.signal(sig, signal.SIG_DFL) # Restore default handler
+            except Exception:
+                pass # Ignore errors during cleanup
+
+    # Check if the stop event was triggered
+    if stop_event.is_set():
+        logger.warning("Graceful shutdown initiated. Cancelling main task...")
+        if not main_task.done():
+            main_task.cancel()
+            try:
+                # Wait briefly for cancellation to propagate and cleanup within the task
+                await asyncio.wait_for(main_task, timeout=10.0) # Increased timeout slightly
+            except asyncio.CancelledError:
+                logger.info("Main task successfully cancelled.")
+            except asyncio.TimeoutError:
+                logger.error("Main task did not cancel within timeout. Potential resource leak.")
+            except Exception as e:
+                logger.error(f"Error during task cancellation waiting: {e}", exc_info=True)
+        else:
+            logger.info("Main task already completed before cancellation request.")
+        # The _run_non_interactive's AsyncExitStack should handle MCP cleanup
+    else:
+        # If the main task finished first, check for exceptions
+        if main_task in done:
+            try:
+                main_task.result() # Raise exception if one occurred in the task
+                logger.debug("Main task completed successfully.")
+            except asyncio.CancelledError:
+                 logger.info("Main task was cancelled externally (unexpected).")
+            except Exception as e:
+                # Error should have been logged within _run_non_interactive
+                # We exit here because the main operation failed
+                logger.critical(f"Blueprint execution failed with unhandled exception: {e}", exc_info=True)
+                sys.exit(1) # Exit with error status if task failed
+
+
+def run_blueprint_cli(
+    blueprint_cls: Type['BlueprintBase'],
+    swarm_version: str,
+    default_config_path: Path
+):
+    """
+    Parses CLI arguments, instantiates, and runs a blueprint.
+
+    Args:
+        blueprint_cls (Type[BlueprintBase]): The blueprint class to run.
+        swarm_version (str): The core swarm version string.
+        default_config_path (Path): Default path to swarm_config.json.
+    """
+    # --- Argument Parsing ---
+    metadata = getattr(blueprint_cls, 'metadata', {})
+    parser = argparse.ArgumentParser(
+        description=metadata.get("description", f"Run {blueprint_cls.__name__}"),
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("--instruction", type=str, required=True, help="Initial instruction for the blueprint.")
+    parser.add_argument("--config-path", type=str, default=None, help=f"Path to swarm_config.json (Default: {default_config_path})")
+    parser.add_argument("--config", type=str, metavar="JSON_FILE_OR_STRING", default=None, help="JSON config overrides (file path or string). Merged last.")
+    parser.add_argument("--profile", type=str, default=None, help="Configuration profile to use.")
+    parser.add_argument("--debug", action="store_true", help="Enable DEBUG logging level.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress most logs and headers, print only final output.")
+    parser.add_argument('--markdown', action=argparse.BooleanOptionalAction, default=None, help="Enable/disable markdown output (--markdown / --no-markdown). Overrides config/default.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s (BP: {metadata.get('name', 'N/A')} v{metadata.get('version', 'N/A')}, Core: {swarm_version})")
+    args = parser.parse_args()
+
+    # --- Load CLI Config Overrides ---
+    cli_config_overrides = {}
+    if args.config:
+        config_arg = args.config
+        config_override_path = Path(config_arg)
+        temp_logger = logging.getLogger("swarm.cli.config") # Temp logger for this part
+        if config_override_path.is_file():
+            temp_logger.info(f"Attempting to load CLI config overrides from file: {config_override_path}")
+            try:
+                with open(config_override_path, "r", encoding="utf-8") as f:
+                    cli_config_overrides = json.load(f)
+                temp_logger.debug(f"Loaded overrides keys: {list(cli_config_overrides.keys())}")
+            except Exception as e:
+                temp_logger.error(f"Failed to load --config file: {e}", exc_info=args.debug)
+                sys.exit(f"Error reading config override file: {e}")
+        else:
+            temp_logger.info("Attempting to parse --config argument as JSON string.")
+            try:
+                cli_config_overrides = json.loads(config_arg)
+                if not isinstance(cli_config_overrides, dict):
+                    raise TypeError("--config JSON string must resolve to a dictionary.")
+                temp_logger.debug(f"--config JSON string parsed successfully. Keys: {list(cli_config_overrides.keys())}")
+            except Exception as e:
+                temp_logger.error(f"Failed parsing --config JSON string: {e}")
+                sys.exit(f"Error: Invalid --config value: {e}")
+
+    # --- Instantiate and Run Blueprint ---
+    blueprint_instance: Optional['BlueprintBase'] = None
+    try:
+        # Instantiate the blueprint, passing necessary config/flags
+        blueprint_instance = blueprint_cls(
+            config_path_override=args.config_path,
+            profile_override=args.profile,
+            config_overrides=cli_config_overrides,
+            debug=args.debug,
+            quiet=args.quiet,
+            force_markdown=args.markdown,
+            # Pass necessary context if needed by __init__
+            # default_config_path=default_config_path,
+            # swarm_version=swarm_version
+        )
+
+        # Run the async part with shutdown handling
+        asyncio.run(_run_blueprint_async_with_shutdown(blueprint_instance, args.instruction))
+
+    except (ValueError, TypeError, FileNotFoundError) as config_err:
+        logger.critical(f"[Initialization Error] Configuration problem: {config_err}", exc_info=args.debug)
+        sys.exit(1)
+    except ImportError as ie:
+        # Catch potential issues if dependencies are missing
+        logger.critical(f"[Import Error] Failed to import required module for {blueprint_cls.__name__}: {ie}. Please check dependencies.", exc_info=args.debug)
+        sys.exit(1)
+    except KeyboardInterrupt:
+         logger.info("Execution interrupted by user (KeyboardInterrupt).")
+         # Should be handled by signal handler now, but keep as fallback
+         sys.exit(130) # Standard exit code for Ctrl+C
+    except Exception as e:
+        logger.critical(f"[Execution Error] An unexpected error occurred: {e}", exc_info=True)
+        sys.exit(1)
+    finally:
+        logger.debug("Blueprint CLI execution finished.")
+        # Any final cleanup outside the async loop (rarely needed here)
+

swarm/extensions/blueprint/config_loader.py

@@ -0,0 +1,122 @@
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from dotenv import load_dotenv
+
+logger = logging.getLogger("swarm.config")
+
+def _substitute_env_vars(value: Any) -> Any:
+    """Recursively substitute environment variables in strings, lists, and dicts."""
+    if isinstance(value, str):
+        return os.path.expandvars(value)
+    elif isinstance(value, list):
+        return [_substitute_env_vars(item) for item in value]
+    elif isinstance(value, dict):
+        return {k: _substitute_env_vars(v) for k, v in value.items()}
+    else:
+        return value
+
+def load_environment(project_root: Path):
+    """Loads environment variables from a `.env` file located at the project root."""
+    dotenv_path = project_root / ".env"
+    logger.debug(f"Checking for .env file at: {dotenv_path}")
+    try:
+        if dotenv_path.is_file():
+            loaded = load_dotenv(dotenv_path=dotenv_path, override=True)
+            if loaded:
+                logger.debug(f".env file Loaded/Overridden at: {dotenv_path}")
+        else:
+            logger.debug(f"No .env file found at {dotenv_path}.")
+    except Exception as e:
+        logger.error(f"Error loading .env file '{dotenv_path}': {e}", exc_info=logger.level <= logging.DEBUG)
+
+def load_full_configuration(
+    blueprint_class_name: str,
+    default_config_path: Path,
+    config_path_override: Optional[Union[str, Path]] = None,
+    profile_override: Optional[str] = None,
+    cli_config_overrides: Optional[Dict[str, Any]] = None,
+) -> Dict[str, Any]:
+    """
+    Loads and merges configuration settings from base file, blueprint specifics, profiles, and CLI overrides.
+
+    Args:
+        blueprint_class_name (str): The name of the blueprint class (e.g., "MyBlueprint").
+        default_config_path (Path): The default path to the swarm_config.json file.
+        config_path_override (Optional[Union[str, Path]]): Path specified via CLI argument.
+        profile_override (Optional[str]): Profile specified via CLI argument.
+        cli_config_overrides (Optional[Dict[str, Any]]): Overrides provided via CLI argument.
+
+    Returns:
+        Dict[str, Any]: The final, merged configuration dictionary.
+
+    Raises:
+        ValueError: If the configuration file has JSON errors or cannot be read.
+        FileNotFoundError: If a specific config_path_override is given but the file doesn't exist.
+    """
+    config_path = Path(config_path_override) if config_path_override else default_config_path
+    logger.debug(f"Attempting to load base configuration from: {config_path}")
+    base_config = {}
+    if config_path.is_file():
+        try:
+            with open(config_path, "r", encoding="utf-8") as f:
+                base_config = json.load(f)
+            logger.debug(f"Successfully loaded base configuration from: {config_path}")
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Config Error: Failed to parse JSON in {config_path}: {e}") from e
+        except Exception as e:
+            raise ValueError(f"Config Error: Failed to read {config_path}: {e}") from e
+    else:
+        if config_path_override:
+            raise FileNotFoundError(f"Configuration Error: Specified config file not found: {config_path}")
+        else:
+            logger.warning(f"Default configuration file not found at {config_path}. Proceeding without base configuration.")
+
+    # 1. Start with base defaults
+    final_config = base_config.get("defaults", {}).copy()
+    logger.debug(f"Applied base defaults. Keys: {list(final_config.keys())}")
+
+    # 2. Merge base llm and mcpServers sections
+    if "llm" in base_config:
+        final_config.setdefault("llm", {}).update(base_config["llm"])
+        logger.debug("Merged base 'llm'.")
+    if "mcpServers" in base_config:
+        final_config.setdefault("mcpServers", {}).update(base_config["mcpServers"])
+        logger.debug("Merged base 'mcpServers'.")
+
+    # 3. Merge blueprint-specific settings
+    blueprint_settings = base_config.get("blueprints", {}).get(blueprint_class_name, {})
+    if blueprint_settings:
+        final_config.update(blueprint_settings)
+        logger.debug(f"Merged BP '{blueprint_class_name}' settings. Keys: {list(blueprint_settings.keys())}")
+
+    # 4. Determine and merge profile settings
+    # Priority: CLI > Blueprint Specific > Base Defaults > "default"
+    profile_in_bp_settings = blueprint_settings.get("default_profile")
+    profile_in_base_defaults = base_config.get("defaults", {}).get("default_profile")
+    profile_to_use = profile_override or profile_in_bp_settings or profile_in_base_defaults or "default"
+    logger.debug(f"Using profile: '{profile_to_use}'")
+    profile_settings = base_config.get("profiles", {}).get(profile_to_use, {})
+    if profile_settings:
+        final_config.update(profile_settings)
+        logger.debug(f"Merged profile '{profile_to_use}'. Keys: {list(profile_settings.keys())}")
+    elif profile_to_use != "default" and (profile_override or profile_in_bp_settings or profile_in_base_defaults):
+        logger.warning(f"Profile '{profile_to_use}' requested but not found.")
+
+    # 5. Merge CLI overrides (highest priority)
+    if cli_config_overrides:
+        final_config.update(cli_config_overrides)
+        logger.debug(f"Merged CLI overrides. Keys: {list(cli_config_overrides.keys())}")
+
+    # Ensure top-level keys exist
+    final_config.setdefault("llm", {})
+    final_config.setdefault("mcpServers", {})
+
+    # 6. Substitute environment variables in the final config
+    final_config = _substitute_env_vars(final_config)
+    logger.debug("Applied final env var substitution.")
+
+    return final_config