NVlabs/SpatialClaw

📚 SpatialClaw とは何か？

SpatialClaw は、空間推論エージェント向けのトレーニング不要なフレームワークです。ビジョン・ランゲージモデル（VLM）が、すでにセグメンテーション（例：SAM-3）、3D再構成（Depth-Anything-3）、科学計算ライブラリ（NumPy、SciPy、Matplotlib）がロードされた永続的なJupyterカーネル内で、ステップバイステップでPythonコードを書く・実行することを可能にします。エージェントは中間結果を確認し、ツール出力を組み合わせ、最終的に ReturnAnswer(...) を使って答えを返すまで、計画・コード生成・安全確認実行・観測のループを繰り返します。

研究者たちは、20の異なる空間推論ベンチマーク（静止画像、マルチビューシーン、動画/4Dタスク）でこのシステムを評価し、平均精度59.9% を達成しました。これは、同じプロンプト、ツールセット、ハイパーパラメータを用いて、6つのVLMバックエンド（26B～397Bパラメータ）で実行された前例の最高精度を**+11.2ポイント**上回る結果です。

🔧 動作原理

3サービスランタイム – vLLMサーバ（VLM）、GPU加速の認識ツールサーバ（セグメンテーション、深度、幾何）、エージェント自体（Jupyterカーネル）。JSONレジストリを介して通信でき、単一GPUマシンまたはSLURMクラスタで実行可能。
サンプルごとの5段階ループ
- プランナーが高レベルな戦略を提案。
- VLMが1つのPythonセルを書く。認識ツールの呼び出し、変数の作成、プロットなどが可能。
- セルはAST検証で安全確認され、永続カーネル内で実行。
- カーネルのstdout、新規変数、show()で出力された画像が次の観測として戻される。
- VLMが ReturnAnswer(...) を出力するまでループを繰り返す。
状態保持カーネル – すべての変数とロードされた画像がステップ間で保持されるため、後続のセルで以前の結果を再計算せずに再利用可能。
ツールラッパー – SAM-3、Depth-Anything-3、幾何ユーティリティをシンプルな関数呼び出しとして公開する軽量Pythonラッパー。
LangGraphワークフロー – 全体のオーケストレーションはLangGraphに基づいており、ループの拡張が容易です。

🚀 クイックスタート（単一マシン、SLURM不要）

# 1. サブモジュール含むクローンと環境インストール（約15〜30分）
git clone --recursive https://github.com/NVlabs/SpatialClaw.git
cd SpatialClaw
bash spatial_agent/scripts/setup.sh

# 2. APIキーの提供（または自前vLLMサーバを起動してキー不要）
cp .env.example .env   # あなたのキーでファイルを編集

# 3. 1つのベンチマーク例を実行
python -m spatial_agent.entrypoints.run \
    --dataset spatial_agent/config/dataset/erqa.json \
    --model   spatial_agent/config/model/gemini-3-pro.json \
    --concurrency 4

クラスタ実行の場合は、docs/installation.md と docs/running.md を参照し、SLURM起動マネージャーと重み事前ダウンロード手順を確認してください。

📂 リポジトリ構成（概要）

spatial_agent/ – エージェント本体コード、LangGraphワークフロー、Jupyterカーネルマネージャー、ASTセキュリティチェッカー。
tools/ – 認識モジュール（SAM-3、Depth-Anything-3）および幾何ユーティリティのラッパー。
docs/ – 詳細ガイド（インストール、実験実行、モニタリング、設定、アーキテクチャ）。
spatial_agent/config/ – 20のベンチマークおよびモデルバックエンド用のJSON設定ファイル。
scripts/ – 環境セットアップおよびSLURMジョブ送信用のヘルパースクリプト。

🎯 SpatialClawを使うべき場面

空間推論の研究 – モデルのファインチューニングなしに、視覚ツールを柔軟に組み合わせたい場合。
ツール拡張エージェント – 固定されたツールコールAPIより、より表現力豊かな「コードとしての行動」インターフェースを提供。
ベンチマーク比較 – 20の標準空間ベンチマーク用ローダーが同梱されており、再現性が容易。
迅速なプロトタイピング – 新しいPythonラッパーを書くだけで、認識ツールを置き換えたり追加したり可能。エージェントは自動的に呼び出せる。

⚠️ 制限事項と考慮点

トレーニング不要のみ – 性能は根本的なVLMに依存。ファインチューニングは一切行わない。
GPU負荷が高い – 認識ツールサーバとVLMの両方がGPUメモリを必要とするため、多数の並行サンプルを実行するにはマルチGPU環境またはSLURMが必要。
セキュリティチェックは静的 – ASTバリデーターは明らかな不正コードを検出できるが、カーネルは任意のPythonを実行するため、信頼できる環境で実行すべき。
ライセンス – NVIDIA Source Code License-NC（非営利）。サードパーティツールはそれぞれ独自のライセンスを持つ。

📖 引用

SpatialClawを研究で使用する場合、以下の引用を記載してください：

@article{cho2026spatialclaw,
  title   = {SpatialClaw: Rethinking Action Interface for Agentic Spatial Reasoning},
  author  = {Cho, Seokju and Hachiuma, Ryo and Badki, Abhishek and
             Su, Hang and Lee, Byung-Kwan and Song, Chan Hee and
             Liu, Sifei and Radhakrishnan, Subhashree and Kim, Seungryong and
             Wang, Yu-Chiang Frank and Chen, Min-Hung},
  journal = {arXiv preprint},
  year    = {2026}
}

TL;DR – SpatialClawは、大規模ビジョン・ランゲージモデルが強力な認識ツールを呼び出すPythonセルを書くことで、2D/3D/4Dの高度な推論を実行できる研究用のコード駆動型エージェントフレームワークであり、モデルのトレーニングなしに、幅広い空間ベンチマークで最先端の結果を達成しています。