=== 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

Replace WooCommerce's keyword search with AI semantic search that runs entirely in the shopper's browser — no API keys, no signup, no cost.

== Description ==

FindAstra replaces WooCommerce's default keyword search with AI search that understands what shoppers mean. A search for "comfortable hiking shoes" finds your "Trail Running Sneakers Cushioned" product even when none of those words appear in the title or description.

Every published product is converted into a vector embedding that captures its semantic meaning. At search time the shopper's query is embedded too, and FindAstra returns the closest matches by cosine similarity.

= The search engine =

This plugin runs the **Local** engine: embeddings are generated in the shopper's browser with transformers.js (`Xenova/bge-small-en-v1.5`). No API keys, no signup, no monthly cost. The ~33 MB model is downloaded once and cached. There is no product limit — index your whole catalog.

= Pro engines (optional) =

FindAstra Pro — a separate, paid version available from findastra.com — adds two server-side engines, useful for very large catalogs where browser-side indexing becomes impractical:

*   **OpenAI** — `text-embedding-3-small`, server-side. Bring your own API key (~$2/year for an average store).
*   **Hugging Face** — `BAAI/bge-small-en-v1.5`, or `BAAI/bge-m3` for multilingual catalogs (100+ languages). Bring your own token (free tier ~30k requests/month).

Pro also adds WPML / Polylang multilingual indexing. The free version on WordPress.org is fully functional on its own; none of its features are time-limited or locked.

= Shopper-facing features =

*   **Live autocomplete dropdown** that auto-attaches to the theme's existing search bar.
*   **Semantic results page** — WooCommerce's product archive template renders proper product cards with the semantic ranking.
*   **Fallback products** when no match scores above the relevance gate, so shoppers never see an empty results page.

= Admin features =

*   **One-click setup** under WooCommerce → FindAstra.
*   **Encrypted credential storage** — API keys never sit in plain text.
*   **Match-quality gating** so weak queries gracefully trigger the fallback instead of returning low-relevance noise.

= Developer features =

*   `[findastra]` shortcode + classic sidebar widget + Gutenberg block.
*   `findastra/v1/*` REST namespace.
*   Filter hooks for source text, gating thresholds, fallback notice text, and the free/paid capability matrix.

= Pro =

The free version is fully functional with the Local engine and no product limit. FindAstra Pro (from findastra.com) adds the server-side OpenAI and Hugging Face engines, WPML / Polylang multilingual indexing, and search analytics (recent searches, zero-result catalog gaps, daily totals).

See [findastra.com/pricing](https://findastra.com/pricing) for details.

== 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 engine is Local — it runs entirely in your shoppers' browsers via transformers.js. Zero keys, zero accounts, $0 forever. The Hugging Face and OpenAI tiers are optional upgrades for stores that want server-side quality.

= Will this slow down my store? =

No. AI scoring runs inside your existing database and adds about 20–30 milliseconds to a typical search. Indexing is asynchronous and chunked, so it never blocks admin. The Local tier offloads work to the shopper's browser entirely.

= 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 automatically switches to a hybrid retrieval mode (FULLTEXT prefilter + cosine re-rank on the top candidates) for stores with more than 5,000 indexed products.

= 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 embedding and search runs entirely in the browser. (The Hugging Face and OpenAI engines instead call their respective APIs using the keys you provide.)

== 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 embedding model (`Xenova/bge-small-en-v1.5`) from the Hugging Face model hub and caches it locally for subsequent visits. Only the model files are fetched; no store, product, shopper, or site data is ever sent. After the download, all embedding and 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 AI autocomplete. A shopper typing "comfortable hiking shoes" instantly sees Merino Wool Hiking Socks, Trail Running Sneakers, and Mountain Trek Boots, even though those exact words are not in the product titles.
2. Semantic results page. The same search renders standard WooCommerce product cards, ranked by meaning instead of keyword matching.

== 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.
