Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ jobs:
cache: pip
- run: python -m pip install -r requirements-dev.txt
- run: python -m pytest -q
- uses: actions/setup-node@v4
with:
node-version: "22"
- run: node --test tests/workspace_manual.test.mjs
render:
runs-on: ubuntu-latest
env:
Expand Down
13 changes: 12 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,8 @@ artifacts/

# Optional upstream benchmark and isolated simulation runtime
.external/
.venv-libero/
# May be a directory OR a local link to another worktree.
/.venv-libero
.runtime/

# Optional local learned-policy runtime and model snapshots
Expand All @@ -51,3 +52,13 @@ artifacts/
/docs/design/
/docs/research/
/docs/experiments/

.venv-robosuite/

.venv-robocasa/

# Local handoff notes; not public project documentation.
/docs/TASK_EXPANSION_PROGRESS.md

# Shared inference runtime link (the models store is under ignored .runtime).
.venv-vla
49 changes: 49 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,3 +206,52 @@ These checks do not make model requests. Offline tests cover macOS, Linux, and W
## License

ManiLoop is [MIT licensed](LICENSE). ARX X5 assets retain MIT; Panda assets retain Apache-2.0. LIBERO, LeRobot, and downloaded checkpoints retain their own licenses. See [third-party notices](THIRD_PARTY_NOTICES.md).

## Optional robosuite tasks

Add Panda Lift, Stack, PickPlaceCan, Door, and NutAssemblySquare in an isolated
robosuite runtime, without changing LIBERO. Use the existing workspace for manual
control, model connections, and decision review. See [setup and limitations](docs/ROBOSUITE.md).

```bash
python scripts/setup_robosuite.py
python -m maniloop demo --backend robosuite --task Lift --port 8870
```

These are integrated environments, not model-success claims. Existing LIBERO-trained
local checkpoint presets remain LIBERO-only; RoboCasa is not included in this backend.

## Optional RoboCasa kitchen tasks

Four kitchen tasks are available through a separate PandaOmron backend: `OpenDrawer`,
`CloseDrawer`, `OpenCabinet`, and `CoffeeSetupMug`. The first integration controls the
arm and gripper; base velocity and torso delta inputs are held at zero.

```bash
python scripts/setup_robocasa.py --download-assets
python -m maniloop demo --backend robocasa --task OpenDrawer --port 8872
```

Use the same workspace for camera observations, manual controls, model connections,
and decision review. The installer pins both source projects and isolates their dependencies.
The five required asset groups occupy about 11.1 GB unpacked, excluding source/runtime files.
Default layout 11 / style 14 / seed 0 has real interface checks for all four tasks;
this is not a model success result or a guarantee of arm-only task solvability in every scene.
See [RoboCasa setup, action semantics, and limitations](docs/ROBOCASA.md).


### Operator workspace

The workspace separates manual control, model execution, and scene settings. Stop stays available while switching panels; camera layouts do not advance physics. See [workspace usage](docs/WORKSPACE.md) and [six-dimensional manual control](docs/MANUAL_CONTROL.md).

### Jev text commands

Choose **Jev · 文本原语控制** in the model panel to map explicit, one-line commands
to bounded arm or gripper primitives. Enter a separate TypeSafe API key in the workspace;
it is kept in server memory and is not shared with OpenAI connections. Saving the key
does not call the model; connection diagnostics and execution use the TypeSafe API.

Jev receives text and robot proprioception, without camera images or object state.
This mode supports commands such as moving 10 mm or rotating the tool 5 degrees;
it does not autonomously locate or grasp objects. Completing the command sequence
is distinct from task success. See [Jev setup, examples, and verification](docs/JEV.md).
43 changes: 43 additions & 0 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -206,3 +206,46 @@ python -m maniloop smoke
## 许可证

ManiLoop 采用 [MIT 许可证](LICENSE)。ARX X5 资产保留 MIT,Panda 资产保留 Apache-2.0。LIBERO、LeRobot 和下载的检查点分别保留自己的许可证。详见[第三方声明](THIRD_PARTY_NOTICES.md)。

## 可选 robosuite 操作任务

使用独立环境接入 Panda 的 Lift、Stack、PickPlaceCan、Door、NutAssemblySquare,
不改变已有 LIBERO。复用当前工作台的手动控制、模型入口与决策回看。
安装、控制协议和限制见 [robosuite 指南](docs/ROBOSUITE.md)。

```bash
python scripts/setup_robosuite.py
python -m maniloop demo --backend robosuite --task Lift --port 8870
```

任务已接入不代表模型已完成任务。现有 LIBERO 权重仍只用于 LIBERO;此后端尚不包含 RoboCasa。

## 可选 RoboCasa 厨房任务

新增 `OpenDrawer`、`CloseDrawer`、`OpenCabinet`、`CoffeeSetupMug` 四项厨房任务,
使用独立的 PandaOmron 后端。首版控制机械臂和夹爪,底座速度与躯干增量保持0,不包含导航。

```bash
python scripts/setup_robocasa.py --download-assets
python -m maniloop demo --backend robocasa --task OpenDrawer --port 8872
```

继续使用同一个工作台查看图像、手动控制、接入模型与回看决策。安装器固定两个上游源码版本,
将依赖隔离到新环境,不改变现有 robosuite / LIBERO。五组必需资产解压约11.1 GB,另需源码和运行环境空间。
四任务已在默认布局11/风格14/种子0完成真实接口检查;这不代表模型成功,也不保证其他场景
在底座保持时一定可完成。详细说明见 [RoboCasa 安装与控制指南](docs/ROBOCASA.md)。


### 工作台分区

手动控制、模型运行和场景设置分区显示,相机与动作按钮并排。切换分区保留当前表单;相机布局切换不推进物理。参见[工作台使用说明](docs/WORKSPACE.md)和[六维手动控制](docs/MANUAL_CONTROL.md)。

### Jev 文本指令

在模型面板选择“Jev · 文本原语控制”,将每行一个明确指令映射为有界的机械臂或夹爪动作。
TypeSafe 专用密钥可直接在工作台填写,只保存在服务内存,与 OpenAI 连接分开。
保存密钥不调用模型;连接诊断和执行会调用 TypeSafe API。

Jev 只接收文字和机器人本体状态,不读取相机或物体状态。当前支持移动10毫米、
绕工具轴旋转5度等原语,不提供自主视觉定位或抓放;指令序列结束也不代表任务成功。
安装、示例和验证范围见 [Jev 使用说明](docs/JEV.md)。
20 changes: 20 additions & 0 deletions THIRD_PARTY_NOTICES.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,3 +40,23 @@ licenses; ManiLoop's MIT license does not replace them.
## Optional learned-policy checkpoints

The optional LeRobot integration uses the Apache-2.0 LeRobot package and downloads public model snapshots separately. No learned weights are redistributed in this repository. The selected `lerobot/smolvla_libero`, `Deepkar/libero-test-act` and `ttotmoon/diffusion-libero-v3` model cards declare Apache-2.0; preserve upstream notices when redistributing snapshots. The latter two are community checkpoints, not official LeRobot releases. Sources and pinned revisions are in `src/maniloop/agents/lerobot/catalog.py` and `docs/VLA.md`.

## Optional robosuite runtime

The optional integration installs robosuite 1.5.2 (MIT) and its assets from the
upstream release, separately from the existing LIBERO runtime. No robosuite
assets are vendored by this integration. Preserve upstream code and asset notices.
Source: https://github.com/ARISE-Initiative/robosuite
Dependency versions are listed in requirements/robosuite.txt and the local installation snapshot.

## Optional RoboCasa runtime and kitchen assets

RoboCasa 1.0.1 source (MIT, Copyright 2026 the RoboCasa Team) and the paired
robosuite source are downloaded from pinned official commit archives into an optional installation.
RoboCasa retains its MuJoCo-related Apache-2.0 notice. Kitchen/object/texture assets
come from the upstream asset registry; retain individual upstream asset licenses
and attribution requirements. The source-code MIT license is not a blanket relicensing
of third-party assets. Neither these assets nor their downloads are bundled in ManiLoop.

Sources: https://github.com/robocasa/robocasa ; https://github.com/ARISE-Initiative/robosuite
The installation records archive checksums; per-run manifests identify both source implementations.
18 changes: 18 additions & 0 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -97,3 +97,21 @@ ACT / Diffusion 是非语言条件的视觉模仿基线,SmolVLA 是语言条
## 云端 LLM 目标闭环

GPT / API 策略支持文字、图像、结构化动作诊断、`llm_rgb512` 观测和 `controllers/target.py` 的固定目标伺服。`EpisodeRunner` 记录执行终态反馈,并支持 current / paired 上下文、单步、暂停与连续运行。决策回看保存前后帧;可选完整录制保存初帧和每个原生控制步,校验后导出双相机 MP4。使用方法见 [GPT6_DEMO.md](GPT6_DEMO.md) 和 [EPISODE_RECORDING.md](EPISODE_RECORDING.md)。

## 外部操作任务:robosuite

`backends/robosuite` 是独立 Python 3.11 worker,使用固定 robosuite 1.5.2 / MuJoCo 3.3.7。
主进程仍只依赖 Environment 协议,CLI 和网页共用 EpisodeRunner;LIBERO 不迁移。
首版使用 Panda、显式 world-frame OSC 与一致的末端 site 姿态;只有 step 推进物理。
RGB 在观察时从当前状态显式渲染,评分走独立操作,不向模型返回物体真值或评分。
任务目录独立于仿真安装,可供 CLI 与网页读取;实际初始化和运行依赖由 worker 检查。
完整使用说明与支持边界见 [ROBOSUITE.md](ROBOSUITE.md)。

## 外部厨房任务:RoboCasa

`backends/robocasa` 使用独立 Python3.11 / MuJoCo3.3.1 与固定 RoboCasa、配套 robosuite 源码。
复用机械臂目标队列与通信模式,不迁移 LIBERO、不混装依赖。上游完整动作12维,
逻辑 world OSC 七维仅是机械臂子接口;worker 依据机器人 base 姿态转换并通过上游 body-part 接口组装,
底座速度/躯干增量保持0,使用 arm 模式。独立评分与 sensor-only 边界保留。
重置后读取当前 episode 语言;布局、风格、源码摘要、动作子接口与实际指令进入记录。
现阶段默认四任务接口可运行,导航和自主任务成功不属于接入结论。详见 [ROBOCASA.md](ROBOCASA.md)。
80 changes: 80 additions & 0 deletions docs/JEV.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Jev:文本原语控制

本版将 Jev 作为高层选择器,沿用现有机器人控制器。不是将云端模型放进20Hz伺服循环。
纯Jev模式仅发送显式指令和公开本体状态,不发送图像,不读取物体真值。
每行一个动作,成功执行后再处理下一行;序列结束不代表官方操作任务成功。

## 运行入口

网页可以直接填写 TypeSafe 专用密钥,无需先设置终端环境变量。不要把密钥写入仓库或分享日志。
当前版本直接使用官方HTTP接口,不需要安装TypeSafe SDK或Jev权重,不会复用OpenAI认证。

```bash
cd /path/to/ManiLoop
source .venv/bin/activate
python -m maniloop demo --backend robosuite --task Lift --port 8873
```

已有8873服务时无需重复启动;升级后端代码须重启一次,之后更换网页密钥无需重启。
网页选择“模型运行 → Jev · 文本原语控制”,在 **Jev API Key · TypeSafe 专用** 密码框输入密钥。
点击“保存到本次服务”只检查格式并保存在服务内存,不发模型请求,不验证认证有效性。
也可直接填写后点击“Jev连接诊断 · 不动作”或开始执行。提交成功后输入框清空,留空复用已保存值。
“清除网页密钥”清除本次服务的覆盖值及闲置Jev客户端;任务/请求/动作未结束时不能更换。
优先级为本次填写、服务内存中的网页密钥、可选环境变量 `TYPESAFE_API_KEY`。不改写环境变量。
清除后若启动环境仍有密钥,会明确显示使用环境变量;本按钮不是撤销供应商账号中的Key。
密钥不写文件、浏览器存储或实验日志;状态接口只返回已配置标记及来源,不回传密钥。
刷新页面或切换策略不丢失服务内存里的密钥;重启服务会清除网页保存值。OpenAI配置独立。
保存成功不等于认证成功,请用下方无动作诊断查看真实服务结果。
诊断只调用一次Choice查询,不执行机器人动作;成功响应会显示实际模型版本与概率。
没有访问条件时明确报错,不切换到其他模型或本地mock。

## 三步演示

点击“载入三步演示指令”,或逐行输入:

```text
Move up along world Z by 10 mm.
Rotate about the tool Z axis by 5 degrees.
Open the gripper.
```

也可测试中文:“沿世界Z轴上移10毫米”“绕工具自身Z轴旋转5度”“打开夹爪”。中文理解效果需单独验证。
支持单步/继续以及连续消费最多20行。每行只发起一次Jev选择,不在运动中重复调用。
含糊指令、未知候选、低候选概率、API错误或本地动作超时会停止,不跳过失败继续下一行。
当前仅支持受控时序。开始不自动重置场景;需要时先在手动控制中重新初始化。
默认平移10mm、旋转5度;指令含一个明确数值和单位时优先使用该值。
只接受单一数值;复合数值、科学计数法等未实现的解析形式会拒绝,不静默误读。
候选包含固定/工具轴三轴正负平移旋转、夹爪、wait,以及需要澄清/需要视觉定位的出口。
精确单位换算、坐标转换、范围与可达性检查由本地代码处理,不从概率回归坐标。
选择概率阈值默认0.7,可调整;它不是成功率或安全保证。
手臂目标跟踪默认3秒,可设0.05–10秒。仅Jev控制路径使用该预算,其他策略不受影响。
现有夹爪路径/上游评分不变。UI策略调用计数与实际jev_requests在日志中分别可查。

```bash
# CLI 使用其启动环境中的 TYPESAFE_API_KEY,不读取网页服务内存。
python -m maniloop benchmark --backend robosuite --task Lift --agent jev \
--instruction 'Move up 10 mm' --max-calls 2 --output runs/jev-demo
```

## 记录与边界

provider_decision记录候选、概率、模型版本、候选摘要和当前观测ID。
说明文字标记为程序模板,不声称Jev生成思考过程。停止/reset后的迟到响应仍丢弃。
默认模型是jev-1.13.0;使用别名时查看响应实际版本。HTTP不自动重试或跟随重定向。
文本模式不读取图片,图像仅用于工作台显示和现有变化检查。不支持“找到杯子并抓取”。
核心代码:providers/typesafe.py、agents/jev.py,复用runtime/runner.py及现有目标控制器。
组合策略要另设信息来源和评测组,不把VLM输出、特权状态或脚本技能收益算作纯Jev能力。

## 验证命令

```bash
python -m pytest tests/test_jev.py -q
MANILOOP_TEST_JEV_SIM=1 python -m pytest tests/test_jev_integration.py -q
```

第二组是真实仿真加模拟Jev响应,用于验证接线、单位、序列终止和本地执行,不证明真实Jev的判断能力。
真实在线能力应使用配置好的TypeSafe账号在网页诊断和指令demo中另测。

官方协议:https://docs.typesafe.ai/api
模型与输入边界:https://docs.typesafe.ai/models
Choice语义:https://docs.typesafe.ai/primitives/choice
19 changes: 19 additions & 0 deletions docs/LIBERO.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,25 @@ export MANILOOP_LIBERO_ROOT=/path/to/LIBERO

默认从当前工作目录寻找 `.venv-libero` 和 `.external/LIBERO`。源码必须是安装脚本固定的 Git 版本;不支持把任意版本冒充同一实验协议。

## 在另一个 Git 工作区复用已安装的环境

新建 worktree 不会自动带上被 Git 忽略的虚拟环境和资产目录。若原工作区已安装,
可在新工作区根目录执行(将路径换成原工作区):

```bash
python scripts/setup_libero.py --reuse-from ../ManiLoop
python -m maniloop list --backend libero
python -m maniloop smoke --backend libero
```

该命令校验固定源码版本与 Python 3.10 / MuJoCo 2.3.7 / robosuite 1.4.0,
只为 `.venv-libero` 和 `.external/LIBERO` 创建本地目录链接,不下载、不调用 pip。
可重复运行;已有目录、文件或其他链接不会被覆盖。两个目标都检查通过后才建立链接。
原工作区必须保留且不能随意移动;环境更新应由原工作区统一管理。
普通安装命令遇到共享链接会停止,避免误改另一个工作区的依赖。
系统不允许目录链接时,使用上文的两个环境变量指定 Python 和 LIBERO 路径。
链接建立后,已启动的服务在下一次加载目录/场景时即可找到运行时,无需更改 API 配置。

## 选择任务与批量运行

网页支持切换环境后端、官方任务集、任务编号和初始化编号。点击「应用并重置场景」后使用官方任务指令;首次加载可能需要等待数十秒。机器人固定为 Panda。换成 ARX5 属于新的跨具身体任务变体,需要另行验证,不能继续标作原版 LIBERO。
Expand Down
Loading
Loading