alita-sdk 0.3.603__py3-none-any.whl → 0.3.611__py3-none-any.whl

alita_sdk/runtime/tools/function.py

@@ -1,3 +1,4 @@
+import base64
 import json
 import logging
 from copy import deepcopy
@@ -12,6 +13,7 @@ from langchain_core.utils.function_calling import convert_to_openai_tool
 from pydantic import ValidationError
 
 from ..langchain.utils import propagate_the_input_mapping
+from ..utils.serialization import safe_serialize
 
 logger = logging.getLogger(__name__)
 
@@ -40,15 +42,32 @@ class FunctionTool(BaseTool):
     alita_client: Optional[Any] = None
 
     def _prepare_pyodide_input(self, state: Union[str, dict, ToolCall]) -> str:
-        """Prepare input for PyodideSandboxTool by injecting state into the code block."""
-        # add state into the code block here since it might be changed during the execution of the code
+        """Prepare input for PyodideSandboxTool by injecting state into the code block.
+
+        Uses base64 encoding to avoid string escaping issues when passing JSON
+        through multiple layers of parsing (Python -> Deno -> Pyodide).
+        """
         state_copy = replace_escaped_newlines(deepcopy(state))
 
-        del state_copy['messages']  # remove messages to avoid issues with pickling without langchain-core
-        # inject state into the code block as alita_state variable
-        state_json = json.dumps(state_copy, ensure_ascii=False)
-        pyodide_predata = f'#state dict\nimport json\nalita_state = json.loads({json.dumps(state_json)})\n'
+        # remove messages to avoid issues with pickling without langchain-core
+        if 'messages' in state_copy:
+            del state_copy['messages']
+
+        # Use safe_serialize to handle Pydantic models, datetime, and other non-JSON types
+        state_json = safe_serialize(state_copy)
 
+        # Use base64 encoding to avoid all string escaping issues
+        # This is more robust than repr() when the code passes through multiple parsers
+        state_json_b64 = base64.b64encode(state_json.encode('utf-8')).decode('ascii')
+
+        # Generate code that decodes base64 and parses JSON inside Pyodide
+        pyodide_predata = f'''#state dict
+import json
+import base64
+_state_json_b64 = "{state_json_b64}"
+_state_json = base64.b64decode(_state_json_b64).decode('utf-8')
+alita_state = json.loads(_state_json)
+'''
         return pyodide_predata
 
     def _handle_pyodide_output(self, tool_result: Any) -> dict:

alita_sdk/runtime/tools/llm.py

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 from traceback import format_exc
-from typing import Any, Optional, List, Union, Literal
+from typing import Any, Optional, List, Union, Literal, Dict
 
 from langchain_core.messages import HumanMessage, SystemMessage, AIMessage
 from langchain_core.runnables import RunnableConfig
@@ -67,7 +67,7 @@ class LLMNode(BaseTool):
     client: Any = Field(default=None, description='LLM client instance')
     return_type: str = Field(default="str", description='Return type')
     response_key: str = Field(default="messages", description='Response key')
-    structured_output_dict: Optional[dict[str, str]] = Field(default=None, description='Structured output dictionary')
+    structured_output_dict: Optional[Dict[str, Any]] = Field(default=None, description='Structured output dictionary')
     output_variables: Optional[List[str]] = Field(default=None, description='Output variables')
     input_mapping: Optional[dict[str, dict]] = Field(default=None, description='Input mapping')
     input_variables: Optional[List[str]] = Field(default=None, description='Input variables')
@@ -82,7 +82,7 @@ class LLMNode(BaseTool):
         Prepare structured output parameters from structured_output_dict.
 
         Expected self.structured_output_dict formats:
-          - {"field": "str"} / {"field": "list"} / {"field": "list[str]"} / {"field": "any"} ...
+          - {"field": "str"} / {"field": "list"} / {"field": "list[dict]"} / {"field": "any"} ...
           - OR {"field": {"type": "...", "description": "...", "default": ...}}  (optional)
 
         Returns:
@@ -93,19 +93,20 @@ class LLMNode(BaseTool):
         for key, value in (self.structured_output_dict or {}).items():
             # Allow either a plain type string or a dict with details
             if isinstance(value, dict):
-                type_str = (value.get("type") or "any")
+                type_str = str(value.get("type") or "any")
                 desc = value.get("description", "") or ""
                 entry: dict = {"type": type_str, "description": desc}
                 if "default" in value:
                     entry["default"] = value["default"]
             else:
-                type_str = (value or "any") if isinstance(value, str) else "any"
-                entry = {"type": type_str, "description": ""}
+                # Ensure we always have a string type
+                if isinstance(value, str):
+                    type_str = value
+                else:
+                    # If it's already a type object, convert to string representation
+                    type_str = getattr(value, '__name__', 'any')
 
-            # Normalize: only convert the *exact* "list" into "list[str]"
-            # (avoid the old bug where "if 'list' in value" also hits "blacklist", etc.)
-            if isinstance(entry.get("type"), str) and entry["type"].strip().lower() == "list":
-                entry["type"] = "list[str]"
+                entry = {"type": type_str, "description": ""}
 
             struct_params[key] = entry
 
@@ -1146,5 +1147,5 @@ class LLMNode(BaseTool):
 
         return new_messages, current_completion
 
-    def __get_struct_output_model(self, llm_client, pydantic_model, method: Literal["function_calling", "json_mode", "json_schema"] = "json_schema"):
+    def __get_struct_output_model(self, llm_client, pydantic_model, method: Literal["function_calling", "json_mode", "json_schema"] = "function_calling"):
         return llm_client.with_structured_output(pydantic_model, method=method)

alita_sdk/runtime/utils/serialization.py

@@ -0,0 +1,155 @@
+"""
+Serialization utilities for safe JSON encoding of complex objects.
+
+Handles Pydantic models, LangChain messages, datetime objects, and other
+non-standard types that may appear in state variables.
+"""
+import json
+import logging
+from datetime import datetime, date
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def _convert_to_serializable(obj: Any, _seen: set = None) -> Any:
+    """
+    Recursively convert an object to JSON-serializable primitives.
+
+    Handles nested dicts and lists that may contain non-serializable objects.
+    Uses a seen set to prevent infinite recursion with circular references.
+
+    Args:
+        obj: Any object to convert
+        _seen: Internal set to track seen object ids (for circular reference detection)
+
+    Returns:
+        JSON-serializable representation of the object
+    """
+    # Initialize seen set for circular reference detection
+    if _seen is None:
+        _seen = set()
+
+    # Check for circular references (only for mutable objects)
+    obj_id = id(obj)
+    if isinstance(obj, (dict, list, set)) and obj_id in _seen:
+        return f"<circular reference: {type(obj).__name__}>"
+
+    # Primitives - return as-is
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+
+    # Add to seen set for mutable containers
+    if isinstance(obj, (dict, list, set)):
+        _seen = _seen | {obj_id}  # Create new set to avoid mutation issues
+
+    # Dict - recursively process all values
+    if isinstance(obj, dict):
+        return {
+            _convert_to_serializable(k, _seen): _convert_to_serializable(v, _seen)
+            for k, v in obj.items()
+        }
+
+    # List/tuple - recursively process all items
+    if isinstance(obj, (list, tuple)):
+        return [_convert_to_serializable(item, _seen) for item in obj]
+
+    # Set - convert to list and process
+    if isinstance(obj, set):
+        return [_convert_to_serializable(item, _seen) for item in obj]
+
+    # Bytes - decode to string
+    if isinstance(obj, bytes):
+        try:
+            return obj.decode('utf-8')
+        except UnicodeDecodeError:
+            return obj.decode('utf-8', errors='replace')
+
+    # Datetime objects
+    if isinstance(obj, datetime):
+        return obj.isoformat()
+    if isinstance(obj, date):
+        return obj.isoformat()
+
+    # Pydantic BaseModel (v2) - check for model_dump method
+    if hasattr(obj, 'model_dump') and callable(getattr(obj, 'model_dump')):
+        try:
+            return _convert_to_serializable(obj.model_dump(), _seen)
+        except Exception as e:
+            logger.debug(f"Failed to call model_dump on {type(obj).__name__}: {e}")
+
+    # Pydantic BaseModel (v1) - check for dict method
+    if hasattr(obj, 'dict') and callable(getattr(obj, 'dict')) and hasattr(obj, '__fields__'):
+        try:
+            return _convert_to_serializable(obj.dict(), _seen)
+        except Exception as e:
+            logger.debug(f"Failed to call dict on {type(obj).__name__}: {e}")
+
+    # LangChain BaseMessage - extract key fields
+    if hasattr(obj, 'type') and hasattr(obj, 'content'):
+        try:
+            result = {
+                "type": obj.type,
+                "content": _convert_to_serializable(obj.content, _seen),
+            }
+            if hasattr(obj, 'additional_kwargs') and obj.additional_kwargs:
+                result["additional_kwargs"] = _convert_to_serializable(obj.additional_kwargs, _seen)
+            if hasattr(obj, 'name') and obj.name:
+                result["name"] = obj.name
+            return result
+        except Exception as e:
+            logger.debug(f"Failed to extract message fields from {type(obj).__name__}: {e}")
+
+    # Objects with __dict__ attribute (custom classes)
+    if hasattr(obj, '__dict__'):
+        try:
+            return _convert_to_serializable(obj.__dict__, _seen)
+        except Exception as e:
+            logger.debug(f"Failed to serialize __dict__ of {type(obj).__name__}: {e}")
+
+    # UUID objects
+    if hasattr(obj, 'hex') and hasattr(obj, 'int'):
+        return str(obj)
+
+    # Enum objects
+    if hasattr(obj, 'value') and hasattr(obj, 'name') and hasattr(obj.__class__, '__members__'):
+        return obj.value
+
+    # Last resort - convert to string
+    try:
+        return str(obj)
+    except Exception:
+        return f"<non-serializable: {type(obj).__name__}>"
+
+
+def safe_serialize(obj: Any, **kwargs) -> str:
+    """
+    Safely serialize any object to a JSON string.
+
+    Pre-processes the entire object tree to convert non-serializable
+    objects before passing to json.dumps. This ensures nested dicts
+    and lists with non-standard objects are handled correctly.
+
+    Args:
+        obj: Any object to serialize
+        **kwargs: Additional arguments passed to json.dumps
+            (e.g., indent, sort_keys)
+
+    Returns:
+        JSON string representation of the object
+
+    Example:
+        >>> from pydantic import BaseModel
+        >>> class User(BaseModel):
+        ...     name: str
+        >>> state = {"user": User(name="Alice"), "count": 5}
+        >>> safe_serialize(state)
+        '{"user": {"name": "Alice"}, "count": 5}'
+    """
+    # Pre-process the entire object tree
+    serializable = _convert_to_serializable(obj)
+
+    # Set defaults
+    kwargs.setdefault('ensure_ascii', False)
+
+    return json.dumps(serializable, **kwargs)

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