socialrobot 0.2.0__tar.gz

socialrobot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hung-Chun Chang (MEME — Social Robot Platform)
+
+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.

socialrobot-0.2.0/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: socialrobot
+Version: 0.2.0
+Summary: Python runtime client for the Social Robot Platform — connect a robot body (NAO, Pi, any Python process) to a live session and drive it.
+Author-email: Hung-Chun Chang <jonathanchang9@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://sociallab.duckdns.org/ntu_social_robot/
+Project-URL: Repository, https://github.com/hungchunchang/srdp
+Project-URL: Issues, https://github.com/hungchunchang/srdp/issues
+Keywords: social robot,robotics,wizard-of-oz,woz,kebbi,nao,hri,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24
+Requires-Dist: websockets>=11
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# socialrobot — Social Robot Platform Python SDK
+
+把一個**機器人身體**（NAO、Raspberry Pi、任何 Python 程式）接上平台的 live session：
+meme 是大腦，你的程式是身體。負責驅動、監看、以及把外部系統接成中斷條件。
+
+> **角色設計不在這裡做**——那是網頁編輯器 canvas 的工作。詳見下方
+> 「角色設計請用網頁編輯器」。
+
+> 這個目錄同步鏡像到公開 repo [github.com/hungchunchang/srdp](https://github.com/hungchunchang/srdp)（`main` 分支），供 PyPI 套件頁與外部使用者參考；開發仍在這個 monorepo 的 `sdk/` 進行，鏡像不接受直接 PR。
+
+## 在哪裡用？怎麼用？
+
+**在你自己的電腦（或任何伺服器/CI）跑，不是在網頁裡跑。** 流程：
+
+1. **安裝**（任何 Python ≥3.10 環境）：
+
+   ```bash
+   pip install socialrobot    # PyPI
+   pip install -e sdk/        # 或從 repo checkout 安裝
+   ```
+
+   > 安裝名稱和 import 名稱都是 `socialrobot`（下面所有範例都是）。
+   >
+   > ⚠️ **不要 `pip install srdp`。** PyPI 上的 `srdp` 是一個無關的專案（Single Repo Data Platform），不是這個 SDK，照打會裝到別人的程式。
+
+2. **取得憑證**——擇一：
+   - **API key（建議）**：登入網頁 → 右上角使用者設定 → API Key → 產生。
+     `srk_` 開頭、只顯示一次，只能存取**你自己**帳號的資源。
+   - 或直接用 email + password（SDK 會替你登入換 JWT）。該 JWT 預設只有 60 分鐘壽命，
+     但 `SocialRobotClient` 會在收到 401 時，用登入時一併拿到的 refresh cookie 靜默換發
+     新 token 再重送原請求，所以長時間執行的 `RobotSession` 不必自行處理過期。
+     **只在台大網段（或 VPN）內有效**：密碼登入拿到的是網頁 token，校外的請求與換發
+     都會被拒（`ntu_network_only`，#830）；開了兩步驟驗證的帳號還要附 30 秒內的驗證碼。
+     在校外、或寫成長期跑的程式，請用 API key。
+
+3. **指向平台**——`SocialRobotClient(base_url=…)` **必填指向你自己的部署**：
+   - 部署環境：`https://sociallab.duckdns.org/ntu_social_robot/api/v1`
+   - 本機開發：`http://localhost:6868/api/v1`
+   - ⚠️ 不傳 `base_url` 時預設是 `http://localhost:6868/api/v1`（只適合本機）；
+     用 `pip install` 在別台機器上跑時，務必傳入你部署的 URL。
+
+4. **在網頁編輯器把角色設計好**，然後用這個 SDK 把機器人身體接上去：
+   `RobotSession` 連進該角色的 live session，逐則 `state_update` render 到你的
+   硬體上（TTS、`motor_keyframes`、表情），並把感測器／ASR 事件送回平台。
+   完整範例見 `examples/nao_meme_bridge.py`。
+
+## 角色設計請用網頁編輯器（Builder DSL 已退出公開 API）
+
+**這個 SDK 不再提供「用程式碼建角色」的公開介面。** 角色設計請在網頁編輯器
+的 canvas 上進行。原因很單純：Builder 腳本寫完仍然要 `deploy()` 把結果上傳
+到後端，跟在 canvas 上編輯的是同一份資料、同一套 REST API，所以它給設計師的
+好處等於零，而真正持續維護、持續長功能的介面是 canvas。
+
+`socialrobot.builder` 這個模組仍然留在 repo 裡、也仍然 import 得到，但它現在
+的定位是**平台自己的測試／佈建基礎設施**：`server/scripts/seed_*.py`
+（Museum、Origami、搶答主持人、聽力認知搶答主持人）和約 15 支
+`server/scripts/e2e_*.py` 都用它產生 fixture 角色。它不在 `__all__` 裡、不在
+本文件裡、也不在套件描述裡，對外**沒有相容性承諾**——請不要在它上面開發新東西。
+
+需要用程式產生角色的話，直接打 REST API（就是 canvas 用的那套）。
+
+## Runtime client — 驅動正在跑的機器人（這才是這個 SDK 的用途）
+
+```python
+import asyncio
+from socialrobot import RobotSession
+
+async def main():
+    async with await RobotSession.start(client, "我的導覽員") as s:
+        await s.send_face(embedding=[0.1] * 128)          # 模擬鏡頭
+        ev = await s.expect(state="UI", timeout=10)        # 等 ask_name UI
+        await s.send_event("UI_INPUT", {"variable": "name", "value": "小明"})
+        await s.expect(state="SPEAKING", text="小明", timeout=20)
+
+asyncio.run(main())
+```
+
+## 外部系統整合 — 把 API 結果變成中斷條件
+
+**Inbound**（你的程式推進來）——不需要 robot WS，純 HTTP：
+
+```python
+for sess in client.list_sessions():                # 只看得到自己的機器人
+    client.inject(sess["session_id"],
+                  event="order_ready",             # 觸發 OnSensor("order_ready") hook
+                  variables={"yolo_result": "1"})  # 餵 Switch / {{var}} 模板
+```
+
+**Outbound — 後端替你輪詢/訂閱**（掛在節點上的 hook）：
+
+```python
+waiting = Script("等待製作", loop=True, hooks=[
+    # HTTP 輪詢
+    OnApiPoll("https://your-service/jobs/123",
+              path="data.status", equals="done", every=2.0,
+              write_to="job_status", goto="完成播報"),
+    # 或 WebSocket 串流（後端持續訂閱外部 feed）
+    OnWebSocket("wss://your-service/jobs/123/stream",
+                path="status", equals="done",
+                subscribe={"action": "subscribe"},   # 連上後送一次（可省）
+                write_to="job_status", goto="完成播報"),
+])
+```
+
+**Inbound 串流**——高頻推送時用持久 WS（取代一次一個 `inject`）：
+
+```python
+async with await client.open_stream(session_id) as stream:
+    await stream.send(variables={"price": 42})     # → VARIABLE switch
+    await stream.send(event="order_ready")         # → OnSensor hook
+```
+
+注意：有台詞的 loop 在播台詞時一直處於 SPEAKING，`OnSensor` / `OnFace` 會被延後，
+補送時機是**這一輪台詞播完回捲的那一刻**（2026-08 起；在那之前是永遠不觸發），所以
+最慢會晚一輪才離開節點。要求「按下去就立刻打斷」的等待節點（例如搶答）仍請用**無台詞
+的 loop**。`OnWs`（控制面板／外部程式的推送）以及後端自己輪詢的 `OnApiPoll` /
+`OnWebSocket` / `OnTimeout` / `OnVision` / `OnSchedule` 不受此限，隨時都會立刻打斷。
+
+## 自訂視覺模型
+
+上傳自己的分類/偵測模型（`.onnx` / `.pt` / `.tflite` …），掛成 `OnVision`
+中斷條件，讓機器人「看到某個標籤 → 換節點」：
+
+```python
+model = client.upload_vision_model("origami_step.onnx", name="摺紙判斷",
+                                   model_type="onnx", labels=["step1", "step2"])
+step2 = Script("步驟2", loop=True, lines=[Say("把紙對折")], hooks=[
+    OnVision(model["id"], fire_on_label="step2", threshold=0.7, goto=correct_node),
+])
+```
+
+節點開著時後端持續對機器人鏡頭的畫面跑模型，標籤信心值過 threshold 就跳。
+Teachable Machine 匯出的 `.tflite` 可直接上傳。
+
+同一個模型猜每一步時，相鄰步驟長得像，前幾步的機率會一直搶走答案。`OnVision`
+的 `allowed_labels` 讓這一步只在指定標籤裡挑最高分並重新算比例（step1–3 的機率被忽略）：
+
+```python
+step4 = Script("步驟4", loop=True, lines=[Say("把角往內折")], hooks=[
+    OnVision(model["id"], fire_on_label="step4", threshold=0.7, goto=step5,
+             allowed_labels=["step3", "step4"]),   # 觸發標籤一定在名單內
+])
+```
+
+名單裡至少要留一個不會觸發的標籤（這裡是 `step3`）——只剩觸發標籤的名單不管鏡頭看到什麼都會立刻觸發，後端會拒收並改回全部允許。同一步的所有 `OnVision` 共用一份名單（取聯集）；不給就是全部允許。
+
+## 已驗證的環境
+
+從一般使用者環境（容器外的 venv/conda）對 localhost 與公開 prod URL 全程
+驗證過：登入、DSL deploy、WS runtime、HTTP/WS inject。`make e2e-sdk` 是
+完整迴歸（HTTP poll、WS subscribe、HTTP inject、WS stream、vision 全涵蓋）。
+
+## MCP server (drive the platform from a terminal agent)
+
+`socialrobot.mcp_server` exposes the SDK as [MCP](https://modelcontextprotocol.io)
+tools, so an agent (Claude Code, etc.) can run the platform conversationally:
+
+| tool | does |
+|---|---|
+| `list_characters` | your characters (id/name/public) |
+| `list_sessions` | running robot sessions to inject into |
+| `inject_event` | push an event/variables to a live session — `buzz` `{winner}`, `judged` `{result}`, `next_question` `{answer, clip_url}` |
+| `upload_media` | upload an audio/video clip → `{url, signed_url}` |
+| `get_scripts` | read a workflow's WoZ lines (incl. `audio_clip_url`) |
+
+Install + register with Claude Code:
+
+```bash
+pip install "socialrobot[mcp]"   # or from a checkout: pip install -e "sdk/[mcp]"
+                                 # NOT `pip install srdp` — that PyPI name is an unrelated project
+claude mcp add socialrobot \
+  -e SOCIALROBOT_API_KEY=srk_… \
+  -e SOCIALROBOT_BASE_URL=https://sociallab.duckdns.org/ntu_social_robot/api/v1 \
+  -- socialrobot-mcp
+```
+
+Auth via `SOCIALROBOT_API_KEY` (an `srk_` developer key — mint in 個人設定 → API key)
+or `SOCIALROBOT_EMAIL` + `SOCIALROBOT_PASSWORD` (the latter only from the NTU network:
+a password login is a web session, refused elsewhere with `ntu_network_only`). The key lives only in the MCP
+process's env, never in tool arguments.

socialrobot-0.2.0/README.md

@@ -0,0 +1,180 @@
+# socialrobot — Social Robot Platform Python SDK
+
+把一個**機器人身體**（NAO、Raspberry Pi、任何 Python 程式）接上平台的 live session：
+meme 是大腦，你的程式是身體。負責驅動、監看、以及把外部系統接成中斷條件。
+
+> **角色設計不在這裡做**——那是網頁編輯器 canvas 的工作。詳見下方
+> 「角色設計請用網頁編輯器」。
+
+> 這個目錄同步鏡像到公開 repo [github.com/hungchunchang/srdp](https://github.com/hungchunchang/srdp)（`main` 分支），供 PyPI 套件頁與外部使用者參考；開發仍在這個 monorepo 的 `sdk/` 進行，鏡像不接受直接 PR。
+
+## 在哪裡用？怎麼用？
+
+**在你自己的電腦（或任何伺服器/CI）跑，不是在網頁裡跑。** 流程：
+
+1. **安裝**（任何 Python ≥3.10 環境）：
+
+   ```bash
+   pip install socialrobot    # PyPI
+   pip install -e sdk/        # 或從 repo checkout 安裝
+   ```
+
+   > 安裝名稱和 import 名稱都是 `socialrobot`（下面所有範例都是）。
+   >
+   > ⚠️ **不要 `pip install srdp`。** PyPI 上的 `srdp` 是一個無關的專案（Single Repo Data Platform），不是這個 SDK，照打會裝到別人的程式。
+
+2. **取得憑證**——擇一：
+   - **API key（建議）**：登入網頁 → 右上角使用者設定 → API Key → 產生。
+     `srk_` 開頭、只顯示一次，只能存取**你自己**帳號的資源。
+   - 或直接用 email + password（SDK 會替你登入換 JWT）。該 JWT 預設只有 60 分鐘壽命，
+     但 `SocialRobotClient` 會在收到 401 時，用登入時一併拿到的 refresh cookie 靜默換發
+     新 token 再重送原請求，所以長時間執行的 `RobotSession` 不必自行處理過期。
+     **只在台大網段（或 VPN）內有效**：密碼登入拿到的是網頁 token，校外的請求與換發
+     都會被拒（`ntu_network_only`，#830）；開了兩步驟驗證的帳號還要附 30 秒內的驗證碼。
+     在校外、或寫成長期跑的程式，請用 API key。
+
+3. **指向平台**——`SocialRobotClient(base_url=…)` **必填指向你自己的部署**：
+   - 部署環境：`https://sociallab.duckdns.org/ntu_social_robot/api/v1`
+   - 本機開發：`http://localhost:6868/api/v1`
+   - ⚠️ 不傳 `base_url` 時預設是 `http://localhost:6868/api/v1`（只適合本機）；
+     用 `pip install` 在別台機器上跑時，務必傳入你部署的 URL。
+
+4. **在網頁編輯器把角色設計好**，然後用這個 SDK 把機器人身體接上去：
+   `RobotSession` 連進該角色的 live session，逐則 `state_update` render 到你的
+   硬體上（TTS、`motor_keyframes`、表情），並把感測器／ASR 事件送回平台。
+   完整範例見 `examples/nao_meme_bridge.py`。
+
+## 角色設計請用網頁編輯器（Builder DSL 已退出公開 API）
+
+**這個 SDK 不再提供「用程式碼建角色」的公開介面。** 角色設計請在網頁編輯器
+的 canvas 上進行。原因很單純：Builder 腳本寫完仍然要 `deploy()` 把結果上傳
+到後端，跟在 canvas 上編輯的是同一份資料、同一套 REST API，所以它給設計師的
+好處等於零，而真正持續維護、持續長功能的介面是 canvas。
+
+`socialrobot.builder` 這個模組仍然留在 repo 裡、也仍然 import 得到，但它現在
+的定位是**平台自己的測試／佈建基礎設施**：`server/scripts/seed_*.py`
+（Museum、Origami、搶答主持人、聽力認知搶答主持人）和約 15 支
+`server/scripts/e2e_*.py` 都用它產生 fixture 角色。它不在 `__all__` 裡、不在
+本文件裡、也不在套件描述裡，對外**沒有相容性承諾**——請不要在它上面開發新東西。
+
+需要用程式產生角色的話，直接打 REST API（就是 canvas 用的那套）。
+
+## Runtime client — 驅動正在跑的機器人（這才是這個 SDK 的用途）
+
+```python
+import asyncio
+from socialrobot import RobotSession
+
+async def main():
+    async with await RobotSession.start(client, "我的導覽員") as s:
+        await s.send_face(embedding=[0.1] * 128)          # 模擬鏡頭
+        ev = await s.expect(state="UI", timeout=10)        # 等 ask_name UI
+        await s.send_event("UI_INPUT", {"variable": "name", "value": "小明"})
+        await s.expect(state="SPEAKING", text="小明", timeout=20)
+
+asyncio.run(main())
+```
+
+## 外部系統整合 — 把 API 結果變成中斷條件
+
+**Inbound**（你的程式推進來）——不需要 robot WS，純 HTTP：
+
+```python
+for sess in client.list_sessions():                # 只看得到自己的機器人
+    client.inject(sess["session_id"],
+                  event="order_ready",             # 觸發 OnSensor("order_ready") hook
+                  variables={"yolo_result": "1"})  # 餵 Switch / {{var}} 模板
+```
+
+**Outbound — 後端替你輪詢/訂閱**（掛在節點上的 hook）：
+
+```python
+waiting = Script("等待製作", loop=True, hooks=[
+    # HTTP 輪詢
+    OnApiPoll("https://your-service/jobs/123",
+              path="data.status", equals="done", every=2.0,
+              write_to="job_status", goto="完成播報"),
+    # 或 WebSocket 串流（後端持續訂閱外部 feed）
+    OnWebSocket("wss://your-service/jobs/123/stream",
+                path="status", equals="done",
+                subscribe={"action": "subscribe"},   # 連上後送一次（可省）
+                write_to="job_status", goto="完成播報"),
+])
+```
+
+**Inbound 串流**——高頻推送時用持久 WS（取代一次一個 `inject`）：
+
+```python
+async with await client.open_stream(session_id) as stream:
+    await stream.send(variables={"price": 42})     # → VARIABLE switch
+    await stream.send(event="order_ready")         # → OnSensor hook
+```
+
+注意：有台詞的 loop 在播台詞時一直處於 SPEAKING，`OnSensor` / `OnFace` 會被延後，
+補送時機是**這一輪台詞播完回捲的那一刻**（2026-08 起；在那之前是永遠不觸發），所以
+最慢會晚一輪才離開節點。要求「按下去就立刻打斷」的等待節點（例如搶答）仍請用**無台詞
+的 loop**。`OnWs`（控制面板／外部程式的推送）以及後端自己輪詢的 `OnApiPoll` /
+`OnWebSocket` / `OnTimeout` / `OnVision` / `OnSchedule` 不受此限，隨時都會立刻打斷。
+
+## 自訂視覺模型
+
+上傳自己的分類/偵測模型（`.onnx` / `.pt` / `.tflite` …），掛成 `OnVision`
+中斷條件，讓機器人「看到某個標籤 → 換節點」：
+
+```python
+model = client.upload_vision_model("origami_step.onnx", name="摺紙判斷",
+                                   model_type="onnx", labels=["step1", "step2"])
+step2 = Script("步驟2", loop=True, lines=[Say("把紙對折")], hooks=[
+    OnVision(model["id"], fire_on_label="step2", threshold=0.7, goto=correct_node),
+])
+```
+
+節點開著時後端持續對機器人鏡頭的畫面跑模型，標籤信心值過 threshold 就跳。
+Teachable Machine 匯出的 `.tflite` 可直接上傳。
+
+同一個模型猜每一步時，相鄰步驟長得像，前幾步的機率會一直搶走答案。`OnVision`
+的 `allowed_labels` 讓這一步只在指定標籤裡挑最高分並重新算比例（step1–3 的機率被忽略）：
+
+```python
+step4 = Script("步驟4", loop=True, lines=[Say("把角往內折")], hooks=[
+    OnVision(model["id"], fire_on_label="step4", threshold=0.7, goto=step5,
+             allowed_labels=["step3", "step4"]),   # 觸發標籤一定在名單內
+])
+```
+
+名單裡至少要留一個不會觸發的標籤（這裡是 `step3`）——只剩觸發標籤的名單不管鏡頭看到什麼都會立刻觸發，後端會拒收並改回全部允許。同一步的所有 `OnVision` 共用一份名單（取聯集）；不給就是全部允許。
+
+## 已驗證的環境
+
+從一般使用者環境（容器外的 venv/conda）對 localhost 與公開 prod URL 全程
+驗證過：登入、DSL deploy、WS runtime、HTTP/WS inject。`make e2e-sdk` 是
+完整迴歸（HTTP poll、WS subscribe、HTTP inject、WS stream、vision 全涵蓋）。
+
+## MCP server (drive the platform from a terminal agent)
+
+`socialrobot.mcp_server` exposes the SDK as [MCP](https://modelcontextprotocol.io)
+tools, so an agent (Claude Code, etc.) can run the platform conversationally:
+
+| tool | does |
+|---|---|
+| `list_characters` | your characters (id/name/public) |
+| `list_sessions` | running robot sessions to inject into |
+| `inject_event` | push an event/variables to a live session — `buzz` `{winner}`, `judged` `{result}`, `next_question` `{answer, clip_url}` |
+| `upload_media` | upload an audio/video clip → `{url, signed_url}` |
+| `get_scripts` | read a workflow's WoZ lines (incl. `audio_clip_url`) |
+
+Install + register with Claude Code:
+
+```bash
+pip install "socialrobot[mcp]"   # or from a checkout: pip install -e "sdk/[mcp]"
+                                 # NOT `pip install srdp` — that PyPI name is an unrelated project
+claude mcp add socialrobot \
+  -e SOCIALROBOT_API_KEY=srk_… \
+  -e SOCIALROBOT_BASE_URL=https://sociallab.duckdns.org/ntu_social_robot/api/v1 \
+  -- socialrobot-mcp
+```
+
+Auth via `SOCIALROBOT_API_KEY` (an `srk_` developer key — mint in 個人設定 → API key)
+or `SOCIALROBOT_EMAIL` + `SOCIALROBOT_PASSWORD` (the latter only from the NTU network:
+a password login is a web session, refused elsewhere with `ntu_network_only`). The key lives only in the MCP
+process's env, never in tool arguments.

socialrobot-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "socialrobot"
+version = "0.2.0"
+description = "Python runtime client for the Social Robot Platform — connect a robot body (NAO, Pi, any Python process) to a live session and drive it."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Hung-Chun Chang", email = "jonathanchang9@gmail.com" }]
+keywords = ["social robot", "robotics", "wizard-of-oz", "woz", "kebbi", "nao", "hri", "sdk"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Human Machine Interfaces",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.24",
+    "websockets>=11",
+]
+
+[project.optional-dependencies]
+dev = ["build>=1.0", "twine>=5.0"]
+# MCP server (socialrobot.mcp_server) — drive the platform from a terminal agent.
+# <2: mcp 2.x renamed FastMCP to MCPServer; mcp_server.py is written against 1.x.
+mcp = ["mcp>=1.0,<2"]
+
+[project.scripts]
+socialrobot-mcp = "socialrobot.mcp_server:main"
+
+[project.urls]
+Homepage = "https://sociallab.duckdns.org/ntu_social_robot/"
+Repository = "https://github.com/hungchunchang/srdp"
+Issues = "https://github.com/hungchunchang/srdp/issues"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["socialrobot*"]
+
+[tool.setuptools.package-data]
+socialrobot = ["py.typed"]

socialrobot-0.2.0/setup.cfg

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

socialrobot-0.2.0/socialrobot/__init__.py

@@ -0,0 +1,67 @@
+"""Social Robot Platform SDK — a RUNTIME client, not an authoring tool.
+
+The supported public API is the runtime half: connect a non-Android robot
+body (or any program) to a live platform session, and drive/observe it.
+
+    from socialrobot import SocialRobotClient, RobotSession
+
+`RobotSession` is how a NAO, a Raspberry Pi rig, or any Python-driven body
+participates as a robot — meme is the brain, your process is the body (see
+`examples/nao_meme_bridge.py`). `SocialRobotClient` is the authenticated REST
+client underneath it, plus the asset/session endpoints those bodies need.
+
+INTERNAL, NOT PUBLIC API — the Builder DSL (`Character`, `Script`, `Say`,
+`Agent`, `Screen`, `Identify`, hooks, …). Authoring a character is the
+WEB EDITOR's job: a Builder script still has to `deploy()` its result up to
+the backend, so it buys nothing a designer can't do on the canvas, and the
+canvas is the surface that actually gets maintained. The module stays in the
+repo because the platform's own seed scripts and ~15 e2e drivers provision
+their fixture characters with it (`server/scripts/seed_*.py`,
+`server/scripts/e2e_*.py`) — it is test/provisioning infrastructure now.
+
+Those names are still importable so that in-repo tooling keeps working, but
+they are deliberately absent from `__all__`, excluded from the documented
+surface, and carry no compatibility promise for external callers. Do not
+build anything new on them; use the web editor, or the REST API directly.
+"""
+from .builder import (
+    Agent,
+    Button,
+    Call,
+    Character,
+    Data,
+    DataSource,
+    DeployedCharacter,
+    Hook,
+    Identify,
+    Judgment,
+    Mirror,
+    Node,
+    OnApiPoll,
+    OnFace,
+    OnPlaybackDone,
+    OnSchedule,
+    OnSensor,
+    OnTimeout,
+    OnUtterance,
+    OnVision,
+    OnWebSocket,
+    OnWs,
+    Return,
+    Say,
+    Screen,
+    Script,
+    subflow,
+)
+from .client import MfaRequiredError, SocialRobotClient
+from .runtime import ExternalStream, RobotSession, SubscribeStream
+
+__version__ = "0.2.0"
+
+# The PUBLIC surface: the runtime client only. Builder DSL names are
+# imported above for in-repo tooling (seeds + e2e drivers) but are
+# deliberately NOT listed here — `__all__` is what this package promises.
+__all__ = [
+    "__version__",
+    "ExternalStream", "MfaRequiredError", "RobotSession", "SocialRobotClient", "SubscribeStream",
+]