agstack 1.5.0__tar.gz → 1.6.0__tar.gz

{agstack-1.5.0 → agstack-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.5.0
+Version: 1.6.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.5.0 → agstack-1.6.0}/agstack/llm/flow/__init__.py

@@ -18,6 +18,7 @@ from .exceptions import (
 from .factory import create_agent, create_tool
 from .flow import Flow
 from .loader import FlowLoader
+from .nodes import NodeHandler, register_node_handler
 from .records import Record, Status
 from .registry import registry
 from .state import FlowState
@@ -32,6 +33,9 @@ __all__ = [
     "Flow",
     "FlowContext",
     "Usage",
+    # 节点处理器
+    "NodeHandler",
+    "register_node_handler",
     # AG-UI 协议
     "EventType",
     "event",

{agstack-1.5.0 → agstack-1.6.0}/agstack/llm/flow/flow.py

@@ -1,4 +1,4 @@
-#  Copyright (c) 2020-2025 XtraVisions, All rights reserved.
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
 
 """Flow 定义和执行"""
 
@@ -9,12 +9,12 @@ from typing import TYPE_CHECKING, Any, AsyncIterator
 from uuid import uuid4
 
 from . import event
-from .exceptions import FlowError, NodeExecutionError
-from .registry import registry
+from .exceptions import NodeExecutionError
 
 
 if TYPE_CHECKING:
     from .context import FlowContext
+    from .nodes.base import NodeHandler
 
 
 @dataclass
@@ -44,6 +44,16 @@ class Flow:
     edges: list[dict[str, Any]] = field(default_factory=list)
     variables: dict[str, Any] = field(default_factory=dict)
 
+    _node_handlers: dict[str, "NodeHandler"] = field(default_factory=dict, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        from .nodes import _global_node_handlers, builtin_handlers
+
+        for handler in builtin_handlers:
+            self._node_handlers[handler.node_type] = handler
+        # 全局注册的自定义 handler 可覆盖内置
+        self._node_handlers.update(_global_node_handlers)
+
     # ── 重试策略 ──
 
     @staticmethod
@@ -99,7 +109,7 @@ class Flow:
         yield event.text_message_content(message_id=msg_id, delta=text)
         yield event.text_message_end(message_id=msg_id)
 
-    # ── 带重试的节点执行 ──
+    # ── 带重试的节点执行（统一走 NodeHandler） ──
 
     async def _execute_node_with_retry(
         self,
@@ -108,10 +118,17 @@ class Flow:
         node_id: str,
     ) -> AsyncIterator[dict[str, Any]]:
         """执行节点，带重试策略，产出 AG-UI 事件"""
+        node_type: str = node.get("type", "")
+        handler = self._node_handlers.get(node_type)
+        if not handler:
+            yield event.run_error(
+                message=f"Unknown node type: {node_type}",
+                code="UNKNOWN_NODE_TYPE",
+            )
+            raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
+
         policy = self._get_retry_policy(node)
-        node_type = node.get("type")
-        config = node.get("config", {})
-        label = config.get("agent_name") or config.get("tool_name") or node_id
+        label = handler.get_step_name(node, node_id)
         last_error: Exception | None = None
 
         for attempt in range(policy.max_retries + 1):
@@ -131,23 +148,9 @@ class Flow:
                         },
                     )
 
-                if node_type == "agent":
-                    yield event.step_started(step_name=f"agent:{label}")
-                    self._set_parameters(config, context)
-                    ag = self._create_agent(config)
-                    async for evt in ag.stream(context):
-                        yield evt
-                    result = context.get_last_output(ag.name) or ""
-                    context.set_node_result(node_id, result)
-                    yield event.step_finished(step_name=f"agent:{label}")
-                    return
-
-                elif node_type == "tool":
-                    yield event.step_started(step_name=f"tool:{label}")
-                    result = await self._execute_node(node, context)
-                    context.set_node_result(node_id, result)
-                    yield event.step_finished(step_name=f"tool:{label}")
-                    return
+                async for evt in handler.stream(node, context, node_id):
+                    yield evt
+                return
 
             except Exception as e:
                 last_error = e
@@ -173,8 +176,13 @@ class Flow:
                 if not node_id:
                     continue
                 context.current_node = node_id
-                result = await self._execute_node(node, context)
-                context.set_node_result(node_id, result)
+                node_type: str = node.get("type", "")
+                handler = self._node_handlers.get(node_type)
+                if handler:
+                    result = await handler.execute(node, context)
+                    context.set_node_result(node_id, result)
+                else:
+                    raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
         else:
             # edge 驱动执行
             current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
@@ -183,7 +191,7 @@ class Flow:
                 if not node:
                     break
                 context.current_node = current_node_id
-                node_type = node.get("type")
+                node_type: str = node.get("type", "")
 
                 if node_type == "message":
                     config = node.get("config", {})
@@ -191,13 +199,6 @@ class Flow:
                     text = template.format_map(_SafeFormatDict(context.variables))
                     context.set_node_result(current_node_id, text)
                     current_node_id = self._resolve_next_node(current_node_id, "done")
-                elif node_type in ("agent", "tool"):
-                    result = await self._execute_node(node, context)
-                    context.set_node_result(current_node_id, result)
-                    route_key = self._extract_route_key(result)
-                    current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
-                        current_node_id, "done"
-                    )
 
                 elif node_type == "parallel":
                     config = node.get("config", {})
@@ -208,9 +209,11 @@ class Flow:
                         if not branch_node:
                             return
                         context.current_node = branch_id
-                        self._set_parameters(branch_node.get("config", {}), context)
-                        result = await self._execute_node(branch_node, context)
-                        context.set_node_result(branch_id, result)
+                        branch_type: str = branch_node.get("type", "")
+                        branch_handler = self._node_handlers.get(branch_type)
+                        if branch_handler:
+                            result = await branch_handler.execute(branch_node, context)
+                            context.set_node_result(branch_id, result)
 
                     await asyncio.gather(*[_run_branch(bid) for bid in branches])
                     context.set_node_result(current_node_id, "done")
@@ -238,9 +241,11 @@ class Flow:
                             body_node = self.get_node_config(body_node_id)
                             if not body_node:
                                 continue
-                            self._set_parameters(body_node.get("config", {}), context)
-                            body_result = await self._execute_node(body_node, context)
-                            context.set_node_result(body_node_id, body_result)
+                            body_type: str = body_node.get("type", "")
+                            body_handler = self._node_handlers.get(body_type)
+                            if body_handler:
+                                body_result = await body_handler.execute(body_node, context)
+                                context.set_node_result(body_node_id, body_result)
                         if body_nodes:
                             results.append(context.node_results.get(body_nodes[-1]))
 
@@ -262,9 +267,11 @@ class Flow:
                             body_node = self.get_node_config(body_node_id)
                             if not body_node:
                                 continue
-                            self._set_parameters(body_node.get("config", {}), context)
-                            body_result = await self._execute_node(body_node, context)
-                            context.set_node_result(body_node_id, body_result)
+                            body_type: str = body_node.get("type", "")
+                            body_handler = self._node_handlers.get(body_type)
+                            if body_handler:
+                                body_result = await body_handler.execute(body_node, context)
+                                context.set_node_result(body_node_id, body_result)
                         if condition_node_id:
                             cond_result = context.node_results.get(condition_node_id, "")
                             if isinstance(cond_result, str):
@@ -279,27 +286,18 @@ class Flow:
                     context.set_node_result(current_node_id, "done")
                     current_node_id = self._resolve_next_node(current_node_id, "done")
 
-                elif node_type == "python":
-                    config = node.get("config", {})
-                    inputs_spec: dict[str, Any] = config.get("inputs", {})
-                    resolved_inputs: dict[str, Any] = {}
-                    for key, ref in inputs_spec.items():
-                        resolved_inputs[key] = context.resolve_reference(ref) if isinstance(ref, str) else ref
-
-                    from .sandbox import execute_python_node
-
-                    code_str = config.get("code", "")
-                    py_result = execute_python_node(code_str, resolved_inputs)
-
-                    outputs_spec: dict[str, Any] = config.get("outputs", {})
-                    for key in outputs_spec:
-                        if key in py_result:
-                            context.set_variable(key, py_result[key])
+                elif node_type in self._node_handlers:
+                    # 所有执行类节点统一分发
+                    handler = self._node_handlers[node_type]
+                    result = await handler.execute(node, context)
+                    context.set_node_result(current_node_id, result)
+                    route_key = self._extract_route_key(result)
+                    current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
+                        current_node_id, "done"
+                    )
 
-                    context.set_node_result(current_node_id, _json.dumps(py_result, ensure_ascii=False))
-                    current_node_id = self._resolve_next_node(current_node_id, "done")
                 else:
-                    break
+                    raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
 
         return context.node_results
 
@@ -326,17 +324,17 @@ class Flow:
                 continue
 
             context.current_node = node_id
-            yield event.step_started(step_name=f"node:{node_id}")
+            node_type: str = node.get("type", "")
 
-            if node.get("type") in ("agent", "tool"):
+            if node_type in self._node_handlers:
                 async for evt in self._execute_node_with_retry(node, context, node_id):
                     yield evt
             else:
-                tool_name = node.get("config", {}).get("tool_name", "")
-                yield event.step_started(step_name=f"tool:{tool_name}")
-                result = await self._execute_node(node, context)
-                context.set_node_result(node_id, result)
-                yield event.step_finished(step_name=f"tool:{tool_name}")
+                yield event.run_error(
+                    message=f"Unknown node type: {node_type}",
+                    code="UNKNOWN_NODE_TYPE",
+                )
+                raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
 
     async def _stream_edge_driven(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """边驱动流式执行"""
@@ -352,31 +350,13 @@ class Flow:
                 raise NodeExecutionError("NODE_NOT_FOUND", args={"node_id": current_node_id})
 
             context.current_node = current_node_id
-            node_type = node.get("type")
+            node_type: str = node.get("type", "")
 
             if node_type == "message":
                 async for evt in self._emit_message(node, context):
                     yield evt
                 current_node_id = self._resolve_next_node(current_node_id, "done")
 
-            elif node_type == "agent":
-                async for evt in self._execute_node_with_retry(node, context, current_node_id):
-                    yield evt
-                result = context.node_results.get(current_node_id, "")
-                route_key = self._extract_route_key(result)
-                current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
-                    current_node_id, "done"
-                )
-
-            elif node_type == "tool":
-                async for evt in self._execute_node_with_retry(node, context, current_node_id):
-                    yield evt
-                result = context.node_results.get(current_node_id, "")
-                route_key = self._extract_route_key(result)
-                current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
-                    current_node_id, "done"
-                )
-
             elif node_type == "parallel":
                 config = node.get("config", {})
                 branches = config.get("branches", [])
@@ -387,9 +367,11 @@ class Flow:
                     if not branch_node:
                         return
                     context.current_node = branch_id
-                    self._set_parameters(branch_node.get("config", {}), context)
-                    result = await self._execute_node(branch_node, context)
-                    context.set_node_result(branch_id, result)
+                    branch_type = branch_node.get("type", "")
+                    branch_handler = self._node_handlers.get(branch_type)
+                    if branch_handler:
+                        result = await branch_handler.execute(branch_node, context)
+                        context.set_node_result(branch_id, result)
 
                 await asyncio.gather(*[_exec_branch(bid) for bid in branches])
                 context.set_node_result(current_node_id, "done")
@@ -419,9 +401,11 @@ class Flow:
                         body_node = self.get_node_config(body_node_id)
                         if not body_node:
                             continue
-                        self._set_parameters(body_node.get("config", {}), context)
-                        body_result = await self._execute_node(body_node, context)
-                        context.set_node_result(body_node_id, body_result)
+                        body_type = body_node.get("type", "")
+                        body_handler = self._node_handlers.get(body_type)
+                        if body_handler:
+                            body_result = await body_handler.execute(body_node, context)
+                            context.set_node_result(body_node_id, body_result)
                     if body_nodes:
                         results.append(context.node_results.get(body_nodes[-1]))
 
@@ -445,9 +429,11 @@ class Flow:
                         body_node = self.get_node_config(body_node_id)
                         if not body_node:
                             continue
-                        self._set_parameters(body_node.get("config", {}), context)
-                        body_result = await self._execute_node(body_node, context)
-                        context.set_node_result(body_node_id, body_result)
+                        body_type = body_node.get("type", "")
+                        body_handler = self._node_handlers.get(body_type)
+                        if body_handler:
+                            body_result = await body_handler.execute(body_node, context)
+                            context.set_node_result(body_node_id, body_result)
                     # 检查终止条件
                     if condition_node_id:
                         cond_result = context.node_results.get(condition_node_id, "")
@@ -464,84 +450,22 @@ class Flow:
                 yield event.step_finished(step_name=f"loop:{current_node_id}")
                 current_node_id = self._resolve_next_node(current_node_id, "done")
 
-            elif node_type == "python":
-                config = node.get("config", {})
-                yield event.step_started(step_name=f"python:{current_node_id}")
-
-                # 解析 inputs
-                inputs_spec: dict[str, Any] = config.get("inputs", {})
-                resolved_inputs: dict[str, Any] = {}
-                for key, ref in inputs_spec.items():
-                    resolved_inputs[key] = context.resolve_reference(ref) if isinstance(ref, str) else ref
-
-                # 沙箱执行
-                from .sandbox import execute_python_node
-
-                code_str = config.get("code", "")
-                py_result = execute_python_node(code_str, resolved_inputs)
-
-                # 映射 outputs 到 context.variables
-                outputs_spec: dict[str, Any] = config.get("outputs", {})
-                for key in outputs_spec:
-                    if key in py_result:
-                        context.set_variable(key, py_result[key])
-
-                context.set_node_result(current_node_id, _json.dumps(py_result, ensure_ascii=False))
-                yield event.step_finished(step_name=f"python:{current_node_id}")
-                current_node_id = self._resolve_next_node(current_node_id, "done")
+            elif node_type in self._node_handlers:
+                # 所有执行类节点统一分发
+                async for evt in self._execute_node_with_retry(node, context, current_node_id):
+                    yield evt
+                result = context.node_results.get(current_node_id, "")
+                route_key = self._extract_route_key(result)
+                current_node_id = self._resolve_next_node(current_node_id, route_key) or self._resolve_next_node(
+                    current_node_id, "done"
+                )
 
             else:
-                break
-
-    async def _execute_node(self, node_config: dict, context: "FlowContext") -> Any:
-        """执行节点"""
-        node_type = node_config.get("type")
-        config = node_config.get("config", {})
-
-        # 设置参数到 context
-        self._set_parameters(config, context)
-
-        # 创建并执行 runnable
-        if node_type == "agent":
-            runnable = self._create_agent(config)
-        elif node_type == "tool":
-            runnable = self._create_tool(config)
-        else:
-            raise FlowError("UNKNOWN_NODE_TYPE", 400, {"type": node_type})
-
-        return await runnable.run(context)
-
-    def _set_parameters(self, config: dict, context: "FlowContext") -> None:
-        """设置参数到 context"""
-        parameters = config.get("parameters", {})
-
-        for key, value in parameters.items():
-            resolved_value = context.resolve_reference(value) if isinstance(value, str) else value
-            context.set_variable(key, resolved_value)
-
-    def _create_agent(self, config: dict):
-        """创建 Agent"""
-        agent_name = config.get("agent_name")
-        if not agent_name:
-            raise FlowError("MISSING_AGENT_NAME", 400)
-
-        agent = registry.create_agent(agent_name)
-        if not agent:
-            raise FlowError("AGENT_NOT_FOUND", 404, {"agent_name": agent_name})
-
-        return agent
-
-    def _create_tool(self, config: dict):
-        """创建 Tool"""
-        tool_name = config.get("tool_name")
-        if not tool_name:
-            raise FlowError("MISSING_TOOL_NAME", 400)
-
-        tool = registry.create_tool(tool_name)
-        if not tool:
-            raise FlowError("TOOL_NOT_FOUND", 404, {"tool_name": tool_name})
-
-        return tool
+                yield event.run_error(
+                    message=f"Unknown node type: {node_type}",
+                    code="UNKNOWN_NODE_TYPE",
+                )
+                raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
 
     def get_node_config(self, node_id: str) -> dict[str, Any] | None:
         """获取节点配置"""

agstack-1.6.0/agstack/llm/flow/nodes/__init__.py

@@ -0,0 +1,39 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""内置节点处理器注册"""
+
+from .agent_node import AgentNodeHandler
+from .base import NodeHandler
+from .detect_node import DetectNodeHandler
+from .llm_chat_node import LLMChatNodeHandler
+from .llm_embed_node import LLMEmbedNodeHandler
+from .llm_rerank_node import LLMRerankNodeHandler
+from .python_node import PythonNodeHandler
+from .tool_node import ToolNodeHandler
+
+
+# 所有内置 handler 实例
+builtin_handlers: list[NodeHandler] = [
+    AgentNodeHandler(),
+    ToolNodeHandler(),
+    PythonNodeHandler(),
+    LLMChatNodeHandler(),
+    LLMEmbedNodeHandler(),
+    LLMRerankNodeHandler(),
+    DetectNodeHandler(),
+]
+
+# 全局自定义节点注册
+_global_node_handlers: dict[str, NodeHandler] = {}
+
+
+def register_node_handler(node_type: str, handler: NodeHandler) -> None:
+    """注册自定义节点处理器（全局，所有 Flow 实例共享）"""
+    _global_node_handlers[node_type] = handler
+
+
+__all__ = [
+    "NodeHandler",
+    "builtin_handlers",
+    "register_node_handler",
+]

agstack-1.6.0/agstack/llm/flow/nodes/agent_node.py

@@ -0,0 +1,55 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Agent 节点处理器 — 从 flow.py 提取"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from .. import event
+from ..exceptions import FlowError
+from ..registry import registry
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class AgentNodeHandler(NodeHandler):
+    """Agent 节点：通过 registry 查找 agent → ag.stream(context)"""
+
+    node_type = "agent"
+
+    def _set_parameters(self, config: dict, context: "FlowContext") -> None:
+        parameters = config.get("parameters", {})
+        for key, value in parameters.items():
+            resolved = context.resolve_reference(value) if isinstance(value, str) else value
+            context.set_variable(key, resolved)
+
+    def _create_agent(self, config: dict):
+        agent_name = config.get("agent_name")
+        if not agent_name:
+            raise FlowError("MISSING_AGENT_NAME", 400)
+        agent = registry.create_agent(agent_name)
+        if not agent:
+            raise FlowError("AGENT_NOT_FOUND", 404, {"agent_name": agent_name})
+        return agent
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        self._set_parameters(config, context)
+        ag = self._create_agent(config)
+        return await ag.run(context)
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        config = node.get("config", {})
+        step_name = self.get_step_name(node, node_id)
+
+        yield event.step_started(step_name=step_name)
+        self._set_parameters(config, context)
+        ag = self._create_agent(config)
+        async for evt in ag.stream(context):
+            yield evt
+        result = context.get_last_output(ag.name) or ""
+        context.set_node_result(node_id, result)
+        self.map_outputs(config, context, {"result": result})
+        yield event.step_finished(step_name=step_name)

agstack-1.6.0/agstack/llm/flow/nodes/base.py

@@ -0,0 +1,59 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""NodeHandler 基类 — 所有执行类节点的公共接口"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from .. import event
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class NodeHandler:
+    """内置节点处理器基类
+
+    所有执行类节点（agent / tool / python / llm_chat / llm_embed / llm_rerank / detect）
+    都继承此基类，由 Flow 引擎统一分发。
+    """
+
+    node_type: str  # 节点类型标识，子类必须设置
+
+    def get_step_name(self, node: dict, node_id: str) -> str:
+        """step 事件标签，子类可覆盖"""
+        config = node.get("config", {})
+        label = config.get("agent_name") or config.get("tool_name") or node_id
+        return f"{self.node_type}:{label}"
+
+    def resolve_inputs(self, config: dict, context: "FlowContext") -> dict[str, Any]:
+        """解析输入变量引用"""
+        inputs_spec = config.get("inputs", {})
+        return {k: context.resolve_reference(v) if isinstance(v, str) else v for k, v in inputs_spec.items()}
+
+    def map_outputs(self, config: dict, context: "FlowContext", result: dict) -> None:
+        """将结果映射到 context.variables"""
+        for key in config.get("outputs", {}):
+            if isinstance(result, dict) and key in result:
+                context.set_variable(key, result[key])
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        """执行节点，返回结果（将存入 node_results）
+
+        子类必须实现此方法。
+        """
+        raise NotImplementedError
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        """流式执行，产出 AG-UI 事件
+
+        默认实现：产出 step_started，调 execute()，产出 step_finished。
+        需要流式输出的节点（如 agent, llm_chat）应覆盖此方法。
+        """
+        step_name = self.get_step_name(node, node_id)
+        yield event.step_started(step_name=step_name)
+        result = await self.execute(node, context)
+        context.set_node_result(node_id, result)
+        config = node.get("config", {})
+        self.map_outputs(config, context, result)
+        yield event.step_finished(step_name=step_name)

agstack-1.6.0/agstack/llm/flow/nodes/detect_node.py

@@ -0,0 +1,93 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Detect 节点 — 分类/检测，输出路由键"""
+
+import json as _json
+from typing import TYPE_CHECKING, Any
+
+from openai.types.chat import ChatCompletionMessageParam
+
+from ...client import get_llm_client
+from ..context import Usage
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class DetectNodeHandler(NodeHandler):
+    """分类/检测节点
+
+    对输入文本进行分类，输出路由键。结果直接用于 _extract_route_key() 路由。
+
+    输入：query（待检测文本）+ instruction + options
+    输出：{"result": "<option>"} 的 JSON 字符串
+    """
+
+    node_type = "detect"
+
+    def _build_classification_prompt(
+        self, instruction: str, options: list[str], query: str
+    ) -> list[ChatCompletionMessageParam]:
+        options_text = "\n".join(f"- {opt}" for opt in options)
+        system = (
+            "You are a precise classifier. "
+            "Given the user's input and instruction, classify it into exactly one of the provided options. "
+            'Respond with ONLY a JSON object: {"result": "<option>"}. '
+            "Do not include any other text."
+        )
+        user = f"Instruction: {instruction}\n\nOptions:\n{options_text}\n\nInput: {query}"
+        return [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        resolved_inputs = self.resolve_inputs(config, context)
+
+        query = resolved_inputs.get("query", "")
+        instruction = config.get("instruction", "Classify the input")
+        options = config.get("options", [])
+        model = config.get("model", "gpt-4o-mini")
+        temperature = config.get("temperature", 0.0)
+
+        messages = self._build_classification_prompt(instruction, options, query)
+
+        client = get_llm_client()
+        response = await client.chat(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            stream=False,
+        )
+
+        result_text = ""
+        if response.choices:
+            result_text = response.choices[0].message.content or ""
+
+        if response.usage:
+            context.add_usage(
+                Usage(
+                    prompt_tokens=response.usage.prompt_tokens or 0,
+                    completion_tokens=response.usage.completion_tokens or 0,
+                    total_tokens=response.usage.total_tokens or 0,
+                )
+            )
+
+        # 尝试解析为 JSON，确保返回 {"result": "<option>"} 格式
+        try:
+            parsed = _json.loads(result_text)
+            if isinstance(parsed, dict) and "result" in parsed:
+                return _json.dumps(parsed, ensure_ascii=False)
+        except (ValueError, TypeError):
+            pass
+
+        # 如果 LLM 返回的是纯文本选项，包装为标准格式
+        stripped = result_text.strip()
+        if stripped in options:
+            return _json.dumps({"result": stripped}, ensure_ascii=False)
+
+        # 兜底：返回原始文本
+        return _json.dumps({"result": stripped}, ensure_ascii=False)

agstack-1.6.0/agstack/llm/flow/nodes/llm_chat_node.py

@@ -0,0 +1,152 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""LLM Chat 节点 — 单轮 LLM 调用（支持流式/非流式）"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+from uuid import uuid4
+
+from openai.types.chat import ChatCompletionMessageParam
+
+from ...client import get_llm_client
+from .. import event
+from ..context import Usage
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class _SafeFormatDict(dict):
+    """安全的模板变量替换，缺失 key 时保留原始占位符"""
+
+    def __missing__(self, key: str) -> str:
+        return f"{{{key}}}"
+
+
+class LLMChatNodeHandler(NodeHandler):
+    """单轮 LLM 对话节点
+
+    与 agent 的区别：
+    - agent = 多轮对话 + tool use 循环 + 消息历史隔离
+    - llm_chat = 单轮 prompt → response，无状态，更轻量
+    """
+
+    node_type = "llm_chat"
+
+    def _build_prompt(self, config: dict, resolved_inputs: dict[str, Any]) -> str:
+        """将 config.prompt 中的 {var} 占位符替换为 resolved 的输入值"""
+        template = config.get("prompt", "")
+        format_dict = _SafeFormatDict({k: str(v) if not isinstance(v, str) else v for k, v in resolved_inputs.items()})
+        return template.format_map(format_dict)
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        resolved_inputs = self.resolve_inputs(config, context)
+        prompt_text = self._build_prompt(config, resolved_inputs)
+
+        model = config.get("model", "gpt-4o")
+        temperature = config.get("temperature", 0.7)
+        max_tokens = config.get("max_tokens")
+
+        client = get_llm_client()
+        messages: list[ChatCompletionMessageParam] = [{"role": "user", "content": prompt_text}]
+
+        # 如果有 system_prompt，放在前面
+        system_prompt = config.get("system_prompt")
+        if system_prompt:
+            messages.insert(0, {"role": "system", "content": system_prompt})
+
+        response = await client.chat(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=False,
+        )
+
+        result_text = ""
+        if response.choices:
+            result_text = response.choices[0].message.content or ""
+
+        if response.usage:
+            context.add_usage(
+                Usage(
+                    prompt_tokens=response.usage.prompt_tokens or 0,
+                    completion_tokens=response.usage.completion_tokens or 0,
+                    total_tokens=response.usage.total_tokens or 0,
+                )
+            )
+
+        result = {"result": result_text}
+        self.map_outputs(config, context, result)
+        return result_text
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        config = node.get("config", {})
+        use_stream = config.get("stream", False)
+
+        if not use_stream:
+            # 非流式：走默认 execute 路径
+            step_name = self.get_step_name(node, node_id)
+            yield event.step_started(step_name=step_name)
+            result = await self.execute(node, context)
+            context.set_node_result(node_id, result)
+            yield event.step_finished(step_name=step_name)
+            return
+
+        # 流式输出
+        step_name = self.get_step_name(node, node_id)
+        yield event.step_started(step_name=step_name)
+
+        resolved_inputs = self.resolve_inputs(config, context)
+        prompt_text = self._build_prompt(config, resolved_inputs)
+
+        model = config.get("model", "gpt-4o")
+        temperature = config.get("temperature", 0.7)
+        max_tokens = config.get("max_tokens")
+
+        client = get_llm_client()
+        messages: list[ChatCompletionMessageParam] = [{"role": "user", "content": prompt_text}]
+
+        system_prompt = config.get("system_prompt")
+        if system_prompt:
+            messages.insert(0, {"role": "system", "content": system_prompt})
+
+        msg_id = context.message_id or str(uuid4())
+        yield event.text_message_start(message_id=msg_id, role="assistant")
+
+        content_parts: list[str] = []
+        stream_iter = await client.chat(
+            messages=messages,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            stream=True,
+        )
+
+        async for chunk in stream_iter:
+            if not chunk.choices:
+                continue
+            delta = chunk.choices[0].delta
+            if delta.content:
+                content_parts.append(delta.content)
+                yield event.text_message_content(message_id=msg_id, delta=delta.content)
+
+            if chunk.choices[0].finish_reason and chunk.usage:
+                context.add_usage(
+                    Usage(
+                        prompt_tokens=chunk.usage.prompt_tokens or 0,
+                        completion_tokens=chunk.usage.completion_tokens or 0,
+                        total_tokens=chunk.usage.total_tokens or 0,
+                    )
+                )
+
+        yield event.text_message_end(message_id=msg_id)
+
+        result_text = "".join(content_parts)
+        result = {"result": result_text}
+        self.map_outputs(config, context, result)
+        context.set_node_result(node_id, result_text)
+
+        yield event.step_finished(step_name=step_name)

agstack-1.6.0/agstack/llm/flow/nodes/llm_embed_node.py

@@ -0,0 +1,39 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""LLM Embed 节点 — 文本向量化"""
+
+from typing import TYPE_CHECKING, Any
+
+from ...client import get_llm_client
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class LLMEmbedNodeHandler(NodeHandler):
+    """文本向量化节点
+
+    输入：texts（字符串列表或单个字符串）
+    输出：{"embeddings": [[0.1, 0.2, ...], ...]}
+    """
+
+    node_type = "llm_embed"
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        resolved_inputs = self.resolve_inputs(config, context)
+
+        texts = resolved_inputs.get("texts", [])
+        if isinstance(texts, str):
+            texts = [texts]
+
+        model = config.get("model", "bge-m3")
+
+        client = get_llm_client()
+        embeddings = await client.embed(texts=texts, model=model)
+
+        result = {"embeddings": embeddings}
+        self.map_outputs(config, context, result)
+        return result

agstack-1.6.0/agstack/llm/flow/nodes/llm_rerank_node.py

@@ -0,0 +1,49 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""LLM Rerank 节点 — 文档重排序"""
+
+from typing import TYPE_CHECKING, Any
+
+from ...client import get_llm_client
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class LLMRerankNodeHandler(NodeHandler):
+    """文档重排序节点
+
+    输入：query（字符串）+ documents（字符串列表）
+    输出：{"results": [{"index": 0, "score": 0.95, "text": "..."}, ...]}
+    """
+
+    node_type = "llm_rerank"
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        resolved_inputs = self.resolve_inputs(config, context)
+
+        query = resolved_inputs.get("query", "")
+        documents = resolved_inputs.get("documents", [])
+        if isinstance(documents, str):
+            documents = [documents]
+
+        model = config.get("model", "bge-reranker-v2-m3")
+        top_n = config.get("top_n", 10)
+
+        client = get_llm_client()
+        raw_results = await client.rerank(
+            query=query,
+            documents=documents,
+            model=model,
+            top_n=top_n,
+        )
+
+        # raw_results: list[tuple[int, float, str]]
+        results = [{"index": idx, "score": score, "text": text} for idx, score, text in raw_results]
+
+        result = {"results": results}
+        self.map_outputs(config, context, result)
+        return result

agstack-1.5.0/agstack/llm/flow/sandbox.py → agstack-1.6.0/agstack/llm/flow/nodes/python_node.py

@@ -1,16 +1,26 @@
-#  Copyright (c) 2020-2025 XtraVisions, All rights reserved.
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
 
-"""Python 沙箱执行（基于 RestrictedPython）"""
+"""Python 沙箱节点处理器 — 从 sandbox.py 迁入"""
+
+import json as _json
+from typing import TYPE_CHECKING, Any
+
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+# ── 沙箱执行（原 sandbox.py） ──
 
 import builtins
-from typing import Any
 
 from RestrictedPython import compile_restricted, safe_globals
 from RestrictedPython.Eval import default_guarded_getitem, default_guarded_getiter
 from RestrictedPython.Guards import guarded_unpack_sequence, safer_getattr
 
 
-# 白名单内置模块
 _ALLOWED_MODULES = frozenset(
     {
         "json",
@@ -66,3 +76,20 @@ def execute_python_node(code: str, inputs: dict[str, Any]) -> dict[str, Any]:
         raise TypeError(f"main() must return a dict, got {type(result).__name__}")
 
     return result
+
+
+# ── NodeHandler ──
+
+
+class PythonNodeHandler(NodeHandler):
+    """Python 沙箱执行节点"""
+
+    node_type = "python"
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        resolved_inputs = self.resolve_inputs(config, context)
+        code_str = config.get("code", "")
+        py_result = execute_python_node(code_str, resolved_inputs)
+        self.map_outputs(config, context, py_result)
+        return _json.dumps(py_result, ensure_ascii=False)

agstack-1.6.0/agstack/llm/flow/nodes/tool_node.py

@@ -0,0 +1,40 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Tool 节点处理器 — 从 flow.py 提取"""
+
+from typing import TYPE_CHECKING, Any
+
+from ..exceptions import FlowError
+from ..registry import registry
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class ToolNodeHandler(NodeHandler):
+    """Tool 节点：通过 registry 查找 tool → tool.run(context)"""
+
+    node_type = "tool"
+
+    def _set_parameters(self, config: dict, context: "FlowContext") -> None:
+        parameters = config.get("parameters", {})
+        for key, value in parameters.items():
+            resolved = context.resolve_reference(value) if isinstance(value, str) else value
+            context.set_variable(key, resolved)
+
+    def _create_tool(self, config: dict):
+        tool_name = config.get("tool_name")
+        if not tool_name:
+            raise FlowError("MISSING_TOOL_NAME", 400)
+        tool = registry.create_tool(tool_name)
+        if not tool:
+            raise FlowError("TOOL_NOT_FOUND", 404, {"tool_name": tool_name})
+        return tool
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        self._set_parameters(config, context)
+        tool = self._create_tool(config)
+        return await tool.run(context)

agstack-1.6.0/agstack/llm/flow/sandbox.py

@@ -0,0 +1,8 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""向后兼容 — 实际实现已迁移到 nodes/python_node.py"""
+
+from .nodes.python_node import execute_python_node
+
+
+__all__ = ["execute_python_node"]

{agstack-1.5.0 → agstack-1.6.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.5.0
+Version: 1.6.0
 Summary: Production-ready toolkit for building FastAPI and LLM applications
 Author-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>
 Maintainer-email: XtraVisions <gitadmin@xtravisions.com>, Chen Hao <chenhao@xtravisions.com>

{agstack-1.5.0 → agstack-1.6.0}/agstack.egg-info/SOURCES.txt

@@ -44,6 +44,15 @@ agstack/llm/flow/registry.py
 agstack/llm/flow/sandbox.py
 agstack/llm/flow/state.py
 agstack/llm/flow/tool.py
+agstack/llm/flow/nodes/__init__.py
+agstack/llm/flow/nodes/agent_node.py
+agstack/llm/flow/nodes/base.py
+agstack/llm/flow/nodes/detect_node.py
+agstack/llm/flow/nodes/llm_chat_node.py
+agstack/llm/flow/nodes/llm_embed_node.py
+agstack/llm/flow/nodes/llm_rerank_node.py
+agstack/llm/flow/nodes/python_node.py
+agstack/llm/flow/nodes/tool_node.py
 agstack/security/__init__.py
 agstack/security/casbin.py
 agstack/security/crypt.py

{agstack-1.5.0 → agstack-1.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.5.0"
+version = "1.6.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"