# MEV Annotation Toolkit

This directory contains the code used to generate multi-event video annotations.

## Layout

- `qwen/`: local Qwen3-VL annotation, event segmentation, and camera-motion classification scripts.
- `gemini/`: Gemini API wrappers that reuse the Qwen annotation pipeline schema and post-processing.
- `scripts/multi-event/`: shell launchers for batched multi-GPU annotation runs.

Generated annotations, logs, checkpoints, and datasets are intentionally not included. Keep them under local runtime directories such as `data/`, `annotations/`, `logs/`, and `checkpoints/`.

## Basic Usage

Run Qwen annotation on segmented videos:

```bash
bash scripts/multi-event/run_multi_event_annotations.sh data/example_segments annotations/qwen/multi_event/output.json --resume
```

Run Gemini annotation:

```bash
export GEMINI_API_KEY=your_api_key
python gemini/generate_multi_event_annotations.py --input data/example_segments --output annotations/gemini/multi_event/output.json --recursive --resume
```

Segment a single video into event intervals:

```bash
python qwen/segment_events_qwen3vl.py data/video.mp4 --output annotations/segments/video_events.json
```

Classify camera motion for a single video:

```bash
python qwen/classify_camera_motion_qwen3vl.py data/video.mp4 --output annotations/camera/video_camera.json
```

## Notes

- The Qwen scripts expect a local model checkpoint via `--model-path` or `MODEL_PATH`.
- The shell launchers derive all paths from this directory and environment variables.
- `ffmpeg` and `ffprobe` must be available on `PATH`.
- Gemini scripts use `GEMINI_API_KEY` or `GOOGLE_API_KEY`.