matrix-for-agents 0.1.2__py3-none-any.whl

agentmatrix/backends/llm_client.py

@@ -0,0 +1,414 @@
+import requests
+import json
+import traceback
+from typing import Dict, Union, List
+import aiohttp
+from ..core.log_util import AutoLoggerMixin
+import logging
+
+class LLMClient(AutoLoggerMixin):
+
+    _custom_log_level = logging.DEBUG
+    def __init__(self, url: str, api_key: str,model_name: str):
+        """
+        初始化LLM客户端
+        
+        Args:
+            url (str): 大模型API的URL
+            api_key (str): API密钥
+        """
+        self.url = url
+        self.api_key = api_key
+        self.model_name = model_name
+        self.headers = {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json"
+        }
+        self.gemini_headers = {
+            "Content-Type": "application/json",
+            "x-goog-api-key": self.api_key
+        }
+
+
+    async def think(self, messages:  Union[str, List[Dict[str, str]]], **kwargs) -> Dict[str, str]:
+        if isinstance(messages, str):
+            #如果messages 是string,就包装成open ai chat messages 的格式
+            messages =[{"role": "user", "content": messages}]
+        if "googleapis.com" in self.url or "gemini" in self.model_name.lower():
+            return await self._async_stream_think_gemini(messages, **kwargs)
+        return await self.async_stream_think(messages, **kwargs)
+    
+    def _to_gemini_messages(self, messages: list[dict[str, str]]) -> dict:
+        """
+        OpenAI 格式 -> Gemini 格式转换
+        """
+        gemini_contents = []
+        system_instruction = None
+
+        for msg in messages:
+            role = msg.get("role")
+            content = msg.get("content", "")
+            
+            if role == "system":
+                # Gemini system instruction 是顶层字段
+                system_instruction = {"parts": [{"text": content}]}
+            elif role == "user":
+                gemini_contents.append({"role": "user", "parts": [{"text": content}]})
+            elif role == "assistant":
+                gemini_contents.append({"role": "model", "parts": [{"text": content}]})
+        
+        return {
+            "contents": gemini_contents,
+            "systemInstruction": system_instruction
+        }
+
+    def _construct_gemini_config(self, **kwargs) -> dict:
+        """
+        构建符合官方规范的 generationConfig，处理 thinkingConfig 的嵌套
+        """
+        config = {}
+        
+        # 提取 Thinking 相关的参数并封装
+        thinking_config = {}
+        if "thinking_level" in kwargs:
+            thinking_config["thinkingLevel"] = kwargs.pop("thinking_level")
+        if "include_thoughts" in kwargs:
+            thinking_config["includeThoughts"] = kwargs.pop("include_thoughts")
+            
+        # 其他常见参数映射 (OpenAI命名 -> Gemini命名)
+        if "max_tokens" in kwargs:
+            config["maxOutputTokens"] = kwargs.pop("max_tokens")
+        if "temperature" in kwargs:
+            config["temperature"] = kwargs.pop("temperature")
+        if "top_p" in kwargs:
+            config["topP"] = kwargs.pop("top_p")
+            
+        # 将剩余的 kwargs 也放入 config
+        config.update(kwargs)
+        
+        # 如果有 thinking 配置，按照官方格式嵌套
+        if thinking_config:
+            config["thinkingConfig"] = thinking_config
+            
+        return config
+
+    async def _async_stream_think_gemini(self, messages: list[dict[str, str]], **kwargs) -> Dict[str, str]:
+        """
+        Gemini 专用异步流式方法
+        """
+        try:
+            # 1. 消息格式转换
+            payload_parts = self._to_gemini_messages(messages)
+            
+            # 2. 构建 Request Body (匹配官方结构)
+            generation_config = self._construct_gemini_config(**kwargs)
+            
+            data = {
+                "contents": payload_parts["contents"],
+                "generationConfig": generation_config
+            }
+            
+            if payload_parts["systemInstruction"]:
+                data["systemInstruction"] = payload_parts["systemInstruction"]
+
+            # 3. 处理 Tools (如果 kwargs 里传了 tools，按照官方结构放入顶层)
+            # 注意：这里的实现假设 kwargs 里的 'tools' 已经是 Gemini 格式，或者你可以加转换逻辑
+            if "tools" in kwargs:
+                data["tools"] = kwargs.pop("tools")
+
+            final_content = ""
+            final_reasoning = ""
+
+            timeout = aiohttp.ClientTimeout(total=120)
+            
+            async with aiohttp.ClientSession(headers=self.gemini_headers, timeout=timeout, trust_env=True) as session:
+                async with session.post(self.url, json=data) as resp:
+                    if resp.status != 200:
+                        error_text = await resp.text()
+                        raise Exception(f"Gemini Error {resp.status}: {error_text}")
+                    
+                    # Gemini 流式解析 (JSON Array Stream)
+                    buffer = ""
+                    brace_count = 0
+                    in_string = False
+                    escape = False
+                    
+                    async for chunk in resp.content.iter_chunked(1024):
+                        if not chunk: continue
+                        text = chunk.decode("utf-8", errors="ignore")
+                        
+                        for char in text:
+                            # 简易 JSON 对象提取器
+                            if char == '[' and brace_count == 0: continue
+                            if char == ']' and brace_count == 0: continue
+                            if char == ',' and brace_count == 0: continue
+                            
+                            buffer += char
+                            
+                            if char == '"' and not escape: in_string = not in_string
+                            if char == '\\' and not escape: escape = True
+                            else: escape = False
+                            
+                            if not in_string:
+                                if char == '{': brace_count += 1
+                                elif char == '}': brace_count -= 1
+                                    
+                                if brace_count == 0 and buffer.strip():
+                                    try:
+                                        obj = json.loads(buffer)
+                                        # 解析 candidates
+                                        candidates = obj.get("candidates", [])
+                                        if candidates:
+                                            content_obj = candidates[0].get("content", {})
+                                            parts = content_obj.get("parts", [])
+                                            
+                                            # 遍历 parts (Gemini 可能在一个 chunk 返回多个 part)
+                                            for part in parts:
+                                                part_text = part.get("text", "")
+                                                
+                                                # 尝试识别 Reasoning/Thought
+                                                # 目前 Gemini API 尚未统一 "thought" 字段，
+                                                # 但如果官方将来在 part 里加了 "thought": true，可以在这里捕获
+                                                is_thought = part.get("thought", False) 
+                                                
+                                                if is_thought:
+                                                    final_reasoning += part_text
+                                                else:
+                                                    final_content += part_text
+
+                                    except json.JSONDecodeError:
+                                        pass
+                                    finally:
+                                        buffer = ""
+
+            return {
+                "reasoning": final_reasoning,
+                "reply": final_content
+            }
+
+        except Exception as e:
+            self.logger.exception("Gemini调用失败")
+            raise Exception(f"Gemini调用失败: {str(e)}")
+
+    def no_stream_think(self, messages: list[dict[str, str]], **kwargs) -> Dict[str, str]:
+        """
+        调用大模型API
+        
+        Args:
+            messages (list[dict[str, str]]): 对话消息列表，每个消息包含role和content字段
+            **kwargs: 其他可选参数
+            
+        Returns:
+            Dict[str, str]: 包含reasoning_content和content的字典
+            
+        Raises:
+            Exception: 当API调用失败时抛出异常
+        """
+        try:
+            # 构建请求数据
+            data = {
+                "messages": messages,
+                "model": self.model_name,
+                "stream": False,
+                **kwargs
+            }
+            
+            # 发送请求
+            response = requests.post(
+                self.url,
+                headers=self.headers,
+                json=data,
+                timeout=30
+            )
+            
+            # 检查响应状态
+            response.raise_for_status()
+            
+            # 解析响应
+            result = response.json()
+            
+            # 提取所需内容
+            return {
+                "reasoning_content": result.get("reasoning_content", ""),
+                "content": result.get("content", "")
+            }
+            
+        except requests.exceptions.RequestException as e:
+            raise Exception(f"API请求失败: {str(e)}")
+        except json.JSONDecodeError:
+            raise Exception("API响应解析失败")
+        except KeyError as e:
+            raise Exception(f"API响应格式错误，缺少必要字段: {str(e)}")
+        except Exception as e:
+            self.logger.exception("未知错误")
+            self.logger.debug(messages)
+            raise Exception(f"未知错误: {str(e)}")
+
+    def stream_think(self, messages: list[dict[str, str]], **kwargs) -> Dict[str, str]:
+        """
+        流式调用大模型API，实时打印响应内容
+        
+        Args:
+            messages (list[dict[str, str]]): 对话消息列表，每个消息包含role和content字段
+            **kwargs: 其他可选参数
+            
+        Returns:
+            Dict[str, str]: 包含reasoning_content和content的字典
+            
+        Raises:
+            Exception: 当API调用失败时抛出异常
+        """
+        try:
+            # 构建请求数据
+            data = {
+                "messages": messages,
+                "model": self.model_name,
+                "stream": True
+            }
+            
+            # 初始化响应内容
+            final_reasoning_content = ""
+            final_content = ""
+            #print(self.url)
+            #print(self.headers)
+            # 发送流式请求
+            response = requests.post(
+                self.url,
+                headers=self.headers,
+                json=data,
+                stream=True,
+                timeout=120
+            )
+            think_started = False
+            content_started= False
+            buffer = ""
+            for chunk in response.iter_content(decode_unicode=True):
+                if chunk:
+                    buffer += chunk
+                    lines = buffer.split('\n')
+                    buffer = lines[-1]  # Keep incomplete line in buffer
+                    
+                    for line in lines[:-1]:
+                        if line.strip():
+                            try:
+                                # Parse SSE data
+                                if line.startswith('data: '):
+                                    data_str = line[6:]  # Remove "data: " prefix
+                                    if data_str.strip() == '[DONE]':
+                                        continue
+                                    elif data_str.strip():
+                                        try:
+                                            data = json.loads(data_str)
+                                            if 'choices' in data and data['choices']:
+                                                delta = data['choices'][0].get('delta', {})
+
+                                                # Handle think mode streaming
+                                                reasoning_content = delta.get('reasoning_content', '')
+                                                content = delta.get('content', '')
+
+                                                if reasoning_content:
+                                                    if not think_started:
+                                                        print("Reasoning: ")
+                                                        think_started = True
+                                                    print(reasoning_content, end='', flush=True)
+                                                    final_reasoning_content += reasoning_content
+                                                if content:
+                                                    if not content_started:
+                                                        print("Content: ")
+                                                        content_started = True
+                                                    print(content, end='', flush=True)
+                                                    final_content += content
+                                        except json.JSONDecodeError:
+                                            continue
+                            except:
+                                continue
+            
+           
+            
+            
+            
+            
+            return {
+                "reasoning": final_reasoning_content,
+                "reply": final_content
+            }
+            
+        except requests.exceptions.RequestException as e:
+            traceback.print_exc()
+            raise Exception(f"API请求失败: {str(e)}")
+            
+        except Exception as e:
+            traceback.print_exc()
+            raise Exception(f"未知错误: {str(e)}")
+
+
+    async def async_stream_think(self, messages: list[dict[str, str]], **kwargs) -> Dict[str, str]:
+        """
+        异步流式调用大模型API，实时打印响应内容（使用 aiohttp）
+        """
+        
+        try:
+            data = {
+                "messages": messages,
+                "model": self.model_name,
+                "stream": True,
+                **kwargs
+            }
+
+            final_reasoning_content = ""
+            final_content = ""
+            
+            buffer = ""
+
+            timeout = aiohttp.ClientTimeout(total=120)
+            async with aiohttp.ClientSession(headers=self.headers, timeout=timeout, trust_env=True) as session:
+                async with session.post(self.url, json=data) as resp:
+                    if resp.status != 200:
+                        error_text = await resp.text()
+                        raise Exception(f"API请求失败: {resp.status}, message='{error_text}', url='{self.url}'")
+                    resp.raise_for_status()
+                    async for chunk in resp.content.iter_chunked(1024):
+                        if not chunk:
+                            continue
+                        text = chunk.decode("utf-8", errors="ignore")
+                        buffer += text
+                        lines = buffer.split("\n")
+                        buffer = lines[-1]  # 不完整行保留在 buffer
+                        for line in lines[:-1]:
+                            line = line.strip()
+                            if not line:
+                                continue
+                            if line.startswith("data: "):
+                                data_str = line[6:].strip()
+                                if data_str == "[DONE]":
+                                    continue
+                                try:
+                                    payload = json.loads(data_str)
+                                except json.JSONDecodeError:
+                                    continue
+
+                                if "choices" in payload and payload["choices"]:
+                                    delta = payload["choices"][0].get("delta", {})
+                                    reasoning_content = delta.get("reasoning_content", "")
+                                    content = delta.get("content", "")
+
+                                    if reasoning_content:
+                                        final_reasoning_content += reasoning_content
+
+                                    if content:
+                                        final_content += content
+
+            #print()  # 确保换行
+            return {
+                "reasoning": final_reasoning_content,
+                "reply": final_content
+            }
+
+        except aiohttp.ClientError as e:
+            traceback.print_exc()
+            raise Exception(f"API请求失败: {str(e)}")
+        except Exception as e:
+            traceback.print_exc()
+            raise Exception(f"未知错误: {str(e)}")
+
+

agentmatrix/backends/mock_llm.py

@@ -0,0 +1,35 @@
+import asyncio
+import json
+
+class MockLLM:
+    """模拟 LLM，根据输入关键词决定输出，方便测试流程"""
+    
+    async def chat(self, role: str, history: list) -> str:
+        await asyncio.sleep(1.0) # 模拟思考时间
+        
+        last_msg = history[-1]["content"].lower()
+        
+        # === 模拟 Planner 的逻辑 ===
+        if role == "Planner":
+            if "start_task" in last_msg:
+                # 收到用户新任务 -> 派活给 Coder
+                return "[Action: EMAIL] To: Coder | Subject: Task | Body: 请帮我读取 data.csv 并分析数据。"
+            elif "done" in last_msg:
+                # 收到 Coder 回复 -> 汇报给 User
+                return "[Action: REPLY] 任务已完成，数据分析结果如下..."
+
+        # === 模拟 Coder 的逻辑 ===
+        elif role == "Coder":
+            if "读取" in last_msg and "secretary" not in last_msg:
+                # 收到任务，发现需要读文件 -> 问秘书
+                return "[Action: EMAIL] To: Secretary | Subject: Help | Body: 请帮我读取文件 data.csv"
+            elif "file_content" in last_msg:
+                # 收到秘书回信 -> 完成任务
+                return "[Action: REPLY] 我已读取文件，分析完毕，结果是 Done。"
+                
+        # === 模拟 Secretary (SLM) 的逻辑 ===
+        elif role == "Secretary":
+            if "读取文件" in last_msg:
+                return json.dumps({"tool": "read_file", "args": {"path": "data.csv"}})
+            
+        return "[Action: REPLY] I am thinking..."

agentmatrix/cli_runner.py

@@ -0,0 +1,94 @@
+# cli_runner.py
+import asyncio
+from agentmatrix import AgentMatrix
+from agentmatrix import Email
+import logging
+import uuid
+logger = logging.getLogger('CLI_Runner')
+# 1. 定义：收到信时干什么？-> 打印出来
+
+mail_id_sender_map = {}  # 记录邮件 ID 到发送者的映射
+
+async def print_to_console(email: Email):
+    f = f"""
+    📨 [New Mail] From {email.sender}: "
+        Subject: {email.subject}"
+        Body: {email.body}"
+        MsgID: {email.id}
+        >> 请输入回复 (格式: To_Agent: Content) 或 'exit':"
+    """
+    mail_id_sender_map[email.id] = email.sender  # 记录映射
+    loop = asyncio.get_running_loop()
+
+    await loop.run_in_executor(None, logger.debug, f)
+
+
+def global_event_handler(event):
+    print(f"🔔 事件触发: {event}")
+
+async def main():
+    # 2. 初始化 Matrix
+    matrix = AgentMatrix(agent_profile_path="./profiles", matrix_path='../../Samples/TestWorkspace', async_event_call_back=global_event_handler)
+    #matrix.load_matrix('Samples/TestWorkspace')
+    
+    # 3. 挂载回调：把我们的打印函数挂给 UserProxy
+    matrix.agents["User"].on_mail_received = print_to_console
+    
+    await asyncio.to_thread(print, ">>> 系统启动。可以在下面输入指令。")
+    await asyncio.to_thread(print, ">>> 例如: Planner: 帮我分析数据")
+    
+    # 4. 主循环：监听键盘输入 (这是在主线程，不会阻塞 Matrix 的后台 asyncio)
+    # 注意：在 asyncio 程序里做 input() 是个 tricky 的事情，
+    # 生产环境通常用 aioconsole，这里为了演示简单处理
+    
+    loop = asyncio.get_event_loop()
+    
+    import sys
+    from aioconsole import ainput # pip install aioconsole
+    user_session_id = str(uuid.uuid4())
+    while True:
+        try:
+            user_input = await ainput(">> ") # 异步等待输入
+            
+            if user_input.lower() == "exit":
+                await matrix.save_matrix()
+                break
+
+            if user_input.lower() == "new session":
+                user_session_id = str(uuid.uuid4())
+                await asyncio.to_thread(print, f"✅ 新会话开始 ID: {user_session_id}")
+                continue
+
+            if user_input.lower().startswith("reply:"):
+                parts = user_input.split(":")
+                if len(parts) < 3:
+                    await asyncio.to_thread(print, "❌ 回复格式错误，请使用 'reply: MsgID: Content'")
+                    continue
+                reply_to_id = parts[1].strip()
+                content = ":".join(parts[2:]).strip()
+                if reply_to_id not in mail_id_sender_map:
+                    await asyncio.to_thread(print, f"❌ 未找到消息 ID: {reply_to_id}")
+                    continue
+                target = mail_id_sender_map[reply_to_id]
+                await matrix.agents["User"].speak(
+                    user_session_id=user_session_id,
+                    to=target,
+                    subject=f"Re: 回复您的消息 {reply_to_id}",
+                    content=content,
+                    reply_to_id=reply_to_id
+                )
+                continue
+
+                
+            if ":" in user_input:
+                target, content = user_input.split(":", 1)
+                # 5. 调用 UserProxy 说话
+                await matrix.agents["User"].speak(user_session_id, target.strip(), content.strip())
+            else:
+                await asyncio.to_thread(print,"❌ 格式错误，请使用 'Target: Content'")
+                
+        except KeyboardInterrupt:
+            break
+
+if __name__ == "__main__":
+    asyncio.run(main())

agentmatrix/core/action.py

@@ -0,0 +1,50 @@
+from enum import Enum
+from dataclasses import dataclass
+from typing import Any, Dict
+import json
+
+
+
+@dataclass
+class ActionMetadata:
+    name: str
+    description: str    
+    # 存储生成的 JSON Schema，给 SLM 看
+    json_schema: Dict[str, Any] 
+
+def register_action(
+    description: str, 
+    param_infos: Dict[str, str] = None 
+):
+    """
+    Args:
+        description: 函数功能的自然语言描述
+        type: 动作流类型
+        param_infos: 参数名 -> 参数含义的映射 (e.g. {"to": "目标Agent名字"})
+    """
+    if param_infos is None:
+        param_infos = {}
+
+    def decorator(func):
+        func._is_action = True
+        func._action_desc = description
+        func._action_param_infos = param_infos
+        return func
+    return decorator
+
+@dataclass
+class ActionDef:
+    name: str
+    description: str
+    parameters: Dict[str, str]
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]):
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            parameters=data.get("parameters", {})
+        )
+
+    def to_prompt(self):
+        return f"- {self.name}: {self.description} | Params: {json.dumps(self.parameters, ensure_ascii=False)}"