qamule-trajectory 0.1.0__tar.gz

qamule_trajectory-0.1.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.3
+Name: qamule-trajectory
+Version: 0.1.0
+Summary: Python trajectory toolkit for QAMule VLM and agent training datasets.
+Author: lanbaoshen
+Author-email: lanbaoshen <lanbaoshen@icloud.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# qamule-trajectory
+
+Python trajectory toolkit for QAMule VLM and agent training datasets.
+
+## Install
+
+```bash
+uv sync
+```
+
+## CLI
+
+Start the local viewer for the current directory and open the browser:
+
+```bash
+uv run qamule-trajectory
+```
+
+Start the viewer quietly without opening the browser:
+
+```bash
+uv run qamule-trajectory -q
+```
+
+Quiet mode still prints the local viewer URL.
+
+Create a session:
+
+```bash
+uv run qamule-trajectory init dataset/open_wifi_20260626_120000 \
+	--instruction "Open Wi-Fi in Settings" \
+	--app com.android.settings \
+	--device-model "Pixel 8" \
+	--resolution 1080 2400 \
+	--android 14
+```
+
+Append a step after saving `step_001.jpg` in the session directory:
+
+```bash
+uv run qamule-trajectory append dataset/open_wifi_20260626_120000 \
+	--screenshot step_001.jpg \
+	--current-app com.android.settings/.Settings \
+	--thought "I can see the Settings home screen." \
+	--action '{"type":"click","x":540,"y":620}'
+```
+
+Validate a dataset, session, or `trajectory.json`:
+
+```bash
+uv run qamule-trajectory validate dataset/
+```
+
+Browse trajectories locally:
+
+```bash
+uv run qamule-trajectory view dataset/ --port 8932
+```
+
+`-q` and `--quiet` are accepted for quiet viewer mode.
+
+## Trajectory Layout
+
+Each session is a directory named `{task_slug}_YYYYMMDD_HHMMSS` containing `trajectory.json` and sequential screenshots named `step_001.jpg`, `step_002.jpg`, and so on.

qamule_trajectory-0.1.0/README.md

@@ -0,0 +1,64 @@
+# qamule-trajectory
+
+Python trajectory toolkit for QAMule VLM and agent training datasets.
+
+## Install
+
+```bash
+uv sync
+```
+
+## CLI
+
+Start the local viewer for the current directory and open the browser:
+
+```bash
+uv run qamule-trajectory
+```
+
+Start the viewer quietly without opening the browser:
+
+```bash
+uv run qamule-trajectory -q
+```
+
+Quiet mode still prints the local viewer URL.
+
+Create a session:
+
+```bash
+uv run qamule-trajectory init dataset/open_wifi_20260626_120000 \
+	--instruction "Open Wi-Fi in Settings" \
+	--app com.android.settings \
+	--device-model "Pixel 8" \
+	--resolution 1080 2400 \
+	--android 14
+```
+
+Append a step after saving `step_001.jpg` in the session directory:
+
+```bash
+uv run qamule-trajectory append dataset/open_wifi_20260626_120000 \
+	--screenshot step_001.jpg \
+	--current-app com.android.settings/.Settings \
+	--thought "I can see the Settings home screen." \
+	--action '{"type":"click","x":540,"y":620}'
+```
+
+Validate a dataset, session, or `trajectory.json`:
+
+```bash
+uv run qamule-trajectory validate dataset/
+```
+
+Browse trajectories locally:
+
+```bash
+uv run qamule-trajectory view dataset/ --port 8932
+```
+
+`-q` and `--quiet` are accepted for quiet viewer mode.
+
+## Trajectory Layout
+
+Each session is a directory named `{task_slug}_YYYYMMDD_HHMMSS` containing `trajectory.json` and sequential screenshots named `step_001.jpg`, `step_002.jpg`, and so on.

qamule_trajectory-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "qamule-trajectory"
+version = "0.1.0"
+description = "Python trajectory toolkit for QAMule VLM and agent training datasets."
+readme = "README.md"
+authors = [
+    { name = "lanbaoshen", email = "lanbaoshen@icloud.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.scripts]
+qamule-trajectory = "qamule_trajectory.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.8,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]

qamule_trajectory-0.1.0/src/qamule_trajectory/__init__.py

@@ -0,0 +1,19 @@
+"""Python trajectory toolkit for QAMule datasets."""
+
+from .core import TrajectoryError, append_step, expected_screenshot_name, init_session, load_trajectory, parse_action
+from .schema import STEP_JPG_RE, TASK_SLUG_RE, TERMINAL_ACTIONS
+from .validation import ValidationResult, validate_path
+
+__all__ = [
+	"STEP_JPG_RE",
+	"TASK_SLUG_RE",
+	"TERMINAL_ACTIONS",
+	"TrajectoryError",
+	"ValidationResult",
+	"append_step",
+	"expected_screenshot_name",
+	"init_session",
+	"load_trajectory",
+	"parse_action",
+	"validate_path",
+]

qamule_trajectory-0.1.0/src/qamule_trajectory/cli.py

@@ -0,0 +1,146 @@
+"""Command line interface for qamule-trajectory."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import TrajectoryError, append_step, init_session, parse_bool
+from .validation import format_validation_result, validate_path
+from .viewer import serve
+
+
+def _arg_bool(value: str) -> bool:
+    try:
+        return parse_bool(value)
+    except TrajectoryError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from exc
+
+
+def _cmd_init(args: argparse.Namespace) -> int:
+    session_dir = init_session(
+        args.session_dir,
+        instruction=args.instruction,
+        app=args.app,
+        device_model=args.device_model,
+        resolution=args.resolution,
+        android=args.android,
+        task_slug=args.task_slug,
+        dataset_root=args.dataset_root,
+        force=args.force,
+    )
+    print(session_dir)
+    return 0
+
+
+def _cmd_append(args: argparse.Namespace) -> int:
+    trajectory_path = append_step(
+        args.session_dir,
+        screenshot=args.screenshot,
+        current_app=args.current_app,
+        thought=args.thought,
+        raw_action=args.action,
+        step_success=args.step_success,
+    )
+    print(trajectory_path)
+    return 0
+
+
+def _cmd_validate(args: argparse.Namespace) -> int:
+    result = validate_path(args.input_path)
+    print(format_validation_result(result))
+    return 0 if result.ok else 1
+
+
+def _cmd_view(args: argparse.Namespace) -> int:
+    try:
+        quiet = bool(getattr(args, "quiet", False))
+        serve(args.dataset_dir, port=args.port, open_browser=not args.no_open and not quiet, quiet=quiet)
+    except ValueError as exc:
+        print(f"[FATAL] {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qamule-trajectory",
+        description="Create, validate, and browse QAMule trajectory datasets.",
+    )
+    parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="start the default viewer quietly without opening the browser",
+    )
+    parser.add_argument("--port", type=int, default=8932, help="port for the default viewer")
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="create a new trajectory.json for a session")
+    init_parser.add_argument("session_dir", nargs="?", help="session directory, e.g. dataset/open_wifi_20260514_101530")
+    init_parser.add_argument("--task-slug", help="create dataset/{task_slug}_YYYYMMDD_HHMMSS automatically")
+    init_parser.add_argument("--dataset-root", default="dataset", help="dataset root used with --task-slug")
+    init_parser.add_argument("--instruction", required=True, help="human task instruction")
+    init_parser.add_argument("--app", required=True, help="target app package")
+    init_parser.add_argument("--device-model", required=True, help="device model")
+    init_parser.add_argument(
+        "--resolution",
+        required=True,
+        nargs=2,
+        type=int,
+        metavar=("WIDTH", "HEIGHT"),
+        help="device resolution as width height",
+    )
+    init_parser.add_argument("--android", required=True, help="android version")
+    init_parser.add_argument("--force", action="store_true", help="overwrite an existing trajectory.json")
+    init_parser.set_defaults(func=_cmd_init)
+
+    append_parser = subparsers.add_parser("append", help="append one recorded step to trajectory.json")
+    append_parser.add_argument("session_dir", help="session directory that already contains trajectory.json")
+    append_parser.add_argument("--screenshot", required=True, help="step screenshot file name, e.g. step_001.jpg")
+    append_parser.add_argument("--current-app", required=True, help="current package/activity string")
+    append_parser.add_argument("--thought", required=True, help="observation and reasoning for this step")
+    append_parser.add_argument("--action", required=True, help="JSON object describing the action")
+    append_parser.add_argument(
+        "--step-success",
+        default=True,
+        type=_arg_bool,
+        help="whether this recorded step executed successfully (default: true)",
+    )
+    append_parser.set_defaults(func=_cmd_append)
+
+    validate_parser = subparsers.add_parser("validate", help="validate a dataset, session, or trajectory.json")
+    validate_parser.add_argument("input_path", nargs="?", default="dataset", help="dataset dir, session dir, or trajectory.json")
+    validate_parser.set_defaults(func=_cmd_validate)
+
+    view_parser = subparsers.add_parser("view", help="serve a local trajectory viewer")
+    view_parser.add_argument("dataset_dir", nargs="?", default=".", help="dataset directory to browse")
+    view_parser.add_argument("--port", type=int, default=8932, help="port to serve on")
+    view_parser.add_argument("--no-open", action="store_true", help="do not open the browser automatically")
+    view_parser.add_argument(
+        "-q",
+        "--quiet",
+        action="store_true",
+        help="serve quietly without opening the browser",
+    )
+    view_parser.set_defaults(func=_cmd_view)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        args.func = _cmd_view
+        args.dataset_dir = "."
+        args.no_open = False
+    try:
+        return args.func(args)
+    except TrajectoryError as exc:
+        print(f"[FATAL] {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

qamule_trajectory-0.1.0/src/qamule_trajectory/core.py

@@ -0,0 +1,187 @@
+"""Core helpers for creating and updating trajectory sessions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from datetime import datetime
+import json
+from pathlib import Path
+from typing import Any
+
+from .schema import STEP_JPG_RE, TASK_SLUG_RE, TERMINAL_ACTIONS
+
+
+class TrajectoryError(ValueError):
+    """Raised when a trajectory operation cannot be completed."""
+
+
+def parse_bool(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in {"true", "1", "yes", "y"}:
+        return True
+    if lowered in {"false", "0", "no", "n"}:
+        return False
+    raise TrajectoryError("expected true/false")
+
+
+def expected_screenshot_name(step_number: int) -> str:
+    return f"step_{step_number:03d}.jpg"
+
+
+def parse_action(raw_action: str) -> dict[str, Any]:
+    try:
+        action = json.loads(raw_action)
+    except json.JSONDecodeError as exc:
+        raise TrajectoryError(
+            f"invalid action JSON: line {exc.lineno}, column {exc.colno}: {exc.msg}"
+        ) from exc
+
+    if not isinstance(action, dict):
+        raise TrajectoryError("action must decode to a JSON object")
+
+    action_type = action.get("type")
+    if not isinstance(action_type, str) or not action_type.strip():
+        raise TrajectoryError("action.type must be a non-empty string")
+
+    return action
+
+
+def load_trajectory(session_dir: Path) -> tuple[Path, dict[str, Any]]:
+    trajectory_path = session_dir / "trajectory.json"
+    if not trajectory_path.is_file():
+        raise TrajectoryError(f"trajectory.json not found in session directory: {session_dir}")
+
+    try:
+        data = json.loads(trajectory_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise TrajectoryError(
+            f"invalid JSON in {trajectory_path}: line {exc.lineno}, column {exc.colno}: {exc.msg}"
+        ) from exc
+    except OSError as exc:
+        raise TrajectoryError(f"cannot read {trajectory_path}: {exc}") from exc
+
+    if not isinstance(data, dict):
+        raise TrajectoryError("trajectory.json must contain a top-level object")
+
+    steps = data.get("steps")
+    if not isinstance(steps, list):
+        raise TrajectoryError("trajectory.json field 'steps' must be an array")
+
+    return trajectory_path, data
+
+
+def write_trajectory(trajectory_path: Path, data: dict[str, Any]) -> None:
+    data["total_steps"] = len(data.get("steps", []))
+    payload = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
+    trajectory_path.write_text(payload, encoding="utf-8")
+
+
+def resolve_session_dir(
+    session_dir: str | Path | None,
+    *,
+    task_slug: str | None = None,
+    dataset_root: str | Path = "dataset",
+    now: Callable[[], datetime] = datetime.now,
+) -> Path:
+    if session_dir and task_slug:
+        raise TrajectoryError("pass either SESSION_DIR or --task-slug, not both")
+    if session_dir:
+        return Path(session_dir)
+    if not task_slug:
+        raise TrajectoryError("init requires either SESSION_DIR or --task-slug")
+    if not TASK_SLUG_RE.match(task_slug):
+        raise TrajectoryError("task slug must match pattern '[A-Za-z0-9][A-Za-z0-9_-]*'")
+
+    timestamp = now().strftime("%Y%m%d_%H%M%S")
+    return Path(dataset_root) / f"{task_slug}_{timestamp}"
+
+
+def init_session(
+    session_dir: str | Path | None,
+    *,
+    instruction: str,
+    app: str,
+    device_model: str,
+    resolution: tuple[int, int] | list[int],
+    android: str,
+    task_slug: str | None = None,
+    dataset_root: str | Path = "dataset",
+    force: bool = False,
+) -> Path:
+    resolved_session_dir = resolve_session_dir(
+        session_dir,
+        task_slug=task_slug,
+        dataset_root=dataset_root,
+    )
+    resolved_session_dir.mkdir(parents=True, exist_ok=True)
+
+    trajectory_path = resolved_session_dir / "trajectory.json"
+    if trajectory_path.exists() and not force:
+        raise TrajectoryError(f"trajectory.json already exists: {trajectory_path}. Use --force to overwrite it.")
+
+    data: dict[str, Any] = {
+        "task_id": resolved_session_dir.name,
+        "instruction": instruction,
+        "app": app,
+        "device": {
+            "model": device_model,
+            "resolution": [int(resolution[0]), int(resolution[1])],
+            "android": android,
+        },
+        "steps": [],
+        "success": False,
+        "total_steps": 0,
+    }
+
+    write_trajectory(trajectory_path, data)
+    return resolved_session_dir
+
+
+def append_step(
+    session_dir: str | Path,
+    *,
+    screenshot: str,
+    current_app: str,
+    thought: str,
+    raw_action: str,
+    step_success: bool = True,
+) -> Path:
+    resolved_session_dir = Path(session_dir)
+    trajectory_path, data = load_trajectory(resolved_session_dir)
+    steps = data["steps"]
+
+    if steps:
+        last_action = steps[-1].get("action", {})
+        if isinstance(last_action, dict) and last_action.get("type") in TERMINAL_ACTIONS:
+            raise TrajectoryError("cannot append after a terminal action; start a new session or edit the JSON manually")
+
+    action = parse_action(raw_action)
+    step_number = len(steps) + 1
+    expected_name = expected_screenshot_name(step_number)
+
+    if not STEP_JPG_RE.match(screenshot):
+        raise TrajectoryError("screenshot must match pattern 'step_{NNN}.jpg'")
+    if screenshot != expected_name:
+        raise TrajectoryError(f"screenshot for step {step_number} must be named {expected_name}")
+    if not (resolved_session_dir / screenshot).is_file():
+        raise TrajectoryError(f"screenshot not found in session directory: {screenshot}")
+
+    steps.append(
+        {
+            "step": step_number,
+            "screenshot": screenshot,
+            "current_app": current_app,
+            "thought": thought,
+            "action": action,
+            "success": step_success,
+        }
+    )
+
+    action_type = action.get("type")
+    if action_type == "finish":
+        data["success"] = True
+    elif action_type == "impossible":
+        data["success"] = False
+
+    write_trajectory(trajectory_path, data)
+    return trajectory_path

qamule_trajectory-0.1.0/src/qamule_trajectory/schema.py

@@ -0,0 +1,30 @@
+"""Shared trajectory schema constants."""
+
+from __future__ import annotations
+
+import re
+
+STEP_JPG_RE = re.compile(r"^step_(\d{3})\.jpg$")
+TASK_SLUG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*$")
+SESSION_DIR_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]*_\d{8}_\d{6}$")
+
+TERMINAL_ACTIONS = {"finish", "impossible"}
+
+ACTION_REQUIRED_PARAMS = {
+	"app_start": {"app"},
+	"click": {"x", "y"},
+	"long_click": {"x", "y"},
+	"swipe": {"x1", "y1", "x2", "y2"},
+	"type": {"text"},
+	"press": {"key"},
+	"wait": {"duration"},
+	"finish": {"reason"},
+	"impossible": {"reason"},
+}
+
+NUMERIC_ACTION_KEYS = {
+	"click": {"x", "y"},
+	"long_click": {"x", "y"},
+	"swipe": {"x1", "y1", "x2", "y2"},
+	"wait": {"duration"},
+}