README

Better site search and AI Answer for Craft CMS. Smart Search ranks results by meaning as well as by keywords, corrects typos, and can write a short AI Answer with cited sources when you want one. The index lives in Craft's own database, so there is nothing extra to host.

Features

Hybrid ranking: keyword scoring blended with meaning-based matching, with typo correction built in.
Works without an API key: keyword search, typo correction and related terms learned from your own content. Add an OpenAI or OpenRouter key for stronger meaning-based ranking and AI Answer.
Enhanced Craft search: your existing craft.entries.search() and GraphQL search queries rank by Smart Search, with no template changes.
AI Answer: a short summary with citations, as JSON or streamed, with a daily spend cap and per-visitor limits.
Templates, HTTP API and GraphQL: craft.smartSearch.search() and aiAnswer() in Twig, JSON and streaming endpoints for headless front ends, and GraphQL queries with per-schema permissions.
Control panel tools: a Dashboard with usage and spend, Insights reports (top, zero-result and trending queries), an Index page with per-entry inspect, exclude and re-index, and a Preview that compares Craft's search, Smart Search and AI Answer side by side.
Runs in production: settings live in project config, secrets are environment variables, and admins can use the Dashboard, Index, Insights and Preview and view settings read-only where admin changes are off.

Requirements

Craft CMS 5.0+
PHP 8.2+
MySQL, MariaDB or PostgreSQL (whichever Craft already uses)
A running Craft queue (indexing runs as queue jobs)
Optional: an OpenAI or OpenRouter API key

Install

Install from the Plugin Store, or with Composer:

composer require ghoststreet/craft-smart-search
./craft plugin/install smart-search

Installing queues the first index of your content automatically. To add an API key, open Smart Search → Settings → Connections, choose a provider and reference your key as an environment variable (for example $OPENROUTER_API_KEY), then click Save. See Getting Started.

Quick example

{% set results = craft.smartSearch.search(craft.app.request.getParam('q') ?? '') %}

{% for result in results %}
  <a href="{{ result.url }}">{{ result.title }}</a>
  <p>{{ result.excerpt }}</p>
{% endfor %}

Documentation

Full documentation lives in the Smart Search Wiki.

Set up

Getting Started
Requirements
Installation
Connections (providers, keys and models)
Running Without an API Key

Build

Using Search in Templates
Enhanced Craft Search
Using the API (headless and external apps)
Using GraphQL
AI Answer Setup
Developer Events

Tune and run

Reference

Support

Email dev@ghost.st for bugs or questions.

License

Licensed under the Craft License. A license is required for each Craft project running Smart Search in production.

Built by Ghost Street

ghoststreet / craft-smart-search

Package info

Security

Statistics