alita-sdk 0.3.602__py3-none-any.whl → 0.3.609__py3-none-any.whl

alita_sdk/tools/bitbucket/api_wrapper.py

@@ -270,11 +270,20 @@ class BitbucketAPIWrapper(CodeIndexerToolkit):
                 >>>> NEW
             branch(str): branch name (by default: active_branch)
         Returns:
-            str: A success or failure message
+            str | ToolException: A success message or a ToolException on failure.
         """
         try:
-            result = self._bitbucket.update_file(file_path=file_path, update_query=update_query, branch=branch)
-            return result if isinstance(result, ToolException) else f"File has been updated: {file_path}."
+            # Use the shared edit_file logic from BaseCodeToolApiWrapper, operating on
+            # this wrapper instance, which provides _read_file and _write_file.
+            result = self.edit_file(
+                file_path=file_path,
+                branch=branch,
+                file_query=update_query,
+            )
+            return result
+        except ToolException as e:
+            # Pass through ToolExceptions as-is so callers can handle them uniformly.
+            return e
         except Exception as e:
             return ToolException(f"File was not updated due to error: {str(e)}")
 
@@ -415,37 +424,29 @@ class BitbucketAPIWrapper(CodeIndexerToolkit):
         file_path: str,
         content: str,
         branch: str = None,
-        commit_message: str = None
+        commit_message: str = None,
     ) -> str:
+        """Write content to a file (create or update) via the underlying Bitbucket client.
+
+        This delegates to the low-level BitbucketServerApi/BitbucketCloudApi `_write_file`
+        implementations, so all backend-specific commit behavior (server vs cloud) is
+        centralized there. Used by BaseCodeToolApiWrapper.edit_file.
         """
-        Write content to a file (create or update).
-        
-        Parameters:
-            file_path: Path to the file
-            content: New file content
-            branch: Branch name (uses active branch if None)
-            commit_message: Commit message (not used by Bitbucket API)
-            
-        Returns:
-            Success message
-        """
+        branch = branch or self._active_branch
         try:
-            branch = branch or self._active_branch
-            
-            # Check if file exists by attempting to read it
-            try:
-                self._read_file(file_path, branch)
-                # File exists, update it using OLD/NEW format
-                old_content = self._read_file(file_path, branch)
-                update_query = f"OLD <<<<\n{old_content}\n>>>> OLD\nNEW <<<<\n{content}\n>>>> NEW"
-                self._bitbucket.update_file(file_path=file_path, update_query=update_query, branch=branch)
-                return f"Updated file {file_path}"
-            except:
-                # File doesn't exist, create it
-                self._bitbucket.create_file(file_path=file_path, file_contents=content, branch=branch)
-                return f"Created file {file_path}"
+            # Delegate actual write/commit to the underlying API wrapper, which
+            # implements _write_file(file_path, content, branch, commit_message).
+            self._bitbucket._write_file(
+                file_path=file_path,
+                content=content,
+                branch=branch,
+                commit_message=commit_message or f"Update {file_path}",
+            )
+            return f"Update {file_path}"
+        except ToolException:
+            raise
         except Exception as e:
-            raise ToolException(f"Unable to write file {file_path}: {str(e)}")
+            raise ToolException(f"Unable to write file {file_path} on branch {branch}: {str(e)}")
 
     @extend_with_parent_available_tools
     @extend_with_file_operations

alita_sdk/tools/bitbucket/cloud_api_wrapper.py

@@ -142,32 +142,28 @@ class BitbucketServerApi(BitbucketApiAbstract):
             filename=file_path
         )
 
-    def update_file(self, file_path: str, update_query: str, branch: str) -> str:
-        file_content = self.get_file(file_path=file_path, branch=branch)
-        updated_file_content = file_content
-        for old, new in parse_old_new_markers(update_query):
-            if not old.strip():
-                continue
-            updated_file_content = updated_file_content.replace(old, new)
-
-        if file_content == updated_file_content:
-            raise ToolException(
-                "File content was not updated because old content was not found or empty. "
-                "It may be helpful to use the read_file action to get "
-                "the current file contents."
-            )
+    def _write_file(self, file_path: str, content: str, branch: str, commit_message: str) -> str:
+        """Write updated file content to Bitbucket Server.
 
+        it creates a new commit on the given branch that edits the existing file.
+        """
+        # Get the latest commit on the branch (used as source_commit_id)
         source_commit_generator = self.api_client.get_commits(project_key=self.project, repository_slug=self.repository,
                                                               hash_newest=branch, limit=1)
-        source_commit = next(source_commit_generator)
+        source_commit = next(source_commit_generator, None)
+        if not source_commit:
+            raise ToolException(
+                f"Unable to determine latest commit on branch '{branch}' for repository '{self.repository}'."
+            )
+
         return self.api_client.update_file(
             project_key=self.project,
             repository_slug=self.repository,
-            content=updated_file_content,
-            message=f"Update {file_path}",
+            content=content,
+            message=commit_message or f"Update {file_path}",
             branch=branch,
             filename=file_path,
-            source_commit_id=source_commit['id']
+            source_commit_id=source_commit['id'],
         )
 
     def get_pull_request_commits(self, pr_id: str) -> List[Dict[str, Any]]:
@@ -294,7 +290,37 @@ class BitbucketCloudApi(BitbucketApiAbstract):
         return None
 
     def get_file(self, file_path: str, branch: str) -> str:
-        return self.repository.get(path=f'src/{branch}/{file_path}')
+        """Fetch a file's content from Bitbucket Cloud and return it as text.
+
+        Uses the 'get' endpoint with advanced_mode to get a rich response object.
+        """
+        try:
+            file_response = self.repository.get(
+                path=f"src/{branch}/{file_path}",
+                advanced_mode=True,
+            )
+
+            # Prefer HTTP status when available
+            status = getattr(file_response, "status_code", None)
+            if status is not None and status != 200:
+                raise ToolException(
+                    f"Failed to retrieve text from file '{file_path}' from branch '{branch}': "
+                    f"HTTP {status}"
+                )
+
+            # Safely extract text content
+            file_text = getattr(file_response, "text", None)
+            if not isinstance(file_text, str) or not file_text:
+                raise ToolException(
+                    f"File '{file_path}' from branch '{branch}' is empty or could not be retrieved."
+                )
+
+            return file_text
+        except Exception as e:
+            # Network/transport or client-level failure
+            raise ToolException(
+                f"Failed to retrieve text from file '{file_path}' from branch '{branch}': {e}"
+            )
 
     def get_files_list(self, file_path: str, branch: str) -> list:
         files_list = []
@@ -315,22 +341,10 @@ class BitbucketCloudApi(BitbucketApiAbstract):
         return self.repository.post(path='src', data=form_data, files={},
                                     headers={'Content-Type': 'application/x-www-form-urlencoded'})
 
-    def update_file(self, file_path: str, update_query: str, branch: str) -> ToolException | str:
-
-        file_content = self.get_file(file_path=file_path, branch=branch)
-        updated_file_content = file_content
-        for old, new in parse_old_new_markers(file_query=update_query):
-            if not old.strip():
-                continue
-            updated_file_content = updated_file_content.replace(old, new)
-
-        if file_content == updated_file_content:
-            return ToolException(
-                "File content was not updated because old content was not found or empty. "
-                "It may be helpful to use the read_file action to get "
-                "the current file contents."
-            )
-        return self.create_file(file_path, updated_file_content, branch)
+    def _write_file(self, file_path: str, content: str, branch: str, commit_message: str) -> str:
+        """Write updated file content to Bitbucket Cloud.
+        """
+        return self.create_file(file_path=file_path, file_contents=content, branch=branch)
 
     def get_pull_request_commits(self, pr_id: str) -> List[Dict[str, Any]]:
         """

alita_sdk/tools/confluence/api_wrapper.py

@@ -620,11 +620,18 @@ class ConfluenceAPIWrapper(NonCodeIndexerToolkit):
     def _process_search(self, cql, skip_images: bool = False):
         start = 0
         pages_info = []
+        seen_ids: set = set()  # Track seen page IDs to avoid duplicates
         for _ in range((self.max_pages + self.limit - 1) // self.limit):
             pages = self.client.cql(cql, start=start, limit=self.limit).get("results", [])
             if not pages:
                 break
-            page_ids = [page['content']['id'] for page in pages]
+            # Deduplicate page IDs before processing
+            page_ids = []
+            for page in pages:
+                page_id = page['content']['id']
+                if page_id not in seen_ids:
+                    seen_ids.add(page_id)
+                    page_ids.append(page_id)
             for page in self.get_pages_by_id(page_ids, skip_images):
                 page_info = {
                     'content': page.page_content,

alita_sdk/tools/elitea_base.py

@@ -837,10 +837,7 @@ class BaseCodeToolApiWrapper(BaseVectorStoreToolApiWrapper):
             commit_message: Commit message (VCS toolkits only)
             
         Returns:
-            Success message or error
-            
-        Raises:
-            ToolException: If file is not text-editable or edit fails
+            Success message or raises ToolException on failure.
         """
         from .utils.text_operations import parse_old_new_markers, is_text_editable, try_apply_edit
         from langchain_core.callbacks import dispatch_custom_event
@@ -868,45 +865,35 @@ class BaseCodeToolApiWrapper(BaseVectorStoreToolApiWrapper):
                 raise current_content if isinstance(current_content, Exception) else ToolException(str(current_content))
         except Exception as e:
             raise ToolException(f"Failed to read file {file_path}: {e}")
-        
-        # Apply all edits (with tolerant fallback)
+
+        # Apply all edits (stop on first warning/error)
         updated_content = current_content
-        fallbacks_used = 0
         edits_applied = 0
         for old_text, new_text in edits:
             if not old_text.strip():
                 continue
             
-            new_updated, used_fallback = try_apply_edit(
+            new_updated, error_message = try_apply_edit(
                 content=updated_content,
                 old_text=old_text,
                 new_text=new_text,
                 file_path=file_path,
             )
 
-            if new_updated == updated_content:
-                # No change applied for this pair (exact nor fallback)
-                logger.warning(
-                    "Old content not found or could not be safely matched in %s. Snippet: %s...",
-                    file_path,
-                    old_text[:100].replace("\n", "\\n"),
-                )
-                continue
+            if error_message:
+                return error_message
 
             # A replacement was applied
             edits_applied += 1
-            if used_fallback:
-                fallbacks_used += 1
-
             updated_content = new_updated
         
         # Check if any changes were made
-        if current_content == updated_content or edits_applied == 0:
-            return (
-                f"No changes made to {file_path}. "
-                "Old content was not found or is empty. "
-                "Use read_file or search_file to verify current content."
-            )
+        if current_content == updated_content:
+            # At least one edit was applied, but the final content is identical.
+            # This usually means the sequence of OLD/NEW pairs is redundant or cancels out.
+            return (f"Edits for {file_path} were applied but the final content is identical to the original. "
+                    "The sequence of OLD/NEW pairs appears to be redundant or self-cancelling. "
+                    "Please simplify or review the update_query.")
         
         # Write updated content
         try:
@@ -1116,60 +1103,77 @@ def extend_with_file_operations(method):
     """
     Decorator to automatically add file operation tools to toolkits that implement
     _read_file and _write_file methods.
-    
+
     Adds:
     - read_file_chunk: Read specific line ranges
     - read_multiple_files: Batch read files
     - search_file: Search for patterns in files
     - edit_file: Edit files using OLD/NEW markers
+
+    Custom Schema Support:
+    Toolkits can provide custom schemas by implementing _get_file_operation_schemas() method
+    that returns a dict mapping tool names to Pydantic models. This allows toolkits like
+    ArtifactWrapper to use bucket_name instead of branch.
+
+    Example:
+        def _get_file_operation_schemas(self):
+            return {
+                "read_file_chunk": MyCustomReadFileChunkInput,
+                "read_multiple_files": MyCustomReadMultipleFilesInput,
+            }
     """
     def wrapper(self, *args, **kwargs):
         tools = method(self, *args, **kwargs)
-        
+
         # Only add file operations if toolkit has implemented the required methods
         # Check for both _read_file and _write_file methods
         has_file_ops = (hasattr(self, '_read_file') and callable(getattr(self, '_read_file')) and
                         hasattr(self, '_write_file') and callable(getattr(self, '_write_file')))
-        
+
         if has_file_ops:
             # Import schemas from elitea_base
             from . import elitea_base
-            
+
+            # Check for toolkit-specific custom schemas
+            custom_schemas = {}
+            if hasattr(self, '_get_file_operation_schemas') and callable(getattr(self, '_get_file_operation_schemas')):
+                custom_schemas = self._get_file_operation_schemas() or {}
+
             file_operation_tools = [
                 {
                     "name": "read_file_chunk",
                     "mode": "read_file_chunk",
                     "ref": self.read_file_chunk,
                     "description": self.read_file_chunk.__doc__,
-                    "args_schema": elitea_base.ReadFileChunkInput
+                    "args_schema": custom_schemas.get("read_file_chunk", elitea_base.ReadFileChunkInput)
                 },
                 {
                     "name": "read_multiple_files",
                     "mode": "read_multiple_files",
                     "ref": self.read_multiple_files,
                     "description": self.read_multiple_files.__doc__,
-                    "args_schema": elitea_base.ReadMultipleFilesInput
+                    "args_schema": custom_schemas.get("read_multiple_files", elitea_base.ReadMultipleFilesInput)
                 },
                 {
                     "name": "search_file",
                     "mode": "search_file",
                     "ref": self.search_file,
                     "description": self.search_file.__doc__,
-                    "args_schema": elitea_base.SearchFileInput
+                    "args_schema": custom_schemas.get("search_file", elitea_base.SearchFileInput)
                 },
                 {
                     "name": "edit_file",
                     "mode": "edit_file",
                     "ref": self.edit_file,
                     "description": self.edit_file.__doc__,
-                    "args_schema": elitea_base.EditFileInput
+                    "args_schema": custom_schemas.get("edit_file", elitea_base.EditFileInput)
                 },
             ]
-            
+
             tools.extend(file_operation_tools)
-        
+
         return tools
-    
+
     return wrapper
 
 

alita_sdk/tools/figma/api_wrapper.py

@@ -369,50 +369,94 @@ class FigmaApiWrapper(NonCodeIndexerToolkit):
             )
 
     def _base_loader(
-            self,
-            url: Optional[str] = None,
-            file_keys_include: Optional[List[str]] = None,
-            file_keys_exclude: Optional[List[str]] = None,
-            node_ids_include: Optional[List[str]] = None,
-            node_ids_exclude: Optional[List[str]] = None,
-            node_types_include: Optional[List[str]] = None,
-            node_types_exclude: Optional[List[str]] = None,
-            number_of_threads: Optional[int] = None,
-            **kwargs
+        self,
+        urls_or_file_keys: Optional[str] = None,
+        node_ids_include: Optional[List[str]] = None,
+        node_ids_exclude: Optional[List[str]] = None,
+        node_types_include: Optional[List[str]] = None,
+        node_types_exclude: Optional[List[str]] = None,
+        number_of_threads: Optional[int] = None,
+        **kwargs,
     ) -> Generator[Document, None, None]:
-        if url:
-            file_key, node_ids_from_url = self._parse_figma_url(url)
-            # Override include params based on URL
-            file_keys_include = [file_key]
-            if node_ids_from_url and not node_ids_include:
-                node_ids_include = node_ids_from_url
-        
-        # If both include and exclude are provided, use only include
-        if file_keys_include:
-            self._log_tool_event(f"Loading files: {file_keys_include}")
-            for file_key in file_keys_include:
-                self._log_tool_event(f"Loading file `{file_key}`")
-                file = self._client.get_file(file_key, geometry='depth=1') # fetch only top-level structure (only pages without inner components)
-                if not file:
-                    raise ToolException(f"Unexpected error while retrieving file {file_key}. Please try specifying the node-id of an inner page.")
-                # propagate per-call number_of_threads override via metadata so _process_document can respect it
-                metadata = {
-                    'id': file_key,
-                    'file_key': file_key,
-                    'name': file.name,
-                    'updated_on': file.last_modified,
-                    'figma_pages_include': node_ids_include or [],
-                    'figma_pages_exclude': node_ids_exclude or [],
-                    'figma_nodes_include': node_types_include or [],
-                    'figma_nodes_exclude': node_types_exclude or [],
-                }
-                if isinstance(number_of_threads, int) and 1 <= number_of_threads <= 5:
-                    metadata['number_of_threads_override'] = number_of_threads
-                yield Document(page_content=json.dumps(metadata), metadata=metadata)
-        elif file_keys_exclude or node_ids_exclude:
-            raise ValueError("Excludes without parent (file_keys_include) do not make sense.")
-        else:
-            raise ValueError("You must provide file_keys_include or a URL.")
+        """Base loader used by the indexer tool.
+
+        Args:
+            urls_or_file_keys: Comma-separated list of Figma file URLs or raw file keys. Each
+                entry can be:
+                  - a full Figma URL (https://www.figma.com/file/... or /design/...) optionally
+                    with a node-id query parameter, or
+                  - a bare file key string.
+                URL entries are parsed via _parse_figma_url; raw keys are used as-is.
+            node_ids_include: Optional list of top-level node IDs (pages) to include when an
+                entry does not specify node-id in the URL and is not otherwise constrained.
+            node_ids_exclude: Optional list of top-level node IDs (pages) to exclude when
+                node_ids_include is not provided.
+            node_types_include: Optional list of node types to include within each page.
+            node_types_exclude: Optional list of node types to exclude when node_types_include
+                is not provided.
+            number_of_threads: Optional override for number of worker threads to use when
+                processing images.
+        """
+        if not urls_or_file_keys:
+            raise ValueError("You must provide urls_or_file_keys with at least one URL or file key.")
+
+        # Parse the comma-separated entries into concrete (file_key, per_entry_node_ids_include)
+        entries = [item.strip() for item in urls_or_file_keys.split(',') if item.strip()]
+        if not entries:
+            raise ValueError("You must provide urls_or_file_keys with at least one non-empty value.")
+
+        # Validate number_of_threads override once and pass via metadata
+        metadata_threads_override: Optional[int] = None
+        if isinstance(number_of_threads, int) and 1 <= number_of_threads <= 5:
+            metadata_threads_override = number_of_threads
+
+        for entry in entries:
+            per_file_node_ids_include: Optional[List[str]] = None
+            file_key: Optional[str] = None
+
+            # Heuristic: treat as URL if it has a scheme and figma.com host
+            if entry.startswith("http://") or entry.startswith("https://"):
+                file_key, node_ids_from_url = self._parse_figma_url(entry)
+                per_file_node_ids_include = node_ids_from_url
+            else:
+                # Assume this is a raw file key
+                file_key = entry
+
+            if not file_key:
+                continue
+
+            # If URL-derived node IDs exist, they take precedence over global include list
+            effective_node_ids_include = per_file_node_ids_include or node_ids_include or []
+
+            self._log_tool_event(f"Loading file `{file_key}`")
+            try:
+                file = self._client.get_file(file_key, geometry='depth=1')
+            except ToolException as e:
+                # Enrich the error message with the file_key for easier troubleshooting
+                raise ToolException(
+                    f"Failed to retrieve Figma file '{file_key}'. Original error: {e}"
+                ) from e
+
+            if not file:
+                raise ToolException(
+                    f"Unexpected error while retrieving file {file_key}. Please try specifying the node-id of an inner page."
+                )
+
+            metadata = {
+                'id': file_key,
+                'file_key': file_key,
+                'name': file.name,
+                'updated_on': file.last_modified,
+                'figma_pages_include': effective_node_ids_include,
+                'figma_pages_exclude': node_ids_exclude or [],
+                'figma_nodes_include': node_types_include or [],
+                'figma_nodes_exclude': node_types_exclude or [],
+            }
+
+            if metadata_threads_override is not None:
+                metadata['number_of_threads_override'] = metadata_threads_override
+
+            yield Document(page_content=json.dumps(metadata), metadata=metadata)
 
     def has_image_representation(self, node):
         node_type = node.get('type', '').lower()
@@ -672,44 +716,58 @@ class FigmaApiWrapper(NonCodeIndexerToolkit):
                     )
 
     def _index_tool_params(self):
-         """Return the parameters for indexing data."""
-         return {
-             "url": (Optional[str], Field(
-                 description=(
-                     "Full Figma file or page URL to index. Must be in one of the following formats: "
-                     "'https://www.figma.com/file/<FILE_KEY>/...' or 'https://www.figma.com/design/<FILE_KEY>/...'. "
-                     "If present, the 'node-id' query parameter (e.g. '?node-id=<PAGE_ID>') will be used to limit "
-                     "indexing to that page or node. When this URL is provided, it overrides 'file_keys_include' ('node_ids_include')."
-                 ),
-                 default=None)),
-             'number_of_threads': (Optional[int], Field(
-                 description=(
-                     "Optional override for the number of worker threads used when indexing Figma images. "
-                     f"Valid values are from 1 to 5. Default is {DEFAULT_NUMBER_OF_THREADS}."
-                 ),
-                 default=DEFAULT_NUMBER_OF_THREADS,
-                 ge=1,
-                 le=5,
-             )),
-              'file_keys_include': (Optional[List[str]], Field(
-                  description="List of file keys to include in index if project_id is not provided: i.e. ['Fp24FuzPwH0L74ODSrCnQo', 'jmhAr6q78dJoMRqt48zisY']",
-                  default=None)),
-             'file_keys_exclude': (Optional[List[str]], Field(
-                 description="List of file keys to exclude from index. It is applied only if project_id is provided and file_keys_include is not provided: i.e. ['Fp24FuzPwH0L74ODSrCnQo', 'jmhAr6q78dJoMRqt48zisY']",
-                 default=None)),
-             'node_ids_include': (Optional[List[str]], Field(
-                 description="List of top-level nodes (pages) in file to include in index. It is node-id from figma url: i.e. ['123-56', '7651-9230'].",
-                 default=None)),
-             'node_ids_exclude': (Optional[List[str]], Field(
-                 description="List of top-level nodes (pages) in file to exclude from index. It is applied only if node_ids_include is not provided. It is node-id from figma url: i.e. ['Fp24FuzPwH0L74ODSrCnQo', 'jmhAr6q78dJoMRqt48zisY']",
-                 default=None)),
-             'node_types_include': (Optional[List[str]], Field(
-                 description="List type of nodes to include in index: i.e. ['FRAME', 'COMPONENT', 'RECTANGLE', 'COMPONENT_SET', 'INSTANCE', 'VECTOR', ...].",
-                 default=None)),
-             'node_types_exclude': (Optional[List[str]], Field(
-                 description="List type of nodes to exclude from index. It is applied only if node_types_include is not provided: i.e. ['FRAME', 'COMPONENT', 'RECTANGLE', 'COMPONENT_SET', 'INSTANCE', 'VECTOR', ...]",
-                 default=None)),
-         }
+        """Return the parameters for indexing data."""
+        return {
+            "urls_or_file_keys": (str, Field(
+                description=(
+                    "Comma-separated list of Figma file URLs or raw file keys to index. "
+                    "Each entry may be a full Figma URL (with optional node-id query) or a file key. "
+                    "Example: 'https://www.figma.com/file/<FILE_KEY>/...?node-id=<NODE_ID>,Fp24FuzPwH0L74ODSrCnQo'."
+                ))),
+            'number_of_threads': (Optional[int], Field(
+                description=(
+                    "Optional override for the number of worker threads used when indexing Figma images. "
+                    f"Valid values are from 1 to 5. Default is {DEFAULT_NUMBER_OF_THREADS}."
+                ),
+                default=DEFAULT_NUMBER_OF_THREADS,
+                ge=1,
+                le=5,
+            )),
+            'node_ids_include': (Optional[List[str]], Field(
+                description=(
+                    "List of top-level node IDs (pages) to include in the index. Values should match "
+                    "Figma node-id format like ['123-56', '7651-9230']. These include rules are applied "
+                    "for each entry in urls_or_file_keys when the URL does not specify node-id and for "
+                    "each raw file_key entry."
+                ),
+                default=None,
+            )),
+            'node_ids_exclude': (Optional[List[str]], Field(
+                description=(
+                    "List of top-level node IDs (pages) to exclude from the index when node_ids_include "
+                    "is not provided. Values should match Figma node-id format. These exclude rules are "
+                    "applied for each entry in urls_or_file_keys (URLs without node-id and raw fileKey "
+                    "entries)."
+                ),
+                default=None,
+            )),
+            'node_types_include': (Optional[List[str]], Field(
+                description=(
+                    "List of node types to include in the index, e.g. ['FRAME', 'COMPONENT', 'RECTANGLE', "
+                    "'COMPONENT_SET', 'INSTANCE', 'VECTOR', ...]. If provided, only these types are indexed "
+                    "for each page loaded from each urls_or_file_keys entry."
+                ),
+                default=None,
+            )),
+            'node_types_exclude': (Optional[List[str]], Field(
+                description=(
+                    "List of node types to exclude from the index when node_types_include is not provided. "
+                    "These exclude rules are applied to nodes within each page loaded from each "
+                    "urls_or_file_keys entry."
+                ),
+                default=None,
+            )),
+        }
 
     def _send_request(
         self,
@@ -972,8 +1030,7 @@ class FigmaApiWrapper(NonCodeIndexerToolkit):
 
         # Delegate URL and file_key handling to _base_loader
         base_docs = self._base_loader(
-            url=url,
-            file_keys_include=[file_key] if file_key else None,
+            urls_or_file_keys=url or file_key,
             node_ids_include=node_ids_include_list,
             node_ids_exclude=node_ids_exclude_list,
         )