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

swarm/blueprints/omniplex/blueprint_omniplex.py

@@ -0,0 +1,221 @@
+import logging
+import os
+import sys
+from typing import Dict, Any, List, ClassVar, Optional
+
+# Ensure src is in path for BlueprintBase import
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+src_path = os.path.join(project_root, 'src')
+if src_path not in sys.path: sys.path.insert(0, src_path)
+
+try:
+    from agents import Agent, Tool, function_tool, Runner
+    from agents.mcp import MCPServer
+    from agents.models.interface import Model
+    from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+    from openai import AsyncOpenAI
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+    print(f"ERROR: Import failed in OmniplexBlueprint: {e}. Check dependencies.")
+    print(f"sys.path: {sys.path}")
+    sys.exit(1)
+
+logger = logging.getLogger(__name__)
+
+# --- Agent Instructions ---
+
+amazo_instructions = """
+You are Amazo, master of 'npx'-based MCP tools.
+Receive task instructions from the Coordinator.
+Identify the BEST available 'npx' MCP tool from your assigned list to accomplish the task.
+Execute the chosen MCP tool with the necessary parameters provided by the Coordinator.
+Report the results clearly back to the Coordinator.
+"""
+
+rogue_instructions = """
+You are Rogue, master of 'uvx'-based MCP tools.
+Receive task instructions from the Coordinator.
+Identify the BEST available 'uvx' MCP tool from your assigned list.
+Execute the chosen MCP tool with parameters from the Coordinator.
+Report the results clearly back to the Coordinator.
+"""
+
+sylar_instructions = """
+You are Sylar, master of miscellaneous MCP tools (non-npx, non-uvx).
+Receive task instructions from the Coordinator.
+Identify the BEST available MCP tool from your assigned list.
+Execute the chosen MCP tool with parameters from the Coordinator.
+Report the results clearly back to the Coordinator.
+"""
+
+coordinator_instructions = """
+You are the Omniplex Coordinator. Your role is to understand the user request and delegate it to the agent best suited based on the required MCP tool's execution type (npx, uvx, or other).
+Team & Tool Categories:
+- Amazo (Agent Tool `Amazo`): Handles tasks requiring `npx`-based MCP servers (e.g., @modelcontextprotocol/*, mcp-shell, mcp-flowise). Pass the specific tool name and parameters needed.
+- Rogue (Agent Tool `Rogue`): Handles tasks requiring `uvx`-based MCP servers (if any configured). Pass the specific tool name and parameters needed.
+- Sylar (Agent Tool `Sylar`): Handles tasks requiring other/miscellaneous MCP servers (e.g., direct python scripts, other executables). Pass the specific tool name and parameters needed.
+Analyze the user's request, determine if an `npx`, `uvx`, or `other` tool is likely needed, and delegate using the corresponding agent tool (`Amazo`, `Rogue`, or `Sylar`). Provide the *full context* of the user request to the chosen agent. Synthesize the final response based on the specialist agent's report.
+"""
+
+# --- Define the Blueprint ---
+class OmniplexBlueprint(BlueprintBase):
+    """Dynamically routes tasks to agents based on the execution type (npx, uvx, other) of the required MCP server."""
+    metadata: ClassVar[Dict[str, Any]] = {
+            "name": "OmniplexBlueprint",
+            "title": "Omniplex MCP Orchestrator",
+            "description": "Dynamically delegates tasks to agents (Amazo:npx, Rogue:uvx, Sylar:other) based on the command type of available MCP servers.",
+            "version": "1.1.0", # Refactored version
+            "author": "Open Swarm Team (Refactored)",
+            "tags": ["orchestration", "mcp", "dynamic", "multi-agent"],
+            # List common servers - BlueprintBase will try to start them if defined in config.
+            # The blueprint logic will then assign the *started* ones.
+            "required_mcp_servers": [
+                "memory", "filesystem", "mcp-shell", "brave-search", "sqlite",
+                "mcp-flowise", "sequential-thinking", # Add other common ones if needed
+            ],
+            "env_vars": ["ALLOWED_PATH", "BRAVE_API_KEY", "SQLITE_DB_PATH", "FLOWISE_API_KEY"], # Informational
+        }
+
+    # Caches
+    _openai_client_cache: Dict[str, AsyncOpenAI] = {}
+    _model_instance_cache: Dict[str, Model] = {}
+
+    # --- Model Instantiation Helper --- (Standard helper)
+    def _get_model_instance(self, profile_name: str) -> Model:
+        """Retrieves or creates an LLM Model instance."""
+        # ... (Implementation is the same as in previous refactors) ...
+        if profile_name in self._model_instance_cache:
+            logger.debug(f"Using cached Model instance for profile '{profile_name}'.")
+            return self._model_instance_cache[profile_name]
+        logger.debug(f"Creating new Model instance for profile '{profile_name}'.")
+        profile_data = self.get_llm_profile(profile_name)
+        if not profile_data:
+             logger.critical(f"LLM profile '{profile_name}' (or 'default') not found.")
+             raise ValueError(f"Missing LLM profile configuration for '{profile_name}' or 'default'.")
+        provider = profile_data.get("provider", "openai").lower()
+        model_name = profile_data.get("model")
+        if not model_name:
+             logger.critical(f"LLM profile '{profile_name}' missing 'model' key.")
+             raise ValueError(f"Missing 'model' key in LLM profile '{profile_name}'.")
+        if provider != "openai":
+            logger.error(f"Unsupported LLM provider '{provider}'.")
+            raise ValueError(f"Unsupported LLM provider: {provider}")
+        client_cache_key = f"{provider}_{profile_data.get('base_url')}"
+        if client_cache_key not in self._openai_client_cache:
+             client_kwargs = { "api_key": profile_data.get("api_key"), "base_url": profile_data.get("base_url") }
+             filtered_kwargs = {k: v for k, v in client_kwargs.items() if v is not None}
+             log_kwargs = {k:v for k,v in filtered_kwargs.items() if k != 'api_key'}
+             logger.debug(f"Creating new AsyncOpenAI client for '{profile_name}': {log_kwargs}")
+             try: self._openai_client_cache[client_cache_key] = AsyncOpenAI(**filtered_kwargs)
+             except Exception as e: raise ValueError(f"Failed to init OpenAI client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        logger.debug(f"Instantiating OpenAIChatCompletionsModel(model='{model_name}') for '{profile_name}'.")
+        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 provider: {e}") from e
+
+    # --- Agent Creation ---
+    def create_starting_agent(self, mcp_servers: List[MCPServer]) -> Agent:
+        """Creates the Omniplex agent team based on available started MCP servers."""
+        logger.debug("Dynamically creating agents for OmniplexBlueprint...")
+        self._model_instance_cache = {}
+        self._openai_client_cache = {}
+
+        default_profile_name = self.config.get("llm_profile", "default")
+        logger.debug(f"Using LLM profile '{default_profile_name}' for Omniplex agents.")
+        model_instance = self._get_model_instance(default_profile_name)
+
+        # Categorize the *started* MCP servers passed to this method
+        npx_started_servers: List[MCPServer] = []
+        uvx_started_servers: List[MCPServer] = [] # Assuming 'uvx' might be a command name
+        other_started_servers: List[MCPServer] = []
+
+        for server in mcp_servers:
+            server_config = self.mcp_server_configs.get(server.name, {})
+            command_def = server_config.get("command", "")
+            command_name = ""
+            if isinstance(command_def, list) and command_def:
+                command_name = os.path.basename(command_def[0]).lower()
+            elif isinstance(command_def, str):
+                 # Simple case: command is just the executable name
+                 command_name = os.path.basename(shlex.split(command_def)[0]).lower() if command_def else ""
+
+
+            if "npx" in command_name:
+                npx_started_servers.append(server)
+            elif "uvx" in command_name: # Placeholder for uvx logic
+                uvx_started_servers.append(server)
+            else:
+                other_started_servers.append(server)
+
+        logger.debug(f"Categorized MCPs - NPX: {[s.name for s in npx_started_servers]}, UVX: {[s.name for s in uvx_started_servers]}, Other: {[s.name for s in other_started_servers]}")
+
+        # Create agents for each category *only if* they have servers assigned
+        amazo_agent = rogue_agent = sylar_agent = None
+        team_tools: List[Tool] = []
+
+        if npx_started_servers:
+            logger.info(f"Creating Amazo for npx servers: {[s.name for s in npx_started_servers]}")
+            amazo_agent = Agent(
+                name="Amazo",
+                model=model_instance,
+                instructions=amazo_instructions,
+                tools=[], # Uses MCPs
+                mcp_servers=npx_started_servers
+            )
+            team_tools.append(amazo_agent.as_tool(
+                tool_name="Amazo",
+                tool_description=f"Delegate tasks requiring npx-based MCP servers (e.g., {', '.join(s.name for s in npx_started_servers)})."
+            ))
+        else:
+            logger.info("No started npx servers found for Amazo.")
+
+        if uvx_started_servers:
+            logger.info(f"Creating Rogue for uvx servers: {[s.name for s in uvx_started_servers]}")
+            rogue_agent = Agent(
+                name="Rogue",
+                model=model_instance,
+                instructions=rogue_instructions,
+                tools=[], # Uses MCPs
+                mcp_servers=uvx_started_servers
+            )
+            team_tools.append(rogue_agent.as_tool(
+                tool_name="Rogue",
+                tool_description=f"Delegate tasks requiring uvx-based MCP servers (e.g., {', '.join(s.name for s in uvx_started_servers)})."
+            ))
+        else:
+            logger.info("No started uvx servers found for Rogue.")
+
+        if other_started_servers:
+            logger.info(f"Creating Sylar for other servers: {[s.name for s in other_started_servers]}")
+            sylar_agent = Agent(
+                name="Sylar",
+                model=model_instance,
+                instructions=sylar_instructions,
+                tools=[], # Uses MCPs
+                mcp_servers=other_started_servers
+            )
+            team_tools.append(sylar_agent.as_tool(
+                tool_name="Sylar",
+                tool_description=f"Delegate tasks requiring miscellaneous MCP servers (e.g., {', '.join(s.name for s in other_started_servers)})."
+            ))
+        else:
+            logger.info("No other started servers found for Sylar.")
+
+        # Create Coordinator and pass the tools for the agents that were created
+        coordinator_agent = Agent(
+            name="OmniplexCoordinator",
+            model=model_instance,
+            instructions=coordinator_instructions,
+            tools=team_tools,
+            mcp_servers=[] # Coordinator likely doesn't use MCPs directly
+        )
+
+        logger.info(f"Omniplex Coordinator created with tools for: {[t.name for t in team_tools]}")
+        return coordinator_agent
+
+# Standard Python entry point
+if __name__ == "__main__":
+    OmniplexBlueprint.main()

swarm/blueprints/rue_code/blueprint_rue_code.py

@@ -0,0 +1,291 @@
+import logging
+import os
+import sys
+import json
+import subprocess
+from typing import Dict, List, Any, AsyncGenerator, Optional
+from pathlib import Path
+import re
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='[%(levelname)s] %(asctime)s - %(name)s - %(message)s')
+logger = logging.getLogger(__name__)
+
+# Attempt to import BlueprintBase, handle potential ImportError during early setup/testing
+try:
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+    logger.error(f"Import failed: {e}. Check 'openai-agents' install and project structure.")
+    # *** REMOVED sys.exit(1) ***
+    # Define a dummy class if import fails, allowing module to load for inspection/debugging
+    class BlueprintBase:
+        metadata = {}
+        def __init__(self, *args, **kwargs): pass
+        async def run(self, *args, **kwargs): yield {}
+
+# --- Tool Definitions ---
+
+def execute_shell_command(command: str) -> str:
+    """
+    Executes a shell command and returns its stdout and stderr.
+    Security Note: Ensure commands are properly sanitized or restricted.
+    """
+    logger.info(f"Executing shell command: {command}")
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            check=False, # Don't raise exception on non-zero exit code
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=60 # Add a timeout
+        )
+        output = f"Exit Code: {result.returncode}\n"
+        if result.stdout:
+            output += f"STDOUT:\n{result.stdout}\n"
+        if result.stderr:
+            output += f"STDERR:\n{result.stderr}\n"
+        logger.info(f"Command finished. Exit Code: {result.returncode}")
+        return output.strip()
+    except subprocess.TimeoutExpired:
+        logger.error(f"Command timed out: {command}")
+        return "Error: Command timed out after 60 seconds."
+    except Exception as e:
+        logger.error(f"Error executing command '{command}': {e}", exc_info=True)
+        return f"Error executing command: {e}"
+
+def read_file(file_path: str) -> str:
+    """Reads the content of a specified file."""
+    logger.info(f"Reading file: {file_path}")
+    try:
+        # Basic path traversal check (can be enhanced)
+        if ".." in file_path:
+             logger.warning(f"Attempted path traversal detected in read_file: {file_path}")
+             return "Error: Invalid file path (potential traversal)."
+        # Consider restricting base path if needed
+        # base_path = Path("/workspace").resolve()
+        # target_path = (base_path / file_path).resolve()
+        # if not target_path.is_relative_to(base_path):
+        #     return "Error: Access denied."
+
+        path = Path(file_path)
+        if not path.is_file():
+            return f"Error: File not found at {file_path}"
+        content = path.read_text(encoding='utf-8')
+        logger.info(f"Successfully read {len(content)} characters from {file_path}")
+        # Truncate long files?
+        max_len = 10000
+        if len(content) > max_len:
+             logger.warning(f"File {file_path} truncated to {max_len} characters.")
+             return content[:max_len] + "\n... [File Truncated]"
+        return content
+    except Exception as e:
+        logger.error(f"Error reading file '{file_path}': {e}", exc_info=True)
+        return f"Error reading file: {e}"
+
+def write_file(file_path: str, content: str) -> str:
+    """Writes content to a specified file, creating directories if needed."""
+    logger.info(f"Writing to file: {file_path}")
+    try:
+        # Basic path traversal check
+        if ".." in file_path:
+             logger.warning(f"Attempted path traversal detected in write_file: {file_path}")
+             return "Error: Invalid file path (potential traversal)."
+        # Consider restricting base path
+
+        path = Path(file_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding='utf-8')
+        logger.info(f"Successfully wrote {len(content)} characters to {file_path}")
+        return f"Successfully wrote to {file_path}"
+    except Exception as e:
+        logger.error(f"Error writing file '{file_path}': {e}", exc_info=True)
+        return f"Error writing file: {e}"
+
+def list_files(directory_path: str = ".") -> str:
+    """Lists files and directories in a specified path."""
+    logger.info(f"Listing files in directory: {directory_path}")
+    try:
+        # Basic path traversal check
+        if ".." in directory_path:
+             logger.warning(f"Attempted path traversal detected in list_files: {directory_path}")
+             return "Error: Invalid directory path (potential traversal)."
+        # Consider restricting base path
+
+        path = Path(directory_path)
+        if not path.is_dir():
+            return f"Error: Directory not found at {directory_path}"
+
+        entries = []
+        for entry in path.iterdir():
+            entry_type = "d" if entry.is_dir() else "f"
+            entries.append(f"{entry_type} {entry.name}")
+
+        logger.info(f"Found {len(entries)} entries in {directory_path}")
+        return "\n".join(entries) if entries else "Directory is empty."
+    except Exception as e:
+        logger.error(f"Error listing files in '{directory_path}': {e}", exc_info=True)
+        return f"Error listing files: {e}"
+
+# --- RueCodeBlueprint Definition ---
+
+class RueCodeBlueprint(BlueprintBase):
+    """
+    A blueprint designed for code generation, execution, and file system interaction.
+    Uses Jinja2 for templating prompts and provides tools for shell commands and file operations.
+    """
+    metadata = {
+        "name": "RueCode",
+        "description": "Generates, executes code, and interacts with the file system.",
+        "author": "Matthew Hand",
+        "version": "0.1.0",
+        "tags": ["code", "execution", "filesystem", "developer"],
+        "llm_profile": "default_dev" # Example: Suggests a profile suitable for coding
+    }
+
+    # Override __init__ if you need specific setup beyond the base class
+    # def __init__(self, *args, **kwargs):
+    #     super().__init__(*args, **kwargs)
+    #     # Add any RueCode specific initialization here
+    #     logger.info("RueCodeBlueprint initialized.")
+
+    async def run(self, messages: List[Dict[str, str]]) -> AsyncGenerator[Dict[str, Any], None]:
+        """
+        Processes user requests for code generation, execution, or file operations.
+        """
+        logger.info(f"RueCodeBlueprint run called with {len(messages)} messages.")
+        last_user_message = next((m['content'] for m in reversed(messages) if m['role'] == 'user'), None)
+
+        if not last_user_message:
+            yield {"messages": [{"role": "assistant", "content": "I need a user message to proceed."}]}
+            return
+
+        # 1. Prepare the prompt using Jinja (example)
+        # Assuming you have a 'rue_code_prompt.j2' in a 'templates' subdir
+        try:
+            prompt_context = {
+                "user_request": last_user_message,
+                "history": messages[:-1], # Provide previous messages for context
+                "available_tools": ["execute_shell_command", "read_file", "write_file", "list_files"]
+            }
+            rendered_prompt = self.render_prompt("rue_code_prompt.j2", prompt_context)
+            logger.debug(f"Rendered prompt:\n{rendered_prompt}")
+        except Exception as e:
+            logger.error(f"Failed to render prompt template: {e}")
+            yield {"messages": [{"role": "assistant", "content": f"Internal error: Could not prepare request ({e})."}]}
+            return
+
+        # 2. Define available tools for the LLM
+        tools = [
+            {"type": "function", "function": {"name": "execute_shell_command", "description": "Executes a shell command.", "parameters": {"type": "object", "properties": {"command": {"type": "string", "description": "The shell command to execute."}}, "required": ["command"]}}},
+            {"type": "function", "function": {"name": "read_file", "description": "Reads content from a file.", "parameters": {"type": "object", "properties": {"file_path": {"type": "string", "description": "Path to the file to read."}}, "required": ["file_path"]}}},
+            {"type": "function", "function": {"name": "write_file", "description": "Writes content to a file.", "parameters": {"type": "object", "properties": {"file_path": {"type": "string", "description": "Path to the file to write."}, "content": {"type": "string", "description": "Content to write."}}, "required": ["file_path", "content"]}}},
+            {"type": "function", "function": {"name": "list_files", "description": "Lists files in a directory.", "parameters": {"type": "object", "properties": {"directory_path": {"type": "string", "description": "Path to the directory (default is current)."}}, "required": []}}}, # directory_path is optional
+        ]
+        tool_map = {
+            "execute_shell_command": execute_shell_command,
+            "read_file": read_file,
+            "write_file": write_file,
+            "list_files": list_files,
+        }
+
+        # 3. Call the LLM (using the base class's llm instance)
+        llm_messages = [{"role": "system", "content": rendered_prompt}] # Or construct differently based on template
+        # Add user message if not fully incorporated into the system prompt
+        # llm_messages.append({"role": "user", "content": last_user_message})
+
+        logger.info(f"Calling LLM profile '{self.llm_profile_name}' with tools.")
+        try:
+            # Use the configured LLM instance from the base class
+            response_stream = self.llm.chat_completion_stream(
+                messages=llm_messages,
+                tools=tools,
+                tool_choice="auto" # Let the model decide
+            )
+
+            # 4. Process the streaming response and handle tool calls
+            full_response_content = ""
+            tool_calls = []
+            async for chunk in response_stream:
+                delta = chunk.choices[0].delta
+                if delta.content:
+                    full_response_content += delta.content
+                    yield {"messages": [{"role": "assistant", "delta": {"content": delta.content}}]} # Yield content delta
+
+                if delta.tool_calls:
+                    # Accumulate tool call information from deltas
+                    for tc_delta in delta.tool_calls:
+                        if tc_delta.index >= len(tool_calls):
+                            # Start of a new tool call
+                            tool_calls.append({
+                                "id": tc_delta.id,
+                                "type": "function",
+                                "function": {"name": tc_delta.function.name, "arguments": tc_delta.function.arguments}
+                            })
+                        else:
+                            # Append arguments to existing tool call
+                            tool_calls[tc_delta.index]["function"]["arguments"] += tc_delta.function.arguments
+
+            logger.info("LLM response received.")
+            # If no tool calls, the final response is just the accumulated content
+            if not tool_calls and not full_response_content:
+                 logger.warning("LLM finished without content or tool calls.")
+                 yield {"messages": [{"role": "assistant", "content": "[No response content or tool call generated]"}]}
+
+
+            # 5. Execute tool calls if any were made
+            if tool_calls:
+                logger.info(f"Executing {len(tool_calls)} tool call(s)...")
+                tool_messages = [{"role": "assistant", "tool_calls": tool_calls}] # Message for next LLM call
+
+                for tool_call in tool_calls:
+                    function_name = tool_call["function"]["name"]
+                    tool_call_id = tool_call["id"]
+                    logger.debug(f"Processing tool call: {function_name} (ID: {tool_call_id})")
+
+                    if function_name in tool_map:
+                        try:
+                            arguments = json.loads(tool_call["function"]["arguments"])
+                            logger.debug(f"Arguments: {arguments}")
+                            tool_function = tool_map[function_name]
+                            # Execute the tool function (sync for now, consider async if tools are I/O bound)
+                            tool_output = tool_function(**arguments)
+                            logger.debug(f"Tool output: {tool_output[:200]}...") # Log truncated output
+                        except json.JSONDecodeError:
+                            logger.error(f"Failed to decode arguments for {function_name}: {tool_call['function']['arguments']}")
+                            tool_output = f"Error: Invalid arguments format for {function_name}."
+                        except Exception as e:
+                            logger.error(f"Error executing tool {function_name}: {e}", exc_info=True)
+                            tool_output = f"Error executing tool {function_name}: {e}"
+
+                        tool_messages.append({
+                            "tool_call_id": tool_call_id,
+                            "role": "tool",
+                            "name": function_name,
+                            "content": tool_output,
+                        })
+                    else:
+                        logger.warning(f"LLM requested unknown tool: {function_name}")
+                        tool_messages.append({
+                            "tool_call_id": tool_call_id,
+                            "role": "tool",
+                            "name": function_name,
+                            "content": f"Error: Tool '{function_name}' not found.",
+                        })
+
+                # 6. Send tool results back to LLM for final response
+                logger.info("Sending tool results back to LLM...")
+                final_response_stream = self.llm.chat_completion_stream(
+                    messages=llm_messages + tool_messages # Original messages + tool req + tool resp
+                )
+                async for final_chunk in final_response_stream:
+                     if final_chunk.choices[0].delta.content:
+                         yield {"messages": [{"role": "assistant", "delta": {"content": final_chunk.choices[0].delta.content}}]}
+
+        except Exception as e:
+            logger.error(f"Error during RueCodeBlueprint run: {e}", exc_info=True)
+            yield {"messages": [{"role": "assistant", "content": f"An error occurred: {e}"}]}
+
+        logger.info("RueCodeBlueprint run finished.")
+

swarm/blueprints/suggestion/blueprint_suggestion.py

@@ -0,0 +1,110 @@
+import logging
+import os
+import sys
+from typing import Dict, Any, List, TypedDict, ClassVar, Optional
+
+# Ensure src is in path for BlueprintBase import
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..'))
+src_path = os.path.join(project_root, 'src')
+if src_path not in sys.path: sys.path.insert(0, src_path)
+
+try:
+    from agents import Agent, Tool, function_tool, Runner
+    from agents.mcp import MCPServer
+    from agents.models.interface import Model
+    from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
+    from openai import AsyncOpenAI
+    from swarm.extensions.blueprint.blueprint_base import BlueprintBase
+except ImportError as e:
+     print(f"ERROR: Failed to import 'agents' or 'BlueprintBase'. Is 'openai-agents' installed and src in PYTHONPATH? Details: {e}")
+     sys.exit(1)
+
+logger = logging.getLogger(__name__)
+
+# --- Define the desired output structure ---
+class SuggestionsOutput(TypedDict):
+    """Defines the expected structure for the agent's output."""
+    suggestions: List[str]
+
+# --- Define the Blueprint ---
+class SuggestionBlueprint(BlueprintBase):
+    """A blueprint defining an agent that generates structured JSON suggestions using output_type."""
+
+    metadata: ClassVar[Dict[str, Any]] = {
+        "name": "SuggestionBlueprint",
+        "title": "Suggestion Blueprint (Structured Output)",
+        "description": "An agent that provides structured suggestions using Agent(output_type=...).",
+        "version": "1.2.0", # Version bump for refactor
+        "author": "Open Swarm Team (Refactored)",
+        "tags": ["structured output", "json", "suggestions", "output_type"],
+        "required_mcp_servers": [],
+        "env_vars": [], # OPENAI_API_KEY is implicitly needed by the model
+    }
+
+    # Caches
+    _openai_client_cache: Dict[str, AsyncOpenAI] = {}
+    _model_instance_cache: Dict[str, Model] = {}
+
+    # --- Model Instantiation Helper --- (Standard helper)
+    def _get_model_instance(self, profile_name: str) -> Model:
+        """Retrieves or creates an LLM Model instance."""
+        # ... (Implementation is the same as previous refactors) ...
+        if profile_name in self._model_instance_cache:
+            logger.debug(f"Using cached Model instance for profile '{profile_name}'.")
+            return self._model_instance_cache[profile_name]
+        logger.debug(f"Creating new Model instance for profile '{profile_name}'.")
+        profile_data = self.get_llm_profile(profile_name)
+        if not profile_data: raise ValueError(f"Missing LLM profile '{profile_name}'.")
+        provider = profile_data.get("provider", "openai").lower()
+        model_name = profile_data.get("model")
+        # Ensure a model capable of structured output is used (most recent OpenAI models are)
+        if not model_name: raise ValueError(f"Missing 'model' in profile '{profile_name}'.")
+        if provider != "openai": raise ValueError(f"Unsupported provider: {provider}")
+
+        client_cache_key = f"{provider}_{profile_data.get('base_url')}"
+        if client_cache_key not in self._openai_client_cache:
+             client_kwargs = { "api_key": profile_data.get("api_key"), "base_url": profile_data.get("base_url") }
+             filtered_kwargs = {k: v for k, v in client_kwargs.items() if v is not None}
+             log_kwargs = {k:v for k,v in filtered_kwargs.items() if k != 'api_key'}
+             logger.debug(f"Creating new AsyncOpenAI client for '{profile_name}': {log_kwargs}")
+             try: self._openai_client_cache[client_cache_key] = AsyncOpenAI(**filtered_kwargs)
+             except Exception as e: raise ValueError(f"Failed to init client: {e}") from e
+        client = self._openai_client_cache[client_cache_key]
+        logger.debug(f"Instantiating OpenAIChatCompletionsModel(model='{model_name}') for '{profile_name}'.")
+        try:
+            # Ensure the model selected supports structured output (most recent OpenAI do)
+            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 create_starting_agent(self, mcp_servers: List[MCPServer]) -> Agent:
+        """Create the SuggestionAgent."""
+        logger.debug("Creating SuggestionAgent...")
+        self._model_instance_cache = {}
+        self._openai_client_cache = {}
+
+        default_profile_name = self.config.get("llm_profile", "default")
+        # Verify the chosen profile/model supports structured output if possible, or rely on OpenAI's newer models
+        logger.debug(f"Using LLM profile '{default_profile_name}' for SuggestionAgent.")
+        model_instance = self._get_model_instance(default_profile_name)
+
+        suggestion_agent_instructions = (
+            "You are the SuggestionAgent. Analyze the user's input and generate exactly three relevant, "
+            "concise follow-up questions or conversation starters as a JSON object with a single key 'suggestions' "
+            "containing a list of strings."
+        )
+
+        suggestion_agent = Agent(
+            name="SuggestionAgent",
+            instructions=suggestion_agent_instructions,
+            tools=[], # No function tools needed
+            model=model_instance,
+            output_type=SuggestionsOutput, # Enforce the TypedDict structure
+            mcp_servers=mcp_servers # Pass along, though unused
+        )
+        logger.debug("SuggestionAgent created with output_type enforcement.")
+        return suggestion_agent
+
+if __name__ == "__main__":
+    SuggestionBlueprint.main()