xgae 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

xgae/utils/json_helpers.py

@@ -0,0 +1,174 @@
+"""
+JSON helper utilities for handling both legacy (string) and new (dict/list) formats.
+
+These utilities help with the transition from storing JSON as strings to storing
+them as proper JSONB objects in the database.
+"""
+
+import json
+from typing import Any, Union, Dict, List
+
+
+def ensure_dict(value: Union[str, Dict[str, Any], None], default: Dict[str, Any] = None) -> Dict[str, Any]:
+    """
+    Ensure a value is a dictionary.
+    
+    Handles:
+    - None -> returns default or {}
+    - Dict -> returns as-is
+    - JSON string -> parses and returns dict
+    - Other -> returns default or {}
+    
+    Args:
+        value: The value to ensure is a dict
+        default: Default value if conversion fails
+        
+    Returns:
+        A dictionary
+    """
+    if default is None:
+        default = {}
+        
+    if value is None:
+        return default
+        
+    if isinstance(value, dict):
+        return value
+        
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+            if isinstance(parsed, dict):
+                return parsed
+            return default
+        except (json.JSONDecodeError, TypeError):
+            return default
+            
+    return default
+
+
+def ensure_list(value: Union[str, List[Any], None], default: List[Any] = None) -> List[Any]:
+    """
+    Ensure a value is a list.
+    
+    Handles:
+    - None -> returns default or []
+    - List -> returns as-is
+    - JSON string -> parses and returns list
+    - Other -> returns default or []
+    
+    Args:
+        value: The value to ensure is a list
+        default: Default value if conversion fails
+        
+    Returns:
+        A list
+    """
+    if default is None:
+        default = []
+        
+    if value is None:
+        return default
+        
+    if isinstance(value, list):
+        return value
+        
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+            if isinstance(parsed, list):
+                return parsed
+            return default
+        except (json.JSONDecodeError, TypeError):
+            return default
+            
+    return default
+
+
+def safe_json_parse(value: Union[str, Dict, List, Any], default: Any = None) -> Any:
+    """
+    Safely parse a value that might be JSON string or already parsed.
+    
+    This handles the transition period where some data might be stored as
+    JSON strings (old format) and some as proper objects (new format).
+    
+    Args:
+        value: The value to parse
+        default: Default value if parsing fails
+        
+    Returns:
+        Parsed value or default
+    """
+    if value is None:
+        return default
+        
+    # If it's already a dict or list, return as-is
+    if isinstance(value, (dict, list)):
+        return value
+        
+    # If it's a string, try to parse it
+    if isinstance(value, str):
+        try:
+            return json.loads(value)
+        except (json.JSONDecodeError, TypeError):
+            # If it's not valid JSON, return the string itself
+            return value
+            
+    # For any other type, return as-is
+    return value
+
+
+def to_json_string(value: Any) -> str:
+    """
+    Convert a value to a JSON string if needed.
+    
+    This is used for backwards compatibility when yielding data that
+    expects JSON strings.
+    
+    Args:
+        value: The value to convert
+        
+    Returns:
+        JSON string representation
+    """
+    if isinstance(value, str):
+        # If it's already a string, check if it's valid JSON
+        try:
+            json.loads(value)
+            return value  # It's already a JSON string
+        except (json.JSONDecodeError, TypeError):
+            # It's a plain string, encode it as JSON
+            return json.dumps(value)
+    
+    # For all other types, convert to JSON
+    return json.dumps(value)
+
+
+def format_for_yield(message_object: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Format a message object for yielding, ensuring content and metadata are JSON strings.
+    
+    This maintains backward compatibility with clients expecting JSON strings
+    while the database now stores proper objects.
+    
+    Args:
+        message_object: The message object from the database
+        
+    Returns:
+        Message object with content and metadata as JSON strings
+    """
+    if not message_object:
+        return message_object
+        
+    # Create a copy to avoid modifying the original
+    formatted = message_object.copy()
+    
+    # Ensure content is a JSON string
+    if 'content' in formatted and not isinstance(formatted['content'], str):
+        formatted['content'] = json.dumps(formatted['content'])
+        
+    # Ensure metadata is a JSON string
+    if 'metadata' in formatted and not isinstance(formatted['metadata'], str):
+        formatted['metadata'] = json.dumps(formatted['metadata'])
+        
+    return formatted 

xgae/utils/llm_client.py

@@ -4,11 +4,24 @@ import logging
 import os
 import litellm
 
-from typing import Union, Dict, Any, Optional, List
+from typing import Union, Dict, Any, Optional, List, TypedDict
 
 from litellm.utils import ModelResponse, CustomStreamWrapper
 from openai import OpenAIError
 
+class LLMConfig(TypedDict, total=False):
+    model: str
+    model_name: str
+    model_id: str
+    api_key: str
+    api_base: str
+    temperature: float
+    max_tokens: int
+    stream: bool
+    enable_thinking: bool
+    reasoning_effort: str
+    response_format: str
+    top_p: int
 
 class LLMError(Exception):
     """Base exception for LLM-related errors."""
@@ -18,7 +31,7 @@ class LLMClient:
     RATE_LIMIT_DELAY = 30
     RETRY_DELAY = 0.1
 
-    def __init__(self, llm_config: Optional[Dict[str, Any]]=None) -> None:
+    def __init__(self, llm_config: LLMConfig=None) -> None:
         """
         Arg: llm_config (Optional[Dict[str, Any]], optional)
             model: Override default model to use, default set by .env LLM_MODEL
@@ -34,7 +47,7 @@ class LLMClient:
             reasoning_effort: Optional level of reasoning effort, default is  ‘low’
             top_p: Optional Top-p sampling parameter, default is None
         """
-        llm_config = llm_config or {}
+        llm_config = llm_config or LLMConfig()
         litellm.modify_params = True
         litellm.drop_params = True
 
@@ -214,9 +227,7 @@ class LLMClient:
 
 if __name__ == "__main__":
     async def llm_completion():
-        llm_client = LLMClient({
-            "stream": False #default is True
-        })
+        llm_client = LLMClient(LLMConfig(stream=False))
         messages = [{"role": "user", "content": "今天是2025年8月15日，北京本周每天温度"}]
         response = await llm_client.create_completion(messages)
         if llm_client.is_stream:

xgae/utils/setup_env.py

@@ -1,10 +1,8 @@
 import logging
 import os
-import traceback
 
 from langfuse import Langfuse
 
-
 _log_initialized = False
 
 def setup_logging() -> None:
@@ -65,17 +63,6 @@ def setup_logging() -> None:
 
 setup_logging()
 
-
-class XGAError(Exception):
-    """Custom exception for errors in the XGA system."""
-    pass
-
-def handle_error(e: Exception) -> None:
-    logging.error("An error occurred: %s", str(e))
-    logging.error("Traceback details:\n%s", traceback.format_exc())
-    raise (e) from e
-
-
 _langfuse_initialized = False
 
 def setup_langfuse() -> Langfuse:
@@ -101,23 +88,6 @@ def setup_langfuse() -> Langfuse:
 langfuse: Langfuse = Langfuse if _langfuse_initialized else setup_langfuse()
 
 
-def read_file(file_path: str) -> str:
-    if not os.path.exists(file_path):
-        logging.error(f"File '{file_path}' not found")
-        raise XGAError(f"File '{file_path}' not found")
-
-    try:
-        with open(file_path, "r", encoding="utf-8") as template_file:
-            content = template_file.read()
-        return content
-    except Exception as e:
-        logging.error(f"Read file '{file_path}' failed")
-        handle_error(e)
-
-
 if __name__ == "__main__":
-    try:
         trace_id = langfuse.create_trace_id()
-        print(f"trace_id={trace_id}")
-    except Exception as e:
-        handle_error(e)
+        logging.warning(f"trace_id={trace_id}")

xgae/utils/utils.py

@@ -0,0 +1,42 @@
+import logging
+import os
+import sys
+import datetime
+
+from typing import Any, Dict
+
+def handle_error(e: Exception) -> None:
+    import traceback
+
+    logging.error("An error occurred: %s", str(e))
+    logging.error("Traceback details:\n%s", traceback.format_exc())
+    raise (e) from e
+
+def read_file(file_path: str) -> str:
+    if not os.path.exists(file_path):
+        logging.error(f"File '{file_path}' not found")
+        raise Exception(f"File '{file_path}' not found")
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as template_file:
+            content = template_file.read()
+        return content
+    except Exception as e:
+        logging.error(f"Read file '{file_path}' failed")
+        handle_error(e)
+
+def format_file_with_args(file_content:str, args: Dict[str, Any])-> str:
+    from io import StringIO
+
+    formated = file_content
+    original_stdout = sys.stdout
+    buffer = StringIO()
+    sys.stdout = buffer
+    try:
+        code = f"print(f\"\"\"{file_content}\"\"\")"
+        exec(code, args)
+        formated = buffer.getvalue()
+    finally:
+        sys.stdout = original_stdout
+
+    return formated

xgae/utils/xml_tool_parser.py

@@ -0,0 +1,236 @@
+"""
+XML Tool Call Parser Module
+
+This module provides a reliable XML tool call parsing system that supports
+the XML format with structured function_calls blocks.
+"""
+
+import re
+import xml.etree.ElementTree as ET
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass
+import json
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class XMLToolCall:
+    """Represents a parsed XML tool call."""
+    function_name: str
+    parameters: Dict[str, Any]
+    raw_xml: str
+    parsing_details: Dict[str, Any]
+
+
+class XMLToolParser:
+    """
+    Parser for XML tool calls format:
+    
+    <function_calls>
+    <invoke name="function_name">
+    <parameter name="param_name">param_value</parameter>
+    ...
+    </invoke>
+    </function_calls>
+    """
+    
+    # Regex patterns for extracting XML blocks
+    FUNCTION_CALLS_PATTERN = re.compile(
+        r'<function_calls>(.*?)</function_calls>',
+        re.DOTALL | re.IGNORECASE
+    )
+    
+    INVOKE_PATTERN = re.compile(
+        r'<invoke\s+name=["\']([^"\']+)["\']>(.*?)</invoke>',
+        re.DOTALL | re.IGNORECASE
+    )
+    
+    PARAMETER_PATTERN = re.compile(
+        r'<parameter\s+name=["\']([^"\']+)["\']>(.*?)</parameter>',
+        re.DOTALL | re.IGNORECASE
+    )
+    
+    def __init__(self):
+        """Initialize the XML tool parser."""
+        pass
+    
+    def parse_content(self, content: str) -> List[XMLToolCall]:
+        """
+        Parse XML tool calls from content.
+        
+        Args:
+            content: The text content potentially containing XML tool calls
+            
+        Returns:
+            List of parsed XMLToolCall objects
+        """
+        tool_calls = []
+        
+        # Find function_calls blocks
+        function_calls_matches = self.FUNCTION_CALLS_PATTERN.findall(content)
+        
+        for fc_content in function_calls_matches:
+            # Find all invoke blocks within this function_calls block
+            invoke_matches = self.INVOKE_PATTERN.findall(fc_content)
+            
+            for function_name, invoke_content in invoke_matches:
+                try:
+                    tool_call = self._parse_invoke_block(
+                        function_name, 
+                        invoke_content,
+                        fc_content
+                    )
+                    if tool_call:
+                        tool_calls.append(tool_call)
+                except Exception as e:
+                    logger.error(f"Error parsing invoke block for {function_name}: {e}")
+        
+        return tool_calls
+    
+    def _parse_invoke_block(
+        self, 
+        function_name: str, 
+        invoke_content: str,
+        full_block: str
+    ) -> Optional[XMLToolCall]:
+        """Parse a single invoke block into an XMLToolCall."""
+        parameters = {}
+        parsing_details = {
+            "function_name": function_name,
+            "raw_parameters": {}
+        }
+        
+        # Extract all parameters
+        param_matches = self.PARAMETER_PATTERN.findall(invoke_content)
+        
+        for param_name, param_value in param_matches:
+            # Clean up the parameter value
+            param_value = param_value.strip()
+            
+            # Try to parse as JSON if it looks like JSON
+            parsed_value = self._parse_parameter_value(param_value)
+            
+            parameters[param_name] = parsed_value
+            parsing_details["raw_parameters"][param_name] = param_value
+        
+        # Extract the raw XML for this specific invoke
+        invoke_pattern = re.compile(
+            rf'<invoke\s+name=["\']{re.escape(function_name)}["\']>.*?</invoke>',
+            re.DOTALL | re.IGNORECASE
+        )
+        raw_xml_match = invoke_pattern.search(full_block)
+        raw_xml = raw_xml_match.group(0) if raw_xml_match else f"<invoke name=\"{function_name}\">...</invoke>"
+        
+        return XMLToolCall(
+            function_name=function_name,
+            parameters=parameters,
+            raw_xml=raw_xml,
+            parsing_details=parsing_details
+        )
+    
+    def _parse_parameter_value(self, value: str) -> Any:
+        """
+        Parse a parameter value, attempting to convert to appropriate type.
+        
+        Args:
+            value: The string value to parse
+            
+        Returns:
+            Parsed value (could be dict, list, bool, int, float, or str)
+        """
+        value = value.strip()
+        
+        # Try to parse as JSON first
+        if value.startswith(('{', '[')):
+            try:
+                return json.loads(value)
+            except json.JSONDecodeError:
+                pass
+        
+        # Try to parse as boolean
+        if value.lower() in ('true', 'false'):
+            return value.lower() == 'true'
+        
+        # Try to parse as number
+        try:
+            if '.' in value:
+                return float(value)
+            else:
+                return int(value)
+        except ValueError:
+            pass
+        
+        # Return as string
+        return value
+    
+    
+    def format_tool_call(self, function_name: str, parameters: Dict[str, Any]) -> str:
+        """
+        Format a tool call in the XML format.
+        
+        Args:
+            function_name: Name of the function to call
+            parameters: Dictionary of parameters
+            
+        Returns:
+            Formatted XML string
+        """
+        lines = ['<function_calls>', '<invoke name="{}">'.format(function_name)]
+        
+        for param_name, param_value in parameters.items():
+            # Convert value to string representation
+            if isinstance(param_value, (dict, list)):
+                value_str = json.dumps(param_value)
+            elif isinstance(param_value, bool):
+                value_str = str(param_value).lower()
+            else:
+                value_str = str(param_value)
+            
+            lines.append('<parameter name="{}">{}</parameter>'.format(
+                param_name, value_str
+            ))
+        
+        lines.extend(['</invoke>', '</function_calls>'])
+        return '\n'.join(lines)
+    
+    def validate_tool_call(self, tool_call: XMLToolCall, expected_params: Optional[Dict[str, type]] = None) -> Tuple[bool, Optional[str]]:
+        """
+        Validate a tool call against expected parameters.
+        
+        Args:
+            tool_call: The XMLToolCall to validate
+            expected_params: Optional dict of parameter names to expected types
+            
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        if not tool_call.function_name:
+            return False, "Function name is required"
+        
+        if expected_params:
+            for param_name, expected_type in expected_params.items():
+                if param_name not in tool_call.parameters:
+                    return False, f"Missing required parameter: {param_name}"
+                
+                param_value = tool_call.parameters[param_name]
+                if not isinstance(param_value, expected_type):
+                    return False, f"Parameter {param_name} should be of type {expected_type.__name__}"
+        
+        return True, None
+
+
+# Convenience function for quick parsing
+def parse_xml_tool_calls(content: str) -> List[XMLToolCall]:
+    """
+    Parse XML tool calls from content.
+    
+    Args:
+        content: The text content potentially containing XML tool calls
+        
+    Returns:
+        List of parsed XMLToolCall objects
+    """
+    parser = XMLToolParser()
+    return parser.parse_content(content) 

{xgae-0.1.2.dist-info → xgae-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xgae
-Version: 0.1.2
+Version: 0.1.4
 Summary: Extreme General Agent Engine
 Requires-Python: >=3.13
 Requires-Dist: colorlog>=6.9.0

xgae-0.1.4.dist-info/RECORD

@@ -0,0 +1,16 @@
+xgae/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xgae/engine/xga_base.py,sha256=yM8YdThOVHo_TFrLUiu33hZzU2H9knQLs3JfD6hOx24,1669
+xgae/engine/xga_engine.py,sha256=7XRRC6KKz3a2EvH7P9k8szbCCm2O6MxIL674GzUkwHI,12940
+xgae/engine/xga_mcp_tool_box.py,sha256=dvToorrw8FJq4NrzUz494czI6QhT3bvmJQlt5oFgVBA,9994
+xgae/engine/xga_prompt_builder.py,sha256=RuTvQCNufqxDwVvSOPXR0qxAc42cG7NuIaUy9amu66A,4351
+xgae/engine/responser/xga_non_stream_responser.py,sha256=HlSN025jIsl-JY_n6fEdqJQkqc1UqCrgFr6K23uXF3E,12704
+xgae/engine/responser/xga_responser_base.py,sha256=IBJPQELMxZSpnz8YlSCgvPNSHEEUp8_vglotVnHoSeY,36808
+xgae/engine/responser/xga_stream_responser.py,sha256=FESVliTzHFy8BkTudi_Ftcty6QFpJWx7kYRubSuLqsg,50370
+xgae/utils/json_helpers.py,sha256=K1ja6GJCatrAheW9bEWAYSQbDI42__boBCZgtsv1gtk,4865
+xgae/utils/llm_client.py,sha256=mgzn8heUyRm92HTLEYGdfsGEpFtD-xLFr39P98_JP0s,12402
+xgae/utils/setup_env.py,sha256=-Ehv7_E9udHc8AjP66Y78E4X7_G6gpuNJkioCh5fn4A,2902
+xgae/utils/utils.py,sha256=cCYmWjKFksZ8BRD1YYnaM_jTLVHAg1ibEdjsczEUO6k,1134
+xgae/utils/xml_tool_parser.py,sha256=7Ei7X8zSgVct0fFCSmxDtknCLtdrUIwL9hy_0qSNlvs,7546
+xgae-0.1.4.dist-info/METADATA,sha256=R_nN1j5mESZfEQIiLFBQufsOc_Hbd6190GBLgo7-k-o,309
+xgae-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+xgae-0.1.4.dist-info/RECORD,,

xgae-0.1.2.dist-info/RECORD

@@ -1,13 +0,0 @@
-xgae/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xgae/engine/xga_base.py,sha256=vOiYWoBze7VrmndYnaNhMzoB1zCT80WtIlOWdp2IrUc,1253
-xgae/engine/xga_engine.py,sha256=AgklNAimyErvn74xUu6aardZvgjqbIR99gCojEmZfO0,4267
-xgae/engine/xga_mcp_tool_box.py,sha256=jRYvZ8eY72KRU0leD-o15fe_E8wjWJtxQZbsIqGVjPU,9753
-xgae/engine/xga_prompt_builder.py,sha256=Q3nrmYAofRkFQFdfSWkP00FZKjWMUQs2cvMs7bvyQgQ,4819
-xgae/engine/responser/xga_non_stream_responser.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xgae/engine/responser/xga_responser_utils.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xgae/engine/responser/xga_stream_reponser.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-xgae/utils/llm_client.py,sha256=UMMK84psLsx36-Nn6Q8X1hl9wd-OdaS9ZhxbRjwNCr0,12149
-xgae/utils/setup_env.py,sha256=qZmVfqaYHtjq5t-zwRt_G3i-QqGPxSb4D2FnFHbhdcY,3689
-xgae-0.1.2.dist-info/METADATA,sha256=iBwWKlpbp7z0ZQgydnieP_2NBf0Z7H0D6AtavbIN3Zc,309
-xgae-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-xgae-0.1.2.dist-info/RECORD,,