robotrt-sdk 0.1.0__tar.gz

robotrt_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: robotrt-sdk
+Version: 0.1.0
+Summary: RobotRT Python SDK (FFI thin wrapper)
+Author: RobotRT Maintainers
+License-Expression: Apache-2.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# RobotRT Python SDK (Embedded + Daemon)
+
+This directory contains the Python-first SDK implementation on top of the frozen Core FFI ABI.
+
+## Scope
+
+- Embedded mode SDK surface for node and buffer lease lifecycle.
+- Embedded mode full communication APIs: pub/sub, service, action, mission.
+- Embedded mode executor APIs: SimpleExecutor, CallbackExecutor, and MultiThreadExecutor.
+- MultiThread one-shot APIs are `enqueue_*_once`; persistent grouped path uses explicit methods:
+  `register_subscription_handler_grouped_persistent`,
+  `register_service_handler_grouped_persistent`,
+  `register_action_handler_grouped_persistent`,
+  `register_mission_handler_grouped_persistent`.
+- Daemon mode status SDK surface for snapshot/list/info/watch query.
+- Unified error mapping from C ABI status and error payload.
+- Zero-copy readable view via borrowed lease pointer to Python `memoryview`.
+
+## Embedded Communication API (MVP)
+
+```python
+import robotrt_sdk as sdk
+
+with sdk.Node.create() as node:
+  pub = node.create_publisher("/demo/topic")
+  sub = node.create_subscriber("/demo/topic")
+  pub.publish_batch([b"hello", b"robotrt", b"batch"])
+  batch = sub.recv_batch(8)
+  for _ in batch:
+    # Reliable topics require explicit ack to release capacity.
+    sub.ack()
+  print(batch)
+  print("backpressure:", sub.backpressure_signal().value)
+
+  server = node.create_service_server("/demo/service")
+  client = node.create_service_client("/demo/service")
+  request_id = client.call(b"ping")
+  rid, req = server.recv_request()
+  server.reply(rid, b"pong")
+  print(client.poll_response(request_id))
+
+  action_server = node.create_action_server("/demo/action")
+  action_client = node.create_action_client("/demo/action")
+  goal_id, accepted = action_client.send_goal(b"goal")
+  gid, goal = action_server.recv_goal()
+  action_server.accept_goal(gid)
+  action_server.publish_feedback(gid, b"50%")
+  action_server.succeed(gid, b"done")
+  print(action_client.poll_result(goal_id))
+
+  mission = node.create_mission_session(42)
+  mission.open("demo_mission")
+  mission.send_command("start:demo")
+  mission.reconcile("cp-1", 2)
+```
+
+Subscriber with optional callback:
+
+```python
+# Basic polling style
+sub = node.create_subscriber("/demo/topic")
+
+# With inline message handler
+sub = node.create_subscriber("/demo/topic", on_message=lambda payload: print(payload))
+```
+
+## Quick Start
+
+1. Build the shared library:
+
+```bash
+cargo build -p core-ffi --lib
+```
+
+2. Run tests:
+
+```bash
+PYTHONPATH=bindings/python python3 -m unittest discover -s bindings/python/tests -p 'test_*.py'
+```
+
+3. Run the embedded zero-copy demo:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/embedded_zero_copy_demo.py
+```
+
+4. Run the daemon status demo:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/daemon_status_demo.py
+```
+
+5. Run additional examples:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/full_comms_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/executor_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/status_watch_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/node_full_stack_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/assembly_full_stack_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/node_inherit_full_stack_demo.py
+```
+
+## Unified Sample Naming
+
+- `node_full_stack_demo`: node-centric style, encapsulates pub/sub, service, action, mission in one app object and uses blocking `spin()`.
+- `assembly_full_stack_demo`: assembly style, creates resources directly and uses `spin_async()` to keep business logic on the main thread.
+- `node_inherit_full_stack_demo`: inherit-node style, directly derives from `sdk.Node` and adds app-level behavior.
+
+## Mode Switch API
+
+```python
+import robotrt_sdk as sdk
+
+# Embedded mode: read local status report.
+embedded = sdk.StatusClient(mode="embedded", report_path="artifacts/introspection/local-loop-status.json")
+print(embedded.node_list())
+
+# Daemon mode: query robotrt-host status service.
+daemon = sdk.StatusClient(mode="daemon", endpoint="127.0.0.1:7588", timeout_ms=1000)
+print(daemon.service_list())
+```
+
+## Environment Variables
+
+- `ROBOTRT_CORE_FFI_LIB`: optional absolute path to the `core-ffi` dynamic library.
+  - If not set, SDK auto-discovers under `target/debug` and `target/debug/deps`.

robotrt_sdk-0.1.0/README.md

@@ -0,0 +1,127 @@
+# RobotRT Python SDK (Embedded + Daemon)
+
+This directory contains the Python-first SDK implementation on top of the frozen Core FFI ABI.
+
+## Scope
+
+- Embedded mode SDK surface for node and buffer lease lifecycle.
+- Embedded mode full communication APIs: pub/sub, service, action, mission.
+- Embedded mode executor APIs: SimpleExecutor, CallbackExecutor, and MultiThreadExecutor.
+- MultiThread one-shot APIs are `enqueue_*_once`; persistent grouped path uses explicit methods:
+  `register_subscription_handler_grouped_persistent`,
+  `register_service_handler_grouped_persistent`,
+  `register_action_handler_grouped_persistent`,
+  `register_mission_handler_grouped_persistent`.
+- Daemon mode status SDK surface for snapshot/list/info/watch query.
+- Unified error mapping from C ABI status and error payload.
+- Zero-copy readable view via borrowed lease pointer to Python `memoryview`.
+
+## Embedded Communication API (MVP)
+
+```python
+import robotrt_sdk as sdk
+
+with sdk.Node.create() as node:
+  pub = node.create_publisher("/demo/topic")
+  sub = node.create_subscriber("/demo/topic")
+  pub.publish_batch([b"hello", b"robotrt", b"batch"])
+  batch = sub.recv_batch(8)
+  for _ in batch:
+    # Reliable topics require explicit ack to release capacity.
+    sub.ack()
+  print(batch)
+  print("backpressure:", sub.backpressure_signal().value)
+
+  server = node.create_service_server("/demo/service")
+  client = node.create_service_client("/demo/service")
+  request_id = client.call(b"ping")
+  rid, req = server.recv_request()
+  server.reply(rid, b"pong")
+  print(client.poll_response(request_id))
+
+  action_server = node.create_action_server("/demo/action")
+  action_client = node.create_action_client("/demo/action")
+  goal_id, accepted = action_client.send_goal(b"goal")
+  gid, goal = action_server.recv_goal()
+  action_server.accept_goal(gid)
+  action_server.publish_feedback(gid, b"50%")
+  action_server.succeed(gid, b"done")
+  print(action_client.poll_result(goal_id))
+
+  mission = node.create_mission_session(42)
+  mission.open("demo_mission")
+  mission.send_command("start:demo")
+  mission.reconcile("cp-1", 2)
+```
+
+Subscriber with optional callback:
+
+```python
+# Basic polling style
+sub = node.create_subscriber("/demo/topic")
+
+# With inline message handler
+sub = node.create_subscriber("/demo/topic", on_message=lambda payload: print(payload))
+```
+
+## Quick Start
+
+1. Build the shared library:
+
+```bash
+cargo build -p core-ffi --lib
+```
+
+2. Run tests:
+
+```bash
+PYTHONPATH=bindings/python python3 -m unittest discover -s bindings/python/tests -p 'test_*.py'
+```
+
+3. Run the embedded zero-copy demo:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/embedded_zero_copy_demo.py
+```
+
+4. Run the daemon status demo:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/daemon_status_demo.py
+```
+
+5. Run additional examples:
+
+```bash
+PYTHONPATH=bindings/python python3 bindings/python/examples/full_comms_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/executor_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/status_watch_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/node_full_stack_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/assembly_full_stack_demo.py
+PYTHONPATH=bindings/python python3 bindings/python/examples/node_inherit_full_stack_demo.py
+```
+
+## Unified Sample Naming
+
+- `node_full_stack_demo`: node-centric style, encapsulates pub/sub, service, action, mission in one app object and uses blocking `spin()`.
+- `assembly_full_stack_demo`: assembly style, creates resources directly and uses `spin_async()` to keep business logic on the main thread.
+- `node_inherit_full_stack_demo`: inherit-node style, directly derives from `sdk.Node` and adds app-level behavior.
+
+## Mode Switch API
+
+```python
+import robotrt_sdk as sdk
+
+# Embedded mode: read local status report.
+embedded = sdk.StatusClient(mode="embedded", report_path="artifacts/introspection/local-loop-status.json")
+print(embedded.node_list())
+
+# Daemon mode: query robotrt-host status service.
+daemon = sdk.StatusClient(mode="daemon", endpoint="127.0.0.1:7588", timeout_ms=1000)
+print(daemon.service_list())
+```
+
+## Environment Variables
+
+- `ROBOTRT_CORE_FFI_LIB`: optional absolute path to the `core-ffi` dynamic library.
+  - If not set, SDK auto-discovers under `target/debug` and `target/debug/deps`.

robotrt_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "robotrt-sdk"
+version = "0.1.0"
+description = "RobotRT Python SDK (FFI thin wrapper)"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "RobotRT Maintainers" }]
+license = "Apache-2.0"
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["robotrt_sdk", "robotrt_sdk.*"]

robotrt_sdk-0.1.0/robotrt_sdk/__init__.py

@@ -0,0 +1,84 @@
+from ._ffi import _CORE
+from ._version import __version__
+import ctypes
+from .core import (
+    ActionClient,
+    ActionGoalHealth,
+    ActionServer,
+    BackpressureSignal,
+    CallbackGroupType,
+    BufferDescriptor,
+    BufferLease,
+    ExternalBufferRef,
+    LeaseView,
+    MissionSession,
+    Node,
+    NodeCallbackBinding,
+    Publisher,
+    CallbackExecutor,
+    MultiThreadExecutor,
+    MultiThreadExecutorStats,
+    RegisteredWork,
+    RegisteredWorkKind,
+    ServiceClient,
+    ServiceServer,
+    SimpleExecutor,
+    Subscriber,
+    TimerRegistration,
+)
+from .errors import ErrorInfo, RobotRtError
+from .lifecycle import LifecycleNode, LifecycleState
+from .logger import Logger
+from .status import StatusClient
+
+__all__ = [
+    "BufferDescriptor",
+    "BufferLease",
+    "ErrorInfo",
+    "LeaseView",
+    "LifecycleNode",
+    "LifecycleState",
+    "Logger",
+    "Node",
+    "NodeCallbackBinding",
+    "Publisher",
+    "Subscriber",
+    "ServiceClient",
+    "ServiceServer",
+    "ActionClient",
+    "ActionGoalHealth",
+    "ActionServer",
+    "BackpressureSignal",
+    "CallbackGroupType",
+    "CallbackExecutor",
+    "ExternalBufferRef",
+    "MissionSession",
+    "MultiThreadExecutor",
+    "MultiThreadExecutorStats",
+    "RobotRtError",
+    "RegisteredWork",
+    "RegisteredWorkKind",
+    "StatusClient",
+    "SimpleExecutor",
+    "TimerRegistration",
+    "__version__",
+    "abi_version",
+    "protocol_version",
+    "build_info",
+]
+
+
+def abi_version() -> int:
+    return int(_CORE.lib.robotrt_core_abi_version())
+
+
+def protocol_version() -> int:
+    return int(_CORE.lib.robotrt_core_protocol_version())
+
+
+def build_info() -> str:
+    needed = ctypes.c_uint32(0)
+    _CORE.lib.robotrt_core_build_info_copy(None, 0, ctypes.byref(needed))
+    buf = ctypes.create_string_buffer(needed.value + 1)
+    _CORE.lib.robotrt_core_build_info_copy(buf, needed.value + 1, ctypes.byref(needed))
+    return buf.value.decode("utf-8", errors="replace")

robotrt_sdk-0.1.0/robotrt_sdk/_ffi.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from ._ffi_loader import CoreFfi, _CORE
+from ._ffi_types import (
+    RT_DURABILITY_TRANSIENT_LOCAL,
+    RT_DURABILITY_VOLATILE,
+    RT_OK,
+    RtActionGoalHealth,
+    RtBufferDescriptor,
+    RtErrorInfo,
+    RtExternalBufferRef,
+    RtTopicQosProfile,
+)
+
+__all__ = [
+    "RT_OK",
+    "CoreFfi",
+    "RT_DURABILITY_TRANSIENT_LOCAL",
+    "RT_DURABILITY_VOLATILE",
+    "RtActionGoalHealth",
+    "RtBufferDescriptor",
+    "RtErrorInfo",
+    "RtExternalBufferRef",
+    "RtTopicQosProfile",
+    "_CORE",
+]

robotrt_sdk-0.1.0/robotrt_sdk/_ffi_loader.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+from pathlib import Path
+
+from ._ffi_signatures import declare_signatures
+from ._ffi_types import RT_OK, RtErrorInfo
+from .errors import ErrorInfo, RobotRtError
+
+
+def _workspace_root() -> Path:
+    return Path(__file__).resolve().parents[3]
+
+
+def _dylib_name() -> str:
+    name = platform.system().lower()
+    if name == "darwin":
+        return "librobotrt_core_ffi.dylib"
+    if name == "windows":
+        return "robotrt_core_ffi.dll"
+    return "librobotrt_core_ffi.so"
+
+
+def _resolve_library_path() -> Path:
+    env = os.environ.get("ROBOTRT_CORE_FFI_LIB")
+    if env:
+        p = Path(env).expanduser().resolve()
+        if p.exists():
+            return p
+        raise FileNotFoundError(f"ROBOTRT_CORE_FFI_LIB does not exist: {p}")
+
+    root = _workspace_root()
+    direct = root / "target" / "debug" / _dylib_name()
+    if direct.exists():
+        return direct
+
+    deps = root / "target" / "debug" / "deps"
+    if deps.exists():
+        suffixes = {".dylib", ".so", ".dll"}
+        for candidate in sorted(deps.iterdir()):
+            if candidate.suffix not in suffixes:
+                continue
+            if candidate.name.startswith("librobotrt_core_ffi") or candidate.name == _dylib_name():
+                return candidate
+
+    raise FileNotFoundError("robotrt core ffi dynamic library not found; run cargo build -p core-ffi --lib")
+
+
+class CoreFfi:
+    def __init__(self) -> None:
+        self.library_path = _resolve_library_path()
+        self.lib = ctypes.CDLL(str(self.library_path))
+        declare_signatures(self.lib)
+
+    def last_error(self) -> ErrorInfo:
+        info = RtErrorInfo()
+        self.lib.robotrt_error_last(ctypes.byref(info))
+
+        needed = ctypes.c_uint32(0)
+        self.lib.robotrt_error_message_copy(None, 0, ctypes.byref(needed))
+        message = ""
+        if needed.value > 0:
+            buf = ctypes.create_string_buffer(needed.value)
+            self.lib.robotrt_error_message_copy(buf, needed.value, ctypes.byref(needed))
+            message = buf.value.decode("utf-8", errors="replace")
+
+        return ErrorInfo(
+            code=int(info.code),
+            domain=int(info.domain),
+            retryable=bool(info.retryable),
+            message=message,
+        )
+
+    def check(self, status: int, context: str) -> None:
+        if status == RT_OK:
+            return
+        raise RobotRtError(self.last_error(), context)
+
+
+_CORE = CoreFfi()