agstack 1.9.0__tar.gz → 1.10.0__tar.gz

{agstack-1.9.0 → agstack-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.9.0
+Version: 1.10.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>
@@ -20,23 +20,23 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aio-pika>=9.6.1
+Requires-Dist: aio-pika>=9.6.2
 Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: elasticsearch[async]>=9.3.0
-Requires-Dist: fastapi>=0.133.1
-Requires-Dist: jwcrypto>=1.5.6
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: jwcrypto>=1.5.7
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: nebula3-python>=3.8.3
-Requires-Dist: openai>=2.28.0
+Requires-Dist: openai>=2.34.0
 Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: pycasbin>=2.8.0
-Requires-Dist: pydantic>=2.12.4
-Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: python-multipart>=0.0.26
 Requires-Dist: requests>=2.32.5
 Requires-Dist: RestrictedPython>=7.0
-Requires-Dist: sqlobjects>=1.9.0
+Requires-Dist: sqlobjects>=1.9.1
 Requires-Dist: tiktoken>=0.12.0
-Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: uvicorn>=0.46.0
 Dynamic: license-file
 
 # AgStack

{agstack-1.9.0 → agstack-1.10.0}/agstack/llm/flow/nodes/__init__.py

@@ -9,6 +9,8 @@ from .llm_chat_node import LLMChatNodeHandler
 from .llm_embed_node import LLMEmbedNodeHandler
 from .llm_rerank_node import LLMRerankNodeHandler
 from .python_node import PythonNodeHandler
+from .subflow_node import SubflowNodeHandler
+from .switch_node import SwitchNodeHandler
 from .tool_node import ToolNodeHandler
 
 
@@ -21,6 +23,8 @@ builtin_handlers: list[NodeHandler] = [
     LLMEmbedNodeHandler(),
     LLMRerankNodeHandler(),
     DetectNodeHandler(),
+    SwitchNodeHandler(),
+    SubflowNodeHandler(),
 ]
 
 __all__ = [

agstack-1.10.0/agstack/llm/flow/nodes/subflow_node.py

@@ -0,0 +1,74 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Subflow 节点 — 引用并执行另一个 Flow 配置，实现流程复用"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from ..exceptions import FlowError
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class SubflowNodeHandler(NodeHandler):
+    """子流程节点
+
+    通过 flow_name 加载另一个 Flow 实例，在当前 FlowContext 上执行。
+    子 flow 与父 flow 共享同一个 FlowContext。
+    """
+
+    node_type = "subflow"
+
+    def _load_subflow(self, config: dict):
+        """加载子 flow 实例"""
+        from ..loader import FlowLoader
+        from ..registry import registry
+
+        flow_name = config.get("flow_name", "")
+
+        # 优先从 registry 获取已注册的 flow
+        sub_flow = registry.create_flow(flow_name)
+        if sub_flow is not None:
+            return sub_flow
+
+        # 其次从内联配置加载
+        flow_config = config.get("flow_config")
+        if flow_config is not None:
+            return FlowLoader.load_from_dict(flow_config)
+
+        raise FlowError("SUBFLOW_NOT_FOUND", args={"flow_name": flow_name})
+
+    def _resolve_and_apply_inputs(self, config: dict, context: "FlowContext") -> None:
+        """解析 inputs 并更新 context.variables"""
+        inputs_spec = config.get("inputs", {})
+        for key, ref in inputs_spec.items():
+            value = context.resolve_reference(ref) if isinstance(ref, str) else ref
+            context.set_variable(key, value)
+
+    def _get_last_node_output(self, sub_flow, context: "FlowContext") -> Any:
+        """获取子 flow 最后一个节点的输出"""
+        if sub_flow.nodes:
+            last_node_id = sub_flow.nodes[-1].get("id")
+            if last_node_id and last_node_id in context.outputs:
+                return context.outputs[last_node_id]
+        return context.outputs
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        self._resolve_and_apply_inputs(config, context)
+        sub_flow = self._load_subflow(config)
+        await sub_flow.run(context)
+        return self._get_last_node_output(sub_flow, context)
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        config = node.get("config", {})
+        self._resolve_and_apply_inputs(config, context)
+        sub_flow = self._load_subflow(config)
+
+        async for evt in sub_flow.stream(context):
+            yield evt
+
+        result = self._get_last_node_output(sub_flow, context)
+        context.set_output(node_id, result)

agstack-1.10.0/agstack/llm/flow/nodes/switch_node.py

@@ -0,0 +1,41 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Switch 节点 — 纯变量匹配路由，零 LLM 调用开销"""
+
+from typing import TYPE_CHECKING, Any
+
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class SwitchNodeHandler(NodeHandler):
+    """条件路由节点
+
+    读取 flow 变量值，与 cases 映射表匹配，返回路由键。
+    用于根据系统配置在运行时选择不同执行路径。
+
+    输出：{"choice": "<matched_case>"}
+    """
+
+    node_type = "switch"
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        variable_ref = config.get("variable", "")
+        cases: dict[str, str] = config.get("cases", {})
+        default = config.get("default")
+
+        value = context.resolve_reference(variable_ref)
+        value_str = str(value) if value is not None else ""
+
+        if value_str in cases:
+            choice = value_str
+        elif default is not None:
+            choice = default
+        else:
+            choice = value_str
+
+        return {"choice": choice}

{agstack-1.9.0 → agstack-1.10.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.9.0
+Version: 1.10.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>
@@ -20,23 +20,23 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aio-pika>=9.6.1
+Requires-Dist: aio-pika>=9.6.2
 Requires-Dist: asyncpg>=0.30.0
 Requires-Dist: elasticsearch[async]>=9.3.0
-Requires-Dist: fastapi>=0.133.1
-Requires-Dist: jwcrypto>=1.5.6
+Requires-Dist: fastapi>=0.136.1
+Requires-Dist: jwcrypto>=1.5.7
 Requires-Dist: loguru>=0.7.3
 Requires-Dist: nebula3-python>=3.8.3
-Requires-Dist: openai>=2.28.0
+Requires-Dist: openai>=2.34.0
 Requires-Dist: bcrypt>=4.0.0
 Requires-Dist: pycasbin>=2.8.0
-Requires-Dist: pydantic>=2.12.4
-Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: pydantic>=2.13.3
+Requires-Dist: python-multipart>=0.0.26
 Requires-Dist: requests>=2.32.5
 Requires-Dist: RestrictedPython>=7.0
-Requires-Dist: sqlobjects>=1.9.0
+Requires-Dist: sqlobjects>=1.9.1
 Requires-Dist: tiktoken>=0.12.0
-Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: uvicorn>=0.46.0
 Dynamic: license-file
 
 # AgStack

{agstack-1.9.0 → agstack-1.10.0}/agstack.egg-info/SOURCES.txt

@@ -51,8 +51,11 @@ 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/subflow_node.py
+agstack/llm/flow/nodes/switch_node.py
 agstack/llm/flow/nodes/tool_node.py
 agstack/security/__init__.py
 agstack/security/casbin.py
 agstack/security/crypt.py
-tests/test_flow_io.py
+tests/test_flow_io.py
+tests/test_flow_switch_subflow.py

{agstack-1.9.0 → agstack-1.10.0}/agstack.egg-info/requires.txt

@@ -1,17 +1,17 @@
-aio-pika>=9.6.1
+aio-pika>=9.6.2
 asyncpg>=0.30.0
 elasticsearch[async]>=9.3.0
-fastapi>=0.133.1
-jwcrypto>=1.5.6
+fastapi>=0.136.1
+jwcrypto>=1.5.7
 loguru>=0.7.3
 nebula3-python>=3.8.3
-openai>=2.28.0
+openai>=2.34.0
 bcrypt>=4.0.0
 pycasbin>=2.8.0
-pydantic>=2.12.4
-python-multipart>=0.0.20
+pydantic>=2.13.3
+python-multipart>=0.0.26
 requests>=2.32.5
 RestrictedPython>=7.0
-sqlobjects>=1.9.0
+sqlobjects>=1.9.1
 tiktoken>=0.12.0
-uvicorn>=0.41.0
+uvicorn>=0.46.0

{agstack-1.9.0 → agstack-1.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agstack"
-version = "1.9.0"
+version = "1.10.0"
 description = "Production-ready toolkit for building FastAPI and LLM applications"
 readme = "README.md"
 license = "MIT"
@@ -39,30 +39,30 @@ classifiers = [
 ]
 requires-python = ">=3.12"
 dependencies = [
-    "aio-pika>=9.6.1",
+    "aio-pika>=9.6.2",
     "asyncpg>=0.30.0",
     "elasticsearch[async]>=9.3.0",
-    "fastapi>=0.133.1",
-    "jwcrypto>=1.5.6",
+    "fastapi>=0.136.1",
+    "jwcrypto>=1.5.7",
     "loguru>=0.7.3",
     "nebula3-python>=3.8.3",
-    "openai>=2.28.0",
+    "openai>=2.34.0",
     "bcrypt>=4.0.0",
     "pycasbin>=2.8.0",
-    "pydantic>=2.12.4",
-    "python-multipart>=0.0.20",
+    "pydantic>=2.13.3",
+    "python-multipart>=0.0.26",
     "requests>=2.32.5",
     "RestrictedPython>=7.0",
-    "sqlobjects>=1.9.0",
+    "sqlobjects>=1.9.1",
     "tiktoken>=0.12.0",
-    "uvicorn>=0.41.0",
+    "uvicorn>=0.46.0",
 ]
 [dependency-groups]
 dev = [
-    "pre-commit>=4.4.0",
-    "pyright>=1.1.407",
-    "pytest>=9.0.2",
-    "ruff>=0.15.5",
+    "pre-commit>=4.6.0",
+    "pyright>=1.1.409",
+    "pytest>=9.0.3",
+    "ruff>=0.15.12",
     "setuptools>=82.0.0",
 ]
 

agstack-1.10.0/tests/test_flow_switch_subflow.py

@@ -0,0 +1,340 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Switch 和 Subflow 节点测试"""
+
+import asyncio
+
+import pytest
+
+from agstack.llm.flow.context import FlowContext
+from agstack.llm.flow.flow import Flow
+from agstack.llm.flow.nodes.subflow_node import SubflowNodeHandler
+from agstack.llm.flow.nodes.switch_node import SwitchNodeHandler
+
+
+def run(coro):
+    return asyncio.get_event_loop().run_until_complete(coro)
+
+
+# ── Switch 节点 ──
+
+
+class TestSwitchNode:
+    """switch 节点单元测试"""
+
+    def setup_method(self):
+        self.handler = SwitchNodeHandler()
+
+    def test_match_case(self):
+        """正常匹配 cases 中的值"""
+        ctx = FlowContext(variables={"model_tier": "strong"})
+        node = {
+            "id": "sw1",
+            "type": "switch",
+            "config": {
+                "variable": "$v.model_tier",
+                "cases": {"strong": "research_agent", "basic": "research_pipeline"},
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"choice": "strong"}
+
+    def test_no_match_with_default(self):
+        """未匹配时使用 default"""
+        ctx = FlowContext(variables={"model_tier": "unknown"})
+        node = {
+            "id": "sw1",
+            "type": "switch",
+            "config": {
+                "variable": "$v.model_tier",
+                "cases": {"strong": "research_agent", "basic": "research_pipeline"},
+                "default": "basic",
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"choice": "basic"}
+
+    def test_no_match_no_default(self):
+        """未匹配且无 default 时使用变量原始值"""
+        ctx = FlowContext(variables={"model_tier": "medium"})
+        node = {
+            "id": "sw1",
+            "type": "switch",
+            "config": {
+                "variable": "$v.model_tier",
+                "cases": {"strong": "research_agent", "basic": "research_pipeline"},
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"choice": "medium"}
+
+    def test_none_variable(self):
+        """变量值为 None 时转为空字符串"""
+        ctx = FlowContext()
+        node = {
+            "id": "sw1",
+            "type": "switch",
+            "config": {
+                "variable": "$v.missing",
+                "cases": {"strong": "a"},
+                "default": "fallback",
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"choice": "fallback"}
+
+    def test_integer_variable(self):
+        """整数变量转为字符串后匹配"""
+        ctx = FlowContext(variables={"level": 2})
+        node = {
+            "id": "sw1",
+            "type": "switch",
+            "config": {
+                "variable": "$v.level",
+                "cases": {"1": "low", "2": "mid", "3": "high"},
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"choice": "2"}
+
+    def test_node_type(self):
+        assert self.handler.node_type == "switch"
+
+
+# ── Subflow 节点 ──
+
+
+class TestSubflowNode:
+    """subflow 节点单元测试"""
+
+    def setup_method(self):
+        self.handler = SubflowNodeHandler()
+
+    def test_subflow_executes_child_flow(self):
+        """子 flow 正常执行并返回结果"""
+        child_flow = Flow(
+            flow_id="child_1",
+            name="simple_flow",
+            nodes=[
+                {
+                    "id": "py1",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'answer': 42}"},
+                },
+            ],
+            edges=[],
+        )
+
+        from agstack.llm.flow.registry import registry
+
+        registry._flows["simple_flow"] = lambda **kwargs: child_flow
+
+        try:
+            ctx = FlowContext()
+            node = {
+                "id": "sub1",
+                "type": "subflow",
+                "config": {"flow_name": "simple_flow"},
+            }
+            result = run(self.handler.execute(node, ctx))
+            assert result == {"answer": 42}
+        finally:
+            registry._flows.pop("simple_flow", None)
+
+    def test_subflow_with_inputs(self):
+        """子 flow 接收 inputs 参数"""
+        child_flow = Flow(
+            flow_id="child_2",
+            name="echo_flow",
+            nodes=[
+                {
+                    "id": "py1",
+                    "type": "python",
+                    "config": {
+                        "code": "def main(**kwargs):\n    return {'echo': kwargs.get('query', '')}",
+                        "inputs": {"query": "$v.query"},
+                    },
+                },
+            ],
+            edges=[],
+        )
+
+        from agstack.llm.flow.registry import registry
+
+        registry._flows["echo_flow"] = lambda **kwargs: child_flow
+
+        try:
+            ctx = FlowContext(variables={"user_query": "hello world"})
+            node = {
+                "id": "sub1",
+                "type": "subflow",
+                "config": {
+                    "flow_name": "echo_flow",
+                    "inputs": {"query": "$v.user_query"},
+                },
+            }
+            result = run(self.handler.execute(node, ctx))
+            assert result == {"echo": "hello world"}
+            assert ctx.variables["query"] == "hello world"
+        finally:
+            registry._flows.pop("echo_flow", None)
+
+    def test_subflow_not_found(self):
+        """找不到子 flow 时抛出 FlowError"""
+        from agstack.llm.flow.exceptions import FlowError
+
+        ctx = FlowContext()
+        node = {
+            "id": "sub1",
+            "type": "subflow",
+            "config": {"flow_name": "nonexistent_flow"},
+        }
+        with pytest.raises(FlowError):
+            run(self.handler.execute(node, ctx))
+
+    def test_subflow_inline_config(self):
+        """通过内联 flow_config 加载子 flow"""
+        ctx = FlowContext()
+        node = {
+            "id": "sub1",
+            "type": "subflow",
+            "config": {
+                "flow_name": "not_registered",
+                "flow_config": {
+                    "flow_id": "inline_1",
+                    "name": "inline_flow",
+                    "nodes": [
+                        {
+                            "id": "py1",
+                            "type": "python",
+                            "config": {"code": "def main(**kwargs):\n    return {'inline': True}"},
+                        },
+                    ],
+                    "edges": [],
+                },
+            },
+        }
+        result = run(self.handler.execute(node, ctx))
+        assert result == {"inline": True}
+
+    def test_subflow_stream(self):
+        """流式执行子 flow 并透传事件"""
+        child_flow = Flow(
+            flow_id="child_s",
+            name="stream_flow",
+            nodes=[
+                {
+                    "id": "py1",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'streamed': True}"},
+                },
+            ],
+            edges=[{"source": "py1", "target": None}],
+        )
+
+        from agstack.llm.flow.registry import registry
+
+        registry._flows["stream_flow"] = lambda **kwargs: child_flow
+
+        try:
+            ctx = FlowContext()
+            node = {
+                "id": "sub1",
+                "type": "subflow",
+                "config": {"flow_name": "stream_flow"},
+            }
+
+            async def collect():
+                events = []
+                async for evt in self.handler.stream(node, ctx, "sub1"):
+                    events.append(evt)
+                return events
+
+            events = run(collect())
+            assert len(events) > 0
+            assert ctx.outputs["sub1"] == {"streamed": True}
+        finally:
+            registry._flows.pop("stream_flow", None)
+
+    def test_node_type(self):
+        assert self.handler.node_type == "subflow"
+
+
+# ── 集成测试：switch + edge 路由 ──
+
+
+class TestSwitchEdgeRouting:
+    """switch 节点与 edge 路由集成测试"""
+
+    def test_switch_routes_to_correct_branch(self):
+        """switch 节点路由到正确的下游节点"""
+        flow = Flow(
+            flow_id="test_flow",
+            name="switch_routing",
+            nodes=[
+                {
+                    "id": "model_switch",
+                    "type": "switch",
+                    "config": {
+                        "variable": "$v.model_tier",
+                        "cases": {"strong": "agent_a", "basic": "pipeline_b"},
+                        "default": "pipeline_b",
+                    },
+                },
+                {
+                    "id": "agent_a",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'path': 'strong_path'}"},
+                },
+                {
+                    "id": "pipeline_b",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'path': 'basic_path'}"},
+                },
+            ],
+            edges=[
+                {"source": "model_switch", "target": "agent_a", "condition": "strong"},
+                {"source": "model_switch", "target": "pipeline_b", "condition": "basic"},
+            ],
+        )
+
+        ctx = FlowContext(variables={"model_tier": "strong"})
+        run(flow.run(ctx))
+        assert ctx.outputs["agent_a"] == {"path": "strong_path"}
+        assert "pipeline_b" not in ctx.outputs
+
+    def test_switch_routes_default(self):
+        """switch 节点 default 分支路由"""
+        flow = Flow(
+            flow_id="test_flow",
+            name="switch_default",
+            nodes=[
+                {
+                    "id": "sw",
+                    "type": "switch",
+                    "config": {
+                        "variable": "$v.tier",
+                        "cases": {"a": "node_a", "b": "node_b"},
+                        "default": "b",
+                    },
+                },
+                {
+                    "id": "node_a",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'path': 'a'}"},
+                },
+                {
+                    "id": "node_b",
+                    "type": "python",
+                    "config": {"code": "def main(**kwargs):\n    return {'path': 'b'}"},
+                },
+            ],
+            edges=[
+                {"source": "sw", "target": "node_a", "condition": "a"},
+                {"source": "sw", "target": "node_b", "condition": "b"},
+            ],
+        )
+
+        ctx = FlowContext(variables={"tier": "unknown"})
+        run(flow.run(ctx))
+        assert ctx.outputs["node_b"] == {"path": "b"}