vibeblocks 0.1.0__py3-none-any.whl

vibeblocks/__init__.py

@@ -0,0 +1,22 @@
+__version__ = "0.1.0"
+
+from vibeblocks.core.context import ExecutionContext
+from vibeblocks.components.block import Block
+from vibeblocks.components.chain import Chain
+from vibeblocks.components.flow import Flow
+from vibeblocks.runtime.runner import SyncRunner, AsyncRunner
+from vibeblocks.core.decorators import block
+from vibeblocks.policies.failure import FailureStrategy
+from vibeblocks.utils.execution import execute_flow
+
+__all__ = [
+    "Block",
+    "Chain",
+    "Flow",
+    "ExecutionContext",
+    "SyncRunner",
+    "AsyncRunner",
+    "block",
+    "FailureStrategy",
+    "execute_flow",
+]

vibeblocks/components/block.py

@@ -0,0 +1,195 @@
+import asyncio
+import concurrent.futures
+import inspect
+import time
+from typing import Any, Awaitable, Callable, Optional, TypeVar, Union
+
+from vibeblocks.core.context import ExecutionContext
+from vibeblocks.core.errors import BlockExecutionError, BlockTimeoutError
+from vibeblocks.core.executable import Executable
+from vibeblocks.core.outcome import Outcome
+from vibeblocks.policies.retry import RetryPolicy
+from vibeblocks.utils.inspection import is_async_callable
+
+T = TypeVar("T")
+
+# Shared executor for synchronous block timeouts to avoid overhead and thread leakage.
+# Using a large enough number of workers to handle concurrent blocks.
+_TASK_TIMEOUT_EXECUTOR = concurrent.futures.ThreadPoolExecutor(
+    thread_name_prefix="BlockTimeout")
+
+
+class Block(Executable[T]):
+    """
+    Represents an atomic unit of work in a workflow.
+    Executes a function with retry logic and supports compensation.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        func: Callable[[ExecutionContext[T]], Any],
+        description: Optional[str] = None,
+        retry_policy: Optional[RetryPolicy] = None,
+        undo: Optional[Callable[[ExecutionContext[T]], Any]] = None,
+        timeout: Optional[float] = None,
+    ):
+        self.name = name
+        self.func = func
+        self.description = description or func.__doc__
+        self.retry_policy = retry_policy or RetryPolicy(max_attempts=1)
+        self.undo = undo
+        self.timeout = timeout
+
+        self._is_async = is_async_callable(self.func)
+        self._is_undo_async = is_async_callable(
+            self.undo) if self.undo else False
+
+    @property
+    def is_async(self) -> bool:
+        """Determines if the block function is asynchronous."""
+        # Optimized: Return pre-calculated value to avoid repeated inspection overhead
+        return self._is_async
+
+    def execute(self, ctx: ExecutionContext[T]) -> Union[Outcome[T], Awaitable[Outcome[T]]]:
+        if self.is_async:
+            return self._execute_async(ctx)
+        else:
+            return self._execute_sync(ctx)
+
+    def _execute_sync(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        ctx.log_event("INFO", self.name, "Block Started")
+        start_time = time.time()
+        attempt = 1
+
+        while True:
+            try:
+                if self.timeout:
+                    try:
+                        future = _TASK_TIMEOUT_EXECUTOR.submit(self.func, ctx)
+                        res = future.result(timeout=self.timeout)
+                    except concurrent.futures.TimeoutError:
+                        raise BlockTimeoutError(
+                            f"Block '{self.name}' timed out after {self.timeout}s"
+                        ) from None
+                else:
+                    res = self.func(ctx)
+
+                # Runtime check for false-negative async detection (e.g. lambdas)
+                if inspect.isawaitable(res):
+                    if inspect.iscoroutine(res):
+                        res.close()
+                    # We cannot await it here because we are in sync mode.
+                    # We must warn the user that their block logic probably didn't run.
+                    # Or raise an error? Raising error is safer.
+                    msg = (
+                        f"Block '{self.name}' returned an awaitable (coroutine) but "
+                        "was executed synchronously. Check if the function is "
+                        "defined correctly or if AsyncRunner should be used."
+                    )
+                    raise RuntimeError(msg)
+
+                duration = int((time.time() - start_time) * 1000)
+                ctx.log_event("INFO", self.name, "Block Completed")
+                ctx.completed_steps.add(self.name)
+                return Outcome(status="SUCCESS", context=ctx, errors=[], duration_ms=duration)
+
+            except Exception as e:
+                duration = int((time.time() - start_time) * 1000)
+                ctx.log_event("ERROR", self.name,
+                              f"Block Failed: {ctx.format_exception(e)}")
+
+                if self.retry_policy.should_retry(attempt, e):
+                    delay = self.retry_policy.calculate_delay(attempt)
+                    msg = (
+                        f"Retrying in {delay}s (Attempt {attempt}/"
+                        f"{self.retry_policy.max_attempts})"
+                    )
+                    ctx.log_event("INFO", self.name, msg)
+                    time.sleep(delay)
+                    attempt += 1
+                    continue
+                else:
+                    msg = f"Block '{self.name}' failed after {attempt} attempts"
+                    error = BlockExecutionError(msg)
+                    error.__cause__ = e
+                    return Outcome(
+                        status="FAILED", context=ctx, errors=[error], duration_ms=duration
+                    )
+
+    async def _execute_async(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        ctx.log_event("INFO", self.name, "Block Started (Async)")
+        start_time = time.time()
+        attempt = 1
+
+        while True:
+            try:
+                res = self.func(ctx)
+                if inspect.isawaitable(res):
+                    if self.timeout:
+                        try:
+                            res = await asyncio.wait_for(res, timeout=self.timeout)
+                        except asyncio.TimeoutError:
+                            raise BlockTimeoutError(
+                                f"Block '{self.name}' timed out after {self.timeout}s"
+                            ) from None
+                    else:
+                        res = await res
+
+                duration = int((time.time() - start_time) * 1000)
+                ctx.log_event("INFO", self.name, "Block Completed")
+                ctx.completed_steps.add(self.name)
+                return Outcome(status="SUCCESS", context=ctx, errors=[], duration_ms=duration)
+
+            except Exception as e:
+                duration = int((time.time() - start_time) * 1000)
+                ctx.log_event("ERROR", self.name,
+                              f"Block Failed: {ctx.format_exception(e)}")
+
+                if self.retry_policy.should_retry(attempt, e):
+                    delay = self.retry_policy.calculate_delay(attempt)
+                    msg = (
+                        f"Retrying in {delay}s (Attempt {attempt}/"
+                        f"{self.retry_policy.max_attempts})"
+                    )
+                    ctx.log_event("INFO", self.name, msg)
+                    await asyncio.sleep(delay)
+                    attempt += 1
+                    continue
+                else:
+                    msg = f"Block '{self.name}' failed after {attempt} attempts"
+                    error = BlockExecutionError(msg)
+                    error.__cause__ = e
+                    return Outcome(
+                        status="FAILED", context=ctx, errors=[error], duration_ms=duration
+                    )
+
+    def compensate(self, ctx: ExecutionContext[T]) -> Union[None, Awaitable[None]]:
+        if self.undo is None:
+            return None
+
+        ctx.log_event("INFO", self.name, "Compensating Block")
+
+        if self._is_undo_async:
+            return self._compensate_async(ctx)
+        else:
+            try:
+                self.undo(ctx)
+            except Exception as e:
+                ctx.log_event("ERROR", self.name,
+                              f"Compensation Failed: {ctx.format_exception(e)}")
+                raise
+            return None
+
+    async def _compensate_async(self, ctx: ExecutionContext[T]) -> None:
+        if self.undo is None:
+            return
+
+        try:
+            res = self.undo(ctx)
+            if inspect.isawaitable(res):
+                await res
+        except Exception as e:
+            ctx.log_event("ERROR", self.name,
+                          f"Compensation Failed: {ctx.format_exception(e)}")
+            raise

vibeblocks/components/chain.py

@@ -0,0 +1,124 @@
+"""
+Chain component handling linear execution of multiple blocks.
+"""
+
+import inspect
+import time
+from typing import List, Union, Awaitable, TypeVar
+
+from vibeblocks.core.context import ExecutionContext
+from vibeblocks.core.outcome import Outcome
+from vibeblocks.core.executable import Executable
+from vibeblocks.core.errors import ChainExecutionError
+
+T = TypeVar("T")
+
+
+class Chain(Executable[T]):
+    """
+    A linear collection of executables (blocks or sub-chains).
+    Executes steps sequentially.
+    """
+
+    def __init__(self, name: str, steps: List[Executable[T]]):
+        self.name = name
+        self.steps = list(steps)
+        self._is_async = any(step.is_async for step in self.steps)
+
+    @property
+    def is_async(self) -> bool:
+        """Determines if the chain requires asynchronous execution."""
+        return self._is_async
+
+    def execute(self, ctx: ExecutionContext[T]) -> Union[Outcome[T], Awaitable[Outcome[T]]]:
+        if self.is_async:
+            return self._execute_async(ctx)
+        return self._execute_sync(ctx)
+
+    def _execute_sync(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        start_time = time.perf_counter_ns()
+        ctx.log_event("INFO", self.name, "Chain Started")
+
+        for step in self.steps:
+            try:
+                result = step.execute(ctx)
+
+                # Safety check for unexpected async returns in sync mode
+                if inspect.isawaitable(result):
+                    if inspect.iscoroutine(result):
+                        result.close()
+                    raise ChainExecutionError(
+                        f"Step '{getattr(step, 'name', 'Unknown')}' returned a coroutine in a sync chain execution. Use AsyncRunner.")
+
+                # Check outcome
+                if isinstance(result, Outcome):
+                    if result.status != "SUCCESS":
+                        # Stop execution and bubble up failure
+                        return result
+            except Exception as e:
+                duration = (time.perf_counter_ns() - start_time) // 1_000_000
+                ctx.log_event("ERROR", self.name,
+                              f"Chain Error: {ctx.format_exception(e)}")
+                # Return Failed Outcome instead of raising
+                return Outcome(status="FAILED", context=ctx, errors=[e], duration_ms=duration)
+
+        duration = (time.perf_counter_ns() - start_time) // 1_000_000
+        ctx.log_event("INFO", self.name, "Chain Completed")
+        ctx.completed_steps.add(self.name)
+        return Outcome(status="SUCCESS", context=ctx, errors=[], duration_ms=duration)
+
+    async def _execute_async(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        start_time = time.perf_counter_ns()
+        ctx.log_event("INFO", self.name, "Chain Started (Async)")
+
+        for step in self.steps:
+            try:
+                result = step.execute(ctx)
+                if inspect.isawaitable(result):
+                    result = await result
+
+                if isinstance(result, Outcome):
+                    if result.status != "SUCCESS":
+                        return result
+            except Exception as e:
+                duration = (time.perf_counter_ns() - start_time) // 1_000_000
+                ctx.log_event("ERROR", self.name,
+                              f"Chain Error: {ctx.format_exception(e)}")
+                # Return Failed Outcome instead of raising
+                return Outcome(status="FAILED", context=ctx, errors=[e], duration_ms=duration)
+
+        duration = (time.perf_counter_ns() - start_time) // 1_000_000
+        ctx.log_event("INFO", self.name, "Chain Completed")
+        ctx.completed_steps.add(self.name)
+        return Outcome(status="SUCCESS", context=ctx, errors=[], duration_ms=duration)
+
+    def compensate(self, ctx: ExecutionContext[T]) -> Union[None, Awaitable[None]]:
+        if self.is_async:
+            return self._compensate_async(ctx)
+
+        ctx.log_event("INFO", self.name, "Compensating Chain")
+        for step in reversed(self.steps):
+            if self._did_step_succeed(ctx, step):
+                res = step.compensate(ctx)
+                if inspect.isawaitable(res):
+                    if inspect.iscoroutine(res):
+                        res.close()
+                    raise RuntimeError(
+                        f"Step '{getattr(step, 'name', 'Unknown')}' returned an async compensation in a sync chain. Use AsyncRunner.")
+        return None
+
+    async def _compensate_async(self, ctx: ExecutionContext[T]) -> None:
+        ctx.log_event("INFO", self.name, "Compensating Chain (Async)")
+        for step in reversed(self.steps):
+            if self._did_step_succeed(ctx, step):
+                res = step.compensate(ctx)
+                if inspect.isawaitable(res):
+                    await res
+
+    def _did_step_succeed(self, ctx: ExecutionContext[T], step: Executable[T]) -> bool:
+        """Checks trace to see if the step completed successfully."""
+        name = getattr(step, "name", None)
+        if not name:
+            return False
+
+        return name in ctx.completed_steps

vibeblocks/components/flow.py

@@ -0,0 +1,278 @@
+"""
+Flow orchestrator for executing trees of Blocks and Chaines.
+Handles high-level failure policies.
+"""
+
+import inspect
+import time
+from typing import Any, Awaitable, Dict, List, Literal, Optional, Tuple, TypeVar, Union
+
+from vibeblocks.core.context import ExecutionContext
+from vibeblocks.core.executable import Executable
+from vibeblocks.core.outcome import Outcome
+from vibeblocks.policies.failure import FailureStrategy
+
+T = TypeVar("T")
+
+
+class Flow(Executable[T]):
+    """
+    The top-level orchestrator that manages a sequence of steps (Blocks or Chaines)
+    and handles failures according to a strategy.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        steps: List[Executable[T]],
+        description: Optional[str] = None,
+        strategy: FailureStrategy = FailureStrategy.ABORT
+    ):
+        self.name = name
+        self.steps = list(steps)
+        self.description = description
+        self.strategy = strategy
+        self._is_async = any(step.is_async for step in self.steps)
+
+    @property
+    def is_async(self) -> bool:
+        """Recursively checks if any step requires async execution."""
+        return self._is_async
+
+    def get_manifest(self) -> Dict[str, Any]:
+        """
+        Returns a dictionary representation of the flow structure, including semantic descriptions.
+        """
+        steps_info = []
+        for step in self.steps:
+            step_data = {
+                "name": getattr(step, "name", "Unknown"),
+                "type": step.__class__.__name__,
+                "description": getattr(step, "description", None) or step.__doc__ or "No description provided."
+            }
+            steps_info.append(step_data)
+
+        return {
+            "name": self.name,
+            "description": self.description or "No description provided.",
+            "steps": steps_info,
+            "strategy": self.strategy.name
+        }
+
+    def execute(self, ctx: ExecutionContext[T]) -> Union[Outcome[T], Awaitable[Outcome[T]]]:
+        if self.is_async:
+            return self._execute_async(ctx)
+        return self._execute_sync(ctx)
+
+    def _execute_sync(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        start_time = time.perf_counter_ns()
+        ctx.log_event("INFO", self.name, "Flow Started")
+        collected_errors = []
+
+        for step in self.steps:
+            try:
+                result = step.execute(ctx)
+
+                self._ensure_not_awaitable(
+                    result, getattr(step, "name", "Unknown"), "step execution"
+                )
+
+                if isinstance(result, Outcome) and result.status != "SUCCESS":
+                    action, outcome = self._handle_failure_strategy(
+                        ctx, step, result.errors, start_time
+                    )
+                    if action == "ABORT":
+                        return outcome
+                    elif action == "CONTINUE":
+                        collected_errors.extend(result.errors)
+                        continue
+                    elif action == "COMPENSATE":
+                        res = step.compensate(ctx)
+                        self._ensure_not_awaitable(
+                            res, getattr(
+                                step, "name", "Unknown"), "step compensation"
+                        )
+                        self.compensate(ctx)
+                        if outcome:
+                            outcome.duration_ms = (
+                                time.perf_counter_ns() - start_time
+                            ) // 1_000_000
+                        return outcome
+
+            except Exception as e:
+                ctx.log_event("ERROR", self.name,
+                              f"Flow Error: {ctx.format_exception(e)}")
+                action, outcome = self._handle_failure_strategy(
+                    ctx, step, [e], start_time
+                )
+                if action == "ABORT":
+                    return outcome
+                elif action == "CONTINUE":
+                    collected_errors.append(e)
+                    continue
+                elif action == "COMPENSATE":
+                    res = step.compensate(ctx)
+                    self._ensure_not_awaitable(
+                        res, getattr(
+                            step, "name", "Unknown"), "step compensation"
+                    )
+                    res = self.compensate(ctx)
+                    self._ensure_not_awaitable(
+                        res, self.name, "flow compensation")
+                    if outcome:
+                        outcome.duration_ms = (
+                            time.perf_counter_ns() - start_time
+                        ) // 1_000_000
+                    return outcome
+
+        return self._finish_flow(ctx, collected_errors, start_time)
+
+    async def _execute_async(self, ctx: ExecutionContext[T]) -> Outcome[T]:
+        start_time = time.perf_counter_ns()
+        ctx.log_event("INFO", self.name, "Flow Started (Async)")
+        collected_errors = []
+
+        for step in self.steps:
+            try:
+                result = step.execute(ctx)
+                if inspect.isawaitable(result):
+                    result = await result
+
+                if isinstance(result, Outcome) and result.status != "SUCCESS":
+                    action, outcome = self._handle_failure_strategy(
+                        ctx, step, result.errors, start_time
+                    )
+                    if action == "ABORT":
+                        return outcome
+                    elif action == "CONTINUE":
+                        collected_errors.extend(result.errors)
+                        continue
+                    elif action == "COMPENSATE":
+                        res = step.compensate(ctx)
+                        if inspect.isawaitable(res):
+                            await res
+
+                        res = self.compensate(ctx)
+                        if inspect.isawaitable(res):
+                            await res
+                        if outcome:
+                            outcome.duration_ms = (
+                                time.perf_counter_ns() - start_time
+                            ) // 1_000_000
+                        return outcome
+
+            except Exception as e:
+                ctx.log_event("ERROR", self.name,
+                              f"Flow Error: {ctx.format_exception(e)}")
+                collected_errors.append(e)
+
+                action, outcome = self._handle_failure_strategy(
+                    ctx, step, [e], start_time
+                )
+                if action == "ABORT":
+                    return outcome
+                elif action == "CONTINUE":
+                    continue
+                elif action == "COMPENSATE":
+                    res = step.compensate(ctx)
+                    if inspect.isawaitable(res):
+                        await res
+
+                    res = self.compensate(ctx)
+                    if inspect.isawaitable(res):
+                        await res
+                    if outcome:
+                        outcome.duration_ms = (
+                            time.perf_counter_ns() - start_time
+                        ) // 1_000_000
+                    return outcome
+
+        return self._finish_flow(ctx, collected_errors, start_time)
+
+    def compensate(self, ctx: ExecutionContext[T]) -> Union[None, Awaitable[None]]:
+        if self.is_async:
+            return self._compensate_async(ctx)
+
+        ctx.log_event("INFO", self.name, "Compensating Flow")
+        for step in reversed(self.steps):
+            if self._did_step_succeed(ctx, step):
+                res = step.compensate(ctx)
+                self._ensure_not_awaitable(
+                    res, getattr(step, "name", "Unknown"), "compensation"
+                )
+        return None
+
+    async def _compensate_async(self, ctx: ExecutionContext[T]) -> None:
+        ctx.log_event("INFO", self.name, "Compensating Flow (Async)")
+        for step in reversed(self.steps):
+            if self._did_step_succeed(ctx, step):
+                res = step.compensate(ctx)
+                if inspect.isawaitable(res):
+                    await res
+
+    def _did_step_succeed(self, ctx: ExecutionContext[T], step: Executable[T]) -> bool:
+        """Checks trace to see if the step completed successfully."""
+        name = getattr(step, "name", None)
+        if not name:
+            return False
+
+        return name in ctx.completed_steps
+
+    def _ensure_not_awaitable(self, result, step_name: str, context: str) -> None:
+        if inspect.isawaitable(result):
+            if inspect.iscoroutine(result):
+                result.close()
+            raise RuntimeError(
+                f"Step '{step_name}' returned a coroutine "
+                f"in a sync flow ({context}). Use AsyncRunner."
+            )
+
+    def _handle_failure_strategy(
+        self,
+        ctx: ExecutionContext[T],
+        step: Executable[T],
+        errors: List[Exception],
+        start_time: int,
+    ) -> Tuple[Literal["ABORT", "CONTINUE", "COMPENSATE"], Optional[Outcome[T]]]:
+        if self.strategy == FailureStrategy.ABORT:
+            ctx.log_event(
+                "ERROR",
+                self.name,
+                f"Flow Aborted due to failure in step '{getattr(step, 'name', 'Unknown')}'",
+            )
+            duration = (time.perf_counter_ns() - start_time) // 1_000_000
+            return "ABORT", Outcome("ABORTED", ctx, errors, duration_ms=duration)
+
+        elif self.strategy == FailureStrategy.CONTINUE:
+            ctx.log_event(
+                "ERROR",
+                self.name,
+                f"Flow Continuing after failure in step '{getattr(step, 'name', 'Unknown')}'",
+            )
+            return "CONTINUE", None
+
+        elif self.strategy == FailureStrategy.COMPENSATE:
+            ctx.log_event(
+                "ERROR",
+                self.name,
+                f"Flow Compensating due to failure in step '{getattr(step, 'name', 'Unknown')}'",
+            )
+            duration = (time.perf_counter_ns() - start_time) // 1_000_000
+            return "COMPENSATE", Outcome("FAILED", ctx, errors, duration_ms=duration)
+
+        return "CONTINUE", None
+
+    def _finish_flow(
+        self, ctx: ExecutionContext[T], collected_errors: List[Exception], start_time: int
+    ) -> Outcome[T]:
+        final_status: Literal["SUCCESS", "FAILED"] = (
+            "FAILED" if collected_errors else "SUCCESS"
+        )
+        ctx.log_event("INFO", self.name,
+                      f"Flow Completed with status {final_status}")
+
+        if final_status == "SUCCESS":
+            ctx.completed_steps.add(self.name)
+
+        duration = (time.perf_counter_ns() - start_time) // 1_000_000
+        return Outcome(final_status, ctx, collected_errors, duration_ms=duration)