open-swarm 0.1.1744943015__py3-none-any.whl → 0.1.1744943085__py3-none-any.whl

{open_swarm-0.1.1744943015.dist-info → open_swarm-0.1.1744943085.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-swarm
-Version: 0.1.1744943015
+Version: 0.1.1744943085
 Summary: Open Swarm: Orchestrating AI Agent Swarms with Django
 Project-URL: Homepage, https://github.com/yourusername/open-swarm
 Project-URL: Documentation, https://github.com/yourusername/open-swarm/blob/main/README.md

{open_swarm-0.1.1744943015.dist-info → open_swarm-0.1.1744943085.dist-info}/RECORD

@@ -49,6 +49,26 @@ swarm/blueprints/unapologetic_press/blueprint_unapologetic_press.py,sha256=MDegK
 swarm/blueprints/whiskeytango_foxtrot/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 swarm/blueprints/whiskeytango_foxtrot/apps.py,sha256=V1QKvyb2Vz-EtDNhhNe4tw2W9LYhNDuiaIq_fAU4ilw,334
 swarm/blueprints/whiskeytango_foxtrot/blueprint_whiskeytango_foxtrot.py,sha256=8PjKGDHSTaQ76DXPD3T4MXQ8uLIlm4xmJ5s0i64a_Jw,16179
+swarm/core/agent_utils.py,sha256=exKnbJEm1VRL270x6XqQXHtJhqD8ogY3ZBIGZO_tYUE,552
+swarm/core/blueprint_base.py,sha256=YRn8wYfOAnLlO40x7M-m9gcl2dCnq8uuwRiqEicQwN8,18602
+swarm/core/blueprint_discovery.py,sha256=rNbfe0D98kfWiW5MdushT8405899tfm_hnpVN5jDg_Q,5688
+swarm/core/blueprint_runner.py,sha256=TIfcIFfW86gCIeYs67ePmurKRPrcGgVYmVFGbpNuojQ,2576
+swarm/core/blueprint_utils.py,sha256=Ef_pu-RYomqzFjMg6LOSPSdbYFCbYXjEoSvK1OT49Eo,702
+swarm/core/build_launchers.py,sha256=Eh3ODR9L4KinG1GDK4-lF3NE0EZ-ArCrP3fxtGYhXgs,433
+swarm/core/build_swarm_wrapper.py,sha256=c_9oR3To4M2cZyc1uYSiysHLhUGX5FkCAQk9AG7Va2Q,231
+swarm/core/common_utils.py,sha256=jeKcN3lMdrpOYWIpErH3L5am13jHjaImpVvk2b0mps4,462
+swarm/core/config_loader.py,sha256=ldQGtv4tXeDJzL2GCylDxykZxYBo4ALFY2kS0jZ79Eo,5652
+swarm/core/config_manager.py,sha256=rRTBpqVJrJdHzJ8GD_PCtt6NHfB7_gJmpWkqzy_M-nk,10599
+swarm/core/output_utils.py,sha256=HGpXIujoJNM5nCCzXH0Upog_ctw5BuftmMBiPujh-ZM,7139
+swarm/core/server_config.py,sha256=v2t7q22qZwMAPdiUZreQaLAy1706k3VbR8Wk0NCQuCQ,3224
+swarm/core/setup_wizard.py,sha256=yAZ7MOgc8ZGti2kjZ72G6QLFBI0lbhXAa7Wi7SeXDYo,4567
+swarm/core/slash_commands.py,sha256=5LEO_veo50_eRDmiGPNnFsI-I6-X-C9NvNNmu1187T0,498
+swarm/core/spinner.py,sha256=9lyjzLnQBdEBy_dXr6N6I7nxx6KfrNp7wf44sQN06GU,3756
+swarm/core/swarm_api.py,sha256=f8olTI5JVdayp923etVQWsP8WRquPG5Mw3Q40ItN6kY,2877
+swarm/core/swarm_cli.py,sha256=dlvMq2HvUI2XlADuTzM8kpeedPkqzKB6k0oy7z2V_p0,9747
+swarm/core/swarm_wrapper.py,sha256=3K58yqPN4Ct0c7zfSDKRIGdL1Q7WOBXmAVHXT-aaPj4,1004
+swarm/core/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+swarm/core/utils/logger.py,sha256=sUkKdZsjRiCGGCEPfZ4YqeZDbiaUeGFOa3mdbVOTmvU,1242
 swarm/extensions/__init__.py,sha256=SadbzfxckByaaqzuKPfXMvqmj45-dcMlavlfQYhGnzE,56
 swarm/extensions/blueprint/__init__.py,sha256=CqPy-gR0KAeVGxDnOWKOYZZzVC1FXRzQDtUCY8jmP1c,1850
 swarm/extensions/blueprint/cli_handler.py,sha256=ZdjnTmBzSimQv8rCTwI3ZDp_2Zrjf9hqWLXYD3jzMck,9091
@@ -235,8 +255,8 @@ swarm/views/message_views.py,sha256=sDUnXyqKXC8WwIIMAlWf00s2_a2T9c75Na5FvYMJwBM,
 swarm/views/model_views.py,sha256=aAbU4AZmrOTaPeKMWtoKK7FPYHdaN3Zbx55JfKzYTRY,2937
 swarm/views/utils.py,sha256=8Usc0g0L0NPegNAyY20tJBNBy-JLwODf4VmxV0yUtpw,3627
 swarm/views/web_views.py,sha256=T1CKe-Nyv1C8aDt6QFTGWo_dkH7ojWAvS_QW9mZnZp0,7371
-open_swarm-0.1.1744943015.dist-info/METADATA,sha256=-IY39ve592zB1K4xEMlDzC6l0l0Z0DqjSgCE_b8pO5Q,18813
-open_swarm-0.1.1744943015.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-open_swarm-0.1.1744943015.dist-info/entry_points.txt,sha256=fo28d0_zJrytRsh8QqkdlWQT_9lyAwYUx1WuSTDI3HM,177
-open_swarm-0.1.1744943015.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
-open_swarm-0.1.1744943015.dist-info/RECORD,,
+open_swarm-0.1.1744943085.dist-info/METADATA,sha256=j21Gbmh-ylnfyUmQC-_Zr6BCSw7qc6TftUHblyD7np0,18813
+open_swarm-0.1.1744943085.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+open_swarm-0.1.1744943085.dist-info/entry_points.txt,sha256=fo28d0_zJrytRsh8QqkdlWQT_9lyAwYUx1WuSTDI3HM,177
+open_swarm-0.1.1744943085.dist-info/licenses/LICENSE,sha256=BU9bwRlnOt_JDIb6OT55Q4leLZx9RArDLTFnlDIrBEI,1062
+open_swarm-0.1.1744943085.dist-info/RECORD,,

swarm/core/agent_utils.py

@@ -0,0 +1,21 @@
+"""
+agent_utils.py
+
+Utility functions for agent operations used in blueprints.
+This module has been updated to remove dependency on swarm.types;
+instead, it now imports Agent from the openai-agents SDK.
+"""
+
+from blueprint_agents.agent import Agent  # Updated import
+
+def get_agent_name(agent: Agent) -> str:
+    """
+    Returns the name of the agent.
+    """
+    return agent.name
+
+def initialize_agents(blueprint) -> dict:
+    """
+    Initializes agents by calling the blueprint's create_agents() method.
+    """
+    return blueprint.create_agents()

swarm/core/blueprint_base.py

@@ -0,0 +1,395 @@
+# --- REMOVE noisy debug/framework prints unless SWARM_DEBUG=1 ---
+import os
+
+def _should_debug():
+    return os.environ.get("SWARM_DEBUG") == "1"
+
+def _debug_print(*args, **kwargs):
+    if _should_debug():
+        print(*args, **kwargs)
+
+def _framework_print(*args, **kwargs):
+    if _should_debug():
+        print(*args, **kwargs)
+
+# --- Content for src/swarm/extensions/blueprint/blueprint_base.py ---
+import logging
+import json
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional, List, AsyncGenerator
+from pathlib import Path
+from django.apps import apps # Import Django apps registry
+
+# Keep the function import
+from swarm.core.config_loader import _substitute_env_vars
+
+from openai import AsyncOpenAI
+from agents import set_default_openai_client
+
+logger = logging.getLogger(__name__)
+from rich.console import Console
+import traceback
+
+# --- PATCH: Suppress OpenAI tracing/telemetry errors if using LiteLLM/custom endpoint ---
+import logging
+import os
+if os.environ.get("LITELLM_BASE_URL") or os.environ.get("OPENAI_BASE_URL"):
+    # Silence openai.agents tracing/telemetry errors
+    logging.getLogger("openai.agents").setLevel(logging.CRITICAL)
+    try:
+        import openai.agents.tracing
+        openai.agents.tracing.TracingClient = lambda *a, **kw: None
+    except Exception:
+        pass
+
+# --- Spinner/Status Message Enhancements ---
+# To be used by all blueprints for consistent UX
+import itertools
+import sys
+import threading
+import time
+
+class Spinner:
+    def __init__(self, message_sequence=None, interval=0.3, slow_threshold=10):
+        self.message_sequence = message_sequence or ['Generating.', 'Generating..', 'Generating...', 'Running...']
+        self.interval = interval
+        self.slow_threshold = slow_threshold  # seconds before 'Taking longer than expected'
+        self._stop_event = threading.Event()
+        self._thread = None
+        self._start_time = None
+
+    def start(self):
+        self._stop_event.clear()
+        self._start_time = time.time()
+        self._thread = threading.Thread(target=self._spin)
+        self._thread.start()
+
+    def _spin(self):
+        for msg in itertools.cycle(self.message_sequence):
+            if self._stop_event.is_set():
+                break
+            elapsed = time.time() - self._start_time
+            if elapsed > self.slow_threshold:
+                sys.stdout.write('\rGenerating... Taking longer than expected   ')
+            else:
+                sys.stdout.write(f'\r{msg}   ')
+            sys.stdout.flush()
+            time.sleep(self.interval)
+        sys.stdout.write('\r')
+        sys.stdout.flush()
+
+    def stop(self, final_message=''):
+        self._stop_event.set()
+        if self._thread:
+            self._thread.join()
+        if final_message:
+            sys.stdout.write(f'\r{final_message}\n')
+            sys.stdout.flush()
+
+# Usage Example (to be called in blueprints):
+# spinner = Spinner()
+# spinner.start()
+# ... do work ...
+# spinner.stop('Done!')
+
+def configure_openai_client_from_env():
+    """
+    Framework-level function: Always instantiate and set the default OpenAI client.
+    Prints out the config being used for debug.
+    """
+    import os
+    from agents import set_default_openai_client
+    from openai import AsyncOpenAI
+    base_url = os.environ.get("LITELLM_BASE_URL") or os.environ.get("OPENAI_BASE_URL")
+    api_key = os.environ.get("LITELLM_API_KEY") or os.environ.get("OPENAI_API_KEY")
+    _debug_print(f"[DEBUG] Using OpenAI client config: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+    if base_url and api_key:
+        client = AsyncOpenAI(base_url=base_url, api_key=api_key)
+        set_default_openai_client(client)
+        _framework_print(f"[FRAMEWORK] Set default OpenAI client: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+    else:
+        _framework_print("[FRAMEWORK] WARNING: base_url or api_key missing, OpenAI client not set!")
+
+configure_openai_client_from_env()
+
+class BlueprintBase(ABC):
+    """
+    Abstract base class for all Swarm blueprints.
+
+    Defines the core interface for blueprint initialization and execution.
+    """
+    enable_terminal_commands: bool = False  # By default, terminal command execution is disabled
+
+    @classmethod
+    def main(cls):
+        """
+        Standard CLI entry point for all blueprints.
+        Subclasses can override metadata/config_path if needed.
+        """
+        from swarm.extensions.blueprint.cli_handler import run_blueprint_cli
+        from pathlib import Path
+        swarm_version = getattr(cls, "SWARM_VERSION", "1.0.0")
+        config_path = getattr(cls, "DEFAULT_CONFIG_PATH", Path(__file__).parent / "swarm_config.json")
+        run_blueprint_cli(cls, swarm_version=swarm_version, default_config_path=config_path)
+
+    def display_splash_screen(self, animated: bool = False):
+        """Default splash screen. Subclasses can override for custom CLI/API branding."""
+        console = Console()
+        console.print(f"[bold cyan]Welcome to {self.__class__.__name__}![/]", style="bold")
+
+    def __init__(self, blueprint_id: str, config: dict = None, config_path: 'Optional[Path]' = None, enable_terminal_commands: 'Optional[bool]' = None, **kwargs):
+        try:
+            if not blueprint_id:
+                raise ValueError("blueprint_id cannot be empty or None")
+            self.blueprint_id = blueprint_id
+            self.config_path = config_path  # for legacy compatibility
+            self._config = config  # Allow test injection
+            self._llm_profile_name = None
+            self._llm_profile_data = None
+            self._markdown_output = None
+            # Allow per-instance override
+            if enable_terminal_commands is not None:
+                self.enable_terminal_commands = enable_terminal_commands
+            # Else: use class attribute (default False or set by subclass)
+
+            logger.info(f"Initializing blueprint '{self.blueprint_id}' (Type: {self.__class__.__name__})")
+            
+            # --- Ensure custom OpenAI client for custom LLM providers ---
+            import os
+
+            # Remove monkey patching and envvar hacks. Always pass config values directly.
+            # (Retain only explicit AsyncOpenAI client instantiation in blueprints)
+            # (No changes needed here for direct client pattern)
+
+            self._load_and_process_config()
+        except AttributeError as e:
+            logger.debug(f"[BlueprintBase.__init__] AttributeError: {e}")
+            traceback.print_exc()
+            raise
+
+    def _load_and_process_config(self):
+        """Loads the main Swarm config and extracts relevant settings. Falls back to empty config if Django unavailable or not found."""
+        import os
+        import json
+        from pathlib import Path
+        def redact(val):
+            if not isinstance(val, str) or len(val) <= 4:
+                return "****"
+            return val[:2] + "*" * (len(val)-4) + val[-2:]
+        def redact_dict(d):
+            if isinstance(d, dict):
+                return {k: (redact_dict(v) if not (isinstance(v, str) and ("key" in k.lower() or "token" in k.lower() or "secret" in k.lower())) else redact(v)) for k, v in d.items()}
+            elif isinstance(d, list):
+                return [redact_dict(item) for item in d]
+            return d
+        try:
+            if self._config is None:
+                try:
+                    # --- Get config from the AppConfig instance (Django) ---
+                    app_config_instance = apps.get_app_config('swarm')
+                    if not hasattr(app_config_instance, 'config') or not app_config_instance.config:
+                        raise ValueError("AppConfig for 'swarm' does not have a valid 'config' attribute.")
+                    self._config = app_config_instance.config
+                    logger.debug("Loaded config from Django AppConfig.")
+                except Exception as e:
+                    if _should_debug():
+                        logger.warning(f"Falling back to CLI/home config due to error: {e}")
+                    # 1. CLI argument (not handled here, handled in cli_handler)
+                    # 2. Current working directory
+                    cwd_config = Path.cwd() / "swarm_config.json"
+                    if cwd_config.exists():
+                        with open(cwd_config, 'r') as f:
+                            self._config = json.load(f)
+                    # 3. XDG_CONFIG_HOME or ~/.config/swarm/swarm_config.json
+                    elif os.environ.get("XDG_CONFIG_HOME"):
+                        xdg_config = Path(os.environ["XDG_CONFIG_HOME"]) / "swarm" / "swarm_config.json"
+                        if xdg_config.exists():
+                            with open(xdg_config, 'r') as f:
+                                self._config = json.load(f)
+                    elif (Path.home() / ".config/swarm/swarm_config.json").exists():
+                        with open(Path.home() / ".config/swarm/swarm_config.json", 'r') as f:
+                            self._config = json.load(f)
+                    # 4. Legacy fallback: ~/.swarm/swarm_config.json
+                    elif (Path.home() / ".swarm/swarm_config.json").exists():
+                        with open(Path.home() / ".swarm/swarm_config.json", 'r') as f:
+                            self._config = json.load(f)
+                    # 5. Fallback: OPENAI_API_KEY envvar
+                    elif os.environ.get("OPENAI_API_KEY"):
+                        self._config = {
+                            "llm": {"default": {"provider": "openai", "model": "gpt-3.5-turbo", "api_key": os.environ["OPENAI_API_KEY"]}},
+                            "settings": {"default_llm_profile": "default", "default_markdown_output": True},
+                            "blueprints": {},
+                            "llm_profile": "default",
+                            "mcpServers": {}
+                        }
+                        logger.info("No config file found, using default config with OPENAI_API_KEY for CLI mode.")
+                    else:
+                        self._config = {}
+                        logger.warning("No config file found and OPENAI_API_KEY is not set. Using empty config. CLI blueprints may fail if LLM config is required.")
+                    if self._config is not None:
+                        self._config = _substitute_env_vars(self._config)
+            # Ensure self._config is always a dict
+            if self._config is None:
+                self._config = {}
+            settings_section = self._config.get("settings", {})
+            llm_section = self._config.get("llm", {})
+
+            # --- After config is loaded, set OpenAI client from config if possible ---
+            try:
+                llm_profiles = self._config.get("llm", {})
+                default_profile = llm_profiles.get("default", {})
+                base_url = default_profile.get("base_url")
+                api_key = default_profile.get("api_key")
+                # Expand env vars if present
+                import os
+                if base_url and base_url.startswith("${"):
+                    var = base_url[2:-1]
+                    base_url = os.environ.get(var, base_url)
+                if api_key and api_key.startswith("${"):
+                    var = api_key[2:-1]
+                    api_key = os.environ.get(var, api_key)
+                if base_url and api_key:
+                    from openai import AsyncOpenAI
+                    from agents import set_default_openai_client
+                    _debug_print(f"[DEBUG] (config) Setting OpenAI client: base_url={base_url}, api_key={'set' if api_key else 'NOT SET'}")
+                    client = AsyncOpenAI(base_url=base_url, api_key=api_key)
+                    set_default_openai_client(client)
+            except Exception as e:
+                _debug_print(f"[DEBUG] Failed to set OpenAI client from config: {e}")
+
+            # --- Debug: Print and log redacted config ---
+            redacted_config = redact_dict(self._config)
+            logger.debug(f"Loaded config (redacted): {json.dumps(redacted_config, indent=2)}")
+
+            # --- Process LLM profile name and data ---
+            default_profile = settings_section.get("default_llm_profile") or "default"
+            self._llm_profile_name = self._config.get("llm_profile") or default_profile
+            if "profiles" in llm_section:
+                self._llm_profile_data = llm_section["profiles"].get(self._llm_profile_name, {})
+            else:
+                self._llm_profile_data = llm_section.get(self._llm_profile_name, {})
+
+            blueprint_specific_settings = self._config.get("blueprints", {}).get(self.blueprint_id, {})
+            global_markdown_setting = settings_section.get("default_markdown_output", True)
+            self._markdown_output = blueprint_specific_settings.get("markdown_output", global_markdown_setting)
+            logger.debug(f"Markdown output for '{self.blueprint_id}': {self._markdown_output}")
+
+        except ValueError as e:
+            logger.error(f"Configuration error for blueprint '{self.blueprint_id}': {e}", exc_info=True)
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error loading config for blueprint '{self.blueprint_id}': {e}", exc_info=True)
+            raise
+
+    @property
+    def config(self) -> Dict[str, Any]:
+        """Returns the loaded and processed Swarm configuration."""
+        if self._config is None:
+            raise RuntimeError("Configuration accessed before initialization or after failure.")
+        return self._config
+
+    @property
+    def llm_profile(self) -> Dict[str, Any]:
+        """
+        Returns the LLM profile dict for this blueprint.
+        Raises a clear error if provider is missing.
+        """
+        llm_section = self._config.get("llm", {}) if self._config else {}
+        profile_name = self.llm_profile_name or "default"
+        profile = llm_section.get(profile_name)
+        if not profile:
+            raise ValueError(f"LLM profile '{profile_name}' not found in config: {llm_section}")
+        if "provider" not in profile:
+            raise ValueError(f"'provider' missing in LLM profile '{profile_name}': {profile}")
+        return profile
+
+    @property
+    def llm_profile_name(self) -> str:
+        """Returns the name of the LLM profile being used."""
+        if self._llm_profile_name is None:
+             raise RuntimeError("LLM profile name accessed before initialization or after failure.")
+        return self._llm_profile_name
+
+    @property
+    def slash_commands(self):
+        from swarm.core.slash_commands import slash_registry
+        return slash_registry
+
+    def get_llm_profile(self, profile_name: str) -> dict:
+        """Returns the LLM profile dict for the given profile name from config, or empty dict if not found.
+        Supports both llm.profiles and direct llm keys for backward compatibility."""
+        llm_section = self.config.get("llm", {})
+        if "profiles" in llm_section:
+            return llm_section["profiles"].get(profile_name, {})
+        return llm_section.get(profile_name, {})
+
+    @property
+    def should_output_markdown(self) -> bool:
+        """
+        Determines if markdown output should be used for this blueprint.
+        Priority: blueprint config > global config > False
+        """
+        settings = self._config.get("settings", {}) if self._config else {}
+        bp_settings = self._config.get("blueprints", {}).get(self.blueprint_id, {}) if self._config else {}
+        if "output_markdown" in bp_settings:
+            return bool(bp_settings["output_markdown"])
+        if "default_markdown_output" in settings:
+            return bool(settings["default_markdown_output"])
+        return False
+
+    def _get_model_instance(self, profile_name: str):
+        """Retrieves or creates an LLM Model instance, respecting LITELLM_MODEL/DEFAULT_LLM if set."""
+        if not hasattr(self, '_model_instance_cache'):
+            self._model_instance_cache = {}
+        if not hasattr(self, '_openai_client_cache'):
+            self._openai_client_cache = {}
+        if profile_name in self._model_instance_cache:
+            return self._model_instance_cache[profile_name]
+        profile_data = self.get_llm_profile(profile_name)
+        import os
+        model_name = os.getenv("LITELLM_MODEL") or os.getenv("DEFAULT_LLM") or profile_data.get("model") or "gpt-3.5-turbo"
+        openai_kwargs = {}
+        if "base_url" in profile_data:
+            openai_kwargs["base_url"] = profile_data["base_url"]
+        if "api_key" in profile_data:
+            openai_kwargs["api_key"] = profile_data["api_key"]
+        from openai import AsyncOpenAI
+        from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+        client_cache_key = f"{model_name}:{openai_kwargs.get('base_url','')}:key={bool(openai_kwargs.get('api_key'))}"
+        if client_cache_key not in self._openai_client_cache:
+            try:
+                self._openai_client_cache[client_cache_key] = AsyncOpenAI(**openai_kwargs)
+            except Exception as e:
+                raise ValueError(f"Failed to init client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        try:
+            model_instance = OpenAIChatCompletionsModel(model=model_name, openai_client=client)
+            self._model_instance_cache[profile_name] = model_instance
+            return model_instance
+        except Exception as e:
+            raise ValueError(f"Failed to init LLM: {e}") from e
+
+    def make_agent(self, name, instructions, tools, mcp_servers=None, **kwargs):
+        """Factory for creating an Agent with the correct model instance from framework config."""
+        from agents import Agent  # Ensure Agent is always in scope
+        model_instance = self._get_model_instance(self.config.get("llm_profile", "default"))
+        return Agent(
+            name=name,
+            model=model_instance,
+            instructions=instructions,
+            tools=tools,
+            mcp_servers=mcp_servers or [],
+            **kwargs
+        )
+
+    @abstractmethod
+    async def run(self, messages: List[Dict[str, Any]], **kwargs: Any) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        The main execution method for the blueprint.
+        """
+        import os
+        import pprint
+        logger.debug("ENVIRONMENT DUMP BEFORE MODEL CALL:")
+        pprint.pprint(dict(os.environ))
+        raise NotImplementedError("Subclasses must implement the 'run' method.")
+        yield {}

swarm/core/blueprint_discovery.py

@@ -0,0 +1,128 @@
+import os
+import importlib
+import importlib.util
+import inspect
+import logging # Ensure logging is imported
+import sys
+from typing import Dict, Type, Any
+from pathlib import Path
+
+# *** Define logger EARLIER ***
+logger = logging.getLogger(__name__)
+
+# *** Import the ACTUAL BlueprintBase from the likely correct path ***
+try:
+    # Adjust this path if BlueprintBase lives elsewhere
+    from swarm.core.blueprint_base import BlueprintBase
+except ImportError:
+    # This logger call is now safe
+    logger.error("Failed to import BlueprintBase from swarm.core.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]]:
+    """
+    Discovers blueprints (subclasses of BlueprintBase) by looking for
+    'blueprint_{name}.py' files within subdirectories of the given blueprint directory.
+
+    Args:
+        blueprint_dir: The path to the directory containing blueprint subdirectories.
+
+    Returns:
+        A dictionary mapping blueprint names to their corresponding class objects.
+    """
+    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 subdir in base_dir.iterdir():
+        if not subdir.is_dir():
+            continue # Skip files directly under blueprints/
+
+        # Use directory name as blueprint name (e.g., 'echocraft')
+        blueprint_name = subdir.name
+        logger.debug(f"Processing potential blueprint '{blueprint_name}' in directory: {subdir.name}")
+
+        # Look for the specific .py file, e.g., blueprint_echocraft.py
+        py_file_name = f"blueprint_{blueprint_name}.py"
+        py_file_path = subdir / 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 = subdir / 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 '{subdir.name}': Neither '{py_file_name}' nor '{alt_py_file_name}' found.")
+                 continue
+
+
+        # Construct module import path, e.g., blueprints.echocraft.blueprint_echocraft
+        if py_file_path.name.startswith('blueprint_gatcha'):
+            module_import_path = f"swarm.blueprints.gatcha.{py_file_path.stem}"
+        elif py_file_path.name.startswith('blueprint_'):
+            module_import_path = f"swarm.blueprints.{subdir.name}.{py_file_path.stem}"
+        else:
+            continue
+
+        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/core/blueprint_runner.py

@@ -0,0 +1,59 @@
+import sys
+import traceback
+import types
+from typing import AsyncGenerator
+import inspect
+
+from .blueprint_base import Spinner
+
+class BlueprintRunner:
+    @staticmethod
+    async def run_agent(agent, instruction, filter_llm_function_calls=True, spinner_enabled=True) -> AsyncGenerator[dict, None]:
+        """
+        Runs the agent using Runner.run as an async generator or coroutine, with spinner and error handling.
+        Filters out LLM function call outputs if requested.
+        Handles both coroutine and async generator return types.
+        """
+        from agents import Runner
+        # Only enable spinner if spinner_enabled is True and not in non-interactive mode
+        # (i.e., only if show_intermediate is True)
+        spinner = None
+        if spinner_enabled:
+            # Check for a marker in instruction or a kwarg to disable spinner in non-interactive
+            frame = inspect.currentframe()
+            show_intermediate = False
+            while frame:
+                if 'kwargs' in frame.f_locals and isinstance(frame.f_locals['kwargs'], dict):
+                    show_intermediate = frame.f_locals['kwargs'].get('show_intermediate', False)
+                    break
+                frame = frame.f_back
+            if show_intermediate:
+                spinner = Spinner()
+        try:
+            if spinner:
+                spinner.start()
+            result = await Runner.run(agent, instruction)
+            # If result is an async generator, iterate over it
+            if isinstance(result, types.AsyncGeneratorType):
+                async for chunk in result:
+                    if filter_llm_function_calls:
+                        content = chunk.get("content")
+                        if content and ("function call" in content or "args" in content):
+                            continue
+                    yield chunk
+            elif isinstance(result, (list, dict)):
+                # If it's a list of chunks or a single chunk, yield directly
+                if isinstance(result, list):
+                    for chunk in result:
+                        yield chunk
+                else:
+                    yield result
+            elif result is not None:
+                # Fallback: yield as a single chunk
+                yield {"messages": [{"role": "assistant", "content": str(result)}]}
+        except Exception as e:
+            tb = traceback.format_exc()
+            yield {"messages": [{"role": "assistant", "content": f"Error: {e}\n{tb}"}]}
+        finally:
+            if spinner:
+                spinner.stop()

swarm/core/blueprint_utils.py

@@ -0,0 +1,17 @@
+"""
+Utility functions for blueprint management.
+"""
+
+def filter_blueprints(all_blueprints: dict, allowed_blueprints_str: str) -> dict:
+    """
+    Filters the given blueprints dictionary using a comma-separated string of allowed blueprint keys.
+
+    Args:
+        all_blueprints (dict): A dictionary containing all discovered blueprints.
+        allowed_blueprints_str (str): A comma-separated string of allowed blueprint keys.
+
+    Returns:
+        dict: A dictionary containing only the blueprints whose keys are present in the allowed list.
+    """
+    allowed_list = [bp.strip() for bp in allowed_blueprints_str.split(",")]
+    return {k: v for k, v in all_blueprints.items() if k in allowed_list}