roboapi 0.4.2__py3-none-any.whl

roboapi/semantics.py

@@ -0,0 +1,6 @@
+"""The model contract shared by every supported embodiment."""
+
+TRAINING_FRAME = "training"
+HOME_POSE7 = (-0.13, -0.46, 0.49, 0.0, 0.0, 1.0, 0.0)  # metres, quaternion wxyz
+ACTION_HZ = 30
+ACTION_DT = 1.0 / ACTION_HZ

roboapi/tasks.py

@@ -0,0 +1,337 @@
+"""Host-local task history, human feedback and camera recordings."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+import queue
+import shutil
+import subprocess
+import threading
+import time
+import uuid
+
+logger = logging.getLogger(__name__)
+
+
+def _write_json(path: Path, value: dict) -> None:
+    temporary = path.with_suffix(".tmp")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n")
+    temporary.replace(path)
+
+
+class _Recording:
+    """Sample the existing camera owner; encoding never runs on the control thread."""
+
+    def __init__(self, camera, path: Path):
+        self.camera, self.path = camera, path
+        self.stop = threading.Event()
+        self.error: str | None = None
+        self.thread = threading.Thread(target=self._capture, name="task-camera", daemon=True)
+        self.thread.start()
+
+    def _capture(self):
+        writer = None
+        temporary = self.path.with_name(self.path.stem + ".partial.mp4")
+        try:
+            import imageio_ffmpeg
+
+            deadline = time.monotonic()
+            while not self.stop.is_set():
+                frame, _ = self.camera.read()
+                if writer is None:
+                    height, width = frame.shape[:2]
+                    writer = imageio_ffmpeg.write_frames(
+                        str(temporary), (width, height), fps=30, codec="libx264",
+                        pix_fmt_in="rgb24", pix_fmt_out="yuv420p", macro_block_size=2,
+                        output_params=["-preset", "ultrafast", "-crf", "23", "-threads", "2"],
+                        ffmpeg_timeout=15,
+                    )
+                    writer.send(None)
+                writer.send(frame)
+                deadline = max(deadline + 1 / 30, time.monotonic())
+                self.stop.wait(max(0, deadline - time.monotonic()))
+        except Exception as exc:
+            self.error = str(exc)
+        finally:
+            if writer is not None:
+                try:
+                    writer.close()
+                    if temporary.exists() and temporary.stat().st_size:
+                        temporary.replace(self.path)
+                except Exception as exc:
+                    self.error = str(exc)
+            temporary.unlink(missing_ok=True)
+
+
+class TaskArchive:
+    """One current task, many stopped runs, one rating and one published video.
+
+    A single publication queue preserves run order even if a task is continued
+    while the previous recording is still closing. Completed segments remain on
+    disk so continuing or restarting the host never re-encodes old video.
+    """
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root).expanduser()
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+        self._tasks: dict[str, dict] = {}
+        self._active: tuple[str, float, _Recording | None] | None = None
+        self._pending: dict[str, int] = {}
+        self._queue: queue.Queue = queue.Queue()
+        self._worker: threading.Thread | None = None
+        self._state_path = self.root / "settings.json"
+        self._state = {"enabled": True, "current_id": None}
+        if self._state_path.exists():
+            self._state.update(json.loads(self._state_path.read_text()))
+        for path in self.root.glob("*/metadata.json"):
+            task = json.loads(path.read_text())
+            # A process exit cannot leave a task pretending it is still running.
+            if task["active"] or task["recording"] in ("recording", "saving"):
+                task.update(active=False, stop_reason="interrupted",
+                            recording="ready" if (path.parent / "video.mp4").exists() else "error",
+                            recording_error="Recording interrupted by host restart")
+                _write_json(path, task)
+            self._tasks[task["id"]] = task
+
+    def _save(self, task: dict) -> None:
+        _write_json(self.root / task["id"] / "metadata.json", task)
+
+    def _snapshot(self, task: dict) -> dict:
+        result = dict(task)
+        result["video_available"] = (self.root / task["id"] / "video.mp4").is_file()
+        if self._active and self._active[0] == task["id"]:
+            _, started, recording = self._active
+            result["elapsed_s"] = round(task["elapsed_s"] + time.monotonic() - started, 2)
+            if recording and recording.error:
+                result.update(recording="error", recording_error=recording.error)
+        return result
+
+    def current(self) -> dict | None:
+        with self._lock:
+            task = self._tasks.get(self._state["current_id"])
+            return self._snapshot(task) if task else None
+
+    def list(self) -> list[dict]:
+        with self._lock:
+            return [self._snapshot(task) for task in
+                    sorted(self._tasks.values(), key=lambda item: item["created_at"], reverse=True)]
+
+    def get(self, task_id: str) -> dict:
+        with self._lock:
+            return self._snapshot(self._tasks[task_id])
+
+    def settings(self, enabled: bool | None = None) -> dict:
+        """Recording preference applies when the next run starts."""
+        with self._lock:
+            if enabled is not None:
+                if not isinstance(enabled, bool):
+                    raise ValueError("enabled must be a boolean")
+                self._state["enabled"] = enabled
+                _write_json(self._state_path, self._state)
+            return {"enabled": self._state["enabled"]}
+
+    def begin(self, instruction: str, model: str | None = None, source: str = "web",
+              camera=None, *, new_task: bool = False) -> dict:
+        instruction = instruction.strip()
+        with self._lock:
+            if self._active:
+                raise RuntimeError("a task is already running")
+            now = time.time()
+            task = self._tasks.get(self._state["current_id"])
+            if new_task or task is None or task["instruction"] != instruction:
+                task = {
+                    "id": uuid.uuid4().hex, "instruction": instruction, "model": model,
+                    "source": source, "created_at": now, "updated_at": now,
+                    "elapsed_s": 0.0, "runs": 0, "rating": None, "note": "",
+                    "stop_reason": None, "active": False, "recording": "off",
+                    "recording_error": None, "infer_ms": None,
+                }
+                (self.root / task["id"] / ".segments").mkdir(parents=True)
+            else:
+                task = dict(task)
+            task.update(active=True, updated_at=now, model=model, source=source,
+                        runs=task["runs"] + 1, stop_reason=None, recording_error=None)
+            record = self._state["enabled"] and camera is not None
+            task["recording"] = "recording" if record else "off"
+            state = {**self._state, "current_id": task["id"]}
+            # Persist before creating a recording thread: failed storage cannot leak one.
+            self._save(task)
+            _write_json(self._state_path, state)
+            self._tasks[task["id"]], self._state = task, state
+            recording = None
+            if record:
+                path = self.root / task["id"] / ".segments" / f'{task["runs"]:08d}.mp4'
+                try:
+                    recording = _Recording(camera, path)
+                except Exception as exc:
+                    task.update(recording="error", recording_error=str(exc))
+            self._active = (task["id"], time.monotonic(), recording)
+            return self._snapshot(task)
+
+    def finish(self, reason: str | None = None, infer_ms: float | None = None) -> dict | None:
+        """Stop sampling immediately; MP4 publication proceeds in the background."""
+        with self._lock:
+            if self._active is None:
+                return self.current()
+            task_id, started, recording = self._active
+            self._active = None
+            task = self._tasks[task_id]
+            task.update(active=False, updated_at=time.time(), stop_reason=reason,
+                        elapsed_s=round(task["elapsed_s"] + time.monotonic() - started, 2),
+                        infer_ms=infer_ms)
+            if recording:
+                recording.stop.set()
+                task["recording"] = "saving"
+                self._pending[task_id] = self._pending.get(task_id, 0) + 1
+                self._queue.put((task_id, recording))
+                if self._worker is None:
+                    self._worker = threading.Thread(target=self._publish_runs, name="task-video", daemon=True)
+                    self._worker.start()
+            self._save(task)
+            return self._snapshot(task)
+
+    def _publish_runs(self):
+        while True:
+            job = self._queue.get()
+            if job is None:
+                self._queue.task_done()
+                return
+            task_id, recording = job
+            recording.thread.join()
+            error = recording.error
+            try:
+                if recording.path.exists():
+                    self._publish_video(task_id, recording.path)
+            except Exception as exc:
+                error = str(exc)
+                logger.warning("Task recording could not be saved: %s", exc)
+            with self._lock:
+                task = self._tasks[task_id]
+                self._pending[task_id] -= 1
+                if error and int(recording.path.stem) == task["runs"]:
+                    task["recording_error"] = error
+                if not task["active"] and not self._pending[task_id]:
+                    available = (self.root / task_id / "video.mp4").exists()
+                    task["recording"] = "error" if task["recording_error"] else "ready" if available else "off"
+                try:
+                    self._save(task)
+                except OSError:
+                    logger.exception("Task recording metadata could not be saved")
+            self._queue.task_done()
+
+    def _publish_video(self, task_id: str, last_segment: Path) -> None:
+        import imageio_ffmpeg
+
+        directory = self.root / task_id
+        # Include only this and earlier runs, even when a later capture has finished.
+        segments = sorted(path for path in (directory / ".segments").glob("*.mp4")
+                          if not path.name.endswith(".partial.mp4") and path.name <= last_segment.name)
+        manifest = directory / ".concat.txt"
+        manifest.write_text("".join(f"file '.segments/{path.name}'\n" for path in segments))
+        temporary = directory / ".video.mp4"
+        try:
+            result = subprocess.run(
+                [imageio_ffmpeg.get_ffmpeg_exe(), "-hide_banner", "-loglevel", "error",
+                 "-y", "-f", "concat", "-safe", "0", "-i", str(manifest), "-c", "copy",
+                 "-movflags", "+faststart", str(temporary)],
+                capture_output=True, timeout=120,
+            )
+            if result.returncode:
+                raise RuntimeError(result.stderr.decode(errors="replace").strip())
+            temporary.replace(directory / "video.mp4")
+        finally:
+            manifest.unlink(missing_ok=True)
+            temporary.unlink(missing_ok=True)
+
+    def feedback(self, task_id: str, rating: str | None, note: str = "") -> dict:
+        if rating not in (None, "up", "down"):
+            raise ValueError("rating must be up, down or null")
+        if not isinstance(note, str):
+            raise ValueError("note must be text")
+        with self._lock:
+            task = self._tasks[task_id]
+            task.update(rating=rating, note=note, updated_at=time.time())
+            self._save(task)
+            return self._snapshot(task)
+
+    def delete(self, task_id: str) -> None:
+        with self._lock:
+            task = self._tasks[task_id]
+            if task["active"] or self._pending.get(task_id):
+                raise RuntimeError("stop the task and wait for its video before deleting it")
+            shutil.rmtree(self.root / task_id)
+            del self._tasks[task_id]
+            if self._state["current_id"] == task_id:
+                self._state["current_id"] = None
+                _write_json(self._state_path, self._state)
+
+    def storage(self) -> dict:
+        """Actual task-directory usage, including the source clips used for continuation."""
+        with self._lock:
+            tasks = []
+            for task in sorted(self._tasks.values(), key=lambda item: item["created_at"], reverse=True):
+                total = video = 0
+                for path in (self.root / task["id"]).rglob("*"):
+                    if not path.is_file():
+                        continue
+                    try:
+                        size = path.stat().st_size
+                    except FileNotFoundError:  # A recorder may publish a file during this scan.
+                        continue
+                    total += size
+                    if path.suffix == ".mp4":
+                        video += size
+                tasks.append({**self._snapshot(task), "bytes": total, "video_bytes": video,
+                              "busy": task["active"] or bool(self._pending.get(task["id"]))})
+            return {"tasks": tasks, "total_bytes": sum(task["bytes"] for task in tasks),
+                    "video_bytes": sum(task["video_bytes"] for task in tasks),
+                    "recordings_count": sum(task["video_bytes"] > 0 for task in tasks),
+                    "recording_enabled": self._state["enabled"]}
+
+    def cleanup(self, kind: str, task_ids: list[str] | None = None) -> dict:
+        """Clear selected or all archives, leaving live and finalizing runs untouched."""
+        if kind not in ("recordings", "tasks"):
+            raise ValueError("kind must be recordings or tasks")
+        with self._lock:
+            ids = list(self._tasks) if task_ids is None else list(dict.fromkeys(task_ids))
+            tasks = [self._tasks[task_id] for task_id in ids]
+            cleared = skipped = 0
+            for task in tasks:
+                task_id = task["id"]
+                if task["active"] or self._pending.get(task_id):
+                    skipped += 1
+                    continue
+                if kind == "tasks":
+                    self.delete(task_id)
+                else:
+                    directory = self.root / task_id
+                    for path in directory.glob("*.mp4"):
+                        path.unlink(missing_ok=True)
+                    segments = directory / ".segments"
+                    if segments.exists():
+                        shutil.rmtree(segments)
+                    segments.mkdir()
+                    task.update(recording="off", recording_error=None)
+                    self._save(task)
+                cleared += 1
+            return {"cleared": cleared, "skipped": skipped}
+
+    def video_path(self, task_id: str) -> Path:
+        with self._lock:
+            self._tasks[task_id]  # Resolve membership before constructing any filesystem path.
+            path = self.root / task_id / "video.mp4"
+            if not path.is_file():
+                raise FileNotFoundError("this task has no recording")
+            return path
+
+    def close(self) -> None:
+        """Flush at application shutdown, never from Robot Stop."""
+        self.finish("shutdown")
+        self._queue.join()
+        if self._worker:
+            self._queue.put(None)
+            self._worker.join()
+            self._worker = None

roboapi/web/__init__.py

@@ -0,0 +1,5 @@
+"""Browser interface for the shared runtime."""
+
+from .server import start_web
+
+__all__ = ["start_web"]

roboapi/web/presets.py

@@ -0,0 +1,44 @@
+"""Installation-local browser instruction presets, independent of policy execution."""
+
+import json
+import os
+from pathlib import Path
+import tempfile
+import threading
+
+
+class Presets:
+    def __init__(self, config_path):
+        self.path = Path(config_path).expanduser().resolve().with_name("instruction-presets.json")
+        self._lock = threading.Lock()
+
+    @staticmethod
+    def validate(instructions):
+        if not isinstance(instructions, list) or len(instructions) > 20:
+            raise ValueError("presets must be a list of at most 20 instructions")
+        if any(not isinstance(item, str) or not 1 <= len(item.strip()) <= 1000 for item in instructions):
+            raise ValueError("each preset must contain 1–1000 characters")
+        return [item.strip() for item in instructions]
+
+    def read(self):
+        with self._lock:
+            try:
+                return self.validate(json.loads(self.path.read_text()))
+            except FileNotFoundError:
+                return []
+
+    def save(self, instructions):
+        instructions = self.validate(instructions)
+        with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            temporary = None
+            try:
+                with tempfile.NamedTemporaryFile(mode="w", dir=self.path.parent, delete=False) as out:
+                    temporary = out.name
+                    json.dump(instructions, out, ensure_ascii=False, indent=2)
+                    out.write("\n")
+                os.replace(temporary, self.path)
+            finally:
+                if temporary is not None:
+                    Path(temporary).unlink(missing_ok=True)
+        return instructions