xgae 0.1.1__py3-none-any.whl

xgae/engine/xga_base.py

@@ -0,0 +1,46 @@
+from typing import Union, Optional, Dict, List, Any, Literal
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+
+
+
+@dataclass
+class XGAMessage:
+    message_id: str
+    type: Literal["status",  "tool", "assistant", "assistant_response_end"]
+    is_llm_message: bool
+    content: Union[Dict[str, Any], List[Any], str]
+    metadata: Optional[Dict[str, Any]]
+    session_id: Optional[str]
+    agent_id: Optional[str]
+    task_id: Optional[str]
+
+@dataclass
+class XGAToolSchema:
+    tool_name: str
+    server_name: str
+    description: str
+    input_schema: Optional[str]
+
+
+@dataclass
+class XGAToolResult:
+    success: bool
+    output: str
+
+class XGAToolBox(ABC):
+    @abstractmethod
+    async def creat_task_tool_box(self, task_id: str, general_tools: List[str], custom_tools: List[str]):
+        pass
+
+    @abstractmethod
+    async def destroy_task_tool_box(self, task_id: str):
+        pass
+
+    @abstractmethod
+    def get_task_tool_schemas(self, task_id: str, type: Literal["general_tool",  "custom_tool"]) -> List[XGAToolSchema]:
+        pass
+
+    @abstractmethod
+    async def call_tool(self, task_id: str, tool_name: str, args: Optional[Dict[str, Any]] = None) -> XGAToolResult:
+        pass

xgae/engine/xga_engine.py

@@ -0,0 +1,69 @@
+
+from typing import List, Any, Dict, Optional, AsyncGenerator
+from uuid import uuid4
+
+from xgae.engine.xga_base import XGAMessage, XGAToolSchema, XGAToolBox
+from xgae.utils.llm_client import LLMClient
+from xgae.utils.setup_env import langfuse
+from xga_prompt_builder import XGAPromptBuilder
+from xga_mcp_tool_box import XGAMcpToolBox
+
+class XGAEngine():
+    def __init__(self,
+                 session_id: Optional[str] = None,
+                 trace_id: Optional[str] = None,
+                 agent_id: Optional[str] = None,
+                 llm_config: Optional[Dict[str, Any]] = None,
+                 prompt_builder: Optional[XGAPromptBuilder] = None,
+                 tool_box: Optional[XGAToolBox] = None):
+        self.session_id = session_id if session_id else f"xga_sid_{uuid4()}"
+        self.agent_id = agent_id
+
+        self.messages: List[XGAMessage] = []
+        self.llm_client = LLMClient(llm_config)
+        self.model_name = self.llm_client.model_name
+        self.is_stream = self.llm_client.is_stream
+
+        self.prompt_builder = prompt_builder or XGAPromptBuilder()
+        self.tool_box = tool_box or XGAMcpToolBox()
+
+        self.task_id = None
+        self.trace_id = trace_id if trace_id else langfuse.create_trace_id()
+
+
+    async def run_task(self,
+                       task_messages: List[Dict[str, Any]],
+                       task_id: Optional[str],
+                       prompt_template: Optional[str] = None,
+                       general_tools: Optional[List[str]] = ["*"],
+                       custom_tools: Optional[List[str]] = []) -> AsyncGenerator:
+        try:
+            self.task_id = task_id if task_id else f"xga_task_{uuid4()}"
+            await self.tool_box.creat_task_tool_box(self.task_id, general_tools, custom_tools)
+            system_prompt = await self._build_system_prompt(prompt_template, general_tools, custom_tools)
+            yield system_prompt
+
+        finally:
+            await self.tool_box.destroy_task_tool_box(self.task_id)
+        
+
+    def _run_task_once(self):
+        pass
+
+    async def _build_system_prompt(self, prompt_template: str, general_tools: List[str], custom_tools: List[str]) -> str:
+        self.task_tool_schemas: Dict[str, XGAToolSchema] = {}
+        system_prompt = self.prompt_builder.build_system_prompt(self.model_name, prompt_template)
+
+        tool_schemas = await self.tool_box.get_task_tool_schemas(self.task_id, "general_tool")
+        system_prompt = self.prompt_builder.build_general_tool_prompt(self.model_name, system_prompt, tool_schemas)
+
+        tool_schemas = await self.tool_box.get_task_tool_schemas(self.task_id, "general_tool")
+        system_prompt = self.prompt_builder.build_custom_tool_prompt(self.model_name, system_prompt, tool_schemas)
+
+        return system_prompt
+
+    def add_message(self, message: XGAMessage):
+        message.message_id = f"xga_msg_{uuid4()}"
+        message.session_id = self.session_id
+        message.agent_id = self.agent_id
+        self.messages.append(message)

xgae/engine/xga_mcp_tool_box.py

@@ -0,0 +1,192 @@
+import json
+import logging
+import os
+from typing import List, Any, Dict, Optional, Literal, override
+
+from langchain_mcp_adapters.client import MultiServerMCPClient
+from langchain_mcp_adapters.tools import load_mcp_tools
+
+from xgae.engine.xga_base import XGAToolSchema, XGAToolBox, XGAToolResult
+from xgae.utils.setup_env import XGAError
+
+
+class XGAMcpToolBox(XGAToolBox):
+    GENERAL_MCP_SERVER_NAME = "xga_general"
+
+    def __init__(self,
+                 custom_mcp_server_config: Optional[Dict[str, Any]] = None,
+                 custom_mcp_server_file: Optional[str] = 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", {})
+
+        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", {})
+            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]] = {}
+
+    @override
+    async def creat_task_tool_box(self, task_id: str, general_tools: List[str], custom_tools: List[str]):
+        task_tool_schemas = {}
+        general_tool_schemas = self.mcp_tool_schemas.get(XGAMcpToolBox.GENERAL_MCP_SERVER_NAME, {})
+        if len(general_tools) > 0 and general_tools[0] == "*":
+            task_tool_schemas = {tool_schema.tool_name: tool_schema for tool_schema in general_tool_schemas}
+        else:
+            for tool_schema in general_tool_schemas:
+                if tool_schema.tool_name in general_tools:
+                    task_tool_schemas[tool_schema.tool_name] = tool_schema
+        task_tool_schemas.pop("end_task")
+
+        for server_tool_name in custom_tools:
+            parts = server_tool_name.split(".")
+            if len(parts) != 2:
+                continue
+            custom_server_name, custom_tool_name = parts
+            if (not custom_server_name ) or (not custom_tool_name):
+                continue
+
+            custom_tool_schemas = self.mcp_tool_schemas.get(custom_server_name, None)
+            if custom_tool_schemas is None:
+                continue
+            if custom_tool_name == "*":
+                custom_tool_schema_d = {tool_schema.tool_name: tool_schema for tool_schema in custom_tool_schemas}
+                task_tool_schemas.update(custom_tool_schema_d)
+            else:
+                for tool_schema in custom_tool_schemas:
+                    if custom_tool_name == tool_schema.tool_name:
+                        task_tool_schemas[custom_tool_name] = tool_schema
+
+
+        self.task_tool_schemas[task_id] = task_tool_schemas
+
+    @override
+    async def destroy_task_tool_box(self, task_id: str):
+        tool_schemas = self.get_task_tool_schemas(task_id, type="general_tool")
+        if len(tool_schemas) > 0:
+            await self.call_tool(task_id, "end_task", {"task_id": task_id})
+        self.task_tool_schemas.pop(task_id, None)
+
+    @override
+    def get_task_tool_schemas(self, task_id: str, type: Literal["general_tool",  "custom_tool"]) -> List[XGAToolSchema]:
+        task_tool_schemas = []
+
+        all_task_tool_schemas = self.task_tool_schemas.get(task_id, {})
+        for tool_schema in all_task_tool_schemas.values():
+            if type == "general_tool" and tool_schema.server_name == self.GENERAL_MCP_SERVER_NAME:
+                task_tool_schemas.append(tool_schema)
+            elif type == "custom_tool" and tool_schema.server_name != self.GENERAL_MCP_SERVER_NAME:
+                task_tool_schemas.append(tool_schema)
+
+        return task_tool_schemas
+
+    @override
+    async def call_tool(self, task_id: str, tool_name: str, args: Optional[Dict[str, Any]] = None) -> XGAToolResult:
+        if tool_name == "end_task":
+            server_name = self.GENERAL_MCP_SERVER_NAME
+        else:
+            task_tool_schemas = self.task_tool_schemas.get(task_id, {})
+            tool_schema = task_tool_schemas.get(tool_name, None)
+            if tool_schema is None:
+                raise XGAError(f"MCP tool not found: '{tool_name}'")
+            server_name = tool_schema.server_name
+
+        async with self._mcp_client.session(server_name) as session:
+            tools = await load_mcp_tools(session)
+            mcp_tool = next((t for t in tools if t.name == tool_name), None)
+
+            if mcp_tool:
+                tool_args = args or {}
+                if server_name == self.GENERAL_MCP_SERVER_NAME:
+                    pass
+                    #tool_args["task_id"] = task_id #xga general tool, first param must be task_id
+                else:
+                    tool_args = args
+
+                try:
+                    tool_result = await mcp_tool.arun(tool_args)
+                    result = XGAToolResult(success=True, output=str(tool_result))
+                except Exception as e:
+                    error = f"Call mcp tool '{tool_name}' error: {str(e)}"
+                    logging.error(f"XGAMcpToolBox.call_tool: {error}")
+                    result = XGAToolResult(success=False, output=error)
+            else:
+                error = f"No MCP tool found with name: {tool_name}"
+                logging.info(f"XGAMcpToolBox.call_tool: error={error}")
+                result =  XGAToolResult(success=False, output=error)
+
+            return result
+
+    async def load_mcp_tools_schema(self)-> None:
+        for server_name in self.mcp_server_names:
+            self.mcp_tool_schemas[server_name] = []
+            mcp_tools = await self._mcp_client.get_tools(server_name=server_name)
+            for tool in mcp_tools:
+                input_schema = tool.args_schema
+                if server_name == self.GENERAL_MCP_SERVER_NAME:
+                    input_schema = str(tool.args_schema) # @todo remove task_id param
+                input_schema_str = str(input_schema) # @todo convert input tool.args_schema
+                tool_schema = XGAToolSchema(tool_name=tool.name,
+                                            server_name=server_name,
+                                            description=tool.description,
+                                            input_schema=input_schema_str)
+                self.mcp_tool_schemas[server_name].append(tool_schema)
+
+    @staticmethod
+    def _load_mcp_servers_config(mcp_config_path: str) -> Dict[str, Any]:
+        try:
+            if os.path.exists(mcp_config_path):
+                with open(mcp_config_path, 'r', encoding='utf-8') as f:
+                    server_config = json.load(f)
+
+                    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"
+                            else:
+                                server_info["transport"] = "stdio"
+
+                    return server_config
+            else:
+                logging.warning("MCP servers config file not found at: %s", mcp_config_path)
+                return {"mcpServers": {}}
+
+        except Exception as e:
+            logging.error("Failed to load MCP servers config: %s", str(e))
+            return {"mcpServers": {}}
+
+
+if __name__ == "__main__":
+    import asyncio
+    from dataclasses import asdict
+    async def main():
+        task_id = "task1"
+        mcp_tool_box = XGAMcpToolBox(custom_mcp_server_file="mcpservers/custom_servers.json")
+        #mcp_tool_box = XGAMcpToolBox()
+        await mcp_tool_box.load_mcp_tools_schema()
+        await mcp_tool_box.creat_task_tool_box(task_id=task_id, general_tools=["*"], custom_tools=["bomc_fault.*"])
+        tool_schemas = mcp_tool_box.get_task_tool_schemas(task_id, "general_tool")
+        print("general_tools_schemas" + "*"*50)
+        for tool_schema in tool_schemas:
+            print(asdict(tool_schema))
+        print()
+
+        tool_schemas = mcp_tool_box.get_task_tool_schemas(task_id, "custom_tool")
+        print("custom_tools_schemas" + "*" * 50)
+        for tool_schema in tool_schemas:
+            print(asdict(tool_schema))
+        print()
+
+        result = await mcp_tool_box.call_tool(task_id=task_id, tool_name="web_search", args={"task_id": task_id, "query": "查询天津天气"})
+        print(f"call web_search result: {result}")
+
+        result = await mcp_tool_box.call_tool(task_id=task_id, tool_name="complete", args={"task_id": task_id})
+        print(f"call complete result: {result}")
+
+        await mcp_tool_box.destroy_task_tool_box(task_id)
+    asyncio.run(main())

xgae/engine/xga_prompt_builder.py

@@ -0,0 +1,38 @@
+import datetime
+
+from typing import Optional, List
+
+from xga_base import XGAToolSchema
+from xgae.utils.setup_env import read_file, XGAError
+
+
+class XGAPromptBuilder():
+    def __init__(self,
+                 prompt_template: Optional[str] = None,
+                 prompt_template_file: Optional[str] = None):
+        self.system_prompt_template = None
+        if prompt_template:
+            self.system_prompt_template = prompt_template
+        elif prompt_template_file:
+            self.system_prompt_template = read_file(prompt_template_file)
+        else:
+            _system_prompt_template = read_file("templates/system_prompt_template.txt")
+            self.system_prompt_template = _system_prompt_template.format(
+                current_date=datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%d'),
+                current_time=datetime.datetime.now(datetime.timezone.utc).strftime('%H:%M:%S'),
+                current_year=datetime.datetime.now(datetime.timezone.utc).strftime('%Y')
+            )
+
+
+    def build_system_prompt(self, model_name:str, prompt_template: Optional[str]=None)-> str:
+        system_prompt = prompt_template if prompt_template else self.system_prompt_template
+
+        return system_prompt
+
+
+    def build_general_tool_prompt(self, model_name:str, prompt_template: str, tool_schemas:List[XGAToolSchema])-> str:
+        pass
+
+
+    def build_custom_tool_prompt(self, model_name:str, prompt_template: str, tool_schemas:List[XGAToolSchema])-> str:
+        pass

xgae/utils/llm_client.py

@@ -0,0 +1,239 @@
+import asyncio
+import json
+import logging
+import os
+import litellm
+
+from typing import Union, Dict, Any, Optional, List
+
+from litellm.utils import ModelResponse, CustomStreamWrapper
+from openai import OpenAIError
+
+from setup_env import setup_xga_env
+
+
+class LLMError(Exception):
+    """Base exception for LLM-related errors."""
+    pass
+
+class LLMClient:
+    RATE_LIMIT_DELAY = 30
+    RETRY_DELAY = 0.1
+
+    def __init__(self, llm_config: Optional[Dict[str, Any]]={}) -> None:
+        """
+        Arg: llm_config (Optional[Dict[str, Any]], optional)
+            model: Override default model to use, default set by .env LLM_MODEL
+            model_name: Optional Name of the model to use , use model if empty
+            model_id: Optional ARN for Bedrock inference profiles, default is None
+            api_key: Optional  API key, Override .env LLM_API_KEY or OS environment variable
+            api_base: Optional API base URL, Override .env LLM_API_BASE
+            temperature: Optional Sampling temperature (0-1), Override .env LLM_TEMPERATURE
+            max_tokens: Optional Maximum tokens in the response, Override .env LLM_MAX_TOKENS
+            stream: Optional whether to stream the response, default is True
+            response_format: Optional desired format for the response, default is  None
+            enable_thinking: Optional whether to enable thinking, default is  False
+            reasoning_effort: Optional level of reasoning effort, default is  ‘low’
+            top_p: Optional Top-p sampling parameter, default is None
+        """
+        litellm.modify_params = True
+        litellm.drop_params = True
+
+        self.max_retries = int(os.getenv("LLM_MAX_RETRIES", 1))
+
+        env_llm_model = os.getenv("LLM_MODEL", "openai/qwen3-235b-a22b")
+        env_llm_api_key = os.getenv("LLM_API_KEY")
+        env_llm_api_base = os.getenv("LLM_API_BASE", "https://dashscope.aliyuncs.com/compatible-mode/v1")
+        env_llm_max_tokens = int(os.getenv("LLM_MAX_TOKENS", 16384))
+        env_llm_temperature = float(os.getenv("LLM_TEMPERATURE", 0.7))
+
+        llm_config_params = {
+            "model":            llm_config.get("model", env_llm_model),
+            "model_name":       llm_config.get("model_name", env_llm_model),
+            "model_id":         llm_config.get("model_id", None),
+            "api_key":          llm_config.get("api_key", env_llm_api_key),
+            "api_base":         llm_config.get("api_base", env_llm_api_base),
+            "temperature":      llm_config.get("temperature", env_llm_temperature),
+            "max_tokens":       llm_config.get("max_tokens", env_llm_max_tokens),
+            "stream":           llm_config.get("stream", True),
+            "enable_thinking":  llm_config.get("enable_thinking", False),
+            "reasoning_effort": llm_config.get("reasoning_effort", 'low'),
+            "response_format":  llm_config.get("response_format", None),
+            "top_p":            llm_config.get("top_p", None),
+            "tools":            None,
+            "tool_choice":      "none",
+        }
+
+        self.model_name = llm_config_params["model_name"]
+        self.is_stream = llm_config_params['stream']
+
+        self.lite_llm_params = self._prepare_llm_params(llm_config_params)
+        logging.info(f"📡 LLMClient initialed : model={self.model_name}, is_stream={self.is_stream}, enable thinking={self.lite_llm_params['enable_thinking']}")
+
+
+    def _prepare_llm_params(self, llm_config_params: Dict[str, Any]) -> Dict[str, Any]:
+        prepared_llm_params = llm_config_params.copy()
+
+        model_name = llm_config_params.get("model_name")
+        max_tokens = llm_config_params.get("max_tokens")
+        model_id = llm_config_params.get("model_id")
+
+        # Handle token limits
+        if max_tokens is not None:
+            # For Claude 3.7 in Bedrock, do not set max_tokens or max_tokens_to_sample
+            # as it causes errors with inference profiles
+            if model_name.startswith("bedrock/") and "claude-3-7" in model_name:
+                prepared_llm_params.pop("max_tokens")
+                logging.debug(f"prepare_llm_params: Remove 'max_tokens' param for model: {model_name}")
+            else:
+                is_openai_o_series = 'o1' in model_name
+                is_openai_gpt5 = 'gpt-5' in model_name
+                param_name = "max_completion_tokens" if (is_openai_o_series or is_openai_gpt5) else "max_tokens"
+                if param_name == "max_completion_tokens":
+                    prepared_llm_params[param_name] = max_tokens
+                    logging.debug(f"prepare_llm_params: Add 'max_completion_tokens' param for model: {model_name}")
+
+        # # Add Claude-specific headers
+        if "claude" in model_name.lower() or "anthropic" in model_name.lower():
+            prepared_llm_params["extra_headers"] = {
+                "anthropic-beta": "output-128k-2025-02-19"
+            }
+            logging.debug(f"prepare_llm_params: Add 'extra_headers' param for model: {model_name}")
+
+        # Add Bedrock-specific parameters
+        if model_name.startswith("bedrock/"):
+            if not model_id and "anthropic.claude-3-7-sonnet" in model_name:
+                prepared_llm_params["model_id"] = "arn:aws:bedrock:us-west-2:935064898258:inference-profile/us.anthropic.claude-3-7-sonnet-20250219-v1:0"
+                logging.debug(f"prepare_llm_params: Must Set 'model_id' param for model: {model_name}")
+
+        # Apply Anthropic prompt caching (minimal implementation)
+        effective_model_name = llm_config_params.get("model", model_name)
+
+        # OpenAI GPT-5: drop unsupported temperature param (only default 1 allowed)
+        if "gpt-5" in effective_model_name and "temperature" in llm_config_params and llm_config_params["temperature"] != 1:
+            prepared_llm_params.pop("temperature", None)
+            logging.debug(f"prepare_llm_params: Remove 'temperature' param for model: {model_name}")
+
+        # OpenAI GPT-5: request priority service tier when calling OpenAI directly
+        # Pass via both top-level and extra_body for LiteLLM compatibility
+        if "gpt-5" in effective_model_name and not effective_model_name.startswith("openrouter/"):
+            prepared_llm_params["service_tier"] = "priority"
+            prepared_llm_params["extra_body"] = {"service_tier": "priority"}
+            logging.debug(f"prepare_llm_params: Add 'service_tier' and 'extra_body' param for model: {model_name}")
+
+        # Add reasoning_effort for Anthropic models if enabled
+        enable_thinking = llm_config_params.get("enable_thinking")
+        use_thinking = enable_thinking if enable_thinking is not None else False
+
+        is_anthropic = "anthropic" in effective_model_name.lower() or "claude" in effective_model_name.lower()
+        is_kimi_k2 = "kimi-k2" in effective_model_name.lower() or model_name.startswith("moonshotai/kimi-k2")
+
+        if is_kimi_k2:
+            prepared_llm_params["provider"] = {
+                "order": ["together/fp8", "novita/fp8", "baseten/fp8", "moonshotai", "groq"]
+            }
+            logging.debug(f"prepare_llm_params: Add 'provider' param for model: {model_name}")
+
+        reasoning_effort = llm_config_params.get("reasoning_effort")
+        if is_anthropic and use_thinking:
+            effort_level = reasoning_effort if reasoning_effort else 'low'
+            prepared_llm_params["reasoning_effort"] = effort_level
+            prepared_llm_params["temperature"] = 1.0  # Required by Anthropic when reasoning_effort is used
+            logging.debug(f"prepare_llm_params: Set 'temperature'=1.0 param for model: {model_name}")
+
+        return prepared_llm_params
+
+
+    def _prepare_complete_params(self, messages: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """Prepare parameters for the API call."""
+        complete_params = self.lite_llm_params.copy()
+        complete_params["messages"] = messages
+
+        model_name = self.lite_llm_params["model_name"]
+        effective_model_name = complete_params.get("model", model_name)
+
+        # Apply cache control to the first 4 text blocks across all messages , for anthropic and claude model
+        if "claude" in effective_model_name.lower() or "anthropic" in effective_model_name.lower():
+            messages = complete_params["messages"]
+
+            if not isinstance(messages, list):
+                return complete_params
+
+            cache_control_count = 0
+            max_cache_control_blocks = 3
+
+            for message in messages:
+                if cache_control_count >= max_cache_control_blocks:
+                    break
+
+                content = message.get("content")
+
+                if isinstance(content, str):
+                    message["content"] = [
+                        {"type": "text", "text": content, "cache_control": {"type": "ephemeral"}}
+                    ]
+                    cache_control_count += 1
+                    logging.debug(f"prepare_complete_params: Add 'cache_control' in message content, for model: {model_name}")
+                elif isinstance(content, list):
+                    for item in content:
+                        if cache_control_count >= max_cache_control_blocks:
+                            break
+                        if isinstance(item, dict) and item.get("type") == "text" and "cache_control" not in item:
+                            item["cache_control"] = {"type": "ephemeral"}
+                            cache_control_count += 1
+                            logging.debug(f"prepare_complete_params: Add 'cache_control' in message content list, for model: {model_name}")
+
+        return complete_params
+
+    async def _handle_llm_error(self, error: Exception, attempt: int) -> None:
+        """Handle API errors with appropriate delays and logging."""
+        if (attempt + 1) < self.max_retries:
+            delay = LLMClient.RATE_LIMIT_DELAY if isinstance(error, litellm.exceptions.RateLimitError) else LLMClient.RETRY_DELAY
+            logging.warning(f"LLMClient: Error on llm completion, retry={attempt + 1}/{self.max_retries}: {error}")
+            logging.debug(f"LLMClient: Waiting {delay} seconds before retry llm completion...")
+            await asyncio.sleep(delay)
+
+
+    async def create_completion(self, messages: List[Dict[str, Any]]) -> Union[ModelResponse, CustomStreamWrapper]:
+        complete_params = self._prepare_complete_params(messages)
+
+        last_error = None
+        for attempt in range(self.max_retries):
+            try:
+                logging.info(f"*** create_completion ***: LLM '{self.model_name}' completion attempt {attempt + 1}/{self.max_retries}")
+                response = await litellm.acompletion(**complete_params)
+                return response
+            except (litellm.exceptions.RateLimitError, OpenAIError, json.JSONDecodeError) as e:
+                last_error = e
+                await self._handle_llm_error(e, attempt)
+            except Exception as e:
+                logging.error(f"create_completion: Unexpected error during LLM completion: {str(e)}", exc_info=True)
+                raise LLMError(f"LLM completion failed: {e}")
+
+        logging.error(f"create_completion: LLM completion failed after {self.max_retries} attempts: {last_error}", exc_info=True)
+        raise LLMError(f"LLM completion failed after {self.max_retries} attempts !")
+
+if __name__ == "__main__":
+    setup_xga_env()
+
+    async def llm_completion():
+        llm_client = LLMClient({
+            "stream": False #default is True
+        })
+        messages = [{"role": "user", "content": "今天是2025年8月15日，北京本周每天温度"}]
+        response = await llm_client.create_completion(messages)
+        if llm_client.is_stream:
+            async for chunk in response:
+                choices = chunk.get("choices", [{}])
+                if not choices:
+                    continue
+                delta = choices[0].get("delta", {})
+                content = delta.get("content", "")
+                if content:
+                    print(content, end="", flush=True)
+        else:
+            print(response.choices[0].message.content)
+
+    asyncio.run(llm_completion())
+
+

xgae/utils/setup_env.py

@@ -0,0 +1,108 @@
+import logging
+import os
+import traceback
+
+from langfuse import Langfuse
+
+
+class XGAError(Exception):
+    """Custom exception for errors in the XGA system."""
+    pass
+
+langfuse: Langfuse = None
+
+def setup_langfuse() -> None:
+    env_public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+    env_secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+    env_host = os.getenv("LANGFUSE_HOST", "https://cloud.langfuse.com")
+    global langfuse
+    if env_public_key and env_secret_key:
+        langfuse = Langfuse(tracing_enabled=True,
+                            public_key=env_public_key,
+                            secret_key=env_secret_key,
+                            host=env_host)
+        logging.info("utils.setup_langfuse: Langfuse initialized!")
+    else:
+        langfuse = Langfuse(tracing_enabled=False)
+        logging.warning("utils.setup_langfuse: Langfuse is disabled!")
+
+def setup_logging() -> None:
+    env_log_level = os.getenv("LOG_LEVEL", "INFO")
+    env_log_file = os.getenv("LOG_FILE", "log/xga.log")
+    log_level = getattr(logging, env_log_level.upper(), logging.INFO)
+
+    log_dir = os.path.dirname(env_log_file)
+    if log_dir and not os.path.exists(log_dir):
+        os.makedirs(log_dir, exist_ok=True)
+    else:
+        os.remove(env_log_file)
+
+    logger = logging.getLogger()
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    import colorlog
+
+    log_colors = {
+        'DEBUG': 'cyan',
+        'INFO': 'green',
+        'WARNING': 'yellow',
+        'ERROR': 'red',
+        'CRITICAL': 'red,bg_white'
+    }
+
+    console_formatter = colorlog.ColoredFormatter('%(log_color)s%(asctime)s - %(levelname)-8s%(reset)s %(white)s%(message)s',
+        log_colors=log_colors,
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+
+    file_formatter = logging.Formatter(
+        '%(asctime)s -%(levelname)-8s  %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    )
+
+    console_handler = logging.StreamHandler()
+    console_handler.setFormatter(console_formatter)
+
+    file_handler = logging.FileHandler(env_log_file, encoding='utf-8')
+    file_handler.setFormatter(file_formatter)
+
+    logger.addHandler(console_handler)
+    logger.addHandler(file_handler)
+
+    logger.setLevel(log_level)
+
+    logging.info(f"Logger is initialized, log_level={env_log_level}, log_file={env_log_file}")
+
+
+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
+
+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)
+
+def setup_xga_env() -> None:
+    from dotenv import load_dotenv
+    load_dotenv()
+    setup_logging()
+    setup_langfuse()
+
+if __name__ == "__main__":
+    try:
+        setup_xga_env()
+        trace_id = langfuse.create_trace_id()
+        print(f"trace_id={trace_id}")
+    except Exception as e:
+        handle_error(e)

xgae-0.1.1.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: xgae
+Version: 0.1.1
+Summary: Extreme General Agent Engine
+Requires-Python: >=3.13
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: langchain-mcp-adapters>=0.1.4
+Requires-Dist: langfuse>=2.60.5
+Requires-Dist: langgraph>=0.3.21
+Requires-Dist: litellm>=1.74.8
+Requires-Dist: mcp>=1.12.1

xgae-0.1.1.dist-info/RECORD

@@ -0,0 +1,13 @@
+xgae/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+xgae/engine/xga_base.py,sha256=ZuOVD5mLnfi8rTnDspY8qfEgwefVTTYgf6eY3B_001s,1213
+xgae/engine/xga_engine.py,sha256=3U0F3_ISu5K1CGYhn0RZsIaZkm4OQIrMTIf3N22M7bE,3013
+xgae/engine/xga_mcp_tool_box.py,sha256=3L48c-Wl8QghbudUsZdYemOzEHoOGF0QC-sAh0H1PVI,9047
+xgae/engine/xga_prompt_builder.py,sha256=wPCB6g0QNpKDuvWs5Ix_Z8-OoCFjxqApodb-g-qZrbM,1503
+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=bsdWLTXRDDpiuEn72a5BuT4FYomE1LjY-thQHbTQ_Fg,12167
+xgae/utils/setup_env.py,sha256=nJHllWuM9kLs_mJg_-j3Lhj8FHtyFjK4CIoDY_SHOxk,3253
+xgae-0.1.1.dist-info/METADATA,sha256=_j2ZiXzJZa-sw_fk7P0sHkKiyYus_ncxoL9YoZEv4iQ,309
+xgae-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+xgae-0.1.1.dist-info/RECORD,,

xgae-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any