resonite-io 0.1.0__tar.gz

resonite_io-0.1.0/.gitignore

@@ -0,0 +1,227 @@
+# =============================================================================
+# Python
+# =============================================================================
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# uv
+# `python/uv.lock` は commit するので除外しない (lock を commit する方針)
+.venv/
+venv/
+env/
+ENV/
+
+# Type checkers / linters / test runners
+.pytest_cache/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.tox/
+.nox/
+.cache/
+.hypothesis/
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+# Jupyter / IPython
+.ipynb_checkpoints
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# =============================================================================
+# C# / .NET
+# =============================================================================
+
+# Build outputs
+[Bb]in/
+[Oo]bj/
+[Oo]ut/
+[Ll]og/
+[Ll]ogs/
+[Dd]ebug/
+[Dd]ebugPublic/
+[Rr]elease/
+[Rr]eleases/
+x64/
+x86/
+[Ww][Ii][Nn]32/
+[Aa][Rr][Mm]/
+[Aa][Rr][Mm]64/
+bld/
+
+# Visual Studio / Rider / VSCode user state
+.vs/
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.idea/
+*.user
+*.suo
+*.userprefs
+*.userosscache
+*.sln.docstates
+
+# .NET tooling
+.dotnet/
+project.lock.json
+project.fragment.lock.json
+artifacts/
+
+# Test results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+*.VisualState.xml
+TestResult.xml
+nunit-*.xml
+
+# Roslyn cache / build artifacts
+*.tlog
+*.lastbuildstate
+*.cache
+*.ilk
+*.iobj
+*.ipdb
+*.meta
+*_i.c
+*_p.c
+*_h.h
+
+# NuGet
+*.nupkg
+*.snupkg
+**/[Pp]ackages/*
+!**/[Pp]ackages/build/
+*.nuget.props
+*.nuget.targets
+
+# Compiled binaries (mod artifacts deploy 経由で配布する想定)
+*.dll
+*.pdb
+*.exe
+
+# =============================================================================
+# Protobuf
+# =============================================================================
+
+# Python 側の protoc 出力は意図的に commit する (plan §3.C)
+# `python/src/resoio/_generated/` は ignore せず
+#
+# C# 側は csproj の <Protobuf> ItemGroup から build 時生成される (obj/ に出る) ため
+# obj/ の ignore でカバーされる
+
+# =============================================================================
+# Environment / secrets
+# =============================================================================
+
+.env
+.env.*
+!.env.example
+
+# =============================================================================
+# OS noise
+# =============================================================================
+
+.DS_Store
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+
+# =============================================================================
+# Local artifacts
+# =============================================================================
+
+*.log
+*.tmp
+*.swp
+*~
+
+# =============================================================================
+# Docs site (mkdocs)
+# =============================================================================
+
+# `just docs-build` の出力先 (repo root の mkdocs.yml の既定 site_dir)。
+site/
+
+# =============================================================================
+# Host-side scripts venv
+# =============================================================================
+
+# `just host-agent` が起動時に `uv venv` で作る host 専用 venv。
+# 既に `.venv/` で吸えるが、scripts/ 配下の意図を明示するため明記する。
+scripts/.venv/
+
+# =============================================================================
+# E2E artifacts
+# =============================================================================
+
+# `just e2e-test camera_stream` 等が録画した MP4 / PNG の出力先。
+# 動画は数 MB/run で commit する意味がないため ignore。
+python/tests/e2e/e2e_artifacts/
+
+# `just e2e-camera-v2` / `just resonite-screenshot` の出力先。
+# repo-relative path で書き出すため repo root 直下に `tmp/` を作る。
+tmp/
+
+# =============================================================================
+# Decompiled sources
+# =============================================================================
+
+# `just decompile` の出力先。Resonite の decompile 結果は配布物・改変対象では
+# なく開発者個人の参照用なので commit しない。
+decompiled/
+
+# =============================================================================
+# Gale profile
+# =============================================================================
+
+# Gale (Resonite mod manager) のカスタムプロファイル展開先。
+# `just deploy-mod` の配置先 (gale/BepInEx/plugins/ResoniteIO/) も含めて
+# host 側で Gale が管理するため、リポジトリには持ち込まない。
+gale/
+
+# =============================================================================
+# Claude Code
+# =============================================================================
+
+# 並列 implementer が一時的に作る git worktree のルート。
+.claude/worktrees/
+.claude/settings.local.json
+.claude/scheduled_tasks.lock
+
+# agent memory runtime mirror (canonical tracked copy lives under memory/agents/)
+.claude/agent-memory/

resonite_io-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: resonite-io
+Version: 0.1.0
+Summary: Python client for Resonite IO
+Project-URL: Homepage, https://github.com/MLShukai/ResoniteIO
+Project-URL: Repository, https://github.com/MLShukai/ResoniteIO
+Author: mlshukai
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: argcomplete>=3.5
+Requires-Dist: av>=14
+Requires-Dist: betterproto2[grpclib]
+Requires-Dist: numpy>=2.0
+Requires-Dist: prompt-toolkit>=3.0
+Description-Content-Type: text/markdown
+
+# resonite-io
+
+Python client for [ResoniteIO](https://github.com/MLShukai/ResoniteIO) — a bidirectional IPC
+bridge that turns [Resonite](https://resonite.com/) into a runtime environment for AI agents.
+The `resonite-io` distribution imports as `resoio` and wraps the `resonite_io.v1` gRPC schema
+(Unix Domain Socket transport, async via `grpclib`) into a friendly, fully typed client
+library and a `resoio` CLI.
+
+## Install
+
+```bash
+pip install resonite-io
+```
+
+## Requires
+
+A Resonite client running the **ResoniteIO mod** on the same host (the two halves connect
+over a Unix Domain Socket). See the documentation for installing the mod.
+
+## Quick start
+
+```python
+import asyncio
+
+from resoio import ConnectionClient
+
+
+async def main() -> None:
+    async with ConnectionClient() as client:
+        response = await client.ping("hello")
+        print(response.message)
+
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- **Docs:** <https://mlshukai.github.io/ResoniteIO/>
+- **Source:** <https://github.com/MLShukai/ResoniteIO>
+
+## License
+
+[MIT](https://github.com/MLShukai/ResoniteIO/blob/main/LICENSE)

resonite_io-0.1.0/README.md

@@ -0,0 +1,44 @@
+# resonite-io
+
+Python client for [ResoniteIO](https://github.com/MLShukai/ResoniteIO) — a bidirectional IPC
+bridge that turns [Resonite](https://resonite.com/) into a runtime environment for AI agents.
+The `resonite-io` distribution imports as `resoio` and wraps the `resonite_io.v1` gRPC schema
+(Unix Domain Socket transport, async via `grpclib`) into a friendly, fully typed client
+library and a `resoio` CLI.
+
+## Install
+
+```bash
+pip install resonite-io
+```
+
+## Requires
+
+A Resonite client running the **ResoniteIO mod** on the same host (the two halves connect
+over a Unix Domain Socket). See the documentation for installing the mod.
+
+## Quick start
+
+```python
+import asyncio
+
+from resoio import ConnectionClient
+
+
+async def main() -> None:
+    async with ConnectionClient() as client:
+        response = await client.ping("hello")
+        print(response.message)
+
+
+asyncio.run(main())
+```
+
+## Documentation
+
+- **Docs:** <https://mlshukai.github.io/ResoniteIO/>
+- **Source:** <https://github.com/MLShukai/ResoniteIO>
+
+## License
+
+[MIT](https://github.com/MLShukai/ResoniteIO/blob/main/LICENSE)

resonite_io-0.1.0/examples/README.md

@@ -0,0 +1,119 @@
+# resoio examples
+
+各モダリティの **最小 API 呼び出しサンプル** を 1 ファイル = 1 モダリティで
+収録する。 `python/src/resoio/cli/` の production CLI や `python/tests/e2e/` の
+回帰テストは "完全形" で重いため、ライブラリの呼び方を最短で把握したい場合は
+こちらを読む。
+
+## 前提
+
+- ホスト側で Resonite が起動しており、`ResoniteIO` mod が load 済み
+- mod が `~/.resonite-io/` 配下に UDS を bind 済み (初回環境構築は
+  [`.claude/skills/setup-resonite-env/SKILL.md`](../../.claude/skills/setup-resonite-env/SKILL.md))
+- 依存は dev container 内にすべて閉じている (`uv sync` 済み)
+
+モダリティ固有の追加前提:
+
+- `microphone_send.py` — Resonite Settings → Audio Input で "ResoniteIO" の
+  virtual mic デバイスを選択しないと音は鳴らない (mod 起動後 1 回だけ)
+- `locomotion_drive.py` — `SmoothLocomotionBase` が active な world (default
+  Home Cloud は OK。Teleport / NoClip / NoLocomotion world は不可)
+- `display_config.py` — Resonite が desktop mode で起動していること (VR mode
+  では `ResolutionSettings` が異なる経路を通る)
+- `world_browse.py` — cloud に login 済みで join 可能な公開セッションが見える
+  こと (session list が空 = signed out / 空 cloud の場合は notice を print して
+  安全に終了する)
+- `context_menu_interact.py` — desktop の T-key radial menu が出せる状態
+  (LocalUser / InteractionHandler が attach 済みの world にいること)
+- `dash_navigate.py` — userspace の Esc dash が開ける状態 (engine boot 済み)。
+  screen が少ない logged-out 状態でも開閉は可能だが navigation 先が減る
+- `inventory_manage.py` — cloud に login 済み (inventory ops は実 cloud
+  inventory を叩く)。書込先は自分で mkdir する `/Inventory/__resoio_example__`
+  配下のみで、最後に rm -r で後片付けする
+- `cursor_move.py` — Resonite が desktop mode で起動していること (cursor は
+  desktop window 座標を操作する。カーソル自体は screenshot に写りにくいので、
+  動いたことの可視確認は context menu を開く `tests/e2e/cursor.py` を参照)
+
+## 実行
+
+すべて引数なし。dev container 内で:
+
+```bash
+uv run python python/examples/connection_ping.py
+uv run python python/examples/camera_view.py
+uv run python python/examples/speaker_record.py
+uv run python python/examples/microphone_send.py
+uv run python python/examples/locomotion_drive.py
+uv run python python/examples/display_config.py
+uv run python python/examples/manipulation_grab.py
+uv run python python/examples/world_browse.py
+uv run python python/examples/context_menu_interact.py
+uv run python python/examples/dash_navigate.py
+uv run python python/examples/inventory_manage.py
+uv run python python/examples/cursor_move.py
+```
+
+各 example の内容:
+
+| File                       | やること                                                                                    |
+| -------------------------- | ------------------------------------------------------------------------------------------- |
+| `connection_ping.py`       | `Connection.Ping` を 1 回呼んで RTT と server timestamp を print                            |
+| `camera_view.py`           | 5 秒 streaming して fps と最終フレームの輝度統計を print                                    |
+| `speaker_record.py`        | 5 秒 streaming して peak amplitude を print + `speaker_output.raw` に raw float32 LE で保存 |
+| `microphone_send.py`       | 440 Hz / 3 秒 mono sine wave を生成し virtual mic に送信                                    |
+| `locomotion_drive.py`      | 6 秒 scripted シナリオで forward → strafe → yaw → jump → neutral を流し、reset() で締める   |
+| `display_config.py`        | 現在解像度 → 1024x768 apply → 元解像度に restore                                            |
+| `manipulation_grab.py`     | primary hand で get_state → grab → release の最小サイクル (空き home では grabbed=False)    |
+| `world_browse.py`          | session list → join → list_open_worlds → focus → leave (空 cloud は notice して終了)        |
+| `context_menu_interact.py` | T-key radial を open → get_state → highlight(0) → invoke(first enabled) → close             |
+| `dash_navigate.py`         | Esc dash を open → list_screens → set_screen(key) → get_tree → invoke(first) → close        |
+| `inventory_manage.py`      | 一時 dir を mkdir → cp -r → mv → list で確認 → finally で rm -r 後片付け                    |
+| `cursor_move.py`           | get_position → center(0.5,0.5) → move(0.25,0.25) → 元位置に restore                         |
+
+## FAILED_PRECONDITION について
+
+Resonite cold-boot 中 (UDS は bound 済みだが engine の `LocalUser` /
+`FocusedWorld` がまだ attach されていない期間) は、各 bridge が
+`grpclib.exceptions.GRPCError(status=Status.FAILED_PRECONDITION)` を返す。
+
+各 example は `wait_for_ready()` という小さな inline retry helper を持ち、
+1〜2 秒間隔で 60〜120 秒間 retry する。production レベルで同じことを
+やりたい場合は、より厳密な実装例として `python/tests/e2e/*.py` の
+`wait_for_*_ready()` 系を参照。
+
+## 出力 artifact
+
+- `speaker_output.raw` — `speaker_record.py` が生成する raw float32 LE stereo
+  (48 kHz)。再生は `ffplay`:
+
+  ```bash
+  ffplay -f f32le -ar 48000 -ac 2 speaker_output.raw
+  ```
+
+## production reference
+
+examples では「最短コード」を優先しているため、以下は意図的に削っている:
+
+- argparse / CLI flag 群 (引数は module-level constant で固定)
+- Signal handler (Ctrl+C は asyncio の default 挙動に委ねる)
+- Per-frame 詳細ログ
+- WAV / MP4 header / muxing (raw float32 / 統計 print のみ)
+- TTY 制御 (Locomotion は scripted シナリオのみ、対話操作なし)
+- 厳密な error 分類 (FAILED_PRECONDITION 以外の status はそのまま投げる)
+
+完全形が必要な場合は対応する CLI / e2e を参照:
+
+| Example                    | CLI                                                         | E2E                                                                     |
+| -------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `connection_ping.py`       | [`cli/ping.py`](../src/resoio/cli/ping.py)                  | [`tests/e2e/connection.py`](../tests/e2e/connection.py)                 |
+| `camera_view.py`           | [`cli/record.py`](../src/resoio/cli/record.py) (video 経路) | [`tests/e2e/camera_stream.py`](../tests/e2e/camera_stream.py)           |
+| `speaker_record.py`        | [`cli/record.py`](../src/resoio/cli/record.py) (audio 経路) | [`tests/e2e/speaker_record.py`](../tests/e2e/speaker_record.py)         |
+| `microphone_send.py`       | [`cli/mic.py`](../src/resoio/cli/mic.py)                    | [`tests/e2e/mic_send.py`](../tests/e2e/mic_send.py)                     |
+| `locomotion_drive.py`      | [`cli/locomotion.py`](../src/resoio/cli/locomotion.py)      | [`tests/e2e/locomotion.py`](../tests/e2e/locomotion.py)                 |
+| `display_config.py`        | [`cli/display.py`](../src/resoio/cli/display.py)            | [`tests/e2e/display_resolution.py`](../tests/e2e/display_resolution.py) |
+| `manipulation_grab.py`     | [`cli/manipulate.py`](../src/resoio/cli/manipulate.py)      | [`tests/e2e/manipulation.py`](../tests/e2e/manipulation.py)             |
+| `world_browse.py`          | [`cli/world.py`](../src/resoio/cli/world.py)                | [`tests/e2e/world.py`](../tests/e2e/world.py)                           |
+| `context_menu_interact.py` | [`cli/context_menu.py`](../src/resoio/cli/context_menu.py)  | [`tests/e2e/context_menu.py`](../tests/e2e/context_menu.py)             |
+| `dash_navigate.py`         | [`cli/dash.py`](../src/resoio/cli/dash.py)                  | [`tests/e2e/dash.py`](../tests/e2e/dash.py)                             |
+| `inventory_manage.py`      | [`cli/inventory.py`](../src/resoio/cli/inventory.py)        | [`tests/e2e/inventory.py`](../tests/e2e/inventory.py)                   |
+| `cursor_move.py`           | [`cli/cursor.py`](../src/resoio/cli/cursor.py)              | [`tests/e2e/cursor.py`](../tests/e2e/cursor.py)                         |

resonite_io-0.1.0/examples/camera_view.py

@@ -0,0 +1,86 @@
+"""Minimal Camera stream example.
+
+Streams RGBA frames for DURATION_S seconds, then prints the achieved
+fps and basic luminance statistics of the final frame. No frames are
+written to disk; numpy is the only non-stdlib dependency. Assumes a
+Resonite client with the ResoniteIO mod loaded is running on the host.
+
+Run from inside the dev container:
+
+    uv run python python/examples/camera_view.py
+"""
+
+import asyncio
+import time
+
+import grpclib.exceptions
+import numpy as np
+from grpclib.const import Status
+
+from resoio import CameraClient, Frame
+
+SOCKET_PATH: str | None = None
+DURATION_S = 5.0
+WIDTH = 640
+HEIGHT = 480
+# fps_limit caps server emission so this demo does not burn CPU
+# rendering at the engine's native framerate.
+FPS_LIMIT = 30.0
+READY_TIMEOUT_S = 120.0
+READY_INTERVAL_S = 2.0
+
+
+async def wait_for_ready() -> None:
+    """Block until the Camera bridge yields a frame.
+
+    Cold-boot gap between UDS bind and LocalUser/FocusedWorld attach
+    surfaces as FAILED_PRECONDITION; retry until ``READY_TIMEOUT_S``.
+    """
+    deadline = time.monotonic() + READY_TIMEOUT_S
+    while True:
+        try:
+            async with CameraClient(SOCKET_PATH) as cam:
+                async for _ in cam.stream(1, 1, 1.0):
+                    return
+        except grpclib.exceptions.GRPCError as e:
+            if e.status != Status.FAILED_PRECONDITION:
+                raise
+            if time.monotonic() > deadline:
+                raise TimeoutError(
+                    f"Camera did not become ready in {READY_TIMEOUT_S:.0f}s"
+                ) from e
+            await asyncio.sleep(READY_INTERVAL_S)
+
+
+async def main() -> None:
+    await wait_for_ready()
+    count = 0
+    last: Frame | None = None
+    t0 = 0.0
+    elapsed = 0.0
+    async with CameraClient(SOCKET_PATH) as client:
+        async for frame in client.stream(WIDTH, HEIGHT, FPS_LIMIT):
+            if count == 0:
+                t0 = time.monotonic()
+            last = frame
+            count += 1
+            elapsed = time.monotonic() - t0
+            if elapsed >= DURATION_S:
+                break
+
+    fps = count / elapsed if elapsed > 0 else 0.0
+    print(f"frames={count} elapsed_s={elapsed:.3f} fps={fps:.2f}")
+    if last is not None:
+        # frame.pixels is a read-only RGBA8 view; row 0 is the image
+        # top. astype(float32) makes a writable copy for arithmetic.
+        rgb = last.pixels[..., :3].astype(np.float32)
+        lum = 0.299 * rgb[..., 0] + 0.587 * rgb[..., 1] + 0.114 * rgb[..., 2]
+        print(
+            f"shape={last.pixels.shape} dtype={last.pixels.dtype} "
+            f"lum_min={lum.min():.2f} lum_max={lum.max():.2f} "
+            f"lum_mean={lum.mean():.2f}"
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

resonite_io-0.1.0/examples/connection_ping.py

@@ -0,0 +1,66 @@
+"""Minimal Connection.Ping example.
+
+Sends a single ping over the Resonite IO UDS and prints the server
+timestamp plus the measured round-trip time. Assumes a Resonite client
+with the ResoniteIO mod loaded is running on the host.
+
+Run from inside the dev container:
+
+    uv run python python/examples/connection_ping.py
+"""
+
+import asyncio
+import time
+
+import grpclib.exceptions
+from grpclib.const import Status
+
+from resoio import ConnectionClient
+
+SOCKET_PATH: str | None = None
+MESSAGE = "hello"
+READY_TIMEOUT_S = 60.0
+READY_INTERVAL_S = 2.0
+
+
+async def wait_for_ready() -> None:
+    """Block until Connection.Ping returns OK.
+
+    During cold boot the UDS may be bound before the engine is fully
+    ready, in which case the server replies with FAILED_PRECONDITION.
+    Retry until ``READY_TIMEOUT_S`` elapses.
+    """
+    deadline = time.monotonic() + READY_TIMEOUT_S
+    while True:
+        try:
+            async with ConnectionClient(SOCKET_PATH) as client:
+                await client.ping("ready?")
+            return
+        except grpclib.exceptions.GRPCError as e:
+            if e.status != Status.FAILED_PRECONDITION:
+                raise
+            if time.monotonic() > deadline:
+                raise TimeoutError(
+                    f"Connection did not become ready in {READY_TIMEOUT_S:.0f}s"
+                ) from e
+            await asyncio.sleep(READY_INTERVAL_S)
+
+
+async def main() -> None:
+    await wait_for_ready()
+    async with ConnectionClient(SOCKET_PATH) as client:
+        # monotonic_ns is immune to wall-clock jumps (NTP step / DST)
+        # that would otherwise produce negative or inflated RTTs.
+        t0 = time.monotonic_ns()
+        resp = await client.ping(MESSAGE)
+        t1 = time.monotonic_ns()
+    rtt_ms = (t1 - t0) / 1e6
+    print(
+        f"message={resp.message} "
+        f"server_unix_nanos={resp.server_unix_nanos} "
+        f"rtt_ms={rtt_ms:.3f}"
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())