loop-sdk 0.1.0__tar.gz

loop_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,80 @@
+# Publish loop-sdk on every version tag.
+#
+# Routing by tag name:
+#   v0.1.0          -> PyPI        (real release)
+#   v0.1.0-test     -> TestPyPI    (rehearsal)
+#
+# Versioning is tag-driven (hatch-vcs): a plain tag `vX.Y.Z` -> version `X.Y.Z`.
+# A `-test` tag is NOT a valid PEP 440 version, so the TestPyPI path overrides the
+# version with `X.Y.Z.dev<run_number>` (valid + unique per run, so re-runs don't
+# collide on TestPyPI).
+#
+# Auth uses Trusted Publishing (OIDC) — no API tokens. ONE-TIME setup: register a
+# trusted publisher on BOTH indexes (workflow=publish.yml):
+#   pypi.org      -> project loop-sdk, environment "pypi"
+#   test.pypi.org -> project loop-sdk, environment "testpypi"
+# (Before the project exists, add it as a "pending publisher".)
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  testpypi:
+    name: Publish to TestPyPI
+    if: contains(github.ref_name, '-test')
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/loop-sdk
+    permissions:
+      id-token: write           # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # hatch-vcs needs full history + tags
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Compute a valid TestPyPI version
+        id: ver
+        run: |
+          base="${GITHUB_REF_NAME#v}"        # strip leading v
+          base="${base%%-test*}"             # strip the -test suffix
+          echo "version=${base}.dev${{ github.run_number }}" >> "$GITHUB_OUTPUT"
+      - name: Build (version overridden for TestPyPI)
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.ver.outputs.version }}
+        run: uv build
+      - name: Check package metadata
+        run: uvx twine check dist/*
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    name: Publish to PyPI
+    if: ${{ !contains(github.ref_name, '-test') }}
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/loop-sdk
+    permissions:
+      id-token: write           # OIDC token for Trusted Publishing
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0          # hatch-vcs needs full history + tags
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Check package metadata
+        run: uvx twine check dist/*
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

loop_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.pyright/

loop_sdk-0.1.0/Makefile

@@ -0,0 +1,49 @@
+SDK_DIR := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+PROTO_DIR := $(SDK_DIR)/proto
+PY_PACKAGE ?= loop_sdk
+# The vendored contract is owned by the foundation module; its package root is
+# loop/foundation/source. Generated Python lands directly under gen/vN.
+PROTO_PACKAGE_ROOT ?= loop/foundation/source
+GEN_DIR ?= $(SDK_DIR)/src/$(PY_PACKAGE)/gen
+# Generation-only Buf config. buf.yaml keeps the module root at proto/ so
+# lint/breaking enforce package-mirrored IDL paths. Python generation uses the
+# contract owner directory as its root so generated modules land directly under
+# gen/vN instead of gen/loop/foundation/source/vN.
+GEN_BUF_CONFIG ?= {"version":"v2","modules":[{"path":"$(PROTO_PACKAGE_ROOT)"}]}
+GEN_BUF_TEMPLATE ?= {"version":"v2","clean":true,"plugins":[{"remote":"buf.build/protocolbuffers/python","out":"$(GEN_DIR)"},{"remote":"buf.build/protocolbuffers/pyi","out":"$(GEN_DIR)"},{"remote":"buf.build/grpc/python","out":"$(GEN_DIR)"}]}
+
+# Prerequisites:
+#   - buf CLI on PATH (https://buf.build/docs/installation) — runs codegen via
+#     remote plugins, lint, and breaking-change detection.
+#   - uv (provides `uvx` to run protoletariat in an isolated env). protoletariat
+#     rewrites absolute proto imports into relative ones; it is run isolated
+#     because it caps protobuf <6 and must not touch the project runtime.
+PROTOLETARIAT_SPEC ?= protoletariat
+
+# Upstream contract location, for drift/breaking checks against the source of truth.
+UPSTREAM_PROTO ?= ../loop/module/foundation/proto
+
+.PHONY: proto proto-gen proto-lint proto-breaking proto-sync
+
+## proto: lint then regenerate stubs (full pipeline)
+proto: proto-lint proto-gen
+
+## proto-gen: regenerate Python stubs for the vendored contract
+proto-gen:
+	cd "$(PROTO_DIR)" && buf generate --config '$(GEN_BUF_CONFIG)' --template '$(GEN_BUF_TEMPLATE)'
+	cd "$(PROTO_DIR)" && buf build --config '$(GEN_BUF_CONFIG)' -o - | \
+		uvx --from "$(PROTOLETARIAT_SPEC)" \
+			protol --create-package --in-place --python-out "$(GEN_DIR)" raw -
+
+## proto-lint: lint the vendored .proto contract
+proto-lint:
+	cd "$(PROTO_DIR)" && buf lint
+
+## proto-breaking: fail if the vendored contract breaks wire compatibility vs the upstream foundation contract
+proto-breaking:
+	cd "$(PROTO_DIR)" && buf breaking --against "$(UPSTREAM_PROTO)"
+
+## proto-sync: refresh the vendored .proto from the upstream foundation contract
+proto-sync:
+	cp "$(UPSTREAM_PROTO)/loop/foundation/source/v1/source_ingest.proto" \
+		"$(PROTO_DIR)/loop/foundation/source/v1/source_ingest.proto"

loop_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: loop-sdk
+Version: 0.1.0
+Summary: Customer-side gRPC client SDK for the Loop Source Bus.
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.81.1
+Requires-Dist: protobuf>=7.35.1
+Requires-Dist: pydantic-settings>=2.13.0
+Requires-Dist: pydantic>=2.12.0

loop_sdk-0.1.0/README.md

@@ -0,0 +1,152 @@
+# loop-sdk
+
+[English](#loop-sdk) · [한국어](#한국어)
+
+Stream your robot onto the Loop **Source Bus** with one class — `connect`,
+`send` each tick, `disconnect`.
+
+```python
+import time
+
+from loop_sdk import RobotStepSender, RobotConfig, RobotConfigOptions
+
+control_hz = 20   # the control rate; updated when Loop negotiates one below
+
+# At Open, Loop picks a config from `options`; apply it to your robot and confirm.
+# (robot-control-interface assigns this to env.control_hz.)
+def apply_robot_config(cfg: RobotConfig) -> RobotConfig | None:
+    global control_hz
+    control_hz = cfg.control_hz
+    return cfg
+
+# loop_addr defaults to the LOOP_ADDR env var (else localhost:50051),
+# source_id to "robot-step". Advertise the configs you can open with.
+sender = RobotStepSender(
+    options=RobotConfigOptions(control_hz=(10, 20, 30), action_space=("target_cartesian_delta",)),
+    apply_config=apply_robot_config,
+)
+
+sender.connect()
+while running:                                # your control loop
+    t_capture_us = time.time_ns() // 1_000    # capture time, epoch microseconds
+    # A nested dict — the SDK flattens it to dotted channel keys. The FIRST send
+    # fixes the layout, so this first frame must be complete. A numeric list is ONE
+    # vector channel (robot0.action.joint_position); build key[0], key[1], … yourself
+    # for per-index scalar channels.
+    sender.send(t_capture_us, {
+        "robot0": {
+            "observation": {"robot_state": {"joint_positions": [0.12, -0.34, 1.57], "gripper": 0.80}},
+            "action": {"joint_position": [0.13, -0.33, 1.55]},
+            "policy_action": [0.01, -0.02, 0.00],   # or None when teleop is driving
+        },
+    })
+    wait_for_next_tick(control_hz)            # your loop's rate control — send does not pace
+sender.disconnect()                           # on shutdown (not for pauses)
+```
+
+`RobotStepSender` owns the connection, sequence numbering, config validation,
+retries, and reconnection. The **first `send` declares the layout** from its keys —
+no separate step — so make the first frame complete (a channel you'll only
+*sometimes* have should still appear, as `None`). A key you omit — or set to
+`None` — means "no reading this tick". At Open the SDK validates Loop's config
+selection against your `options` and calls `apply_config`. `send` never blocks and
+**does not pace your loop** — your control loop owns its cadence (the negotiated
+`control_hz`); the SDK just streams. The operator — not you — starts and stops
+recording.
+
+Want the config negotiated *before* you start sending (e.g. apply `control_hz`
+first)? Call `sender.declare(channels)` once after `connect()`.
+
+## Install
+
+```bash
+pip install loop-sdk      # Python ≥ 3.10
+```
+
+## Examples
+
+[`examples/`](examples/): `quickstart.py` (start here) · `robot_step_producer.py`
+(full robot-control-interface producer + config negotiation) ·
+`policy_action_consumer.py` (read actions back out).
+
+## Lower level
+
+`RobotStepSender` is robot-only and opinionated. For per-channel metadata
+(`role` / `unit` / `rot_type`) or non-robot source kinds (tactile, marker), use
+`loop_sdk.SourceProducer` / `SourceConsumer` directly — the high-level sender is
+built on them. Internals and dev setup are in [`docs/`](docs/).
+
+---
+
+<a id="한국어"></a>
+
+# loop-sdk (한국어)
+
+[English](#loop-sdk) · [한국어](#한국어)
+
+로봇을 Loop **Source Bus**로 스트리밍 — 클래스 하나로 `connect`, 매 tick `send`, `disconnect`.
+
+```python
+import time
+
+from loop_sdk import RobotStepSender, RobotConfig, RobotConfigOptions
+
+control_hz = 20   # 제어율; 아래에서 Loop가 협상하면 갱신됨
+
+# Open 시 Loop가 `options` 중 하나를 고름 → 로봇에 적용하고 확인 반환.
+# (robot-control-interface는 이를 env.control_hz에 대입.)
+def apply_robot_config(cfg: RobotConfig) -> RobotConfig | None:
+    global control_hz
+    control_hz = cfg.control_hz
+    return cfg
+
+# loop_addr 기본값 = LOOP_ADDR 환경변수(없으면 localhost:50051), source_id 기본값 = "robot-step".
+# 열 수 있는 config들을 광고.
+sender = RobotStepSender(
+    options=RobotConfigOptions(control_hz=(10, 20, 30), action_space=("target_cartesian_delta",)),
+    apply_config=apply_robot_config,
+)
+
+sender.connect()
+while running:                                # 네 제어 루프
+    t_capture_us = time.time_ns() // 1_000    # 캡처 시각, epoch 마이크로초
+    # 중첩 dict → SDK가 점-키로 평탄화. 첫 send가 레이아웃을 고정하므로 첫 프레임은 완전해야.
+    # 숫자 리스트는 벡터 채널 하나(robot0.action.joint_position); per-index 스칼라 채널을
+    # 원하면 key[0], key[1], … 를 직접 만들어 넣을 것.
+    sender.send(t_capture_us, {
+        "robot0": {
+            "observation": {"robot_state": {"joint_positions": [0.12, -0.34, 1.57], "gripper": 0.80}},
+            "action": {"joint_position": [0.13, -0.33, 1.55]},
+            "policy_action": [0.01, -0.02, 0.00],   # teleop이 몰면 None
+        },
+    })
+    wait_for_next_tick(control_hz)            # 네 루프의 rate control — send는 페이싱 안 함
+sender.disconnect()                           # 종료 시에만 (일시정지엔 금지)
+```
+
+`RobotStepSender`가 연결·시퀀스 번호·config 검증·재시도·재연결을 떠안습니다. **첫 `send`가
+키에서 레이아웃을 선언**(별도 단계 없음)하므로 첫 프레임은 완전해야 합니다(가끔만 있는 채널도
+`None`으로 포함). 키를 빼거나 `None`으로 두면 "이번 tick 무판독"입니다. Open 시 SDK가 Loop의
+config 선택을 `options`에 대조 검증하고 `apply_config`를 호출합니다. `send`는 블로킹하지 않고
+**루프를 페이싱하지도 않습니다** — 케이던스는 네 제어 루프 몫(협상된 `control_hz`)이고 SDK는
+스트리밍만 합니다. 녹화 시작·정지는 네가 아니라 operator가 합니다.
+
+스트리밍 *전에* config를 협상하고 싶다면(예: `control_hz`를 먼저 적용) `connect()` 뒤에
+`sender.declare(channels)`를 한 번 호출하세요.
+
+## 설치
+
+```bash
+pip install loop-sdk      # Python ≥ 3.10
+```
+
+## 예제
+
+[`examples/`](examples/): `quickstart.py`(여기서 시작) · `robot_step_producer.py`(전체
+robot-control-interface 생산자 + config 협상) · `policy_action_consumer.py`(액션 되읽기).
+
+## 저수준
+
+`RobotStepSender`는 로봇 전용이고 의견이 강합니다. 채널별 메타(`role`/`unit`/`rot_type`)나
+비로봇 소스 종류(tactile, marker)가 필요하면 `loop_sdk.SourceProducer` / `SourceConsumer`를
+직접 쓰세요 — 고수준 sender가 그 위에 얹혀 있습니다. 내부 구조와 개발 셋업은 [`docs/`](docs/).

loop_sdk-0.1.0/docs/data_model/README.md

@@ -0,0 +1,66 @@
+# Robot data model — real examples & visualizer
+
+Investigation backing `docs/spec_discrepancies.md` §A: what an SDK should stream
+per tick (data plane / A1) vs declare once (control plane / A2). Grounded in
+**real episodes** from three robot classes — no synthetic data.
+
+## Source episodes (real)
+
+Full originals stored outside this repo at
+`/home/suchae/inference_workspace/product/recorder_data_samples/`
+(override with the `RECORDER_DATA_SAMPLES` env var):
+
+| dataset | format | rows | robot | DOF | notes |
+|---|---|---|---|---|---|
+| `franka/` | recorder parquet | 909 | `franka` (`y_frame`, robotiq) | 7×2 | from `s3://configint-raw/recorder/v2.8.9/…/17/00` |
+| `vega/` | recorder parquet | 1125 | `vega-1-pro` (torso_frame) | 7×2 | from `s3://configint-raw/recorder/2.8.1/…/02/00` |
+| `unitree_g1/sonic-sample-data/` | LeRobot v2.1 / GR00T | 8697/5084 | `unitree_g1` humanoid | 43 | G1 + "sonic" teleop, built dataset |
+
+- **recorder** episodes: `data.parquet` (flat dotted columns from
+  `recorder/state_action_recorder.py`'s `pd.json_normalize`) + `tasks.jsonl`
+  session metadata. Names *fields* (`joint_positions[7]`), no per-scalar names, no
+  units, no group/rotation metadata.
+- **LeRobot/GR00T** episode: per-feature vectors + `meta/info.json`
+  (per-dim names, dtype, shape), `meta/modality.json` (named vector-slice groups +
+  `rotation_type`), `meta/episodes_stats.jsonl` (per-dim min/max/mean/std). This
+  format **already ships** the §A2 metadata, so it anchors the v2 proposal.
+
+## Files here
+
+- `real_examples.json` — extracted example set (real values only): per dataset,
+  the source metadata + a unified channel list (each channel tagged with the
+  **provenance** of every attribute) + subsampled per-tick real values.
+- `visualizer.html` — self-contained, data embedded inline. Open in a browser.
+- `extract_real_examples.py` — reads the three episodes from
+  `recorder_data_samples/` and writes `real_examples.json`.
+- `build_visualizer.py` — embeds `real_examples.json` into `visualizer.html`.
+
+## Reproduce
+
+```bash
+python3 extract_real_examples.py   # reads recorder_data_samples/{franka,vega,unitree_g1}
+python3 build_visualizer.py        # embeds real_examples.json into visualizer.html
+```
+
+## What the visualizer shows
+
+Three robots in one unified channel table. Each row = one real scalar channel; the
+left block is **real source data**, the right block is the **channel descriptor**,
+and every descriptor cell is colour-coded by provenance:
+
+- **teal `source`** — read from the dataset's own metadata (real). G1 supplies
+  names, groups, rotation types, and ranges this way.
+- **amber `inferred`** — our heuristic annotation, *not* in the source (e.g. units
+  for Franka/Vega, which carry none).
+- **faint `none` / `?`** — the source does not provide it at all.
+
+Controls: robot (Franka/Vega/G1) → source (robot0/robot1 or g1) → tick scrub/play.
+A top panel states the **proposed transfer protocol (v2)**; the summary line counts
+how many channel attributes each dataset supplies from source vs inferred — making
+the gap between the recorder format and the GR00T format explicit.
+
+> Honesty note: values and `source field` are always real. For Franka/Vega the
+> per-scalar name, group, rotation, and unit are our proposal (the source has
+> none); for G1 most of them are real (read from `info.json` / `modality.json` /
+> `episodes_stats.jsonl`). G1's `eef_state` ships 4 names for 14 dims — partial
+> name lists are marked untrusted, which is why the spec requires `len(names) == shape`.

loop_sdk-0.1.0/docs/data_model/build_descriptor.py

@@ -0,0 +1,116 @@
+"""Build a focused, toggle-able §A2 robot descriptor viewer (descriptor.html).
+
+Pick a robot (Franka / Vega / G1) and see its full proposed §A2 control-plane
+descriptor — groups + role + per-channel name/unit/rot_type/range — built from the
+real per-robot data in real_examples.json. Value colour = provenance
+(source vs inferred). Self-contained (data embedded inline).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+HERE = Path(__file__).parent
+DATA = (HERE / "real_examples.json").read_text()
+
+HTML = r"""<title>Robot descriptor (§A2) — Franka · Vega · G1</title>
+<style>
+  :root{--bg:#0f1115;--panel:#171a21;--panel2:#1d212b;--line:#2a2f3a;--ink:#e6e9ef;--mut:#9aa3b2;--faint:#6b7384;
+    --accent:#7aa2f7;--key:#2dd4bf;--prop:#f5a524;--num:#bb9af7;--warn:#f7768e}
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink);font:14px/1.6 ui-sans-serif,system-ui,-apple-system,"Apple SD Gothic Neo","Malgun Gothic",sans-serif}
+  .wrap{max-width:1080px;margin:0 auto;padding:22px 18px 60px}
+  h1{font-size:21px;margin:0 0 4px} .sub{color:var(--mut);margin:0 0 14px;font-size:13px}
+  code{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:.9em}
+  .robtabs{display:flex;gap:8px;margin:0 0 14px;flex-wrap:wrap}
+  .robtabs button{background:var(--panel);color:var(--mut);border:1px solid var(--line);border-radius:10px;padding:8px 16px;cursor:pointer;font-size:14px;font-weight:600}
+  .robtabs button.on{background:var(--accent);color:#0f1115;border-color:var(--accent)}
+  .robtabs .meta{margin-left:auto;color:var(--faint);font-size:12px;align-self:center}
+  .note{background:#1a1d25;border:1px solid var(--line);border-left:3px solid var(--prop);border-radius:8px;padding:9px 12px;font-size:12.5px;color:var(--mut);margin:0 0 12px}
+  .note b{color:var(--ink)} .note .s{color:var(--key)} .note .prop{color:var(--prop)}
+  pre.msg{background:var(--bg);border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;font-size:12px;max-height:62vh;margin:0 0 14px}
+  .msg .k{color:var(--mut)} .msg .c{color:var(--faint)} .msg .p{color:#565f70}
+  .msg .kk{color:var(--ink);font-weight:700} .msg .s{color:var(--key)} .msg .prop{color:var(--prop)}
+  .lbl{font-size:12px;color:var(--faint);font-weight:700;text-transform:uppercase;letter-spacing:.04em;margin:14px 0 6px}
+  .reqtbl{border:1px solid var(--line);border-radius:8px;overflow:hidden}
+  .reqrow{display:grid;grid-template-columns:96px 96px 1fr;gap:10px;align-items:center;padding:5px 12px;border-bottom:1px solid #20242e;font-size:12.5px}
+  .reqrow:last-child{border-bottom:0}
+  .rqb{font-size:10.5px;font-weight:700;text-align:center;padding:2px 0;border-radius:6px}
+  .rqb.must{background:#3a1620;color:#f7768e} .rqb.cond{background:#2a1d05;color:#f5a524} .rqb.opt{background:#20242e;color:#9aa3b2}
+  .rqf{font-family:ui-monospace,Menlo,monospace;color:var(--ink)} .rqd{color:var(--mut)}
+  .footnote{color:var(--faint);font-size:12px;margin-top:20px;border-top:1px solid var(--line);padding-top:12px}
+  .footnote code{color:var(--mut)}
+</style>
+<div class="wrap">
+  <h1>Robot descriptor (§A2) — control-plane blueprint</h1>
+  <p class="sub">소스가 <code>Describe</code> 때 한 번 선언하는 <b>설계도</b>의 §A2 제안형 — <b>실제 자료구조(JSON) 그대로</b>입니다. <code>channels</code>는 객체의 배열이고, <b>배열 순서가 곧 <code>values[]</code> 인덱스</b>(우측 <code>// [i]</code>). 필드명은 흰색, <b>값 색이 출처</b>를 뜻합니다: <span class="s">청록=소스 메타에서 옴(예: key=실제 컬럼명)</span> / <span class="prop">주황=우리 추론(예: unit)</span>. null인 필드(rot_type/group/range)는 객체에서 생략됩니다. (색은 표시용일 뿐 데이터에 <code>*_src</code> 같은 필드는 없습니다.)</p>
+  <div class="robtabs" id="robtabs"></div>
+  <div class="note" style="border-left-color:var(--key)"><b>핵심 원칙 — 이름은 무손실(verbatim).</b> 채널 이름은 클라이언트가 보낸 컬럼명 <b>그대로</b> 저장됩니다(예: <code>robot0.action.state.joint_positions[3]</code>). SDK가 중간을 깎지 않습니다(<code>.state.</code> 제거 금지) — 원본 복구가 보장돼야 하니까요. <b>observation/action 구분은 이름에 이미 있으니 거기엔 role을 안 씁니다.</b> 대신 <b>role</b>은 <b>로봇 경계를 실제로 넘었는지</b>로 2가지로 나눕니다 — <code>robot</code>(로봇에서 나온 측정 상태 또는 로봇에 실제 전달된 명령) / <code>aux</code>(그 외 곁다리: 실행 안 된 후보 액션·action_source·inference latency·prev_·success 등). 판별: "이 값이 로봇으로 실제 들어갔거나 로봇에서 나왔나?" 이름만으론 모르니 가치 있는 부가 필드입니다. 그 외 이름으로 복구 불가라 유용한 건 <b>unit·rot_type</b>. <code>group</code>은 선택적 묶음 태그. <b>role·rot_type은 닫힌 집합(proto enum)</b>이라 정해진 값 외엔 거부됩니다(role: robot/aux, rot_type: none/quaternion/euler/rotation_6d). <b>unit은 권장 집합 + 그 외는 경고</b>(단위는 무한하므로). 중복·불필요 채널(예: <code>action.state.*</code>가 <code>observation.state.*</code>와 동일, 한 명령의 여러 표현)은 <b>권고로 줄이되 강제로 제거하지 않습니다</b> — 클라이언트가 로깅 목적으로 보낼 수 있으니까요.</div>
+  <div class="note"><b>rot_type</b>은 3D 방향(orientation) 인코딩 표시입니다 — 사원수/오일러/6D. 1-DOF 관절각 같은 <b>스칼라 각도엔 none</b>(unit=rad만으로 충분), EE roll/pitch/yaw처럼 3채널이 한 방향이면 <code>euler</code>.</div>
+  <pre class="msg" id="desc"></pre>
+  <div class="lbl">필드별 필수도</div>
+  <div class="reqtbl">
+    <div class="reqrow"><span class="rqb must">필수</span><span class="rqf">name</span><span class="rqd">클라이언트 컬럼명 그대로(verbatim). observation/action 구분도 이름에 들어있음</span></div>
+    <div class="reqrow"><span class="rqb opt">선택</span><span class="rqf">role</span><span class="rqd">로봇 경계 기준 2분류: robot(로봇에 실제 입출력된 신호) / aux(그 외 곁다리: 미실행 후보 액션·action_source·latency·진단). 닫힌 enum</span></div>
+    <div class="reqrow"><span class="rqb must">필수</span><span class="rqf">unit</span><span class="rqd">rad · m · normalized … 한 벡터에 단위가 섞임</span></div>
+    <div class="reqrow"><span class="rqb cond">조건부 필수</span><span class="rqf">rot_type</span><span class="rqd">회전(quaternion/euler/rotation_6d) 채널일 때만. 아니면 none</span></div>
+    <div class="reqrow"><span class="rqb opt">선택</span><span class="rqf">range</span><span class="rqd">정규화·검증·이상치 (관측 min/max)</span></div>
+    <div class="reqrow"><span class="rqb opt">선택</span><span class="rqf">group</span><span class="rqd">left_leg 등 의미 묶음. 휴머노이드 슬라이싱</span></div>
+    <div class="reqrow"><span class="rqb opt">선택</span><span class="rqf">dtype</span><span class="rqd">wire는 double. int/bool/enum일 때만</span></div>
+  </div>
+  <p class="footnote">실제 에피소드(프랑카·베가=recorder, G1=LeRobot/GR00T)에서 추출. unit/rot_type은 best-effort 추론이며 <b>실제 계약은 클라이언트가 선언</b>합니다. <code>docs/spec_discrepancies.md</code> §A2.</p>
+</div>
+<script id="data" type="application/json">__DATA__</script>
+<script>
+  const DS = JSON.parse(document.getElementById('data').textContent).datasets;
+  const ROBOTS = Object.keys(DS);
+  const KOR = { franka:"프랑카", vega:"베가", g1:"G1 (휴머노이드)" };
+  const st = { rob: ROBOTS[0] };
+  const src = () => { const s=DS[st.rob].sources; return s[Object.keys(s)[0]]; };
+  const esc = s => String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;');
+
+  function groups(){ const ch=src().channels; const gs=[]; let cur=null;
+    ch.forEach((c,i)=>{ const gk=c.group||c.source_field;
+      if(!cur||cur.gk!==gk){cur={gk,label:(c.group||c.source_field),items:[]}; gs.push(cur);} cur.items.push({c,i}); });
+    return gs; }
+  const pv = (val,srcTag)=>{ if(val===null||val===undefined||val==="") return `<span class="c">none</span>`;
+    return `<span class="${srcTag==="source"?"s":"prop"}">${esc(val)}</span>`; };
+
+  // 실제 자료구조(JSON) 그대로 렌더. 필드명=흰색, 값 색=출처(청록 source / 주황 inferred).
+  // null인 필드(rot_type/group/range)는 객체에서 생략(= proto의 unset).
+  function descriptor(){
+    const ch=src().channels; const m=DS[st.rob].meta||{}; const L=[];
+    const q = s => `"${esc(s)}"`;
+    const cv = (txt, srcTag) => `<span class="${srcTag==="source"?"s":"prop"}">${txt}</span>`;
+    L.push(`<span class="p">{</span>`);
+    L.push(`  <span class="kk">"robot_class"</span>: ${cv(q(m.robot_type||st.rob), m.robot_type?"source":"inf")},`);
+    if(m.control_frequency||m.fps) L.push(`  <span class="kk">"control_hz"</span>: ${cv(m.control_frequency||m.fps,"source")},`);
+    L.push(`  <span class="kk">"channels"</span>: [   <span class="c">// ${ch.length}개 · 배열 순서 = values[] 인덱스</span>`);
+    ch.forEach((c,i)=>{
+      const parts=[];
+      parts.push(`<span class="kk">"key"</span>: ${cv(q(c.name||c.key),"source")}`);
+      if(c.role) parts.push(`<span class="kk">"role"</span>: ${cv(q(c.role), c.role_src==="source"?"source":"inf")}`);
+      parts.push(`<span class="kk">"unit"</span>: ${cv(q(c.unit), c.unit_src==="source"?"source":"inf")}`);
+      if(c.rotation_type) parts.push(`<span class="kk">"rot_type"</span>: ${cv(q(c.rotation_type), c.rotation_src==="source"?"source":"inf")}`);
+      if(c.group && c.group_src==="source") parts.push(`<span class="kk">"group"</span>: ${cv(q(c.group),"source")}`);
+      if(c.range) parts.push(`<span class="kk">"range"</span>: ${cv("["+c.range.map(x=>typeof x==="number"?(+x.toFixed(2)):x).join(", ")+"]", c.range_src==="source"?"source":"inf")}`);
+      const comma = i < ch.length-1 ? "," : "";
+      L.push(`    {${parts.join(", ")}}${comma}   <span class="c">// [${i}]</span>`);
+    });
+    L.push(`  ]`); L.push(`<span class="p">}</span>`);
+    return L.join("\n");
+  }
+  function render(){
+    document.getElementById('robtabs').innerHTML =
+      ROBOTS.map(r=>`<button data-r="${r}" class="${r===st.rob?'on':''}">${KOR[r]||r}</button>`).join("")
+      + `<span class="meta">${esc(DS[st.rob].label)} · ${src().channels.length} ch</span>`;
+    for(const b of document.querySelectorAll('#robtabs button')) b.onclick=()=>{ st.rob=b.dataset.r; render(); };
+    document.getElementById('desc').innerHTML = descriptor();
+  }
+  render();
+</script>
+"""
+
+out = HERE / "descriptor.html"
+out.write_text(HTML.replace("__DATA__", DATA))
+print(f"wrote {out} ({out.stat().st_size} bytes)")