plexspaces 0.1.1__py3-none-any.whl

plexspaces/runtime.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2025 PlexSpaces Contributors
+#
+# PlexSpaces Runtime
+#
+# Generates the WIT interface wrapper for actor classes decorated with @actor.
+# This bridges the gap between the Pythonic SDK API and the componentize-py
+# WIT bindings.
+
+"""
+Runtime support for PlexSpaces actors.
+
+## Multi-Actor Dispatch
+
+The framework always sets ``actor_type`` to the exact class name in the init
+config (e.g. ``"SessionActor"``).  The dispatch rule is therefore simple:
+
+1. ``config["actor_type"]`` — exact lookup in the class map.  This is the
+   normal case and covers every virtual-actor activation.
+2. ``config["role"]`` — exact lookup, used only when multiple children in
+   ``app-config.toml`` share the same ``actor_type`` but need different
+   behaviour (e.g. ``ephemeral`` / ``channel`` / ``controller`` all map to
+   ``AbstractionsActor``).
+3. ``default_class`` — first class in ``__all__`` / registration order.
+
+No aliases, no prefix matching, no normalization.  The framework is the
+source of truth; the SDK trusts what it receives.
+"""
+
+import json
+from typing import Type, List, Dict, Optional
+
+from .decorators import (
+    get_state_dict,
+    set_state_dict,
+    dispatch_message,
+    init_actor,
+    _sanitize_payload_for_wasm,
+    _desanitize_from_wasm,
+    _has_float,
+)
+
+
+def build_class_map(
+    actor_classes: List[Type],
+    actor_roles: Optional[Dict[str, Type]] = None,
+) -> Dict[str, Type]:
+    """Build the dispatch map used by ``select_actor_class``.
+
+    Keys are exact strings the framework places in ``actor_type`` or ``role``:
+    - Each class is registered under its exact ``__name__``.
+    - Explicit ``actor_roles`` entries are registered under their exact key
+      (for same-class multi-instance cases like ``ephemeral``/``channel``).
+    """
+    class_map: Dict[str, Type] = {}
+
+    # Class names first (lower priority — roles may override for same-class dispatch)
+    for cls in actor_classes:
+        class_map[cls.__name__] = cls
+
+    # Explicit role overrides (only valid when multiple children share actor_type)
+    if actor_roles:
+        for role, cls in actor_roles.items():
+            if cls in actor_classes:
+                class_map[role] = cls
+
+    return class_map
+
+
+def select_actor_class(
+    config: dict,
+    class_map: Dict[str, Type],
+    default_class: Type,
+) -> Type:
+    """Select the actor class from the framework-supplied init config.
+
+    Priority:
+    1. ``config["actor_type"]`` — exact match (the normal case).
+    2. ``config["role"]`` — exact match (same-class multi-instance only).
+    3. ``default_class`` — first registered class.
+    """
+    if not isinstance(config, dict) or not class_map:
+        return default_class
+
+    actor_type = config.get("actor_type", "")
+    if actor_type and actor_type in class_map:
+        return class_map[actor_type]
+
+    role = config.get("role", "")
+    if role and role in class_map:
+        return class_map[role]
+
+    return default_class
+
+
+def generate_wrapper(
+    actor_classes: List[Type],
+    module_name: str,
+    actor_roles: Optional[Dict[str, Type]] = None,
+) -> str:
+    """Generate the WIT interface wrapper for one or more actor classes.
+
+    Args:
+        actor_classes: List of @actor decorated classes (at least one).
+        module_name: Name of the module containing the actor classes.
+        actor_roles: Optional role→class map for same-class multi-instance dispatch.
+
+    Returns:
+        Python source code for the generated wrapper.
+    """
+    if not actor_classes:
+        raise ValueError("No @actor classes provided")
+
+    class_names = [cls.__name__ for cls in actor_classes]
+    imports = ", ".join(class_names)
+    default_class = class_names[0]
+    class_map = build_class_map(actor_classes, actor_roles)
+
+    lines = [
+        "# AUTO-GENERATED by PlexSpaces SDK",
+        "# DO NOT EDIT - regenerate with: plexspaces-py build",
+        "",
+        "import json",
+        "from wit_world import exports",
+        f"from {module_name} import {imports}",
+        "from plexspaces.decorators import (",
+        "    get_state_dict, set_state_dict, dispatch_message, init_actor,",
+        "    _sanitize_payload_for_wasm, _desanitize_from_wasm, _has_float,",
+        "    payload_from_request_json,",
+        ")",
+        "from plexspaces.runtime import select_actor_class as _select_actor_class",
+        "",
+    ]
+
+    if len(actor_classes) == 1:
+        lines.append(f"_actor_class = {default_class}")
+        lines.append("_CLASS_MAP = {}")
+    else:
+        lines.append(f"_actor_class = {default_class}  # default")
+        lines.append("")
+        lines.append("# Dispatch map: actor_type / role -> class (exact match only)")
+        lines.append("_CLASS_MAP = {")
+        for key, cls in class_map.items():
+            lines.append(f'    "{key}": {cls.__name__},')
+        lines.append("}")
+
+    lines.extend([
+        "",
+        "# Actor instance (created on first init)",
+        "_instance = None",
+        "",
+        "",
+        "def _select_class(config):",
+        '    """Delegate to plexspaces.runtime.select_actor_class (single source of truth)."""',
+        f"    return _select_actor_class(config, _CLASS_MAP, {default_class})",
+        "",
+        "",
+        f'class Actor(exports.Actor):',
+        f'    """WIT interface wrapper (supports {", ".join(class_names)})."""',
+        "",
+        "    def _decode(self, data):",
+        '        """Decode WIT payload (list<u8>) to str. Accepts bytes or str."""',
+        "        if isinstance(data, (bytes, bytearray)):",
+        "            return data.decode('utf-8')",
+        "        return str(data) if data else ''",
+        "",
+        "    def init(self, config):",
+        '        """Initialize the actor with optional config."""',
+        "        global _instance, _actor_class",
+        "        try:",
+        "            config_json = self._decode(config)",
+        "            config = json.loads(config_json) if config_json else {}",
+        "            _actor_class = _select_class(config)",
+        "            _instance = _actor_class()",
+        "            if config:",
+        "                init_actor(_instance, config)",
+        "        except Exception as e:",
+        '            return f"ERROR: {e}"',
+        "",
+        "    def handle(self, from_actor: str, msg_type: str, payload):",
+        '        """Handle incoming message."""',
+        "        global _instance",
+        "        if _instance is None:",
+        '            return json.dumps({"error": "Actor not initialized"}).encode("utf-8")',
+        "",
+        "        try:",
+        "            payload_json = self._decode(payload)",
+        '            payload = payload_from_request_json(payload_json or "")',
+        "            result = dispatch_message(_instance, from_actor, msg_type, payload)",
+        "",
+        "            if isinstance(result, str):",
+        '                return result.encode("utf-8")',
+        "            # json.dumps handles floats natively as JSON numbers.",
+        "            # Do NOT sanitize floats to strings here -- that corrupts",
+        "            # inter-actor ask() responses (receivers get strings where",
+        "            # they expect numbers, causing 'float + str' TypeError).",
+        "            # Float sanitization is only needed in get_state() for",
+        "            # checkpoint persistence (reversed by _desanitize_from_wasm",
+        "            # in set_state).",
+        '            return json.dumps(result).encode("utf-8")',
+        "        except Exception as e:",
+        '            return json.dumps({"error": str(e)}).encode("utf-8")',
+        "",
+        "    def get_state(self):",
+        '        """Get actor state as JSON bytes."""',
+        "        global _instance",
+        "        if _instance is None:",
+        '            return b"{}"',
+        "",
+        "        try:",
+        "            state = get_state_dict(_instance)",
+        "            state_safe = _sanitize_payload_for_wasm(state)",
+        '            return json.dumps(state_safe).encode("utf-8")',
+        "        except Exception as e:",
+        '            return json.dumps({"error": str(e)}).encode("utf-8")',
+        "",
+        "    def set_state(self, state_data):",
+        '        """Restore actor state from JSON bytes."""',
+        "        global _instance",
+        "        if _instance is None:",
+        "            _instance = _actor_class()",
+        "",
+        "        try:",
+        "            state_json = self._decode(state_data)",
+        "            state = json.loads(state_json)",
+        "            # Recursively restore stringified numbers back to numeric types.",
+        "            # get_state sanitizes floats to strings for WASM JSON safety;",
+        "            # _desanitize_from_wasm reverses this for lists, dicts, and scalars.",
+        "            state = _desanitize_from_wasm(state)",
+        "            set_state_dict(_instance, state)",
+        '            return ""',
+        "        except Exception as e:",
+        '            return f"ERROR: {e}"',
+    ])
+
+    return "\n".join(lines)
+
+
+def create_actor_module(user_module_path: str, output_path: str = None) -> str:
+    """
+    Create a wrapped actor module from a user's actor file.
+
+    Args:
+        user_module_path: Path to the user's Python file with @actor class(es)
+        output_path: Optional output path (defaults to {name}_wrapper.py)
+
+    Returns:
+        Path to the generated wrapper file
+    """
+    import importlib.util
+    import os
+
+    # Load the user's module
+    module_name = os.path.splitext(os.path.basename(user_module_path))[0]
+    spec = importlib.util.spec_from_file_location(module_name, user_module_path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # Find ALL @actor decorated classes (preserving definition order)
+    actor_classes = []
+    for name in dir(module):
+        obj = getattr(module, name)
+        if isinstance(obj, type) and hasattr(obj, '_plexspaces_is_actor'):
+            actor_classes.append(obj)
+
+    if not actor_classes:
+        raise ValueError(f"No @actor decorated class found in {user_module_path}")
+
+    actor_roles = getattr(module, "ACTOR_ROLES", None)
+
+    # Generate wrapper
+    wrapper_code = generate_wrapper(actor_classes, module_name, actor_roles=actor_roles)
+
+    # Write to output file
+    if output_path is None:
+        output_path = os.path.join(
+            os.path.dirname(user_module_path),
+            f"{module_name}_actor.py"
+        )
+
+    with open(output_path, 'w') as f:
+        f.write(wrapper_code)
+
+    return output_path

plexspaces/workflow.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2025 PlexSpaces Contributors
+#
+# Workflow retry helpers aligned with proto RetryConfig (plexspaces.workflow.v1.RetryConfig).
+# Single run-with-config semantics: use default_retry_config() for one attempt;
+# pass config with max_attempts > 1 for retries.
+
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union
+
+T = TypeVar("T")
+
+# Use the proto-generated RetryConfig when available (native/server-side with betterproto).
+# Falls back to a plain dataclass for WASM guest environments where generated/ is not bundled.
+# The interface is identical in both cases: attribute access (cfg.max_attempts) works for
+# both the betterproto dataclass and the fallback dataclass.
+try:
+    # betterproto generates plexspaces/workflow/v1/__init__.py with RetryConfig as a dataclass
+    from plexspaces.generated.plexspaces.workflow.v1 import RetryConfig  # type: ignore[import]
+except ImportError:
+    from dataclasses import dataclass, field as _field
+
+    @dataclass
+    class RetryConfig:  # type: ignore[no-redef]
+        """Fallback RetryConfig matching proto plexspaces.workflow.v1.RetryConfig fields."""
+        max_attempts: int = 1
+        initial_interval_ms: int = 100
+        backoff_rate: float = 2.0
+        max_interval_ms: int = 30000
+        retryable_errors: List[str] = _field(default_factory=list)
+
+# RetryConfigDict is a type alias kept for backward compatibility with callers that pass dicts.
+# New code should use RetryConfig directly (attribute access instead of dict key access).
+RetryConfigDict = Dict[str, Any]
+RetryConfigInput = Union[RetryConfig, RetryConfigDict]
+
+
+def _to_retry_config(config: Optional[RetryConfigInput]) -> Optional[RetryConfig]:
+    """Normalize dict-or-proto input into the proto-shaped RetryConfig object."""
+    if config is None:
+        return None
+    if isinstance(config, dict):
+        return RetryConfig(
+            max_attempts=config.get("max_attempts", 0),
+            initial_interval_ms=config.get("initial_interval_ms", 0),
+            backoff_rate=config.get("backoff_rate", 0.0),
+            max_interval_ms=config.get("max_interval_ms", 0),
+            retryable_errors=list(config.get("retryable_errors", [])),
+        )
+    return config
+
+
+def default_retry_config() -> RetryConfig:
+    """Default retry config as the canonical proto-shaped model."""
+    return RetryConfig(
+        max_attempts=1,
+        initial_interval_ms=100,
+        backoff_rate=2.0,
+        max_interval_ms=30000,
+        retryable_errors=[],
+    )
+
+
+def _effective_max_attempts(config: Optional[RetryConfig]) -> int:
+    """Effective max attempts: 0 or unset means 1."""
+    if not config:
+        return 1
+    n = getattr(config, "max_attempts", 0)
+    return 1 if n == 0 else max(1, n)
+
+
+def with_retry(
+    fn: Callable[[], T],
+    retry_config: Optional[RetryConfigInput] = None,
+) -> T:
+    """
+    Execute a step with retries. Uses RetryConfig. When retry_config is omitted or
+    max_attempts unset, 3 attempts. When max_attempts is 0 or 1, single attempt.
+    Aligns with Rust run(name, retry, op) and proto RetryConfig.
+
+    Args:
+        fn: Callable with no args that returns a value or raises.
+        retry_config: Optional dict with max_attempts, initial_interval_ms, etc.
+            Omitted => 3 attempts; max_attempts: 1 => one attempt.
+
+    Returns:
+        The result of fn() after a successful attempt.
+
+    Raises:
+        The last exception if all attempts fail.
+    """
+    normalized = _to_retry_config(retry_config)
+    has_max = normalized is not None and getattr(normalized, "max_attempts", 0) != 0
+    from_config = _effective_max_attempts(normalized) if has_max else 0
+    max_attempts = from_config if from_config > 0 else 3
+    last_error: Optional[Exception] = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            return fn()
+        except Exception as e:
+            last_error = e
+            if attempt == max_attempts:
+                raise
+    if last_error is not None:
+        raise last_error
+    raise RuntimeError("with_retry: no result and no error")