feat: add LeRobot v3 dataset import support by rikunosuke · Pull Request #268 · fastlabel/fastlabel-python-sdk

rikunosuke · 2026-03-12T00:31:44Z

Summary

LeRobot v3 データセットを FastLabel ロボティクスプロジェクトにインポートする import_lerobot メソッドを追加
pip install fastlabel[robotics] でオプション依存（pandas, pyarrow）をインストール可能に
v2 データセットはエラーメッセージで非対応を通知
flake8 の E231 誤検知（f-string format spec）を tox.ini で対応

Test plan

LeRobot v3 データセットでの import_lerobot 動作確認
v2 データセットで適切なエラーメッセージが表示されることを確認
pip install fastlabel[robotics] で pandas, pyarrow がインストールされることを確認
robotics 依存なしで import 時に適切なエラーが出ることを確認

🤖 Generated with Claude Code

Add import_lerobot method to import LeRobot v3 datasets into FastLabel robotics projects. Includes optional dependencies (pandas, pyarrow) via pip install fastlabel[robotics]. v2 datasets are detected and rejected with an error message. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

rikunosuke · 2026-03-12T00:59:22Z

pyproject.toml

+[project.optional-dependencies]
+robotics = ["pandas>=2.0.0", "pyarrow>=14.0.0"]
+


pip install fastlabel[robotics] でダウンロードできるようにしています。pandas, pyarrow くらいであれば分ける必要はないと思っているんですが、今後、Lerobot 用のパッケージがなどが入るので、先にこうしています。

rikunosuke · 2026-03-12T01:02:07Z

fastlabel/lerobot/__init__.py

+    if version == "v2":
+        raise FastLabelInvalidException(
+            "LeRobot dataset v2 is not supported. Please convert to v3.",
+            422,
+        )


まずはメインで使われている v3 をサポートしています。
v2 に関しては、必要今後検討します。

rikunosuke · 2026-03-12T01:05:52Z

こちら、サンプルのために録画した lerobot のデータになります。

sample-realman.zip

kamei-takuma

@rikunosuke
拝見させていただきました！
ロボット周りがあまりわかってないので、変なこと言ってたら無視してください🙇

localhostに向けて動かして、問題なく動くことは確認しました！

(sdk) kmtkm@193-TakumaKamei fastlabel-python-sdk % python -c "
dquote> from fastlabel.lerobot import common
from pathlib import Path

data_path = Path('sample-realman')

# 1. バージョン検出
print('Version:', common.detect_version(data_path))

# 2. カメラ一覧
for cam_dir, name in common.get_camera_dirs(data_path):
    print(f'Camera: {name}')
"
Version: v3
Camera: cam_high
Camera: cam_left_wrist
Camera: cam_right_wrist
Camera: camera_01
(sdk) kmtkm@193-TakumaKamei fastlabel-python-sdk % python -c "
from fastlabel.lerobot import v3
from pathlib import Path

data_path = Path('sample-realman')

# エピソード一覧
indices = v3.get_episode_indices(data_path)
print('Episodes:', indices)

# 最初のエピソードで ZIP 生成
zip_path = v3.create_episode_zip(data_path, indices[0])
print('ZIP:', zip_path)

# ZIP の中身を確認
import zipfile
with zipfile.ZipFile(zip_path) as zf:
    for name in zf.namelist():
        print(f'  {name}')
"

Episodes: [0]
ZIP: /var/folders/s_/yw3yzchj76vgrqzw9vg24z0h0000gn/T/tmpcuq297nn/episode_000000.zip
  cam_left_wrist.mp4
  cam_right_wrist.mp4
  cam_high.mp4
  episode_000000.json
  camera_01.mp4
(sdk) kmtkm@193-TakumaKamei fastlabel-python-sdk % python -c "
import fastlabel

client = fastlabel.Client()
results = client.import_lerobot(
    project='robotics-task-classification',
    lerobot_data_path='sample-realman',
    episode_indices=[0],
)
print(results)
"
[{'episode': 'episode_000000', 'success': True, 'result': {'id': '7c310bf6-1937-4d48-99cb-04a704317229', 'status': 'running', 'msgCode': 'none', 'userName': '', 'credentialName': 'test', 'createdAt': '2026-03-12T23:01:56.137Z', 'updatedAt': '2026-03-12T23:01:56.137Z'}}]

kamei-takuma · 2026-03-12T10:48:34Z

fastlabel/__init__.py

+            episode_name = lerobot.format_episode_name(episode_index)
+            self.create_robotics_task(project=project, name=episode_name)
+
+            zip_path = lerobot.create_episode_zip(


[nits]

parquet読み込みが何度も走っているのが若干気にはなりました
create_episode_zipから内部的に呼び出している_build_episode_mapが
ループ毎に全 parquet をスキャンしてエピソードのインデックス情報を構築してそうで、
結果は呼び出し間で変わらなそうだなと

これがパフォーマンスにどれくらい影響があるのかちょっとわかってないのですが、ループ外で一度だけ構築して渡す設計でもいいかもと思ったりしました

確かにその通りですね！ループ外のメインのメソッドで作成して、引数として渡す構造に変更しました！

d3303df

kamei-takuma · 2026-03-12T10:51:17Z

fastlabel/lerobot/v3.py

+        ret, frame = cap.read()
+        if not ret:
+            break
+        writer.write(frame)


ループ中に例外が起きるとreleseされなさそうなので、finally入れとくといいかもです

try: for _ in range(num_frames): ret, frame = cap.read() if not ret: break writer.write(frame) finally: writer.release() cap.release()

ありがとうございます！ finally いれました！
d3303df

kamei-takuma · 2026-03-12T10:52:18Z

examples/import_lerobot.py

+
+Requires: pip install fastlabel[robotics]
+
+Supports both LeRobot v2 and v3 dataset formats.


v2も対応してるぜ、ってコメントで言ってそう？

すみみません、最初にv2対応してみた時の名残です🙇
削除しました！
d3303df

kamei-takuma · 2026-03-12T10:52:58Z

fastlabel/__init__.py

+        """
+        Import a LeRobot dataset into a FastLabel robotics project.
+
+        Automatically detects LeRobot dataset version (v2 or v3).


同じくv2も対応しているぜと言ってそう

kamei-takuma · 2026-03-12T11:02:30Z

fastlabel/__init__.py

+                    project=project, file_path=zip_path
+                )
+                results.append(
+                    {"episode": episode_name, "success": True, "result": result}


[imo]
例外が発生した時のexceptがなさそうなので、例外が発生するとその時点で処理を中断して返却値なしとなるAll-or-nothin的な実装だと読み取ったのですが、
一方、resultsに各エピソードの処理結果をsuccess として格納しており、部分的にも処理した結果を返したいようにも見えてます。

一部でも失敗したら返却がいらないならsuccessってキーとしているっけ？という感じですし、
一部失敗しても全部処理をし切りたいならexceptで受けて {"success": False, ...} 等を
resultsに追加してcontinueで次に進む等の対応が必要な気がしました。

kamei-takuma · 2026-03-12T11:11:40Z

fastlabel/lerobot/v3.py

+
+    if episode_index not in episode_map:
+        raise FastLabelInvalidException(
+            f"Episode index {episode_index} not found in dataset.",  # noqa: E713


E713って何だっけと思って軽く調べたのですが、なんか関係なさそうにも見えてて、これないと通らなかったです？？
https://www.flake8rules.com/rules/E713.html

kamei-takuma · 2026-03-12T11:15:50Z

fastlabel/lerobot/v3.py

+            "action": row["action"].tolist(),
+            "frame_index": int(row["frame_index"]),
+            "timestamp": float(row["timestamp"]),
+        }


ロボット詳しくなくてすみません、ここのキー名って決め打ちで大丈夫でしたかね？
observation.stateとかactionとかってロボットが変わっても変わらずあるぜっていうキーなのかどうかがちょっと心配になりました。

もしキーが存在しなかったらKeyエラーが出そうだなとmm

observation.state と action は lerobot の仕様でロボットごとの差異はないので、決め打ちで大丈夫です！
ただ、key がない可能性を考慮できていなかったので、確認をするようにしました🙇

681bb56

kamei-takuma · 2026-03-12T11:28:16Z

fastlabel/lerobot/__init__.py

+    ZIP structure:
+        {episode_name}/
+            {content_name}.mp4  (one per camera)
+            {episode_name}.json (frame data)


docstringでは {episode_name}/ がZIPのルートディレクトリとして存在し、
その下にファイルが配置される構造をしてそうに見えたのでsが、
v3.pyの下記実装だと shutil.make_archive(root_dir=content_dir) でファイルが直接ZIPのルートに配置されちゃうかもと思ったのですがどうですかね？

tmp_dir = tempfile.mkdtemp() content_dir = Path(tmp_dir) / "content" content_dir.mkdir() ... # Create ZIP (files at root, ZIP name = episode name) zip_path = shutil.make_archive( base_name=str(Path(tmp_dir) / episode_name), format="zip", root_dir=str(content_dir), )

もし乖離がありそうなら、docstringを実態に合わせる形で良いかなと思いますmm

[docstringの想定] episode_000000.zip └── episode_000000/ ├── top.mp4 └── episode_000000.json [コード上の構造] episode_000000.zip ├── top.mp4 └── episode_000000.json

ここも修正忘れでした🙇

d928047

kamei-takuma · 2026-03-12T11:37:38Z

fastlabel/lerobot/common.py

+        if not obs_dir.is_dir():
+            continue
+        parts = obs_dir.name.split(".")
+        content_name = parts[-1] if len(parts) > 1 else obs_dir.name


下記みたいなパターンってあります？content_nameが被るとv3.pyの132行目あたりで同じ名前で衝突しちゃいそうだなと

videos/ observation.images.top/ → content_name = "top" observation.depth.top/ → content_name = "top"

あり得なさそうであればスルーで大丈夫です!

lerobot の仕様としては observation.* みたいなので、あり得そうですね！
修正しました！

6cddb65

The docstring incorrectly described files as nested under an {episode_name}/ directory, but the implementation places files at the ZIP root. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Return an empty list when required parquet columns (observation.state, action, frame_index, timestamp) are missing, preventing KeyError on datasets from different robot types. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use all parts after "observation." joined with "_" for content_name (e.g. observation.images.top -> images_top) instead of only the last part. Also replace assert with FastLabelInvalidException for non-observation camera directories. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

rikunosuke commented Mar 12, 2026

View reviewed changes

kamei-takuma assigned rikunosuke Mar 12, 2026

kamei-takuma self-requested a review March 12, 2026 01:26

kamei-takuma reviewed Mar 12, 2026

View reviewed changes

rikunosuke and others added 5 commits March 19, 2026 14:20

fix wrong comments, create a episode map out of loop scope

d3303df

fix create_episode_zip docstring to match actual ZIP structure

d928047

The docstring incorrectly described files as nested under an {episode_name}/ directory, but the implementation places files at the ZIP root. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: version up flake8 and fix codes

8612de4

		[project.optional-dependencies]
		robotics = ["pandas>=2.0.0", "pyarrow>=14.0.0"]


		Requires: pip install fastlabel[robotics]

		Supports both LeRobot v2 and v3 dataset formats.

Conversation

rikunosuke commented Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rikunosuke commented Mar 12, 2026

Uh oh!

kamei-takuma left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rikunosuke Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kamei-takuma Mar 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rikunosuke Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

rikunosuke commented Mar 12, 2026 •

edited

Loading

kamei-takuma left a comment •

edited

Loading

rikunosuke Mar 19, 2026 •

edited

Loading

kamei-takuma Mar 12, 2026 •

edited

Loading

rikunosuke Mar 19, 2026 •

edited

Loading