qamule-trajectory

Python trajectory toolkit for QAMule VLM and agent training datasets.

Install

uv sync

CLI

Start the local viewer for the current directory and open the browser:

uv run qamule-trajectory

Start the viewer quietly without opening the browser:

uv run qamule-trajectory -q

Quiet mode still prints the local viewer URL.

Create a session:

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:

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:

uv run qamule-trajectory validate dataset/

Browse trajectories locally:

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.