sycommon-python-lib 0.2.0b25__tar.gz → 0.2.0b26__tar.gz

{sycommon_python_lib-0.2.0b25 → sycommon_python_lib-0.2.0b26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.0b25
+Version: 0.2.0b26
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -9,27 +9,27 @@ Requires-Dist: aiohttp>=3.13.3
 Requires-Dist: aiomysql>=0.3.2
 Requires-Dist: anyio>=4.12.1
 Requires-Dist: decorator>=5.2.1
-Requires-Dist: deepagents>=0.4.5
+Requires-Dist: deepagents>=0.4.11
 Requires-Dist: elasticsearch>=9.3.0
-Requires-Dist: fastapi>=0.133.1
+Requires-Dist: fastapi>=0.135.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: kafka-python>=2.3.0
-Requires-Dist: langchain>=1.2.10
-Requires-Dist: langchain-core>=1.2.16
-Requires-Dist: langchain-openai>=1.1.10
-Requires-Dist: langfuse>=3.14.5
-Requires-Dist: langgraph>=1.0.9
+Requires-Dist: langchain>=1.2.12
+Requires-Dist: langchain-core>=1.2.19
+Requires-Dist: langchain-openai>=1.1.11
+Requires-Dist: langfuse>=4.0.0
+Requires-Dist: langgraph>=1.1.2
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: mysql-connector-python>=9.6.0
 Requires-Dist: nacos-sdk-python<3.0,>=2.0.9
 Requires-Dist: psutil>=7.2.2
 Requires-Dist: pydantic>=2.12.5
-Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: python-dotenv>=1.2.2
 Requires-Dist: python-multipart>=0.0.22
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: redis>=7.3.0
-Requires-Dist: sentry-sdk[fastapi]>=2.53.0
-Requires-Dist: sqlalchemy[asyncio]>=2.0.47
+Requires-Dist: sentry-sdk[fastapi]>=2.54.0
+Requires-Dist: sqlalchemy[asyncio]>=2.0.48
 Requires-Dist: starlette>=0.52.1
 Requires-Dist: tiktoken>=0.12.0
 Requires-Dist: uvicorn>=0.41.0

{sycommon_python_lib-0.2.0b25 → sycommon_python_lib-0.2.0b26}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.0b25"
+version = "0.2.0b26"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,27 +10,27 @@ dependencies = [
     "aiomysql>=0.3.2",
     "anyio>=4.12.1",
     "decorator>=5.2.1",
-    "deepagents>=0.4.5",
+    "deepagents>=0.4.11",
     "elasticsearch>=9.3.0",
-    "fastapi>=0.133.1",
+    "fastapi>=0.135.1",
     "jinja2>=3.1.6",
     "kafka-python>=2.3.0",
-    "langchain>=1.2.10",
-    "langchain-core>=1.2.16",
-    "langchain-openai>=1.1.10",
-    "langfuse>=3.14.5",
-    "langgraph>=1.0.9",
+    "langchain>=1.2.12",
+    "langchain-core>=1.2.19",
+    "langchain-openai>=1.1.11",
+    "langfuse>=4.0.0",
+    "langgraph>=1.1.2",
     "loguru>=0.7.3",
     "mysql-connector-python>=9.6.0",
     "nacos-sdk-python>=2.0.9,<3.0",
     "psutil>=7.2.2",
     "pydantic>=2.12.5",
-    "python-dotenv>=1.2.1",
+    "python-dotenv>=1.2.2",
     "python-multipart>=0.0.22",
     "pyyaml>=6.0.3",
     "redis>=7.3.0",
-    "sentry-sdk[fastapi]>=2.53.0",
-    "sqlalchemy[asyncio]>=2.0.47",
+    "sentry-sdk[fastapi]>=2.54.0",
+    "sqlalchemy[asyncio]>=2.0.48",
     "starlette>=0.52.1",
     "tiktoken>=0.12.0",
     "uvicorn>=0.41.0",

sycommon_python_lib-0.2.0b26/src/sycommon/agent/__init__.py

@@ -0,0 +1,38 @@
+"""
+sycommon.agent - DeepAgents 便捷封装
+
+提供对 deepagents 的便捷调用，自动集成 get_llm 的 Token 统计和 Langfuse 追踪
+"""
+
+from sycommon.agent.exports import *
+
+__all__ = [
+    # 主要接口
+    "get_agent",
+    "create_tool_agent",
+    "create_multi_agent",
+    "create_structured_agent",
+    # deepagents 透传
+    "SubAgent",
+    "CompiledSubAgent",
+    "create_deep_agent",
+    "MemoryMiddleware",
+    "FilesystemMiddleware",
+    "SubAgentMiddleware",
+    # 虚拟员工系统
+    "VirtualEmployee",
+    "VirtualTeam",
+    "EmployeeFactory",
+    "Skill",
+    "SkillLevel",
+    "SubTeamMember",
+    "MemoryConfig",
+    "MemoryType",
+    "EmployeeMiddleware",
+    "LoggingEmployeeMiddleware",
+    "QuotaEmployeeMiddleware",
+    "PermissionEmployeeMiddleware",
+    # 技能系统中间件
+    "SkillsMiddleware",
+    "SkillMetadata",
+]

sycommon_python_lib-0.2.0b26/src/sycommon/agent/examples/virtual_employee_demo.py

@@ -0,0 +1,463 @@
+"""
+虚拟员工系统示例
+================
+
+展示如何使用 VirtualEmployee 封装创建业务级的虚拟员工。
+
+运行方式:
+    python -m sycommon.agent.examples.virtual_employee_demo
+"""
+import asyncio
+from typing import Optional
+from pydantic import BaseModel, Field
+from langchain_core.tools import tool
+from langchain_core.messages import HumanMessage
+
+from sycommon.agent import (
+    VirtualEmployee,
+    VirtualTeam,
+    EmployeeFactory,
+    Skill,
+    SkillLevel,
+    SubTeamMember,
+    MemoryConfig,
+    MemoryType,
+    LoggingEmployeeMiddleware,
+    QuotaEmployeeMiddleware,
+    PermissionEmployeeMiddleware,
+)
+
+
+# ========== 工具定义 ==========
+
+@tool
+def search_faq(keyword: str) -> str:
+    """搜索常见问题"""
+    faqs = {
+        "退货": "退货政策：购买后7天内可无理由退货",
+        "退款": "退款将在3-5个工作日内到账",
+        "配送": "配送时间：一线城市1-2天，其他地区3-5天"
+    }
+    for key, value in faqs.items():
+        if key in keyword:
+            return f"找到FAQ: {value}"
+    return f"未找到与 '{keyword}' 相关的FAQ"
+
+
+@tool
+def create_ticket(title: str, content: str) -> str:
+    """创建工单"""
+    return f"工单已创建: #{hash(title) % 10000} - {title}"
+
+
+@tool
+def search_web(query: str) -> str:
+    """搜索网络"""
+    return f"搜索结果: {query} 相关信息..."
+
+
+@tool
+def analyze_data(data: str) -> str:
+    """分析数据"""
+    return f"分析结果: {data}"
+
+
+# ========== 示例函数 ==========
+
+async def basic_employee():
+    """基础虚拟员工"""
+    print("=" * 60)
+    print("示例 1: 基础虚拟员工")
+    print("=" * 60)
+
+    # 创建一个简单的客服员工
+    employee = VirtualEmployee(
+        name="客服小美",
+        role="客户支持专员",
+        model="Qwen2.5-72B",
+        skills=[
+            Skill("faq", "回答常见问题", level=SkillLevel.INTERMEDIATE),
+            Skill("complaint", "处理客户投诉", level=SkillLevel.SENIOR),
+        ],
+        tools=[search_faq, create_ticket],
+        system_prompt="请用友好的语气回答客户问题。"
+    )
+
+    print(f"\n员工信息: {employee}")
+
+    # 执行任务
+    result = await employee.run("我想退货，怎么操作？")
+    print(f"\n用户: 我想退货，怎么操作？")
+    print(f"员工: {result}")
+
+
+async def employee_with_subteam():
+    """带内部小团队的员工"""
+    print("\n" + "=" * 60)
+    print("示例 2: 带内部小团队的经理员工")
+    print("=" * 60)
+
+    # 创建经理员工，带有内部小团队
+    manager = VirtualEmployee(
+        name="项目经理张三",
+        role="项目经理",
+        model="Qwen2.5-72B",
+        subteam=[
+            SubTeamMember(
+                name="研究员",
+                role="负责调研和分析",
+                system_prompt="你是研究员，负责收集和分析信息。"
+            ),
+            SubTeamMember(
+                name="执行员",
+                role="负责具体执行",
+                system_prompt="你是执行员，负责落实具体任务。"
+            )
+        ],
+        skills=[
+            Skill("coordination", "协调团队成员"),
+            Skill("planning", "制定工作计划")
+        ],
+        system_prompt="你需要协调内部小团队完成工作。"
+    )
+
+    result = await manager.run("帮我规划一个新产品发布方案")
+    print(f"\n用户: 帮我规划一个新产品发布方案")
+    print(f"经理: {result[:200]}...")
+
+
+async def employee_with_memory():
+    """带记忆的员工"""
+    print("\n" + "=" * 60)
+    print("示例 3: 带记忆的员工")
+    print("=" * 60)
+
+    employee = VirtualEmployee(
+        name="助手小明",
+        role="智能助手",
+        model="Qwen2.5-72B",
+        memory=MemoryConfig(
+            types=[MemoryType.CONVERSATION, MemoryType.EPISODIC],
+            max_history=50
+        ),
+        system_prompt="你需要记住用户的偏好和信息。"
+    )
+
+    thread_id = "user_001"
+
+    # 第一轮对话
+    print("\n--- 第一轮对话 ---")
+    result1 = await employee.run("我叫李华，我喜欢科技产品", thread_id=thread_id)
+    print(f"用户: 我叫李华，我喜欢科技产品")
+    print(f"员工: {result1}")
+
+    # 第二轮对话（有记忆）
+    print("\n--- 第二轮对话 ---")
+    result2 = await employee.run("你还记得我叫什么吗？我喜欢什么？", thread_id=thread_id)
+    print(f"用户: 你还记得我叫什么吗？我喜欢什么？")
+    print(f"员工: {result2}")
+
+
+async def employee_with_middleware():
+    """带中间件的员工"""
+    print("\n" + "=" * 60)
+    print("示例 4: 带中间件的员工")
+    print("=" * 60)
+
+    # 创建带日志和配额中间件的员工
+    logger = LoggingEmployeeMiddleware(verbose=True)
+    quota = QuotaEmployeeMiddleware(max_requests=5)
+
+    employee = VirtualEmployee(
+        name="受限助手",
+        role="有使用限制的助手",
+        model="Qwen2.5-72B",
+        middleware=[logger, quota]
+    )
+
+    # 执行几次任务
+    for i in range(2):
+        print(f"\n--- 请求 {i+1} ---")
+        result = await employee.run(f"问题{i+1}")
+        print(f"员工: {result[:100]}...")
+
+    print(f"\n剩余配额: {quota.remaining}")
+
+
+async def employee_with_permission():
+    """带权限控制的员工"""
+    print("\n" + "=" * 60)
+    print("示例 5: 带权限控制的员工")
+    print("=" * 60)
+
+    # 只允许读取操作
+    permission = PermissionEmployeeMiddleware(allowed_actions=["read"])
+
+    employee = VirtualEmployee(
+        name="只读助手",
+        role="只读权限的助手",
+        model="Qwen2.5-72B",
+        middleware=[permission]
+    )
+
+    # 读取操作（允许）
+    print("\n--- 读取操作 ---")
+    result = await employee.run("查看系统状态")
+    print(f"员工: {result[:100]}...")
+
+    # 删除操作（拒绝）
+    print("\n--- 删除操作 ---")
+    try:
+        await employee.run("删除所有数据")
+    except PermissionError as e:
+        print(f"权限错误: {e}")
+
+
+async def factory_employees():
+    """使用工厂创建员工"""
+    print("\n" + "=" * 60)
+    print("示例 6: 使用工厂创建员工")
+    print("=" * 60)
+
+    # 创建客服员工
+    support = EmployeeFactory.create_support_agent(
+        name="客服小红",
+        tools=[search_faq, create_ticket]
+    )
+    print(f"\n客服员工: {support}")
+
+    # 创建研究员工
+    researcher = EmployeeFactory.create_researcher(
+        name="研究员小张",
+        tools=[search_web, analyze_data]
+    )
+    print(f"研究员工: {researcher}")
+
+    # 创建写作员工
+    writer = EmployeeFactory.create_writer(name="写作专家小李")
+    print(f"写作员工: {writer}")
+
+    # 创建经理员工
+    manager = EmployeeFactory.create_manager(name="经理小王")
+    print(f"经理员工: {manager}")
+
+    # 测试研究员工
+    print("\n--- 研究员工工作 ---")
+    result = await researcher.run("研究一下人工智能的最新发展")
+    print(f"研究员: {result[:200]}...")
+
+
+async def chain_configuration():
+    """链式配置员工"""
+    print("\n" + "=" * 60)
+    print("示例 7: 链式配置员工")
+    print("=" * 60)
+
+    # 使用链式调用配置员工
+    employee = (
+        VirtualEmployee(
+            name="可配置助手",
+            role="灵活配置的助手",
+            model="Qwen2.5-72B"
+        )
+        .add_skill(Skill("chat", "日常对话"))
+        .add_skill(Skill("translate", "翻译服务"))
+        .add_tool(search_web)
+        .use_middleware(LoggingEmployeeMiddleware(verbose=True))
+    )
+
+    print(f"员工: {employee}")
+    print(f"技能数: {len(employee.skills)}")
+    print(f"工具数: {len(employee.tools)}")
+
+    result = await employee.run("你好")
+    print(f"\n员工: {result[:100]}...")
+
+
+async def virtual_team():
+    """虚拟团队"""
+    print("\n" + "=" * 60)
+    print("示例 8: 虚拟团队")
+    print("=" * 60)
+
+    # 创建多个员工
+    support = EmployeeFactory.create_support_agent(name="客服小美")
+    researcher = EmployeeFactory.create_researcher(name="研究员小张")
+    writer = EmployeeFactory.create_writer(name="写作专家小李")
+
+    # 组建团队
+    team = VirtualTeam(
+        name="智能服务团队",
+        employees=[support, researcher, writer],
+        coordinator=EmployeeFactory.create_manager(name="团队经理")
+    )
+
+    print(f"团队: {team}")
+
+    # 委派任务给特定员工
+    print("\n--- 委派任务给客服 ---")
+    result = await team.delegate("客服小美", "我想咨询退货问题")
+    print(f"客服小美: {result[:150]}...")
+
+    print("\n--- 委派任务给研究员 ---")
+    result = await team.delegate("研究员小张", "研究市场趋势")
+    print(f"研究员小张: {result[:150]}...")
+
+
+async def combined_example():
+    """综合示例"""
+    print("\n" + "=" * 60)
+    print("示例 9: 综合示例 - 完整的客服系统")
+    print("=" * 60)
+
+    # 创建带完整功能的客服员工
+    logger = LoggingEmployeeMiddleware(verbose=True)
+    quota = QuotaEmployeeMiddleware(max_requests=100)
+
+    support = VirtualEmployee(
+        name="高级客服专家",
+        role="高级客户支持专员",
+        model="Qwen2.5-72B",
+        skills=[
+            Skill("faq", "回答常见问题", level=SkillLevel.SENIOR,
+                  examples=["退货政策", "配送时间"]),
+            Skill("complaint", "处理客户投诉", level=SkillLevel.EXPERT,
+                  examples=["产品质量", "服务态度"]),
+            Skill("escalation", "问题升级处理", level=SkillLevel.EXPERT),
+        ],
+        tools=[search_faq, create_ticket],
+        subteam=[
+            SubTeamMember(name="技术支持", role="处理技术问题"),
+            SubTeamMember(name="售后专员", role="处理售后问题")
+        ],
+        memory=MemoryConfig(
+            types=[MemoryType.CONVERSATION],
+            max_history=100
+        ),
+        middleware=[logger, quota],
+        system_prompt="""你是一个专业、友好的高级客服专家。
+        你可以：
+        1. 直接回答常见问题
+        2. 处理客户投诉
+        3. 委派给技术支持或售后专员
+        4. 创建工单跟踪问题
+        """
+    )
+
+    # 模拟客户服务场景
+    thread_id = "customer_001"
+
+    print("\n--- 场景1: 咨询退货 ---")
+    result = await support.run("我买的东西不喜欢，可以退货吗？", thread_id=thread_id)
+    print(f"客户: 我买的东西不喜欢，可以退货吗？")
+    print(f"客服: {result}")
+
+    print("\n--- 场景2: 追问细节 ---")
+    result = await support.run("退货需要什么条件？", thread_id=thread_id)
+    print(f"客户: 退货需要什么条件？")
+    print(f"客服: {result}")
+
+    print(f"\n剩余配额: {quota.remaining}")
+    print(f"日志条数: {len(logger.logs)}")
+
+
+async def structured_output_example():
+    """结构化输出示例"""
+    print("\n" + "=" * 60)
+    print("示例 10: 结构化输出")
+    print("=" * 60)
+
+    # 定义输出格式
+    class AnalysisResult(BaseModel):
+        """分析结果结构"""
+        summary: str = Field(description="简要总结")
+        sentiment: str = Field(description="情感倾向: positive/negative/neutral")
+        confidence: float = Field(description="置信度 0-1")
+        keywords: list = Field(description="关键词列表")
+
+    # 创建结构化输出员工
+    analyst = VirtualEmployee(
+        name="情感分析师",
+        role="文本情感分析专家",
+        model="Qwen2.5-72B",
+        response_format=AnalysisResult,
+        system_prompt="你是情感分析专家，分析文本的情感和关键信息。"
+    )
+
+    print(f"\n员工: {analyst}")
+    print(f"输出格式: {AnalysisResult.__name__}")
+
+    result = await analyst.run("这个产品太棒了！质量好，价格合理，非常满意！")
+    print(f"\n用户: 这个产品太棒了！质量好，价格合理，非常满意！")
+    print(f"分析结果: {result}")
+
+
+async def interrupt_example():
+    """中断控制示例（人工审核）"""
+    print("\n" + "=" * 60)
+    print("示例 11: 中断控制 - 人工审核")
+    print("=" * 60)
+
+    # 创建带中断控制的员工
+    from langgraph.checkpoint.memory import MemorySaver
+
+    approver = VirtualEmployee(
+        name="审批助手",
+        role="审批流程助手",
+        model="Qwen2.5-72B",
+        tools=[create_ticket],
+        checkpointer=MemorySaver(),
+        interrupt_on={"tool_calls": True},  # 工具调用前中断
+        system_prompt="你是审批助手，在执行重要操作前需要人工确认。"
+    )
+
+    thread_id = "approval_001"
+    config = {"configurable": {"thread_id": thread_id}}
+
+    print(f"\n员工: {approver}")
+    print("场景: 创建工单需要人工确认")
+
+    # 发起请求
+    print("\n--- 发起请求 ---")
+    result = await approver.run("帮我创建一个紧急工单，标题是系统故障", thread_id=thread_id)
+    print(f"用户: 帮我创建一个紧急工单，标题是系统故障")
+    print(f"当前状态: {result[:100]}...")
+
+    # 检查状态
+    print("\n--- 检查状态 ---")
+    state = await approver.aget_state(config)
+    print(f"是否需要继续: {bool(state.next)}")
+    print(f"下一步: {state.next}")
+
+    # 模拟人工确认后继续
+    if state.next:
+        print("\n--- 人工确认后继续 ---")
+        result = await approver.ainvoke(None, config=config)
+        print(f"最终结果: {result['messages'][-1].content[:100]}...")
+
+
+async def main():
+    """运行所有示例"""
+    print("\n" + "=" * 70)
+    print("🚀 虚拟员工系统示例")
+    print("=" * 70)
+
+    await basic_employee()
+    await employee_with_subteam()
+    await employee_with_memory()
+    await employee_with_middleware()
+    await employee_with_permission()
+    await factory_employees()
+    await chain_configuration()
+    await virtual_team()
+    await combined_example()
+    await structured_output_example()
+    await interrupt_example()
+
+    print("\n" + "=" * 70)
+    print("✅ 所有示例完成")
+    print("=" * 70)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

sycommon_python_lib-0.2.0b26/src/sycommon/agent/exports.py

@@ -0,0 +1,107 @@
+"""
+sycommon.agent 导出
+=====================
+
+提供对 deepagents 的便捷调用，自动集成 get_llm 的 Token 统计和 Langfuse 追踪。
+
+## 使用示例
+
+```python
+from sycommon.agent import get_agent, SubAgent
+
+# 创建 Agent
+agent = get_agent(
+    model="Qwen2.5-72B",
+    tools=[my_tool],
+    system_prompt="你是助手"
+)
+
+# 执行
+result = await agent.ainvoke({"messages": ["你好"]})
+
+# 多 Agent
+agent = get_agent(
+    model="Qwen2.5-72B",
+    subagents=[
+        SubAgent(name="researcher", description="研究助手"),
+    ]
+)
+
+# 虚拟员工（业务层封装）
+from sycommon.agent import VirtualEmployee, Skill, EmployeeFactory
+
+support = EmployeeFactory.create_support_agent(name="客服小美")
+result = await support.run("我需要帮助")
+```
+"""
+
+# 主要接口
+from sycommon.agent.get_agent import (
+    get_agent,
+    create_tool_agent,
+    create_multi_agent,
+    create_structured_agent,
+)
+
+# 透传 deepagents 的核心类，方便用户直接使用
+from deepagents import (
+    SubAgent,
+    CompiledSubAgent,
+    create_deep_agent,
+    MemoryMiddleware,
+    FilesystemMiddleware,
+    SubAgentMiddleware,
+)
+
+# 虚拟员工系统（业务层封装）
+from sycommon.agent.virtual_employee import (
+    VirtualEmployee,
+    VirtualTeam,
+    EmployeeFactory,
+    Skill,
+    SkillLevel,
+    SubTeamMember,
+    MemoryConfig,
+    MemoryType,
+    EmployeeMiddleware,
+    LoggingEmployeeMiddleware,
+    QuotaEmployeeMiddleware,
+    PermissionEmployeeMiddleware,
+)
+
+# 技能系统中间件（从 deepagents 导入）
+from sycommon.agent.skills import (
+    SkillsMiddleware,
+    SkillMetadata,
+)
+
+__all__ = [
+    # 主要接口
+    "get_agent",
+    "create_tool_agent",
+    "create_multi_agent",
+    "create_structured_agent",
+    # deepagents 透传
+    "SubAgent",
+    "CompiledSubAgent",
+    "create_deep_agent",
+    "MemoryMiddleware",
+    "FilesystemMiddleware",
+    "SubAgentMiddleware",
+    # 虚拟员工系统
+    "VirtualEmployee",
+    "VirtualTeam",
+    "EmployeeFactory",
+    "Skill",
+    "SkillLevel",
+    "SubTeamMember",
+    "MemoryConfig",
+    "MemoryType",
+    "EmployeeMiddleware",
+    "LoggingEmployeeMiddleware",
+    "QuotaEmployeeMiddleware",
+    "PermissionEmployeeMiddleware",
+    # 技能系统中间件
+    "SkillsMiddleware",
+    "SkillMetadata",
+]