travel-destination-brochure

Build travel destination scenarios and brochures from a city name. Fetches street-level and landmark imagery from OpenStreetCam and Wikimedia Commons, then uses VLM Run (vlmrun) to generate a travel video and a travel plan. Use when the user wants a travel brochure, destination guide, travel video, or travel planning for a city.

# Travel Destination Brochure & Video

Create travel brochures, videos, and 1-day plans for a destination city by combining OpenStreetCam street-level photos, Wikimedia Commons imagery, and VLM Run for video and copy.

## Prerequisites

Before starting, ensure you have:

- **Python 3.10 or higher** installed
- **Internet connection** (for downloading images and API access)
- **VLMRUN_API_KEY** (optional, but required for video and travel plan generation)

**No API keys required for:**
- OpenStreetCam (public read access)
- Wikimedia Commons (public access)
- Nominatim geocoding (public access)

## Installation Steps

### Step 1: Verify Python Installation

Check if Python 3.10+ is installed:

**Windows (PowerShell):**
```powershell
python --version
# Should show Python 3.10.x or higher
```

**macOS/Linux:**
```bash
python3 --version
# Should show Python 3.10.x or higher
```

If Python is not installed or is an older version:
- **Windows**: Download from [python.org](https://www.python.org/downloads/)
- **macOS**: `brew install python@3.11` (or use python.org installer)
- **Linux**: `sudo apt install python3.11` (Ubuntu/Debian) or use your distribution's package manager

### Step 2: Install uv (Package Manager)

**Windows (PowerShell):**
```powershell
# Using pip
pip install uv

# Or using PowerShell installer
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS/Linux:**
```bash
# Using pip
pip install uv

# Or using curl installer
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Verify installation:**
```bash
uv --version
```

### Step 3: Create Virtual Environment

Navigate to the skill directory and create a virtual environment:

**Windows (PowerShell):**
```powershell
cd c:\Users\mehed\.claude\skills\travel-destination-brochure
uv venv
.venv\Scripts\Activate.ps1
```

**macOS/Linux:**
```bash
cd ~/.claude/skills/travel-destination-brochure
uv venv
source .venv/bin/activate
```

**Note:** You should see `(.venv)` in your terminal prompt when activated.

### Step 4: Install Dependencies

Install the required packages:

```bash
# Install vlmrun CLI (required for video and travel plan generation)
uv pip install "vlmrun[cli]"

# Install requests (required for API calls)
uv pip install requests
```

**Verify installation:**
```bash
vlmrun --version
python -c "import requests; print(requests.__version__)"
```

### Step 5: Set Up VLMRUN_API_KEY (Optional but Recommended)

To generate travel videos and plans, you need a VLMRUN API key:

**Windows (PowerShell):**
```powershell
# Set for current session
Check .env file for api key

$env:VLMRUN_API_KEY="your-api-key-here"

# Set permanently (User-level)
[System.Environment]::SetEnvironmentVariable('VLMRUN_API_KEY', 'your-api-key-here', 'User')
```

**macOS/Linux:**
```bash
# Set for current session
export VLMRUN_API_KEY="your-api-key-here"

# Set permanently (add to ~/.bashrc or ~/.zshrc)
echo 'export VLMRUN_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
```

**Verify environment variable:**

Read **.env** file to find api keys

```bash
# Windows PowerShell
echo $env:VLMRUN_API_KEY

# macOS/Linux
echo $VLMRUN_API_KEY
```

### Step 6: Verify Installation

Test that everything works:

```bash
# Test geocoding (should work without API key)
uv run scripts/geocode_city.py "Paris, France"

# Test vlmrun (if API key is set)
vlmrun --help
```

**Installation Complete!** You're ready to generate travel brochures.

## Quick Start (Recommended)

Use the simplified all-in-one script that handles everything automatically:

**Windows (PowerShell):**
```powershell
uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"
```

**macOS/Linux:**
```bash
uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"
```

**Alternative (if uv is not available):**
```bash
python scripts/simple_travel_brochure.py --city "Doha, Qatar"
```

This script will:
1. Geocode the city name to coordinates
2. Fetch 3 street-level photos from OpenStreetCam
3. Fetch 2 landmark images from Wikimedia Commons (total 5 images)
4. Generate a 30-second travel video using vlmrun (if `VLMRUN_API_KEY` is set)
5. Generate a one-day travel plan using vlmrun (if `VLMRUN_API_KEY` is set)
6. Clean up temporary files automatically

**Options:**
- `--output DIR` — Output directory (default: `./travel_brochure`)
- `--osc-count N` — Number of OpenStreetCam photos (default: 3)
- `--commons-count N` — Number of Commons images (default: 2)

**Note:** Set the `VLMRUN_API_KEY` environment variable to enable video and travel plan generation. The script will skip video generation gracefully if the API key is not set.

**Example:**
```bash
uv run scripts/simple_travel_brochure.py --city "Paris, France" --output ./paris_trip
```

**Output:**
- `images/` — Downloaded photos (5 images total)
- `manifest.json` — Metadata about the city, coordinates, and image paths
- `video/` — Generated travel video (if VLMRUN_API_KEY is set)
- `travel_plan.md` — One-day travel itinerary (if VLMRUN_API_KEY is set)

---

## Advanced: Step-by-Step Workflow

For more control over each step, use the individual scripts below.

### Workflow Overview

1. **Collect input** – Get destination city from the user.
2. **Geocode** – Resolve city name to coordinates (lat, lng).
3. **Fetch imagery & info** – OpenStreetCam (nearby photos) + Wikimedia Commons (search images and metadata).
4. **Generate assets** – Use **vlmrun** to create a short travel video and a travel plan from the collected images and info.

All paths below are relative to the directory containing this SKILL.md. 

**Run scripts using:**
- `uv run scripts/script_name.py` (recommended - handles dependencies automatically via PEP 723)
- `python scripts/script_name.py` (if dependencies are already installed)

### Step 1: Get Destination City

Ask the user: *"Which city do you want the travel brochure and video for?"* Use the exact city name (and country/region if ambiguous) for geocoding and Commons search.

### Step 2: Geocode City

Resolve city name to latitude/longitude (e.g. for OpenStreetCam and optional Commons geo-search).

```bash
uv run scripts/geocode_city.py "Paris, France"
# Or: python scripts/geocode_city.py "Tokyo"
```

Output: JSON with `lat`, `lng`, `display_name`. Use these in Steps 3–4.

### Step 3: Fetch OpenStreetCam Photos

OpenStreetCam provides street-level imagery. Base URL: `https://api.openstreetcam.org/`.

- **Nearby sequences:** `POST /nearby-tracks` — body: `lat`, `lng`, `distance` (km).
- **Nearby photos:** `POST /1.0/list/nearby-photos/` — body: `lat`, `lng`, `radius` (meters), optional `page`, `ipp`.

No `access_token` required for these read endpoints. Use `scripts/fetch_openstreetcam.py` to request photos and optionally download thumbnails/full images into a folder.

```bash
uv run scripts/fetch_openstreetcam.py --lat 48.8566 --lng 2.3522 --radius 2000 --output ./assets/osc --max-photos 20
```

Produces: image files under `--output` and a small manifest (e.g. `osc_manifest.json`) with captions/locations if available.

### Step 4: Fetch Wikimedia Commons Images & Info

Commons provides landmark and cultural images. API: `https://commons.wikimedia.org/w/api.php`.

- **Search:** `action=query`, `list=search`, `srsearch=<city or landmark>`, `srnamespace=6` (File namespace).
- **Image URLs and metadata:** `action=query`, `prop=imageinfo`, `iiprop=url|extmetadata`, `titles=File:...`.

Use `scripts/fetch_commons.py` to search by destination name, resolve file URLs, and optionally download to a folder.

```bash
uv run scripts/fetch_commons.py --query "Paris landmarks" --output ./assets/commons --max-images 15
```

Produces: image files and a manifest (e.g. `commons_manifest.json`) with captions/descriptions from Commons.

### Step 5: Aggregate Manifest for vlmrun

Combine OSC and Commons manifests (and optionally add short text lines per image) into a single manifest or list that you can pass to vlmrun (e.g. paths + one short caption per image). The