SmartMatch Search

SmartMatch Search keeps the normal WordPress search results intact and surfaces
the most semantically relevant post(s) on top as a “Best match” suggestion.

Search that understands intent

Classic WordPress search matches keywords: when the words in the query do not
literally appear in a post, the visitor gets “nothing found” — even when your
site has exactly the right page. SmartMatch Search judges meaning instead, so
visitors can search the way they actually talk:

• “page where I can find my orders” surfaces your Order history page,
  even though none of those words appear in its title.
• “how do I get my money back” finds your Returns & refunds policy —
  no overlap in wording needed.
• “wo finde ich meine rechnung” (German) still lands on your Invoices
  page: the model matches meaning across languages, so visitors searching in
  their own language get the right result.
• “cancel my subscription” surfaces Manage your membership, instead of
  every post that happens to contain the word “cancel”.
• “what time are you open on saturday” finds your Contact & visiting
  information page.

And it filters as well as it finds: a query like “burst viewer” will not match
a post just because the word “burst” appears somewhere — only posts that are
genuinely about the topic are suggested. The native results stay untouched
below the suggestion, so search never gets worse, only better.

Why SmartMatch Search connects to Burst

The Burst Statistics integration exists for two reasons:

1. Real visitors only. Every AI search is a paid model call, so you only
   want to spend it on real people. Burst already knows which visits are
   validated human visits — its tracking filters out bots, crawlers and spam
   before a visit is recorded, in both cookie and cookieless mode. SmartMatch
   Search runs the AI only for those validated visits; bots silently get the
   normal search results at zero AI cost.
2. Searches land in your statistics. Searches run through the normal
   WordPress search request, so they show up directly in Burst’s Engagement
   tab. You see what visitors are looking for — and where your content falls
   short — in the same dashboard you already use.

How it works

SmartMatch Search is a thin integration layer between two plugins:

• AI (WordPress\AI) — supplies the configured provider and text model.
  Provider/model selection is delegated entirely to the AI plugin via
  WordPress\AI\get_ai_service() and the wpai_preferred_text_models filter.
• Burst Statistics / Burst Pro — supplies visit validation. The AI search
  only runs for a validated Burst visit (a uid with a recorded hit in the
  last 30 minutes), which excludes bots. Works in both cookie mode
  (burst_uid cookie) and cookieless mode (session fingerprint).

How it works on a search request (?s=...):

1. The visitor must be a validated Burst visit, otherwise the native results
   are shown untouched.
2. Public, published posts of public post types are collected (title +
   excerpt, capped, freshest first) and sent to the model with the search
   term.
3. The model returns only the genuinely relevant post IDs, ranked.
4. Those posts are merged into the main query’s result array itself (via the
   the_posts filter): prepended above the native matches, de-duplicated, and
   optionally tagged with a configurable badge (via the_title). Because the
   change happens at the data layer, placement does not depend on how the theme
   renders the loop — it works the same for classic templates and block themes.
   When the native search found nothing, the suggestions become the results so
   the page is not empty.
5. Results are cached per search term (transient), invalidated when the
   candidate set changes. Suggestions appear on the first results page only.

If the AI is unavailable, errors, or finds nothing relevant, nothing is added
and the normal results (or “nothing found”) are displayed as usual.

Settings

The plugin adds a “SmartMatch Search” item to the Burst settings menu
(Statistics → Settings → SmartMatch Search), with the options stored in the
Burst settings store:

• Daily search budget (default 50, seeded on activation) — the maximum
  number of AI searches per day. Only actual model calls count (cached
  rankings are free); once the budget is spent, visitors get the normal
  search results until the site’s next midnight.
• Posts sent to the AI (default 200) — how many posts (most recently
  updated first) are sent to the model as candidates per search. More posts
  improve coverage on large sites, but raise the token cost per search.
• Excerpt length in words (default 40) — how many words of each post are
  included in the prompt. Longer excerpts give the model more context to
  judge relevance, but increase token usage per search.
• Badge for the suggested result (default empty) — text shown before the
  title of the suggested result, e.g. “(Best match)”, so visitors see why it
  is on top. Leave empty to show the suggestion without a badge.
• Prompt customization — extra instructions appended to the system
  instruction sent to the model, e.g. to prioritize certain content or set a
  tie-breaking rule.

Editing the prompt customization or excerpt length invalidates previously
cached rankings, so changes take effect immediately.

Filters

• smartmatch_search_enabled (bool, WP_Query) — disable per query.
• smartmatch_search_is_validated_visit (bool, uid) — override the visit gate.
• smartmatch_search_post_types (string[]) — post types to search.
• smartmatch_search_candidate_limit (int) — override the configured number
  of candidate posts sent to the model.
• smartmatch_search_excerpt_words (int) — override the configured excerpt
  length in words.
• smartmatch_search_cache_ttl (int seconds, default 1 hour) — ranking cache.
• smartmatch_search_suggestion_count (int, default 1) — how many to surface.
• smartmatch_search_badge_label (string) — override the configured badge
  text; an empty string disables the badge.
• smartmatch_search_badge_html (string) — replace the rendered badge markup;
  an empty string suppresses the badge. The result is passed through
  wp_kses_post() before it is output.
• smartmatch_search_rate_limit (int, default 5) — AI searches per IP / window.
• smartmatch_search_rate_window (int seconds, default 5 min) — the window.
• smartmatch_search_daily_budget (int) — override the configured daily budget.
• smartmatch_search_debug (bool) — toggle debug logging (see Testing).
• wpai_preferred_text_models (from the AI plugin) — choose provider/model.
• smartmatch_search_ranked (action: ids, term, WP_Query) — observe results.
• smartmatch_search_rate_limited (action: term, WP_Query) — fired when an IP
  exceeds the limit and falls back to normal search.
• smartmatch_search_budget_exceeded (action: term) — fired when an AI search
  is skipped because the daily budget is spent.

Testing / diagnostics

Define SMARTMATCH_SEARCH_BYPASS_GATES as true (e.g. in wp-config.php) to disable
the visitor gates — the Burst uid validation and the per-IP rate limit — so AI
search runs without a tracked Burst visit. Useful for local testing or to verify
a production setup where no validated visit is available. It does NOT bypass the
dependency, main-query or relevance checks. Leave it undefined in normal use.

define( 'SMARTMATCH_SEARCH_BYPASS_GATES', true );

Define SMARTMATCH_SEARCH_DEBUG as true to log every point where AI search bails
out silently to the PHP error log (prefixed “[SmartMatch Search]”): missing
dependencies, no validated visit, rate limit hit, no AI credentials, provider
unsupported, SDK exception, unparseable response, nothing relevant, or the IDs
finally selected. When the constant is undefined, logging follows WP_DEBUG; the
smartmatch_search_debug filter can override it. Logging stays off in normal use.

define( 'SMARTMATCH_SEARCH_DEBUG', true );<h3>Rate limiting</h3>

To curb abuse and AI cost, each IP may run at most 5 AI searches per rolling
5-minute window (both filterable). Beyond that, the request falls back to normal
WordPress search. Only searches that trigger an actual model call count against
the limit: cached rankings are served freely. The visitor IP is resolved through
Burst’s own proxy-aware detector (Burst\Frontend\Ip\Ip::get_ip_address()) and
is only stored hashed.

Requirements

Both the “AI” plugin and Burst Statistics (free) or Burst Pro must be active.
The AI plugin needs a configured provider with valid credentials.

The AI plugin is declared through the WordPress “Requires Plugins” header, so
WordPress itself enforces it on activation. The Burst requirement is enforced
at runtime instead (with an admin notice when missing): that header is an
AND-list of wordpress.org slugs, so it cannot express “Burst free OR Burst
Pro”, and Burst Pro is not distributed on wordpress.org. The plugin simply
stays inactive (and tells you why) until both are present.

External services

SmartMatch Search does not connect to any service of its own and sends no data
to Burst or SmartMatch servers. When a search qualifies for AI ranking, the
search term and the candidate posts (post ID, post type, title and a short
excerpt of public, published content) are sent to the AI provider that you
yourself configured in the WordPress “AI” plugin — which provider that is
depends entirely on your configuration there, and its terms of service and
privacy policy apply to those requests. This happens only for validated human
visits, within the configured daily budget, and only when the ranking is not
already cached. No other data (no IP addresses, no visitor identifiers) is
included in these requests.