=== FindAstra — AI Semantic Search for WooCommerce ===
Contributors: elyass, freemius
Tags: woocommerce, search, semantic search, ai search, product search
Requires at least: 6.4
Tested up to: 7.0
Stable tag: 0.11.7
Requires PHP: 8.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI product search that understands what shoppers mean, not just keywords. Runs in the browser. No API keys, no signup, no cost.

== Description ==

FindAstra is AI product search for WooCommerce. It helps your store understand what shoppers actually mean, not just the exact words they type. Someone searching for "comfortable shoes for hiking" will find your "Trail Running Sneakers" even when the title never mentions comfort or hiking.

Ordinary keyword search only matches products that literally contain the words a shopper types. So a customer who describes things in their own way lands on a "no results" page and leaves. FindAstra closes that gap. It reads the intent behind each search, puts the most relevant products first, and offers helpful suggestions instead of dead ends.

And the free version runs completely on its own. There are no API keys to paste, no account to create, and no monthly fees. The AI runs right inside the shopper's browser, so nothing about your catalog or your customers is sent to an outside server, and you can index your entire catalog with no product limit.

= What your shoppers get =

*   **Answers, not just matches.** Searches are understood by meaning, so shoppers reach the right products even when their wording differs from yours.
*   **Live suggestions as they type.** A search-as-you-type dropdown attaches to your existing search bar, with no theme editing.
*   **A results page that makes sense.** Your normal WooCommerce results page is simply re-ordered by relevance, keeping your theme's design exactly as it is.
*   **No more empty pages.** When nothing is a strong match, shoppers see popular products instead of a dead end.

= What you get as a store owner =

*   **Set up in minutes.** Activate, click index once, and AI search is live. No keys, no account, no configuration headaches.
*   **Private by default.** Your products and your customers' searches stay on your own site.
*   **Fits your store.** Works with classic and block themes, and includes a search block, a shortcode, and a sidebar widget. Developers also get filter hooks and a REST endpoint to build on.

= How it works, in plain terms =

When you click index, FindAstra reads each product and builds a small understanding of what it is. When a shopper searches, it compares their wording to that understanding and lists the closest products first. The first time it runs, the browser downloads a small AI model (about 33 MB) and reuses it from then on, so searches stay fast.

= FindAstra Pro (optional) =

A separate paid version is available at findastra.com for stores that want more. It adds optional server-side engines for very large catalogs (using your own OpenAI or Hugging Face key), multilingual search for WPML and Polylang, and built-in search analytics. The free version here is complete on its own, and nothing in it is locked or time limited.

== Installation ==

1. Upload the FindAstra plugin folder to `/wp-content/plugins/`, or install it via the WordPress Plugins screen.
2. Activate the plugin.
3. Go to WooCommerce → FindAstra.
4. Pick an engine. Local works without any account or key.
5. Click "Index now" to build the search index.
6. Open your storefront and search. Autocomplete and the results page wire automatically.

WooCommerce 7.0+ and PHP 8.1+ are required.

== Frequently Asked Questions ==

= Do I need an OpenAI key to use this? =

No. The default Local engine runs entirely in your shoppers' browsers, with zero keys, zero accounts, and no cost. (The OpenAI and Hugging Face engines are part of the separate FindAstra Pro, for stores that prefer server-side processing.)

= Will this slow down my store? =

No. Scoring runs inside your existing database and adds roughly 20 to 30 milliseconds to a typical search. Indexing runs in the background in small batches, so it never blocks the admin. The Local engine does its work in the shopper's browser.

= Does it work with WPML or Polylang? =

Multilingual indexing is part of FindAstra Pro. With Pro, FindAstra detects each translated product's language at index time and writes one embedding row per (product_id, language) pair, and searches are scoped to the current request language.

= What about large catalogs? =

FindAstra handles large catalogs automatically. For stores with more than 5,000 indexed products it switches to a faster two-step search, so results stay quick even on big stores.

= Where are my API keys stored? =

Encrypted at rest using AES-256-CBC with a site-specific key derived from `wp_salt('auth')`. Keys are only decrypted at the moment of use.

= Does the Local engine download anything? =

Yes, once. The first time the Local engine runs, it downloads a roughly 33 MB AI model from the Hugging Face model hub (huggingface.co), which your browser then caches. Only the model files are fetched. No store, product, or shopper data is ever sent. After that, all search runs entirely in the browser. (The optional Pro engines instead call OpenAI or Hugging Face using the keys you provide.)

= Is the free version really unlimited? =

Yes. The free version indexes your entire catalog with no product cap and serves unlimited searches. It is not a trial, and nothing in it expires or gets locked later.

= When is plain keyword search enough? =

When shoppers type exact product names, model numbers, or SKUs, plain keyword matching already works well. FindAstra covers those cases with instant prefix matching in its suggestions, and adds meaning-based results for every search where the wording does not line up.

= Which themes does it work with? =

Any theme that uses the standard WooCommerce search form and results page. It is tested with Storefront, Astra, Kadence, Blocksy, and GeneratePress, on both classic and block themes. The results page keeps your theme's own layout.

= Is my shoppers' search data private? =

Yes. With the default Local engine, each search is processed inside the shopper's own browser and never leaves your site. The plugin sets no tracking cookies and stores no personal data.

== External services ==

Which external service (if any) FindAstra contacts depends on the search engine you choose during setup. Each is described below, including what data is sent and when.

= Hugging Face model hub (huggingface.co) =

Used by the default **Local** engine. The first time the Local engine runs (when you index products in wp-admin, or when a shopper performs a search), the browser downloads a roughly 33 MB open-source AI model from the Hugging Face model hub and caches it locally for later visits. Only the model files are fetched. No store, product, shopper, or site data is ever sent. After the download, all search runs entirely in the browser.

Hugging Face terms of service: https://huggingface.co/terms-of-service . Privacy policy: https://huggingface.co/privacy

= OpenAI API (api.openai.com) =

Used only if you select the **OpenAI** engine and enter your own API key. At index time, the text of each product (its title and the fields you choose to include) is sent to OpenAI to generate an embedding; at search time, the shopper's query text is sent. Requests are authenticated with the API key you provide and are made only while the OpenAI engine is the active provider.

OpenAI terms of use: https://openai.com/policies/terms-of-use . Privacy policy: https://openai.com/policies/privacy-policy

= Hugging Face Inference API (router.huggingface.co) =

Used only if you select the **Hugging Face** engine and enter your own access token. The same data as the OpenAI engine (product text at index time, query text at search time) is sent to the Hugging Face Inference API to generate embeddings, authenticated with the token you provide, and only while the Hugging Face engine is the active provider.

Hugging Face terms of service: https://huggingface.co/terms-of-service . Privacy policy: https://huggingface.co/privacy

== Screenshots ==

1. Live suggestions as shoppers type. FindAstra reads the intent behind a search, so wording like "something to lift weights at home" surfaces the right gear even when those words are not in the product names.
2. A results page that makes sense. The shopper's search returns genuinely relevant products, ranked by meaning instead of exact keyword matching, in your theme's normal layout.
3. Set up in a single screen. Pick the free Local engine, click index, and AI search goes live on your store. No API keys and no account required.
4. Before and after. The same search on default WooCommerce ends in "No products were found", while FindAstra returns the right products ranked by meaning.
5. No more dead ends. When a search has no strong match, shoppers are offered popular products instead of nothing.
6. Match quality settings. Sensible defaults out of the box, with optional advanced gates for stores that want to tune relevance.

== Changelog ==

= 0.11.7 =
* The in-browser Local engine now loads its runtime entirely from the plugin — no external CDN fallback of any kind.
* Internal naming and packaging cleanup.

= 0.11.6 =
* The free version is fully functional with no product limit — index your whole catalog with the Local engine.
* The OpenAI and Hugging Face server-side engines, WPML/Polylang multilingual indexing, and search analytics are part of FindAstra Pro.
* Documented the external services each engine can contact (the in-browser model download and the optional Pro APIs).

= 0.11.5 =
* Background indexing for the OpenAI and Hugging Face engines: click "Index now" and you can close the tab — indexing keeps running on the server and resumes if interrupted. Ideal for large catalogs. (The Local engine still indexes in your browser.)
* Faster indexing: larger embedding batches mean far fewer API calls, so big stores finish in a fraction of the time.
* Clearer Match-quality gates: the settings now show the real defaults for your selected engine and note that they are advanced — most stores never need to change them.

= 0.11.4 =
* Fixed: with the OpenAI engine selected, almost every search showed "No exact matches — here are some popular products" instead of real results. OpenAI's relevance threshold was tuned for a different model; it now uses correctly calibrated values. (Local and Hugging Face were not affected.)
* Search relevance is now self-calibrating across all three engines: results are shown when a product clearly stands out from the rest, so genuine matches surface even when a store's catalog scores differently from the built-in defaults. Gibberish still falls back to popular products, and your manual Match-quality gates still take precedence when set.

= 0.11.3 =
* WordPress.org Plugin Check pass: documented the intentional direct/uncached queries against the plugin's own custom tables, suppressed the no-nonce notice on the public product-search request (input is sanitized and the token is signature-validated), and annotated the third-party WPML filter hooks.
* Aligned the readme title with the plugin header name to clear the Plugin Check name-mismatch notice.

= 0.11.2 =
* WordPress.org compliance pass (Plugin Check clean): added translator comments, hardened output escaping on the analytics counters, and documented the intentional schema-change and asset-streaming database/file calls.
* FAQ: documented the Local engine's one-time on-device model download.
* Compatibility: tested up to WordPress 7.0.

= 0.11.1 =
* Refreshed plugin brand: new mark on the FindAstra admin hero, official compact icon on the WP sidebar menu entry.
* Plugin metadata cleanup ahead of WordPress.org submission: Plugin URI + Author URI now point at findastra.com.

= 0.11.0 =
* Freemius integration: free + Pro/Agency/Unlimited tiers, license activation, automatic updates.
* New `FindAstra_License` class centralises the free/paid capability matrix.
* Free version ships the Local engine; Pro adds the OpenAI and Hugging Face engines.

= 0.10.4 =
* Kill the WooCommerce single-result redirect on hijacked searches so the ranked product cards aren't replaced by a teleport to one item.
* Language-aware shop-page fallback.

= 0.10.3 =
* Shop search page falls back to popular products on no-match so shoppers never see a dead-end results page.

= 0.10.2 =
* Per-model default match-quality gates (fixes HF + bge-m3 "no results" on multilingual queries).

= 0.10.1 =
* Fix indexer infinite loop on Polylang/WPML sites with untagged products.

= 0.10.0 =
* WPML + Polylang multilingual support — per-language embedding rows.
* Theme matrix expanded (Astra, Kadence, Blocksy verified working).
* Hugging Face provider gains `BAAI/bge-m3` (multilingual, 1024d) as a settings-driven alternative to bge-small.

= 0.9.0 =
* Rebrand from SearchSense to FindAstra.

== Upgrade Notice ==

= 0.11.0 =
First public release. Existing installs upgrade non-destructively — your provider settings, vectors, and analytics carry over.
