stageflow-framework 0.1.0__py3-none-any.whl

stageflow/__init__.py

@@ -0,0 +1,25 @@
+from .core import (
+    Event, EventSpec, InputSpec,
+    JsonLogic,
+    Node, ConditionNode, Condition, ParallelNode, TerminalNode, StageNode,
+    Session, SessionResult,
+    BaseStage, get_stage, register_stage, get_stages, get_stages_by_category,
+    Context, DotDict,
+    Pipeline,
+)
+
+from .docs import generate_stages_yaml, generate_stages_json
+from . import builtins
+
+
+__all__ = [
+    "Event", "EventSpec", "InputSpec",
+    "JsonLogic",
+    "Node", "ConditionNode", "Condition", "ParallelNode", "TerminalNode", "StageNode",
+    "Session", "SessionResult",
+    "BaseStage", "get_stage", "register_stage", "get_stages", "get_stages_by_category",
+    "Context", "DotDict",
+    "Pipeline",
+    "generate_stages_yaml", "generate_stages_json",
+    "builtins",
+]

stageflow/builtins/__init__.py

@@ -0,0 +1,34 @@
+from .vars import (
+    SetValueStage,
+    CopyValueStage,
+    IncrementStage,
+    MergeDictStage,
+)
+from .lists import (
+    AppendListStage,
+    ExtendListStage,
+)
+from .logic import AssertStage, FailStage, LogStage, SleepStage
+from .strings import ConcatStage, TemplateStage
+from .dicts import PickKeysStage, DropKeysStage
+from .lists_extra import FilterListStage, UniqueListStage, PopListStage
+
+__all__ = [
+    "SetValueStage",
+    "CopyValueStage",
+    "IncrementStage",
+    "MergeDictStage",
+    "AppendListStage",
+    "ExtendListStage",
+    "AssertStage",
+    "FailStage",
+    "LogStage",
+    "SleepStage",
+    "ConcatStage",
+    "TemplateStage",
+    "PickKeysStage",
+    "DropKeysStage",
+    "FilterListStage",
+    "UniqueListStage",
+    "PopListStage",
+]

stageflow/builtins/dicts.py

@@ -0,0 +1,59 @@
+from stageflow.core.stage import BaseStage, register_stage
+
+
+@register_stage("PickKeysStage")
+class PickKeysStage(BaseStage):
+    """
+    description: "Pick only specified keys from a dict and return new object"
+    arguments:
+      src:
+        type: object
+        description: "Source dict"
+    config:
+      keys:
+        type: list
+        description: "Keys to keep in the result"
+    outputs:
+      result:
+        type: object
+        description: "Dict containing only picked keys"
+    """
+    category = "builtin.dicts"
+
+    async def run(self):
+        args = self.get_arguments()
+        src_val = args.get("src") or {}
+        keys = self.config.get("keys", [])
+        if not isinstance(src_val, dict):
+            raise ValueError("PickKeysStage expects dict in arguments.src")
+        picked = {k: src_val[k] for k in keys if k in src_val}
+        self.set_outputs({"result": picked})
+
+
+@register_stage("DropKeysStage")
+class DropKeysStage(BaseStage):
+    """
+    description: "Remove specified keys from dict and return cleaned object"
+    arguments:
+      src:
+        type: object
+        description: "Source dict"
+    config:
+      keys:
+        type: list
+        description: "Keys to remove from the dict"
+    outputs:
+      result:
+        type: object
+        description: "Dict without removed keys"
+    """
+    category = "builtin.dicts"
+
+    async def run(self):
+        args = self.get_arguments()
+        keys = set(self.config.get("keys", []))
+        src_val = args.get("src") or {}
+        if not isinstance(src_val, dict):
+            raise ValueError("DropKeysStage expects dict in arguments.src")
+        cleaned = {k: v for k, v in src_val.items() if k not in keys}
+        self.set_outputs({"result": cleaned})

stageflow/builtins/lists.py

@@ -0,0 +1,71 @@
+from stageflow.core.stage import BaseStage, register_stage
+
+
+@register_stage("AppendListStage")
+class AppendListStage(BaseStage):
+    """
+    description: "Append value from args/config to list (creates list if missing)"
+    arguments:
+      list:
+        type: list
+        description: "List to append to (from context)"
+      value:
+        type: any
+        description: "Value to append (overrides config)"
+    config:
+      value:
+        type: any
+        description: "Fallback value when argument is missing"
+    outputs:
+      list:
+        type: list
+        description: "Resulting list after append"
+    """
+    category = "builtin.lists"
+
+    async def run(self):
+        args = self.get_arguments()
+        value = args.get("value", self.config.get("value"))
+        lst = args.get("list", None)
+        if lst is None:
+            lst = []
+        if not isinstance(lst, list):
+            raise ValueError("AppendListStage expects list")
+        lst.append(value)
+        self.set_outputs({"list": lst})
+
+
+@register_stage("ExtendListStage")
+class ExtendListStage(BaseStage):
+    """
+    description: "Extend list with items from arguments (or default list)"
+    arguments:
+      list:
+        type: list
+        description: "Base list to extend"
+      items:
+        type: list
+        description: "Items to extend the list with"
+    config:
+      default_list:
+        type: list
+        description: "Fallback list when argument is missing"
+    outputs:
+      list:
+        type: list
+        description: "Resulting list after extend"
+    """
+    category = "builtin.lists"
+
+    async def run(self):
+        args = self.get_arguments()
+        lst = args.get("list", self.config.get("default_list", []))
+        if lst is None:
+            lst = []
+        if not isinstance(lst, list):
+            raise ValueError("ExtendListStage expects list")
+        src_val = args.get("items", [])
+        if not isinstance(src_val, (list, tuple)):
+            raise ValueError("Source for extend is not a list/tuple")
+        lst.extend(src_val)
+        self.set_outputs({"list": lst})

stageflow/builtins/lists_extra.py

@@ -0,0 +1,110 @@
+from stageflow.core.stage import BaseStage, register_stage
+from stageflow.core.jsonlogic import JsonLogic
+from stageflow.core.context import Context
+
+
+@register_stage("FilterListStage")
+class FilterListStage(BaseStage):
+    """
+    description: "Filter list items by JsonLogic condition using item_path binding"
+    arguments:
+      items:
+        type: list
+        description: "List to filter"
+    config:
+      condition:
+        type: object
+        description: "JsonLogic condition evaluated for each item"
+      item_path:
+        type: string
+        description: "Context key to bind current item during evaluation"
+    outputs:
+      list:
+        type: list
+        description: "Filtered list"
+    """
+    category = "builtin.lists"
+
+    async def run(self):
+        args = self.get_arguments()
+        condition = self.config.get("condition")
+        item_path = self.config.get("item_path", "item")
+        if condition is None:
+            raise ValueError("FilterListStage requires config.condition")
+        items = args.get("items", [])
+        if not isinstance(items, list):
+            raise ValueError("FilterListStage expects list in arguments.items")
+        base_payload = self.session.context.payload
+        result = []
+        for item in items:
+            temp_ctx = Context(payload=dict(base_payload))
+            temp_ctx.set(item_path, item)
+            if JsonLogic(condition).evaluate(temp_ctx):
+                result.append(item)
+        self.set_outputs({"list": result})
+
+
+@register_stage("UniqueListStage")
+class UniqueListStage(BaseStage):
+    """
+    description: "Deduplicate list while preserving original order"
+    arguments:
+      items:
+        type: list
+        description: "List to deduplicate"
+    outputs:
+      list:
+        type: list
+        description: "List with unique items"
+    """
+    category = "builtin.lists"
+
+    async def run(self):
+        args = self.get_arguments()
+        items = args.get("items", [])
+        if not isinstance(items, list):
+            raise ValueError("UniqueListStage expects list in arguments.items")
+        seen = set()
+        out = []
+        for item in items:
+            if item not in seen:
+                seen.add(item)
+                out.append(item)
+        self.set_outputs({"list": out})
+
+
+@register_stage("PopListStage")
+class PopListStage(BaseStage):
+    """
+    description: "Pop element from list (default last) and return list+popped value"
+    arguments:
+      items:
+        type: list
+        description: "List to pop from"
+      index:
+        type: int
+        description: "Index to pop (overrides config)"
+    config:
+      index:
+        type: int
+        description: "Default index to pop, -1 means last element"
+    outputs:
+      list:
+        type: list
+        description: "List after pop"
+      popped:
+        type: any
+        description: "Popped value"
+    """
+    category = "builtin.lists"
+
+    async def run(self):
+        args = self.get_arguments()
+        index = args.get("index", self.config.get("index", -1))
+        lst = args.get("items", [])
+        if not isinstance(lst, list):
+            raise ValueError("PopListStage expects list in arguments.items")
+        if not lst:
+            return
+        value = lst.pop(index)
+        self.set_outputs({"list": lst, "popped": value})

stageflow/builtins/logic.py

@@ -0,0 +1,84 @@
+import asyncio
+from stageflow.core.stage import BaseStage, register_stage
+from stageflow.core.jsonlogic import JsonLogic
+
+
+@register_stage("AssertStage")
+class AssertStage(BaseStage):
+    """
+    description: "Validate JsonLogic condition against context, raise on failure"
+    config:
+      condition:
+        type: object
+        description: "JsonLogic condition to check"
+      message:
+        type: string
+        description: "Error message when condition fails"
+    outputs: {}
+    """
+    category = "builtin.logic"
+
+    async def run(self):
+        condition = self.config.get("condition")
+        if not condition:
+            raise ValueError("AssertStage requires config.condition")
+        ok = JsonLogic(condition).evaluate(self.session.context)
+        if not ok:
+            raise AssertionError(self.config.get("message", "assertion failed"))
+
+
+@register_stage("FailStage")
+class FailStage(BaseStage):
+    """
+    description: "Always raise a runtime error with provided message"
+    config:
+      message:
+        type: string
+        description: "Message for raised error"
+    outputs: {}
+    """
+    category = "builtin.logic"
+
+    async def run(self):
+        msg = self.config.get("message", "fail")
+        raise RuntimeError(msg)
+
+
+@register_stage("LogStage")
+class LogStage(BaseStage):
+    """
+    description: "Emit log event with message and payload resolved from context paths"
+    config:
+      message:
+        type: string
+        description: "Log message"
+      paths:
+        type: object
+        description: "Mapping of payload fields to context paths"
+    outputs: {}
+    """
+    category = "builtin.logic"
+
+    async def run(self):
+        payload = {"message": self.config.get("message", "")}
+        paths = self.config.get("paths", {})
+        for key, path in paths.items():
+            payload[key] = self.session.context.get(path)
+        self.emit("log", payload)
+
+
+@register_stage("SleepStage")
+class SleepStage(BaseStage):
+    """
+    description: "Async sleep for configured number of seconds"
+    config:
+      seconds:
+        type: number
+        description: "Duration to sleep in seconds"
+    outputs: {}
+    """
+    category = "builtin.logic"
+
+    async def run(self):
+        sec = self.config.get("seconds", 0)
+        await asyncio.sleep(sec)

stageflow/builtins/strings.py

@@ -0,0 +1,81 @@
+from stageflow.core.stage import BaseStage, register_stage
+
+
+@register_stage("ConcatStage")
+class ConcatStage(BaseStage):
+    """
+    description: "Concatenate parts (values or context paths) with separator"
+    arguments:
+      parts:
+        type: list
+        description: "List of values or context paths to concatenate"
+      separator:
+        type: string
+        description: "Separator overriding config"
+    config:
+      parts:
+        type: list
+        description: "Default parts when argument is missing"
+      separator:
+        type: string
+        description: "Default separator"
+      output_key:
+        type: string
+        description: "Context key for resulting string"
+    outputs:
+      value:
+        type: string
+        description: "Concatenated string"
+    """
+    category = "builtin.strings"
+
+    async def run(self):
+        args = self.get_arguments()
+        parts = args.get("parts", self.config.get("parts", []))
+        sep = args.get("separator", self.config.get("separator", ""))
+        out_key = self.config.get("output_key", "value")
+        values = []
+        for p in parts:
+            if isinstance(p, str):
+                values.append(str(self.session.context.get(p, p)))
+            else:
+                values.append(str(p))
+        self.set_outputs({out_key: sep.join(values)})
+
+
+@register_stage("TemplateStage")
+class TemplateStage(BaseStage):
+    """
+    description: "Format template string with values pulled from context paths"
+    arguments:
+      template:
+        type: string
+        description: "Template overriding config"
+    config:
+      template:
+        type: string
+        description: "Default template string"
+      output_key:
+        type: string
+        description: "Context key for rendered value"
+      values:
+        type: object
+        description: "Mapping placeholder -> context path"
+    outputs:
+      value:
+        type: string
+        description: "Rendered string"
+    """
+    category = "builtin.strings"
+
+    async def run(self):
+        args = self.get_arguments()
+        template = self.config.get("template") or args.get("template")
+        out_key = self.config.get("output_key", "value")
+        values_cfg = self.config.get("values", {})
+        if template is None:
+            raise ValueError("TemplateStage requires template")
+        values = {}
+        for key, path in values_cfg.items():
+            values[key] = self.session.context.get(path)
+        self.set_outputs({out_key: template.format(**values)})

stageflow/builtins/vars.py

@@ -0,0 +1,118 @@
+from stageflow.core.stage import BaseStage, register_stage
+
+
+@register_stage("SetValueStage")
+class SetValueStage(BaseStage):
+    """
+    description: "Set value from arguments or config to the target path"
+    arguments:
+      value:
+        type: any
+        description: "Value to set (overrides config)"
+    config:
+      value:
+        type: any
+        description: "Fallback value when argument is missing"
+    outputs:
+      value:
+        type: any
+        description: "Value that was written"
+    """
+    category = "builtin.vars"
+
+    async def run(self):
+        args = self.get_arguments()
+        value = args.get("value", self.config.get("value"))
+        if value is None and "value" not in args and "value" not in self.config:
+            raise ValueError("SetValueStage requires value via arguments or config")
+        self.set_outputs({"value": value})
+
+
+@register_stage("CopyValueStage")
+class CopyValueStage(BaseStage):
+    """
+    description: "Copy value from arguments (or default) to output path"
+    arguments:
+      value:
+        type: any
+        description: "Value to copy"
+    config:
+      default:
+        type: any
+        description: "Default value when argument is missing"
+    outputs:
+      value:
+        type: any
+        description: "Copied value"
+    """
+    category = "builtin.vars"
+
+    async def run(self):
+        args = self.get_arguments()
+        value = args.get("value", None)
+        if value is None:
+            value = self.config.get("default")
+        self.set_outputs({"value": value})
+
+
+@register_stage("IncrementStage")
+class IncrementStage(BaseStage):
+    """
+    description: "Increment numeric value by delta (from args or config)"
+    arguments:
+      current:
+        type: number
+        description: "Current numeric value"
+      delta:
+        type: number
+        description: "Delta overriding config"
+    config:
+      delta:
+        type: number
+        description: "Default delta (1 if missing)"
+    outputs:
+      value:
+        type: number
+        description: "Result after increment"
+    """
+    category = "builtin.vars"
+
+    async def run(self):
+        args = self.get_arguments()
+        current = args.get("current", 0)
+        delta = args.get("delta", self.config.get("delta", 1))
+        if not isinstance(current, (int, float)):
+            raise ValueError("IncrementStage current is not numeric")
+        self.set_outputs({"value": current + delta})
+
+
+@register_stage("MergeDictStage")
+class MergeDictStage(BaseStage):
+    """
+    description: "Shallow merge src dict into dst (config default if missing)"
+    arguments:
+      src:
+        type: object
+        description: "Dict with overrides"
+      dst:
+        type: object
+        description: "Base dict to merge into"
+    config:
+      default_dst:
+        type: object
+        description: "Fallback base dict if dst is missing"
+    outputs:
+      merged:
+        type: object
+        description: "Merged dict result"
+    """
+    category = "builtin.vars"
+
+    async def run(self):
+        args = self.get_arguments()
+        src_val = args.get("src") or {}
+        dst_val = args.get("dst") or self.config.get("default_dst", {})
+        if not isinstance(src_val, dict) or not isinstance(dst_val, dict):
+            raise ValueError("MergeDictStage expects dict values")
+        merged = {**dst_val, **src_val}
+        self.set_outputs({"merged": merged})

stageflow/core/__init__.py

@@ -0,0 +1,7 @@
+from .event import Event, EventSpec, InputSpec  # noqa: F401
+from .jsonlogic import JsonLogic  # noqa: F401
+from .node import Node, ConditionNode, Condition, ParallelNode, TerminalNode, StageNode  # noqa: F401
+from .session import Session, SessionResult  # noqa: F401
+from .stage import BaseStage, get_stage, register_stage, get_stages, get_stages_by_category  # noqa: F401
+from .context import Context, DotDict  # noqa: F401
+from .pipeline import Pipeline  # noqa: F401

stageflow/core/context.py

@@ -0,0 +1,86 @@
+from typing import Any
+
+
+class DotDict(dict):
+    def __getattr__(self, item):
+        try:
+            value = self[item]
+            if isinstance(value, dict) and not isinstance(value, DotDict):
+                value = DotDict(value)
+                self[item] = value
+            return value
+        except KeyError:
+            raise AttributeError(item)
+
+    def __setattr__(self, key, value):
+        self[key] = value
+
+    def __delattr__(self, key):
+        try:
+            del self[key]
+        except KeyError:
+            raise AttributeError(key)
+
+
+class Context:
+    def __init__(self, payload: dict[str, Any] | None = None):
+        self.payload: DotDict = DotDict(payload or {})
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._deep_copy(self.payload))
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Context":
+        return cls(payload=data)
+
+    def get(self, path: str, default=None):
+        parts = path.split(".")
+        if parts and parts[0] == "payload":
+            parts = parts[1:]
+        cur: Any = self.payload
+        for p in parts:
+            if isinstance(cur, dict):
+                cur = cur.get(p, default)
+            elif isinstance(cur, list):
+                try:
+                    idx = int(p)
+                    cur = cur[idx]
+                except (ValueError, IndexError):
+                    return default
+            else:
+                return default
+        return cur
+
+    def set(self, path: str, value: Any):
+        parts = path.split(".")
+        if parts and parts[0] == "payload":
+            parts = parts[1:]
+        cur = self.payload
+        for p in parts[:-1]:
+            if isinstance(cur, dict):
+                cur = cur.setdefault(p, DotDict())
+            elif isinstance(cur, list):
+                idx = int(p)
+                while len(cur) <= idx:
+                    cur.append(DotDict())
+                cur = cur[idx]
+            else:
+                raise ValueError(f"Can't traverse into {type(cur)}")
+
+        last = parts[-1]
+        if isinstance(cur, dict):
+            cur[last] = value
+        elif isinstance(cur, list):
+            idx = int(last)
+            while len(cur) <= idx:
+                cur.append(None)
+            cur[idx] = value
+        else:
+            raise ValueError(f"Can't set into {type(cur)}")
+
+    def _deep_copy(self, obj: Any) -> Any:
+        if isinstance(obj, dict):
+            return {k: self._deep_copy(v) for k, v in obj.items()}
+        if isinstance(obj, list):
+            return [self._deep_copy(v) for v in obj]
+        return obj