rune-framework 1.1.1__py3-none-any.whl

rune/__init__.py

@@ -0,0 +1,7 @@
+"""Rune SDK -- Official Python Caster SDK for the Rune framework."""
+
+__version__ = "1.1.1"
+
+from .caster import Caster
+from .types import RuneConfig, RuneContext, FileAttachment
+from .stream import StreamSender

rune/_proto/__init__.py

@@ -0,0 +1 @@
+"""Generated protobuf/gRPC code. Do not edit manually."""

rune/_proto/rune/wire/v1/rune_pb2.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: rune/wire/v1/rune.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'rune/wire/v1/rune.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x17rune/wire/v1/rune.proto\x12\x0crune.wire.v1\"\xc5\x03\n\x0eSessionMessage\x12,\n\x06\x61ttach\x18\n \x01(\x0b\x32\x1a.rune.wire.v1.CasterAttachH\x00\x12,\n\x06\x64\x65tach\x18\x0b \x01(\x0b\x32\x1a.rune.wire.v1.CasterDetachH\x00\x12-\n\x06result\x18\x0c \x01(\x0b\x32\x1b.rune.wire.v1.ExecuteResultH\x00\x12\x31\n\x0cstream_event\x18\r \x01(\x0b\x32\x19.rune.wire.v1.StreamEventH\x00\x12-\n\nstream_end\x18\x0e \x01(\x0b\x32\x17.rune.wire.v1.StreamEndH\x00\x12-\n\nattach_ack\x18\x14 \x01(\x0b\x32\x17.rune.wire.v1.AttachAckH\x00\x12/\n\x07\x65xecute\x18\x15 \x01(\x0b\x32\x1c.rune.wire.v1.ExecuteRequestH\x00\x12-\n\x06\x63\x61ncel\x18\x16 \x01(\x0b\x32\x1b.rune.wire.v1.CancelRequestH\x00\x12,\n\theartbeat\x18\x1e \x01(\x0b\x32\x17.rune.wire.v1.HeartbeatH\x00\x42\t\n\x07payload\"\xdb\x01\n\x0c\x43\x61sterAttach\x12\x11\n\tcaster_id\x18\x01 \x01(\t\x12,\n\x05runes\x18\x02 \x03(\x0b\x32\x1d.rune.wire.v1.RuneDeclaration\x12\x36\n\x06labels\x18\x03 \x03(\x0b\x32&.rune.wire.v1.CasterAttach.LabelsEntry\x12\x16\n\x0emax_concurrent\x18\x04 \x01(\r\x12\x0b\n\x03key\x18\x05 \x01(\t\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"I\n\tAttachAck\x12\x10\n\x08\x61\x63\x63\x65pted\x18\x01 \x01(\x08\x12\x0e\n\x06reason\x18\x02 \x01(\t\x12\x1a\n\x12supported_features\x18\x03 \x03(\t\"\x1e\n\x0c\x43\x61sterDetach\x12\x0e\n\x06reason\x18\x01 \x01(\t\"\xc5\x01\n\x0fRuneDeclaration\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07version\x18\x02 \x01(\t\x12\x13\n\x0b\x64\x65scription\x18\x03 \x01(\t\x12\x14\n\x0cinput_schema\x18\x04 \x01(\t\x12\x15\n\routput_schema\x18\x05 \x01(\t\x12\x17\n\x0fsupports_stream\x18\x06 \x01(\x08\x12&\n\x04gate\x18\x07 \x01(\x0b\x32\x18.rune.wire.v1.GateConfig\x12\x10\n\x08priority\x18\x08 \x01(\x05\"*\n\nGateConfig\x12\x0c\n\x04path\x18\x01 \x01(\t\x12\x0e\n\x06method\x18\x02 \x01(\t\"C\n\x0e\x46ileAttachment\x12\x10\n\x08\x66ilename\x18\x01 \x01(\t\x12\x0c\n\x04\x64\x61ta\x18\x02 \x01(\x0c\x12\x11\n\tmime_type\x18\x03 \x01(\t\"\xf9\x01\n\x0e\x45xecuteRequest\x12\x12\n\nrequest_id\x18\x01 \x01(\t\x12\x11\n\trune_name\x18\x02 \x01(\t\x12\r\n\x05input\x18\x03 \x01(\x0c\x12:\n\x07\x63ontext\x18\x04 \x03(\x0b\x32).rune.wire.v1.ExecuteRequest.ContextEntry\x12\x12\n\ntimeout_ms\x18\x05 \x01(\r\x12\x31\n\x0b\x61ttachments\x18\x06 \x03(\x0b\x32\x1c.rune.wire.v1.FileAttachment\x1a.\n\x0c\x43ontextEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01\"3\n\rCancelRequest\x12\x12\n\nrequest_id\x18\x01 \x01(\t\x12\x0e\n\x06reason\x18\x02 \x01(\t\"\xb6\x01\n\rExecuteResult\x12\x12\n\nrequest_id\x18\x01 \x01(\t\x12$\n\x06status\x18\x02 \x01(\x0e\x32\x14.rune.wire.v1.Status\x12\x0e\n\x06output\x18\x03 \x01(\x0c\x12(\n\x05\x65rror\x18\x04 \x01(\x0b\x32\x19.rune.wire.v1.ErrorDetail\x12\x31\n\x0b\x61ttachments\x18\x05 \x03(\x0b\x32\x1c.rune.wire.v1.FileAttachment\"C\n\x0bStreamEvent\x12\x12\n\nrequest_id\x18\x01 \x01(\t\x12\x0c\n\x04\x64\x61ta\x18\x02 \x01(\x0c\x12\x12\n\nevent_type\x18\x03 \x01(\t\"o\n\tStreamEnd\x12\x12\n\nrequest_id\x18\x01 \x01(\t\x12$\n\x06status\x18\x02 \x01(\x0e\x32\x14.rune.wire.v1.Status\x12(\n\x05\x65rror\x18\x03 \x01(\x0b\x32\x19.rune.wire.v1.ErrorDetail\"!\n\tHeartbeat\x12\x14\n\x0ctimestamp_ms\x18\x01 \x01(\x04\"=\n\x0b\x45rrorDetail\x12\x0c\n\x04\x63ode\x18\x01 \x01(\t\x12\x0f\n\x07message\x18\x02 \x01(\t\x12\x0f\n\x07\x64\x65tails\x18\x03 \x01(\x0c*_\n\x06Status\x12\x16\n\x12STATUS_UNSPECIFIED\x10\x00\x12\x14\n\x10STATUS_COMPLETED\x10\x01\x12\x11\n\rSTATUS_FAILED\x10\x02\x12\x14\n\x10STATUS_CANCELLED\x10\x03\x32X\n\x0bRuneService\x12I\n\x07Session\x12\x1c.rune.wire.v1.SessionMessage\x1a\x1c.rune.wire.v1.SessionMessage(\x01\x30\x01\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'rune.wire.v1.rune_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
+  _globals['_CASTERATTACH_LABELSENTRY']._loaded_options = None
+  _globals['_CASTERATTACH_LABELSENTRY']._serialized_options = b'8\001'
+  _globals['_EXECUTEREQUEST_CONTEXTENTRY']._loaded_options = None
+  _globals['_EXECUTEREQUEST_CONTEXTENTRY']._serialized_options = b'8\001'
+  _globals['_STATUS']._serialized_start=1909
+  _globals['_STATUS']._serialized_end=2004
+  _globals['_SESSIONMESSAGE']._serialized_start=42
+  _globals['_SESSIONMESSAGE']._serialized_end=495
+  _globals['_CASTERATTACH']._serialized_start=498
+  _globals['_CASTERATTACH']._serialized_end=717
+  _globals['_CASTERATTACH_LABELSENTRY']._serialized_start=672
+  _globals['_CASTERATTACH_LABELSENTRY']._serialized_end=717
+  _globals['_ATTACHACK']._serialized_start=719
+  _globals['_ATTACHACK']._serialized_end=792
+  _globals['_CASTERDETACH']._serialized_start=794
+  _globals['_CASTERDETACH']._serialized_end=824
+  _globals['_RUNEDECLARATION']._serialized_start=827
+  _globals['_RUNEDECLARATION']._serialized_end=1024
+  _globals['_GATECONFIG']._serialized_start=1026
+  _globals['_GATECONFIG']._serialized_end=1068
+  _globals['_FILEATTACHMENT']._serialized_start=1070
+  _globals['_FILEATTACHMENT']._serialized_end=1137
+  _globals['_EXECUTEREQUEST']._serialized_start=1140
+  _globals['_EXECUTEREQUEST']._serialized_end=1389
+  _globals['_EXECUTEREQUEST_CONTEXTENTRY']._serialized_start=1343
+  _globals['_EXECUTEREQUEST_CONTEXTENTRY']._serialized_end=1389
+  _globals['_CANCELREQUEST']._serialized_start=1391
+  _globals['_CANCELREQUEST']._serialized_end=1442
+  _globals['_EXECUTERESULT']._serialized_start=1445
+  _globals['_EXECUTERESULT']._serialized_end=1627
+  _globals['_STREAMEVENT']._serialized_start=1629
+  _globals['_STREAMEVENT']._serialized_end=1696
+  _globals['_STREAMEND']._serialized_start=1698
+  _globals['_STREAMEND']._serialized_end=1809
+  _globals['_HEARTBEAT']._serialized_start=1811
+  _globals['_HEARTBEAT']._serialized_end=1844
+  _globals['_ERRORDETAIL']._serialized_start=1846
+  _globals['_ERRORDETAIL']._serialized_end=1907
+  _globals['_RUNESERVICE']._serialized_start=2006
+  _globals['_RUNESERVICE']._serialized_end=2094
+# @@protoc_insertion_point(module_scope)

rune/_proto/rune/wire/v1/rune_pb2_grpc.py

@@ -0,0 +1,100 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+from rune._proto.rune.wire.v1 import rune_pb2 as rune_dot_wire_dot_v1_dot_rune__pb2
+
+GRPC_GENERATED_VERSION = '1.78.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in rune/wire/v1/rune_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class RuneServiceStub(object):
+    """Caster 与 Runtime 的双向流
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.Session = channel.stream_stream(
+                '/rune.wire.v1.RuneService/Session',
+                request_serializer=rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.SerializeToString,
+                response_deserializer=rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.FromString,
+                _registered_method=True)
+
+
+class RuneServiceServicer(object):
+    """Caster 与 Runtime 的双向流
+    """
+
+    def Session(self, request_iterator, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_RuneServiceServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'Session': grpc.stream_stream_rpc_method_handler(
+                    servicer.Session,
+                    request_deserializer=rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.FromString,
+                    response_serializer=rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'rune.wire.v1.RuneService', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('rune.wire.v1.RuneService', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class RuneService(object):
+    """Caster 与 Runtime 的双向流
+    """
+
+    @staticmethod
+    def Session(request_iterator,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.stream_stream(
+            request_iterator,
+            target,
+            '/rune.wire.v1.RuneService/Session',
+            rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.SerializeToString,
+            rune_dot_wire_dot_v1_dot_rune__pb2.SessionMessage.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

rune/caster.py

@@ -0,0 +1,454 @@
+"""Caster -- connects to Rune runtime and executes registered handlers."""
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import logging
+import threading
+import time
+from typing import Callable, Awaitable
+
+import grpc
+
+from .types import RuneConfig, RuneContext, FileAttachment
+from .stream import StreamSender
+from .handler import RegisteredRune, OnceHandler
+
+# Ensure _proto dir is on sys.path before importing generated code.
+from . import _proto  # noqa: F401
+from ._proto.rune.wire.v1 import rune_pb2, rune_pb2_grpc
+
+logger = logging.getLogger("rune")
+
+
+class Caster:
+    """Connects to a Rune runtime server and executes registered handlers."""
+
+    def __init__(
+        self,
+        addr: str = "localhost:50070",
+        caster_id: str = "python-caster",
+        max_concurrent: int = 10,
+        reconnect_base_delay: float = 1.0,
+        reconnect_max_delay: float = 30.0,
+        heartbeat_interval: float = 10.0,
+        labels: dict[str, str] | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        self._addr = addr
+        self._caster_id = caster_id
+        self._max_concurrent = max_concurrent
+        self._runes: dict[str, RegisteredRune] = {}
+        self._cancelled: set[str] = set()
+        self._reconnect_base_delay = reconnect_base_delay
+        self._reconnect_max_delay = reconnect_max_delay
+        self._heartbeat_interval = heartbeat_interval
+        self._labels = labels or {}
+        self._api_key = api_key
+        self._shutdown = threading.Event()
+
+    # ------------------------------------------------------------------
+    # Decorator API
+    # ------------------------------------------------------------------
+
+    def rune(
+        self,
+        name: str,
+        *,
+        version: str = "0.0.0",
+        description: str = "",
+        gate: str | None = None,
+        gate_method: str = "POST",
+        input_schema: dict | None = None,
+        output_schema: dict | None = None,
+        priority: int = 0,
+    ) -> Callable:
+        """Decorator to register a unary rune handler."""
+
+        def decorator(fn: OnceHandler) -> OnceHandler:
+            config = RuneConfig(
+                name=name,
+                version=version,
+                description=description,
+                supports_stream=False,
+                gate=gate,
+                gate_method=gate_method,
+                input_schema=input_schema,
+                output_schema=output_schema,
+                priority=priority,
+            )
+            accepts_files = _handler_accepts_files(fn)
+            self._runes[name] = RegisteredRune(
+                config=config, handler=fn, is_stream=False, accepts_files=accepts_files,
+            )
+            return fn
+
+        return decorator
+
+    def stream_rune(
+        self,
+        name: str,
+        *,
+        version: str = "0.0.0",
+        description: str = "",
+        gate: str | None = None,
+        gate_method: str = "POST",
+        input_schema: dict | None = None,
+        output_schema: dict | None = None,
+        priority: int = 0,
+    ) -> Callable:
+        """Decorator to register a streaming rune handler."""
+
+        def decorator(fn: Callable) -> Callable:
+            config = RuneConfig(
+                name=name,
+                version=version,
+                description=description,
+                supports_stream=True,
+                gate=gate,
+                gate_method=gate_method,
+                input_schema=input_schema,
+                output_schema=output_schema,
+                priority=priority,
+            )
+            accepts_files = _handler_accepts_files(fn)
+            self._runes[name] = RegisteredRune(
+                config=config, handler=fn, is_stream=True, accepts_files=accepts_files,
+            )
+            return fn
+
+        return decorator
+
+    # ------------------------------------------------------------------
+    # Run
+    # ------------------------------------------------------------------
+
+    def run(self) -> None:
+        """Start the caster (blocking). Runs asyncio event loop with auto-reconnect."""
+        asyncio.run(self._run_with_reconnect())
+
+    def stop(self) -> None:
+        """Signal the caster to stop its run loop.
+
+        Safe to call from any thread.  The ``run()`` method will return
+        shortly after this is called.
+        """
+        self._shutdown.set()
+
+    async def _run_with_reconnect(self) -> None:
+        """Reconnect loop with exponential backoff."""
+        delay = self._reconnect_base_delay
+        while not self._shutdown.is_set():
+            try:
+                await self._session()
+                # Session ended normally (detach) -- don't reconnect
+                logger.info("session ended normally")
+                break
+            except grpc.aio.AioRpcError as e:
+                if self._shutdown.is_set():
+                    break
+                logger.warning("gRPC error: %s, reconnecting in %.1fs", e.code(), delay)
+            except Exception as e:
+                if self._shutdown.is_set():
+                    break
+                logger.warning("session error: %s, reconnecting in %.1fs", e, delay)
+
+            # Wait for delay or shutdown, whichever comes first
+            if self._shutdown.wait(timeout=delay):
+                break  # shutdown requested
+            delay = min(delay * 2, self._reconnect_max_delay)
+            logger.info("reconnecting to %s ...", self._addr)
+
+    # ------------------------------------------------------------------
+    # Attach message builder
+    # ------------------------------------------------------------------
+
+    def _build_attach_message(self) -> rune_pb2.SessionMessage:
+        """Build the CasterAttach session message."""
+        declarations = []
+        for registered in self._runes.values():
+            decl = rune_pb2.RuneDeclaration(
+                name=registered.config.name,
+                version=registered.config.version,
+                description=registered.config.description,
+                supports_stream=registered.config.supports_stream,
+                input_schema=json.dumps(registered.config.input_schema) if registered.config.input_schema else "",
+                output_schema=json.dumps(registered.config.output_schema) if registered.config.output_schema else "",
+                priority=registered.config.priority,
+            )
+            if registered.config.gate:
+                decl.gate.CopyFrom(
+                    rune_pb2.GateConfig(
+                        path=registered.config.gate,
+                        method=registered.config.gate_method,
+                    )
+                )
+            declarations.append(decl)
+
+        return rune_pb2.SessionMessage(
+            attach=rune_pb2.CasterAttach(
+                caster_id=self._caster_id,
+                runes=declarations,
+                labels=self._labels,
+                max_concurrent=self._max_concurrent,
+                key=self._api_key or "",
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Session
+    # ------------------------------------------------------------------
+
+    async def _session(self) -> None:
+        """Run one gRPC session."""
+        async with grpc.aio.insecure_channel(self._addr) as channel:
+            stub = rune_pb2_grpc.RuneServiceStub(channel)
+
+            # Bidirectional stream
+            outbound_queue: asyncio.Queue[rune_pb2.SessionMessage | None] = asyncio.Queue()
+
+            async def outbound_iter():
+                while True:
+                    msg = await outbound_queue.get()
+                    if msg is None:
+                        break
+                    yield msg
+
+            call = stub.Session(outbound_iter())
+
+            # Build and send attach message
+            attach_msg = self._build_attach_message()
+            await outbound_queue.put(attach_msg)
+
+            # Start heartbeat task
+            hb_task = asyncio.create_task(self._heartbeat_loop(outbound_queue))
+
+            # Monitor shutdown event to cancel the gRPC call
+            async def _watch_shutdown():
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(None, self._shutdown.wait)
+                call.cancel()
+
+            shutdown_task = asyncio.create_task(_watch_shutdown())
+
+            try:
+                async for msg in call:
+                    if self._shutdown.is_set():
+                        break
+
+                    payload = msg.WhichOneof("payload")
+
+                    if payload == "attach_ack":
+                        if msg.attach_ack.accepted:
+                            logger.info(
+                                "attached to %s, caster_id=%s",
+                                self._addr,
+                                self._caster_id,
+                            )
+                        else:
+                            logger.error("attach rejected: %s", msg.attach_ack.reason)
+                            break
+
+                    elif payload == "execute":
+                        req = msg.execute
+                        asyncio.create_task(self._handle_execute(req, outbound_queue))
+
+                    elif payload == "cancel":
+                        self._cancelled.add(msg.cancel.request_id)
+                        logger.info("cancel requested: %s", msg.cancel.request_id)
+
+                    elif payload == "heartbeat":
+                        pass  # server heartbeat received
+
+            finally:
+                shutdown_task.cancel()
+                hb_task.cancel()
+                await outbound_queue.put(None)  # stop outbound iter
+
+    # ------------------------------------------------------------------
+    # Heartbeat
+    # ------------------------------------------------------------------
+
+    async def _heartbeat_loop(self, queue: asyncio.Queue) -> None:
+        """Send periodic heartbeat."""
+        try:
+            while True:
+                await asyncio.sleep(self._heartbeat_interval)
+                msg = rune_pb2.SessionMessage(
+                    heartbeat=rune_pb2.Heartbeat(
+                        timestamp_ms=int(time.time() * 1000),
+                    )
+                )
+                await queue.put(msg)
+        except asyncio.CancelledError:
+            pass
+
+    # ------------------------------------------------------------------
+    # Execute dispatch
+    # ------------------------------------------------------------------
+
+    async def _handle_execute(
+        self,
+        req: rune_pb2.ExecuteRequest,
+        outbound_queue: asyncio.Queue,
+    ) -> None:
+        """Execute a rune handler (once or stream)."""
+        registered = self._runes.get(req.rune_name)
+        if registered is None:
+            await outbound_queue.put(
+                rune_pb2.SessionMessage(
+                    result=rune_pb2.ExecuteResult(
+                        request_id=req.request_id,
+                        status=rune_pb2.STATUS_FAILED,
+                        error=rune_pb2.ErrorDetail(
+                            code="NOT_FOUND",
+                            message=f"rune '{req.rune_name}' not found",
+                        ),
+                    )
+                )
+            )
+            return
+
+        ctx = RuneContext(
+            rune_name=req.rune_name,
+            request_id=req.request_id,
+            context=dict(req.context),
+        )
+
+        try:
+            if registered.is_stream:
+                await self._execute_stream(registered, ctx, req, outbound_queue)
+            else:
+                await self._execute_once(registered, ctx, req, outbound_queue)
+        except Exception as e:
+            logger.error("handler error for %s: %s", req.rune_name, e)
+            await outbound_queue.put(
+                rune_pb2.SessionMessage(
+                    result=rune_pb2.ExecuteResult(
+                        request_id=req.request_id,
+                        status=rune_pb2.STATUS_FAILED,
+                        error=rune_pb2.ErrorDetail(
+                            code="EXECUTION_FAILED",
+                            message=str(e),
+                        ),
+                    )
+                )
+            )
+        finally:
+            # NF-8: Always clean up the cancelled set to prevent unbounded growth
+            self._cancelled.discard(req.request_id)
+
+    async def _execute_once(
+        self,
+        registered: RegisteredRune,
+        ctx: RuneContext,
+        req: rune_pb2.ExecuteRequest,
+        outbound_queue: asyncio.Queue,
+    ) -> None:
+        """Execute unary handler."""
+        if registered.accepts_files:
+            attachments = _extract_attachments(req)
+            result = registered.handler(ctx, bytes(req.input), attachments)
+        else:
+            result = registered.handler(ctx, bytes(req.input))
+        output = await _ensure_awaitable(result)
+
+        # Check if cancelled during execution
+        if req.request_id in self._cancelled:
+            self._cancelled.discard(req.request_id)
+            logger.info("request %s cancelled during execution, discarding", req.request_id)
+            return
+
+        await outbound_queue.put(
+            rune_pb2.SessionMessage(
+                result=rune_pb2.ExecuteResult(
+                    request_id=req.request_id,
+                    status=rune_pb2.STATUS_COMPLETED,
+                    output=output,
+                )
+            )
+        )
+
+    async def _execute_stream(
+        self,
+        registered: RegisteredRune,
+        ctx: RuneContext,
+        req: rune_pb2.ExecuteRequest,
+        outbound_queue: asyncio.Queue,
+    ) -> None:
+        """Execute streaming handler."""
+
+        async def send_event(data: bytes) -> None:
+            if req.request_id in self._cancelled:
+                raise RuntimeError("cancelled")
+            await outbound_queue.put(
+                rune_pb2.SessionMessage(
+                    stream_event=rune_pb2.StreamEvent(
+                        request_id=req.request_id,
+                        data=data,
+                    )
+                )
+            )
+
+        sender = StreamSender(send_event)
+        if registered.accepts_files:
+            attachments = _extract_attachments(req)
+            result = registered.handler(ctx, bytes(req.input), attachments, sender)
+        else:
+            result = registered.handler(ctx, bytes(req.input), sender)
+        await _ensure_awaitable(result)
+
+        # Send StreamEnd
+        await outbound_queue.put(
+            rune_pb2.SessionMessage(
+                stream_end=rune_pb2.StreamEnd(
+                    request_id=req.request_id,
+                    status=rune_pb2.STATUS_COMPLETED,
+                )
+            )
+        )
+
+
+# ------------------------------------------------------------------
+# Helpers (module-level)
+# ------------------------------------------------------------------
+
+
+async def _ensure_awaitable(result):
+    """Await a coroutine or return a sync result directly.
+
+    If the handler is a regular (non-async) function its return value
+    is *not* a coroutine and attempting ``await`` on it raises
+    ``TypeError``.  This wrapper detects that case and returns the
+    value as-is, so that sync handlers work transparently.
+    """
+    if inspect.isawaitable(result):
+        return await result
+    return result
+
+
+def _handler_accepts_files(fn: Callable) -> bool:
+    """Check if handler function has a 'files' parameter (3rd arg for once, 3rd for stream)."""
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.keys())
+    # Once handler: (ctx, input) or (ctx, input, files)
+    # Stream handler: (ctx, input, stream) or (ctx, input, files, stream)
+    # If there are >= 3 params, check the 3rd param name
+    if len(params) >= 3:
+        third = params[2]
+        if third == "files":
+            return True
+    return False
+
+
+def _extract_attachments(req: rune_pb2.ExecuteRequest) -> list[FileAttachment]:
+    """Convert proto attachments to FileAttachment dataclass list."""
+    return [
+        FileAttachment(
+            filename=att.filename,
+            data=bytes(att.data),
+            mime_type=att.mime_type,
+        )
+        for att in req.attachments
+    ]

rune/handler.py

@@ -0,0 +1,27 @@
+"""Handler registry with decorator support."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Awaitable
+
+from .types import RuneConfig, RuneContext, FileAttachment
+from .stream import StreamSender
+
+
+# Handler function signatures
+OnceHandler = Callable[[RuneContext, bytes], Awaitable[bytes]]
+StreamHandler = Callable  # async def(ctx, input, stream) -> None
+
+# Extended handler signatures with file attachments
+OnceHandlerWithFiles = Callable[[RuneContext, bytes, list[FileAttachment]], Awaitable[bytes]]
+StreamHandlerWithFiles = Callable[[RuneContext, bytes, list[FileAttachment], StreamSender], Awaitable[None]]
+
+
+@dataclass
+class RegisteredRune:
+    """A registered rune with its config and handler."""
+
+    config: RuneConfig
+    handler: OnceHandler | StreamHandler | OnceHandlerWithFiles | StreamHandlerWithFiles
+    is_stream: bool
+    accepts_files: bool = False

rune/stream.py

@@ -0,0 +1,33 @@
+"""StreamSender for streaming Rune handlers."""
+from __future__ import annotations
+
+import json
+
+
+class StreamSender:
+    """Sends stream events to the runtime."""
+
+    def __init__(self, send_fn):
+        self._send = send_fn
+        self._ended = False
+
+    async def emit(self, data: bytes | str | dict | list) -> None:
+        """Send a stream event.
+
+        Accepts bytes, str (auto-encoded to UTF-8), or dict/list (auto-serialized to JSON bytes).
+        """
+        if self._ended:
+            raise RuntimeError("stream already ended")
+        if isinstance(data, bytes):
+            raw = data
+        elif isinstance(data, str):
+            raw = data.encode("utf-8")
+        elif isinstance(data, (dict, list)):
+            raw = json.dumps(data).encode("utf-8")
+        else:
+            raw = str(data).encode("utf-8")
+        await self._send(raw)
+
+    async def end(self) -> None:
+        """Signal end of stream."""
+        self._ended = True

rune/types.py

@@ -0,0 +1,35 @@
+"""Core types for the Rune Python SDK."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class RuneConfig:
+    """Configuration for a Rune registration."""
+    name: str
+    version: str = "0.0.0"
+    description: str = ""
+    supports_stream: bool = False
+    gate: str | None = None  # gate path, e.g. "/translate"
+    gate_method: str = "POST"
+    input_schema: dict | None = None   # JSON Schema for input validation
+    output_schema: dict | None = None  # JSON Schema for output validation
+    priority: int = 0                  # Caster priority (higher wins)
+
+
+@dataclass
+class FileAttachment:
+    """File attachment for ExecuteRequest / ExecuteResult."""
+    filename: str
+    data: bytes
+    mime_type: str
+
+
+@dataclass
+class RuneContext:
+    """Execution context passed to handler."""
+    rune_name: str
+    request_id: str
+    context: dict[str, str] = field(default_factory=dict)

rune_framework-1.1.1.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: rune-framework
+Version: 1.1.1
+Summary: Official Python SDK for Rune — protocol-first multi-language function execution framework
+Author: Chasey
+License: MIT
+Project-URL: Homepage, https://github.com/chasey-dev/rune
+Project-URL: Repository, https://github.com/chasey-dev/rune
+Project-URL: Documentation, https://github.com/chasey-dev/rune/tree/main/sdks/python
+Keywords: rune,grpc,distributed,function,execution,framework
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# Rune Python SDK
+
+Official Python Caster SDK for the Rune framework.
+
+## 安装
+
+```bash
+pip install rune-framework
+```
+
+要求 Python >= 3.10。
+
+## 快速开始
+
+```python
+from rune import Caster
+
+caster = Caster("localhost:50070")
+
+@caster.rune("echo", gate="/echo")
+async def echo(ctx, input):
+    return input
+
+caster.run()
+```
+
+启动后 Runtime 自动暴露：
+```
+POST /echo              -- sync
+POST /echo?stream=true  -- SSE streaming
+POST /echo?async=true   -- async task
+```
+
+## Caster 配置
+
+```python
+caster = Caster(
+    addr="localhost:50070",           # Runtime gRPC 地址
+    caster_id="my-python-caster",     # Caster ID（默认 "python-caster"）
+    max_concurrent=10,                # 最大并发处理数
+    labels={"env": "prod", "gpu": "true"},  # Caster 标签（用于标签路由）
+    api_key="rk_xxx",                # API Key（认证开启时需要）
+    reconnect_base_delay=1.0,         # 重连初始延迟（秒）
+    reconnect_max_delay=30.0,         # 重连最大延迟（秒）
+    heartbeat_interval=10.0,          # 心跳间隔（秒）
+)
+```
+
+## 注册 Rune
+
+### Unary Handler
+
+```python
+@caster.rune(
+    "translate",
+    gate="/translate",                # HTTP 路由路径
+    gate_method="POST",               # HTTP 方法（默认 POST）
+    version="1.0.0",                  # 语义版本
+    description="Translate text",     # 人类可读描述
+    priority=10,                      # 优先级（越高越优先）
+    input_schema={                    # JSON Schema 输入校验
+        "type": "object",
+        "properties": {
+            "text": {"type": "string"},
+            "lang": {"type": "string"}
+        },
+        "required": ["text", "lang"]
+    },
+    output_schema={                   # JSON Schema 输出校验
+        "type": "object",
+        "properties": {
+            "translated": {"type": "string"}
+        }
+    },
+)
+async def translate(ctx, input):
+    data = json.loads(input)
+    result = do_translate(data["text"], data["lang"])
+    return json.dumps({"translated": result})
+```
+
+### Streaming Handler
+
+```python
+@caster.stream_rune("generate", gate="/generate")
+async def generate(ctx, input, sender):
+    prompt = json.loads(input)["prompt"]
+    for token in model.stream(prompt):
+        await sender.emit(token)       # 发送一个 chunk
+    # StreamEnd 自动发送
+```
+
+`StreamSender.emit()` 接受 `bytes`、`str`、`dict`、`list` 类型，自动序列化。
+
+### File Handler
+
+Handler 的第三个参数命名为 `files` 时，自动接收文件附件：
+
+```python
+@caster.rune("process-doc", gate="/process")
+async def process_doc(ctx, input, files):
+    # files: list[FileAttachment]
+    for f in files:
+        print(f.filename, f.mime_type, len(f.data))
+    return json.dumps({"processed": len(files)})
+```
+
+`FileAttachment` 字段：
+- `filename: str` -- 文件名
+- `data: bytes` -- 文件内容
+- `mime_type: str` -- MIME 类型
+
+## Context
+
+每次调用都会传入 `RuneContext`：
+
+```python
+@caster.rune("example", gate="/example")
+async def example(ctx, input):
+    print(ctx.rune_name)     # "example"
+    print(ctx.request_id)    # "r-18e8f3a1b-0"
+    print(ctx.context)       # {} (额外的 key-value 上下文)
+    return input
+```
+
+## 运行与停止
+
+```python
+# 阻塞运行（自动重连）
+caster.run()
+
+# 从另一个线程停止
+caster.stop()
+```
+
+## 开发
+
+```bash
+cd sdks/python
+pip install -e ".[dev]"
+pytest tests/test_unit.py       # 单元测试
+pytest tests/test_e2e.py -m e2e # E2E 测试（需要运行中的 Runtime）
+```

rune_framework-1.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+rune/__init__.py,sha256=kP4VkoLmsWKtnCSErHwCraBlWmkOqG3o7hC3fC75Nuc,212
+rune/caster.py,sha256=qRk1LnqF948Qqouxy0gfZq9i3YOdhafHY1hXqC0JFi8,16261
+rune/handler.py,sha256=JK2jKVbzKEyqV1cwImXpn3aaNRXni5Cy-Z6l2CkHfMA,923
+rune/stream.py,sha256=C3X3CiNYqDdZsBMJzNTK0zAFkH4SU6c71WsOhaM7XpI,960
+rune/types.py,sha256=voKBeXciW_Jd5ptVKMNsK-AI78fpO20voNXvaiY-bsE,959
+rune/_proto/__init__.py,sha256=zHdQtjuI2H8TM5wJPaWJY8iP3tMHpGrEEicuWA-rORk,58
+rune/_proto/rune/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rune/_proto/rune/wire/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rune/_proto/rune/wire/v1/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rune/_proto/rune/wire/v1/rune_pb2.py,sha256=pMwAyoq5_cQFFFXDLSYG6L5JV1o_VvaTPAhTX5jFqVA,6915
+rune/_proto/rune/wire/v1/rune_pb2_grpc.py,sha256=CwxOh_bf7NEG58V7U0sUjKsThQTwXuwbNRUn4RFeZC4,3571
+rune_framework-1.1.1.dist-info/licenses/LICENSE,sha256=6btH8q0Bvi2Y3u3i6Yx_nzOYSDjWOM0Lhl0OIbn77m0,1063
+rune_framework-1.1.1.dist-info/METADATA,sha256=xBoA49Pefn2AzfRRyiCKRyF2xDC0ahfOE6xPqdxOWEw,4739
+rune_framework-1.1.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+rune_framework-1.1.1.dist-info/top_level.txt,sha256=WiPBkToefNAERnF4884CB1cJyYYE5lnnGO6OU_iWONA,5
+rune_framework-1.1.1.dist-info/RECORD,,

rune_framework-1.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rune_framework-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chasey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rune_framework-1.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+rune