alita-sdk 0.3.462__py3-none-any.whl → 0.3.627__py3-none-any.whl

alita_sdk/tools/utils/text_operations.py

@@ -0,0 +1,410 @@
+"""
+Shared text operations utilities for file manipulation across toolkits.
+
+Provides common functionality for:
+- Parsing OLD/NEW marker-based edits
+- Text file validation
+- Line-based slicing and partial reads
+- Content searching with context
+"""
+import re
+import logging
+from typing import List, Tuple, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Text file extensions that support editing
+TEXT_EDITABLE_EXTENSIONS = {
+    '.md', '.txt', '.csv', '.json', '.xml', '.html', 
+    '.yaml', '.yml', '.ini', '.conf', '.log', '.sh',
+    '.py', '.js', '.ts', '.jsx', '.tsx', '.java', '.go',
+    '.rb', '.php', '.c', '.cpp', '.h', '.hpp', '.cs',
+    '.sql', '.r', '.m', '.swift', '.kt', '.rs', '.scala'
+}
+
+
+def parse_old_new_markers(file_query: str) -> List[Tuple[str, str]]:
+    """
+    Parse OLD/NEW marker-based edit instructions.
+    
+    Extracts the first pair of old and new content from a file query using markers:
+    - OLD <<<< ... >>>> OLD
+    - NEW <<<< ... >>>> NEW
+    
+    Args:
+        file_query: String containing marked old and new content sections
+        
+    Returns:
+        List with at most one tuple (old_content, new_content) for the first edit pair.
+        Returns empty list if no valid OLD/NEW pair is found.
+        
+    Example:
+        >>> query = '''
+        ... OLD <<<<
+        ... Hello World
+        ... >>>> OLD
+        ... NEW <<<<
+        ... Hello Mars
+        ... >>>> NEW
+        ... '''
+        >>> parse_old_new_markers(query)
+        [('Hello World', 'Hello Mars')]
+    """
+    # Split the file content by lines
+    code_lines = file_query.split("\n")
+
+    # Initialize variables to track section state
+    in_old_section = False
+    in_new_section = False
+    old_content = None
+    new_content = None
+
+    # Temporary storage for the current section's content
+    current_section_content = []
+
+    # Iterate through each line in the file content
+    for line in code_lines:
+        # Check for OLD section start
+        if "OLD <<<" in line:
+            in_old_section = True
+            current_section_content = []  # Reset current section content
+            continue  # Skip the line with the marker
+
+        # Check for OLD section end
+        if ">>>> OLD" in line:
+            in_old_section = False
+            old_content = "\n".join(current_section_content).strip()
+            current_section_content = []  # Reset current section content
+            continue  # Skip the line with the marker
+
+        # Check for NEW section start
+        if "NEW <<<" in line:
+            in_new_section = True
+            current_section_content = []  # Reset current section content
+            continue  # Skip the line with the marker
+
+        # Check for NEW section end
+        if ">>>> NEW" in line:
+            in_new_section = False
+            new_content = "\n".join(current_section_content).strip()
+            # Return immediately after finding the first complete pair
+            if old_content is not None and new_content is not None:
+                return [(old_content, new_content)]
+            current_section_content = []  # Reset current section content
+            continue  # Skip the line with the marker
+
+        # If currently in an OLD or NEW section, add the line to the current section content
+        if in_old_section or in_new_section:
+            current_section_content.append(line)
+
+    # Return empty list if no complete pair found
+    return []
+
+
+def is_text_editable(filename: str) -> bool:
+    """
+    Check if a file is editable as text based on its extension.
+    
+    Args:
+        filename: Name or path of the file to check
+        
+    Returns:
+        True if file extension is in the text-editable whitelist
+        
+    Example:
+        >>> is_text_editable("config.json")
+        True
+        >>> is_text_editable("image.png")
+        False
+    """
+    from pathlib import Path
+    ext = Path(filename).suffix.lower()
+    return ext in TEXT_EDITABLE_EXTENSIONS
+
+
+def apply_line_slice(
+    content: str, 
+    offset: Optional[int] = None,
+    limit: Optional[int] = None,
+    head: Optional[int] = None,
+    tail: Optional[int] = None
+) -> str:
+    """
+    Apply line-based slicing to text content.
+    
+    Supports multiple modes:
+    - offset + limit: Read from line `offset` for `limit` lines (1-indexed)
+    - head: Read only first N lines
+    - tail: Read only last N lines
+    - No params: Return full content
+    
+    Args:
+        content: Text content to slice
+        offset: Starting line number (1-indexed, inclusive)
+        limit: Number of lines to read from offset
+        head: Return only first N lines
+        tail: Return only last N lines
+        
+    Returns:
+        Sliced content as string
+        
+    Example:
+        >>> text = "line1\\nline2\\nline3\\nline4\\nline5"
+        >>> apply_line_slice(text, offset=2, limit=2)
+        'line2\\nline3'
+        >>> apply_line_slice(text, head=2)
+        'line1\\nline2'
+        >>> apply_line_slice(text, tail=2)
+        'line4\\nline5'
+    """
+    if not content:
+        return content
+        
+    lines = content.splitlines(keepends=True)
+    
+    # Head mode: first N lines
+    if head is not None:
+        return ''.join(lines[:head])
+    
+    # Tail mode: last N lines
+    if tail is not None:
+        return ''.join(lines[-tail:] if tail > 0 else lines)
+    
+    # Offset + limit mode: slice from offset for limit lines
+    if offset is not None:
+        start_idx = max(0, offset - 1)  # Convert 1-indexed to 0-indexed
+        if limit is not None:
+            end_idx = start_idx + limit
+            return ''.join(lines[start_idx:end_idx])
+        else:
+            return ''.join(lines[start_idx:])
+    
+    # No slicing parameters: return full content
+    return content
+
+
+def search_in_content(
+    content: str,
+    pattern: str,
+    is_regex: bool = True,
+    context_lines: int = 2
+) -> List[Dict[str, any]]:
+    """
+    Search for pattern in content with context lines.
+    
+    Args:
+        content: Text content to search
+        pattern: Search pattern (regex if is_regex=True, else literal string)
+        is_regex: Whether to treat pattern as regex (default True)
+        context_lines: Number of lines before/after match to include (default 2)
+        
+    Returns:
+        List of match dictionaries with keys:
+            - line_number: 1-indexed line number of match
+            - line_content: The matching line
+            - match_text: The actual matched text
+            - context_before: List of lines before match
+            - context_after: List of lines after match
+            
+    Example:
+        >>> text = "line1\\nHello World\\nline3"
+        >>> matches = search_in_content(text, "Hello", is_regex=False)
+        >>> matches[0]['line_number']
+        2
+        >>> matches[0]['match_text']
+        'Hello'
+    """
+    if not content:
+        return []
+    
+    lines = content.splitlines()
+    matches = []
+    
+    # Compile regex pattern or escape for literal search
+    if is_regex:
+        try:
+            regex = re.compile(pattern, re.IGNORECASE)
+        except re.error as e:
+            logger.warning(f"Invalid regex pattern '{pattern}': {e}")
+            return []
+    else:
+        regex = re.compile(re.escape(pattern), re.IGNORECASE)
+    
+    # Search each line
+    for line_idx, line in enumerate(lines):
+        match = regex.search(line)
+        if match:
+            line_number = line_idx + 1  # Convert to 1-indexed
+            
+            # Get context lines
+            context_start = max(0, line_idx - context_lines)
+            context_end = min(len(lines), line_idx + context_lines + 1)
+            
+            context_before = lines[context_start:line_idx]
+            context_after = lines[line_idx + 1:context_end]
+            
+            matches.append({
+                'line_number': line_number,
+                'line_content': line,
+                'match_text': match.group(0),
+                'context_before': context_before,
+                'context_after': context_after,
+            })
+    
+    return matches
+
+
+def _normalize_for_match(text: str) -> str:
+    """Normalize text for tolerant OLD/NEW matching.
+
+    - Split into lines
+    - Replace common Unicode spaces with regular spaces
+    - Strip leading/trailing whitespace per line
+    - Collapse internal whitespace runs to a single space
+    - Join with '\n'
+    """
+    lines = text.splitlines()
+    norm_lines = []
+    for line in lines:
+        # Normalize common Unicode spaces to regular space
+        line = line.replace("\u00A0", " ").replace("\u2009", " ")
+        # Strip outer whitespace
+        line = line.strip()
+        # Collapse internal whitespace
+        line = re.sub(r"\s+", " ", line)
+        norm_lines.append(line)
+    return "\n".join(norm_lines)
+
+
+def try_apply_edit(
+    content: str,
+    old_text: str,
+    new_text: str,
+    file_path: Optional[str] = None,
+) -> Tuple[str, Optional[str]]:
+    """Apply a single OLD/NEW edit with a tolerant fallback.
+
+    This helper is used by edit_file to apply one (old_text, new_text) pair:
+    
+    1. First tries exact substring replacement (old_text in content).
+    2. If that fails, performs a tolerant, line-based match:
+       - Builds a logical OLD sequence without empty/whitespace-only lines
+       - Scans content while skipping empty/whitespace-only lines
+       - Compares using `_normalize_for_match` so minor spacing differences
+         don't break the match
+       - If exactly one such region is found, replaces that region with new_text
+       - If zero or multiple regions are found, no change is applied
+    
+    Args:
+        content: Current file content
+        old_text: OLD block extracted from markers
+        new_text: NEW block extracted from markers
+        file_path: Optional path for logging context
+    
+    Returns:
+        (updated_content, warning_message)
+        - updated_content: resulting content (may be unchanged)
+        - warning_message: human-readable warning if no edit was applied
+          or if the operation was ambiguous; None if an edit was
+          successfully and unambiguously applied.
+    """
+    # Stage 1: exact match
+    if old_text:
+        occurrences = content.count(old_text)
+        if occurrences == 1:
+            return content.replace(old_text, new_text, 1), None
+        if occurrences > 1:
+            msg = (
+                "Exact OLD block appears %d times in %s; no replacement applied to avoid ambiguity. "
+                "OLD value: %r" % (
+                    occurrences,
+                    file_path or "<unknown>",
+                    old_text,
+                )
+            )
+            logger.warning(msg)
+            return content, msg
+
+    # Stage 2: tolerant match
+    if not old_text or not old_text.strip() or not content:
+        msg = None
+        if not old_text or not old_text.strip():
+            msg = (
+                "OLD block is empty or whitespace-only; no replacement applied. "
+                "OLD value: %r" % (old_text,)
+            )
+        elif not content:
+            msg = "Content is empty; no replacement applied."
+        if msg:
+            logger.warning(msg)
+        return content, msg
+
+    # Logical OLD: drop empty/whitespace-only lines
+    old_lines_raw = old_text.splitlines()
+    old_lines = [l for l in old_lines_raw if l.strip()]
+    if not old_lines:
+        msg = (
+            "OLD block contains only empty/whitespace lines; no replacement applied. "
+            "OLD value: %r" % (old_text,)
+        )
+        logger.warning(msg)
+        return content, msg
+
+    # Precompute normalized OLD (joined by '\n')
+    norm_old = _normalize_for_match("\n".join(old_lines))
+
+    content_lines = content.splitlines(keepends=True)
+    total = len(content_lines)
+    candidates: list[tuple[int, int, str]] = []  # (start_idx, end_idx, block)
+
+    # Scan content for regions whose non-empty, normalized lines match norm_old
+    for start in range(total):
+        idx = start
+        collected_non_empty: list[str] = []
+        window_lines: list[str] = []
+
+        while idx < total and len(collected_non_empty) < len(old_lines):
+            line = content_lines[idx]
+            window_lines.append(line)
+            if line.strip():
+                collected_non_empty.append(line)
+            idx += 1
+
+        if len(collected_non_empty) < len(old_lines):
+            # Not enough non-empty lines from this start; no more windows possible
+            break
+
+        # Compare normalized non-empty content lines to normalized OLD
+        candidate_norm = _normalize_for_match("".join(collected_non_empty))
+        if candidate_norm == norm_old:
+            block = "".join(window_lines)
+            candidates.append((start, idx, block))
+
+    if not candidates:
+        msg = (
+            "Normalized OLD block not found in %s. OLD value: %r"
+            % (file_path or "<unknown>", old_text)
+        )
+        logger.warning(msg)
+        return content, msg
+
+    if len(candidates) > 1:
+        msg = (
+            "Multiple candidate regions for OLD block in %s; "
+            "no change applied to avoid ambiguity. OLD value: %r"
+            % (file_path or "<unknown>", old_text)
+        )
+        logger.warning(msg)
+        return content, msg
+
+    start_idx, end_idx, candidate_block = candidates[0]
+    updated = content.replace(candidate_block, new_text, 1)
+
+    logger.info(
+        "Applied tolerant OLD/NEW replacement in %s around lines %d-%d",
+        file_path or "<unknown>",
+        start_idx + 1,
+        start_idx + len(old_lines),
+    )
+
+    return updated, None

alita_sdk/tools/utils/tool_prompts.py

@@ -0,0 +1,79 @@
+"""
+Shared tool prompt constants for file operations across toolkits.
+
+These constants provide consistent descriptions for update_file and edit_file tools.
+"""
+
+# Base description for OLD/NEW marker format - used by all file editing operations
+UPDATE_FILE_MARKERS_DESCRIPTION = """
+**Marker format:**
+- OLD block: starts with `OLD <<<<` and ends with `>>>> OLD`
+- NEW block: starts with `NEW <<<<` and ends with `>>>> NEW`
+- Content must be on separate lines between opening and closing markers
+- Leading/trailing whitespace in content is stripped
+- Only the first OLD/NEW pair is processed
+
+**Examples:**
+
+Example 1 - Replace single line:
+```
+OLD <<<<
+old contents
+>>>> OLD
+NEW <<<<
+new contents
+>>>> NEW
+```
+
+Example 2 - Add new lines:
+```
+OLD <<<<
+existing line
+>>>> OLD
+NEW <<<<
+existing line
+added line
+>>>> NEW
+```
+
+Example 3 - Replace multiple lines:
+```
+OLD <<<<
+old line 1
+old line 2
+>>>> OLD
+NEW <<<<
+new line 1
+new line 2
+new line 3
+>>>> NEW
+```"""
+
+# Description for update_file when file_path is a separate parameter
+UPDATE_FILE_PROMPT_NO_PATH = f"""Updates a file using OLD/NEW markers.
+{UPDATE_FILE_MARKERS_DESCRIPTION}"""
+
+# Description for update_file when file_path is in the first line of file_query
+UPDATE_FILE_PROMPT_WITH_PATH = f"""Updates a file in repository.
+
+**Input format:**
+First non-empty line must be the file path (must not start with a slash), followed by OLD/NEW markers.
+
+Example:
+```
+path/to/file.txt
+OLD <<<<
+old content
+>>>> OLD
+NEW <<<<
+new content
+>>>> NEW
+```
+{UPDATE_FILE_MARKERS_DESCRIPTION}"""
+
+# Common description for edit_file/update_file operations
+EDIT_FILE_DESCRIPTION = """Edit file by path using OLD/NEW markers for precise replacements.
+        
+Only works with text files (markdown, txt, csv, json, xml, html, yaml, code files).
+"""
+

alita_sdk/tools/vector_adapters/VectorStoreAdapter.py

@@ -31,8 +31,8 @@ class VectorStoreAdapter(ABC):
         pass
 
     @abstractmethod
-    def clean_collection(self, vectorstore_wrapper, index_name: str = ''):
-        """Clean the vectorstore collection by deleting all indexed data."""
+    def clean_collection(self, vectorstore_wrapper, index_name: str = '', including_index_meta: bool = False):
+        """Clean the vectorstore collection by deleting all indexed data. If including_index_meta is True, skip the index_meta records."""
         pass
 
     @abstractmethod
@@ -132,18 +132,22 @@ class PGVectorAdapter(VectorStoreAdapter):
             logger.error(f"Failed to get indexed IDs from PGVector: {str(e)}")
             return []
 
-    def clean_collection(self, vectorstore_wrapper, index_name: str = ''):
-        """Clean the vectorstore collection by deleting all indexed data."""
-        # This logic deletes all data from the vectorstore collection without removal of collection.
-        # Collection itself remains available for future indexing.
+    def clean_collection(self, vectorstore_wrapper, index_name: str = '', including_index_meta: bool = False):
+        """Clean the vectorstore collection by deleting all indexed data. If including_index_meta is True, skip the index_meta records."""
         from sqlalchemy.orm import Session
-        from sqlalchemy import func
-
+        from sqlalchemy import func, or_
         store = vectorstore_wrapper.vectorstore
         with Session(store.session_maker.bind) as session:
-            session.query(store.EmbeddingStore).filter(
-                func.jsonb_extract_path_text(store.EmbeddingStore.cmetadata, 'collection') == index_name
-            ).delete(synchronize_session=False)
+            if including_index_meta:
+                session.query(store.EmbeddingStore).filter(
+                    func.jsonb_extract_path_text(store.EmbeddingStore.cmetadata, 'collection') == index_name
+                ).delete(synchronize_session=False)
+            else:
+                session.query(store.EmbeddingStore).filter(
+                    func.jsonb_extract_path_text(store.EmbeddingStore.cmetadata, 'collection') == index_name,
+                    or_(func.jsonb_extract_path_text(store.EmbeddingStore.cmetadata, 'type').is_(None),
+                        func.jsonb_extract_path_text(store.EmbeddingStore.cmetadata, 'type') != IndexerKeywords.INDEX_META_TYPE.value)
+                ).delete(synchronize_session=False)
             session.commit()
 
     def is_vectorstore_type(self, vectorstore) -> bool:
@@ -334,8 +338,8 @@ class ChromaAdapter(VectorStoreAdapter):
             logger.error(f"Failed to get indexed IDs from Chroma: {str(e)}")
             return []
 
-    def clean_collection(self, vectorstore_wrapper, index_name: str = ''):
-        """Clean the vectorstore collection by deleting all indexed data."""
+    def clean_collection(self, vectorstore_wrapper, index_name: str = '', including_index_meta: bool = False):
+        """Clean the vectorstore collection by deleting all indexed data. including_index_meta is ignored."""
         vectorstore_wrapper.vectorstore.delete(ids=self.get_indexed_ids(vectorstore_wrapper, index_name))
 
     def get_indexed_data(self, vectorstore_wrapper):

alita_sdk/tools/xray/__init__.py

@@ -8,9 +8,10 @@ from pydantic import create_model, BaseModel, Field
 from .api_wrapper import XrayApiWrapper
 from ..base.tool import BaseAction
 from ..elitea_base import filter_missconfigured_index_tools
-from ..utils import clean_string, get_max_toolkit_length, TOOLKIT_SPLITTER
+from ..utils import clean_string, get_max_toolkit_length
 from ...configurations.pgvector import PgVectorConfiguration
 from ...configurations.xray import XrayConfiguration
+from ...runtime.utils.constants import TOOLKIT_NAME_META, TOOL_NAME_META, TOOLKIT_TYPE_META
 
 name = "xray_cloud"
 
@@ -34,15 +35,13 @@ def get_tools(tool):
 
 class XrayToolkit(BaseToolkit):
     tools: List[BaseTool] = []
-    toolkit_max_length: int = 0
 
     @staticmethod
     def toolkit_config_schema() -> BaseModel:
         selected_tools = {x['name']: x['args_schema'].schema() for x in XrayApiWrapper.model_construct().get_available_tools()}
-        XrayToolkit.toolkit_max_length = get_max_toolkit_length(selected_tools)
         return create_model(
             name,
-            limit=(Optional[int], Field(description="Limit", default=100)),
+            limit=(Optional[int], Field(description="Limit", default=100, gt=0)),
             xray_configuration=(XrayConfiguration, Field(description="Xray Configuration", json_schema_extra={'configuration_types': ['xray']})),
             pgvector_configuration=(Optional[PgVectorConfiguration], Field(default=None,
                                                                            description="PgVector Configuration",
@@ -56,7 +55,6 @@ class XrayToolkit(BaseToolkit):
                             {
                                 'metadata': {
                                     "label": "XRAY cloud", "icon_url": "xray.svg",
-                                    "max_length": XrayToolkit.toolkit_max_length,
                                     "categories": ["test management"],
                                     "extra_categories": ["test automation", "test case management", "test planning"]
                                 }
@@ -76,18 +74,23 @@ class XrayToolkit(BaseToolkit):
             **(kwargs.get('pgvector_configuration') or {}),
         }
         xray_api_wrapper = XrayApiWrapper(**wrapper_payload)
-        prefix = clean_string(toolkit_name, cls.toolkit_max_length) + TOOLKIT_SPLITTER if toolkit_name else ''
         available_tools = xray_api_wrapper.get_available_tools()
         tools = []
         for tool in available_tools:
             if selected_tools:
                 if tool["name"] not in selected_tools:
                     continue
+            description = tool["description"]
+            if toolkit_name:
+                description = f"Toolkit: {toolkit_name}\n{description}"
+            description = description + "\nXray instance: " + xray_api_wrapper.base_url
+            description = description[:1000]
             tools.append(BaseAction(
                 api_wrapper=xray_api_wrapper,
-                name=prefix + tool["name"],
-                description=tool["description"] + "\nXray instance: " + xray_api_wrapper.base_url,
-                args_schema=tool["args_schema"]
+                name=tool["name"],
+                description=description,
+                args_schema=tool["args_schema"],
+                metadata={TOOLKIT_NAME_META: toolkit_name, TOOLKIT_TYPE_META: name, TOOL_NAME_META: tool["name"]} if toolkit_name else {TOOL_NAME_META: tool["name"]}
             ))
         return cls(tools=tools)
 

alita_sdk/tools/yagmail/__init__.py

@@ -6,6 +6,7 @@ from pydantic import create_model, BaseModel, Field, SecretStr
 
 from .yagmail_wrapper import YagmailWrapper, SMTP_SERVER
 from ..base.tool import BaseAction
+from ...runtime.utils.constants import TOOLKIT_NAME_META, TOOL_NAME_META, TOOLKIT_TYPE_META
 
 name = "yagmail"
 
@@ -34,7 +35,7 @@ class AlitaYagmailToolkit(BaseToolkit):
         )
 
     @classmethod
-    def get_toolkit(cls, selected_tools: list[str] | None = None, **kwargs):
+    def get_toolkit(cls, selected_tools: list[str] | None = None, toolkit_name: Optional[str] = None, **kwargs):
         if selected_tools is None:
             selected_tools = []
         yagmail_wrapper = YagmailWrapper(**kwargs)
@@ -44,11 +45,16 @@ class AlitaYagmailToolkit(BaseToolkit):
             if selected_tools:
                 if tool["name"] not in selected_tools:
                     continue
+            description = tool["description"]
+            if toolkit_name:
+                description = f"Toolkit: {toolkit_name}\n{description}"
+            description = description[:1000]
             tools.append(BaseAction(
                 api_wrapper=yagmail_wrapper,
                 name=tool["name"],
-                description=tool["description"],
-                args_schema=tool["args_schema"]
+                description=description,
+                args_schema=tool["args_schema"],
+                metadata={TOOLKIT_NAME_META: toolkit_name, TOOLKIT_TYPE_META: name, TOOL_NAME_META: tool["name"]} if toolkit_name else {TOOL_NAME_META: tool["name"]}
             ))
         return cls(tools=tools)