xgae 0.1.14__py3-none-any.whl → 0.1.15__py3-none-any.whl

xgae/engine/mcp_tool_box.py

@@ -17,16 +17,17 @@ class XGAMcpToolBox(XGAToolBox):
                  custom_mcp_server_config: Optional[Dict[str, Any]] = None
         ):
         general_mcp_server_config = self._load_mcp_servers_config("mcpservers/xga_server.json")
-        tool_box_mcp_server_config = general_mcp_server_config.get("mcpServers", {})
+        tool_box_mcp_server_config = general_mcp_server_config.get('mcpServers', {})
 
         if custom_mcp_server_config:
             tool_box_mcp_server_config.update(custom_mcp_server_config)
         elif custom_mcp_server_file:
             custom_mcp_server_config = self._load_mcp_servers_config(custom_mcp_server_file)
-            custom_mcp_server_config = custom_mcp_server_config.get("mcpServers", {})
+            custom_mcp_server_config = custom_mcp_server_config.get('mcpServers', {})
             tool_box_mcp_server_config.update(custom_mcp_server_config)
 
         self._mcp_client = MultiServerMCPClient(tool_box_mcp_server_config)
+
         self.mcp_server_names: List[str] = [server_name for server_name in tool_box_mcp_server_config]
         self.mcp_tool_schemas: Dict[str, List[XGAToolSchema]] = {}
         self.task_tool_schemas: Dict[str, Dict[str,XGAToolSchema]] = {}
@@ -178,18 +179,18 @@ class XGAMcpToolBox(XGAToolBox):
                     for server_name, server_info in server_config["mcpServers"].items():
                         if "transport" not in server_info:
                             if "url" in server_info:
-                                server_info["transport"] = "streamable_http" if "mcp" in server_info["url"] else "sse"
+                                server_info['transport'] = "streamable_http" if "mcp" in server_info['url'] else "sse"
                             else:
-                                server_info["transport"] = "stdio"
+                                server_info['transport'] = "stdio"
 
                     return server_config
             else:
                 logging.warning(f"McpToolBox load_mcp_servers_config: MCP servers config file not found at: {mcp_config_path}")
-                return {"mcpServers": {}}
+                return {'mcpServers': {}}
 
         except Exception as e:
             logging.error(f"McpToolBox load_mcp_servers_config: Failed to load MCP servers config: {e}")
-            return {"mcpServers": {}}
+            return {'mcpServers': {}}
 
 
 if __name__ == "__main__":

xgae/engine/prompt_builder.py

@@ -34,19 +34,20 @@ class XGAPromptBuilder():
             openai_schemas = []
             for tool_schema in tool_schemas:
                 openai_schema = {}
-                openai_schema["type"] = "function"
                 openai_function = {}
-                openai_schema["function"] = openai_function
+                openai_schema['type'] = "function"
+                openai_schema['function'] = openai_function
 
-                openai_function["name"] = tool_schema.tool_name
-                openai_function["description"] = tool_schema.description if tool_schema.description else 'No description available'
+                openai_function['name'] = tool_schema.tool_name
+                openai_function['description'] = tool_schema.description if tool_schema.description else 'No description available'
 
                 openai_parameters = {}
+                openai_function['parameters'] = openai_parameters
+
                 input_schema = tool_schema.input_schema
-                openai_function["parameters"] = openai_parameters
-                openai_parameters["type"] = input_schema["type"]
-                openai_parameters["properties"] = input_schema.get("properties", {})
-                openai_parameters["required"] = input_schema["required"]
+                openai_parameters['type']       = input_schema['type']
+                openai_parameters['properties'] = input_schema.get('properties', {})
+                openai_parameters['required']   = input_schema['required']
 
                 openai_schemas.append(openai_schema)
 

xgae/engine/responser/non_stream_responser.py

@@ -3,7 +3,7 @@ import logging
 from typing import List, Dict, Any, AsyncGenerator, override,Optional
 
 from xgae.utils import log_trace
-from xgae.utils.json_helpers import format_for_yield
+
 
 from xgae.engine.responser.responser_base import TaskResponseProcessor, TaskResponserContext, TaskRunContinuousState
 
@@ -25,7 +25,7 @@ class NonStreamTaskResponser(TaskResponseProcessor):
         try:
             if hasattr(llm_response, 'choices') and llm_response.choices:
                 if hasattr(llm_response.choices[0], 'finish_reason'):
-                    finish_reason = llm_response.choices[0].finish_reason
+                    finish_reason = llm_response.choices[0].finish_reason # LLM finish reason: ‘stop' , 'length'
                     logging.info(f"NonStreamResp: LLM response finish_reason={finish_reason}")
 
                 response_message = llm_response.choices[0].message if hasattr(llm_response.choices[0], 'message') else None
@@ -35,12 +35,13 @@ class NonStreamTaskResponser(TaskResponseProcessor):
                         
                         parsed_xml_data = self._parse_xml_tool_calls(llm_content)
                         if self.max_xml_tool_calls > 0 and len(parsed_xml_data) > self.max_xml_tool_calls:
-                            logging.warning(f"NonStreamResp: Truncate content, parsed_xml_data length={len(parsed_xml_data)} limit over max_xml_tool_calls={self.max_xml_tool_calls}")
+                            logging.warning(f"NonStreamResp: Over XML Tool Limit, finish_reason='xml_tool_limit_reached', "
+                                            f"parsed_xml_data_len={len(parsed_xml_data)}")
                             parsed_xml_data = parsed_xml_data[:self.max_xml_tool_calls]
                             finish_reason = "xml_tool_limit_reached"
 
             self.root_span.event(name=f"non_stream_processor_start[{self.task_no}]({llm_count})", level="DEFAULT",
-                             status_message=f"finish_reason={finish_reason}, tool_exec_strategy={self.tool_execution_strategy}, "
+                             status_message=f"finish_reason={finish_reason}, tool_exec_strategy={self.tool_exec_strategy}, "
                                             f"parsed_xml_data_len={len(parsed_xml_data)}, llm_content_len={len(llm_content)}")
 
             if  len(llm_content) == 0:
@@ -52,7 +53,7 @@ class NonStreamTaskResponser(TaskResponseProcessor):
 
             tool_calls_to_execute = [item['tool_call'] for item in parsed_xml_data]
             if  len(tool_calls_to_execute) > 0:
-                tool_results = await self._execute_tools(tool_calls_to_execute, self.tool_execution_strategy)
+                tool_results = await self._execute_tools(tool_calls_to_execute, self.tool_exec_strategy)
 
                 tool_index = 0
                 for i, (returned_tool_call, tool_result) in enumerate(tool_results):
@@ -64,16 +65,16 @@ class NonStreamTaskResponser(TaskResponseProcessor):
                     tool_context = self._create_tool_context(tool_call, tool_index, assistant_msg_id, parsing_details, tool_result)
 
                     tool_start_msg = self._add_tool_start_message(tool_context)
-                    yield format_for_yield(tool_start_msg)
+                    yield tool_start_msg
 
                     tool_message = self._add_tool_messsage(tool_call, tool_result, self.xml_adding_strategy, assistant_msg_id, parsing_details)
 
                     tool_completed_msg = self._add_tool_completed_message(tool_context, tool_message['message_id'])
-                    yield format_for_yield(tool_completed_msg)
+                    yield tool_completed_msg
 
-                    yield format_for_yield(tool_message)
+                    yield tool_message
 
-                    if tool_completed_msg["metadata"].get("agent_should_terminate") == "true":
+                    if tool_context.function_name in ['ask', 'complete']:
                         finish_reason = "completed"
                         break
 
@@ -85,7 +86,7 @@ class NonStreamTaskResponser(TaskResponseProcessor):
             if finish_reason:
                 finish_content = {"status_type": "finish", "finish_reason": finish_reason}
                 finish_msg = self.add_response_message(type="status", content=finish_content, is_llm_message=False)
-                yield format_for_yield(finish_msg)
+                yield finish_msg
         except Exception as e:
             trace = log_trace(e, f"NonStreamResp: Process response llm_content:\n {llm_content}")
             self.root_span.event(name="non_stream_process_response_error", level="ERROR",
@@ -94,7 +95,7 @@ class NonStreamTaskResponser(TaskResponseProcessor):
 
             content = {"role": "system", "status_type": "error", "message": f"Process non-streaming response error: {e}"}
             error_msg = self.add_response_message(type="status", content=content, is_llm_message=False)
-            yield format_for_yield(error_msg)
+            yield error_msg
 
             raise  # Use bare 'raise' to preserve the original exception with its traceback
 

xgae/engine/responser/responser_base.py

@@ -28,8 +28,8 @@ class TaskResponserContext(TypedDict, total=False):
     model_name: str
     max_xml_tool_calls: int             # LLM generate max_xml_tool limit, 0 is no limit
     use_assistant_chunk_msg: bool
-    tool_execution_strategy: ToolExecutionStrategy
-    tool_execute_on_stream: bool
+    tool_exec_strategy: ToolExecutionStrategy
+    tool_exec_on_stream: bool
     xml_adding_strategy: XmlAddingStrategy
     add_response_msg_func: Callable
     create_response_msg_func: Callable
@@ -49,9 +49,9 @@ class ToolExecutionContext:
     """Context for a tool execution including call details, result, and display info."""
     tool_call: Dict[str, Any]
     tool_index: int
-    function_name: Optional[str] = None
+    function_name: str
+    xml_tag_name: str
     result: Optional[XGAToolResult] = None
-    xml_tag_name: Optional[str] = None
     error: Optional[Exception] = None
     assistant_message_id: Optional[str] = None
     parsing_details: Optional[Dict[str, Any]] = None
@@ -61,21 +61,23 @@ class TaskResponseProcessor(ABC):
     def __init__(self, response_context: TaskResponserContext):
         self.response_context = response_context
 
-        self.task_id = response_context.get("task_id")
-        self.task_run_id = response_context.get("task_run_id")
-        self.task_no = response_context.get("task_no")
-        self.tool_execution_strategy = self.response_context.get("tool_execution_strategy", "parallel")
-        self.xml_adding_strategy = self.response_context.get("xml_adding_strategy", "user_message")
-        self.max_xml_tool_calls = self.response_context.get("max_xml_tool_calls", 0)
-        self.tool_execute_on_stream = response_context.get("tool_execute_on_stream", False)
+        self.task_id                = response_context['task_id']
+        self.task_run_id            = response_context['task_run_id']
+        self.task_no                = response_context['task_no']
+        self.tool_exec_strategy     = response_context['tool_exec_strategy']
+        self.tool_exec_on_stream    = response_context['tool_exec_on_stream']
+        self.xml_adding_strategy    = response_context['xml_adding_strategy']
+        self.max_xml_tool_calls     = response_context['max_xml_tool_calls']
 
-        task_langfuse = response_context.get("task_langfuse")
+        self.add_response_message       = response_context['add_response_msg_func']
+        self.create_response_message    = response_context['create_response_msg_func']
+        self.tool_box                   = response_context['tool_box']
+
+        task_langfuse = response_context['task_langfuse']
         self.root_span = task_langfuse.root_span
-        self.add_response_message = response_context.get("add_response_msg_func")
-        self.create_response_message = response_context.get("create_response_msg_func")
 
-        self.tool_box = response_context.get("tool_box")
-        self.xml_parser = XMLToolParser()
+        self.xml_parser                 = XMLToolParser()
+
 
 
     @abstractmethod
@@ -209,16 +211,16 @@ class TaskResponseProcessor(ABC):
 
                 # Convert to the expected format
                 tool_call = {
-                    "function_name": xml_tool_call.function_name,
-                    "xml_tag_name": xml_tool_call.function_name.replace('_', '-'),  # For backwards compatibility
-                    "arguments": xml_tool_call.parameters
+                    'function_name' : xml_tool_call.function_name,
+                    'xml_tag_name'  : xml_tool_call.function_name.replace("_", "-"),  # For backwards compatibility
+                    'arguments'     : xml_tool_call.parameters
                 }
 
                 # Include the parsing details
                 parsing_details = xml_tool_call.parsing_details
-                parsing_details["raw_xml"] = xml_tool_call.raw_xml
+                parsing_details['raw_xml'] = xml_tool_call.raw_xml
 
-                logging.debug(f"Parsed new format tool call: {tool_call}")
+                logging.debug(f"TaskProcessor parse_xml_tool_call: Parsed new format tool call: {tool_call}")
                 return tool_call, parsing_details
 
             # If not the expected <function_calls><invoke> format, return None
@@ -260,7 +262,7 @@ class TaskResponseProcessor(ABC):
 
     async def _execute_tool(self, tool_call: Dict[str, Any]) -> XGAToolResult:
         """Execute a single tool call and return the result."""
-        function_name = tool_call.get("function_name", "empty_function")
+        function_name = tool_call['function_name']
         exec_tool_span = self.root_span.span(name=f"execute_tool.{function_name}", input=tool_call["arguments"])
         try:
             arguments = tool_call["arguments"]
@@ -328,7 +330,7 @@ class TaskResponseProcessor(ABC):
 
         results = []
         for index, tool_call in enumerate(tool_calls):
-            tool_name = tool_call.get('function_name', 'unknown')
+            tool_name = tool_call['function_name']
             logging.info(f"TaskProcessor execute_tools_sequentially: Executing tool '{tool_name}', sequence={index + 1}/{tool_num}")
             result = await self._execute_tool(tool_call)
             results.append((tool_call, result))
@@ -358,7 +360,7 @@ class TaskResponseProcessor(ABC):
             logging.warning("TaskProcessor execute_tools_in_parallel: tool_calls is empty")
             return []
 
-        tool_names = [t.get('function_name', 'unknown') for t in tool_calls]
+        tool_names = [t['function_name'] for t in tool_calls]
         tool_num = len(tool_calls)
         if tool_num > 1:
             logging.info(f"TaskProcessor execute_tools_in_parallel: Executing {tool_num} tools sequentially: {tool_names}")
@@ -384,17 +386,6 @@ class TaskResponseProcessor(ABC):
                            assistant_message_id: Optional[str] = None,
                            parsing_details: Optional[Dict[str, Any]] = None
                            ) -> Optional[Dict[str, Any]]:  # Return the full message object
-        tool_message = None
-
-        metadata = {}
-        if assistant_message_id:
-            metadata["assistant_message_id"] = assistant_message_id
-
-        if parsing_details:
-            metadata["parsing_details"] = parsing_details
-
-        role = "user" if strategy == "user_message" else "assistant"
-
         # Create two versions of the structured result
         # Rich version for the frontend
         result_for_frontend = self._create_structured_tool_result(tool_call, result, parsing_details, for_llm=False)
@@ -403,21 +394,24 @@ class TaskResponseProcessor(ABC):
 
         # Add the message with the appropriate role to the conversation history
         # This allows the LLM to see the tool result in subsequent interactions
+        role = "user" if strategy == "user_message" else "assistant"
         content = {
-            "role": role,
-            "content": json.dumps(result_for_llm)
+            'role': role,
+            'content': json.dumps(result_for_llm)
         }
 
+        metadata = {}
+        if assistant_message_id:
+            metadata["assistant_message_id"] = assistant_message_id
+
+        if parsing_details:
+            metadata["parsing_details"] = parsing_details
+
         metadata['frontend_content'] = result_for_frontend
 
-        tool_message =  self.add_response_message(
-            type="tool",
-            content=content,
-            is_llm_message=True,
-            metadata=metadata
-        )
+        tool_message =  self.add_response_message(type="tool", content=content, is_llm_message=True, metadata=metadata)
 
-        # Let's reconstruct the message for yielding.
+        # Let's result_for_frontend the message for yielding.
         yield_message = tool_message.copy()
         yield_message['content'] = result_for_frontend
 
@@ -429,7 +423,7 @@ class TaskResponseProcessor(ABC):
                                        result: XGAToolResult,
                                        parsing_details: Optional[Dict[str, Any]] = None,
                                        for_llm: bool = False) -> Dict[str, Any]:
-        function_name = tool_call.get("function_name", "unknown")
+        function_name = tool_call['function_name']
         xml_tag_name = tool_call.get("xml_tag_name")
         arguments = tool_call.get("arguments", {})
         tool_call_id = tool_call.get("id")
@@ -449,15 +443,14 @@ class TaskResponseProcessor(ABC):
             output_to_use = output
 
         structured_result = {
-            "tool_execution": {
-                "function_name": function_name,
-                "xml_tag_name": xml_tag_name,
-                "tool_call_id": tool_call_id,
-                "arguments": arguments,
-                "result": {
-                    "success": result.success,
-                    "output": output_to_use,
-                    "error": None if result.success else result.output
+            'tool_execution': {
+                'function_name' : function_name,
+                'xml_tag_name'  : xml_tag_name,
+                'arguments'     : arguments,
+                'result'      : {
+                    'success' : result.success,
+                    'output'  : output_to_use,
+                    'error'   : None if result.success else result.output
                 },
             }
         }
@@ -474,26 +467,25 @@ class TaskResponseProcessor(ABC):
                              ) -> ToolExecutionContext:
         """Create a tool execution context with display name and parsing details populated."""
         return ToolExecutionContext(
-            function_name=tool_call.get("function_name"),
-            tool_call=tool_call,
-            tool_index=tool_index,
-            assistant_message_id=assistant_message_id,
-            parsing_details=parsing_details,
-            xml_tag_name=tool_call.get("xml_tag_name"),
-            result=result,
+            tool_call               = tool_call,
+            tool_index              = tool_index,
+            function_name           = tool_call['function_name'],
+            xml_tag_name            = tool_call['xml_tag_name'],
+            assistant_message_id    = assistant_message_id,
+            parsing_details         = parsing_details,
+            result                  = result
         )
 
 
     def _add_tool_start_message(self, context: ToolExecutionContext) -> Optional[Dict[str, Any]]:
         """Formats, saves, and returns a tool started status message."""
-        tool_name = context.xml_tag_name or context.function_name
         content = {
-            "status_type": "tool_started",
-            "role": "assistant",
-            "function_name": context.function_name,
-            "xml_tag_name": context.xml_tag_name,
-            "message": f"Starting execution of {tool_name}",
-            "tool_index": context.tool_index
+            'status_type'       : "tool_started",
+            'role'              : "assistant",
+            'function_name'     : context.function_name,
+            'xml_tag_name'      : context.xml_tag_name,
+            'message'           : f"Starting execution of {context.function_name}",
+            'tool_index'        : context.tool_index
         }
 
         return  self.add_response_message(type="status", content=content, is_llm_message=False)
@@ -503,42 +495,34 @@ class TaskResponseProcessor(ABC):
         if not context.result:
             return  self._add_tool_error_message(context)
 
-        tool_name = context.xml_tag_name or context.function_name
         status_type = "tool_completed" if context.result.success else "tool_failed"
-        message_text = f"Tool {tool_name} {'completed successfully' if context.result.success else 'failed'}"
+        message_text = f"Tool {context.function_name} {'completed successfully' if context.result.success else 'failed'}"
 
         content = {
-            "status_type": status_type,
-            "role": "assistant",
-            "function_name": context.function_name,
-            "xml_tag_name": context.xml_tag_name,
-            "message": message_text,
-            "tool_index": context.tool_index,
-            "tool_call_id": context.tool_call.get("id")
+            "status_type"       : status_type,
+            "role"              : "assistant",
+            "function_name"     : context.function_name,
+            "xml_tag_name"      : context.xml_tag_name,
+            "message"           : message_text,
+            "tool_index"        : context.tool_index
         }
 
         metadata = {}
-        # Add the *actual* tool result message ID to the metadata if available and successful
-        if context.result.success and tool_message_id:
-            metadata["linked_tool_result_message_id"] = tool_message_id
-
-        if context.function_name in ['ask', 'complete']:
-            metadata["agent_should_terminate"] = "true"
+        if tool_message_id:
+            metadata["tool_result_message_id"] = tool_message_id
 
         return  self.add_response_message(type="status", content=content, is_llm_message=False, metadata=metadata)
 
     def _add_tool_error_message(self, context: ToolExecutionContext) -> Optional[Dict[str, Any]]:
         """Formats, saves, and returns a tool error status message."""
-        error_msg = str(context.error) if context.error else "Unknown error during tool execution"
-        tool_name = context.xml_tag_name or context.function_name
+        error_msg = str(context.error) if context.error else "Tool execution unknown exception"
         content = {
-            "status_type": "tool_error",
-            "role": "assistant",
-            "function_name": context.function_name,
-            "xml_tag_name": context.xml_tag_name,
-            "message": f"Error executing tool {tool_name}: {error_msg}",
-            "tool_index": context.tool_index,
-            "tool_call_id": context.tool_call.get("id")
+            "status_type"       : "tool_error",
+            "role"              : "assistant",
+            "function_name"     : context.function_name,
+            "xml_tag_name"      : context.xml_tag_name,
+            "message"           : f"Executing tool {context.function_name} exception: {error_msg}",
+            "tool_index"        : context.tool_index
         }
 
         return  self.add_response_message(type="status", content=content, is_llm_message=False)