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

autobyteus/tools/mcp/registrar.py

@@ -1,6 +1,6 @@
 # file: autobyteus/autobyteus/tools/mcp/registrar.py
 import logging
-from typing import Dict
+from typing import Any, Dict, List, Optional, Union
 
 # Import the new handler architecture components
 from .call_handlers import (
@@ -15,34 +15,32 @@ from autobyteus.tools.mcp import (
     McpConfigService,
     McpSchemaMapper,
     McpToolFactory,
-    McpTransportType
+    McpTransportType,
+    BaseMcpConfig
 )
 
 from autobyteus.tools.registry import ToolRegistry, ToolDefinition
+from autobyteus.tools.tool_category import ToolCategory
+from autobyteus.utils.singleton import SingletonMeta
 from mcp import types as mcp_types
 
 
 logger = logging.getLogger(__name__)
 
-class McpToolRegistrar:
+class McpToolRegistrar(metaclass=SingletonMeta):
     """
     Orchestrates the discovery of remote MCP tools and their registration
     with the AutoByteUs ToolRegistry using a handler-based architecture.
+    This class is a singleton.
     """
-    def __init__(self,
-                 config_service: McpConfigService,
-                 schema_mapper: McpSchemaMapper,
-                 tool_registry: ToolRegistry):
-        if not isinstance(config_service, McpConfigService):
-            raise TypeError("config_service must be an McpConfigService instance.")
-        if not isinstance(schema_mapper, McpSchemaMapper):
-            raise TypeError("schema_mapper must be an McpSchemaMapper instance.")
-        if not isinstance(tool_registry, ToolRegistry):
-            raise TypeError("tool_registry must be a ToolRegistry instance.")
-
-        self._config_service = config_service
-        self._schema_mapper = schema_mapper
-        self._tool_registry = tool_registry
+    def __init__(self):
+        """
+        Initializes the McpToolRegistrar singleton.
+        It retrieves singleton instances of its service dependencies and initializes
+        its internal state for tracking registered tools.
+        """
+        self._config_service: McpConfigService = McpConfigService()
+        self._tool_registry: ToolRegistry = ToolRegistry()
         
         # The handler registry maps a transport type to a reusable handler instance.
         self._handler_registry: Dict[McpTransportType, McpCallHandler] = {
@@ -50,35 +48,119 @@ class McpToolRegistrar:
             McpTransportType.STREAMABLE_HTTP: StreamableHttpMcpCallHandler(),
             McpTransportType.SSE: SseMcpCallHandler(),
         }
+
+        # Internal state to track which ToolDefinitions were registered from which server.
+        self._registered_tools_by_server: Dict[str, List[ToolDefinition]] = {}
         
         logger.info(f"McpToolRegistrar initialized with {len(self._handler_registry)} call handlers.")
 
-    async def discover_and_register_tools(self) -> None:
+    def _create_tool_definition_from_remote(
+        self,
+        remote_tool: mcp_types.Tool,
+        server_config: BaseMcpConfig,
+        handler: McpCallHandler,
+        schema_mapper: McpSchemaMapper
+    ) -> ToolDefinition:
         """
-        Discovers tools from all enabled MCP servers and registers them.
+        Maps a single remote tool from an MCP server to an AutoByteUs ToolDefinition.
+        This is a helper method to centralize the mapping logic.
         """
-        logger.info("Starting MCP tool discovery and registration process.")
-        all_server_configs = self._config_service.get_all_configs() 
-        if not all_server_configs:
-            logger.info("No MCP server configurations found. Skipping discovery.")
-            return
+        if hasattr(remote_tool, 'model_dump_json'):
+            logger.debug(f"Processing remote tool from server '{server_config.server_id}':\n{remote_tool.model_dump_json(indent=2)}")
+
+        actual_arg_schema = schema_mapper.map_to_autobyteus_schema(remote_tool.inputSchema)
+        actual_desc = remote_tool.description
+        
+        registered_name = remote_tool.name
+        if server_config.tool_name_prefix:
+            registered_name = f"{server_config.tool_name_prefix.rstrip('_')}_{remote_tool.name}"
+
+        tool_factory = McpToolFactory(
+            mcp_server_config=server_config,
+            mcp_remote_tool_name=remote_tool.name,
+            mcp_call_handler=handler,
+            registered_tool_name=registered_name,
+            tool_description=actual_desc,
+            tool_argument_schema=actual_arg_schema
+        )
+        
+        tool_def = ToolDefinition(
+            name=registered_name,
+            description=actual_desc,
+            argument_schema=actual_arg_schema,
+            category=ToolCategory.MCP,
+            custom_factory=tool_factory.create_tool,
+            config_schema=None,
+            tool_class=None
+        )
+        return tool_def
 
-        registered_count = 0
-        for server_config in all_server_configs:
+    async def discover_and_register_tools(self, mcp_config: Optional[Union[BaseMcpConfig, Dict[str, Any]]] = None) -> List[ToolDefinition]:
+        """
+        Discovers tools from MCP servers and registers them.
+
+        If `mcp_config` is provided (as a validated object or a raw dictionary),
+        it discovers tools only from that specific server, unregistering any
+        of its old tools first.
+        
+        If `mcp_config` is None, it unregisters all existing MCP tools and then
+        discovers tools from all enabled servers found in the McpConfigService.
+        
+        Returns:
+            A list of ToolDefinition objects for all tools that were successfully
+            discovered and registered during this call.
+        """
+        configs_to_process: List[BaseMcpConfig]
+        
+        if mcp_config:
+            validated_config: BaseMcpConfig
+            # If the user provided a raw dictionary, parse and add it via the service.
+            if isinstance(mcp_config, dict):
+                try:
+                    validated_config = self._config_service.load_config(mcp_config)
+                except ValueError as e:
+                    logger.error(f"Failed to parse provided MCP config dictionary: {e}")
+                    raise
+            # If a validated object was passed, add it to the service to ensure it's known.
+            elif isinstance(mcp_config, BaseMcpConfig):
+                validated_config = self._config_service.add_config(mcp_config)
+            else:
+                raise TypeError(f"mcp_config must be a BaseMcpConfig object or a dictionary, not {type(mcp_config)}.")
+            
+            logger.info(f"Starting targeted MCP tool discovery for server: {validated_config.server_id}")
+            # Unregister any existing tools from this server before re-discovering.
+            self.unregister_tools_from_server(validated_config.server_id)
+            configs_to_process = [validated_config]
+        else:
+            logger.info("Starting full MCP tool discovery and registration process. Unregistering all existing MCP tools first.")
+            # Get a copy of all server IDs that have tools registered.
+            all_server_ids = list(self._registered_tools_by_server.keys())
+            for server_id in all_server_ids:
+                self.unregister_tools_from_server(server_id)
+            
+            # The registrar's internal state should now be empty, but a clear() is a good safeguard.
+            self._registered_tools_by_server.clear()
+            
+            configs_to_process = self._config_service.get_all_configs()
+
+        if not configs_to_process:
+            logger.info("No MCP server configurations to process. Skipping discovery.")
+            return []
+
+        schema_mapper = McpSchemaMapper()
+        registered_tool_definitions: List[ToolDefinition] = []
+        for server_config in configs_to_process:
             if not server_config.enabled:
                 logger.info(f"MCP server '{server_config.server_id}' is disabled. Skipping.")
                 continue
 
             logger.info(f"Discovering tools from MCP server: '{server_config.server_id}' ({server_config.transport_type.value})")
             try:
-                # Get the correct handler for this server's transport type.
                 handler = self._handler_registry.get(server_config.transport_type)
                 if not handler:
                     logger.error(f"No MCP call handler found for transport type '{server_config.transport_type.value}' on server '{server_config.server_id}'.")
                     continue
 
-                # Use the handler to call the special 'list_tools' method.
-                # The registrar does not need to know how this is done; it's encapsulated in the handler.
                 remote_tools_result = await handler.handle_call(
                     config=server_config,
                     remote_tool_name="list_tools",
@@ -94,42 +176,148 @@ class McpToolRegistrar:
 
                 for remote_tool in actual_remote_tools: 
                     try:
-                        if hasattr(remote_tool, 'model_dump_json'):
-                             logger.debug(f"Processing remote tool from server '{server_config.server_id}':\n{remote_tool.model_dump_json(indent=2)}")
-                        
-                        actual_arg_schema = self._schema_mapper.map_to_autobyteus_schema(remote_tool.inputSchema)
-                        actual_desc = remote_tool.description
+                        tool_def = self._create_tool_definition_from_remote(remote_tool, server_config, handler, schema_mapper)
                         
-                        registered_name = remote_tool.name
-                        if server_config.tool_name_prefix:
-                            registered_name = f"{server_config.tool_name_prefix.rstrip('_')}_{remote_tool.name}"
-
-                        # Create the tool factory, injecting the server config and the correct handler.
-                        tool_factory = McpToolFactory(
-                            mcp_server_config=server_config,
-                            mcp_remote_tool_name=remote_tool.name,
-                            mcp_call_handler=handler,
-                            registered_tool_name=registered_name,
-                            tool_description=actual_desc,
-                            tool_argument_schema=actual_arg_schema
-                        )
+                        self._tool_registry.register_tool(tool_def)
+                        self._registered_tools_by_server.setdefault(server_config.server_id, []).append(tool_def)
+                        registered_tool_definitions.append(tool_def)
                         
-                        tool_def = ToolDefinition(
-                            name=registered_name,
-                            description=actual_desc,
-                            argument_schema=actual_arg_schema,
-                            custom_factory=tool_factory.create_tool,
-                            config_schema=None,
-                            tool_class=None
-                        )
+                        logger.info(f"Successfully registered MCP tool '{remote_tool.name}' from server '{server_config.server_id}' as '{tool_def.name}'.")
 
-                        self._tool_registry.register_tool(tool_def)
-                        logger.info(f"Successfully registered MCP tool '{remote_tool.name}' from server '{server_config.server_id}' as '{registered_name}'.")
-                        registered_count +=1
                     except Exception as e_tool:
                         logger.error(f"Failed to process or register remote tool '{remote_tool.name}' from server '{server_config.server_id}': {e_tool}", exc_info=True)
             
             except Exception as e_server:
                 logger.error(f"Failed to discover tools from MCP server '{server_config.server_id}': {e_server}", exc_info=True)
         
-        logger.info(f"MCP tool discovery and registration process completed. Total tools registered: {registered_count}.")
+        logger.info(f"MCP tool discovery and registration process completed. Total tools registered: {len(registered_tool_definitions)}.")
+        return registered_tool_definitions
+
+    async def list_remote_tools(self, mcp_config: Union[BaseMcpConfig, Dict[str, Any]]) -> List[ToolDefinition]:
+        """
+        Previews tools from a remote MCP server without registering them or storing the configuration.
+        This is a stateless "dry-run" or "preview" operation.
+
+        Args:
+            mcp_config: A single MCP server configuration, as a validated object or a raw dictionary.
+        
+        Returns:
+            A list of ToolDefinition objects for all tools discovered on the server.
+        
+        Raises:
+            TypeError: If mcp_config is not a supported type.
+            ValueError: If the provided configuration is invalid.
+            RuntimeError: If the connection or tool call to the remote server fails.
+        """
+        validated_config: BaseMcpConfig
+        if isinstance(mcp_config, dict):
+            # Use the static method to parse the config without storing it in the service.
+            validated_config = McpConfigService.parse_mcp_config_dict(mcp_config)
+        elif isinstance(mcp_config, BaseMcpConfig):
+            validated_config = mcp_config
+        else:
+            raise TypeError(f"mcp_config must be a BaseMcpConfig object or a dictionary, not {type(mcp_config)}.")
+        
+        logger.info(f"Previewing tools from MCP server: '{validated_config.server_id}' ({validated_config.transport_type.value})")
+        
+        schema_mapper = McpSchemaMapper()
+        tool_definitions: List[ToolDefinition] = []
+
+        try:
+            handler = self._handler_registry.get(validated_config.transport_type)
+            if not handler:
+                raise ValueError(f"No MCP call handler found for transport type '{validated_config.transport_type.value}'.")
+
+            remote_tools_result = await handler.handle_call(
+                config=validated_config,
+                remote_tool_name="list_tools",
+                arguments={}
+            )
+            
+            if not isinstance(remote_tools_result, mcp_types.ListToolsResult):
+                error_msg = f"Expected ListToolsResult from handler, but got {type(remote_tools_result)}. Cannot preview tools from server '{validated_config.server_id}'."
+                logger.error(error_msg)
+                raise RuntimeError(error_msg)
+
+            actual_remote_tools: list[mcp_types.Tool] = remote_tools_result.tools
+            logger.info(f"Discovered {len(actual_remote_tools)} tools from server '{validated_config.server_id}' for preview.")
+
+            for remote_tool in actual_remote_tools:
+                try:
+                    tool_def = self._create_tool_definition_from_remote(remote_tool, validated_config, handler, schema_mapper)
+                    tool_definitions.append(tool_def)
+                except Exception as e_tool:
+                    logger.error(f"Failed to map remote tool '{remote_tool.name}' from server '{validated_config.server_id}' during preview: {e_tool}", exc_info=True)
+                    # For a preview, we continue to show other valid tools.
+            
+        except Exception as e_server:
+            logger.error(f"Failed to discover tools for preview from MCP server '{validated_config.server_id}': {e_server}", exc_info=True)
+            # Re-raise server-level exceptions to the caller as per AC5.
+            raise
+            
+        logger.info(f"MCP tool preview completed. Found {len(tool_definitions)} tools.")
+        return tool_definitions
+
+    def get_registered_tools_for_server(self, server_id: str) -> List[ToolDefinition]:
+        """
+        Returns a list of ToolDefinition objects that were successfully registered 
+        from a specific MCP server during the most recent discovery process.
+
+        Args:
+            server_id: The unique ID of the MCP server to query.
+
+        Returns:
+            A list of ToolDefinition objects. Returns an empty list if the server ID
+            is not found or registered no tools.
+        """
+        return self._registered_tools_by_server.get(server_id, [])
+
+    def get_all_registered_mcp_tools(self) -> List[ToolDefinition]:
+        """
+        Returns a flat list of all ToolDefinitions registered from any MCP server.
+        """
+        all_tools = []
+        for server_tools in self._registered_tools_by_server.values():
+            all_tools.extend(server_tools)
+        return all_tools
+
+    def is_server_registered(self, server_id: str) -> bool:
+        """
+        Checks if any tools from a specific MCP server are currently registered.
+
+        Args:
+            server_id: The unique ID of the MCP server.
+
+        Returns:
+            True if the server has tools registered, False otherwise.
+        """
+        is_registered = server_id in self._registered_tools_by_server
+        logger.debug(f"Checking if server '{server_id}' is registered: {is_registered}")
+        return is_registered
+
+    def unregister_tools_from_server(self, server_id: str) -> bool:
+        """
+        Unregisters all tools associated with a given MCP server ID from the
+        main ToolRegistry and removes the server from internal tracking.
+
+        Args:
+            server_id: The unique ID of the MCP server whose tools should be unregistered.
+
+        Returns:
+            True if the server was found and its tools were processed for unregistration,
+            False if the server was not found in the registrar's state.
+        """
+        if not self.is_server_registered(server_id):
+            logger.info(f"No tools found for server ID '{server_id}'. Nothing to unregister.")
+            return False
+
+        tools_to_unregister = self._registered_tools_by_server.get(server_id, [])
+        logger.info(f"Unregistering {len(tools_to_unregister)} tools from server ID: '{server_id}'...")
+
+        for tool_def in tools_to_unregister:
+            self._tool_registry.unregister_tool(tool_def.name)
+
+        # Remove the server from the tracking dictionary
+        del self._registered_tools_by_server[server_id]
+        logger.info(f"Successfully unregistered all tools and removed server '{server_id}' from registrar tracking.")
+        return True

autobyteus/tools/mcp/types.py

@@ -44,7 +44,11 @@ class StdioMcpServerConfig(BaseMcpConfig):
         super().__post_init__() 
         self.transport_type = McpTransportType.STDIO
 
-        # Added: Validation for command
+        # BUG FIX: Normalize cwd. An empty string is invalid for subprocess creation
+        # and should be treated as None (use parent CWD).
+        if self.cwd == '':
+            self.cwd = None
+
         if self.command is None or not isinstance(self.command, str) or not self.command.strip():
             raise ValueError(f"StdioMcpServerConfig '{self.server_id}' 'command' must be a non-empty string.")
         
@@ -66,7 +70,6 @@ class SseMcpServerConfig(BaseMcpConfig):
         super().__post_init__()
         self.transport_type = McpTransportType.SSE
 
-        # Added: Validation for url
         if self.url is None or not isinstance(self.url, str) or not self.url.strip():
             raise ValueError(f"SseMcpServerConfig '{self.server_id}' 'url' must be a non-empty string.")
         
@@ -86,7 +89,6 @@ class StreamableHttpMcpServerConfig(BaseMcpConfig):
         super().__post_init__()
         self.transport_type = McpTransportType.STREAMABLE_HTTP
 
-        # Added: Validation for url
         if self.url is None or not isinstance(self.url, str) or not self.url.strip():
             raise ValueError(f"StreamableHttpMcpServerConfig '{self.server_id}' 'url' must be a non-empty string.")
         

autobyteus/tools/registry/tool_definition.py

@@ -6,6 +6,7 @@ from typing import Dict, Any, List as TypingList, Type, TYPE_CHECKING, Optional,
 from autobyteus.llm.providers import LLMProvider
 from autobyteus.tools.tool_config import ToolConfig
 from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.tools.tool_category import ToolCategory
 from autobyteus.tools.usage.providers import (
     XmlSchemaProvider, 
     JsonSchemaProvider, 
@@ -27,6 +28,7 @@ class ToolDefinition:
                  name: str,
                  description: str,
                  argument_schema: Optional['ParameterSchema'],
+                 category: ToolCategory,
                  config_schema: Optional['ParameterSchema'] = None,
                  tool_class: Optional[Type['BaseTool']] = None,
                  custom_factory: Optional[Callable[['ToolConfig'], 'BaseTool']] = None):
@@ -52,6 +54,8 @@ class ToolDefinition:
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'argument_schema'. Expected ParameterSchema or None.")
         if config_schema is not None and not isinstance(config_schema, ParameterSchema):
              raise TypeError(f"ToolDefinition '{name}' received an invalid 'config_schema'. Expected ParameterSchema or None.")
+        if not isinstance(category, ToolCategory):
+            raise TypeError(f"ToolDefinition '{name}' requires a ToolCategory for 'category'. Got {type(category)}")
 
         self._name = name
         self._description = description
@@ -59,6 +63,7 @@ class ToolDefinition:
         self._config_schema: Optional['ParameterSchema'] = config_schema
         self._tool_class = tool_class
         self._custom_factory = custom_factory
+        self._category = category
         
         logger.debug(f"ToolDefinition created for tool '{self.name}'.")
 
@@ -75,6 +80,8 @@ class ToolDefinition:
     def argument_schema(self) -> Optional['ParameterSchema']: return self._argument_schema
     @property
     def config_schema(self) -> Optional['ParameterSchema']: return self._config_schema
+    @property
+    def category(self) -> ToolCategory: return self._category
     
     # --- Schema Generation API ---
     def get_usage_xml(self, provider: Optional[LLMProvider] = None) -> str:
@@ -129,4 +136,4 @@ class ToolDefinition:
 
     def __repr__(self) -> str:
         creator_repr = f"class='{self._tool_class.__name__}'" if self._tool_class else "factory=True"
-        return (f"ToolDefinition(name='{self.name}', {creator_repr})")
+        return (f"ToolDefinition(name='{self.name}', category='{self.category.value}', {creator_repr})")

autobyteus/tools/registry/tool_registry.py

@@ -43,6 +43,24 @@ class ToolRegistry(metaclass=SingletonMeta):
         ToolRegistry._definitions[tool_name] = definition
         logger.info(f"Successfully registered tool definition: '{tool_name}'")
 
+    def unregister_tool(self, name: str) -> bool:
+        """
+        Unregisters a tool definition by its name.
+
+        Args:
+            name: The unique name of the tool definition to unregister.
+
+        Returns:
+            True if the tool was found and unregistered, False otherwise.
+        """
+        if name in self._definitions:
+            del self._definitions[name]
+            logger.info(f"Successfully unregistered tool definition: '{name}'")
+            return True
+        else:
+            logger.warning(f"Attempted to unregister tool '{name}', but it was not found in the registry.")
+            return False
+
     def get_tool_definition(self, name: str) -> Optional[ToolDefinition]:
         """
         Retrieves the definition for a specific tool name.

autobyteus/tools/tool_category.py

@@ -0,0 +1,11 @@
+# file: autobyteus/autobyteus/tools/tool_category.py
+from enum import Enum
+
+class ToolCategory(str, Enum):
+    """Enumeration of tool categories to identify their origin."""
+    LOCAL = "local"
+    MCP = "mcp"
+    # BUILT_IN, USER_DEFINED etc. could be added later.
+
+    def __str__(self) -> str:
+        return self.value

autobyteus/tools/tool_meta.py

@@ -5,6 +5,7 @@ from typing import Dict, Any
 
 from autobyteus.tools.registry import default_tool_registry, ToolDefinition
 from autobyteus.tools.parameter_schema import ParameterSchema
+from autobyteus.tools.tool_category import ToolCategory
 
 logger = logging.getLogger(__name__)
 
@@ -60,7 +61,8 @@ class ToolMeta(ABCMeta):
                 tool_class=cls,
                 custom_factory=None,
                 argument_schema=argument_schema,
-                config_schema=instantiation_config_schema 
+                config_schema=instantiation_config_schema,
+                category=ToolCategory.LOCAL
             )
             default_tool_registry.register_tool(definition)
             

autobyteus/tools/tool_state.py

@@ -0,0 +1,20 @@
+# file: autobyteus/autobyteus/tools/tool_state.py
+"""
+Defines the ToolState class, an explicit container for a tool's internal state,
+providing a dictionary-like interface for backward compatibility.
+"""
+from collections import UserDict
+
+class ToolState(UserDict):
+    """
+    A specialized container for a tool's state.
+
+    This class inherits from collections.UserDict to provide a dictionary-like
+    interface, ensuring that existing tools can interact with the state attribute
+    (tool.tool_state) just as they would with a regular dictionary.
+
+    The primary purpose of this class is to make the concept of a tool's
+    state explicit in the framework's type system, improving code clarity
+    and developer experience.
+    """
+    pass

autobyteus/tools/usage/parsers/_json_extractor.py

@@ -0,0 +1,99 @@
+import re
+import logging
+from typing import List
+
+logger = logging.getLogger(__name__)
+
+def _find_json_blobs(text: str) -> List[str]:
+    """
+    Robustly finds and extracts all top-level JSON objects or arrays from a string,
+    maintaining their original order of appearance. It handles JSON within
+    markdown-style code blocks (```json ... ```) and inline JSON.
+    
+    Args:
+        text: The string to search for JSON in.
+        
+    Returns:
+        A list of strings, where each string is a valid-looking JSON blob,
+        ordered as they appeared in the input text.
+    """
+    found_blobs = []
+
+    # 1. Find all markdown blobs first and store them with their start positions.
+    markdown_matches = list(re.finditer(r"```(?:json)?\s*([\s\S]+?)\s*```", text))
+    for match in markdown_matches:
+        content = match.group(1).strip()
+        found_blobs.append((match.start(), content))
+    
+    # 2. Create a "masked" version of the text by replacing markdown blocks with spaces.
+    #    This prevents the inline scanner from finding JSON inside them, while preserving indices.
+    masked_text_list = list(text)
+    for match in markdown_matches:
+        for i in range(match.start(), match.end()):
+            masked_text_list[i] = ' '
+    masked_text = "".join(masked_text_list)
+
+    # 3. Scan the masked text for any other JSON using a single pass brace-counter.
+    idx = 0
+    while idx < len(masked_text):
+        start_idx = -1
+        
+        # Find the next opening brace or bracket
+        next_brace = masked_text.find('{', idx)
+        next_bracket = masked_text.find('[', idx)
+
+        if next_brace == -1 and next_bracket == -1:
+            break # No more JSON starts
+        
+        if next_brace != -1 and (next_bracket == -1 or next_brace < next_bracket):
+            start_idx = next_brace
+            start_char, end_char = '{', '}'
+        else:
+            start_idx = next_bracket
+            start_char, end_char = '[', ']'
+
+        brace_count = 1
+        in_string = False
+        is_escaped = False
+        end_idx = -1
+
+        for i in range(start_idx + 1, len(masked_text)):
+            char = masked_text[i]
+            
+            if in_string:
+                if is_escaped:
+                    is_escaped = False
+                elif char == '\\':
+                    is_escaped = True
+                elif char == '"':
+                    in_string = False
+            else:
+                if char == '"':
+                    in_string = True
+                    is_escaped = False
+                elif char == '{' or char == '[':
+                    brace_count += 1
+                elif char == '}' or char == ']':
+                    brace_count -= 1
+            
+            if brace_count == 0:
+                if (start_char == '{' and char == '}') or \
+                   (start_char == '[' and char == ']'):
+                    end_idx = i
+                    break
+        
+        if end_idx != -1:
+            # We found a blob in the masked text, so its indices are correct
+            # for the original text. Extract the blob from the original text.
+            blob = text[start_idx : end_idx + 1]
+            found_blobs.append((start_idx, blob))
+            idx = end_idx + 1
+        else:
+            # No matching end brace found, move on from the start character.
+            idx = start_idx + 1
+
+    # 4. Sort all found blobs by their start position to ensure correct order
+    found_blobs.sort(key=lambda item: item[0])
+    
+    # 5. Return only the content of the blobs
+    return [content for _, content in found_blobs]