blokctl 1.3.0 → 1.4.1

package/dist/scaffold-repo/sdks/python3/blok/server/runtime_server.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+import json
+import logging
+import signal
+import sys
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from typing import Optional
+
+from blok.node.node_registry import NodeRegistry
+from blok.config.server_config import ServerConfig
+from blok.types.execution_request import ExecutionRequest
+from blok.types.execution_result import ExecutionResult
+
+logger = logging.getLogger("blok")
+
+
+class _RequestHandler(BaseHTTPRequestHandler):
+    """HTTP request handler for the blok runtime."""
+
+    registry: NodeRegistry
+    config: ServerConfig
+
+    def do_POST(self) -> None:
+        if self.path != "/execute":
+            self._write_json(
+                404,
+                ExecutionResult.error_result(f"not found: {self.path}").to_dict(),
+            )
+            return
+
+        content_length = int(self.headers.get("Content-Length", 0))
+        body = self.rfile.read(content_length)
+
+        try:
+            parsed = json.loads(body)
+        except (json.JSONDecodeError, ValueError) as e:
+            self._write_json(
+                400,
+                ExecutionResult.error_result(f"invalid JSON: {e}").to_dict(),
+            )
+            return
+
+        execution_request = ExecutionRequest.from_dict(parsed)
+        result = self.registry.execute(execution_request)
+        self._write_json(200, result.to_dict())
+
+    def do_GET(self) -> None:
+        if self.path != "/health":
+            self._write_json(404, {"error": f"not found: {self.path}"})
+            return
+
+        health = self.registry.health()
+        self._write_json(200, health.to_dict())
+
+    def _write_json(self, status_code: int, data: dict) -> None:
+        response_body = json.dumps(data).encode("utf-8")
+
+        self.send_response(status_code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(response_body)))
+
+        if self.config.enable_cors:
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+
+        self.end_headers()
+        self.wfile.write(response_body)
+
+    def do_OPTIONS(self) -> None:
+        """Handle CORS preflight requests."""
+        self.send_response(204)
+        if self.config.enable_cors:
+            self.send_header("Access-Control-Allow-Origin", "*")
+            self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+            self.send_header("Access-Control-Allow-Headers", "Content-Type, Authorization")
+        self.end_headers()
+
+    def log_message(self, format: str, *args) -> None:
+        """Override to use Python logging instead of stderr."""
+        logger.debug("%s %s", self.address_string(), format % args)
+
+    def handle_one_request(self) -> None:
+        """Override to suppress ConnectionResetError noise.
+
+        The Blok runner closes HTTP connections after reading the response,
+        which causes Python's http.server to log ConnectionResetError tracebacks.
+        These are expected and not actual errors.
+        """
+        try:
+            super().handle_one_request()
+        except ConnectionResetError:
+            self.close_connection = True
+
+
+class RuntimeServer:
+    """Blok HTTP server that handles execute and health requests.
+
+    This server exposes two endpoints matching the Blok SDK contract:
+
+    - ``POST /execute`` - Execute a node with the provided ExecutionRequest JSON
+    - ``GET /health``   - Return runtime health status
+
+    Usage::
+
+        registry = NodeRegistry()
+        registry.register("my-node", MyNode())
+
+        server = RuntimeServer(registry)
+        server.start()  # blocks until shutdown
+    """
+
+    def __init__(
+        self,
+        registry: NodeRegistry,
+        config: Optional[ServerConfig] = None,
+    ):
+        self.registry = registry
+        self.config = config or ServerConfig.from_env()
+        self._server: Optional[HTTPServer] = None
+
+    def start(self) -> None:
+        """Start the HTTP server. Blocks until shutdown."""
+        handler_class = type(
+            "Handler",
+            (_RequestHandler,),
+            {"registry": self.registry, "config": self.config},
+        )
+
+        self._server = HTTPServer(
+            (self.config.host, self.config.port),
+            handler_class,
+        )
+        self._server.timeout = self.config.read_timeout_sec
+
+        # Set up graceful shutdown.
+        # NOTE: We use sys.exit() instead of self._server.shutdown() because
+        # shutdown() must be called from a different thread than serve_forever().
+        # Calling it from a signal handler in the same thread causes a deadlock.
+        def shutdown_handler(signum, frame):
+            logger.info("Shutdown signal received, stopping server...")
+            sys.exit(0)
+
+        signal.signal(signal.SIGTERM, shutdown_handler)
+        signal.signal(signal.SIGINT, shutdown_handler)
+
+        logger.info(
+            "Blok runtime v%s starting on %s",
+            self.config.version,
+            self.config.address,
+        )
+        logger.info("Registered nodes: %s", self.registry.node_names())
+
+        try:
+            self._server.serve_forever()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self._server.server_close()
+            logger.info("Server stopped.")
+
+    def shutdown(self) -> None:
+        """Gracefully shut down the server."""
+        if self._server:
+            self._server.shutdown()

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

@@ -0,0 +1,13 @@
+from blok.types.context import Context, Request, Response
+from blok.types.execution_request import ExecutionRequest, NodeConfig
+from blok.types.execution_result import ExecutionResult, ExecutionMetrics
+
+__all__ = [
+    "Context",
+    "Request",
+    "Response",
+    "ExecutionRequest",
+    "NodeConfig",
+    "ExecutionResult",
+    "ExecutionMetrics",
+]

package/dist/scaffold-repo/sdks/python3/blok/types/context.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+from typing import Any, Callable, Dict, Optional
+
+
+class Request:
+    """Represents the incoming HTTP request data."""
+
+    __slots__ = ("body", "headers", "params", "query", "method", "url", "cookies", "base_url")
+
+    def __init__(
+        self,
+        body: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, str]] = None,
+        query: Optional[Dict[str, str]] = None,
+        method: str = "",
+        url: str = "",
+        cookies: Optional[Dict[str, str]] = None,
+        base_url: str = "",
+    ):
+        self.body = body
+        self.headers = headers or {}
+        self.params = params or {}
+        self.query = query or {}
+        self.method = method
+        self.url = url
+        self.cookies = cookies or {}
+        self.base_url = base_url
+
+    def body_map(self) -> Optional[Dict[str, Any]]:
+        """Return the request body as a dict, or None if not a dict."""
+        if isinstance(self.body, dict):
+            return self.body
+        return None
+
+    def body_str(self, key: str, default: str = "") -> str:
+        """Get a string value from the body dict."""
+        body = self.body_map()
+        if body is None:
+            return default
+        val = body.get(key)
+        return str(val) if val is not None else default
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Request:
+        return cls(
+            body=data.get("body"),
+            headers=data.get("headers", {}),
+            params=data.get("params", {}),
+            query=data.get("query", {}),
+            method=data.get("method", ""),
+            url=data.get("url", ""),
+            cookies=data.get("cookies", {}),
+            base_url=data.get("baseUrl", ""),
+        )
+
+
+class Response:
+    """Represents the workflow response."""
+
+    __slots__ = ("data", "content_type", "success", "error")
+
+    def __init__(
+        self,
+        data: Any = None,
+        content_type: str = "application/json",
+        success: bool = True,
+        error: Any = None,
+    ):
+        self.data = data
+        self.content_type = content_type
+        self.success = success
+        self.error = error
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Response:
+        return cls(
+            data=data.get("data"),
+            content_type=data.get("contentType", "application/json"),
+            success=data.get("success", True),
+            error=data.get("error"),
+        )
+
+
+class Context:
+    """Represents the workflow execution context passed between nodes."""
+
+    __slots__ = ("id", "workflow_name", "workflow_path", "request", "response", "vars", "env", "_emit_sink")
+
+    def __init__(
+        self,
+        id: str = "",
+        workflow_name: str = "",
+        workflow_path: str = "",
+        request: Optional[Request] = None,
+        response: Optional[Response] = None,
+        vars: Optional[Dict[str, Any]] = None,
+        env: Optional[Dict[str, str]] = None,
+    ):
+        self.id = id
+        self.workflow_name = workflow_name
+        self.workflow_path = workflow_path
+        self.request = request or Request()
+        self.response = response or Response()
+        self.vars = vars if vars is not None else {}
+        self.env = env if env is not None else {}
+        # Set by the gRPC server during ``ExecuteStream`` so ``emit()`` can
+        # push live data events back to the runner. ``None`` under the unary
+        # ``Execute`` path (and any non-streaming caller) — ``emit()`` is then
+        # a no-op, so node code can call it unconditionally.
+        self._emit_sink: Optional[Callable[[Any], None]] = None
+
+    def emit(self, snapshot: Any) -> None:
+        """Emit a live intermediate event while the node is still running.
+
+        Under an ``ExecuteStream`` call (a workflow step with
+        ``streamTo: "sse"`` / ``stream: true``), each ``emit(...)`` is sent to
+        the runner as a ``PartialResult`` frame AS IT HAPPENS — before this
+        node returns its terminal result. The runner forwards it to the SSE
+        client live. Use it to stream tokens, tool-calls, or discovered
+        sources from a long-running agent::
+
+            def execute(ctx, config):
+                ctx.emit({"event": "text", "data": {"delta": "Hel"}, "id": "1"})
+                ctx.emit({"event": "source", "data": {"url": "..."}, "id": "2"})
+                return {"answer": "Hello", "sources": [...]}
+
+        ``snapshot`` is any JSON-serializable value. Emit a framed object
+        ``{"event": str, "data": Any, "id": str?, "retry": int?}`` to name the
+        SSE event yourself (the producer holds the semantic context); any other
+        value becomes the frame ``data`` with no explicit event name.
+
+        A no-op when the node runs under the unary ``Execute`` path (no SSE
+        sink installed), so the same handler works in both modes.
+        """
+        sink = self._emit_sink
+        if sink is not None:
+            sink(snapshot)
+
+    def _set_emit_sink(self, sink: Optional[Callable[[Any], None]]) -> None:
+        """Install (or clear) the live-emit sink. Called by the gRPC server."""
+        self._emit_sink = sink
+
+    def set_var(self, key: str, value: Any) -> None:
+        """Store a variable in the context for downstream nodes."""
+        self.vars[key] = value
+
+    def get_var(self, key: str, default: Any = None) -> Any:
+        """Retrieve a variable from the context."""
+        return self.vars.get(key, default)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> Context:
+        return cls(
+            id=data.get("id", ""),
+            workflow_name=data.get("workflow_name", ""),
+            workflow_path=data.get("workflow_path", ""),
+            request=Request.from_dict(data.get("request", {})),
+            response=Response.from_dict(data.get("response", {})),
+            vars=data.get("vars", {}),
+            env=data.get("env", {}),
+        )

package/dist/scaffold-repo/sdks/python3/blok/types/execution_request.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+from typing import Any, Dict, Optional
+from blok.types.context import Context
+
+
+class NodeConfig:
+    """Represents node-specific configuration from the runner."""
+
+    __slots__ = ("name", "type", "config")
+
+    def __init__(
+        self,
+        name: str = "",
+        type: str = "",
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        self.name = name
+        self.type = type
+        self.config = config or {}
+
+    def get_config_str(self, key: str, default: str = "") -> str:
+        """Retrieve a string config value with a default."""
+        val = self.config.get(key)
+        if val is None:
+            return default
+        return str(val)
+
+    def get_config_int(self, key: str, default: int = 0) -> int:
+        """Retrieve an integer config value with a default."""
+        val = self.config.get(key)
+        if val is None:
+            return default
+        try:
+            return int(val)
+        except (ValueError, TypeError):
+            return default
+
+    def get_config_bool(self, key: str, default: bool = False) -> bool:
+        """Retrieve a boolean config value with a default."""
+        val = self.config.get(key)
+        if val is None:
+            return default
+        if isinstance(val, bool):
+            return val
+        return default
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> NodeConfig:
+        return cls(
+            name=data.get("name", ""),
+            type=data.get("type", ""),
+            config=data.get("config", {}),
+        )
+
+
+class ExecutionRequest:
+    """The request received from the Blok runner."""
+
+    __slots__ = ("node", "context")
+
+    def __init__(
+        self,
+        node: Optional[NodeConfig] = None,
+        context: Optional[Context] = None,
+    ):
+        self.node = node or NodeConfig()
+        self.context = context or Context()
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> ExecutionRequest:
+        return cls(
+            node=NodeConfig.from_dict(data.get("node", {})),
+            context=Context.from_dict(data.get("context", {})),
+        )

package/dist/scaffold-repo/sdks/python3/blok/types/execution_result.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+from typing import Any, Dict, List, Optional
+
+
+class ExecutionMetrics:
+    """Captures performance metrics for a node execution."""
+
+    __slots__ = ("duration_ms", "cpu_ms", "memory_bytes")
+
+    def __init__(
+        self,
+        duration_ms: Optional[float] = None,
+        cpu_ms: Optional[float] = None,
+        memory_bytes: Optional[int] = None,
+    ):
+        self.duration_ms = duration_ms
+        self.cpu_ms = cpu_ms
+        self.memory_bytes = memory_bytes
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {}
+        if self.duration_ms is not None:
+            result["duration_ms"] = self.duration_ms
+        if self.cpu_ms is not None:
+            result["cpu_ms"] = self.cpu_ms
+        if self.memory_bytes is not None:
+            result["memory_bytes"] = self.memory_bytes
+        return result
+
+
+class ExecutionResult:
+    """The response returned to the Blok runner."""
+
+    __slots__ = ("success", "data", "errors", "logs", "metrics", "vars")
+
+    def __init__(
+        self,
+        success: bool = True,
+        data: Any = None,
+        errors: Any = None,
+        logs: Optional[List[str]] = None,
+        metrics: Optional[ExecutionMetrics] = None,
+        vars: Optional[Dict[str, Any]] = None,
+    ):
+        self.success = success
+        self.data = data
+        self.errors = errors
+        self.logs = logs
+        self.metrics = metrics
+        self.vars = vars
+
+    def with_vars(self, vars: Dict[str, Any]) -> ExecutionResult:
+        """Attach context variables to the result."""
+        self.vars = vars
+        return self
+
+    def with_logs(self, logs: List[str]) -> ExecutionResult:
+        """Add log entries to the result."""
+        self.logs = logs
+        return self
+
+    def with_metrics(self, metrics: ExecutionMetrics) -> ExecutionResult:
+        """Add execution metrics to the result."""
+        self.metrics = metrics
+        return self
+
+    def to_dict(self) -> Dict[str, Any]:
+        result: Dict[str, Any] = {
+            "success": self.success,
+            "data": self.data,
+            "errors": self.errors,
+        }
+        if self.logs is not None:
+            result["logs"] = self.logs
+        if self.metrics is not None:
+            result["metrics"] = self.metrics.to_dict()
+        if self.vars is not None:
+            result["vars"] = self.vars
+        return result
+
+    @classmethod
+    def success_result(cls, data: Any) -> ExecutionResult:
+        """Create a successful execution result."""
+        return cls(success=True, data=data)
+
+    @classmethod
+    def error_result(cls, message: str) -> ExecutionResult:
+        """Create a failed execution result."""
+        return cls(success=False, data=None, errors={"message": message})
+
+    @classmethod
+    def success_with_metrics(cls, data: Any, metrics: ExecutionMetrics) -> ExecutionResult:
+        """Create a successful result with metrics."""
+        return cls(success=True, data=data, metrics=metrics)
+
+    @classmethod
+    def error_with_details(cls, message: str, details: Dict[str, Any]) -> ExecutionResult:
+        """Create a failed result with additional details."""
+        return cls(
+            success=False,
+            data=None,
+            errors={"message": message, "details": details},
+        )

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

@@ -0,0 +1,10 @@
+from blok.worker.worker_config import WorkerConfig
+from blok.worker.job_message import JobMessage
+from blok.worker.worker import Worker, listen_and_serve_worker
+
+__all__ = [
+    "WorkerConfig",
+    "JobMessage",
+    "Worker",
+    "listen_and_serve_worker",
+]

package/dist/scaffold-repo/sdks/python3/blok/worker/job_message.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class JobMessage:
+    """Represents a job received from a NATS worker queue.
+
+    Mirrors the Go/Rust JobMessage struct.
+    """
+
+    __slots__ = ("id", "queue", "data", "headers", "attempt", "max_retries")
+
+    def __init__(
+        self,
+        id: str = "",
+        queue: str = "",
+        data: Any = None,
+        headers: Optional[Dict[str, str]] = None,
+        attempt: int = 0,
+        max_retries: int = 3,
+    ):
+        self.id = id
+        self.queue = queue
+        self.data = data
+        self.headers = headers or {}
+        self.attempt = attempt
+        self.max_retries = max_retries
+
+    def data_map(self) -> Optional[Dict[str, Any]]:
+        """Return the job data as a dict, or None if not a dict."""
+        if isinstance(self.data, dict):
+            return self.data
+        return None