dex-python-sdk 0.0.2__cp311-abi3-win_amd64.whl

dex/persistence.py

@@ -0,0 +1,89 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from typing import Any, Tuple, Union
+
+from dex.data_attributes import DataAttributes
+from dex.search_attributes import SearchAttributes
+from dex.state_execution_locals import StateExecutionLocals
+
+class Persistence:
+    _data_attributes: DataAttributes
+    _search_attributes: SearchAttributes
+    _state_execution_locals: StateExecutionLocals
+
+    def __init__(
+        self,
+        data_attributes: DataAttributes,
+        search_attributes: SearchAttributes,
+        state_execution_locals: StateExecutionLocals,
+    ):
+        self._data_attributes = data_attributes
+        self._search_attributes = search_attributes
+        self._state_execution_locals = state_execution_locals
+
+    def get_data_attribute(self, key: str) -> Any:
+        return self._data_attributes.get_data_attribute(key)
+
+    def set_data_attribute(self, key: str, value: Any):
+        self._data_attributes.set_data_attribute(key, value)
+
+    def get_search_attribute_int64(self, key: str) -> Union[None, int]:
+        return self._search_attributes.get_search_attribute_int64(key)
+
+    def set_search_attribute_int64(self, key: str, value: Union[None, int]):
+        self._search_attributes.set_search_attribute_int64(key, value)
+
+    def get_search_attribute_double(self, key: str) -> Union[None, float]:
+        return self._search_attributes.get_search_attribute_double(key)
+
+    def set_search_attribute_double(self, key: str, value: Union[None, float]):
+        self._search_attributes.set_search_attribute_double(key, value)
+
+    def get_search_attribute_boolean(self, key: str) -> Union[None, bool]:
+        return self._search_attributes.get_search_attribute_boolean(key)
+
+    def set_search_attribute_boolean(self, key: str, value: Union[None, bool]):
+        self._search_attributes.set_search_attribute_boolean(key, value)
+
+    def get_search_attribute_keyword(self, key: str) -> Union[None, str]:
+        return self._search_attributes.get_search_attribute_keyword(key)
+
+    def set_search_attribute_keyword(self, key: str, value: Union[None, str]):
+        self._search_attributes.set_search_attribute_keyword(key, value)
+
+    def get_search_attribute_text(self, key: str) -> Union[None, str]:
+        return self._search_attributes.get_search_attribute_text(key)
+
+    def set_search_attribute_text(self, key: str, value: Union[None, str]):
+        self._search_attributes.set_search_attribute_text(key, value)
+
+    def get_search_attribute_datetime(self, key: str) -> Union[None, str]:
+        return self._search_attributes.get_search_attribute_datetime(key)
+
+    def set_search_attribute_datetime(self, key: str, value: Union[None, str]):
+        self._search_attributes.set_search_attribute_datetime(key, value)
+
+    def get_search_attribute_keyword_array(self, key: str) -> Union[None, list[str]]:
+        return self._search_attributes.get_search_attribute_keyword_array(key)
+
+    def set_search_attribute_keyword_array(
+        self, key: str, value: Union[None, list[str]]
+    ):
+        self._search_attributes.set_search_attribute_keyword_array(key, value)
+
+    def get_state_execution_local(self, key: str) -> Any:
+        return self._state_execution_locals.get_state_execution_local(key)
+
+    def set_state_execution_local(self, key: str, value: Any):
+        self._state_execution_locals.set_state_execution_local(key, value)
+
+    def record_event(self, key: str, *event_data: Tuple[Any, ...]):
+        self._state_execution_locals.record_event(key, *event_data)

dex/persistence_options.py

@@ -0,0 +1,12 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+
+@dataclass
+class PersistenceOptions:
+    enable_caching: bool
+
+    @classmethod
+    def get_default(cls):
+        return PersistenceOptions(False)

dex/persistence_schema.py

@@ -0,0 +1,51 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+from dex.dex_api.models import SearchAttributeValueType
+
+class PersistenceFieldType(Enum):
+    DataAttribute = 1
+    SearchAttribute = 2
+    DataAttributePrefix = 3
+
+@dataclass
+class PersistenceField:
+    key: str
+    field_type: PersistenceFieldType
+    value_type: Optional[type]
+    search_attribute_type: Optional[SearchAttributeValueType] = None
+
+    @classmethod
+    def data_attribute_def(cls, key: str, value_type: Optional[type]):
+        return PersistenceField(key, PersistenceFieldType.DataAttribute, value_type)
+
+    @classmethod
+    def search_attribute_def(cls, key: str, sa_type: SearchAttributeValueType):
+        return PersistenceField(
+            key, PersistenceFieldType.SearchAttribute, None, sa_type
+        )
+
+    @classmethod
+    def data_attribute_prefix_def(cls, key: str, value_type: Optional[type]):
+        return PersistenceField(
+            key, PersistenceFieldType.DataAttributePrefix, value_type
+        )
+
+@dataclass
+class PersistenceSchema:
+    persistence_fields: List[PersistenceField] = field(default_factory=list)
+
+    @classmethod
+    def create(cls, *args: PersistenceField):
+        return PersistenceSchema(list(args))

dex/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

dex/registry.py

@@ -0,0 +1,204 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from typing import Callable, Optional
+
+from dex.communication_schema import CommunicationMethodType
+from dex.errors import InvalidArgumentError, WorkflowDefinitionError
+from dex.dex_api.models import SearchAttributeValueType
+from dex.persistence_options import PersistenceOptions
+from dex.persistence_schema import PersistenceFieldType
+from dex.rpc import RPCInfo
+from dex.type_store import TypeStore, Type
+from dex.workflow import ObjectWorkflow, get_workflow_type
+from dex.workflow_state import WorkflowState, get_state_id
+
+class Registry:
+    _workflow_store: dict[str, ObjectWorkflow]
+    _starting_state_store: dict[str, WorkflowState]
+    _state_store: dict[str, dict[str, WorkflowState]]
+    _internal_channel_type_store: dict[str, TypeStore]
+    _signal_channel_type_store: dict[str, dict[str, Optional[type]]]
+    _data_attribute_types: dict[str, TypeStore]
+    _search_attribute_types: dict[str, dict[str, SearchAttributeValueType]]
+    _persistence_options: dict[str, PersistenceOptions]
+    _rpc_infos: dict[str, dict[str, RPCInfo]]
+
+    def __init__(self):
+        self._workflow_store = dict()
+        self._starting_state_store = dict()
+        self._state_store = dict()
+        self._internal_channel_type_store = dict()
+        self._signal_channel_type_store = dict()
+        self._data_attribute_types = dict()
+        self._search_attribute_types = {}
+        self._persistence_options = {}
+        self._rpc_infos = dict()
+
+    def add_workflow(self, wf: ObjectWorkflow):
+        self._register_workflow_type(wf)
+        self._register_workflow_state(wf)
+        self._register_internal_channels(wf)
+        self._register_signal_channels(wf)
+        self._register_data_attributes(wf)
+        self._register_search_attributes(wf)
+        self._register_persistence_options(wf)
+        self._register_workflow_rpcs(wf)
+
+    def add_workflows(self, *wfs: ObjectWorkflow):
+        for wf in wfs:
+            self.add_workflow(wf)
+
+    def get_workflow_with_check(self, wf_type: str) -> ObjectWorkflow:
+        wf = self._workflow_store.get(wf_type)
+        if wf is None:
+            raise InvalidArgumentError(f"workflow {wf_type} is not registered")
+        return wf
+
+    def get_workflow_starting_state(self, wf_type: str) -> Optional[WorkflowState]:
+        return self._starting_state_store.get(wf_type)
+
+    def get_workflow_state_with_check(
+        self, wf_type: str, state_id: str
+    ) -> WorkflowState:
+        states = self._state_store.get(wf_type)
+        if states is None:
+            raise InvalidArgumentError(f"workflow {wf_type} is not registered")
+        state = states.get(state_id)
+        if state is None:
+            raise InvalidArgumentError(
+                f"workflow {wf_type} state {state_id} is not registered"
+            )
+        return state
+
+    def get_state_store(self, wf_type: str) -> dict[str, WorkflowState]:
+        return self._state_store[wf_type]
+
+    def get_internal_channel_type_store(self, wf_type: str) -> TypeStore:
+        return self._internal_channel_type_store[wf_type]
+
+    def get_signal_channel_types(self, wf_type: str) -> dict[str, Optional[type]]:
+        return self._signal_channel_type_store[wf_type]
+
+    def get_data_attribute_types(self, wf_type: str) -> TypeStore:
+        return self._data_attribute_types[wf_type]
+
+    def get_search_attribute_types(
+        self, wf_type: str
+    ) -> dict[str, SearchAttributeValueType]:
+        return self._search_attribute_types[wf_type]
+
+    def get_persistence_options(self, wf_type: str) -> PersistenceOptions:
+        return self._persistence_options[wf_type]
+
+    def get_rpc_infos(self, wf_type: str) -> dict[str, RPCInfo]:
+        return self._rpc_infos[wf_type]
+
+    def _register_workflow_type(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+        if wf_type in self._workflow_store:
+            raise WorkflowDefinitionError("workflow type conflict: ", wf_type)
+        self._workflow_store[wf_type] = wf
+
+    def _register_internal_channels(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+
+        if wf_type not in self._internal_channel_type_store:
+            self._internal_channel_type_store[wf_type] = TypeStore(
+                Type.INTERNAL_CHANNEL
+            )
+
+        for method in wf.get_communication_schema().communication_methods:
+            if method.method_type == CommunicationMethodType.InternalChannel:
+                self._internal_channel_type_store[wf_type].add_internal_channel_def(
+                    method
+                )
+
+    def _register_signal_channels(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+        types: dict[str, Optional[type]] = {}
+        for method in wf.get_communication_schema().communication_methods:
+            if method.method_type == CommunicationMethodType.SignalChannel:
+                types[method.name] = method.value_type
+        self._signal_channel_type_store[wf_type] = types
+
+    def _register_data_attributes(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+        data_attribute_types: TypeStore = TypeStore(Type.DATA_ATTRIBUTE)
+        for field in wf.get_persistence_schema().persistence_fields:
+            if (
+                field.field_type == PersistenceFieldType.DataAttribute
+                or field.field_type == PersistenceFieldType.DataAttributePrefix
+            ):
+                data_attribute_types.add_data_attribute_def(field)
+        self._data_attribute_types[wf_type] = data_attribute_types
+
+    def _register_search_attributes(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+        types: dict[str, SearchAttributeValueType] = {}
+        for field in wf.get_persistence_schema().persistence_fields:
+            if field.field_type == PersistenceFieldType.SearchAttribute:
+                sa_type = field.search_attribute_type
+                if sa_type is None:
+                    raise WorkflowDefinitionError(
+                        f"Found search attribute {field.key} with no type set"
+                    )
+                if field.key in types:
+                    raise WorkflowDefinitionError(
+                        f"Search attribute {field.key} already exists"
+                    )
+                types[field.key] = sa_type
+        self._search_attribute_types[wf_type] = types
+
+    def _register_persistence_options(self, wf: ObjectWorkflow):
+        wf_type = get_workflow_type(wf)
+        self._persistence_options[wf_type] = wf.get_persistence_options()
+
+    def _register_workflow_state(self, wf):
+        wf_type = get_workflow_type(wf)
+        state_map = {}
+        starting_state = None
+        for state_def in wf.get_workflow_states().states:
+            state_id = get_state_id(state_def.state)
+            if state_id in state_map:
+                raise WorkflowDefinitionError(
+                    f"Workflow {wf_type} cannot have duplicate stateId {state_id}"
+                )
+            state_map[state_id] = state_def.state
+            if state_def.can_start_workflow:
+                if starting_state is not None:
+                    raise WorkflowDefinitionError(
+                        f"Workflow {wf_type} cannot contain more than one starting "
+                        f"state"
+                    )
+                starting_state = state_def.state
+            self._state_store[wf_type] = state_map
+            self._starting_state_store[wf_type] = starting_state
+
+    @staticmethod
+    def _is_decorated_by_rpc(func: Callable):
+        return getattr(func, "_is_dex_rpc", False)
+
+    @staticmethod
+    def _get_rpc_info(func: Callable):
+        info = getattr(func, "_rpc_info")
+        assert isinstance(info, RPCInfo)
+        # NOTE: we have to override the method here so that it's associated the object
+        info.method_func = func
+        return info
+
+    def _register_workflow_rpcs(self, wf):
+        wf_type = get_workflow_type(wf)
+        rpc_infos = {}
+        for method_name in dir(wf):
+            method = getattr(wf, method_name)
+            if callable(method) and self._is_decorated_by_rpc(method):
+                rpc_infos[method_name] = self._get_rpc_info(method)
+        self._rpc_infos[wf_type] = rpc_infos

dex/reset_workflow_type_and_options.py

@@ -0,0 +1,67 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+from typing import Optional
+
+from dex.dex_api.models import WorkflowResetType
+
+@dataclass
+class ResetWorkflowTypeAndOptions:
+    reset_type: WorkflowResetType
+    reason: str
+    history_event_id: Optional[int] = None
+    history_event_time: Optional[str] = None
+    state_id: Optional[str] = None
+    state_execution_id: Optional[str] = None
+    skip_signal_reapply: Optional[bool] = None
+
+def reset_to_beginning(reason: str) -> ResetWorkflowTypeAndOptions:
+    return ResetWorkflowTypeAndOptions(
+        reset_type=WorkflowResetType.BEGINNING,
+        reason=reason,
+    )
+
+def reset_to_history_event_id(
+    history_event_id: int,
+    reason: str,
+) -> ResetWorkflowTypeAndOptions:
+    return ResetWorkflowTypeAndOptions(
+        reset_type=WorkflowResetType.HISTORY_EVENT_ID,
+        history_event_id=history_event_id,
+        reason=reason,
+    )
+
+def reset_to_history_event_time(
+    history_event_time: str,
+    reason: str,
+) -> ResetWorkflowTypeAndOptions:
+    return ResetWorkflowTypeAndOptions(
+        reset_type=WorkflowResetType.HISTORY_EVENT_TIME,
+        history_event_time=history_event_time,
+        reason=reason,
+    )
+
+def reset_to_state_id(state_id: str, reason: str) -> ResetWorkflowTypeAndOptions:
+    return ResetWorkflowTypeAndOptions(
+        reset_type=WorkflowResetType.STATE_ID,
+        state_id=state_id,
+        reason=reason,
+    )
+
+def reset_to_state_execution_id(
+    state_execution: str,
+    reason: str,
+) -> ResetWorkflowTypeAndOptions:
+    return ResetWorkflowTypeAndOptions(
+        reset_type=WorkflowResetType.STATE_EXECUTION_ID,
+        state_execution_id=state_execution,
+        reason=reason,
+    )

dex/rpc.py

@@ -0,0 +1,93 @@
+# Legacy Materials in this file remain under their original licenses.
+# See LEGACY_NOTICES.md.
+
+# Modifications Copyright (c) 2026 Super Durable, Inc.
+#
+# Modifications after the Legacy Cutoff are licensed under the
+# Super Durable Source License 1.0.
+# Legacy Materials remain under their original licenses.
+# See LICENSE and LEGACY_NOTICES.md.
+
+from dataclasses import dataclass
+from functools import wraps
+from inspect import signature
+from typing import Callable, Optional
+
+from dex.errors import WorkflowDefinitionError
+from dex.dex_api.models import PersistenceLoadingPolicy, PersistenceLoadingType
+
+@dataclass
+class RPCInfo:
+    method_func: Callable
+    timeout_seconds: int
+    input_type: Optional[type] = None
+    data_attribute_loading_policy: Optional[PersistenceLoadingPolicy] = None
+    params_order: Optional[list] = (
+        None  # store this so that the rpc can be invoked with correct parameters
+    )
+    bypass_caching_for_strong_consistency: bool = False
+
+rpc_definition_err = WorkflowDefinitionError(
+    "an RPC must have at most 5 params: self, context:WorkflowContext, input:Any, persistence:Persistence, "
+    "communication:Communication, where input can be any type"
+)
+
+def rpc(
+    timeout_seconds: int = 10,
+    data_attribute_loading_policy: Optional[PersistenceLoadingPolicy] = None,
+    bypass_caching_for_strong_consistency: bool = False,
+):
+    def decorator(func):
+        # preserve the properties of the original function.
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # TODO need to add type hint for decorated method
+            return func(*args, **kwargs)
+
+        wrapper._is_dex_rpc = True
+        rpc_info = RPCInfo(
+            method_func=func,
+            timeout_seconds=timeout_seconds,
+            data_attribute_loading_policy=data_attribute_loading_policy,
+            bypass_caching_for_strong_consistency=bypass_caching_for_strong_consistency,
+        )
+        params = signature(func).parameters
+
+        from inspect import _empty  # ignored.
+        from dex.persistence import Persistence
+        from dex.workflow_context import WorkflowContext
+        from dex.communication import Communication
+
+        valid_param_types_exclude_input = {
+            _empty: True,
+            Persistence: True,
+            WorkflowContext: True,
+            Communication: True,
+        }
+        need_persistence = False
+        params_order = []
+        if len(params) > 5:
+            raise rpc_definition_err
+
+        has_input = False
+        for k, v in params.items():
+            if k != "self":
+                params_order.append(v.annotation)
+
+            if v.annotation == Persistence:
+                need_persistence = True
+            if v.annotation not in valid_param_types_exclude_input:
+                if not has_input:
+                    has_input = True
+                    rpc_info.input_type = v.annotation
+                else:
+                    raise rpc_definition_err
+        if not need_persistence:
+            rpc_info.data_attribute_loading_policy = PersistenceLoadingPolicy(
+                persistence_loading_type=PersistenceLoadingType.LOAD_NONE
+            )
+        rpc_info.params_order = params_order
+        wrapper._rpc_info = rpc_info
+        return wrapper
+
+    return decorator

dex/runtime_errors.py

@@ -0,0 +1,81 @@
+# Copyright (c) 2026 Super Durable, Inc.
+#
+# Licensed under the Super Durable Source License 1.0.
+# You may not use this file except in compliance with the License.
+# See the LICENSE file in the repository root.
+#
+# SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+import grpc
+
+from dex.flow_info import FlowStatus
+
+if TYPE_CHECKING:
+    from dex._value_mapper import ValueMapper
+    from dex.dexpb import dex_pb2 as pb
+
+
+class ErrorSubStatus(Enum):
+    UNCATEGORIZED = "uncategorized"
+    FLOW_ALREADY_STARTED = "flow_already_started"
+    FLOW_NOT_EXISTS = "flow_not_exists"
+    WORKER_API_ERROR = "worker_api_error"
+    LONG_POLL_TIMEOUT = "long_poll_timeout"
+
+
+class FlowErrorType(Enum):
+    STEP_DECISION_FAILED = "step_decision_failed"
+    CLIENT_API_FAILED = "client_api_failed"
+    WORKER_API_FAILED = "worker_api_failed"
+    INVALID_USER_FLOW_CODE = "invalid_user_flow_code"
+    INTERNAL = "internal"
+
+
+class DexException(RuntimeError):
+    def __init__(
+        self,
+        code: grpc.StatusCode,
+        sub_status: ErrorSubStatus | None,
+        detail: str | None,
+        worker_error_type: str = "",
+        worker_error_detail: str = "",
+    ) -> None:
+        super().__init__(detail)
+        self.code = code
+        self.sub_status = sub_status
+        self.detail = detail
+        self.worker_error_type = worker_error_type
+        self.worker_error_detail = worker_error_detail
+
+
+class LongPollTimeoutError(RuntimeError):
+    def __init__(self, flow_id: str) -> None:
+        super().__init__(f"Flow is still running: {flow_id}")
+        self.flow_id = flow_id
+
+
+class FlowUncompletedError(RuntimeError):
+    def __init__(
+        self,
+        run_id: str,
+        status: FlowStatus,
+        error_type: FlowErrorType | None,
+        message: str | None,
+        results: list[pb.StepCompletionOutput],
+        values: ValueMapper,
+    ) -> None:
+        super().__init__(message)
+        self.run_id = run_id
+        self.status = status
+        self.error_type = error_type
+        self.results = tuple(results)
+        self._values = values
+
+    def result(self, index: int, result_type: type[Any]) -> Any:
+        value = self.results[index].completed_step_output
+        return self._values.decode(value, self._values.codec(result_type))