Generate Route Titles and Descriptions from GPX files with LLMs and {ellmer}

Overview

The gen_description() function in the gpxtoolbox package leverages the ellmer package to interact with large language models (LLMs) and generate meaningful titles and descriptions for GPX routes. This vignette demonstrates how to use gen_description() and provides detailed steps for setting up and using the ellmer package.

Prerequisites

Before using gen_description(), ensure you have the following:

An API key for the LLM platform you wish to use (e.g., OpenAI, Azure OpenAI, Anthropic Claude, or Google Gemini).
The ellmer package installed.
A GPX file processed using analyse_gpx() to generate route statistics.

Installation

Install the gpxtoolbox package from GitHub:

# Install devtools if not already installed
install.packages("devtools")

# Install gpxtoolbox
devtools::install_github("martinctc/gpxtoolbox")

Install the ellmer package:

install.packages("ellmer")

Example Workflow

Step 1: Process a GPX File

Use the analyse_gpx() function to process a GPX file and generate route statistics.

library(gpxtoolbox)

# Path to the example GPX file
example_gpx_path <- system.file("extdata", "icc_intro_ride.gpx", package = "gpxtoolbox")

# Analyse the GPX file and get route statistics
stats <- analyse_gpx(example_gpx_path, return = "stats")
print(stats)

Step 2: Generate a Title and Description

Use the gen_description() function to generate a title and description for the route. Specify the platform, API key, and model to use.

library(ellmer)

# Generate a title and description using OpenAI
result <- gen_description(
  stats = stats,
  platform = "openai",
  api_key = Sys.getenv("OPENAI_API_KEY"),
  model = "gpt-3.5-turbo"
)

cat(result)

Step 3: Customizing the Prompt

The gen_description() function uses a default prompt to generate the title and description. You can customize the prompt by modifying the desc_prompt.md file included in the package.

Detailed Explanation of Parameters

`stats`

A named list of route statistics generated by analyse_gpx(). This includes details such as total distance, elevation gain/loss, start and end points, and key locations at 25%, 50%, and 75% of the route.

`platform`

Specifies the LLM platform to use. Examples include: - "openai" for OpenAI models. - "azure" for Azure OpenAI models. - "gemini" for Google Gemini models.

`api_key`

The API key for the specified LLM platform. This should be stored securely, for example, using Sys.getenv().

`model`

The model to use for generating the response (e.g., "gpt-3.5-turbo", "gpt-4").

Additional Arguments

You can pass additional arguments to the ellmer package’s chat_*() functions, such as temperature and max_tokens.

Conclusion

The gen_description() function provides a powerful way to generate meaningful titles and descriptions for GPX routes using LLMs. By leveraging the ellmer package, you can easily integrate various LLM platforms into your workflow. This functionality is particularly useful for creating engaging content for cycling or hiking routes.

Martin Chan

2025-04-14