get-embodied-tasks 0.1.0__py3-none-any.whl

get_embodied_tasks/__init__.py

@@ -0,0 +1,4 @@
+# Copyright 2025. Apache-2.0.
+"""get-embodied-tasks: task spec -> dataset + runnable commands across backends."""
+
+__version__ = "0.1.0"

get_embodied_tasks/backends/__init__.py

@@ -0,0 +1 @@
+# Copyright 2025. Apache-2.0.

get_embodied_tasks/backends/base.py

@@ -0,0 +1,35 @@
+# Copyright 2025. Apache-2.0.
+"""Backend protocol: a source of embodied-AI tasks + datasets + runnable commands."""
+
+from __future__ import annotations
+
+import abc
+
+from get_embodied_tasks.discovery import Resolution
+
+
+class Backend(abc.ABC):
+    """One task source (e.g. a LeRobot checkout). Adapters subclass this."""
+
+    name: str
+
+    @abc.abstractmethod
+    def locate(self) -> Resolution:
+        """Where is this backend? (does not import it)."""
+
+    def available(self) -> bool:
+        return bool(self.locate())
+
+    @abc.abstractmethod
+    def bundles(
+        self,
+        query: str | None = None,
+        benchmark: str | None = None,
+        limit: int = 20,
+        policy: str | None = None,
+    ) -> tuple[list[dict], list[dict], list[dict]]:
+        """Return (matched bundles, fuzzy-suggestion bundles, warnings). Bundles are plain dicts."""
+
+    @abc.abstractmethod
+    def dump(self, policy: str | None = None) -> tuple[list[dict], list[dict]]:
+        """Return (all bundles, warnings)."""

get_embodied_tasks/backends/lerobot.py

@@ -0,0 +1,99 @@
+# Copyright 2025. Apache-2.0.
+"""LeRobot backend adapter.
+
+Locates a (vanilla) LeRobot checkout or installed package, reads its task catalog by
+AST (`catalog.build`), and attaches the LeRobot dataset map + train/eval commands
+(`data.lerobot_datasets`). Never imports LeRobot.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+
+from get_embodied_tasks import catalog
+from get_embodied_tasks.backends.base import Backend
+from get_embodied_tasks.data import lerobot_datasets as ds
+from get_embodied_tasks.discovery import Resolution, resolve_root
+from get_embodied_tasks.matching import find_tasks
+
+ENV_VAR = "LEROBOT_HOME"
+SUBPATH = "lerobot"
+IMPORT_NAME = "lerobot"
+
+
+class LeRobotBackend(Backend):
+    name = "lerobot"
+
+    def __init__(self, cwd: Path | None = None):
+        self._cwd = cwd
+
+    def locate(self) -> Resolution:
+        return resolve_root(SUBPATH, env_var=ENV_VAR, import_name=IMPORT_NAME, cwd=self._cwd)
+
+    def envs_dir(self) -> Path | None:
+        """Resolve the `lerobot/envs` directory for a checkout or installed package."""
+        res = self.locate()
+        if not res:
+            return None
+        if res.root is not None:  # checkout
+            return res.root / "src" / "lerobot" / "envs"
+        spec = importlib.util.find_spec(IMPORT_NAME)  # installed
+        if spec and spec.origin:
+            return Path(spec.origin).parent / "envs"
+        return None
+
+    def _build(self) -> tuple[list[catalog.TaskEntry], list[dict]]:
+        envs = self.envs_dir()
+        if envs is None:
+            res = self.locate()
+            warn = {
+                "benchmark": "lerobot",
+                "what": "LeRobot backend not found",
+                "where": res.detail,
+                "hint": (
+                    f"set ${ENV_VAR}=<lerobot checkout>, vendor it under "
+                    f"third_party/ei_ws/{SUBPATH}, or pip install lerobot"
+                ),
+            }
+            return [], [warn]
+        entries, warnings = catalog.build(envs)
+        return entries, [w.as_dict() for w in warnings]
+
+    def _bundle(self, e: catalog.TaskEntry, policy: str | None) -> dict:
+        p = policy or ds.default_policy(e.env_type)
+        d = ds.dataset_for(e.env_type)
+        return {
+            "backend": self.name,
+            "benchmark": e.benchmark,
+            "env_type": e.env_type,
+            "task": e.task_name,
+            "description": e.description,
+            "category": e.category,
+            "enumerable": e.enumerable,
+            "dataset": ({"repo_id": d.repo_id, "url": d.url, "note": d.note} if d else None),
+            "policy": p,
+            "train_command": ds.train_command(e.env_type, e.task_name, p),
+            "eval_command": ds.eval_command(e.env_type, e.task_name),
+            "upstream_url": e.upstream_url,
+        }
+
+    def bundles(self, query=None, benchmark=None, limit=20, policy=None):
+        entries, warnings = self._build()
+        if not query:
+            corpus = entries
+            if benchmark:
+                b = benchmark.lower()
+                corpus = [e for e in corpus if b in (e.benchmark.lower(), e.env_type.lower())]
+            matches, suggestions = corpus[:limit], []
+        else:
+            matches, suggestions = find_tasks(entries, query, benchmark=benchmark, limit=limit)
+        return (
+            [self._bundle(e, policy) for e in matches],
+            [self._bundle(e, policy) for e in suggestions],
+            warnings,
+        )
+
+    def dump(self, policy=None):
+        entries, warnings = self._build()
+        return [self._bundle(e, policy) for e in entries], warnings

get_embodied_tasks/backends.toml

@@ -0,0 +1,8 @@
+# Backend registry for get-embodied-tasks. Each table is one backend.
+# Discovery for a backend tries, in order:
+#   $env_var  ->  ./third_party/ei_ws/<subpath>  ->  ~/ei_ws/<subpath>  ->  installed package
+[lerobot]
+adapter = "lerobot"        # maps to backends/lerobot.py:LeRobotBackend
+subpath = "lerobot"        # dir name under the ei_ws roots
+env_var = "LEROBOT_HOME"   # explicit override
+enabled = true

get_embodied_tasks/catalog.py

@@ -0,0 +1,335 @@
+# Copyright 2025. Apache-2.0.
+"""Import-light task catalog read from a *vanilla* LeRobot checkout.
+
+Reads LeRobot's `envs/` source by AST (task-list constants) and JSON (MetaWorld
+config) — it never imports LeRobot, so no torch/gymnasium and no dependency on any
+patched `task_index.py`. RoboTwin/RoboMME task descriptions ship with this package
+(`data/*.json`); they are not in upstream LeRobot.
+
+`build(envs_dir)` returns `(entries, warnings)`. Anything it cannot read (a renamed
+constant, a moved module, a missing JSON) becomes a structured warning instead of a
+silent drop, so drift against a future LeRobot is surfaced, not hidden.
+"""
+
+from __future__ import annotations
+
+import ast
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+_DATA_DIR = Path(__file__).parent / "data"
+
+
+@dataclass(frozen=True)
+class TaskEntry:
+    benchmark: str
+    env_type: str
+    task_name: str
+    description: str | None = None
+    category: str | None = None
+    enumerable: bool = True
+    upstream_url: str | None = None
+    extra: str | None = None
+
+    @property
+    def search_text(self) -> str:
+        return " ".join([self.task_name, self.description or "", self.category or ""]).lower()
+
+    @property
+    def tokens(self) -> set[str]:
+        return set(re.split(r"[-_\s]+", self.search_text)) - {""}
+
+
+@dataclass
+class CatalogWarning:
+    benchmark: str
+    what: str
+    where: str
+    hint: str
+
+    def as_dict(self) -> dict:
+        return {"benchmark": self.benchmark, "what": self.what, "where": self.where, "hint": self.hint}
+
+
+@dataclass(frozen=True)
+class _BenchMeta:
+    name: str
+    env_type: str
+    upstream_url: str | None = None
+    extra: str | None = None
+
+
+_BENCHMARKS: dict[str, _BenchMeta] = {
+    "metaworld": _BenchMeta(
+        "Meta-World", "metaworld", "https://github.com/Farama-Foundation/Metaworld", "metaworld"
+    ),
+    "robotwin": _BenchMeta(
+        "RoboTwin", "robotwin", "https://github.com/RoboTwin-Platform/RoboTwin", "robotwin"
+    ),
+    "robomme": _BenchMeta("RoboMME", "robomme", "https://github.com/RoboMME/robomme_benchmark", "robomme"),
+    "vlabench": _BenchMeta("VLABench", "vlabench", "https://github.com/OpenMOSS/VLABench", "vlabench"),
+    "libero": _BenchMeta("LIBERO", "libero", "https://github.com/Lifelong-Robot-Learning/LIBERO", "libero"),
+    "libero_plus": _BenchMeta("LIBERO-plus", "libero_plus", "https://github.com/sylvestf/LIBERO-plus", None),
+    "robocasa": _BenchMeta("RoboCasa", "robocasa", "https://github.com/robocasa/robocasa", "robocasa"),
+    "pusht": _BenchMeta("PushT", "pusht", "https://github.com/huggingface/gym-pusht", "pusht"),
+    "aloha": _BenchMeta("Aloha", "aloha", "https://github.com/huggingface/gym-aloha", "aloha"),
+}
+
+
+# --- AST / JSON readers ----------------------------------------------------
+
+
+def _read_literal(envs_dir: Path, filename: str, name: str):
+    """`ast.literal_eval` the RHS of a top-level `name = <literal>` in envs/<filename>."""
+    source = (envs_dir / filename).read_text()
+    tree = ast.parse(source, filename=filename)
+    for node in tree.body:
+        targets = (
+            node.targets
+            if isinstance(node, ast.Assign)
+            else ([node.target] if isinstance(node, ast.AnnAssign) else [])
+        )
+        for target in targets:
+            if isinstance(target, ast.Name) and target.id == name and node.value is not None:
+                return ast.literal_eval(node.value)
+    raise KeyError(f"{name} not found in {filename}")
+
+
+def _read_docstring(envs_dir: Path, filename: str) -> str:
+    return ast.get_docstring(ast.parse((envs_dir / filename).read_text(), filename=filename)) or ""
+
+
+def _scan_env_types(envs_dir: Path) -> dict[str, str]:
+    """Map env.type -> default task by AST-scanning the register_subclass decorators."""
+    tree = ast.parse((envs_dir / "configs.py").read_text(), filename="configs.py")
+    out: dict[str, str] = {}
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        env_type = None
+        for deco in node.decorator_list:
+            if (
+                isinstance(deco, ast.Call)
+                and isinstance(deco.func, ast.Attribute)
+                and deco.func.attr == "register_subclass"
+            ):
+                if deco.args and isinstance(deco.args[0], ast.Constant):
+                    env_type = deco.args[0].value
+                for kw in deco.keywords:
+                    if kw.arg == "name" and isinstance(kw.value, ast.Constant):
+                        env_type = kw.value.value
+        if env_type is None:
+            continue
+        default = ""
+        for stmt in node.body:
+            if (
+                isinstance(stmt, ast.AnnAssign)
+                and isinstance(stmt.target, ast.Name)
+                and stmt.target.id == "task"
+                and isinstance(stmt.value, ast.Constant)
+            ):
+                default = stmt.value.value
+        out[env_type] = default
+    return out
+
+
+def _load_descriptions(data_dir: Path, filename: str) -> dict[str, str]:
+    return json.loads((data_dir / filename).read_text()).get("descriptions", {})
+
+
+# --- per-benchmark builders (each appends to `warnings` on failure) ---------
+
+
+def _try(warnings: list[CatalogWarning], benchmark: str, where: str, hint: str, fn):
+    try:
+        return fn()
+    except Exception as exc:  # noqa: BLE001 — any read failure becomes a warning, not a crash
+        warnings.append(CatalogWarning(benchmark, f"{type(exc).__name__}: {exc}", where, hint))
+        return None
+
+
+def build(
+    envs_dir: str | Path, data_dir: str | Path | None = None
+) -> tuple[list[TaskEntry], list[CatalogWarning]]:
+    """Build the task corpus from a LeRobot `envs/` dir. Returns (entries, warnings)."""
+    envs = Path(envs_dir)
+    data = Path(data_dir) if data_dir else _DATA_DIR
+    entries: list[TaskEntry] = []
+    warnings: list[CatalogWarning] = []
+    hint_ver = "likely a LeRobot version change — check LEROBOT_HOME or update the lerobot adapter"
+
+    # MetaWorld (descriptions + difficulty from the checkout's JSON).
+    mw = _try(
+        warnings,
+        "Meta-World",
+        "envs/metaworld_config.json",
+        hint_ver,
+        lambda: json.loads((envs / "metaworld_config.json").read_text()),
+    )
+    if mw:
+        difficulty = {t: d for d, ts in mw.get("DIFFICULTY_TO_TASKS", {}).items() for t in ts}
+        m = _BENCHMARKS["metaworld"]
+        for name, desc in sorted(mw.get("TASK_DESCRIPTIONS", {}).items()):
+            entries.append(
+                TaskEntry(
+                    m.name,
+                    m.env_type,
+                    name,
+                    desc,
+                    difficulty.get(name),
+                    upstream_url=m.upstream_url,
+                    extra=m.extra,
+                )
+            )
+
+    # RoboTwin (names from checkout, descriptions from this package).
+    rt_names = _try(
+        warnings,
+        "RoboTwin",
+        "envs/robotwin.py:ROBOTWIN_TASKS",
+        hint_ver,
+        lambda: _read_literal(envs, "robotwin.py", "ROBOTWIN_TASKS"),
+    )
+    rt_desc = (
+        _try(
+            warnings,
+            "RoboTwin",
+            "data/robotwin_task_descriptions.json",
+            "shipped with this package",
+            lambda: _load_descriptions(data, "robotwin_task_descriptions.json"),
+        )
+        or {}
+    )
+    if rt_names:
+        m = _BENCHMARKS["robotwin"]
+        for n in rt_names:
+            entries.append(
+                TaskEntry(
+                    m.name, m.env_type, n, rt_desc.get(n) or None, upstream_url=m.upstream_url, extra=m.extra
+                )
+            )
+
+    # VLABench (names only, by suite).
+    m = _BENCHMARKS["vlabench"]
+    for const, cat in (("PRIMITIVE_TASKS", "primitive"), ("COMPOSITE_TASKS", "composite")):
+        names = _try(
+            warnings,
+            "VLABench",
+            f"envs/vlabench.py:{const}",
+            hint_ver,
+            lambda const=const: _read_literal(envs, "vlabench.py", const),
+        )
+        for n in names or []:
+            entries.append(
+                TaskEntry(m.name, m.env_type, n, category=cat, upstream_url=m.upstream_url, extra=m.extra)
+            )
+
+    # RoboMME (names from checkout, suites from its docstring, descriptions from this package).
+    rm_names = _try(
+        warnings,
+        "RoboMME",
+        "envs/robomme.py:ROBOMME_TASKS",
+        hint_ver,
+        lambda: _read_literal(envs, "robomme.py", "ROBOMME_TASKS"),
+    )
+    rm_desc = (
+        _try(
+            warnings,
+            "RoboMME",
+            "data/robomme_task_descriptions.json",
+            "shipped with this package",
+            lambda: _load_descriptions(data, "robomme_task_descriptions.json"),
+        )
+        or {}
+    )
+    suite_of: dict[str, str] = {}
+    doc = (
+        _try(
+            warnings,
+            "RoboMME",
+            "envs/robomme.py docstring",
+            hint_ver,
+            lambda: _read_docstring(envs, "robomme.py"),
+        )
+        or ""
+    )
+    for line in doc.splitlines():
+        mm = re.match(r"\s*(Counting|Permanence|Reference|Imitation):\s*(.+)", line)
+        if mm:
+            for t in mm.group(2).split(","):
+                suite_of[t.strip()] = mm.group(1)
+    if rm_names:
+        m = _BENCHMARKS["robomme"]
+        for n in rm_names:
+            entries.append(
+                TaskEntry(
+                    m.name,
+                    m.env_type,
+                    n,
+                    rm_desc.get(n) or None,
+                    suite_of.get(n),
+                    upstream_url=m.upstream_url,
+                    extra=m.extra,
+                )
+            )
+
+    # Upstream-only suites/groups (LIBERO, LIBERO-plus, RoboCasa) + single-task envs.
+    libero_suites = _try(
+        warnings,
+        "LIBERO",
+        "envs/libero.py:TASK_SUITE_MAX_STEPS",
+        hint_ver,
+        lambda: list(_read_literal(envs, "libero.py", "TASK_SUITE_MAX_STEPS")),
+    )
+    for env_type in ("libero", "libero_plus"):
+        m = _BENCHMARKS[env_type]
+        for suite in libero_suites or []:
+            entries.append(
+                TaskEntry(
+                    m.name,
+                    m.env_type,
+                    suite,
+                    category="suite",
+                    enumerable=False,
+                    upstream_url=m.upstream_url,
+                    extra=m.extra,
+                )
+            )
+    rc_groups = _try(
+        warnings,
+        "RoboCasa",
+        "envs/robocasa.py:_TASK_GROUP_SPLITS",
+        hint_ver,
+        lambda: list(_read_literal(envs, "robocasa.py", "_TASK_GROUP_SPLITS")),
+    )
+    m = _BENCHMARKS["robocasa"]
+    for g in rc_groups or []:
+        entries.append(
+            TaskEntry(
+                m.name,
+                m.env_type,
+                g,
+                category="group",
+                enumerable=False,
+                upstream_url=m.upstream_url,
+                extra=m.extra,
+            )
+        )
+
+    defaults = _try(warnings, "PushT/Aloha", "envs/configs.py", hint_ver, lambda: _scan_env_types(envs)) or {}
+    for env_type in ("pusht", "aloha"):
+        m = _BENCHMARKS[env_type]
+        entries.append(
+            TaskEntry(
+                m.name,
+                m.env_type,
+                defaults.get(env_type) or env_type,
+                enumerable=False,
+                upstream_url=m.upstream_url,
+                extra=m.extra,
+            )
+        )
+
+    return entries, warnings

get_embodied_tasks/cli.py

@@ -0,0 +1,195 @@
+# Copyright 2025. Apache-2.0.
+"""`get-embodied-tasks` dispatcher.
+
+Resolves an embodied-AI task query across enabled backends (LeRobot, ...) and prints,
+per match, the dataset + ready-to-run train/eval commands. Facts come from each
+backend's adapter; this layer only routes and merges. Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+
+from get_embodied_tasks.backends.base import Backend
+from get_embodied_tasks.backends.lerobot import LeRobotBackend
+
+_ADAPTERS: dict[str, type[Backend]] = {"lerobot": LeRobotBackend}
+_CONFIG = Path(__file__).parent / "backends.toml"
+
+
+def _load_backends(only: str | None = None) -> list[Backend]:
+    cfg = tomllib.loads(_CONFIG.read_text())
+    backends: list[Backend] = []
+    for name, spec in cfg.items():
+        if not spec.get("enabled", True):
+            continue
+        if only and name != only:
+            continue
+        adapter = _ADAPTERS.get(spec.get("adapter", name))
+        if adapter:
+            backends.append(adapter())
+    return backends
+
+
+# --- rendering -------------------------------------------------------------
+
+
+def _render_bundle(b: dict) -> str:
+    head = f"### [{b['backend']}] {b['benchmark']} — `{b['task']}`"
+    if b.get("category"):
+        head += f" ({b['category']})"
+    lines = [head]
+    if b.get("description"):
+        lines.append(b["description"])
+    d = b.get("dataset")
+    if d:
+        note = f" ({d['note']})" if d.get("note") else ""
+        lines.append(f"- **Dataset:** [{d['repo_id']}]({d['url']}){note}")
+    else:
+        lines.append("- **Dataset:** none published — data is generated locally (see the benchmark docs)")
+    if not b.get("enumerable", True):
+        lines.append("- _suite/group; concrete tasks come from the upstream package_")
+    lines.append(f"- **Train:** `{b['train_command']}`")
+    lines.append(f"- **Eval:**  `{b['eval_command']}`")
+    lines.append(f"- _policy `{b['policy']}` is a default; swap via `--policy.type=`_")
+    return "\n".join(lines)
+
+
+def _render(query: str, matches: list[dict], suggestions: list[dict]) -> str:
+    out: list[str] = []
+    if matches:
+        out.append(f"## Tasks matching {query!r}\n")
+        out.append("\n\n".join(_render_bundle(b) for b in matches))
+    else:
+        out.append(f"## No exact match for {query!r}\n")
+        if suggestions:
+            out.append("Closest existing tasks to adapt from:\n")
+            out.append("\n\n".join(_render_bundle(b) for b in suggestions))
+        else:
+            out.append(
+                "No task matched across the available backends. Next: research whether another "
+                "open-source project/dataset covers it; if none, draft an implementation plan."
+            )
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _emit_warnings(warnings: list[dict]) -> None:
+    if not warnings:
+        return
+    print("⚠ Diagnostics — some catalog facts could not be read:", file=sys.stderr)
+    for w in warnings:
+        print(f"  - [{w['benchmark']}] {w['what']} @ {w['where']} — {w['hint']}", file=sys.stderr)
+
+
+# --- subcommands -----------------------------------------------------------
+
+
+def _doctor(only: str | None) -> int:
+    backends = _load_backends(only)
+    if not backends:
+        print("No backends enabled in backends.toml.")
+        return 1
+    rc = 0
+    for be in backends:
+        res = be.locate()
+        print(f"## backend: {be.name}")
+        print(f"- located: {'yes' if res else 'NO'} ({res.source}) — {res.detail}")
+        if not res:
+            print("  → set the env var, vendor under third_party/ei_ws/, or pip install it.")
+            rc = 1
+            continue
+        all_bundles, warnings = be.dump()
+        from collections import Counter
+
+        by_b = Counter(b["benchmark"] for b in all_bundles)
+        with_ds = sum(1 for b in all_bundles if b["dataset"])
+        print(f"- tasks: {len(all_bundles)} across {len(by_b)} benchmarks; {with_ds} with a dataset")
+        print(f"- benchmarks: {dict(by_b)}")
+        if warnings:
+            rc = 1
+            print(f"- ⚠ {len(warnings)} warning(s):")
+            for w in warnings:
+                print(f"    [{w['benchmark']}] {w['what']} @ {w['where']} — {w['hint']}")
+        else:
+            print("- ✓ no warnings")
+    return rc
+
+
+def _query(args: argparse.Namespace) -> int:
+    backends = _load_backends(args.backend)
+    matches: list[dict] = []
+    suggestions: list[dict] = []
+    warnings: list[dict] = []
+    for be in backends:
+        if not be.available():
+            warnings.append(
+                {
+                    "benchmark": be.name,
+                    "what": "backend unavailable",
+                    "where": be.locate().detail,
+                    "hint": f"set its env var / vendor it / pip install {be.name}",
+                }
+            )
+            continue
+        if args.dump:
+            b, w = be.dump(args.policy)
+            matches += b
+            warnings += w
+        else:
+            m, s, w = be.bundles(args.query, benchmark=args.benchmark, limit=args.limit, policy=args.policy)
+            matches += m
+            suggestions += s
+            warnings += w
+
+    label = args.query or (f"benchmark {args.benchmark}" if args.benchmark else "all tasks")
+    if args.json or args.dump:
+        payload = {"query": label, "matches": matches, "suggestions": suggestions, "warnings": warnings}
+        if args.dump:
+            payload = {"bundles": matches, "warnings": warnings}
+        print(json.dumps(payload, indent=2))
+    else:
+        print(_render(label, matches, suggestions))
+        _emit_warnings(warnings)
+
+    if args.strict and warnings:
+        return 2
+    return 0 if matches else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] == "doctor":
+        sub = argparse.ArgumentParser(prog="get-embodied-tasks doctor")
+        sub.add_argument("--backend", default=None)
+        a = sub.parse_args(argv[1:])
+        return _doctor(a.backend)
+
+    parser = argparse.ArgumentParser(
+        prog="get-embodied-tasks",
+        description="Resolve a task query to its dataset and runnable train/eval commands across backends.",
+    )
+    parser.add_argument("query", nargs="?", help="Task to search for, e.g. 'stack blocks'.")
+    parser.add_argument("-b", "--benchmark", default=None, help="Restrict to a benchmark (name or env.type).")
+    parser.add_argument("--backend", default=None, help="Restrict to a single backend (e.g. lerobot).")
+    parser.add_argument("-n", "--limit", type=int, default=20, help="Max results (default: 20).")
+    parser.add_argument("--policy", default=None, help="Override the policy in generated commands.")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of markdown.")
+    parser.add_argument(
+        "--dump", action="store_true", help="Emit every task (with datasets/commands) as JSON."
+    )
+    parser.add_argument(
+        "--strict", action="store_true", help="Exit non-zero if any diagnostics warning is emitted."
+    )
+    args = parser.parse_args(argv)
+
+    if not args.query and not args.benchmark and not args.dump:
+        parser.error("provide a query, --benchmark, --dump, or the `doctor` subcommand")
+    return _query(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

get_embodied_tasks/data/__init__.py

@@ -0,0 +1 @@
+# Copyright 2025. Apache-2.0.

get_embodied_tasks/data/lerobot_datasets.py

@@ -0,0 +1,69 @@
+# Copyright 2025. Apache-2.0.
+"""LeRobot-backend facts: dataset map + command templates + default policy.
+
+These are the get-task value-add for the LeRobot backend — which Hugging Face
+dataset backs each benchmark and the exact train/eval commands to run it. Kept as
+data (not recalled by a model) so the commands are always correct. Repo ids were
+verified to resolve at authoring time; if LeRobot publishes/moves a dataset, update
+the map here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DatasetInfo:
+    repo_id: str
+    note: str | None = None
+
+    @property
+    def url(self) -> str | None:
+        return f"https://huggingface.co/datasets/{self.repo_id}" if self.repo_id else None
+
+
+# env_type -> canonical HF dataset. None == no downloadable dataset (generated locally).
+DATASETS: dict[str, DatasetInfo | None] = {
+    "pusht": DatasetInfo("lerobot/pusht"),
+    "aloha": DatasetInfo("lerobot/aloha_sim_insertion_human", "several aloha sim datasets exist"),
+    "libero": DatasetInfo("HuggingFaceVLA/libero"),
+    "libero_plus": DatasetInfo("Sylvest/libero_plus_lerobot"),
+    "metaworld": DatasetInfo("lerobot/metaworld_mt50"),
+    "robocasa": DatasetInfo("pepijn223/robocasa_CloseFridge", "per-task; see the RoboCasa docs"),
+    "robotwin": DatasetInfo("lerobot/robotwin_unified"),
+    "robomme": DatasetInfo("lerobot/robomme"),
+    "vlabench": None,  # generates data locally; no published HF dataset
+}
+
+# Benchmarks better served by a small VLA than ACT (multi-task / language-conditioned).
+_VLA_BENCHMARKS = frozenset(
+    {"libero", "libero_plus", "metaworld", "robocasa", "robotwin", "robomme", "vlabench"}
+)
+
+
+def dataset_for(env_type: str) -> DatasetInfo | None:
+    return DATASETS.get(env_type)
+
+
+def default_policy(env_type: str) -> str:
+    """SmolVLA for multi-task/VLA benchmarks, else ACT."""
+    return "smolvla" if env_type in _VLA_BENCHMARKS else "act"
+
+
+def train_command(env_type: str, task_name: str, policy: str | None = None) -> str:
+    policy = policy or default_policy(env_type)
+    ds = dataset_for(env_type)
+    repo = ds.repo_id if ds else "<your_dataset>"
+    return (
+        f"lerobot-train --policy.type={policy} --dataset.repo_id={repo} "
+        f"--env.type={env_type} --env.task={task_name} "
+        f"--batch_size=8 --steps=50000 --policy.device=cuda"
+    )
+
+
+def eval_command(env_type: str, task_name: str, policy_path: str = "<your_policy>") -> str:
+    return (
+        f"lerobot-eval --policy.path={policy_path} "
+        f"--env.type={env_type} --env.task={task_name} --policy.device=cuda"
+    )

get_embodied_tasks/data/robomme_task_descriptions.json

@@ -0,0 +1,22 @@
+{
+  "_source": "https://robomme.github.io/ (RoboMME official website, 'RoboMME Task Examples' instructions)",
+  "_note": "Verbatim task instructions; keys match ROBOMME_TASKS in robomme.py",
+  "descriptions": {
+    "BinFill": "Put two green cubes into the bin and press the button to stop.",
+    "PickXtimes": "Pick up the blue cube and place it on the target, repeating this pick-and-place action three times, then press the button to stop.",
+    "SwingXtimes": "Pick up the red cube, move it to the right-side target and then to the left-side target, repeating this right-to-left swing motion three times, then put down the cube and press the button to stop.",
+    "StopCube": "Press the button to stop the cube exactly at the target on its third visit.",
+    "VideoUnmask": "Watch the video carefully, then pick up the container hiding the green cube.",
+    "VideoUnmaskSwap": "Watch the video carefully, then pick up the container hiding the blue cube, finally pick up another container hiding the red cube.",
+    "ButtonUnmask": "First press the button, then pick up the container hiding the green cube, finally pick up another container hiding the red cube.",
+    "ButtonUnmaskSwap": "First press both buttons on the table, then pick up the container hiding the red cube.",
+    "PickHighlight": "First press the button, then pick up all highlighted cubes, finally press the button again to stop.",
+    "VideoRepick": "Watch the video carefully, identify the cube that was picked up, then pick up and place down the same cube twice, finally press the button to stop.",
+    "VideoPlaceButton": "Watch the video carefully, then place the blue cube on the target where it was last placed before the button was pressed.",
+    "VideoPlaceOrder": "Watch the video carefully and place the green cube on the third target where it was placed.",
+    "MoveCube": "Watch the video carefully, then move the cube to the target in the same manner shown in the video.",
+    "InsertPeg": "Watch the video carefully, then grasp the same peg at the same end and insert it into the same side of the box as in the video.",
+    "PatternLock": "Watch the video carefully, then use the stick attached to the robot to retrace the same pattern shown in the video.",
+    "RouteStick": "Watch the video carefully, then use the stick attached to the robot to navigate around the sticks on the table, following the same path shown in the video."
+  }
+}

get_embodied_tasks/data/robotwin_task_descriptions.json

@@ -0,0 +1,56 @@
+{
+  "_source": "https://robotwin-platform.github.io/doc/tasks/ (RoboTwin 2.0 official docs)",
+  "_note": "Verbatim task descriptions; keys match ROBOTWIN_TASKS in robotwin.py",
+  "descriptions": {
+    "adjust_bottle": "Pick up the bottle on the table headup with the correct arm.",
+    "beat_block_hammer": "There is a hammer and a block on the table, use the arm to grab the hammer and beat the block.",
+    "blocks_ranking_rgb": "Place the red block, green block, and blue block in the order of red, green, and blue from left to right, placing in a row.",
+    "blocks_ranking_size": "There are three blocks on the table, the color of the blocks is random, move the blocks to the center of the table, and arrange them from largest to smallest, from left to right.",
+    "click_alarmclock": "Click the alarm clock's center of the top side button on the table.",
+    "click_bell": "Click the bell's top center on the table.",
+    "dump_bin_bigbin": "Grab the small bin and pour the balls into the big bin.",
+    "grab_roller": "Use both arms to grab the roller on the table.",
+    "handover_block": "Use the left arm to grasp the red block on the table, handover it to the right arm and place it on the blue pad.",
+    "handover_mic": "Use one arm to grasp the microphone on the table and handover it to the other arm.",
+    "hanging_mug": "Use left arm to pick the mug on the table, rotate the mug and put the mug down in the middle of the table, use the right arm to pick the mug and hang it onto the rack.",
+    "lift_pot": "Use arms to lift the pot.",
+    "move_can_pot": "There is a can and a pot on the table, use one arm to pick up the can and move it to beside the pot.",
+    "move_pillbottle_pad": "Use one arm to pick the pillbottle and place it onto the pad.",
+    "move_playingcard_away": "Use the arm to pick up the playing card and move it away from the table. For example, if the playing card is on the outward side of the table, you should move it further outward side of the table.",
+    "move_stapler_pad": "Use appropriate arm to move the stapler to a colored mat.",
+    "open_laptop": "Use one arm to open the laptop.",
+    "open_microwave": "Use one arm to open the microwave.",
+    "pick_diverse_bottles": "Pick up one bottle with one arm, and pick up another bottle with the other arm.",
+    "pick_dual_bottles": "Pick up one bottle with one arm, and pick up another bottle with the other arm.",
+    "place_a2b_left": "Use appropriate arm to place object A on the left of object B.",
+    "place_a2b_right": "Use appropriate arm to place object A on the right of object B.",
+    "place_bread_basket": "If there is one bread on the table, use one arm to grab the bread and put it in the basket, if there are two breads on the table, use two arms to simultaneously grab up two breads and put them in the basket.",
+    "place_bread_skillet": "If there is one bread on the table, use one arm to grab the bread and put it into the skillet.",
+    "place_burger_fries": "Use dual arm to pick the hamburg and frenchfries and put them onto the tray.",
+    "place_can_basket": "Use one arm to pick up the can, put it into the basket, and use another arm to lift the basket",
+    "place_cans_plasticbox": "Use dual arm to pick and place cans into plasticbox.",
+    "place_container_plate": "Place the container onto the plate.",
+    "place_dual_shoes": "Use both arms to pick up the two shoes on the table and put them in the shoebox, with the shoe tip pointing to the left.",
+    "place_empty_cup": "Use an arm to place the empty cup on the coaster.",
+    "place_fan": "Grab the fan and place it on a colored mat, and make sure the fan is facing the robot.",
+    "place_mouse_pad": "Grab the mouse and place it on a colored mat.",
+    "place_object_basket": "Use one arm to grab the target object and put it in the basket, then use the other arm to grab the basket, and finally move the basket slightly away.",
+    "place_object_scale": "Use one arm to grab the object and put it on the scale.",
+    "place_object_stand": "Use appropriate arm to place the object on the stand.",
+    "place_phone_stand": "Pick up the phone and put it on the phone stand.",
+    "place_shoe": "Use one arm to grab the shoe from the table and place it on the mat.",
+    "press_stapler": "Use one arm to press the stapler.",
+    "put_bottles_dustbin": "Use arms to grab the bottles and put them into the dustbin to the left of the table.",
+    "put_object_cabinet": "Use one arm to open the cabinet's drawer, and use another arm to put the object on the table to the drawer.",
+    "rotate_qrcode": "Use arm to catch the qrcode board on the table, pick it up and rotate to let the qrcode face towards the robot.",
+    "scan_object": "Use one arm to pick the scanner and use the other arm to pick the object, and use the scanner to scan the object.",
+    "shake_bottle": "Shake the bottle with proper arm.",
+    "shake_bottle_horizontally": "Shake the bottle horizontally with proper arm.",
+    "stack_blocks_three": "There are three blocks on the table, the color of the blocks is red, green and blue. Move the blocks to the center of the table, and stack the blue block on the green block, and the green block on the red block.",
+    "stack_blocks_two": "There are two blocks on the table, the color of the blocks is red, green. Move the blocks to the center of the table, and stack the geen block on the red block.",
+    "stack_bowls_three": "Stack the three bowls on top of each other.",
+    "stack_bowls_two": "Stack the two bowls on top of each other.",
+    "stamp_seal": "Grab the stamp and stamp onto the specific color mat.",
+    "turn_switch": "Use the robotic arm to click the switch."
+  }
+}

get_embodied_tasks/discovery.py

@@ -0,0 +1,66 @@
+# Copyright 2025. Apache-2.0.
+"""Locate a backend's checkout, trying several conventions in order.
+
+Precedence (first hit wins):
+  1. `$<ENV_VAR>`                      explicit override (e.g. $LEROBOT_HOME)
+  2. `<cwd>/third_party/ei_ws/<sub>`   vendored inside the current project
+  3. `~/ei_ws/<sub>`                   the global embodied-intelligence workspace
+  4. installed package (`find_spec`)   pip-installed backend, no checkout needed
+
+Returns a `Resolution` describing where the backend was found (or that it wasn't),
+without importing the backend.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Resolution:
+    found: bool
+    source: str  # "env" | "third_party" | "ei_ws" | "installed" | "missing"
+    root: Path | None = None  # checkout root (None for "installed"/"missing")
+    detail: str = ""
+
+    def __bool__(self) -> bool:
+        return self.found
+
+
+def resolve_root(
+    subpath: str, env_var: str | None = None, import_name: str | None = None, cwd: Path | None = None
+) -> Resolution:
+    """Resolve a backend location. `subpath` is the dir name under the ei_ws roots."""
+    cwd = cwd or Path.cwd()
+
+    if env_var and os.environ.get(env_var):
+        p = Path(os.environ[env_var]).expanduser()
+        if p.exists():
+            return Resolution(True, "env", p, f"${env_var}={p}")
+        return Resolution(False, "missing", None, f"${env_var}={p} does not exist")
+
+    candidates = [
+        ("third_party", cwd / "third_party" / "ei_ws" / subpath),
+        ("ei_ws", Path.home() / "ei_ws" / subpath),
+    ]
+    for source, path in candidates:
+        if path.exists():
+            return Resolution(True, source, path, str(path))
+
+    if import_name:
+        spec = importlib.util.find_spec(import_name)
+        if spec and spec.origin:
+            return Resolution(
+                True, "installed", None, f"installed package {import_name} at {Path(spec.origin).parent}"
+            )
+
+    hint = env_var or "the workspace"
+    return Resolution(
+        False,
+        "missing",
+        None,
+        f"not found via ${hint}, ./third_party/ei_ws/{subpath}, ~/ei_ws/{subpath}, or pip",
+    )

get_embodied_tasks/matching.py

@@ -0,0 +1,46 @@
+# Copyright 2025. Apache-2.0.
+"""Query matching over a task corpus: substring + token-subset, with a fuzzy fallback."""
+
+from __future__ import annotations
+
+import difflib
+import re
+
+from get_embodied_tasks.catalog import TaskEntry
+
+
+def _tokenize(text: str) -> set[str]:
+    return set(re.split(r"[-_\s]+", text.lower())) - {""}
+
+
+def find_tasks(
+    entries: list[TaskEntry], query: str, benchmark: str | None = None, limit: int = 20
+) -> tuple[list[TaskEntry], list[TaskEntry]]:
+    """Return (matches, fuzzy_suggestions).
+
+    A match is a substring hit on the entry's search text, or an entry whose tokens
+    contain every query token. When there are no matches, suggestions are the closest
+    task names (difflib) ranked by token overlap.
+    """
+    corpus = entries
+    if benchmark:
+        b = benchmark.lower()
+        corpus = [e for e in corpus if b in (e.benchmark.lower(), e.env_type.lower())]
+
+    q = query.strip().lower()
+    q_tokens = _tokenize(q)
+
+    matches = [e for e in corpus if (q and q in e.search_text) or (q_tokens and q_tokens <= e.tokens)]
+    if matches:
+        matches.sort(key=lambda e: (not e.enumerable, e.benchmark, e.task_name))
+        return matches[:limit], []
+
+    names = [e.task_name for e in corpus]
+    close = set(difflib.get_close_matches(query, names, n=limit, cutoff=0.4))
+    scored: list[tuple[float, TaskEntry]] = []
+    for e in corpus:
+        score = len(q_tokens & e.tokens) + (0.5 if e.task_name in close else 0.0)
+        if score > 0:
+            scored.append((score, e))
+    scored.sort(key=lambda s: (-s[0], s[1].benchmark, s[1].task_name))
+    return [], [e for _, e in scored[:limit]]

get_embodied_tasks-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: get-embodied-tasks
+Version: 0.1.0
+Summary: Resolve an embodied-AI task description to its dataset and ready-to-run train/eval commands across pluggable backends (LeRobot, ...).
+Project-URL: Homepage, https://github.com/OpenGHz/get-embodied-tasks
+Project-URL: Repository, https://github.com/OpenGHz/get-embodied-tasks
+Author: OpenGHz
+License: Apache-2.0
+Keywords: agent-skill,benchmark,datasets,embodied-ai,lerobot,robotics
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Description-Content-Type: text/markdown
+
+# get-embodied-tasks
+
+Resolve an embodied-AI task description to its **existing dataset** and
+**ready-to-run train/eval commands**, across pluggable backends. **LeRobot** is the
+first backend; more can be added. Ships as both a CLI and an agent skill (Claude +
+Codex).
+
+```bash
+get-embodied-tasks "stack blocks"
+#  → [lerobot] RoboTwin stack_blocks_two
+#    Dataset: lerobot/robotwin_unified
+#    Train:   lerobot-train --policy.type=smolvla --dataset.repo_id=lerobot/robotwin_unified ...
+#    Eval:    lerobot-eval  --env.type=robotwin --env.task=stack_blocks_two ...
+```
+
+## Design
+
+- **Facts in the tool, judgment in the skill.** The CLI emits real dataset ids and
+  command flags (never model-recalled). The `SKILL.md` playbook parses a fuzzy task
+  description, calls the CLI, and on a miss researches alternatives or drafts a plan.
+- **Backends are read, not vendored.** The LeRobot adapter reads a *vanilla* LeRobot
+  checkout by AST over its `envs/` source (no import of torch/gymnasium; no patches to
+  LeRobot). RoboTwin/RoboMME task descriptions ship here in `data/`.
+- **Drift is surfaced, never hidden.** If a backend's expected constant/file changes,
+  the catalog emits structured warnings (stderr, `--json` `warnings`, `--strict`,
+  `doctor`) so it can be fixed.
+
+## Install
+
+```bash
+pip install -e .
+bash install.sh        # symlink into ~/.agents/skills (Claude + Codex pick it up)
+```
+
+## Backend discovery
+
+For each backend, in order: `$<ENV_VAR>` → `./third_party/ei_ws/<name>` →
+`~/ei_ws/<name>` → installed package. For LeRobot set `LEROBOT_HOME=<checkout>` or
+just `pip install lerobot`. Configure backends in
+[`src/get_embodied_tasks/backends.toml`](src/get_embodied_tasks/backends.toml).
+
+## CLI
+
+```
+get-embodied-tasks "<query>" [-b BENCHMARK] [--backend NAME] [-n N] [--policy P] [--json]
+get-embodied-tasks --benchmark <b>     # list a benchmark
+get-embodied-tasks --dump              # whole catalog as JSON
+get-embodied-tasks doctor              # backend health / drift report
+```
+
+## Reference docs (per backend)
+
+[`docs/backends/lerobot/`](docs/backends/lerobot/) holds reference material for the
+LeRobot backend, regeneratable from a vanilla checkout:
+
+- [`cli_reference.md`](docs/backends/lerobot/cli_reference.md) — every `lerobot-*` command + its extra (generated)
+- [`components_reference.md`](docs/backends/lerobot/components_reference.md) — registered policies/robots/teleops/cameras/optimizers/schedulers/processors (generated)
+- [`troubleshooting.md`](docs/backends/lerobot/troubleshooting.md) — consolidated FAQ (hand-written, links upstream)
+
+Refresh the generated ones:
+
+```bash
+python docs/scripts/gen_lerobot_reference.py --lerobot-root <checkout>   # or rely on discovery
+python docs/scripts/gen_lerobot_reference.py --check                     # CI: fail if stale
+```
+
+## Adding a backend
+
+Add an adapter under `src/get_embodied_tasks/backends/` implementing
+`backends/base.py:Backend`, register it in `cli.py:_ADAPTERS`, and add a table to
+`backends.toml`.

get_embodied_tasks-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+get_embodied_tasks/__init__.py,sha256=t4xMYNZ57wK_qGztXaSvQeKVUJ7qwKp8xD_QmXMwwXE,137
+get_embodied_tasks/backends.toml,sha256=lEeNKlRm-J4hZ3d8S8OnT6UqqjuVOCdykNC2KSE6dYc,411
+get_embodied_tasks/catalog.py,sha256=7fd7gv79LOtc8pvZvcfsN58F_X1do-XIlEiYjP1Gfs8,11495
+get_embodied_tasks/cli.py,sha256=u026atAWwMNYQYB9vktv8m0kdzUvUbpVKV-7PZePSWc,7427
+get_embodied_tasks/discovery.py,sha256=dcISWq6keh39Jt41-YVFnn6Q1Izj48Da4TZ7SloJ9KI,2243
+get_embodied_tasks/matching.py,sha256=J3QUmIrPrhimlJ7fBnoXg3FUrpBbVBR86rxDYPFjmKw,1654
+get_embodied_tasks/backends/__init__.py,sha256=dJZfelbSlqWJYcO6ramHYvTMnZtegylLGC5zx78aElg,30
+get_embodied_tasks/backends/base.py,sha256=ynCMJ9xWXHHbTWK920ZwU1MAfn-KjyXg7CcwKtk9T2c,1016
+get_embodied_tasks/backends/lerobot.py,sha256=oLW0cYcg75yjB3rhfKf4z4kGNrlS8TVvyc2_DsTuko8,3646
+get_embodied_tasks/data/__init__.py,sha256=dJZfelbSlqWJYcO6ramHYvTMnZtegylLGC5zx78aElg,30
+get_embodied_tasks/data/lerobot_datasets.py,sha256=T1CiOSqgazCrCLp2zlqCKomb573MdsY-sdh5MhApG9s,2612
+get_embodied_tasks/data/robomme_task_descriptions.json,sha256=0rbEg_EVDhGyA-0zl4hAdPf4S0Whme2z7PDdNKr8WjE,2427
+get_embodied_tasks/data/robotwin_task_descriptions.json,sha256=MfCetXbFJKZ2aehNIVk15JEXU4AkbOeqAKkGYoZWUew,5691
+get_embodied_tasks-0.1.0.dist-info/METADATA,sha256=2N1-mjSbsOj1ChEL5_LjaFgUHyjHFXImOBkfyS2YlqA,3780
+get_embodied_tasks-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+get_embodied_tasks-0.1.0.dist-info/entry_points.txt,sha256=nFwS_I7hrs8ejrjkH9_RIJ_-G235JxKZK2lktnToICg,67
+get_embodied_tasks-0.1.0.dist-info/RECORD,,

get_embodied_tasks-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

get_embodied_tasks-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+get-embodied-tasks = get_embodied_tasks.cli:main