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.
