=== CelerSearch - AI-Powered Instant Search with Meilisearch ===
Contributors: darkog, celersearch
Tags: search, meilisearch, instant search, autocomplete, woocommerce
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.7.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

⚡ Instant, typo-tolerant, AI-powered WordPress search with Meilisearch. Autocomplete, faceted filters, semantic search, WooCommerce-ready.

== Description ==

CelerSearch routes WordPress search through Meilisearch: fast responses, typo tolerance, autocomplete, highlighting, optional AI semantic search, and full WooCommerce support.

= 🎬 Try it live =

All three demos run this exact plugin with AI Semantic Search enabled:

* **[Outdoor Shop](https://demo1.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=outdoor-shop)** (WooCommerce): search *keep my coffee hot on the summit* and a vacuum flask ranks first, even though its product copy never uses those words.
* **[Art Gallery](https://demo2.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=gallery)** (custom post type): try *a moody storm at sea*, then narrow by medium, style, and era.
* **[Cinema](https://demo3.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=cinema)**: describe *a feel-good time-travel movie* without knowing a single title.

More context for each demo at [celersearch.com/demos](https://celersearch.com/demos).

= 🔍 Search =

* Instant results on any site size
* Typo tolerance and stemming out of the box
* Optional AI semantic search that blends meaning with keyword relevance (see below)
* Optional AI chatbot that answers visitor questions from your indexed content, as a floating widget, shortcode, or block (bring your own OpenAI-compatible API key)
* Live, paginated autocomplete as users type
* Match highlighting on titles and excerpts
* Category, tag, and custom-taxonomy filtering
* Pin documents at fixed positions for chosen queries (per-index Rules)
* Custom search results pages via Views + block/shortcode
* Native WordPress search fallback when Meilisearch is unreachable

= 🤖 AI Semantic Search =

Semantic search matches meaning, not just words. CelerSearch configures a Meilisearch embedder on the index and blends vector similarity with keyword relevance (hybrid search) on every query.

* Enable it per index: Index Settings, AI Search, "Enable AI semantic search"
* Bring your own OpenAI API key; keyword search never needs one
* Pick the model: text-embedding-3-small (default, cheapest) or text-embedding-3-large (most accurate)
* Tune the keyword-to-semantic balance with a ratio slider, plus an optional relevance cutoff
* Applies automatically everywhere: site search, autocomplete, and WooCommerce shop filters
* Works with any Meilisearch 1.13+ (or 1.3+ with the vectorStore experimental flag), self-hosted or managed

Full walkthrough in the [AI Semantic Search guide](https://celersearch.com/docs/guides/ai-semantic-search), and see the FAQ below for models and costs.

= 🗂 Indexing =

* Posts, pages, any custom post type
* WooCommerce products (including variations) and orders
* Users, for membership and community sites (strict privacy allowlist; email excluded by default)
* Meta Box custom fields, including fields stored in Custom Database Tables
* Real-time sync on publish, update, trash, and watched meta changes
* Manual reindex with configurable batch size; "Refresh in place" mode keeps search live (zero downtime)
* Per-index searchable, filterable, sortable attributes and synonyms, all editable in the admin
* Content splitting for long posts (configurable; Meilisearch deduplicates results)

= 🌐 Where search runs =

* Frontend site search (replace the default results page with a custom View)
* Admin list search (posts, products, orders, media, users)
* BuddyPress members directory
* REST API search (headless/decoupled setups)
* AJAX-faceted WooCommerce shop & archive filters

= 📊 Analytics (opt-in) =

* See your top queries and which ones return zero results, so you can fix content gaps
* Daily query-volume trend per index over 7/30/90-day windows
* Off by default and fully private: data stays in your own database, with bounded retention (see Privacy & Data below)

= 🎯 Use cases =

* **WooCommerce stores with thousands of orders**: native admin order search slows to a crawl and misses matches as the orders table grows. Enable the "WooCommerce Admin Orders Search" area and lookups stay instant at any scale.
* **Product catalogs with rich attributes**: drive shop and category archives with AJAX-faceted filters for color, size, brand, price, plus typo-tolerant keyword search.
* **Content-heavy sites (news, blogs, documentation)**: replace the frontend search with live autocomplete and fuzzy matching so readers find posts by typing a few characters.
* **Membership and community sites**: index users behind a strict privacy allowlist and make the wp-admin Users screen and the BuddyPress members directory instant and typo-tolerant.
* **Custom post types at scale**: directories, job boards, listings. Native WP search is a slow `LIKE '%…%'` across a handful of columns; CelerSearch indexes every field and ranks by relevance.

= 🧑‍💻 Developer-friendly =

* 40+ filter hooks across indexing, search, and results
* Extend with your own index types (`celersearch_supported_indices`)
* Custom search-area types (`celersearch_area_types`) for LearnDash and others (BuddyPress ships built-in)
* Taxonomy-aware queries translate WP_Query `tax_query` to the engine filter syntax

Full documentation at [celersearch.com/docs](https://celersearch.com/docs).

= Requirements =

* WordPress 6.0+
* PHP 8.1+
* A Meilisearch instance: self-host on your VPS, or get a managed one at [celersearch.com](https://celersearch.com/) from $12/mo.
* Optional, for AI Semantic Search: an OpenAI API key and Meilisearch 1.13+ (or 1.3+ with the vectorStore experimental flag).

= 🚀 Getting started =

After activation a welcome notice points you to the setup flow:

1. Stand up Meilisearch: self-host ([guide](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch)) or use [celersearch.com](https://celersearch.com/)
2. Add the service under **CelerSearch → Services**
3. Create an index under **CelerSearch → Indices** and rebuild it
4. Enable the relevant search area under **CelerSearch → Settings**

== Installation ==

1. Upload the `celersearch` folder to the `/wp-content/plugins/` directory
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure your Meilisearch service under CelerSearch > Services
4. Create indices and configure search areas

== Privacy & Data ==

CelerSearch does not phone home. Keyword search forwards queries only to the Meilisearch instance you configure under CelerSearch → Services. One optional feature involves a third party: if you enable AI Semantic Search on an index, document text (as rendered by the document template, capped by its byte limit) and search queries are sent to OpenAI to generate embeddings, using your own API key. That feature is off by default.

The optional **Analytics** feature (off by default; opt-in under CelerSearch → Settings → Analytics) stores each performed search in your own WordPress database so you can see what visitors search for. When enabled it records:

* The search term (the text typed by the visitor)
* The matching index, area type, and the number of results returned
* The search engine that served the request (e.g. `meilisearch`) and a timestamp

IP addresses, user identifiers, session tokens, referrers, and user-agent strings are **never** stored. Retention is bounded by a configurable window (default 30 days, range 7–365) and a daily background job prunes older rows automatically. You can disable Analytics at any time and clear all collected data from the Settings page. Uninstalling the plugin drops the analytics table entirely.

== Frequently Asked Questions ==

= Do I need my own Meilisearch server? =

Yes. Two options:

* **Self-host** on your VPS: free, but you handle updates, backups, and SSL. [Upstream guide](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch).
* **Managed** at [celersearch.com](https://celersearch.com/): from $12/mo, provisioned in seconds, updates and backups handled.

= Is there a live demo? =

Three, all running this plugin with AI Semantic Search enabled: an [Outdoor Shop](https://demo1.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=outdoor-shop) (WooCommerce), an [Art Gallery](https://demo2.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=gallery) (custom post type), and a [Cinema](https://demo3.celersearch.com/?utm_source=wordpress.org&utm_medium=referral&utm_campaign=plugin-readme&utm_content=cinema). Overview at [celersearch.com/demos](https://celersearch.com/demos).

= What is AI Semantic Search? =

Meaning-aware search. CelerSearch stores a vector embedding for each document and blends semantic similarity with keyword relevance on every query (hybrid search). Searching for *keep my coffee hot on the summit* surfaces a vacuum flask even though its copy never contains those words. It is optional and enabled per index; with it off, keyword search works exactly as before.

= Do I need an OpenAI API key? =

Only for AI Semantic Search. Regular keyword search never calls any AI service. You enter the key per index (Index Settings, AI Search); it is stored server-side, shown masked, used only to generate embeddings, and never exposed to visitors.

= Which embedding models are supported? =

OpenAI's text-embedding-3-small (the default: 1536 dimensions, fastest and cheapest) and text-embedding-3-large (3072 dimensions, most accurate). Developers can register other embedding sources via the `celersearch_embedder_sources` filter.

= How much does AI search cost in OpenAI usage? =

You pay OpenAI directly, per token, on your own API key. CelerSearch makes one embedding call per document at index time (and again when a document changes), plus one per search query. At the default model's $0.02 per 1M tokens (OpenAI pricing as of mid-2026; text-embedding-3-large is $0.13) that stays small: indexing 10,000 typical products costs roughly $0.05 to $0.15 one time, and 100,000 searches cost a few cents. Each document's embedded text is capped by the Template max bytes setting (default 3000 bytes, roughly 750 tokens), so costs are bounded. Set the semantic ratio to 0 and no embedding calls are made at all.

= Does AI search require CelerSearch Cloud? =

No. It works with any Meilisearch 1.13 or newer (or 1.3+ with the vectorStore experimental flag), self-hosted included. The CelerSearch Cloud [AI plans](https://celersearch.com/pricing?ai=1) are simply sized for vector search workloads.

= Do I need to rebuild the index after enabling semantic search? =

Yes, once. Embeddings are generated at index time, so after enabling AI Search run a rebuild; from then on, new and edited content is embedded automatically as it syncs. Every index-settings tab shows an impact badge telling you whether a change applies instantly or needs a rebuild.

= What is the AI Chatbot? =

An optional assistant that answers visitor questions in natural language, using your indexed content. For each question it retrieves the most relevant documents from the index, has an AI model compose a short answer from them, and streams the reply live with numbered sources. Place it as a floating widget on the pages you choose, inline with the `[celersearch_chatbot]` shortcode, or via the Chatbot block.

= What is the difference between AI Semantic Search and the AI Chatbot? =

Semantic search improves the ranked result lists your visitors already use (search page, autocomplete, shop filters). The chatbot answers questions conversationally instead of returning a list. They are independent features: use either, both, or neither.

= Does the chatbot require AI Semantic Search? =

No. It retrieves supporting content with regular keyword search by default; enabling semantic search on the same index helps it find the right documents for vague or conversational questions.

= Does the chatbot make things up? =

It is instructed to answer only from the documents retrieved for each question, to never invent products, prices, or facts, and to say it does not know when your content has no answer. That grounding keeps it reliable in practice; still, test it with the built-in console before going live.

= Which AI providers can power the chatbot? =

OpenAI (gpt-4o-mini by default), OpenRouter, or any OpenAI-compatible endpoint, self-hosted ones included. Alternatively, a Meilisearch server with the chat completions feature enabled can run the conversation natively. As with semantic search, you bring your own API key and it stays server-side.

= How much does the chatbot cost to run? =

You pay your AI provider per token, on your own key; CelerSearch adds no fees. With the default gpt-4o-mini, a typical answer costs a small fraction of a cent, and built-in per-visitor rate limits (5 questions per minute and 100 per day by default, configurable) keep usage bounded.

= What visitor data does the chatbot send or store? =

Each question sends the visitor's message and short excerpts of the retrieved content to the AI provider you configured, nothing more. By default CelerSearch stores nothing. Turn on question logging to keep anonymous question statistics, or "Preserve conversations" to store full transcripts (attributed to the logged-in account when signed in) with bounded retention; the settings include suggested privacy-policy wording you can adopt.

= Does it work with WooCommerce? =

Yes. Dedicated Products and Orders index types, plus AJAX-faceted shop & archive filters.

= Does it work with BuddyPress and membership sites? =

Yes. Create a Users index and member search becomes instant: the wp-admin Users screen, an optional front-end member directory built with Views, and the BuddyPress members directory (public profile fields are indexed and searchable, respecting each field's visibility setting). Privacy first: only a strict allowlist of fields is indexed, and email addresses stay out unless you explicitly opt in.

= Will it slow down my site? =

No. Search queries go to Meilisearch, which responds in under 50ms.

= What if Meilisearch goes down? =

With fallback enabled (default), search reverts to native WordPress search automatically.

= Can I disable content splitting for large posts? =

Yes. Open **CelerSearch → Indices**, edit the index, and toggle **Content Splitting** (chunk size is configurable per index).

For site-wide overrides you can also set these in `wp-config.php`:

`define( 'CELERSEARCH_SPLIT_POSTS', false );`
`define( 'CELERSEARCH_CONTENT_MAX_SIZE', 3000 );`

Rebuild the affected indices after changing either.

= How do I replace the default search results page? =

1. **CelerSearch → Views**: create a View, pick an index, configure behavior.
2. Create a WordPress page and embed the View via the CelerSearch block or `[celersearch]` shortcode.
3. **CelerSearch → Settings → Search Areas**: on "WordPress Public Search", enable "Replace Search Results Page" and pick the page.

= What's the difference between Search Areas and Views? =

They solve different problems and often work together.

* **Search Areas** (Settings → Search Areas) intercept WordPress search *where it already happens* (the frontend search, admin list search, REST API search, WooCommerce shop filters) and route it through Meilisearch. No template changes; you pick which index each context uses.
* **Views** (CelerSearch → Views) are a UI primitive for building custom search experiences you embed via the CelerSearch block or the `[celersearch]` shortcode. A View bundles the input, autocomplete, filters, results layout, and sorting as one configurable unit you drop onto any page or widget area.

Typical setup uses both: create a View-powered search page, then enable "Replace Search Results Page" on the WordPress Public Search area and point it at that page. The Search Area handles the interception, the View renders the page.

== Screenshots ==

1. Service create page
2. Services index page
3. Index create page
4. Indices index page
5. Index settings modal
6. Index browser - See what's in the index and preview the documents structure
7. Views creation and embed to public page
8. Plugin settings
9. Search Area configuration - WooCommerce product search
10. Search Area configuration - Swap public WordPress search with CelerSearch based search
11. AI Semantic Search settings - embedding model, dimensions, document template, and your OpenAI key, per index

== Changelog ==

= 1.7.2 =

* New: public PHP search API. `celersearch()->search()` runs the full CelerSearch search from your own PHP code (REST endpoints, shortcodes, blocks, templates, WP-CLI). See the [PHP Search API guide](https://celersearch.com/docs/extending/php-search-api).
* Improve: autocomplete, Views and native WordPress search now run through one shared search pipeline, so every surface handles pinned results, pagination and fallbacks the same way.
* Improve: the semantic search settings now warn when no API key is set, since indexing would otherwise fail silently.
* Fix: pinned results in Views now respect each index's own visibility rules, so curated pins work on indices that are not post-based (users, orders).
* Fix: View pages showing boosted pinned results now render facet counts and enriched result cards (such as WooCommerce product cards) like any other page.
* Fix: WooCommerce product searches are no longer redirected to the dedicated search page and now use the WooCommerce Product Search area as configured.
* Fix: sold-out products are no longer excluded from indexing when the exclude sold out option is turned off.

= 1.7.1 =

* New: Search cutoff (ms) index setting — control the engine's per-search time budget. Raise it (e.g. 5000) on AI-enabled indices so hybrid searches are not silently degraded to keyword-only when the embedding provider responds slowly.

= 1.7.0 =

**AI Semantic Search**

* New: per-index embedder support — vector (semantic) search blended with keyword relevance (hybrid search) on every query.
* New: pick an OpenAI embedding model (text-embedding-3-small or -large), bring your own API key; register other sources via `celersearch_embedder_sources`.
* New: keyword-to-semantic ratio slider and optional relevance cutoff, per index.
* Applies automatically to site search, autocomplete, and WooCommerce shop filters.

**Indexing**

* New: User Index for membership/community sites — strict privacy allowlist (email excluded by default), instant wp-admin Users search.
* New: BuddyPress integration — members directory search; public profile fields indexed, respecting visibility settings.
* New: "Refresh in place" reindexing — zero-downtime reindex is now the default; in WP-CLI as `--mode=refresh|full`.
* New: Meta Box integration — index Meta Box fields (including Custom Database Tables) with no code.

**Views & WooCommerce**

* New: Facet Builder — design each filter visually: checkboxes, pills, color swatches, star ratings, range slider, price brackets, category drill-down, searchable dropdown; drag to reorder.
* New: smart facet counts (disjunctive faceting) — picking a value no longer zeroes sibling options; optional greyed-out zero-count values.
* New: replace the WooCommerce shop page with a View — instant-search catalog with your facets, AJAX pagination, and your theme's native product cards.
* New: sort dropdown (relevance, price, rating, newest, popularity) and optional Search button per View.
* New: mobile filter drawer with collapsible facet groups.
* New: per-View Appearance panel — accent color, text, borders, filter pills, corner radius; refreshed built-in product card.
* New: pagination extras — "Load more" button, per-page selector, customizable result-count text.
* New: per-area autocomplete appearance toggles — image, type label, excerpt, product variations.

**AI Chatbot**

* New: optional chat assistant that answers visitor questions from your indexed content — floating widget, `[celersearch_chatbot]` shortcode, or block.
* New: streamed answers with numbered sources and per-visitor rate limits.
* New: connect OpenAI, OpenRouter, any OpenAI-compatible endpoint — or a chat-capable Meilisearch server natively.
* New: widget branding (color, avatar, title, launcher), built-in test console, question log, optional conversation transcripts with suggested privacy-policy text.

**Improvements & fixes**

* Improve: every index-settings tab shows an impact badge — applied instantly, auto-applied, or rebuild required.
* Improve: redesigned first-run notice and hosting chooser.
* Improve: WP-Cron stall warning in Settings, paginated analytics reports, "Select all" in the per-index status picker.
* Fix: real-time order sync could index the wrong order on HPOS stores.
* Fix: AJAX pagination on the WooCommerce shop filter bar.

= 1.6.0 =

* New: Custom Ranking in index settings — tie-break results by a numeric attribute (e.g. `post_date` desc), applied after the ranking rules; included in index import/export.

= 1.5.4 =

* Fix: WooCommerce product search returned zero/irrelevant results — internal `product_visibility` filters are no longer sent to the engine; taxonomy filters match indexed term names.
* Fix: attributes CelerSearch filters on (status, price, stock, rating) stay filterable when index settings are pushed.

= 1.5.3 =

* Improve: index import/export (admin and WP-CLI) now includes Pinned Searches.
* Improve: in-plugin documentation links point to the Getting Started guide.

= 1.5.2 =

* New: "Contains" match type for Pinned Searches — the pin fires when the query contains a keyword, curated records pinned above normal results. Exact match stays the default.

= 1.5.1 =

* Fix: Pinned Searches now also apply to server-rendered search areas (public results page, WooCommerce product search), not only autocomplete and Views. Overridable via the new `celersearch_apply_pinning` filter.

= 1.5.0 =

* New: per-index Pinned Searches — map a term and its aliases to a hand-picked, ordered set of records, chosen with an inline record browser. Stored locally, works on any backend.

= 1.4.2 =

* New: opt-in Search Analytics — top queries, zero-result queries, and daily volume per index; stored only in your own database with bounded retention.
* New: per-index Rules (Meilisearch Dynamic Search Rules) — pin documents at fixed positions for matching queries. Requires Meilisearch 1.41+ with the `dynamicSearchRules` flag.
* New: autocomplete pagination — the suggestions popup pages through all matches, with configurable results per page.

= 1.4.1 =

* Add per-item Import/Export for Indices, Services and Settings — JSON envelope format, slug/name dedup on import, API keys redacted by default with explicit opt-in to embed
* Add WP-CLI commands: `wp celersearch index|service|settings export|import`
* Fix: `wp celersearch index list|info|clear` no longer fatals on the success path (used a non-existent `is_success()` helper)

= 1.4.0 =

* Add first-run welcome notice
* Add host-options picker to the Services empty state and Create Service modal
* Add per-index settings UI for searchable, filterable, sortable attributes and synonyms
* Add Index Browser modal with in-engine search, filters, and index configuration
* Add row-level action menus, toast notifications, reusable confirmation modals, and admin footer polish
* Improve: frontend search-view and WooCommerce shop-filter typography now scales with the theme's font size
* Fix: MultiSelect dropdowns inside modals no longer get clipped by the modal edge
* Fix: Indices page no longer fatals when an index references a deleted service
* Fix: admin assets enqueue with exact page-slug match, avoiding leakage onto third-party admin pages
* Fix: admin modals correctly center and align with the WP admin content area
* Tested and ready for WordPress 7.0

= 1.3.1 =

* Fix: Defer translation of index type labels to avoid the "translation loading triggered too early" notice on WordPress 6.7+

= 1.3.0 =

* Fix: Ensure Meilisearch indexes are created with correct primary key and settings before first sync
* Fix: Provision index with filterable attributes on creation, preventing empty search results
* Fix: Detect and automatically clean up stuck Action Scheduler sync jobs
* Add content splitting as a per-index setting (enable/disable and max record size)
* Add sync error logging visible to admins via AJAX endpoints
* Improve documents column to clarify indexed vs local counts when content splitting is active

= 1.2.4 =

* Fix: URL based search query does not persist in search page
* Fix: CelerSearch menu registers for non-admin users too in wp-admin

= 1.2.3 =

* Respect initial_display setting when search input is cleared in Views

= 1.2.2 =

* Add sorting option in Views and Search areas

= 1.2.1 =

* Fix post splitting / deduplication

= 1.2.0 =

* Add on-demand service health checks from Services page
* Add index document count stats on Indices page
* Fix deleting an index now also removes it from the remote search engine
* Improve service creation form and status display

= 1.1.3 =

* Minor bug fix related to product indexing

= 1.1.2 =

* Improve bundling process
* Add option "Replace Search Results Page" with selected page that embeds View via Block or shortcode in Search area settings for "WordPress Public Search" type
* Add filter celersearch_view_search_hit for adding additional data to the hits response
* Improve UI in view form

= 1.1.1 =

* Improve build process
* Fix admin page icon

= 1.1.0 =

* Add WooCommerce integration
* Add Views
* Improved code quality
* Improved UI/UX


= 1.0.4 =
* Add celersearch as committer
* Add Confirmation for reindex operation
* Fix WooCoomerce order index thumbnail
* Fix Autocomplete dialog result display HTML escaped strings

= 1.0.3 =
* Add WooCommerce Orders index
* Improved code quality

= 1.0.2 =
* Improved code quality

= 1.0.1 =
* Fixed minor bugs

= 1.0.0 =
* Initial release

== Upgrade Notice ==

= 1.7.2 =
Adds a public PHP search API and runs every search surface through one shared pipeline. Fixes WooCommerce product search being hijacked by the dedicated search page and sold-out products being wrongly excluded from indexing.

= 1.7.1 =
Adds a Search cutoff (ms) index setting. If you use AI search, raising it (e.g. 5000) prevents hybrid searches from silently falling back to keyword-only when the embedding provider is slow.

= 1.7.0 =
AI Semantic Search — hybrid keyword + vector search via OpenAI embedders — plus a visual Facet Builder with smart counts, a privacy-first User Index, zero-downtime reindexing, and an optional AI chatbot.

