agstack 1.22.1__tar.gz → 1.24.0__tar.gz

{agstack-1.22.1 → agstack-1.24.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.22.1
+Version: 1.24.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.22.1 → agstack-1.24.0}/agstack/llm/flow/flow.py

@@ -358,8 +358,19 @@ class Flow:
 
                 elif node_type in self._node_handlers:
                     handler = self._node_handlers[node_type]
-                    result = await handler.execute(node, context)
+                    try:
+                        result = await handler.execute(node, context)
+                    except Exception as e:
+                        iter_target = self._find_iterator_fallback(current_node_id)
+                        if iter_target:
+                            context.set_variable(f"_iter_{iter_target}_error", str(e))
+                            context.set_output(current_node_id, {"error": str(e)})
+                            context.set_variable("_prev_node_id", current_node_id)
+                            current_node_id = iter_target
+                            continue
+                        raise
                     context.set_output(current_node_id, result)
+                    context.set_variable("_prev_node_id", current_node_id)
                     current_node_id = self._resolve_next_node(current_node_id, context)
 
                 else:
@@ -409,6 +420,18 @@ class Flow:
                 )
                 raise NodeExecutionError("UNKNOWN_NODE_TYPE", args={"node_type": node_type})
 
+    def _find_iterator_fallback(self, source_id: str) -> str | None:
+        """查找从 source_id 出发指向 iterator 节点的 edge target"""
+        for edge in self.edges:
+            if edge.get("source") == source_id:
+                target_id: str | None = edge.get("target")
+                if not target_id:
+                    continue
+                target_node = self.get_node_config(target_id)
+                if target_node and target_node.get("type") == "iterator":
+                    return target_id
+        return None
+
     async def _stream_edge_driven(self, context: "FlowContext") -> AsyncIterator[dict[str, Any]]:
         """边驱动流式执行"""
         current_node_id: str | None = self.nodes[0]["id"] if self.nodes else None
@@ -478,9 +501,9 @@ class Flow:
                 step_evt["_echo"] = False
                 yield step_evt
 
-                parallel_qid = context.trace._qualify_id(current_node_id)
+                _pqid: str = context.trace._qualify_id(current_node_id)
 
-                async def _exec_branch(branch_id: str, _parent_qid: str = parallel_qid) -> None:
+                async def _exec_branch(branch_id: str, parent_qid: str) -> None:
                     branch_node = self.get_node_config(branch_id)
                     if not branch_node:
                         return
@@ -494,7 +517,7 @@ class Flow:
                         branch_id,
                         branch_type,
                         inputs=branch_config.get("inputs", {}),
-                        parent_id=_parent_qid,
+                        parent_id=parent_qid,
                     )
                     context.current_node = branch_id
                     try:
@@ -505,7 +528,7 @@ class Flow:
                         context.trace.record_node_end(branch_id, error=str(e))
                         raise
 
-                await asyncio.gather(*[_exec_branch(bid) for bid in branches])
+                await asyncio.gather(*[_exec_branch(bid, _pqid) for bid in branches])
                 merged: dict[str, Any] = {}
                 for bid in branches:
                     branch_result = context.outputs.get(bid, {})
@@ -600,8 +623,32 @@ class Flow:
                     label=config.get("label"),
                 )
 
-                async for evt in self._execute_node_with_retry(node, context, current_node_id):
-                    yield evt
+                # output_mode: "append" — 保存执行前的历史
+                append_mode = config.get("output_mode") == "append"
+                _history: list[Any] = []
+                if append_mode:
+                    _prev_output = context.outputs.get(current_node_id)
+                    _history = list(_prev_output) if isinstance(_prev_output, list) else []
+
+                try:
+                    async for evt in self._execute_node_with_retry(node, context, current_node_id):
+                        yield evt
+                except (NodeExecutionError, Exception) as e:
+                    # 迭代体错误容忍：如果该节点有 edge 指向 iterator，路由回去而非中断 flow
+                    iter_target = self._find_iterator_fallback(current_node_id)
+                    if iter_target:
+                        context.set_variable(f"_iter_{iter_target}_error", str(e))
+                        context.set_output(current_node_id, {"error": str(e)})
+                        context.trace.record_node_end(current_node_id, error=str(e))
+                        context.set_variable("_prev_node_id", current_node_id)
+                        current_node_id = iter_target
+                        continue
+                    raise
+
+                # output_mode: "append" — 合并新输出到历史数组
+                if append_mode:
+                    _history.append(context.outputs.get(current_node_id))
+                    context.outputs[current_node_id] = _history
 
                 # 收集 agent 节点存放的 tool_calls 或通用 execution_records
                 tool_calls = context.get_variable("_last_node_tool_calls")
@@ -622,6 +669,15 @@ class Flow:
                     tool_calls=tool_calls if tool_calls else None,
                     messages=messages,
                 )
+
+                # Iterator state cleanup: done 后清理 state 以支持 external re-entry
+                if node_type == "iterator":
+                    _iter_out = context.outputs.get(current_node_id, {})
+                    if isinstance(_iter_out, dict) and _iter_out.get("done"):
+                        if not config.get("preserve_state", False):
+                            context.set_variable(f"_iter_{current_node_id}", None)
+
+                context.set_variable("_prev_node_id", current_node_id)
                 current_node_id = self._resolve_next_node(current_node_id, context)
 
             else:

{agstack-1.22.1 → agstack-1.24.0}/agstack/llm/flow/nodes/__init__.py

@@ -6,6 +6,7 @@ from .agent_node import AgentNodeHandler
 from .base import NodeHandler
 from .detect_node import DetectNodeHandler
 from .echo_node import EchoNodeHandler
+from .iterator_node import IteratorNodeHandler
 from .llm_chat_node import LLMChatNodeHandler
 from .llm_embed_node import LLMEmbedNodeHandler
 from .llm_rerank_node import LLMRerankNodeHandler
@@ -27,6 +28,7 @@ builtin_handlers: list[NodeHandler] = [
     EchoNodeHandler(),
     SwitchNodeHandler(),
     SubflowNodeHandler(),
+    IteratorNodeHandler(),
 ]
 
 __all__ = [

agstack-1.24.0/agstack/llm/flow/nodes/iterator_node.py

@@ -0,0 +1,160 @@
+#  Copyright (c) 2020-2026 XtraVisions, All rights reserved.
+
+"""Iterator 节点处理器 — 通用迭代原语，管理遍历状态并通过 edge 组合实现路由"""
+
+from typing import TYPE_CHECKING, Any, AsyncIterator
+from uuid import uuid4
+
+from .. import event
+from .base import NodeHandler
+
+
+if TYPE_CHECKING:
+    from ..context import FlowContext
+
+
+class IteratorNodeHandler(NodeHandler):
+    """Iterator 节点：管理数组遍历状态，暴露当前元素供下游引用。
+
+    通过 edge-driven 执行被多次访问：
+    - 首次访问：初始化迭代，暴露第一个元素，走迭代体 edge
+    - Cycle-back：推进 index，继续或走 completion edge
+    """
+
+    node_type = "iterator"
+
+    def _resolve_items(self, config: dict, context: "FlowContext") -> list:
+        items_ref = config.get("items", "")
+        items = context.resolve_reference(items_ref) if isinstance(items_ref, str) else items_ref
+        if items is None:
+            return []
+        if not isinstance(items, list):
+            return [items]
+        return items
+
+    def _set_item_output(self, node_id: str, state: dict, config: dict, context: "FlowContext") -> None:
+        idx = state["index"]
+        context.set_output(
+            node_id,
+            {
+                "current_item": state["items"][idx],
+                "index": idx,
+                "count": len(state["items"]),
+                "done": False,
+            },
+        )
+
+    def _set_done_output(self, node_id: str, state: dict, config: dict, context: "FlowContext") -> None:
+        context.set_output(
+            node_id,
+            {
+                "done": True,
+                "count": len(state["items"]),
+            },
+        )
+
+    def _build_event(
+        self, config: dict, event_key: str, state: dict, *, error: str | None = None
+    ) -> dict[str, Any] | None:
+        events_config = config.get("events")
+        if not events_config:
+            return None
+        evt_cfg = events_config.get(event_key)
+        if not evt_cfg:
+            return None
+
+        name = evt_cfg.get("name", event_key)
+        value_template = evt_cfg.get("value", {})
+        value = self._interpolate_event_value(value_template, state, error=error)
+        return event.custom(name=name, value=value)
+
+    def _interpolate_event_value(self, template: Any, state: dict, *, error: str | None = None) -> Any:
+        if isinstance(template, str):
+            if template == "$items":
+                return state["items"]
+            if template == "$index":
+                return state["index"]
+            if template == "$item":
+                return state["items"][state["index"]] if state["index"] < len(state["items"]) else None
+            if template == "$count":
+                return len(state["items"])
+            if template == "$error":
+                return error
+            return template
+        if isinstance(template, dict):
+            return {k: self._interpolate_event_value(v, state, error=error) for k, v in template.items()}
+        if isinstance(template, list):
+            return [self._interpolate_event_value(v, state, error=error) for v in template]
+        return template
+
+    async def execute(self, node: dict, context: "FlowContext") -> Any:
+        config = node.get("config", {})
+        items = self._resolve_items(config, context)
+        return {"done": True, "count": len(items), "current_item": None, "index": 0}
+
+    async def stream(self, node: dict, context: "FlowContext", node_id: str) -> AsyncIterator[dict[str, Any]]:
+        config = node.get("config", {})
+        state_key = f"_iter_{node_id}"
+        step_name = self.get_step_name(node, node_id)
+
+        state = context.get_variable(state_key)
+
+        if state is None:
+            # ═══ 首次访问（或 re-entry 后重新初始化）═══
+            items = self._resolve_items(config, context)
+            state = {"items": items, "index": 0}
+            context.set_variable(state_key, state)
+
+            sid = str(uuid4())
+            yield event.step_started(step_name=step_name, step_id=sid)
+
+            evt = self._build_event(config, "on_start", state)
+            if evt:
+                yield evt
+
+            if not items:
+                self._set_done_output(node_id, state, config, context)
+                yield event.step_finished(step_name=step_name, step_id=sid)
+                return
+
+            self._set_item_output(node_id, state, config, context)
+            evt = self._build_event(config, "on_item_start", state)
+            if evt:
+                yield evt
+
+            yield event.step_finished(step_name=step_name, step_id=sid)
+
+        else:
+            # ═══ Cycle-back：推进 index ═══
+            sid = str(uuid4())
+            yield event.step_started(step_name=step_name, step_id=sid)
+
+            error = context.get_variable(f"_iter_{node_id}_error")
+
+            if error:
+                evt = self._build_event(config, "on_item_error", state, error=error)
+                if evt:
+                    yield evt
+                context.set_variable(f"_iter_{node_id}_error", None)
+            else:
+                evt = self._build_event(config, "on_item_end", state)
+                if evt:
+                    yield evt
+
+            state["index"] += 1
+            max_iter = config.get("max_iterations")
+
+            if state["index"] >= len(state["items"]) or (max_iter and state["index"] >= max_iter):
+                self._set_done_output(node_id, state, config, context)
+                yield event.step_finished(step_name=step_name, step_id=sid)
+                return
+
+            self._set_item_output(node_id, state, config, context)
+            evt = self._build_event(config, "on_item_start", state)
+            if evt:
+                yield evt
+
+            yield event.step_finished(step_name=step_name, step_id=sid)
+
+    def get_step_name(self, node: dict, node_id: str) -> str:
+        return f"iterator:{node_id}"

{agstack-1.22.1 → agstack-1.24.0}/agstack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agstack
-Version: 1.22.1
+Version: 1.24.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.22.1 → agstack-1.24.0}/agstack.egg-info/SOURCES.txt

@@ -53,6 +53,7 @@ agstack/llm/flow/nodes/agent_node.py
 agstack/llm/flow/nodes/base.py
 agstack/llm/flow/nodes/detect_node.py
 agstack/llm/flow/nodes/echo_node.py
+agstack/llm/flow/nodes/iterator_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
@@ -70,6 +71,7 @@ agstack/security/crypt.py
 tests/test_cache_memory.py
 tests/test_cache_redis.py
 tests/test_flow_io.py
+tests/test_flow_iterator.py
 tests/test_flow_switch_subflow.py
 tests/test_messagebus_memory.py
 tests/test_messagebus_redis.py

{agstack-1.22.1 → agstack-1.24.0}/pyproject.toml

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