stepflow-py 0.2.1__py3-none-any.whl

stepflow_py/__init__.py

@@ -0,0 +1,58 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+from .context import StepflowContext
+from .flow_builder import FlowBuilder, StepHandle
+from .generated_protocol import (
+    ErrorAction,
+    OnErrorDefault,
+    OnErrorFail,
+    OnErrorRetry,
+    OnErrorSkip,
+    OnSkipDefault,
+    OnSkipSkip,
+    SkipAction,
+)
+from .stdio_server import StepflowStdioServer
+from .value import JsonPath, StepReference, Valuable, Value, WorkflowInput
+
+__all__ = [
+    # Core classes
+    "StepflowStdioServer",
+    "StepflowContext",
+    "FlowBuilder",
+    # Value API for cleaner workflow definitions
+    "Value",
+    "Valuable",
+    # Helper classes for type hints and intermediate objects
+    "JsonPath",
+    "StepHandle",
+    "StepReference",
+    "WorkflowInput",
+    # Error and Skip Action types
+    "ErrorAction",
+    "OnErrorFail",
+    "OnErrorSkip",
+    "OnErrorRetry",
+    "OnErrorDefault",
+    "SkipAction",
+    "OnSkipSkip",
+    "OnSkipDefault",
+]
+
+if __name__ == "__main__":
+    from . import main
+
+    main.main()

stepflow_py/context.py

@@ -0,0 +1,182 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import Any, TypeVar
+from uuid import uuid4
+
+from stepflow_py.generated_protocol import (
+    EvaluateFlowResult,
+    Flow,
+    FlowResultFailed,
+    FlowResultSkipped,
+    FlowResultSuccess,
+    GetBlobResult,
+    Message,
+    Method,
+    MethodError,
+    MethodSuccess,
+    PutBlobResult,
+)
+from stepflow_py.message_decoder import MessageDecoder
+
+"""
+Context API for stepflow components to interact with the runtime.
+"""
+
+T = TypeVar("T")
+
+
+class StepflowContext:
+    """Context for stepflow components to make calls back to the runtime.
+
+    This allows components to store/retrieve blobs and perform other
+    runtime operations through bidirectional communication.
+    """
+
+    def __init__(
+        self,
+        outgoing_queue: asyncio.Queue,
+        message_decoder: MessageDecoder[asyncio.Future[Message]],
+        session_id: str | None = None,
+    ):
+        self._outgoing_queue = outgoing_queue
+        self._message_decoder = message_decoder
+        self._session_id = session_id
+
+    async def _send_request(
+        self, method: Method, params: Any, result_type: type[T]
+    ) -> T:
+        """Send a request to the stepflow runtime and wait for response."""
+        request_id = str(uuid4())
+        request = {
+            "jsonrpc": "2.0",
+            "id": request_id,
+            "method": method.value,
+            "params": params,
+        }
+
+        # Create future for response
+        future: asyncio.Future[Message] = asyncio.Future()
+
+        # Register pending request with message decoder using method registration
+        self._message_decoder.register_request_for_method(request_id, method, future)
+
+        # Send request via queue
+        await self._outgoing_queue.put(request)
+
+        # Wait for response - the MessageDecoder will resolve this future
+        # when the response is received
+        response_message = await future
+
+        # Extract the result from the response message
+        if isinstance(response_message, MethodSuccess):
+            result = response_message.result
+            assert isinstance(result, result_type), (
+                f"Expected {result_type}, got {type(result)}"
+            )
+            return result
+        elif isinstance(response_message, MethodError):
+            # Handle error case
+            raise Exception(f"Request failed: {response_message.error}")
+        else:
+            raise Exception(
+                f"Unexpected response type: {type(response_message)} {response_message}"
+            )
+
+    async def put_blob(self, data: Any) -> str:
+        """Store JSON data as a blob and return its content-based ID.
+
+        Args:
+            data: The JSON-serializable data to store
+
+        Returns:
+            The blob ID (SHA-256 hash) for the stored data
+        """
+        params = {"data": data}
+        response = await self._send_request(Method.blobs_put, params, PutBlobResult)
+        return response.blob_id
+
+    async def get_blob(self, blob_id: str) -> Any:
+        """Retrieve JSON data by blob ID.
+
+        Args:
+            blob_id: The blob ID to retrieve
+
+        Returns:
+            The JSON data associated with the blob ID
+        """
+        params = {"blob_id": blob_id}
+        response = await self._send_request(Method.blobs_get, params, GetBlobResult)
+        return response.data
+
+    @property
+    def session_id(self) -> str | None:
+        """Get the session ID for HTTP mode, or None for STDIO mode."""
+        return self._session_id
+
+    async def evaluate_flow(self, flow: Flow | dict, input: Any) -> Any:
+        """Evaluate a flow with the given input.
+
+        Args:
+            flow: The flow definition (as a Flow object or dictionary)
+            input: The input to provide to the flow
+
+        Returns:
+            The result value on success
+
+        Raises:
+            StepflowSkipped: If the flow execution was skipped
+            StepflowFailed: If the flow execution failed with a business logic error
+            Exception: For system/runtime errors
+        """
+        from stepflow_py.exceptions import StepflowFailed, StepflowSkipped
+
+        # Convert Flow object to dict if needed
+        if isinstance(flow, Flow):
+            import msgspec
+
+            flow_dict = msgspec.to_builtins(flow)
+        else:
+            flow_dict = flow
+
+        params = {"flow": flow_dict, "input": input}
+
+        evaluate_result = await self._send_request(
+            Method.flows_evaluate, params, EvaluateFlowResult
+        )
+        flow_result = evaluate_result.result
+
+        # Check the outcome and either return the result or raise appropriate exception
+        if isinstance(flow_result, FlowResultSuccess):
+            return flow_result.result
+        elif isinstance(flow_result, FlowResultSkipped):
+            raise StepflowSkipped("Flow execution was skipped")
+        elif isinstance(flow_result, FlowResultFailed):
+            error = flow_result.error
+            raise StepflowFailed(
+                error_code=error.code,
+                message=error.message,
+                data=error.data,
+            )
+        else:
+            raise Exception(f"Unexpected flow result type: {type(flow_result)}")
+
+    def log(self, message):
+        """Log a message."""
+        print(f"PYTHON: {message}", file=sys.stderr)

stepflow_py/exceptions.py

@@ -0,0 +1,161 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more contributor
+# license agreements.  See the NOTICE file distributed with this work for
+# additional information regarding copyright ownership.  The ASF licenses this
+# file to you under the Apache License, Version 2.0 (the "License"); you may not
+# use this file except in compliance with the License.  You may obtain a copy of
+# the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations under
+# the License.
+
+from enum import IntEnum
+from typing import Any
+
+
+class ErrorCode(IntEnum):
+    GENERIC_ERROR = -32000
+    NOT_INITIALIZED = -32001
+
+    INVALID_REQUEST = -32600
+    COMPONENT_ERROR = -32001
+    VALIDATION_ERROR = -32002
+    EXECUTION_ERROR = -32003
+    RUNTIME_ERROR = -32004
+    VALUE_ERROR = -32005
+
+
+class StepflowError(Exception):
+    """Base exception for all StepFlow SDK errors."""
+
+    def __init__(self, message: str, code: ErrorCode = None, data: dict = None):
+        super().__init__(message)
+        self.message = message
+        self.code = code or self.default_code
+        self.data = data or {}
+
+    @property
+    def default_code(self) -> ErrorCode:
+        """Default error code for this exception type."""
+        return ErrorCode.GENERIC_ERROR
+
+    def to_json_rpc_error(self) -> dict:
+        """Convert to JSON-RPC error format."""
+        return {"code": self.code.value, "message": self.message, "data": self.data}
+
+
+class StepflowProtocolError(StepflowError):
+    """Errors related to JSON-RPC protocol violations."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.INVALID_REQUEST  # Invalid Request
+
+
+class StepflowComponentError(StepflowError):
+    """Errors related to component operations."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.COMPONENT_ERROR
+
+
+class StepflowValidationError(StepflowError):
+    """Errors related to input/output validation."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.VALIDATION_ERROR
+
+
+class StepflowValueError(StepflowError):
+    """Errors related to invalid values."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.VALUE_ERROR
+
+
+class StepflowExecutionError(StepflowError):
+    """Errors during component execution."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.EXECUTION_ERROR
+
+
+class StepflowRuntimeError(StepflowError):
+    """Errors from the StepFlow runtime."""
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.RUNTIME_ERROR
+
+
+class ComponentNotFoundError(StepflowComponentError):
+    """Component was not found."""
+
+    def __init__(self, component_name: str):
+        super().__init__(f"Component '{component_name}' not found")
+        self.component_name = component_name
+        self.data = {"component": component_name}
+
+
+class ServerNotInitializedError(StepflowProtocolError):
+    """Server hasn't been initialized yet."""
+
+    def __init__(self):
+        super().__init__("Server not initialized")
+
+    @property
+    def default_code(self) -> ErrorCode:
+        return ErrorCode.NOT_INITIALIZED
+
+
+class InputValidationError(StepflowValidationError):
+    """Input validation failed."""
+
+    def __init__(self, validation_error: str, input_data: dict | None = None):
+        super().__init__(f"Input validation failed: {validation_error}")
+        if input_data:
+            self.data = {"input": input_data}
+
+
+class BlobNotFoundError(StepflowRuntimeError):
+    """Blob was not found in storage."""
+
+    def __init__(self, blob_id: str):
+        super().__init__(f"Blob '{blob_id}' not found")
+        self.blob_id = blob_id
+        self.data = {"blob_id": blob_id}
+
+
+class CodeCompilationError(StepflowExecutionError):
+    """User code compilation failed."""
+
+    def __init__(self, compilation_error: str, code: str | None = None):
+        super().__init__(f"Code compilation failed: {compilation_error}")
+        if code:
+            self.data = {"code": code}
+
+
+class StepflowSkipped(Exception):
+    """Exception raised when a step or flow is skipped."""
+
+    def __init__(self, message: str = "Flow execution was skipped"):
+        super().__init__(message)
+        self.message = message
+
+
+class StepflowFailed(Exception):
+    """Exception raised when a step or flow fails with a business logic error."""
+
+    def __init__(self, error_code: int, message: str, data: Any = None):
+        super().__init__(message)
+        self.error_code = error_code
+        self.message = message
+        self.data = data