pyrelay-workflow 0.1.0__tar.gz

pyrelay_workflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Developer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyrelay_workflow-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: pyrelay-workflow
+Version: 0.1.0
+Summary: A lightweight, async-first Python workflow engine with dynamic branching and rich visual dashboarding.
+Author-email: Developer <developer@example.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=12.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# ⚡ pyrelay
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/pyrelay/)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+`pyrelay` is a lightweight, high-performance, async-first Python workflow engine. It allows developers to model, execute, and monitor complex task pipelines with native pythonic flows (`if/else` branching), zero complex DSLs, live terminal dashboards, and interactive web visualizers.
+
+---
+
+## ✨ Features
+
+- **🐍 Native Python Branching**: Use standard Python `if/else` and loops. The execution graph is discovered dynamically at runtime.
+- **⚡ Async-First Architecture**: Built natively on top of Python `asyncio`. Executes independent tasks concurrently.
+- **🧵 Auto-Offloading for Sync Tasks**: Run blocking synchronous functions without stalling the async event loop (automatically offloaded to thread executors).
+- **⏱️ Fault Tolerance**: Custom task-level retry policies, exponential backoff, and timeouts out-of-the-box.
+- **🖥️ Live Console Dashboard**: Animated status trees, progress bars, and log streams in your terminal powered by `rich`.
+- **🌐 Draggable HTML/JS Visualizer**: Compile any workflow run into a standalone dark-mode HTML file containing a responsive network chart powered by Vis-Network.
+
+---
+
+## 📦 Installation
+
+Initialize your project and install `pyrelay`:
+
+```bash
+pip install pyrelay
+```
+
+*(Requires Python 3.9+)*
+
+---
+
+## 🚀 Quickstart
+
+Create a workflow by wrapping functions with `@task` and `@workflow`. Awaited tasks automatically map dependencies based on their execution order!
+
+```python
+import asyncio
+from pyrelay import task, workflow, WorkflowRun
+from pyrelay.dashboard import ConsoleDashboard
+
+@task(retries=2, retry_delay=0.5)
+async def fetch_user_data(user_id: int):
+    await asyncio.sleep(0.5)
+    return {"id": user_id, "name": "Alice", "status": "active"}
+
+@task()
+async def process_account(user: dict):
+    await asyncio.sleep(0.3)
+    return f"Account processed for {user['name']}"
+
+@workflow(name="Account Pipeline")
+async def account_flow(user_id: int):
+    user = await fetch_user_data(user_id)
+    result = await process_account(user)
+    return result
+
+if __name__ == "__main__":
+    run = WorkflowRun(account_flow)
+    
+    # Attach the live CLI dashboard
+    ConsoleDashboard(run)
+    
+    # Run the workflow blocking/sync
+    run.run_sync(user_id=101)
+```
+
+---
+
+## 🌿 Dynamic Branching (Option B)
+
+In `pyrelay`, branching is simply Python. The engine tracks exactly which path was taken and marks skipped branches appropriately in reports.
+
+```python
+@task()
+async def process_premium_user(user: dict):
+    return "VIP treatment applied"
+
+@task()
+async def process_standard_user(user: dict):
+    return "Standard access configured"
+
+@workflow(name="User Routing")
+async def user_routing_flow(user: dict):
+    # Branching happens at runtime based on real data values
+    if user["is_premium"]:
+        result = await process_premium_user(user)
+    else:
+        result = await process_standard_user(user)
+    return result
+```
+
+---
+
+## 🎨 Visualization Telemetry
+
+Generating an interactive, visual representation of your executed workflow is a single method call:
+
+```python
+# Save interactive HTML dashboard
+run.visualize("workflow_run.html")
+```
+
+Open `workflow_run.html` in any browser to get a premium dark-mode interface where you can:
+1. Pan and zoom around the execution DAG.
+2. Review node colors indicating statuses: **Green (Success)**, **Red (Failed)**, **Blue (Running)**, **Grey (Pending)**.
+3. Click any node to slide open a telemetry inspect panel containing:
+   - Inputs and outputs
+   - Time elapsed, start/end timestamps
+   - Retry counts and exceptions
+
+---
+
+## ⚙️ Configuration Properties
+
+The `@task` decorator accepts the following metadata options:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `str` | *Function Name* | Identifier for the task (used in dashboard and graphs). |
+| `retries` | `int` | `0` | Number of attempts to retry if the function raises an exception. |
+| `retry_delay` | `float` | `1.0` | Initial delay (seconds) before attempting a retry. |
+| `backoff_factor`| `float` | `2.0` | Exponential multiplier for consecutive retries (delay * backoff_factor^attempt). |
+| `timeout` | `float` | `None` | Max seconds before cancelling execution and marking the task as failed. |
+
+---
+
+## 🧪 Running Tests
+
+To run the unit and integration test suite, install development dependencies and run `pytest`:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for details.

pyrelay_workflow-0.1.0/README.md

@@ -0,0 +1,142 @@
+# ⚡ pyrelay
+
+[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/pyrelay/)
+[![Python versions](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+`pyrelay` is a lightweight, high-performance, async-first Python workflow engine. It allows developers to model, execute, and monitor complex task pipelines with native pythonic flows (`if/else` branching), zero complex DSLs, live terminal dashboards, and interactive web visualizers.
+
+---
+
+## ✨ Features
+
+- **🐍 Native Python Branching**: Use standard Python `if/else` and loops. The execution graph is discovered dynamically at runtime.
+- **⚡ Async-First Architecture**: Built natively on top of Python `asyncio`. Executes independent tasks concurrently.
+- **🧵 Auto-Offloading for Sync Tasks**: Run blocking synchronous functions without stalling the async event loop (automatically offloaded to thread executors).
+- **⏱️ Fault Tolerance**: Custom task-level retry policies, exponential backoff, and timeouts out-of-the-box.
+- **🖥️ Live Console Dashboard**: Animated status trees, progress bars, and log streams in your terminal powered by `rich`.
+- **🌐 Draggable HTML/JS Visualizer**: Compile any workflow run into a standalone dark-mode HTML file containing a responsive network chart powered by Vis-Network.
+
+---
+
+## 📦 Installation
+
+Initialize your project and install `pyrelay`:
+
+```bash
+pip install pyrelay
+```
+
+*(Requires Python 3.9+)*
+
+---
+
+## 🚀 Quickstart
+
+Create a workflow by wrapping functions with `@task` and `@workflow`. Awaited tasks automatically map dependencies based on their execution order!
+
+```python
+import asyncio
+from pyrelay import task, workflow, WorkflowRun
+from pyrelay.dashboard import ConsoleDashboard
+
+@task(retries=2, retry_delay=0.5)
+async def fetch_user_data(user_id: int):
+    await asyncio.sleep(0.5)
+    return {"id": user_id, "name": "Alice", "status": "active"}
+
+@task()
+async def process_account(user: dict):
+    await asyncio.sleep(0.3)
+    return f"Account processed for {user['name']}"
+
+@workflow(name="Account Pipeline")
+async def account_flow(user_id: int):
+    user = await fetch_user_data(user_id)
+    result = await process_account(user)
+    return result
+
+if __name__ == "__main__":
+    run = WorkflowRun(account_flow)
+    
+    # Attach the live CLI dashboard
+    ConsoleDashboard(run)
+    
+    # Run the workflow blocking/sync
+    run.run_sync(user_id=101)
+```
+
+---
+
+## 🌿 Dynamic Branching (Option B)
+
+In `pyrelay`, branching is simply Python. The engine tracks exactly which path was taken and marks skipped branches appropriately in reports.
+
+```python
+@task()
+async def process_premium_user(user: dict):
+    return "VIP treatment applied"
+
+@task()
+async def process_standard_user(user: dict):
+    return "Standard access configured"
+
+@workflow(name="User Routing")
+async def user_routing_flow(user: dict):
+    # Branching happens at runtime based on real data values
+    if user["is_premium"]:
+        result = await process_premium_user(user)
+    else:
+        result = await process_standard_user(user)
+    return result
+```
+
+---
+
+## 🎨 Visualization Telemetry
+
+Generating an interactive, visual representation of your executed workflow is a single method call:
+
+```python
+# Save interactive HTML dashboard
+run.visualize("workflow_run.html")
+```
+
+Open `workflow_run.html` in any browser to get a premium dark-mode interface where you can:
+1. Pan and zoom around the execution DAG.
+2. Review node colors indicating statuses: **Green (Success)**, **Red (Failed)**, **Blue (Running)**, **Grey (Pending)**.
+3. Click any node to slide open a telemetry inspect panel containing:
+   - Inputs and outputs
+   - Time elapsed, start/end timestamps
+   - Retry counts and exceptions
+
+---
+
+## ⚙️ Configuration Properties
+
+The `@task` decorator accepts the following metadata options:
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `name` | `str` | *Function Name* | Identifier for the task (used in dashboard and graphs). |
+| `retries` | `int` | `0` | Number of attempts to retry if the function raises an exception. |
+| `retry_delay` | `float` | `1.0` | Initial delay (seconds) before attempting a retry. |
+| `backoff_factor`| `float` | `2.0` | Exponential multiplier for consecutive retries (delay * backoff_factor^attempt). |
+| `timeout` | `float` | `None` | Max seconds before cancelling execution and marking the task as failed. |
+
+---
+
+## 🧪 Running Tests
+
+To run the unit and integration test suite, install development dependencies and run `pytest`:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for details.

pyrelay_workflow-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyrelay-workflow"
+version = "0.1.0"
+description = "A lightweight, async-first Python workflow engine with dynamic branching and rich visual dashboarding."
+readme = "README.md"
+authors = [
+    { name = "Developer", email = "developer@example.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+]
+requires-python = ">=3.9"
+dependencies = [
+    "rich>=12.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.18.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py39"

pyrelay_workflow-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyrelay_workflow-0.1.0/src/pyrelay/__init__.py

@@ -0,0 +1,14 @@
+from .core import task, workflow, WorkflowRun
+from .exceptions import WorkflowError, TaskFailedError, TaskTimeoutError
+# Import visualizer to trigger WorkflowRun monkeypatching
+from . import visualizer
+
+__all__ = [
+    "task",
+    "workflow",
+    "WorkflowRun",
+    "WorkflowError",
+    "TaskFailedError",
+    "TaskTimeoutError",
+]
+

pyrelay_workflow-0.1.0/src/pyrelay/core.py

@@ -0,0 +1,220 @@
+import asyncio
+import contextvars
+from datetime import datetime
+from enum import Enum
+from typing import Any, Callable, Dict, Optional, Set
+import uuid
+
+# Async context storage for active workflow run
+active_run_context: contextvars.ContextVar[Optional["WorkflowRun"]] = contextvars.ContextVar(
+    "active_run_context", default=None
+)
+
+
+class TaskStatus(str, Enum):
+    PENDING = "PENDING"
+    running = "RUNNING"  # Case-insensitive compatibility
+    RUNNING = "RUNNING"
+    SUCCESS = "SUCCESS"
+    FAILED = "FAILED"
+    SKIPPED = "SKIPPED"
+
+
+class Task:
+    """Decorator wrapper that stores task metadata and intercepts calls inside workflows."""
+
+    def __init__(
+        self,
+        func: Callable[..., Any],
+        name: Optional[str] = None,
+        retries: int = 0,
+        retry_delay: float = 1.0,
+        backoff_factor: float = 2.0,
+        timeout: Optional[float] = None,
+    ):
+        self.func = func
+        self.name = name or func.__name__
+        self.retries = retries
+        self.retry_delay = retry_delay
+        self.backoff_factor = backoff_factor
+        self.timeout = timeout
+        self.is_coroutine = asyncio.iscoroutinefunction(func)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        run = active_run_context.get()
+        if not run:
+            # Standalone invocation (useful for unit testing)
+            return self.func(*args, **kwargs)
+
+        return run.execute_task(self, args, kwargs)
+
+
+class TaskInstance:
+    """Tracks state and telemetry for a single task execution."""
+
+    def __init__(self, task: Task, run_id: str):
+        self.id = str(uuid.uuid4())
+        self.task = task
+        self.name = task.name
+        self.run_id = run_id
+        self.status = TaskStatus.PENDING
+        
+        self.start_time: Optional[datetime] = None
+        self.end_time: Optional[datetime] = None
+        self.duration: float = 0.0
+        
+        self.attempts = 0
+        self.inputs: Dict[str, Any] = {}
+        self.result: Any = None
+        self.error: Optional[str] = None
+        self.predecessors: Set[str] = set()
+
+    def start(self, inputs: Dict[str, Any]) -> None:
+        self.status = TaskStatus.RUNNING
+        self.start_time = datetime.now()
+        self.inputs = inputs
+        self.attempts += 1
+
+    def complete(self, result: Any) -> None:
+        self.status = TaskStatus.SUCCESS
+        self.end_time = datetime.now()
+        if self.start_time:
+            self.duration = (self.end_time - self.start_time).total_seconds()
+        self.result = result
+
+    def fail(self, error: Exception) -> None:
+        self.status = TaskStatus.FAILED
+        self.end_time = datetime.now()
+        if self.start_time:
+            self.duration = (self.end_time - self.start_time).total_seconds()
+        self.error = f"{type(error).__name__}: {str(error)}"
+
+    def skip(self) -> None:
+        self.status = TaskStatus.SKIPPED
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "status": self.status.value,
+            "start_time": self.start_time.isoformat() if self.start_time else None,
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "duration": self.duration,
+            "attempts": self.attempts,
+            "inputs": str(self.inputs),
+            "result": str(self.result) if self.result is not None else None,
+            "error": self.error,
+            "predecessors": list(self.predecessors),
+        }
+
+
+class Workflow:
+    """Blueprint representing a workflow defined with `@workflow`."""
+
+    def __init__(self, func: Callable[..., Any], name: Optional[str] = None):
+        self.func = func
+        self.name = name or func.__name__
+
+    def run(self, *args: Any, **kwargs: Any) -> "WorkflowRun":
+        run = WorkflowRun(self)
+        return run.run_sync(*args, **kwargs)
+
+    async def run_async(self, *args: Any, **kwargs: Any) -> "WorkflowRun":
+        run = WorkflowRun(self)
+        await run.run_async(*args, **kwargs)
+        return run
+
+
+class WorkflowRun:
+    """Coordinates the execution trace and lifecycle events for a single pipeline run."""
+
+    def __init__(self, workflow: Workflow):
+        self.id = str(uuid.uuid4())
+        self.workflow = workflow
+        self.status = "PENDING"
+        self.start_time: Optional[datetime] = None
+        self.end_time: Optional[datetime] = None
+        self.duration: float = 0.0
+        self.result: Any = None
+        self.error: Optional[str] = None
+
+        self.tasks: Dict[str, TaskInstance] = {}
+        self.event_callbacks: List[Callable[[str, Any], None]] = []
+        self.executor_hook: Optional[Callable[[Task, tuple, dict], Any]] = None
+
+    def add_event_callback(self, callback: Callable[[str, Any], None]) -> None:
+        self.event_callbacks.append(callback)
+
+    def emit_event(self, event_type: str, data: Any) -> None:
+        for cb in self.event_callbacks:
+            try:
+                cb(event_type, data)
+            except Exception:
+                pass
+
+    def get_frontier(self) -> Set[str]:
+        """Identifies completed tasks that have no dependent downstream runs.
+        
+        Uses:
+        Frontier = {Completed} - {Predecessors of any task}
+        """
+        all_completed = {
+            t_id for t_id, t in self.tasks.items() 
+            if t.status in (TaskStatus.SUCCESS, TaskStatus.FAILED, TaskStatus.SKIPPED)
+        }
+        
+        all_predecessors = set()
+        for t in self.tasks.values():
+            all_predecessors.update(t.predecessors)
+            
+        return all_completed - all_predecessors
+
+    def execute_task(self, task: Task, args: tuple, kwargs: dict) -> Any:
+        if not self.executor_hook:
+            raise RuntimeError("Engine runner not initialized on this WorkflowRun.")
+        return self.executor_hook(task, args, kwargs)
+
+    def run_sync(self, *args: Any, **kwargs: Any) -> "WorkflowRun":
+        try:
+            loop = asyncio.get_event_loop()
+        except RuntimeError:
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+
+        if loop.is_running():
+            # Jupyter and FastAPI loops are already running; patch to prevent loop collision
+            import nest_asyncio
+            nest_asyncio.apply()
+            
+        loop.run_until_complete(self.run_async(*args, **kwargs))
+        return self
+
+    async def run_async(self, *args: Any, **kwargs: Any) -> None:
+        from .engine import ExecutionEngine
+        engine = ExecutionEngine(self)
+        await engine.run(args, kwargs)
+
+
+def task(
+    name: Optional[str] = None,
+    retries: int = 0,
+    retry_delay: float = 1.0,
+    backoff_factor: float = 2.0,
+    timeout: Optional[float] = None,
+) -> Callable[[Callable[..., Any]], Task]:
+    def decorator(func: Callable[..., Any]) -> Task:
+        return Task(
+            func=func,
+            name=name,
+            retries=retries,
+            retry_delay=retry_delay,
+            backoff_factor=backoff_factor,
+            timeout=timeout,
+        )
+    return decorator
+
+
+def workflow(name: Optional[str] = None) -> Callable[[Callable[..., Any]], Workflow]:
+    def decorator(func: Callable[..., Any]) -> Workflow:
+        return Workflow(func=func, name=name)
+    return decorator