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.

Security Scan

The code and runtime instructions are consistent with the stated purpose (fetch public images, build a manifest, and call the vlmrun CLI to generate video/itineraries), but the install instructions ask users to run remote installer scripts and there are a few operational risks to be aware of.

Purpose & Capability

The name and description match the actual files and behavior: scripts geocode a city (Nominatim), download public images from Wikimedia Commons and OpenStreetCam, assemble them into an images/ manifest, and call the vlmrun CLI to generate video and a travel plan. Required credentials are limited to an optional VLMRUN_API_KEY for vlmrun; no unrelated cloud credentials or secrets are requested.

Instruction Scope

SKILL.md instructs the user to create a venv, install dependencies, download images, and run the provided scripts. The runtime steps stay within the stated purpose and the scripts only read/write files within the output directories. One noteworthy instruction-level detail: SKILL.md suggests running remote install commands (curl | sh and PowerShell irm | iex) to install 'uv' — see install_mechanism. The docs also instruct users how to set VLMRUN_API_KEY in environment or .env. The scripts do not attempt to read other environment variables or system config paths.

Install Mechanism

There is no formal install spec, but SKILL.md recommends installing the 'uv' tool using remote installer scripts (https://astral.sh/uv/install.sh and install.ps1) with curl/PowerShell piped to shell/iex. Executing remote installers with ExecutionPolicy Bypass or piping shell scripts from the network is a higher-risk operation and should be treated with caution. The rest of the dependencies are normal Python packages (requests, vlmrun[cli]).

Credentials

Only an optional VLMRUN_API_KEY (and optional VLMRUN_BASE_URL in .env_template) is referenced to enable vlmrun-based video/plan generation. No other secrets are requested. The scripts themselves do not read arbitrary environment variables beyond what the user supplies for vlmrun; they default to public APIs for image fetching.

Persistence & Privilege

The skill is instruction-only and does not request always:true. It creates local files and suggests creating a virtual environment (.venv) inside the skill directory — normal behavior. It does not modify other skills or system-wide agent settings.

Assessment

This skill appears to do what it says: fetch public images for a city, save them locally, and call the vlmrun CLI (if you provide its API key) to generate a video and itinerary. Before installing/running: 1) Avoid blindly running the suggested remote installer commands (curl | sh or PowerShell irm | iex). Prefer installing packages from your normal package manager (pip install uv) or review the install script from https://astral.sh before executing it. 2) Verify the origin and trustworthiness of the 'vlmrun' CLI/package you install (it will send image data to an external service). 3) Run the scripts inside an isolated virtual environment or sandbox to limit accidental system changes and to control network/file access. 4) Be aware images are downloaded to disk (check output directories) and may contain large files; check disk/quota. 5) If you care about privacy, note that images and the images themselves are sent to the external vlmrun service when generating video/plan; do not provide private or sensitive imagery. If you want more confidence, you can audit the Python files (they are included) and test them with --no-download or --skip-commons/--skip-osc to observe behavior without external downloads.

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):

python --version
# Should show Python 3.10.x or higher

macOS/Linux:

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
• 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):

# Using pip
pip install uv

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

macOS/Linux:

# Using pip
pip install uv

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

Verify installation:

uv --version

Step 3: Create Virtual Environment

Navigate to the skill directory and create a virtual environment:

Windows (PowerShell):

cd c:\Users\mehed\.claude\skills\travel-destination-brochure
uv venv
.venv\Scripts\Activate.ps1

macOS/Linux:

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:

# 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:

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):

# 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:

# 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

# Windows PowerShell
echo $env:VLMRUN_API_KEY

# macOS/Linux
echo $VLMRUN_API_KEY

Step 6: Verify Installation

Test that everything works:

# 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):

uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"

macOS/Linux:

uv run scripts/simple_travel_brochure.py --city "Doha, Qatar"

Alternative (if uv is not available):

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:

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).

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.

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.

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 pipeline script can do this.

uv run scripts/run_travel_pipeline.py --city "Paris, France" --output-dir ./travel_output

This script should: geocode → fetch OSC → fetch Commons → write images/ and manifest.json (or manifest.txt) under --output-dir.

Step 6: Generate Video and Travel Plan with vlmrun

Use the vlmrun-cli-skill workflow: ensure vlmrun is installed and VLMRUN_API_KEY is set.

Travel video – Pass the collected images and a single prompt so the model produces a short travel video (e.g. 30 seconds). Prefer -o to save the artifact.

Note: If VLMRUN_API_KEY is set as an environment variable, you can omit --api-key:

# Using environment variable (recommended)
vlmrun chat "Create a 30-second travel video showcasing these images of [CITY]. Add subtle captions with the location names. Keep a calm, inspiring travel-documentary style." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg -i ./travel_output/images/photo3.jpg ... -o ./travel_output/video

# Or using --api-key from .env, flag directly
vlmrun --api-key "your-api-key-here" chat "Create a 30-second travel video showcasing these images of [CITY]. Add subtle captions with the location names. Keep a calm, inspiring travel-documentary style." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg -i ./travel_output/images/photo3.jpg ... -o ./travel_output/video

If the number of files is large, reference the manifest and pass a subset (e.g. up to 10–15 representative images) or use a prompt that says “using the attached images in order.”

Travel plan (1-day) – Use the same images plus a text prompt to get a narrative or bullet-point plan.

# Using environment variable (recommended)
vlmrun chat "Using these images and their locations, write a one-day travel plan for [CITY]: morning, midday, and evening activities with specific places and practical tips. Output as structured markdown (headings and bullet points)." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg ... -o ./travel_output

# Or using --api-key flag directly
vlmrun --api-key "your-api-key-here" chat "Using these images and their locations, write a one-day travel plan for [CITY]: morning, midday, and evening activities with specific places and practical tips. Output as structured markdown (headings and bullet points)." -i ./travel_output/images/photo1.jpg -i ./travel_output/images/photo2.jpg ... -o ./travel_output

Save the model’s text response (and any artifact) under --output-dir (e.g. travel_plan.md).

Scripts Reference

Script	Purpose
scripts/geocode_city.py	City name → lat, lng (Nominatim)
scripts/fetch_openstreetcam.py	Fetch/download OpenStreetCam photos by lat/lng/radius
scripts/fetch_commons.py	Search and download Wikimedia Commons images by query
scripts/run_travel_pipeline.py	Run geocode + OSC + Commons and write manifest + images

API References

• OpenStreetCam: API Reference — nearby-tracks, list/nearby-photos, auth only for uploads.
• Wikimedia Commons: Commons API — action=query, list=search, prop=imageinfo; MediaWiki API help.
• vlmrun: Use the vlmrun-cli-skill for setup, env vars, and all vlmrun chat options.

Checklist for a Complete Run

• User provided destination city (and country if needed).
• Geocoded city and confirmed lat/lng.
• Fetched OpenStreetCam photos; saved images and manifest.
• Fetched Commons images for the destination; saved images and manifest.
• Built aggregated manifest/images under one output dir.
• Ran vlmrun with collected images to generate travel video; saved artifact with -o.
• Ran vlmrun with same (or subset) images to generate travel plan; saved text as markdown.

Troubleshooting

Installation Issues

Python not found:

• Windows: Ensure Python is added to PATH during installation, or use py instead of python
• macOS/Linux: Use python3 instead of python

uv command not found:

• Restart your terminal after installation
• Windows: Check if uv is in your PATH: $env:PATH
• macOS/Linux: Ensure ~/.cargo/bin or ~/.local/bin is in your PATH

Virtual environment activation fails:

• Windows PowerShell: If you get an execution policy error, run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
• Windows CMD: Use .venv\Scripts\activate.bat instead of .ps1
• macOS/Linux: Ensure you're using source .venv/bin/activate (not ./.venv/bin/activate)

vlmrun not found:

• Ensure virtual environment is activated
• Reinstall: uv pip install "vlmrun[cli]"
• Verify: which vlmrun (macOS/Linux) or where.exe vlmrun (Windows)

Runtime Issues

• Geocode fails – Try adding country/region, or use “City, Country” format.
• OpenStreetCam returns few/no results:
• Increase radius parameter (default: 2000m, try 5000m or 10000m)
• Try city center coordinates instead of outskirts
• Some regions have sparse coverage; try nearby major cities
• Commons returns few results – Broaden query (e.g. “City tourism”, “City sights”).
• vlmrun errors:
• Confirm VLMRUN_API_KEY is set correctly: echo $VLMRUN_API_KEY (macOS/Linux) or echo $env:VLMRUN_API_KEY (Windows)
• Check network connection
• Reduce number of input images if hitting API limits (try 5-10 images instead of 20+)
• Verify API key is valid and has sufficient credits/quota

Script execution errors:

• Ensure you're in the correct directory (skill root directory)
• Check that virtual environment is activated
• Verify all dependencies are installed: uv pip list

Example End-to-End

# 1) Ask user for city, then run pipeline (e.g. "Paris, France")
uv run scripts/run_travel_pipeline.py --city "Paris, France" --output-dir ./travel_output

# 2) Generate travel video (use image paths from travel_output/images/ or image_paths.txt)
vlmrun chat "Create a 30-second travel video from these images of Paris. Add short location captions. Calm documentary style." -i ./travel_output/images/img_0000.jpg -i ./travel_output/images/img_0001.jpg -o ./travel_output/video

# 3) Generate 1-day travel plan (same images)
vlmrun chat "Using these photos of Paris, write a one-day travel plan (morning, midday, evening) with specific places and tips in markdown." -i ./travel_output/images/img_0000.jpg -i ./travel_output/images/img_0001.jpg -o ./travel_output

Quick Reference: Key URLs

• OpenStreetCam API base: https://api.openstreetcam.org/
• Commons API: https://commons.wikimedia.org/w/api.php
• Nominatim geocoding: https://nominatim.openstreetmap.org/search?q=<query>&format=json