stageflow-framework 0.1.0__py3-none-any.whl

stageflow/core/event.py

@@ -0,0 +1,71 @@
+from dataclasses import dataclass
+from datetime import datetime, UTC
+
+
+@dataclass
+class InputSpec:
+    type: str | None = None
+    description: str | None = None
+    required: bool = True
+    default: str | int | float | bool | None = None
+    payload_schema: object | None = None
+
+
+@dataclass
+class EventSpec:
+    type: str
+    description: str | None = None
+    payload_schema: object | None = None
+
+
+class Event:
+    type: str
+    session_id: str
+    node_id: str | None
+    stage_id: str | None
+    action_id: str | None
+    payload: dict
+    timestamp: datetime
+
+    def __init__(
+        self,
+        type: str,
+        session_id: str,
+        node_id: str | None = None,
+        stage_id: str | None = None,
+        action_id: str | None = None,
+        payload: dict = None,
+    ):
+        self.type = type
+        self.session_id = session_id
+        self.node_id = node_id
+        self.stage_id = stage_id
+        self.action_id = action_id
+        self.payload = payload or {}
+        self.timestamp = datetime.now(UTC)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "session_id": self.session_id,
+            "node_id": self.node_id,
+            "stage_id": self.stage_id,
+            "action_id": self.action_id,
+            "payload": self.payload,
+            "timestamp": self.timestamp.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Event":
+        ts_raw = data.get("timestamp")
+        timestamp = datetime.fromisoformat(ts_raw) if ts_raw else datetime.now(UTC)
+        ev = cls(
+            type=data.get("type"),
+            session_id=data.get("session_id"),
+            node_id=data.get("node_id"),
+            stage_id=data.get("stage_id"),
+            action_id=data.get("action_id"),
+            payload=data.get("payload"),
+        )
+        ev.timestamp = timestamp
+        return ev

stageflow/core/jsonlogic.py

@@ -0,0 +1,43 @@
+from .context import Context
+
+
+class JsonLogic:
+    def __init__(self, condition: dict):
+        self.condition = condition
+
+    def evaluate(self, context: Context) -> bool:
+        base = {"payload": context.payload}
+        if isinstance(context.payload, dict):
+            base.update(context.payload)
+        return self._eval(self.condition, base)
+
+    def _eval(self, expr, data):
+        if isinstance(expr, dict):
+            if len(expr) != 1:
+                raise ValueError("Invalid JSONLogic expression")
+            op, args = next(iter(expr.items()))
+            if not isinstance(args, list):
+                args = [args]
+
+            if op == "var":
+                path = args[0].split(".")
+                val = data
+                for p in path:
+                    if val is None:
+                        return None
+                    val = val.get(p, None)
+                return val
+            elif op == "<":
+                return self._eval(args[0], data) < self._eval(args[1], data)
+            elif op == ">":
+                return self._eval(args[0], data) > self._eval(args[1], data)
+            elif op == "==":
+                return self._eval(args[0], data) == self._eval(args[1], data)
+            elif op == "and":
+                return all(self._eval(a, data) for a in args)
+            elif op == "or":
+                return any(self._eval(a, data) for a in args)
+            else:
+                raise NotImplementedError(f"Operator {op} not implemented")
+        else:
+            return expr

stageflow/core/node.py

@@ -0,0 +1,256 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from .jsonlogic import JsonLogic
+from .stage import get_stage
+
+
+class Node:
+    id: str
+    type: str
+    metadata: dict
+
+    def __init__(self, id: str, type: str, metadata: dict = None):
+        self.id = id
+        self.type = type
+        self.metadata = metadata or {}
+
+    @staticmethod
+    def from_dict(data: dict) -> "Node":
+        node_type = data.get("type")
+        match node_type:
+            case "condition":
+                return ConditionNode.from_dict(data)
+            case "parallel":
+                return ParallelNode.from_dict(data)
+            case "terminal":
+                return TerminalNode.from_dict(data)
+            case "stage":
+                return StageNode.from_dict(data)
+            case "subpipeline":
+                return SubPipelineNode.from_dict(data)
+            case "map":
+                return MapNode.from_dict(data)
+            case _:
+                raise ValueError(f"Unknown node type: {node_type}")
+
+
+@dataclass
+class Condition:
+    if_condition: JsonLogic
+    then_goto: str
+
+
+class ConditionNode(Node):
+    conditions: list[Condition]
+    else_goto: str | None
+
+    def __init__(
+        self,
+        id: str,
+        type: str,
+        conditions: list[Condition],
+        else_goto: str | None = None,
+        metadata: dict = None,
+    ):
+        super().__init__(id, type, metadata)
+        self.conditions = conditions
+        self.else_goto = else_goto
+
+    @staticmethod
+    def from_dict(data: dict) -> "ConditionNode":
+        id = data.get("id")
+        type = data.get("type")
+        conditions_data = data.get("conditions", [])
+        conditions = [
+            Condition(if_condition=JsonLogic(cond["if"]), then_goto=cond["then"])
+            for cond in conditions_data
+        ]
+        else_goto = data.get("else")
+        metadata = data.get("metadata", {})
+        return ConditionNode(
+            id=id,
+            type=type,
+            conditions=conditions,
+            else_goto=else_goto,
+            metadata=metadata,
+        )
+
+
+class ParallelNode(Node):
+    children: list[str]
+    policy: Literal["all", "any"]
+    next: str | None
+    cancel_on_error: bool
+
+    def __init__(
+        self,
+        id: str,
+        type: str,
+        children: list[str],
+        policy: Literal["all", "any"] = "all",
+        next: str | None = None,
+        cancel_on_error: bool = True,
+        metadata: dict = None,
+    ):
+        super().__init__(id, type, metadata)
+        self.children = children
+        self.policy = policy
+        self.next = next
+        self.cancel_on_error = cancel_on_error
+
+    @staticmethod
+    def from_dict(data: dict) -> "ParallelNode":
+        id = data.get("id")
+        type = data.get("type")
+        children = data.get("children", [])
+        policy = data.get("policy", "all")
+        next = data.get("next")
+        cancel_on_error = data.get("cancel_on_error", True)
+        metadata = data.get("metadata", {})
+        return ParallelNode(
+            id=id,
+            type=type,
+            children=children,
+            policy=policy,
+            next=next,
+            cancel_on_error=cancel_on_error,
+            metadata=metadata,
+        )
+
+
+class TerminalNode(Node):
+    artifact_paths: list[str]
+    result: dict | None
+
+    def __init__(
+        self,
+        id: str,
+        type: str,
+        artifact_paths: list[str] = None,
+        result: dict | None = None,
+        metadata: dict = None,
+    ):
+        super().__init__(id, type, metadata)
+        self.artifact_paths = artifact_paths or []
+        self.result = result
+
+    @staticmethod
+    def from_dict(data: dict) -> "TerminalNode":
+        id = data.get("id")
+        type = data.get("type")
+        artifact_paths = data.get("artifacts", [])
+        result = data.get("result")
+        metadata = data.get("metadata", {})
+        return TerminalNode(
+            id=id,
+            type=type,
+            artifact_paths=artifact_paths,
+            result=result,
+            metadata=metadata,
+        )
+
+
+class SubPipelineNode(Node):
+    subpipeline_id: str
+    inputs: dict
+    artifact_outputs: dict
+    result_output: str | None
+    next: str | None
+
+    def __init__(
+        self,
+        id: str,
+        type: str,
+        subpipeline_id: str,
+        inputs: dict = None,
+        artifact_outputs: dict = None,
+        result_output: str | None = None,
+        next: str | None = None,
+        metadata: dict = None,
+    ):
+        super().__init__(id, type, metadata)
+        self.subpipeline_id = subpipeline_id
+        self.inputs = inputs or {}
+        self.artifact_outputs = artifact_outputs or {}
+        self.result_output = result_output
+        self.next = next
+
+    @staticmethod
+    def from_dict(data: dict) -> "SubPipelineNode":
+        id = data.get("id")
+        type = data.get("type")
+        subpipeline_id = data.get("subpipeline_id")
+        if not subpipeline_id:
+            raise ValueError("subpipeline_id is required for subpipeline node")
+        inputs = data.get("inputs", {})
+        artifact_outputs = data.get("artifact_outputs", {})
+        result_output = data.get("result_output")
+        next = data.get("next")
+        metadata = data.get("metadata", {})
+        return SubPipelineNode(
+            id=id,
+            type=type,
+            subpipeline_id=subpipeline_id,
+            inputs=inputs,
+            artifact_outputs=artifact_outputs,
+            result_output=result_output,
+            next=next,
+            metadata=metadata,
+        )
+
+class StageNode(Node):
+    stage: str
+    config: dict = {}
+    inputs: dict = {}
+    outputs: dict = {}
+    next: str | None = None
+    fallback: str | None = None
+
+    def __init__(
+        self,
+        id: str,
+        type: str,
+        stage: str,
+        config: dict = None,
+        arguments: dict = None,
+        outputs: dict = None,
+        next: str | None = None,
+        fallback: str | None = None,
+        metadata: dict = None,
+    ):
+        super().__init__(id, type, metadata)
+        if not get_stage(stage):
+            raise ValueError(f"Stage '{stage}' not found in registry")
+        self.stage = stage
+        self.config = config or {}
+        self.arguments = arguments or {}
+        self.outputs = outputs or {}
+        self.next = next
+        self.fallback = fallback
+
+    @staticmethod
+    def from_dict(data: dict) -> "StageNode":
+        id = data.get("id")
+        type = data.get("type")
+        stage = data.get("stage")
+        config = data.get("config", {})
+        arguments = data.get("arguments", {})
+        outputs = data.get("outputs", {})
+        next = data.get("next")
+        fallback = data.get("fallback")
+        metadata = data.get("metadata", {})
+        return StageNode(
+            id=id,
+            type=type,
+            stage=stage,
+            config=config,
+            arguments=arguments,
+            outputs=outputs,
+            next=next,
+            fallback=fallback,
+            metadata=metadata,
+        )
+
+    def get_stage_class(self):
+        return get_stage(self.stage)

stageflow/core/pipeline.py

@@ -0,0 +1,108 @@
+from .node import Node, StageNode, ConditionNode, ParallelNode, TerminalNode, SubPipelineNode, MapNode
+from stageflow.docs.schema import load_pipeline_schema
+
+try:
+    from jsonschema import validate, ValidationError
+except ImportError:  # pragma: no cover - optional dependency
+    validate = None
+
+    class ValidationError(Exception):
+        pass
+
+
+class Pipeline:
+    entry: str
+    nodes: list[Node]
+    _nodes_map: dict[str, Node]
+    metadata: dict
+    raw_json: dict
+    subpipelines: dict
+
+    def __init__(
+        self,
+        entry: str,
+        nodes: list[Node],
+        metadata: dict = None,
+        raw_json: dict = None,
+        subpipelines: dict | None = None,
+    ):
+        self.entry = entry
+        self.nodes = nodes
+        self._nodes_map = {node.id: node for node in nodes}
+        self.metadata = metadata or {}
+        self.raw_json = raw_json or {}
+        self.subpipelines = subpipelines or {}
+
+    @staticmethod
+    def from_dict(data: dict) -> "Pipeline":
+        # Schema validation before constructing nodes (if jsonschema available).
+        schema = None
+        if validate:
+            try:
+                schema = load_pipeline_schema()
+                validate(instance=data, schema=schema)
+            except ValidationError as e:
+                raise ValueError(f"Pipeline schema validation failed: {e.message}") from e
+        entry = data.get("entry")
+        nodes_data = data.get("nodes", [])
+        nodes = [Node.from_dict(node) for node in nodes_data]
+        metadata = data.get("metadata", {})
+        subpipelines = data.get("subpipelines", {})
+        # Validate subpipelines recursively.
+        if validate and schema:
+            for sub_id, sub_data in subpipelines.items():
+                try:
+                    validate(instance=sub_data, schema=schema)
+                except ValidationError as e:
+                    raise ValueError(f"Subpipeline '{sub_id}' schema validation failed: {e.message}") from e
+        return Pipeline(entry=entry, nodes=nodes, metadata=metadata, raw_json=data, subpipelines=subpipelines)
+
+    def get_node(self, node_id: str) -> Node:
+        if node_id not in self._nodes_map:
+            raise ValueError(f"Node with id {node_id} not found in pipeline")
+        return self._nodes_map[node_id]
+
+    def get_entry_node(self) -> Node:
+        return self.get_node(self.entry)
+
+    def validate(self) -> bool:
+        if self.entry not in self._nodes_map:
+            raise ValueError(f"Entry node '{self.entry}' not found in pipeline")
+
+        for node in self.nodes:
+            match node:
+                case StageNode():
+                    stage_class = node.get_stage_class()
+                    if not stage_class:
+                        raise ValueError(f"Stage class for node {node.id} not found")
+                    if node.next and node.next not in self._nodes_map:
+                        raise ValueError(f"Next node '{node.next}' for stage {node.id} not found in pipeline")
+                    if node.fallback and node.fallback not in self._nodes_map:
+                        raise ValueError(f"Fallback node '{node.fallback}' for stage {node.id} not found in pipeline")
+                case ConditionNode():
+                    for cond in node.conditions:
+                        if cond.then_goto not in self._nodes_map:
+                            raise ValueError(f"Condition target '{cond.then_goto}' not found in pipeline")
+                    if node.else_goto and node.else_goto not in self._nodes_map:
+                        raise ValueError(f"Condition else '{node.else_goto}' not found in pipeline")
+                case ParallelNode():
+                    for child in node.children:
+                        if child not in self._nodes_map:
+                            raise ValueError(f"Parallel branch '{child}' not found in pipeline")
+                    if node.next and node.next not in self._nodes_map:
+                        raise ValueError(f"Parallel next '{node.next}' not found in pipeline")
+                case TerminalNode():
+                    pass
+                case SubPipelineNode():
+                    if node.subpipeline_id not in self.subpipelines:
+                        raise ValueError(f"Subpipeline '{node.subpipeline_id}' not found for node {node.id}")
+                    # Basic cycle check: prevent direct self-reference
+                    if node.subpipeline_id == self.entry:
+                        raise ValueError(f"Subpipeline '{node.subpipeline_id}' cannot reference root entry")
+                case MapNode():
+                    if node.next and node.next not in self._nodes_map:
+                        raise ValueError(f"Map next '{node.next}' not found in pipeline")
+                case _:
+                    raise ValueError(f"Unknown node type: {type(node)}")
+
+        return True