neon3-sdk 0.1.1__tar.gz

neon3_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: neon3-sdk
+Version: 0.1.1
+Summary: Public Python client SDK for the Neon3 control-plane protocol.
+Author: Neon3
+License: MIT OR Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# neon3-sdk
+
+Python SDK for the Neon3 `neon3.rpc` control plane.
+
+```bash
+cd packages/python-sdk
+pip install -e .
+python -m neon3_sdk calculator
+```
+
+Tests and deterministic scenario:
+
+```bash
+python -m unittest discover -s tests -v
+python -m neon3_sdk calculator --once
+```
+
+### Event subscriptions
+
+The SDK also exposes the canonical `neon3.event` stream. A WGPU window owner
+publishes `ui.file_drop.accepted` for OS file drops; same-machine tools can
+subscribe without implementing a second transport:
+
+```python
+from neon3_sdk import EventClient
+
+events = EventClient.connect("127.0.0.1:39101").subscribe(
+    name="ui.file_drop.accepted"
+)
+with events:
+    for image in events.file_drops():
+        print(image.source_path)
+```
+
+When `--neon-root` is omitted, the command uses the SDK-local `release`
+directory. Set `NEON_ROOT` or pass `--neon-root <path>` only to override it.
+Runtime clients can select a checkout profile with `RuntimeConfig(profile="debug")`
+or `RuntimeConfig(profile="release")`; `auto` preserves the release-first default.

neon3_sdk-0.1.1/README.md

@@ -0,0 +1,38 @@
+# neon3-sdk
+
+Python SDK for the Neon3 `neon3.rpc` control plane.
+
+```bash
+cd packages/python-sdk
+pip install -e .
+python -m neon3_sdk calculator
+```
+
+Tests and deterministic scenario:
+
+```bash
+python -m unittest discover -s tests -v
+python -m neon3_sdk calculator --once
+```
+
+### Event subscriptions
+
+The SDK also exposes the canonical `neon3.event` stream. A WGPU window owner
+publishes `ui.file_drop.accepted` for OS file drops; same-machine tools can
+subscribe without implementing a second transport:
+
+```python
+from neon3_sdk import EventClient
+
+events = EventClient.connect("127.0.0.1:39101").subscribe(
+    name="ui.file_drop.accepted"
+)
+with events:
+    for image in events.file_drops():
+        print(image.source_path)
+```
+
+When `--neon-root` is omitted, the command uses the SDK-local `release`
+directory. Set `NEON_ROOT` or pass `--neon-root <path>` only to override it.
+Runtime clients can select a checkout profile with `RuntimeConfig(profile="debug")`
+or `RuntimeConfig(profile="release")`; `auto` preserves the release-first default.

neon3_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "neon3-sdk"
+version = "0.1.1"
+description = "Public Python client SDK for the Neon3 control-plane protocol."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT OR Apache-2.0" }
+authors = [{ name = "Neon3" }]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.scripts]
+neon3-sdk = "neon3_sdk.cli:main"
+neon3-component-gallery-probe = "neon3_sdk.bin.component_gallery_probe:main"
+neon3-api-contract-probe = "neon3_sdk.bin.api_contract_probe:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+neon3_sdk = ["fixtures/*.nui"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

neon3_sdk-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

neon3_sdk-0.1.1/src/neon3_sdk/__init__.py

@@ -0,0 +1,55 @@
+"""Public Python SDK for Neon3's transport-independent control-plane protocol."""
+
+from .client import NeonClient
+from .calculator import CalculatorDomain, CalculatorServer
+from .errors import NeonError, ProtocolError, RemoteError, TransportError
+from .models import AssetRef, ClientIdentity, EventEnvelope, RpcResponse, ServiceDescription, ServiceHealth, UiFileDropPayload
+from .nui import ComponentGallery, GallerySubmission
+from .input import InputClient, KeyEvent
+from .render import Backend, BackendNegotiation, Camera3D, ColorSpace, ExternalSurface, RenderClient, SurfaceKind, SurfaceOpen, SurfaceSize, SurfaceTarget, WorldInformation, WorldPlacement
+from .runtime import RuntimeConfig, RuntimeEndpoints, RuntimeMode, RuntimeSession, default_neon_root
+from .ui import UiClient, UiProgram
+from .event import EventClient, EventFilter, EventSubscription
+
+__all__ = [
+    "AssetRef",
+    "ClientIdentity",
+    "CalculatorDomain",
+    "CalculatorServer",
+    "Camera3D",
+    "Backend",
+    "BackendNegotiation",
+    "ColorSpace",
+    "ComponentGallery",
+    "GallerySubmission",
+    "ExternalSurface",
+    "InputClient",
+    "KeyEvent",
+    "NeonClient",
+    "NeonError",
+    "ProtocolError",
+    "RemoteError",
+    "RenderClient",
+    "RpcResponse",
+    "ServiceDescription",
+    "ServiceHealth",
+    "SurfaceKind",
+    "SurfaceOpen",
+    "SurfaceSize",
+    "SurfaceTarget",
+    "TransportError",
+    "RuntimeConfig",
+    "RuntimeEndpoints",
+    "RuntimeMode",
+    "RuntimeSession",
+    "default_neon_root",
+    "UiClient",
+    "UiProgram",
+    "EventClient",
+    "EventFilter",
+    "EventSubscription",
+    "EventEnvelope",
+    "UiFileDropPayload",
+    "WorldPlacement",
+    "WorldInformation",
+]

neon3_sdk-0.1.1/src/neon3_sdk/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

neon3_sdk-0.1.1/src/neon3_sdk/bin/__init__.py

@@ -0,0 +1 @@
+"""Executable SDK diagnostics."""

neon3_sdk-0.1.1/src/neon3_sdk/bin/api_contract_probe.py

@@ -0,0 +1,57 @@
+"""Executable JSONL probe for the public multi-mode SDK API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import uuid
+from pathlib import Path
+
+from ..client import NeonClient
+from ..errors import NeonError
+from ..render import Camera3D, RenderClient, SurfaceKind, SurfaceOpen, SurfaceSize, SurfaceTarget, WorldInformation
+from ..runtime import RuntimeConfig, RuntimeEndpoints, RuntimeMode, RuntimeSession, default_neon_root
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--neon-root", type=Path, default=default_neon_root())
+    parser.add_argument("--external-surface", action="store_true")
+    args = parser.parse_args()
+    run_id = str(uuid.uuid4())
+    mode = RuntimeMode.EXTERNAL_SURFACE if args.external_surface else RuntimeMode.HEADLESS
+    config = RuntimeConfig(neon_root=str(args.neon_root), mode=mode, endpoints=RuntimeEndpoints())
+    try:
+        with RuntimeSession(config):
+            rpc = NeonClient.connect(config.endpoints.wgpu, origin="neon3-sdk-api-probe", kind="external_host" if args.external_surface else "cli")
+            description = rpc.describe("wgpu-runtime")
+            emit(run_id, "describe", "passed", service=description.service, capabilities=list(description.capabilities), epoch=description.epoch)
+            renderer = RenderClient(rpc)
+            if args.external_surface:
+                surface = renderer.open_surface(SurfaceOpen("api-probe-session", "api-probe-surface", SurfaceKind.SCREEN_UI, SurfaceSize(320, 180), targets=(SurfaceTarget("api-probe-color"),)))
+                emit(run_id, "surface.open", "passed", descriptor=surface.descriptor)
+                emit(run_id, "surface.acquire", "passed", handles=surface.acquire_current_process())
+                emit(run_id, "surface.frame", "passed", frame=surface.frame())
+            world = WorldInformation("api-probe-world", 1)
+            world_result = renderer.configure_world(world)
+            emit(run_id, "world.configure", "passed", input=world.to_wire(), result=world_result)
+            camera = Camera3D("api-probe-camera", "api-probe-world", (0.0, 1.0, 3.0), (0.0, 0.0, 0.0, 1.0), 1.0, 0.1, 100.0, description.epoch, 1)
+            camera_result = renderer.submit_camera(camera)
+            emit(run_id, "camera.submit", "passed", input=camera.to_wire(), result=camera_result)
+            diagnostics = renderer.diagnostics()
+            graph = renderer.graph_snapshot()
+            emit(run_id, "render.inspect", "passed", diagnostics=diagnostics, graph=graph)
+        emit(run_id, "result", "passed", modes=[mode.value for mode in RuntimeMode], external_surface_contract="negotiated_only")
+        return 0
+    except (NeonError, OSError, RuntimeError, TimeoutError, ValueError) as error:
+        emit(run_id, "result", "failed", error_type=type(error).__name__, error=str(error))
+        return 1
+
+
+def emit(run_id: str, stage: str, status: str, **data: object) -> None:
+    print(json.dumps({"run_id": run_id, "stage": stage, "status": status, **data}, ensure_ascii=True), flush=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

neon3_sdk-0.1.1/src/neon3_sdk/bin/component_gallery_probe.py

@@ -0,0 +1,191 @@
+"""Run the canonical component gallery through actual local Neon3 services.
+
+Each JSONL record includes the stable request ID or process identity needed to
+correlate the Python client, UI runtime, and renderer journals.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from neon3_sdk.client import NeonClient
+from neon3_sdk.errors import NeonError
+from neon3_sdk.models import AssetRef
+from neon3_sdk.nui import ComponentGallery
+from neon3_sdk.runtime import default_neon_root
+
+
+def main() -> int:
+    args = parse_args()
+    run_id = str(uuid.uuid4())
+    processes: list[subprocess.Popen[str]] = []
+    outcome = "failed"
+    try:
+        neon_root = args.neon_root.resolve()
+        runtime_dir = next(
+            (
+                neon_root / "target" / profile
+                for profile in ("release", "debug")
+                if all((neon_root / "target" / profile / name).is_file() for name in ("neon-eventd.exe", "neon-wgpu-runtime.exe", "neon-ui-runtime.exe"))
+            ),
+            neon_root / "target" / "release",
+        )
+        executables = {
+            "eventd": runtime_dir / "neon-eventd.exe",
+            "wgpu-runtime": runtime_dir / "neon-wgpu-runtime.exe",
+            "ui-runtime": runtime_dir / "neon-ui-runtime.exe",
+            "nui-flow-demo": runtime_dir / "nui_flow_demo.exe",
+        }
+        missing = [str(path) for path in executables.values() if not path.is_file()]
+        if missing:
+            emit(run_id, "setup", "failed", missing_binaries=missing)
+            return 2
+        endpoints = {
+            "eventd": args.eventd_endpoint,
+            "ui-runtime": args.ui_endpoint,
+            "wgpu-runtime": args.wgpu_endpoint,
+        }
+        processes = start_services(executables, endpoints, neon_root, run_id)
+        ui = wait_for_health(args.ui_endpoint, "ui-runtime", args.timeout_seconds, run_id)
+        wgpu = wait_for_health(args.wgpu_endpoint, "wgpu-runtime", args.timeout_seconds, run_id)
+        wait_for_health(args.eventd_endpoint, "eventd", args.timeout_seconds, run_id)
+        description = ui.describe("ui-runtime")
+        emit(
+            run_id,
+            "ui.describe",
+            "passed",
+            endpoint=args.ui_endpoint,
+            service=description.service,
+            epoch=description.epoch,
+            capabilities=list(description.capabilities),
+        )
+        gallery = ComponentGallery(neon_root, executables["nui-flow-demo"])
+        asset = AssetRef("sdk-probe-project", 1, 1, "image")
+        submission = gallery.submit(args.ui_endpoint, asset, timeout_seconds=args.timeout_seconds)
+        emit(
+            run_id,
+            "gallery.submit",
+            "passed",
+            endpoint=args.ui_endpoint,
+            source=str(gallery.source_path),
+            executable=str(submission.executable),
+            input_asset=asset.to_wire(),
+            return_code=submission.return_code,
+        )
+        diagnostics = wgpu.diagnostics()
+        graph = wgpu.call("wgpu-runtime", "wgpu.render.graph.snapshot", request_id=f"sdk-gallery-graph-{run_id}")
+        expected_fragment = "nui-flow-case-component-gallery"
+        fragment = wgpu.call(
+            "wgpu-runtime",
+            "wgpu.ui.fragment.snapshot",
+            {"fragment_id": expected_fragment},
+            request_id=f"sdk-gallery-fragment-{run_id}",
+        )
+        fragment_count = diagnostics.get("fragment_count") if isinstance(diagnostics, dict) else None
+        graph_data = graph.result if isinstance(graph.result, dict) else {}
+        fragment_data = fragment.result if isinstance(fragment.result, dict) else {}
+        submitted_id = fragment_data.get("fragment", {}).get("fragment_id")
+        passed = fragment_count is not None and fragment_count >= 1 and submitted_id == expected_fragment
+        emit(
+            run_id,
+            "renderer.verify",
+            "passed" if passed else "failed",
+            endpoint=args.wgpu_endpoint,
+            request_id=fragment.request_id,
+            producer={"ui_runtime_epoch": description.epoch, "nui_source": str(gallery.source_path)},
+            consumer={"wgpu_runtime_epoch": wgpu.health("wgpu-runtime").epoch, "fragment_count": fragment_count},
+            expected_fragment_id=expected_fragment,
+            submitted_fragment_id=submitted_id,
+            fragment_revision=fragment_data.get("fragment_revision"),
+            fragment_sequence=fragment_data.get("sequence"),
+            graph_revision=graph_data.get("graph_revision"),
+        )
+        if not passed:
+            return 1
+        outcome = "passed"
+        return 0
+    except (NeonError, OSError, RuntimeError, subprocess.TimeoutExpired) as error:
+        emit(run_id, "probe", "failed", error_type=type(error).__name__, error=str(error))
+        return 1
+    finally:
+        stop_services(processes, run_id)
+        emit(run_id, "result", outcome)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Submit and verify Neon3's complete ImGui component gallery.")
+    parser.add_argument("--neon-root", type=Path, default=default_neon_root())
+    parser.add_argument("--eventd-endpoint", default="127.0.0.1:39101")
+    parser.add_argument("--ui-endpoint", default="127.0.0.1:39102")
+    parser.add_argument("--wgpu-endpoint", default="127.0.0.1:39103")
+    parser.add_argument("--timeout-seconds", type=float, default=15.0)
+    return parser.parse_args()
+
+
+def start_services(executables: dict[str, Path], endpoints: dict[str, str], cwd: Path, run_id: str) -> list[subprocess.Popen[str]]:
+    commands = [
+        ("eventd", [str(executables["eventd"]), "--server", endpoints["eventd"], "1"]),
+        ("wgpu-runtime", [str(executables["wgpu-runtime"]), "--headless-server", endpoints["wgpu-runtime"]]),
+        (
+            "ui-runtime",
+            [
+                str(executables["ui-runtime"]),
+                "--forward-server",
+                endpoints["ui-runtime"],
+                endpoints["wgpu-runtime"],
+                "127.0.0.1:39104",
+                "--eventd",
+                endpoints["eventd"],
+            ],
+        ),
+    ]
+    processes = []
+    for name, command in commands:
+        process = subprocess.Popen(command, cwd=cwd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True)
+        processes.append(process)
+        emit(run_id, "service.start", "started", service=name, pid=process.pid, endpoint=endpoints.get(name))
+    return processes
+
+
+def wait_for_health(endpoint: str, target: str, timeout_seconds: float, run_id: str) -> NeonClient:
+    deadline = time.monotonic() + timeout_seconds
+    last_error = "not attempted"
+    while time.monotonic() < deadline:
+        client = NeonClient.connect(endpoint, origin="neon3-component-gallery-probe", timeout_seconds=0.5)
+        try:
+            health = client.health(target)
+            if health.status == "healthy":
+                emit(run_id, "service.health", "passed", service=target, endpoint=endpoint, epoch=health.epoch)
+                return client
+            last_error = f"unexpected health status: {health.status}"
+        except NeonError as error:
+            last_error = str(error)
+        time.sleep(0.1)
+    raise RuntimeError(f"health timeout for {target} at {endpoint}: {last_error}")
+
+
+def stop_services(processes: list[subprocess.Popen[str]], run_id: str) -> None:
+    for process in reversed(processes):
+        if process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=3)
+        emit(run_id, "service.stop", "stopped", pid=process.pid, return_code=process.returncode)
+
+
+def emit(run_id: str, stage: str, status: str, **data: Any) -> None:
+    print(json.dumps({"run_id": run_id, "stage": stage, "status": status, **data}, ensure_ascii=True), flush=True)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

neon3_sdk-0.1.1/src/neon3_sdk/calculator.py

@@ -0,0 +1,228 @@
+"""Python-owned calculator domain connected to the Neon3 UI runtime."""
+
+from __future__ import annotations
+
+import json
+import socket
+import struct
+import threading
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .client import NeonClient
+from .errors import ProtocolError, RemoteError, TransportError
+
+CALCULATOR_FLOW = (Path(__file__).with_name("fixtures") / "calculator.nui").read_text(encoding="utf-8")
+
+
+@dataclass
+class CalculatorState:
+    display: float = 0.0
+    accumulator: float = 0.0
+    pending: float = 0.0
+    operation: str = "add"
+    awaiting_operand: bool = True
+    revision: int = 0
+
+
+class CalculatorDomain:
+    """Owns calculator rules and returns only typed UI input publications."""
+
+    def __init__(self) -> None:
+        self.state = CalculatorState()
+        self._lock = threading.Lock()
+        self._seen: dict[str, dict[str, Any]] = {}
+
+    def apply_event(self, event: dict[str, Any], program_revision: dict[str, Any], input_revision: int) -> dict[str, Any]:
+        event_id = event.get("event_id", "")
+        with self._lock:
+            if event_id in self._seen:
+                return self._seen[event_id]
+            intent = event.get("intent", "")
+            if intent.startswith("calculator.number."):
+                digit = {
+                    "zero": 0, "one": 1, "two": 2, "three": 3, "four": 4,
+                    "five": 5, "six": 6, "seven": 7, "eight": 8, "nine": 9,
+                }[intent.rsplit(".", 1)[1]]
+                self.state.display = digit if self.state.awaiting_operand else self.state.display * 10 + digit
+                self.state.awaiting_operand = False
+            elif intent == "calculator.clear":
+                self.state = CalculatorState()
+            elif intent.startswith("calculator.operator."):
+                if not self.state.awaiting_operand:
+                    self.state.accumulator = (
+                        self._calculate(self.state.accumulator, self.state.display, self.state.operation)
+                        if self.state.pending
+                        else self.state.display
+                    )
+                    self.state.pending = self.state.accumulator
+                self.state.operation = intent.rsplit(".", 1)[1]
+                self.state.awaiting_operand = True
+            elif intent == "calculator.equals":
+                if not self.state.awaiting_operand and self.state.pending:
+                    self.state.display = self._calculate(self.state.accumulator, self.state.display, self.state.operation)
+                    self.state.accumulator = self.state.display
+                    self.state.pending = self.state.display
+                self.state.awaiting_operand = True
+            else:
+                raise ValueError(f"unsupported calculator intent: {intent}")
+            self.state.revision += 1
+            publication = self._publication(program_revision, input_revision, event_id)
+            self._seen[event_id] = publication
+            return publication
+
+    @staticmethod
+    def _calculate(left: float, right: float, operation: str) -> float:
+        if operation == "add":
+            return left + right
+        if operation == "subtract":
+            return left - right
+        if operation == "multiply":
+            return left * right
+        if operation == "divide":
+            if right == 0:
+                raise ValueError("division by zero")
+            return left / right
+        return right
+
+    def _publication(self, program_revision: dict[str, Any], input_revision: int, request_id: str) -> dict[str, Any]:
+        next_input_revision = input_revision + 1
+        return {
+            "scalar_frame": {
+                "program_revision": program_revision,
+                "expected_input_revision": input_revision,
+                "request_id": request_id,
+                "idempotency_key": f"calculator-input:{self.state.revision}",
+                "changes": [
+                    {"key": "display", "value": {"kind": "f32", "value": self.state.display}},
+                    {"key": "accumulator", "value": {"kind": "f32", "value": self.state.accumulator}},
+                    {"key": "pending", "value": {"kind": "f32", "value": self.state.pending}},
+                    {"key": "operation", "value": {"kind": "enum", "value": self.state.operation}},
+                ],
+            },
+            "grid_inputs": [],
+            "presentation_update": None,
+            "calculator": {"revision": self.state.revision, "input_revision": next_input_revision, "state": self.state.__dict__.copy()},
+        }
+
+
+class CalculatorServer:
+    """Length-prefixed JSON Neon RPC server for the Python calculator domain."""
+
+    def __init__(self, endpoint: str, domain: CalculatorDomain | None = None) -> None:
+        host, port = endpoint.rsplit(":", 1)
+        self.endpoint = (host, int(port))
+        self.domain = domain or CalculatorDomain()
+        self._listener: socket.socket | None = None
+        self._stop = threading.Event()
+        self.ready = threading.Event()
+        self.start_error: Exception | None = None
+
+    def serve(self) -> None:
+        try:
+            listener = socket.socket()
+            listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            listener.bind(self.endpoint)
+            listener.listen(16)
+            listener.settimeout(0.2)
+            self._listener = listener
+            self.ready.set()
+            while not self._stop.is_set():
+                try:
+                    stream, _ = listener.accept()
+                except socket.timeout:
+                    continue
+                threading.Thread(target=self._handle, args=(stream,), daemon=True).start()
+        except OSError as error:
+            self.start_error = error
+            self.ready.set()
+        finally:
+            if self._listener is not None:
+                self._listener.close()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._listener is not None:
+            self._listener.close()
+
+    def _handle(self, stream: socket.socket) -> None:
+        with stream:
+            try:
+                request = json.loads(_recv_frame(stream).decode("utf-8"))
+                response = self._dispatch(request)
+                _send_frame(stream, json.dumps(response, separators=(",", ":")).encode("utf-8"))
+            except Exception as error:
+                request_id = request.get("request_id", "unknown") if isinstance(request, dict) else "unknown"
+                response = _response(request_id, "failed", error={"code": "calculator_error", "message": str(error)})
+                try:
+                    _send_frame(stream, json.dumps(response, separators=(",", ":")).encode("utf-8"))
+                except OSError:
+                    pass
+
+    def _dispatch(self, request: dict[str, Any]) -> dict[str, Any]:
+        request_id = request["request_id"]
+        method = request["method"]
+        if method == "service.health":
+            return _response(request_id, "accepted", result={"service": "calculator-python", "status": "healthy", "epoch": 1})
+        if method == "service.describe":
+            return _response(request_id, "accepted", result={"service": "calculator-python", "protocol_version": {"major": 1, "minor": 0}, "endpoint": f"{self.endpoint[0]}:{self.endpoint[1]}", "epoch": 1, "capabilities": ["calculator.evaluate.v1", "ui.host.publication.v1"]})
+        if method == "debug.snapshot.get":
+            return _response(request_id, "accepted", result={"service": "calculator-python", "epoch": 1, "revision": self.domain.state.revision, "state": self.domain.state.__dict__.copy()})
+        if method != "ui.host.inbound":
+            return _response(request_id, "rejected", error={"code": "unsupported_method", "message": "method is not supported"})
+        inbound = request["params"]
+        event = inbound["event"]
+        program_revision = event["program_revision"]
+        input_revision = event["input_revision"]
+        try:
+            publication = self.domain.apply_event(event, program_revision, input_revision)
+        except ValueError as error:
+            return _response(request_id, "rejected", error={"code": "calculator_rejected", "message": str(error)})
+        return _response(request_id, "accepted", revision=publication["calculator"]["input_revision"], result={k: v for k, v in publication.items() if k != "calculator"}, snapshot=publication["calculator"])
+
+
+def submit_calculator(client: NeonClient, source: str = CALCULATOR_FLOW) -> dict[str, Any]:
+    return client.call("ui-runtime", "ui.flow.submit", {"source": source}, idempotency_key="calculator-flow-v1").result
+
+
+def send_calculator_event(client: NeonClient, program_revision: dict[str, Any], input_revision: int, intent: str, source_node_key: str) -> Any:
+    event_id = str(uuid.uuid4())
+    event = {
+        "event_id": event_id,
+        "kind": "activate",
+        "intent": intent,
+        "source_node_key": source_node_key,
+        "payload": {},
+        "program_revision": program_revision,
+        "input_revision": input_revision,
+        "request_id": event_id,
+        "idempotency_key": f"calculator-event:{event_id}",
+        "interaction": {"interaction_id": event_id, "sequence": 1, "renderer_epoch": 1},
+    }
+    return client.call("ui-runtime", "ui.host.inbound", {"kind": "semantic_intent", "event": event}, idempotency_key=f"calculator-host:{event_id}")
+
+
+def _response(request_id: str, status: str, *, result: Any = None, snapshot: Any = None, revision: int | None = None, error: dict[str, Any] | None = None) -> dict[str, Any]:
+    return {"request_id": request_id, "status": status, "revision": revision, "result": result, "snapshot": snapshot, "error": error}
+
+
+def _recv_frame(stream: socket.socket) -> bytes:
+    header = _recv_exact(stream, 4)
+    size = struct.unpack(">I", header)[0]
+    return _recv_exact(stream, size)
+
+
+def _recv_exact(stream: socket.socket, size: int) -> bytes:
+    data = bytearray()
+    while len(data) < size:
+        chunk = stream.recv(size - len(data))
+        if not chunk:
+            raise TransportError("connection_closed")
+        data.extend(chunk)
+    return bytes(data)
+
+
+def _send_frame(stream: socket.socket, payload: bytes) -> None:
+    stream.sendall(struct.pack(">I", len(payload)) + payload)