Use KeywordLens confidently inside Lightroom Classic.

KeywordLens is an Adobe Lightroom Classic plug-in that uses visual AI, Lightroom metadata, and optional location intelligence to add useful keywords, titles, captions, and searchable records to your catalog.

This manual covers day-to-day use of the plug-in. For installation steps, see the installation guide.

Contents

1. What KeywordLens Does
2. First-Run Setup
3. Lightroom Menu Items
4. Plug-in Manager Settings
5. Analyze Photos with AI
6. Natural Language Search
7. Import Existing Keywords
8. Keyword Taxonomy and Scaffolding
9. Location Intelligence and Offline Packs
10. Interactive Pack Builder
11. Keyword Feedback and Accuracy Reports
12. Keyword Hygiene and Rehoming Tools
13. Tips for Better Results
14. Troubleshooting

What KeywordLens Does

KeywordLens analyzes selected Lightroom photos and can add:

• Keywords, including subject, setting, mood, technique, category, and resolved place names.
• Titles, when the photo does not already have a title or the prior title was AI-generated.
• Captions, when the photo does not already have a caption or the prior caption was AI-generated.
• Local search records, so analyzed or imported photos can be found with natural-language queries.
• Optional Lightroom location fields when GPS coordinates are resolved into human-readable place names.

KeywordLens is conservative by default. Existing keywords are preserved unless you explicitly enable Replace existing keywords for a run. Existing user-written titles and captions are also preserved.

Supported AI providers:

First-Run Setup

Before loading the plug-in in Lightroom, the automated setup scripts can help with provider setup. If you choose Ollama, the Windows script offers to install Ollama with winget when it is missing, and the macOS script offers to install Ollama with Homebrew when it is missing. Both scripts can also pull a recommended vision model. Use -SkipProviderSetup on Windows or --skip-provider-setup on macOS/Linux if you want to handle provider setup yourself.

After the plug-in is added to Lightroom, KeywordLens opens an in-Lightroom setup wizard. Use it to choose the AI providers you want available, enter credentials or local server URLs, test each provider, and choose the provider used for analysis.

The in-Lightroom wizard does not create cloud accounts or install local model software. Before running analysis, make sure at least one provider is ready:

• Ollama: install Ollama, pull a vision-capable model, and keep Ollama running.
• LM Studio: start the local server with a vision model loaded.
• Google Gemini: create an API key in Google AI Studio.
• Azure OpenAI: deploy a vision-capable model and configure either an API key or Entra ID credentials.

You can reopen the wizard later from File -> Plug-in Manager -> KeywordLens -> AI Provider -> Re-run Setup Wizard....

Lightroom Menu Items

KeywordLens adds its main commands under Library -> Plug-in Extras:

Some development builds also show an [Eval] Export... item. It is for internal evaluation workflows and is not needed for normal photo management.

Analyze Photos with AI is also available from File -> Plug-in Extras.

Plug-in Manager Settings

Open settings with File -> Plug-in Manager -> KeywordLens. The sections are ordered by how often most users need them.

AI Provider

Choose the active provider and edit provider-specific settings.

• Provider used for analysis controls which provider runs new analysis jobs.
• The provider tabs let you edit Azure OpenAI, Ollama, Google Gemini, and LM Studio settings without changing the active provider.
• Each provider tab includes Test Connection.
• Providers can have optional Pass 1 and Consensus model fields. Pass 1 can use a cheaper/faster model for category detection; Consensus lets a second model contribute keywords when multi-model consensus is enabled.

Azure OpenAI supports an API Style selector. Leave it on Auto-detect unless you have a custom deployment name that needs a specific API surface.

Analysis Behavior

Use this section to control how batches run.

AI Analysis Categories

This editor controls what the AI is asked to identify during two-pass analysis. Categories include common photography subjects such as wildlife, landscape, architecture, portrait, macro, street, event, food, abstract, and others.

Each category contains tag types. For example, wildlife can ask for species, scientific name, behavior, and habitat. Most users can leave this section alone, but it is useful if you want KeywordLens to focus on a specific domain.

This is different from Keyword Taxonomy: analysis categories shape what the AI returns; taxonomy controls where returned keywords land in your Lightroom keyword tree.

Location

Location settings control whether KeywordLens can use or resolve place information.

The resolver order is Offline Pack -> Google Places -> Nominatim, depending on which options are enabled and available. Offline-to-online fallback is off by default to preserve the privacy expectation of offline packs.

Keyword Taxonomy

Use taxonomy settings when you maintain a Lightroom keyword hierarchy and want AI output to land inside it.

Supported import sources:

• Active Lightroom catalog.
• A .txt file exported from Lightroom with Metadata > Export Keywords....
• The bundled starter taxonomy template.

After a taxonomy is imported, KeywordLens writes the canonical snapshot to ~/.keywordlens/taxonomy.json. Enable Use my keyword taxonomy when applying AI keywords to make that snapshot active for analysis. KeywordLens then maps matching AI keywords into your hierarchy and sends a trimmed taxonomy hint to the AI. Also apply parent keywords on each photo is optional and helps Lightroom-native text filtering and Smart Collections match parent names.

Canonical Keyword Scaffold

The scaffold handles useful keywords that are not yet in your imported taxonomy. When enabled, KeywordLens can synthesize predictable hierarchy paths such as:

Wildlife > Mammal > African Bush Elephant
Architecture > Religious > Church
South Africa > Mpumalanga > Timbavati > Game reserve

The scaffold runs only after the taxonomy resolver fails to find a match. If a scaffold path cannot be composed because required tokens are missing, KeywordLens tries to reuse an existing catalog path for the same leaf name. If that also fails, the keyword is added flat at the root.

The scaffold is enabled by default for wildlife, plants, architecture, and location. You can turn categories off or edit their templates in Plug-in Manager.

Localization & Collections

• Language controls the language requested for AI-generated keywords, titles, captions, and descriptions.
• Collection Set controls where KeywordLens-created collections are placed by default. You can still override collection placement in action dialogs.

The plug-in interface language follows Lightroom's UI language when a KeywordLens translation is available. English and French UI resources are included.

Advanced

Advanced contains backend and export plumbing:

• Server URL is the backend address used by the plug-in. It is read-only until you click Change....
• Auto-start backend on plug-in load starts the local Python backend automatically.
• Test Backend Connection checks /health.
• Export Size and Export Quality control the temporary JPEG sent to the provider.
• System Prompt lets you customize the broad analysis instructions.
• Reset Prompt to Default restores the shipped prompt.

Analyze Photos with AI

1. In Lightroom's Library module, select the photos you want to analyze.
2. Choose Library -> Plug-in Extras -> Analyze Photos with AI.
3. Review the confirmation dialog.
4. Adjust per-run options if needed, then click Analyze.

The confirmation dialog shows the selected provider, effective analysis mode, whether existing keywords will be replaced, whether previously analyzed photos should be re-analyzed, and whether location metadata is included for this run.

During analysis, KeywordLens exports temporary JPEGs, sends them to the backend, writes results to Lightroom, and deletes the temporary files. You can cancel the progress dialog; photos already completed keep their updates.

What Gets Written

The backend also stores the AI baseline locally for search, feedback, accuracy snapshots, and pruning.

Already Analyzed Photos

After a successful run, KeywordLens stamps the photo with KeywordLens metadata and updates its local analyzed-photo tracking. With Skip already analyzed photos enabled, those photos are skipped in future runs. To force a refresh, either uncheck the setting in Plug-in Manager or use the Re-analyze already analyzed photos checkbox in the run dialog.

Failed photos are not marked as successfully analyzed, so re-running the same selection retries them.

Analysis Summary

At the end of a run, KeywordLens reports successes, skipped photos, keywords added, and failures by reason. Depending on settings, the summary can also include confidence counts, context transparency, performance statistics, and a button for Smart Collection suggestions.

Smart Collection suggestions are never created automatically. If you accept them, KeywordLens creates or reuses collections such as AI: Wildlife or Location: Jordan. The collections then auto-grow as future photos match the same Lightroom rules.

Natural Language Search

Use Library -> Plug-in Extras -> Search Photos (Natural Language) to search the backend's local index.

The search dialog asks for:

• A query such as sunset over mountains, studio portrait with red background, or bird in flight.
• Scope: entire catalog or current selection.
• Maximum result count.

Search works against photos that have been analyzed or imported into the backend. Results can be added to a new collection or an existing collection. When a taxonomy is loaded, KeywordLens expands the search index with parent paths so parent terms can match even if parent keywords were not explicitly applied to the photo.

Import Existing Keywords

If your catalog already contains useful keywords, run Import Existing Keywords to Backend so those photos can appear in natural-language search before they are AI-analyzed.

You can import all photos in the catalog or only the current selection. KeywordLens sends existing keywords, titles, and captions to the backend in batches.

Run this after first setup if you already have a mature catalog. Run it again when you manually keyword a significant set of photos that KeywordLens has not analyzed.

Keyword Taxonomy and Scaffolding

Taxonomy and scaffold features help keep Lightroom's Keyword List clean.

Taxonomy Workflow

1. Import your taxonomy from the active catalog, an exported keyword file, or the starter template.
2. Enable Use my keyword taxonomy when applying AI keywords.
3. Optionally enable Also apply parent keywords on each photo if you rely on Lightroom text filters or Smart Collections that search parent names.
4. Re-import after you reorganize keywords in Lightroom.

KeywordLens matches keywords case-insensitively and preserves your catalog's preferred casing when a match is found. Ambiguous leaf names are resolved with context from the other AI keywords on the same photo. When context is not enough, KeywordLens keeps the AI's keyword rather than guessing.

Scaffold Workflow

Leave the scaffold on if you want new species, plants, buildings, and resolved places to be nested instead of appearing as flat top-level keywords. Edit templates only if you want a different hierarchy shape.

For example, the default wildlife scaffold is:

{categoryDisplay} > {animalType} > {commonName}

If the AI returns categoryDisplay=Wildlife, animalType=Mammal, and commonName=African Bush Elephant, KeywordLens creates or reuses Wildlife > Mammal > African Bush Elephant.

The scaffold is strict. If a template token is missing, that template does not produce a partial path for that photo.

Location Intelligence and Offline Packs

Location context can improve titles, captions, and keywords, especially for travel, wildlife, landscape, and architecture photography.

KeywordLens can use:

• Existing Lightroom location fields.
• GPS coordinates from the photo.
• Offline location packs installed on your computer.
• Google Places for precise landmark or POI lookup.
• Nominatim/OpenStreetMap for administrative place names when online geocoding is enabled.

When place resolution succeeds, plain-English place keywords such as landmark, city, region, and country can be added. Raw GPS coordinates and ISO country codes are not added as keywords.

Resolved location write-back is optional. When enabled, KeywordLens writes place names to Lightroom's catalog fields. It does not write XMP sidecars directly; enable Lightroom's Catalog Settings -> Metadata -> Automatically write changes into XMP if you want Lightroom to mirror catalog metadata to sidecar files.

Offline Packs

Offline packs let GPS-only photos resolve to place names without live web lookups. A typical setup uses a global core pack plus optional regional packs for parks, protected areas, landmarks, natural features, or custom named regions.

Use Check Offline Pack Status to inspect installed packs. If your backend has a pack catalog configured, Install Offline Packs From Catalog can install missing or updated packs into the active offline-pack folder.

After installing or rebuilding packs, use Clear Location Cache so future analyses re-resolve coordinates with the new data.

Interactive Pack Builder

Open the builder with Library -> Plug-in Extras -> Open Offline Pack Builder... or visit http://127.0.0.1:8099/tools/pack-builder while the backend is running.

The Pack Builder has two modes:

Basic workflow:

1. Choose POI Pack or Named Region.
2. Select a region by searching, drawing on the map, or importing GeoJSON.
3. For POI packs, choose feature classes and download/preview POIs.
4. For Named Region packs, name and classify each polygon.
5. Build the pack, choosing Install locally and/or Generate zip.

Installed packs are listed in the builder sidebar. You can view details, rename the display name, refresh, edit, or delete installed packs. Build history is stored in the browser and can be used to rebuild earlier pack definitions.

Privacy note: the builder loads browser libraries from public CDNs for its map and interface. KeywordLens does not use those requests for analytics or tracking.

Keyword Feedback and Accuracy Reports

Feedback

After analysis, Lightroom's Metadata panel shows KeywordLens fields, including AI Keyword Feedback:

• Not reviewed
• Approved
• Corrected by user

Choose Sync AI Feedback Now to send pending Approved / Corrected values to the backend immediately. KeywordLens also syncs feedback on plug-in reload. Repeated syncs do not double-count unchanged feedback.

Accuracy Snapshots

Use Capture Accuracy Snapshot... after you have reviewed or edited a batch. KeywordLens compares the current catalog state to the AI baseline stored in the backend.

Use Show Accuracy Report... to open the browser report at http://localhost:8099/tools/accuracy-report. The report groups results by provider, model, and analysis mode and shows proxy metrics for kept, removed, and added keywords, plus title/caption verbatim rates and explicit feedback counts.

The metrics are behavior-based proxies, not scientific ground truth. They are most useful for comparing providers and models on your own catalog.

Database Pruning

Use Prune KeywordLens Database... after removing many photos from Lightroom. The command scans the catalog, previews orphan backend rows, and deletes them only after confirmation.

Keyword Hygiene and Rehoming Tools

Audit & Clean Keyword Hygiene

This tool scans the Lightroom keyword tree for common drift:

• Case duplicates, such as adult and Adult.
• Empty keywords.
• Tag-type names accidentally created as keywords.
• Orphan top-level keywords.
• Orphans that can be rebased into your imported taxonomy.

The tool previews changes before writing. Automatic actions run inside Lightroom write-access blocks and are designed to move photo-keyword assignments safely. Lightroom's SDK does not let plug-ins delete keyword nodes, so drained 0-photo keywords still need to be deleted manually from the Keyword List panel.

Back up your catalog before using cleanup tools on a large library.

Rehome Existing Keywords by Detected Category

Use this one-shot maintenance tool when older AI runs left broad value keywords at the root of the keyword tree. It classifies photos by subject category and can move loose values under category roots such as Wildlife > serene or Landscape > afternoon, depending on the detected subject.

Dry-run is enabled by default. Live mode requires explicit confirmation and writes a decision log under ~/.keywordlens/.

Tips for Better Results

• Start with a small representative batch before analyzing thousands of photos.
• Use cloud providers or higher concurrency for faster batches when privacy and cost allow it.
• Keep local providers at lower concurrency if your GPU is already saturated.
• Increase export size when fine detail matters, such as birds, insects, signs, or distant landmarks.
• Use location metadata when place context matters, but turn it off for privacy-sensitive work.
• Import your existing taxonomy before large runs if you care about hierarchy placement.
• Leave scaffold enabled if you want new subjects to land in a predictable hierarchy.
• Capture accuracy snapshots only after you have reviewed the AI output.

Troubleshooting

Backend Not Reachable

Click Test Backend Connection in Plug-in Manager. If auto-start is enabled, reload the plug-in or restart Lightroom. Logs are written to %USERPROFILE%\.keywordlens\server.log on Windows and ~/.keywordlens/server.log on macOS.

If another process is using port 8099, stop that process or change the backend configuration.

Provider Test Failed

For local providers, make sure Ollama or LM Studio is running and the selected model is available. For cloud providers, verify API keys, endpoints, deployments, and model names. For Azure OpenAI with Entra ID, make sure the backend can acquire credentials and that the identity has access to the Azure OpenAI resource.

No Keywords Generated

Check the provider connection, then try the run again. Failed photos are not marked as analyzed. If parse errors persist, try a different model or simplify custom prompt text.

Analysis Is Slow

Local CPU-only analysis can be very slow. Use a smaller local model, reduce export size, lower local concurrency, or switch to a cloud provider. Enable performance statistics or backend performance logging when comparing providers.

Search Finds Nothing

Search only covers records stored in the backend. Analyze photos or run Import Existing Keywords to Backend first. Try broader search terms and confirm you selected the intended search scope.

Offline Pack Results Look Stale

After installing, editing, or rebuilding packs, clear the location cache and re-analyze the affected photos. Already-analyzed photos keep their existing metadata until you re-run analysis.

Plug-in UI Language Did Not Change

Restart Lightroom after installing or updating KeywordLens. Lightroom loads translated plug-in strings at process startup, so Reload Plug-in is not enough for locale files.