FindAstra Documentation

Introduction

FindAstra replaces WooCommerce's default keyword search with AI that understands meaning. A shopper who searches “comfortable hiking shoes” finds your “Trail Running Sneakers, Cushioned” product even when none of those words appear in the title.

Every published product is turned into a numeric embedding, a vector that captures what the product means. At search time the shopper's query is embedded the same way and compared to every product by similarity. The closest matches come back, ranked by relevance, in about 20 to 30 milliseconds.

You choose which AI model (the engine) does the embedding. The free version ships the in-browser Local engine; a Pro license adds the OpenAI and Hugging Face server-side engines. All engines share the same storage and ranking, so switching between them is just a re-index.

Free vs Pro at a glance: the free version on WordPress.org includes the Local engine with no product cap and the automatic popular-products fallback. Pro adds the OpenAI and Hugging Face engines, multilingual indexing (WPML/Polylang), curated fallback controls, and the Analytics tab covered below.

Requirements

1. Install the plugin

1. In wp-admin, go to Plugins → Add New → Upload Plugin.
2. Choose the findastra.zip file from your purchase, then click Install Now.
3. Click Activate. WooCommerce must already be active, since FindAstra declares it as a required plugin.
4. On activation you land on the setup screen. You can return to it any time under WooCommerce → FindAstra.

Your store's search keeps working whether or not you connect a license. Activating your license is what unlocks automatic updates and the premium engines.

2. Activate your license

After purchase you receive a license key by email. Activating it is a one-time step.

1. Go to WooCommerce → FindAstra → Account.
2. Click Activate License.
3. Paste your license key and confirm.

The plugin flips to the licensed state right away: the plan badge in the header turns gold, and all three engines plus hybrid retrieval, multilingual indexing, the curated fallback, and the full analytics window are unlocked.

Moving to a new site? In FindAstra → Account, deactivate the license on the old site first, then activate it on the new one. There's no hardware lock, so you can move freely as long as you free the previous activation.

3. Choose a search engine

Go to WooCommerce → FindAstra → Engine and pick one. Local is selected by default and needs no account. After choosing and saving, build the index (step 4).

Local: in the browser, $0 to run

• No configuration. Embeddings are computed in the shopper's browser using a small model (about 33 MB) that downloads once and is cached for later visits.
• The admin re-index also runs in your browser, so keep the FindAstra tab open while it works.
• Best for English-language catalogs. For multilingual stores, use Hugging Face bge-m3 or OpenAI.

Hugging Face: server-side, free tier

1. Create a free token at huggingface.co/settings/tokens (read access is enough).
2. On the Engine tab, select Hugging Face and paste the token.
3. The default model handles English. For multilingual stores, switch to BAAI/bge-m3 (100+ languages) in the model selector.

The Hugging Face free tier covers roughly 30,000 queries per month, which is plenty for most stores.

OpenAI: server-side, best quality

1. Create an API key at platform.openai.com/api-keys.
2. On the Engine tab, select OpenAI and paste the key.

Cost is roughly $2 a year per store at typical traffic.

Your keys stay private. API keys and tokens are encrypted at rest and only decrypted at the moment of use. Once saved, the raw value is never shown again, and nothing about your catalog is sent anywhere you don't control.

Switching engines means re-indexing. Different engines produce different vectors, so whenever you change the engine (or the Hugging Face model), run a full re-index.

4. Build the index

The index is the set of product embeddings FindAstra searches against. Build it once after setup, then refresh it when your catalog changes substantially.

1. Open WooCommerce → FindAstra → General. The Index status panel shows how many products are indexed.
2. Click Index now (it reads Reindex store once products are already indexed). Progress updates live.
3. When it finishes you'll see a confirmation that your products are indexed and search is live on your storefront.

New and edited products are picked up automatically on save. A full re-index is only needed after bulk changes or an engine switch.

Local engine indexing. With the Local engine the embedding work happens in your browser during re-index. Keep the FindAstra tab open and in the foreground until it completes. Server-side engines (Hugging Face, OpenAI) index without a browser tab open.

Stores with more than 5,000 indexed products automatically use hybrid retrieval: a fast database prefilter narrows the field, then the AI re-ranks the top candidates. No setup is required, and it's tunable via filters (see the developer reference).

5. See it working

There's nothing to place. FindAstra wires itself into your theme's existing search automatically.

• Autocomplete dropdown: start typing in your theme's search box. A dropdown of relevant products appears, combining instant prefix matches with semantic results.
• Results page: submit a search. Your theme's normal product archive renders with the same cards and styling. FindAstra only changes the ranking to semantic match.
• No dead ends: if nothing is relevant enough, shoppers see your curated fallback products instead of an empty page (see Fallback products).

Try a fuzzy query your catalog doesn't literally contain, like “something for a rainy day” or “shoes that won't hurt my feet”, and watch relevant products come back.

Match-quality tuning

FindAstra applies relevance gates so weak queries fall through to the fallback instead of returning loose matches. Sensible defaults ship per engine. Adjust them on the Search tab or via filters if your catalog needs it.

If good products are being hidden, lower the thresholds slightly. If irrelevant products sneak in, raise them. Small changes of about 0.05 go a long way.

Fallback products

When a query has no strong match, the shopper sees a friendly notice and a grid of products you choose, never an empty results page. Configure it on the Fallback tab.

• Curate the products shown on a no-match, or let the plugin show popular products automatically.
• The notice text is customizable, and you can hide it entirely.

Search analytics (Pro)

The Analytics tab, included with a Pro license, shows what shoppers actually search for:

• Recent searches and today's totals.
• Zero-result queries: searches that returned nothing. These are your catalog gaps, the demand for products you don't yet stock.

Analytics are privacy-safe. No IP address, no user agent, and no shopper identity is ever stored.

Multilingual stores (Pro)

FindAstra detects each translated product's language at index time and stores one embedding per product-and-language pair, so shoppers searching on /fr/ get French results and shoppers on /de/ get German.

• Works with WPML and Polylang out of the box.
• Custom translation frameworks are supported via filters (see the developer reference).
• Use a multilingual engine: Hugging Face BAAI/bge-m3 (100+ languages) or OpenAI (multilingual by default). The Local engine is English-only for now.

After enabling translations or switching to a multilingual model, run a full re-index.

Placing the search box

The default experience needs no placement, since FindAstra attaches to your theme's existing search bar. To add an extra search box anywhere, use any of:

Auto-attach and results takeover work on any theme using standard WordPress/WooCommerce search markup. Verified on Storefront, Astra, Kadence, Blocksy, Woostify, and Twenty Twenty-Five, among others.

Developer reference

FindAstra exposes filters so developers can shape indexing, ranking, and the fallback without touching plugin files.

FindAstra exposes a small REST API under the findastra/v1 namespace for status, indexing, and search, with nonce and capability checks where appropriate. Full hook and endpoint signatures ship with the plugin.

Troubleshooting

Support & updates

Email support@findastra.com and you'll reach me directly, usually within one business day. When you write in, please include your WordPress and WooCommerce versions, the engine you're using, and anything relevant from your debug log.

Updates are included for life. New versions install automatically once your license is active. Full release notes for every version live on the changelog page.