blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/python3/blok/logging/logger.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+import json
+import threading
+from datetime import datetime, timezone
+from enum import IntEnum
+from typing import Any, Dict, List, Optional
+
+
+class LogLevel(IntEnum):
+    DEBUG = 0
+    INFO = 1
+    WARN = 2
+    ERROR = 3
+
+
+_LEVEL_NAMES = {
+    LogLevel.DEBUG: "DEBUG",
+    LogLevel.INFO: "INFO",
+    LogLevel.WARN: "WARN",
+    LogLevel.ERROR: "ERROR",
+}
+
+
+def _parse_log_level(level: str) -> LogLevel:
+    """Parse a log level string to LogLevel enum."""
+    mapping = {"DEBUG": LogLevel.DEBUG, "INFO": LogLevel.INFO, "WARN": LogLevel.WARN, "ERROR": LogLevel.ERROR}
+    return mapping.get(level.upper(), LogLevel.INFO)
+
+
+class Logger:
+    """Structured logger with a capture buffer.
+
+    Log entries are captured and can be returned in ExecutionResult.logs.
+    """
+
+    def __init__(self, min_level: LogLevel = LogLevel.INFO):
+        self._entries: List[str] = []
+        self._min_level = min_level
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_level_str(cls, level: str) -> Logger:
+        return cls(min_level=_parse_log_level(level))
+
+    def _log(self, level: LogLevel, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
+        if level < self._min_level:
+            return
+
+        ts = datetime.now(timezone.utc).isoformat()
+        level_name = _LEVEL_NAMES[level]
+
+        if fields:
+            fields_str = " " + json.dumps(fields, default=str)
+        else:
+            fields_str = ""
+
+        entry = f"[{level_name}] {ts} {message}{fields_str}"
+
+        with self._lock:
+            self._entries.append(entry)
+
+    def debug(self, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
+        self._log(LogLevel.DEBUG, message, fields)
+
+    def info(self, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
+        self._log(LogLevel.INFO, message, fields)
+
+    def warn(self, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
+        self._log(LogLevel.WARN, message, fields)
+
+    def error(self, message: str, fields: Optional[Dict[str, Any]] = None) -> None:
+        self._log(LogLevel.ERROR, message, fields)
+
+    def lines(self) -> List[str]:
+        """Return all log entries as formatted strings."""
+        with self._lock:
+            return list(self._entries)
+
+    def clear(self) -> None:
+        """Reset the log buffer."""
+        with self._lock:
+            self._entries.clear()

package/dist/scaffold-repo/sdks/python3/blok/middleware/__init__.py

@@ -0,0 +1,4 @@
+from blok.middleware.logging_middleware import logging_middleware
+from blok.middleware.recovery_middleware import recovery_middleware
+
+__all__ = ["logging_middleware", "recovery_middleware"]

package/dist/scaffold-repo/sdks/python3/blok/middleware/logging_middleware.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+import time
+import logging
+from typing import Any, Callable, Dict
+
+logger = logging.getLogger("blok")
+
+
+def logging_middleware(next_fn: Callable) -> Callable:
+    """Middleware that logs the execution of each node with timing."""
+
+    def wrapper(ctx, config: Dict[str, Any]) -> Any:
+        start = time.monotonic()
+        logger.info("node execution started [workflow=%s]", ctx.workflow_name)
+
+        try:
+            result = next_fn(ctx, config)
+            duration_ms = (time.monotonic() - start) * 1000.0
+            logger.info(
+                "node execution completed [workflow=%s] [duration_ms=%.2f]",
+                ctx.workflow_name,
+                duration_ms,
+            )
+            return result
+        except Exception as e:
+            duration_ms = (time.monotonic() - start) * 1000.0
+            logger.error(
+                "node execution failed [workflow=%s] [duration_ms=%.2f] [error=%s]",
+                ctx.workflow_name,
+                duration_ms,
+                str(e),
+            )
+            raise
+
+    return wrapper

package/dist/scaffold-repo/sdks/python3/blok/middleware/recovery_middleware.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+import traceback
+from typing import Any, Callable, Dict
+
+from blok.errors.blok_error import BlokError
+from blok.errors.node_error import NodeError, ErrorCategory
+
+
+def recovery_middleware(next_fn: Callable) -> Callable:
+    """Middleware that catches unhandled exceptions and converts them to NodeErrors.
+
+    ``BlokError`` instances pass through untouched — they're already
+    structured per master plan §17 and would lose every field except
+    ``message`` if wrapped as a legacy ``NodeError``. Same with the legacy
+    ``NodeError``: pre-wrapped errors keep their shape.
+    """
+
+    def wrapper(ctx, config: Dict[str, Any]) -> Any:
+        try:
+            return next_fn(ctx, config)
+        except BlokError:
+            # Structured BlokError: pass through verbatim so the registry
+            # + gRPC servicer can serialize every field losslessly.
+            raise
+        except NodeError:
+            raise
+        except Exception as e:
+            raise NodeError(
+                message=f"unhandled exception: {e}",
+                code=500,
+                category=ErrorCategory.EXECUTION,
+                details={"traceback": traceback.format_exc()},
+                cause=e,
+            ) from e
+
+    return wrapper

package/dist/scaffold-repo/sdks/python3/blok/node/__init__.py

@@ -0,0 +1,4 @@
+from blok.node.node_handler import NodeHandler
+from blok.node.node_registry import NodeRegistry
+
+__all__ = ["NodeHandler", "NodeRegistry"]

package/dist/scaffold-repo/sdks/python3/blok/node/define_node.py

@@ -0,0 +1,239 @@
+"""Typed, declarative node authoring for the Python SDK (SPEC-B P2).
+
+The `@node` decorator is the Python equivalent of the TypeScript `defineNode`:
+declare typed Pydantic `Input`/`Output` models, get automatic validation +
+JSON-Schema reflection, and auto-registration — instead of a raw
+`Dict[str, Any]` handler with manual `.get()` parsing.
+
+Example::
+
+    from pydantic import BaseModel, Field
+    from blok import node, Context
+
+    class Input(BaseModel):
+        query: str = Field(min_length=1)
+        limit: int = Field(10, ge=1, le=100)
+
+    class Output(BaseModel):
+        results: list[str]
+        count: int
+
+    @node(name="@acme/search", description="Full-text search")
+    def search(ctx: Context, input: Input) -> Output:
+        rows = do_search(input.query, input.limit)   # input is a validated Input
+        return Output(results=rows, count=len(rows))
+
+The SDK validates `config -> Input` BEFORE `search` runs (a Pydantic
+`ValidationError` becomes a structured `BlokError` with HTTP 400 + field paths),
+validates the return against `Output`, and serializes it to a JSON dict. Omit
+the model annotations and `@node` behaves like a legacy raw-dict handler, so
+migration is incremental and the existing `NodeHandler` ABC keeps working.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import inspect
+import logging
+import os
+from typing import Any, Callable, Dict, List, Optional, Tuple, Type, get_type_hints
+
+from pydantic import BaseModel, ValidationError
+
+from ..errors.blok_error import BlokError
+from ..types.context import Context
+from .node_handler import NodeHandler
+
+# Module-global collection of `@node`-decorated handlers. Importing the module
+# that declares them runs the decorator (side effect) and appends here;
+# `register_decorated(registry)` then flushes them into a registry, so authors
+# never edit a central `register_all`.
+_DECORATED_NODES: List[NodeHandler] = []
+
+
+def _format_validation_error(node_name: str, err: ValidationError) -> str:
+    parts: List[str] = []
+    for e in err.errors():
+        loc = ".".join(str(x) for x in e.get("loc", ())) or "(root)"
+        parts.append(f"{loc} ({e.get('msg', 'invalid')})")
+    return f"Validation failed for node '{node_name}': " + "; ".join(parts)
+
+
+class FunctionNode(NodeHandler):
+    """A `NodeHandler` produced by `@node`. Validates I/O against Pydantic models."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        func: Callable[[Context, Any], Any],
+        input_model: Optional[Type[BaseModel]],
+        output_model: Optional[Type[BaseModel]],
+    ) -> None:
+        self.name = name
+        self.description = description
+        self._func = func
+        self.input_model = input_model
+        self.output_model = output_model
+
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        # 1. Validate input → typed model (or pass the raw dict through untyped).
+        validated_input: Any = config
+        if self.input_model is not None:
+            try:
+                validated_input = self.input_model.model_validate(config)
+            except ValidationError as err:
+                raise BlokError.validation(
+                    code="NODE_INPUT_VALIDATION",
+                    message=_format_validation_error(self.name, err),
+                    details=err.errors(),
+                    http_status=400,
+                    node=self.name,
+                ) from err
+
+        # 2. Run the user's function.
+        result = self._func(ctx, validated_input)
+
+        # 3. Validate + serialize output (when declared).
+        if self.output_model is not None:
+            model = result if isinstance(result, self.output_model) else None
+            if model is None:
+                try:
+                    model = self.output_model.model_validate(result)
+                except ValidationError as err:
+                    raise BlokError.validation(
+                        code="NODE_OUTPUT_VALIDATION",
+                        message=f"Output validation failed for node '{self.name}': "
+                        + "; ".join(
+                            f"{'.'.join(str(x) for x in e.get('loc', ()))} ({e.get('msg', 'invalid')})"
+                            for e in err.errors()
+                        ),
+                        details=err.errors(),
+                        http_status=500,
+                        node=self.name,
+                    ) from err
+            return model.model_dump(mode="json")
+
+        # Untyped: a Pydantic model still serializes; otherwise pass through.
+        if isinstance(result, BaseModel):
+            return result.model_dump(mode="json")
+        return result
+
+    def input_json_schema(self) -> Optional[Dict[str, Any]]:
+        return self.input_model.model_json_schema() if self.input_model is not None else None
+
+    def output_json_schema(self) -> Optional[Dict[str, Any]]:
+        return self.output_model.model_json_schema() if self.output_model is not None else None
+
+
+def _resolve_models(
+    func: Callable[..., Any],
+) -> Tuple[Optional[Type[BaseModel]], Optional[Type[BaseModel]]]:
+    """Infer the input/output Pydantic models from a node function's signature.
+
+    Convention: `def execute(ctx, input: Input) -> Output`. The input model is
+    the annotation of the SECOND positional parameter; the output model is the
+    return annotation. Non-`BaseModel` (or missing) annotations → `None`
+    (untyped — the node receives the raw dict).
+    """
+    try:
+        hints = get_type_hints(func)
+    except Exception:
+        hints = {}
+
+    sig = inspect.signature(func)
+    params = list(sig.parameters.values())
+
+    input_model: Optional[Type[BaseModel]] = None
+    if len(params) >= 2:
+        second = params[1]
+        ann = hints.get(second.name, second.annotation)
+        if isinstance(ann, type) and issubclass(ann, BaseModel):
+            input_model = ann
+
+    ret = hints.get("return", sig.return_annotation)
+    output_model = ret if isinstance(ret, type) and issubclass(ret, BaseModel) else None
+
+    return input_model, output_model
+
+
+def node(
+    name: str,
+    description: str = "",
+    *,
+    register: bool = True,
+) -> Callable[[Callable[[Context, Any], Any]], FunctionNode]:
+    """Decorate a node function into a validated, auto-registered `FunctionNode`.
+
+    :param name: the node's registered name (e.g. `"@acme/search"`).
+    :param description: human-readable description (surfaced in `/__blok/nodes`).
+    :param register: append to the module-global collection for
+        `register_decorated()`. Set `False` for ad-hoc / test nodes.
+    """
+
+    def decorator(func: Callable[[Context, Any], Any]) -> FunctionNode:
+        input_model, output_model = _resolve_models(func)
+        handler = FunctionNode(
+            name=name,
+            description=description,
+            func=func,
+            input_model=input_model,
+            output_model=output_model,
+        )
+        if register:
+            _DECORATED_NODES.append(handler)
+        return handler
+
+    return decorator
+
+
+def registered_nodes() -> List[NodeHandler]:
+    """All `@node`-decorated handlers collected so far (import-order)."""
+    return list(_DECORATED_NODES)
+
+
+def register_decorated(registry: Any) -> int:
+    """Register every collected `@node` handler into `registry`. Returns the count."""
+    count = 0
+    for handler in _DECORATED_NODES:
+        registry.register(getattr(handler, "name"), handler)
+        count += 1
+    return count
+
+
+def load_user_nodes(registry: Any, nodes_dir: Optional[str]) -> int:
+    """Discover + register user-authored `@node` handlers from a directory.
+
+    Each user node lives in ``<nodes_dir>/<name>/node.py`` and self-registers via
+    the `@node` decorator on import. We import each module so its decorator runs,
+    then register only the handlers collected during THIS call — purely additive,
+    so the SDK's built-in nodes (registered earlier) are untouched. Returns the
+    number of newly registered nodes. A node that fails to import is logged and
+    skipped so one bad file can't sink the whole runtime.
+    """
+    if not nodes_dir or not os.path.isdir(nodes_dir):
+        return 0
+    before = len(_DECORATED_NODES)
+    log = logging.getLogger("blok.discovery")
+    for entry in sorted(os.listdir(nodes_dir)):
+        node_file = os.path.join(nodes_dir, entry, "node.py")
+        if not os.path.isfile(node_file):
+            continue
+        spec = importlib.util.spec_from_file_location(f"blok_user_node_{entry}", node_file)
+        if spec is None or spec.loader is None:
+            continue
+        try:
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)  # runs the @node decorator(s)
+        except Exception:  # noqa: BLE001 — one bad node must not crash the runtime
+            log.exception("Failed to load user node from %s", node_file)
+    new_handlers = _DECORATED_NODES[before:]
+    for handler in new_handlers:
+        registry.register(getattr(handler, "name"), handler)
+    return len(new_handlers)
+
+
+def _reset_decorated_for_tests() -> None:
+    """Clear the global collection (test isolation)."""
+    _DECORATED_NODES.clear()

package/dist/scaffold-repo/sdks/python3/blok/node/node_handler.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Tuple
+
+from blok.types.context import Context
+
+
+class NodeHandler(ABC):
+    """Base class that all Blok nodes must inherit from.
+
+    Subclasses must implement the ``execute`` method which receives the
+    workflow context and node-specific configuration, and returns a
+    data value (any JSON-serializable value).
+
+    Example::
+
+        class GreetNode(NodeHandler):
+            def execute(self, ctx, config):
+                name = ctx.request.body_str("name") or "World"
+                prefix = config.get("prefix", "Hello")
+                return {"message": f"{prefix}, {name}!"}
+    """
+
+    @abstractmethod
+    def execute(self, ctx: Context, config: Dict[str, Any]) -> Any:
+        """Execute the node logic.
+
+        Args:
+            ctx: The workflow execution context.
+            config: Node-specific configuration.
+
+        Returns:
+            JSON-serializable result data.
+        """
+        raise NotImplementedError

package/dist/scaffold-repo/sdks/python3/blok/node/node_registry.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+import time
+import traceback
+from typing import Any, Callable, Dict, List, Optional
+
+from blok.node.node_handler import NodeHandler
+from blok.types.execution_request import ExecutionRequest
+from blok.types.execution_result import ExecutionMetrics, ExecutionResult
+from blok.errors.blok_error import BlokError
+from blok.errors.node_error import NodeError
+
+
+# Middleware type: receives a callable and returns a wrapped callable
+Middleware = Callable[
+    [Callable[["Context", Dict[str, Any]], Any]],
+    Callable[["Context", Dict[str, Any]], Any],
+]
+
+
+class HealthStatus:
+    """Represents the health status of the runtime."""
+
+    __slots__ = ("status", "version", "nodes_loaded")
+
+    def __init__(self, status: str, version: str, nodes_loaded: List[str]):
+        self.status = status
+        self.version = version
+        self.nodes_loaded = nodes_loaded
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "status": self.status,
+            "version": self.version,
+            "nodes_loaded": self.nodes_loaded,
+        }
+
+
+class NodeRegistry:
+    """Manages registered node handlers and dispatches execution requests.
+
+    Holds a map of node names to handler instances, applies middleware,
+    and measures execution timing.
+    """
+
+    def __init__(self, version: str = "1.0.0"):
+        self._nodes: Dict[str, NodeHandler] = {}
+        self._middlewares: List[Middleware] = []
+        self._version = version
+
+    def register(self, name: str, handler: NodeHandler) -> None:
+        """Register a node handler under the given name."""
+        self._nodes[name] = handler
+
+    def get(self, name: str) -> Optional[NodeHandler]:
+        """Look up a node handler by name."""
+        return self._nodes.get(name)
+
+    def use(self, middleware: Middleware) -> None:
+        """Add a middleware to the execution pipeline."""
+        self._middlewares.append(middleware)
+
+    def node_names(self) -> List[str]:
+        """Return the names of all registered nodes."""
+        return sorted(self._nodes.keys())
+
+    def execute(self, execution_request: ExecutionRequest) -> ExecutionResult:
+        """Execute a node by dispatching through the registry.
+
+        Returns an ExecutionResult with timing metrics.
+        """
+        node_name = execution_request.node.name
+        handler = self.get(node_name)
+
+        if handler is None:
+            return ExecutionResult.error_result(
+                f"node '{node_name}' not found in registry"
+            )
+
+        # Build a callable that invokes the handler
+        def call_handler(ctx, config):
+            return handler.execute(ctx, config)
+
+        callable_fn = call_handler
+
+        # Apply middleware chain (each middleware wraps the callable)
+        for mw in self._middlewares:
+            callable_fn = mw(callable_fn)
+
+        start_time = time.monotonic()
+
+        try:
+            data = callable_fn(
+                execution_request.context,
+                execution_request.node.config,
+            )
+            duration_ms = (time.monotonic() - start_time) * 1000.0
+
+            metrics = ExecutionMetrics(duration_ms=duration_ms)
+            result = ExecutionResult.success_with_metrics(data, metrics)
+
+            # Include context vars so the runner can propagate them downstream
+            ctx_vars = execution_request.context.vars
+            if ctx_vars:
+                result.with_vars(ctx_vars)
+
+            return result
+
+        except BlokError as e:
+            # Structured-error path (master plan §17). The BlokError instance
+            # is passed through verbatim so the gRPC servicer can serialize
+            # every field (category, severity, remediation, retryable hints,
+            # cause chain, etc.) into the proto NodeError.
+            duration_ms = (time.monotonic() - start_time) * 1000.0
+            result = ExecutionResult(success=False, data=None, errors=e)
+            result.with_metrics(ExecutionMetrics(duration_ms=duration_ms))
+            return result
+
+        except NodeError as e:
+            duration_ms = (time.monotonic() - start_time) * 1000.0
+            result = ExecutionResult.error_with_details(e.message, e.to_dict())
+            result.with_metrics(ExecutionMetrics(duration_ms=duration_ms))
+            return result
+
+        except Exception as e:
+            duration_ms = (time.monotonic() - start_time) * 1000.0
+            result = ExecutionResult.error_result(str(e))
+            result.with_metrics(ExecutionMetrics(duration_ms=duration_ms))
+            return result
+
+    def health(self) -> HealthStatus:
+        """Return the health status of the runtime."""
+        return HealthStatus(
+            status="healthy",
+            version=self._version,
+            nodes_loaded=self.node_names(),
+        )