autobyteus 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

examples/run_mcp_browser_client.py

@@ -0,0 +1,174 @@
+# file: autobyteus/examples/run_mcp_browser_client.py
+"""
+This example script demonstrates how to create a standalone MCP client in Python
+to connect to and interact with the Browser MCP server.
+
+This script uses only the 'mcp' library and standard Python libraries,
+intentionally avoiding the 'autobyteus' framework abstractions.
+This approach is useful for understanding the low-level communication
+with an MCP server.
+
+The script will:
+1.  Define the parameters to launch the Browser MCP server (`npx @browsermcp/mcp@latest`).
+2.  Start the server process and establish an stdio transport.
+3.  Initialize an MCP client session.
+4.  List the available tools from the server.
+5.  Call the 'open_page' tool to open a website.
+6.  Call the 'get_page_content' tool to retrieve the page's text.
+7.  Properly clean up the session and server process.
+"""
+
+import asyncio
+import logging
+import sys
+import json
+from contextlib import AsyncExitStack
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+# --- Logging Setup ---
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(levelname)s - %(name)s - %(message)s',
+    stream=sys.stdout,
+)
+logger = logging.getLogger("mcp_browser_client")
+
+
+class MCPBrowserClient:
+    """
+    A client for interacting with a Browser MCP server over stdio.
+    """
+
+    def __init__(self):
+        self.session: ClientSession | None = None
+        self.exit_stack = AsyncExitStack()
+        self.page_id: str | None = None
+
+    async def connect(self):
+        """
+        Starts the browser MCP server and connects to it.
+        """
+        logger.info("Defining server parameters for Browser MCP...")
+        # These parameters specify how to run the MCP server.
+        # This is the same command used by the `run_browser_agent.py` example.
+        server_params = StdioServerParameters(
+            command="npx",
+            args=["@browsermcp/mcp@latest"],
+            env=None,
+        )
+
+        logger.info(f"Starting server with command: '{server_params.command} {' '.join(server_params.args)}'")
+
+        # `stdio_client` is a context manager that starts the process
+        # and provides reader/writer streams for communication.
+        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
+        read, write = stdio_transport
+
+        logger.info("Server process started. Establishing MCP session...")
+
+        # `ClientSession` is another context manager that handles the MCP protocol.
+        self.session = await self.exit_stack.enter_async_context(ClientSession(read, write))
+
+        # The initialize handshake must be performed after connection.
+        await self.session.initialize()
+        logger.info("MCP session initialized successfully.")
+
+        # Let's see what tools the server offers.
+        response = await self.session.list_tools()
+        tool_names = [tool.name for tool in response.tools]
+        logger.info(f"Connected to server. Available tools: {tool_names}")
+
+    async def call_tool(self, tool_name: str, **kwargs):
+        """
+        A wrapper to call a tool on the server and print the result.
+        """
+        if not self.session:
+            raise RuntimeError("Client not connected. Call connect() first.")
+
+        logger.info(f"Calling tool '{tool_name}' with arguments: {kwargs}")
+        try:
+            result = await self.session.call_tool(tool_name, kwargs)
+            logger.info(f"Tool '{tool_name}' executed successfully.")
+
+            # The result content is a list of blocks. For many tools, it's a single text block.
+            if result.content and hasattr(result.content[0], 'text'):
+                tool_output = result.content[0].text
+                logger.info(f"--> Result from '{tool_name}':\n{tool_output[:500]}...")
+                return tool_output
+            else:
+                logger.info(f"--> Result from '{tool_name}' has no text content: {result.content}")
+                return result.content
+        except Exception as e:
+            logger.error(f"An error occurred while calling tool '{tool_name}': {e}", exc_info=True)
+            raise
+
+    async def cleanup(self):
+        """
+        Closes the session and stops the server process.
+        The AsyncExitStack handles this automatically.
+        """
+        logger.info("Cleaning up resources and closing server connection...")
+        await self.exit_stack.aclose()
+        logger.info("Cleanup complete.")
+
+    async def run_demo_flow(self):
+        """
+        Executes a simple workflow: open a page, get its content, and close it.
+        """
+        try:
+            # 1. Open a page
+            open_page_result = await self.call_tool("open_page", url="https://www.google.com/search?q=mcp+protocol")
+
+            # The 'open_page' tool returns a JSON string with the pageId.
+            # We need to parse it to use in subsequent calls.
+            if not isinstance(open_page_result, str):
+                logger.error(f"Expected a string from 'open_page', but got {type(open_page_result)}")
+                return
+
+            try:
+                page_info = json.loads(open_page_result)
+                self.page_id = page_info.get("pageId")
+                if not self.page_id:
+                    logger.error("Could not find 'pageId' in the result from 'open_page'.")
+                    return
+                logger.info(f"Successfully opened page. Page ID: {self.page_id}")
+            except (json.JSONDecodeError, AttributeError) as e:
+                logger.error(f"Failed to parse pageId from 'open_page' result: {e}")
+                return
+
+            # 2. Get the page content
+            # Add a small delay for the page to potentially load dynamic content.
+            logger.info("Waiting for 2 seconds before getting content...")
+            await asyncio.sleep(2)
+
+            await self.call_tool("get_page_content", pageId=self.page_id)
+
+            # 3. Close the page
+            await self.call_tool("close_page", pageId=self.page_id)
+            logger.info(f"Page {self.page_id} closed.")
+
+        except Exception as e:
+            logger.error(f"An error occurred during the demo flow: {e}")
+
+
+async def main():
+    """
+    Main function to run the MCP Browser Client.
+    """
+    logger.info("--- Starting Standalone MCP Browser Client Example ---")
+    client = MCPBrowserClient()
+    try:
+        await client.connect()
+        await client.run_demo_flow()
+    finally:
+        await client.cleanup()
+    logger.info("--- Standalone MCP Browser Client Example Finished ---")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except (KeyboardInterrupt, SystemExit):
+        logger.info("Script interrupted by user. Exiting.")
+

examples/run_mcp_google_slides_client.py

@@ -0,0 +1,270 @@
+import asyncio
+import logging
+import sys
+import os
+import json
+import argparse
+from pathlib import Path
+from datetime import datetime
+from typing import AsyncIterator, Optional, List
+
+# --- Boilerplate to make the script runnable from the project root ---
+
+# Ensure the autobyteus package is discoverable
+SCRIPT_DIR = Path(__file__).resolve().parent
+PACKAGE_ROOT = SCRIPT_DIR.parent
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+# Load environment variables from .env file in the project root
+try:
+    from dotenv import load_dotenv
+    env_file_path = PACKAGE_ROOT / ".env"
+    if env_file_path.exists():
+        load_dotenv(env_file_path)
+        print(f"Loaded environment variables from: {env_file_path}")
+    else:
+        print(f"Info: No .env file found at: {env_file_path}. Relying on exported environment variables.")
+except ImportError:
+    print("Warning: python-dotenv not installed. Cannot load .env file.")
+
+# --- Imports for the MCP Client Example ---
+
+try:
+    # High-level components for the full workflow
+    from autobyteus.tools.mcp import McpToolRegistrar
+    from autobyteus.tools.registry import ToolRegistry, default_tool_registry, ToolDefinition
+    from autobyteus.agent.context import AgentContext, AgentConfig, AgentRuntimeState
+    from autobyteus.llm.base_llm import BaseLLM
+    from autobyteus.llm.utils.response_types import CompleteResponse, ChunkResponse
+except ImportError as e:
+    print(f"Error importing autobyteus components: {e}", file=sys.stderr)
+    print("Please ensure that the autobyteus library is installed and accessible in your PYTHONPATH.", file=sys.stderr)
+    sys.exit(1)
+
+# --- Basic Logging Setup ---
+# A logger for this script
+logger = logging.getLogger("mcp_client_example")
+
+# --- Dummy LLM for creating AgentContext ---
+class DummyLLM(BaseLLM):
+    """A dummy LLM implementation required to instantiate AgentConfig."""
+    def __init__(self):
+        # We need to provide a model and config to the BaseLLM constructor.
+        # Let's use a dummy model configuration.
+        from autobyteus.llm.models import LLMModel
+        from autobyteus.llm.utils.llm_config import LLMConfig
+        from autobyteus.llm.llm_factory import default_llm_factory
+
+        # Ensure factory is initialized to access models
+        default_llm_factory.ensure_initialized()
+
+        # Pick any existing model for the dummy, e.g., the first one available.
+        try:
+            # Iterating through LLMModel is now possible due to metaclass
+            dummy_model_instance = next(iter(LLMModel))
+        except StopIteration:
+            # This is a fallback in case no models are registered, which is unlikely but safe.
+            raise RuntimeError("No LLMModels are registered in the factory. Cannot create DummyLLM.")
+        
+        super().__init__(model=dummy_model_instance, llm_config=LLMConfig())
+
+    def configure_system_prompt(self, system_prompt: str):
+        # This is on BaseLLM. My no-op implementation is fine.
+        super().configure_system_prompt(system_prompt)
+
+    async def _send_user_message_to_llm(self, user_message: str, image_urls: Optional[List[str]] = None, **kwargs) -> CompleteResponse:
+        """Dummy implementation for sending a message."""
+        logger.debug("DummyLLM._send_user_message_to_llm called.")
+        return CompleteResponse(content="This is a dummy response from a dummy LLM.", usage=None)
+
+    async def _stream_user_message_to_llm(
+        self, user_message: str, image_urls: Optional[List[str]] = None, **kwargs
+    ) -> AsyncIterator[ChunkResponse]:
+        """Dummy implementation for streaming a message."""
+        logger.debug("DummyLLM._stream_user_message_to_llm called.")
+        yield ChunkResponse(content="This is a dummy response from a dummy LLM.", is_complete=True, usage=None)
+
+
+def setup_logging(debug: bool = False):
+    """Configures logging for the script."""
+    log_level = logging.DEBUG if debug else logging.INFO
+    root_logger = logging.getLogger()
+    if root_logger.hasHandlers():
+        for handler in root_logger.handlers[:]:
+            root_logger.removeHandler(handler)
+    logging.basicConfig(
+        level=log_level,
+        format='%(asctime)s - %(levelname)s - %(name)s - %(message)s',
+        stream=sys.stdout,
+    )
+    if debug:
+        logging.getLogger("autobyteus").setLevel(logging.DEBUG)
+        logger.info("Debug logging enabled.")
+    else:
+        logging.getLogger("autobyteus").setLevel(logging.INFO)
+
+# --- Environment Variable Checks ---
+def check_required_env_vars():
+    """Checks for environment variables required by this example and returns them."""
+    required_vars = {
+        "script_path": "TEST_GOOGLE_SLIDES_MCP_SCRIPT_PATH",
+        "google_client_id": "GOOGLE_CLIENT_ID",
+        "google_client_secret": "GOOGLE_CLIENT_SECRET",
+        "google_refresh_token": "GOOGLE_REFRESH_TOKEN",
+    }
+    env_values = {}
+    missing_vars = []
+    for key, var_name in required_vars.items():
+        value = os.environ.get(var_name)
+        if not value:
+            missing_vars.append(var_name)
+        else:
+            env_values[key] = value
+    if missing_vars:
+        logger.error("This example requires the following environment variables to be set: %s", missing_vars)
+        sys.exit(1)
+    if not Path(env_values["script_path"]).exists():
+        logger.error(f"The script path specified by TEST_GOOGLE_SLIDES_MCP_SCRIPT_PATH does not exist: {env_values['script_path']}")
+        sys.exit(1)
+    return env_values
+
+def print_tool_definitions(tool_definitions: List[ToolDefinition]):
+    """Iterates through a list of tool definitions and prints their JSON schema."""
+    print("\n--- Registered Tool Schemas (from ToolDefinition) ---")
+    for tool_definition in sorted(tool_definitions, key=lambda d: d.name):
+        try:
+            tool_json_schema = tool_definition.get_usage_json()
+            print(f"\n# Tool: {tool_definition.name}")
+            print(json.dumps(tool_json_schema, indent=2))
+        except Exception as e:
+            print(f"\n# Tool: {tool_definition.name}")
+            print(f"  Error getting schema from definition: {e}")
+    print("\n--------------------------------------------------------\n")
+
+
+async def main():
+    """
+    Main function demonstrating the full end-to-end MCP integration workflow.
+    """
+    logger.info("--- Starting MCP Integration Workflow Example ---")
+    
+    env_vars = check_required_env_vars()
+    
+    # 1. Instantiate the core MCP and registry components.
+    tool_registry = default_tool_registry
+    registrar = McpToolRegistrar()
+
+    # 2. Define the configuration for the MCP server as a dictionary.
+    server_id = "google-slides-mcp"
+    google_slides_mcp_config_dict = {
+        server_id: {
+            "transport_type": "stdio",
+            "stdio_params": {
+                "command": "node",
+                "args": [env_vars["script_path"]],
+                "env": {
+                    "GOOGLE_CLIENT_ID": env_vars["google_client_id"],
+                    "GOOGLE_CLIENT_SECRET": env_vars["google_client_secret"],
+                    "GOOGLE_REFRESH_TOKEN": env_vars["google_refresh_token"],
+                }
+            },
+            "enabled": True,
+            "tool_name_prefix": "gslides",
+        }
+    }
+
+    try:
+        # 3. Discover and register tools by passing the config dictionary directly.
+        logger.info(f"Performing targeted discovery for remote tools from server '{server_id}'...")
+        await registrar.discover_and_register_tools(mcp_config=google_slides_mcp_config_dict)
+        # Use the ToolRegistry to get tools by their source server ID.
+        registered_tool_defs = tool_registry.get_tools_by_mcp_server(server_id)
+        logger.info(f"Tool registration complete. Discovered tools: {[t.name for t in registered_tool_defs]}")
+
+        # 4. Create an instance of a specific tool using the ToolRegistry.
+        create_tool_name = "gslides_create_presentation"
+        summarize_tool_name = "gslides_summarize_presentation"
+        
+        if create_tool_name not in tool_registry.list_tool_names():
+            logger.error(f"Tool '{create_tool_name}' was not found in the registry. Aborting.")
+            return
+
+        logger.info(f"Creating an instance of the '{create_tool_name}' tool from the registry...")
+        create_presentation_tool = tool_registry.create_tool(create_tool_name)
+        
+        logger.info(f"Creating an instance of the '{summarize_tool_name}' tool from the registry...")
+        summarize_presentation_tool = tool_registry.create_tool(summarize_tool_name)
+
+        # 5. Execute the tool using its standard .execute() method.
+        presentation_title = f"AutoByteUs E2E Demo - {datetime.now().isoformat()}"
+        logger.info(f"Executing '{create_tool_name}' with title: '{presentation_title}'")
+        
+        dummy_llm = DummyLLM()
+        dummy_config = AgentConfig(
+            name="mcp_example_runner_agent",
+            role="tool_runner",
+            description="A dummy agent config for running tools outside of a full agent.",
+            llm_instance=dummy_llm,
+            system_prompt="N/A",
+            tools=[]
+        )
+        dummy_state = AgentRuntimeState(agent_id="mcp_example_runner")
+        dummy_context = AgentContext(agent_id="mcp_example_runner", config=dummy_config, state=dummy_state)
+        
+        create_result = await create_presentation_tool.execute(
+            context=dummy_context,
+            title=presentation_title
+        )
+        
+        if not isinstance(create_result, str):
+            raise ValueError(f"Unexpected result type from tool '{create_tool_name}'. Expected a JSON string. Got: {type(create_result)}")
+
+        presentation_object = json.loads(create_result)
+        actual_presentation_id = presentation_object.get("presentationId")
+
+        if not actual_presentation_id:
+            raise ValueError(f"Could not find 'presentationId' in the response. Response: {create_result[:200]}...")
+
+        logger.info(f"Tool '{create_tool_name}' executed. Extracted Presentation ID: {actual_presentation_id}")
+
+        # 6. Execute the second tool.
+        logger.info(f"Executing '{summarize_tool_name}' for presentation ID: {actual_presentation_id}")
+        summary_result = await summarize_presentation_tool.execute(
+            context=dummy_context,
+            presentationId=actual_presentation_id
+        )
+        
+        if not isinstance(summary_result, str):
+            raise ValueError(f"Unexpected result type from tool '{summarize_tool_name}'. Got: {type(summary_result)}")
+
+        logger.info(f"Tool '{summarize_tool_name}' executed successfully.")
+        print("\n--- Presentation Summary ---")
+        print(summary_result)
+        print("--------------------------\n")
+        
+        # 7. Print all tool schemas for verification
+        print_tool_definitions(registered_tool_defs)
+
+    except Exception as e:
+        logger.error(f"An error occurred during the workflow: {e}", exc_info=True)
+    
+    logger.info("--- MCP Integration Workflow Example Finished ---")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run the full MCP registration and execution workflow.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug level logging on the console.")
+    args = parser.parse_args()
+    
+    setup_logging(debug=args.debug)
+
+    try:
+        asyncio.run(main())
+    except (KeyboardInterrupt, SystemExit) as e:
+        if isinstance(e, SystemExit) and e.code == 0:
+             logger.info("Script exited normally.")
+        else:
+             logger.info(f"Script interrupted ({type(e).__name__}). Exiting.")
+    except Exception as e:
+        logger.error(f"An unhandled error occurred at the top level: {e}", exc_info=True)

examples/run_mcp_list_tools.py

@@ -0,0 +1,189 @@
+# file: autobyteus/examples/run_mcp_list_tools.py
+"""
+This example script demonstrates how to use the McpToolRegistrar to connect
+to a remote MCP server and list the available tools without registering or
+executing them.
+
+This is a "dry-run" or "preview" operation, useful for inspecting the
+capabilities of a remote MCP server.
+"""
+import asyncio
+import logging
+import sys
+import os
+import json
+import argparse
+from pathlib import Path
+from typing import List
+
+# --- Boilerplate to make the script runnable from the project root ---
+
+# Ensure the autobyteus package is discoverable
+SCRIPT_DIR = Path(__file__).resolve().parent
+PACKAGE_ROOT = SCRIPT_DIR.parent
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+# Load environment variables from .env file in the project root
+try:
+    from dotenv import load_dotenv
+    env_file_path = PACKAGE_ROOT / ".env"
+    if env_file_path.exists():
+        load_dotenv(env_file_path)
+        print(f"Loaded environment variables from: {env_file_path}")
+    else:
+        print(f"Info: No .env file found at: {env_file_path}. Relying on exported environment variables.")
+except ImportError:
+    print("Warning: python-dotenv not installed. Cannot load .env file.")
+
+# --- Imports for the MCP Client Example ---
+
+try:
+    from autobyteus.tools.mcp import McpToolRegistrar
+    from autobyteus.tools.registry import ToolDefinition
+except ImportError as e:
+    print(f"Error importing autobyteus components: {e}", file=sys.stderr)
+    print("Please ensure that the autobyteus library is installed and accessible in your PYTHONPATH.", file=sys.stderr)
+    sys.exit(1)
+
+# --- Basic Logging Setup ---
+logger = logging.getLogger("mcp_list_tools_example")
+
+def setup_logging(debug: bool = False):
+    """Configures logging for the script."""
+    log_level = logging.DEBUG if debug else logging.INFO
+    root_logger = logging.getLogger()
+    if root_logger.hasHandlers():
+        for handler in root_logger.handlers[:]:
+            root_logger.removeHandler(handler)
+    logging.basicConfig(
+        level=log_level,
+        format='%(asctime)s - %(levelname)s - %(name)s - %(message)s',
+        stream=sys.stdout,
+    )
+    if debug:
+        logging.getLogger("autobyteus").setLevel(logging.DEBUG)
+        logger.info("Debug logging enabled.")
+    else:
+        logging.getLogger("autobyteus").setLevel(logging.INFO)
+
+# --- Environment Variable Checks ---
+def check_required_env_vars():
+    """Checks for environment variables required by the SQLite MCP server."""
+    required_vars = {
+        "script_path": "TEST_SQLITE_MCP_SCRIPT_PATH",
+        "db_path": "TEST_SQLITE_DB_PATH",
+    }
+    env_values = {}
+    missing_vars = []
+    for key, var_name in required_vars.items():
+        value = os.environ.get(var_name)
+        if not value:
+            missing_vars.append(var_name)
+        else:
+            env_values[key] = value
+    if missing_vars:
+        logger.error("This example requires the following environment variables to be set: %s", missing_vars)
+        logger.error("Example usage in your .env file:")
+        logger.error('TEST_SQLITE_MCP_SCRIPT_PATH="/path/to/mcp-database-server/dist/src/index.js"')
+        logger.error('TEST_SQLITE_DB_PATH="/path/to/your/database.db"')
+        sys.exit(1)
+
+    script_path_obj = Path(env_values["script_path"])
+    if not script_path_obj.exists():
+        logger.error(f"The script path specified by TEST_SQLITE_MCP_SCRIPT_PATH does not exist: {script_path_obj}")
+        sys.exit(1)
+
+    db_path_obj = Path(env_values["db_path"])
+    if not db_path_obj.exists():
+        logger.error(f"The database path specified by TEST_SQLITE_DB_PATH does not exist: {db_path_obj}")
+        logger.error("Please ensure the database file is created before running this script.")
+        sys.exit(1)
+        
+    return env_values
+
+def print_tool_definitions(tool_definitions: List[ToolDefinition]):
+    """Iterates through a list of tool definitions and prints their JSON schema."""
+    print("\n--- Discovered Remote Tool Schemas (from ToolDefinition) ---")
+    for tool_definition in sorted(tool_definitions, key=lambda d: d.name):
+        try:
+            # get_usage_json() provides a provider-agnostic JSON schema representation
+            tool_json_schema = tool_definition.get_usage_json()
+            print(f"\n# Tool: {tool_definition.name}")
+            print(f"  Description: {tool_definition.description}")
+            print("# Schema (JSON):")
+            # Pretty-print the JSON schema
+            print(json.dumps(tool_json_schema, indent=2))
+        except Exception as e:
+            print(f"\n# Tool: {tool_definition.name}")
+            print(f"  Error getting schema from definition: {e}")
+    print("\n--------------------------------------------------------\n")
+
+
+async def main():
+    """
+    Main function to connect to the SQLite MCP server and list its tools.
+    """
+    logger.info("--- Starting MCP Remote Tool Listing Example ---")
+    
+    env_vars = check_required_env_vars()
+    
+    # 1. Instantiate the McpToolRegistrar.
+    registrar = McpToolRegistrar()
+
+    # 2. Define the configuration for the SQLite MCP server.
+    server_id = "sqlite-mcp"
+    sqlite_mcp_config_dict = {
+        server_id: {
+            "transport_type": "stdio",
+            "stdio_params": {
+                "command": "node",
+                "args": [
+                    env_vars["script_path"],
+                    env_vars["db_path"],
+                ],
+                "env": {}, # No specific env vars needed for the SQLite server itself
+            },
+            "enabled": True,
+            "tool_name_prefix": "sqlite",
+        }
+    }
+
+    try:
+        # 3. Use the registrar's `list_remote_tools` method for a preview.
+        # This connects to the server, lists tools, and disconnects without
+        # adding them to the main tool registry.
+        logger.info(f"Connecting to remote server '{server_id}' to preview available tools...")
+        
+        tool_definitions = await registrar.list_remote_tools(mcp_config=sqlite_mcp_config_dict)
+        
+        # 4. Print the results.
+        if tool_definitions:
+            print_tool_definitions(tool_definitions)
+            logger.info(f"Successfully listed {len(tool_definitions)} tools from the remote server.")
+        else:
+            logger.warning("No tools were found on the remote server.")
+
+    except Exception as e:
+        logger.error(f"An error occurred while trying to list remote tools: {e}", exc_info=True)
+    
+    logger.info("--- MCP Remote Tool Listing Example Finished ---")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="List available tools from the remote SQLite MCP server.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug level logging on the console.")
+    args = parser.parse_args()
+    
+    setup_logging(debug=args.debug)
+
+    try:
+        asyncio.run(main())
+    except (KeyboardInterrupt, SystemExit) as e:
+        # Gracefully handle user interruption or normal exit.
+        if isinstance(e, SystemExit) and e.code == 0:
+             logger.info("Script exited normally.")
+        else:
+             logger.warning(f"Script interrupted ({type(e).__name__}). Exiting.")
+    except Exception as e:
+        logger.error(f"An unhandled error occurred at the top level: {e}", exc_info=True)