isage-middleware 0.2.4.3__cp311-none-any.whl

sage/middleware/operators/__init__.py

@@ -0,0 +1,56 @@
+"""
+SAGE Middleware Operators - 领域算子
+
+这个模块提供面向特定业务领域的算子实现：
+- LLM算子: 大语言模型推理 (SageLLMGenerator)
+- RAG算子: 检索增强生成算子 (Retriever, Refiner, Reranker, Generator等)
+- Tool算子: 工具调用 + 领域特定工具 (arxiv, image_captioner等)
+- Filters: 业务过滤器 (tool_filter, evaluate_filter, context source/sink)
+- Agentic: Agent runtime operators (requires isage-agentic, optional)
+
+向量数据库集成位于: sage.middleware.components.vector_stores
+
+这些算子继承 sage.kernel.operators 的基础算子，实现具体业务逻辑。
+
+使用方式：
+    from sage.middleware.operators import rag, llm, tools, filters
+
+    # 或直接导入
+    from sage.middleware.operators.rag import ChromaRetriever
+    from sage.middleware.operators.llm import SageLLMGenerator
+    from sage.middleware.components.vector_stores import MilvusBackend, ChromaBackend
+
+    # Agentic operators (requires isage-agentic, install with: pip install isage-middleware[libs])
+    from sage.middleware.operators.agentic import PlanningOperator
+"""
+
+import warnings
+
+from sage.middleware.operators.llm.sagellm_generator import SageLLMGenerator
+
+# 导出核心子模块 (always available)
+from . import filters, llm, rag, tools
+
+# Agentic operators are optional (requires isage-agentic)
+try:
+    from . import agentic
+
+    _HAS_AGENTIC = True
+except ImportError as e:
+    _HAS_AGENTIC = False
+    agentic = None  # type: ignore
+    warnings.warn(
+        f"Agentic operators not available: {e}\n"
+        "Install with: pip install isage-middleware[libs] or pip install isage-agentic",
+        UserWarning,
+        stacklevel=2,
+    )
+
+__all__ = [
+    "rag",
+    "llm",
+    "tools",
+    "filters",
+    "agentic",
+    "SageLLMGenerator",
+]

sage/middleware/operators/agent/__init__.py

@@ -0,0 +1,24 @@
+"""Agent components for SAGE middleware.
+
+Provides agent runtime and planning capabilities.
+
+Note: This module requires isage-agentic. Install with:
+    pip install isage-middleware[libs] or pip install isage-agentic
+"""
+
+import warnings
+
+try:
+    from sage.middleware.operators.agent import runtime
+
+    _HAS_AGENTIC = True
+    __all__ = ["runtime"]
+except ImportError as e:
+    _HAS_AGENTIC = False
+    runtime = None  # type: ignore
+    __all__ = []
+    warnings.warn(
+        f"Agent runtime not available: {e}\nInstall with: pip install isage-agentic",
+        UserWarning,
+        stacklevel=2,
+    )

sage/middleware/operators/agent/planning/__init__.py

@@ -0,0 +1,5 @@
+from .llm_adapter import GeneratorToClientAdapter
+from .planner_adapter import SageLibsPlannerAdapter
+from .router import PlannerRouter
+
+__all__ = ["PlannerRouter", "SageLibsPlannerAdapter", "GeneratorToClientAdapter"]

sage/middleware/operators/agent/planning/llm_adapter.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class GeneratorToClientAdapter:
+    """
+    Adapts OpenAIGenerator/HFGenerator (L4) to UnifiedInferenceClient interface (L2/L3).
+    """
+
+    def __init__(self, generator):
+        self.generator = generator
+
+    def chat(
+        self, messages: list[dict[str, str]], temperature: float = 0.7, max_tokens: int = 512
+    ) -> str:
+        """
+        Execute chat completion.
+        """
+        # OpenAIGenerator.execute takes [user_query, messages] or just messages depending on impl.
+        # Let's check OpenAIGenerator.execute signature.
+        # Based on usage in LLMPlanner: self.generator.execute([user_query, messages])
+        # But here we might not have user_query easily available if it's just a chat call.
+        # We can pass the last user message as user_query.
+
+        user_query = "Chat request"
+        for msg in reversed(messages):
+            if msg["role"] == "user":
+                user_query = msg["content"]
+                break
+
+        # The generator returns (token_usage, text_output)
+        _, output = self.generator.execute([user_query, messages])
+        return output
+
+    def generate(self, prompt: str, **kwargs) -> list[dict[str, Any]]:
+        """
+        Execute text generation.
+        """
+        _, output = self.generator.execute([prompt, [{"role": "user", "content": prompt}]])
+        return [{"generations": [{"text": output}]}]

sage/middleware/operators/agent/planning/planner_adapter.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from sage_libs.sage_agentic.agents.planning.schemas import PlannerConfig, PlanRequest, ToolMetadata
+
+logger = logging.getLogger(__name__)
+
+
+class SageLibsPlannerAdapter:
+    """
+    Adapts sage-libs planners (ReAct, ToT, Hierarchical) to the AgentRuntime interface.
+    """
+
+    def __init__(self, planner_cls, config: PlannerConfig, llm_client):
+        self.planner = planner_cls(config=config, llm_client=llm_client)
+
+    def plan(
+        self,
+        profile_system_prompt: str,
+        user_query: str,
+        tools: dict[str, dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """
+        Convert inputs to PlanRequest, call planner, and convert PlanResult to list[dict].
+        """
+        # 1. Convert tools dict to List[ToolMetadata]
+        tool_metadata_list = []
+        for name, meta in tools.items():
+            tool_metadata_list.append(
+                ToolMetadata(
+                    tool_id=name,
+                    name=name,
+                    description=meta.get("description", ""),
+                    category=meta.get("category", "general"),
+                    input_schema=meta.get("input_schema", {}),
+                )
+            )
+
+        # 2. Create PlanRequest
+        request = PlanRequest(
+            goal=user_query,
+            context={"system_prompt": profile_system_prompt},
+            tools=tool_metadata_list,
+            max_steps=10,  # Default
+            min_steps=1,
+        )
+
+        # 3. Call planner
+        try:
+            result = self.planner.plan(request)
+        except Exception as e:
+            logger.error(f"Planner {self.planner.name} failed: {e}")
+            return [{"type": "reply", "text": f"Planning failed: {str(e)}"}]
+
+        # 4. Convert PlanResult to list[dict]
+        # AgentRuntime expects: [{"type": "tool", "name": "...", "arguments": {...}}, ...]
+        runtime_steps = []
+
+        if not result.steps:
+            return [{"type": "reply", "text": "No plan generated."}]
+
+        for step in result.steps:
+            if step.action == "finish":
+                # Some planners might use a 'finish' action
+                continue
+
+            # Check if it's a tool call
+            # In sage-libs, 'action' is usually the tool name
+            # 'inputs' are arguments
+
+            # Heuristic: if action matches a tool name, it's a tool call
+            if step.action in tools:
+                runtime_steps.append(
+                    {"type": "tool", "name": step.action, "arguments": step.inputs}
+                )
+            else:
+                # Treat as thought or unknown action?
+                # AgentRuntime doesn't support "thought" steps explicitly in the loop yet,
+                # but we can log them or ignore them.
+                # If it's a reply-like action?
+                pass
+
+        # If no tool steps, maybe it's a direct reply?
+        if not runtime_steps:
+            # Try to find a final thought or result
+            final_thought = getattr(result, "final_thought", None) or "Plan completed."
+            runtime_steps.append({"type": "reply", "text": final_thought})
+        else:
+            # Append a final reply step if not present?
+            # AgentRuntime loop executes steps. If the last step is a tool, it will execute it.
+            # Then what? The loop continues?
+            # AgentRuntime loop: for step in plan: execute.
+            # If plan is static, it executes all steps.
+            pass
+
+        return runtime_steps

sage/middleware/operators/agent/planning/router.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from sage_libs.sage_agentic.agents.planning.hierarchical_planner import HierarchicalPlanner
+from sage_libs.sage_agentic.agents.planning.react_planner import ReActConfig, ReActPlanner
+from sage_libs.sage_agentic.agents.planning.schemas import PlannerConfig
+from sage_libs.sage_agentic.agents.planning.simple_llm_planner import SimpleLLMPlanner
+from sage_libs.sage_agentic.agents.planning.tot_planner import ToTConfig
+from sage_libs.sage_agentic.agents.planning.tot_planner import TreeOfThoughtsPlanner as ToTPlanner
+
+from .llm_adapter import GeneratorToClientAdapter
+from .planner_adapter import SageLibsPlannerAdapter
+
+logger = logging.getLogger(__name__)
+
+
+class PlannerRouter:
+    """
+    Routes user queries to the appropriate planner based on intent classification.
+    """
+
+    def __init__(self, generator, default_planner="llm"):
+        self.generator = generator
+        self.llm_client = GeneratorToClientAdapter(generator)
+        self.default_planner_type = default_planner
+
+        # Initialize planners
+        # 1. Simple LLM Planner (Baseline)
+        self.simple_planner = SimpleLLMPlanner(generator=generator)
+
+        # 2. ReAct Planner (Reasoning)
+        self.react_planner = SageLibsPlannerAdapter(
+            ReActPlanner, ReActConfig(max_iterations=5), self.llm_client
+        )
+
+        # 3. ToT Planner (Complex/Exploratory)
+        self.tot_planner = SageLibsPlannerAdapter(
+            ToTPlanner, ToTConfig(max_depth=3, branch_factor=3), self.llm_client
+        )
+
+        # 4. Hierarchical Planner (Long-horizon)
+        self.hierarchical_planner = SageLibsPlannerAdapter(
+            HierarchicalPlanner, PlannerConfig(), self.llm_client
+        )
+
+    def _classify_intent(self, user_query: str) -> str:
+        """
+        Classify the user query into one of the planner types.
+        """
+        prompt = """
+You are an expert intent classifier for an AI agent.
+Analyze the user's query and select the most suitable planning strategy.
+
+Strategies:
+1. "simple": For direct questions, simple tasks, or when no tools are needed. (e.g., "Hello", "What is 2+2?")
+2. "react": For tasks requiring multi-step reasoning and tool usage. (e.g., "Search for X and summarize it")
+3. "tot": For complex problems requiring exploration of multiple possibilities or creative writing. (e.g., "Write a novel outline", "Solve a complex riddle")
+4. "hierarchical": For very long, complex tasks with many sub-tasks. (e.g., "Plan a 3-day trip including flights, hotels, and restaurants")
+
+User Query: "{query}"
+
+Return ONLY the strategy name (simple, react, tot, hierarchical) in JSON format: {{"strategy": "..."}}
+"""
+        try:
+            response = self.llm_client.chat(
+                [
+                    {"role": "system", "content": "You are an intent classifier."},
+                    {"role": "user", "content": prompt.format(query=user_query)},
+                ],
+                temperature=0.1,
+            )
+
+            # Parse JSON
+            import re
+
+            match = re.search(r"\{.*\}", response, re.DOTALL)
+            if match:
+                data = json.loads(match.group(0))
+                return data.get("strategy", "simple").lower()
+        except Exception as e:
+            logger.warning(f"Intent classification failed: {e}. Using default.")
+
+        return "simple"
+
+    def plan(
+        self,
+        profile_system_prompt: str,
+        user_query: str,
+        tools: dict[str, dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """
+        Route to the appropriate planner.
+        """
+        strategy = self._classify_intent(user_query)
+        logger.info(f"Selected planning strategy: {strategy}")
+
+        if strategy == "react":
+            return self.react_planner.plan(profile_system_prompt, user_query, tools)
+        elif strategy == "tot":
+            return self.tot_planner.plan(profile_system_prompt, user_query, tools)
+        elif strategy == "hierarchical":
+            return self.hierarchical_planner.plan(profile_system_prompt, user_query, tools)
+        else:
+            return self.simple_planner.plan(profile_system_prompt, user_query, tools)

sage/middleware/operators/agent/runtime.py

@@ -0,0 +1,296 @@
+"""
+Agent Runtime (Middleware Layer)
+
+This component acts as a Dynamic Pipeline Orchestrator.
+It takes a user query, generates a dynamic execution plan (DAG), and executes it using available tools.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+# Import from L3 (Libs) - Allowed dependency direction (L4 -> L3)
+from sage_libs.sage_agentic.agents.action.mcp_registry import MCPRegistry
+from sage_libs.sage_agentic.agents.planning import PlanStep, SimpleLLMPlanner
+from sage_libs.sage_agentic.agents.profile.profile import BaseProfile
+
+logger = logging.getLogger(__name__)
+
+
+def _missing_required(arguments: dict[str, Any], input_schema: dict[str, Any]) -> list[str]:
+    """基于 MCP JSON Schema 做最小必填参数校验。"""
+    req = (input_schema or {}).get("required") or []
+    return [k for k in req if k not in arguments]
+
+
+class AgentRuntime:
+    """
+    Production-Ready Runtime (Middleware Layer):
+    - Input: user_query
+    - Process: Planner generates JSON plan -> Step-by-step execution -> Optional LLM summary -> Return
+    - Features: Safety checks, Error handling, Structured logging/output
+    """
+
+    def __init__(
+        self,
+        profile: BaseProfile,
+        planner: SimpleLLMPlanner,
+        tools: MCPRegistry,
+        summarizer=None,
+        max_steps: int = 6,
+    ):
+        self.profile = profile
+        self.planner = planner
+        self.tools = tools
+        self.summarizer = summarizer
+        self.max_steps = max_steps
+
+    def step_stream(self, user_query: str):
+        """
+        Execute a single turn of conversation with streaming feedback.
+
+        Yields:
+            Dict containing event type and data
+        """
+        logger.info(f"AgentRuntime (Middleware) step_stream started for query: {user_query}")
+
+        observations: list[dict[str, Any]] = []
+        plan: list[PlanStep] = []
+
+        # 1) 生成计划（流式）
+        try:
+            # 检查 planner 是否支持流式
+            if hasattr(self.planner, "plan_stream"):
+                for event in self.planner.plan_stream(
+                    profile_system_prompt=self.profile.render_system_prompt(),
+                    user_query=user_query,
+                    tools=self.tools.describe(),
+                ):
+                    if event["type"] == "thought":
+                        yield {"type": "planning_thought", "content": event["content"]}
+                    elif event["type"] == "plan":
+                        plan = event["steps"]
+                        yield {"type": "plan_generated", "plan": plan}
+            else:
+                # 降级到非流式
+                yield {"type": "planning_thought", "content": "正在生成计划..."}
+                plan = self.planner.plan(
+                    profile_system_prompt=self.profile.render_system_prompt(),
+                    user_query=user_query,
+                    tools=self.tools.describe(),
+                )
+                yield {"type": "plan_generated", "plan": plan}
+
+            logger.info(f"Plan generated with {len(plan)} steps")
+        except Exception as e:
+            logger.error(f"Planning failed: {e}")
+            yield {"type": "error", "content": f"Planning failed: {str(e)}"}
+            return
+
+        reply_text: str | None = None
+
+        # 2) 逐步执行
+        for i, step in enumerate(plan[: self.max_steps]):
+            logger.debug(f"Executing step {i}: {step}")
+
+            if step.get("type") == "reply":
+                reply_text = step.get("text", "").strip()
+                logger.info("Plan reached reply step")
+                yield {"type": "reply", "content": reply_text}
+                break
+
+            if step.get("type") == "tool":
+                name = step.get("name")
+                arguments = step.get("arguments", {}) or {}
+
+                yield {"type": "tool_start", "tool": name, "arguments": arguments}
+
+                # Safety Check: Validate arguments against schema
+                tools_meta = self.tools.describe()
+                tool_desc = tools_meta.get(name) if isinstance(name, str) else None
+
+                if not tool_desc:
+                    error_msg = f"Tool '{name}' not found in registry"
+                    logger.warning(error_msg)
+                    obs = {
+                        "step": i,
+                        "tool": name,
+                        "ok": False,
+                        "error": error_msg,
+                        "arguments": arguments,
+                    }
+                    observations.append(obs)
+                    yield {"type": "tool_error", "tool": name, "error": error_msg}
+                    continue
+
+                schema = tool_desc.get("input_schema", {}) if tool_desc else {}
+                miss = _missing_required(arguments, schema)
+
+                if miss:
+                    error_msg = f"Missing required fields: {miss}"
+                    logger.warning(f"Tool '{name}' validation failed: {error_msg}")
+                    obs = {
+                        "step": i,
+                        "tool": name,
+                        "ok": False,
+                        "error": error_msg,
+                        "arguments": arguments,
+                    }
+                    observations.append(obs)
+                    yield {"type": "tool_error", "tool": name, "error": error_msg}
+                    continue
+
+                t0 = time.time()
+                try:
+                    logger.info(f"Calling tool '{name}' with args: {arguments}")
+                    out = self.tools.call(name, arguments)  # type: ignore[arg-type]
+                    latency = int((time.time() - t0) * 1000)
+
+                    obs = {
+                        "step": i,
+                        "tool": name,
+                        "ok": True,
+                        "latency_ms": latency,
+                        "result": out,
+                    }
+                    observations.append(obs)
+                    logger.info(f"Tool '{name}' success ({latency}ms)")
+                    yield {"type": "tool_result", "tool": name, "result": out}
+
+                except Exception as e:
+                    latency = int((time.time() - t0) * 1000)
+                    logger.error(f"Tool '{name}' failed: {e}")
+                    obs = {
+                        "step": i,
+                        "tool": name,
+                        "ok": False,
+                        "latency_ms": latency,
+                        "error": str(e),
+                        "arguments": arguments,
+                    }
+                    observations.append(obs)
+                    yield {"type": "tool_error", "tool": name, "error": str(e)}
+
+        # 3) 汇总输出
+        final_reply = ""
+
+        if reply_text:
+            final_reply = reply_text
+        elif not observations:
+            final_reply = "（没有可执行的步骤或工具返回空结果）"
+        elif self.summarizer:
+            yield {"type": "planning_thought", "content": "正在汇总执行结果..."}
+            # 用你的生成器来生成自然语言总结
+            profile_hint = self.profile.render_system_prompt()
+            prompt = f"""请将以下工具步骤结果用中文简洁汇总给用户，保留关键信息和结论。
+
+[Profile]
+{profile_hint}
+
+[Observations]
+{observations}
+
+只输出给用户的总结文本。"""
+            messages = [
+                {
+                    "role": "system",
+                    "content": "你是一个严谨的助理。只输出中文总结，不要额外解释。",
+                },
+                {"role": "user", "content": prompt},
+            ]
+            try:
+                _, summary = self.summarizer.execute([None, messages])
+                final_reply = summary.strip()
+                yield {"type": "reply", "content": final_reply}
+            except Exception as e:
+                logger.error(f"Summarization failed: {e}")
+                final_reply = "Summarization failed."
+                yield {"type": "error", "content": "Summarization failed."}
+        else:
+            # 简单模板
+            lines = []
+            for obs in observations:
+                if obs.get("ok"):
+                    lines.append(f"#{obs['step'] + 1} 工具 {obs['tool']} 成功：{obs.get('result')}")
+                else:
+                    lines.append(f"#{obs['step'] + 1} 工具 {obs['tool']} 失败：{obs.get('error')}")
+            final_reply = "\n".join(lines)
+            yield {"type": "reply", "content": final_reply}
+
+        yield {
+            "type": "completed",
+            "observations": observations,
+            "plan": plan,
+            "reply": final_reply,
+        }
+
+    def step(self, user_query: str) -> dict[str, Any]:
+        """
+        Execute a single turn of conversation.
+
+        Returns:
+            Dict containing:
+            - reply: The final text response
+            - observations: List of execution steps and results
+            - plan: The original plan
+        """
+        # 兼容旧接口，收集流式结果
+        result = {"reply": "", "observations": [], "plan": []}
+
+        for event in self.step_stream(user_query):
+            if event["type"] == "completed":
+                result["reply"] = event.get("reply", "")
+                result["observations"] = event.get("observations", [])
+                result["plan"] = event.get("plan", [])
+
+        return result
+
+    def execute(self, data: Any) -> dict[str, Any]:
+        """
+        Unified Entry Point.
+
+        Args:
+            data: str (query) or dict (config + query)
+
+        Returns:
+            Dict containing 'reply', 'observations', 'plan'
+        """
+        # 形态 1：直接字符串
+        if isinstance(data, str):
+            return self.step(data)
+
+        # 形态 2：字典
+        if isinstance(data, dict):
+            user_query = data.get("user_query") or data.get("query")
+            if not isinstance(user_query, str) or not user_query.strip():
+                raise ValueError(
+                    "AgentRuntime.execute(dict) 需要提供 'user_query' 或 'query'（非空字符串）。"
+                )
+
+            # 临时覆写 max_steps
+            original_max = self.max_steps
+            if "max_steps" in data:
+                ms = data["max_steps"]
+                if not isinstance(ms, int) or ms <= 0:
+                    raise ValueError("'max_steps' 必须是正整数。")
+                self.max_steps = ms
+
+            # 临时覆写 profile（一次性，不污染实例）
+            original_profile = self.profile
+            if "profile_overrides" in data and isinstance(data["profile_overrides"], dict):
+                try:
+                    self.profile = self.profile.merged(**data["profile_overrides"])
+                except Exception:
+                    # 失败则回退，不中断主流程
+                    self.profile = original_profile
+
+            try:
+                return self.step(user_query)
+            finally:
+                # 还原
+                self.max_steps = original_max
+                self.profile = original_profile
+
+        raise TypeError("AgentRuntime.execute 仅接受 str 或 dict 两种输入。")

sage/middleware/operators/agentic/__init__.py

@@ -0,0 +1,41 @@
+"""L4 Agentic Operators.
+
+This package exposes ready-to-use operator wrappers (MapOperators) built on
+sage.libs.agentic components so Studio and pipeline builders can drag-and-drop
+agent runtimes without wiring boilerplate.
+
+Supports engine_type switching for LLM generators:
+- sagellm (default): SageLLMGenerator with configurable backend
+  - backend_type="auto": Automatically select best available backend
+  - backend_type="mock": Mock backend for testing without GPU
+  - backend_type="cuda": NVIDIA CUDA backend
+  - backend_type="ascend": Huawei Ascend NPU backend
+- openai: OpenAIGenerator for OpenAI-compatible APIs
+- hf: HFGenerator for HuggingFace models
+"""
+
+from .config import (
+    AgentRuntimeConfig,
+    GeneratorConfig,
+    ProfileConfig,
+    RuntimeSettings,
+)
+from .planning_operator import PlanningOperator
+from .refined_searcher import RefinedSearcherOperator
+from .runtime import AgentRuntimeOperator
+from .timing_operator import TimingOperator
+from .tool_selection_operator import ToolSelectionOperator
+
+__all__ = [
+    # Operators
+    "AgentRuntimeOperator",
+    "ToolSelectionOperator",
+    "PlanningOperator",
+    "TimingOperator",
+    "RefinedSearcherOperator",
+    # Config classes
+    "AgentRuntimeConfig",
+    "GeneratorConfig",
+    "ProfileConfig",
+    "RuntimeSettings",
+]