Spectacles Documentation

Spectacles indexes your Craft CMS asset library with a computer-vision model and stores a similarity vector for each image. Visitors upload an image and Spectacles returns the closest matches — or you can query by free-form text from Twig.

How it works

1. When an image asset is saved, Spectacles queues an analysis job.
2. The job calls your configured vision provider (OpenAI, Claude, Gemini, or Ollama) for description, tags, objects, and colors.
3. Then your configured embedding provider (OpenAI, Gemini, Voyage multimodal, or Ollama) produces a vector.
4. Description and vector are stored in spectacles_imagemetadata. If pgvector is available, the vector is also indexed in spectacles_imagevectors for fast cosine lookups.
5. At search time, Spectacles computes cosine similarity (in PHP or via pgvector) and returns ranked results.

Getting Started