=== Asorto - AI Product Search for WooCommerce ===
Contributors: mikolajkapica
Tags: product search, woocommerce search, ai search, semantic search, live search
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
WC requires at least: 8.0
WC tested up to: 11.2
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Free smart search and AI search for WooCommerce. Understands needs, typos and budgets like "gift for dad under 150". Never fewer results than before.

== Description ==

Customers rarely type exact product names. They describe needs, problems and budgets: "gift for dad under 150", "my espresso machine leaves white residue", "grinder up to 300". The regular WooCommerce search answers with "No products were found", and the customer leaves.

Asorto makes the search your shop already has understand these searches. Your theme, search boxes and products stay as they are: only the search results change.

**Two ways to use it**

* **Smart search (free, no account):** word forms, typos, product codes, prices ("up to 300") and stock ("in stock"), synonyms you add yourself. Never fewer results than the regular search. Ready in seconds.
* **AI search with your own OpenAI key:** also understands needs, problems and occasions. You pay OpenAI directly: preparing 1,000 products costs less than USD 0.01.

**Measured, with the method:** on a test shop with 405 products and 41 typical customer searches, the right product was among the first five results in about 4 of 10 searches with the regular WooCommerce search, 8 of 10 with smart search and 9 of 10 with AI search.

**See what customers could not find:** the Statistics tab lists searches that found nothing; add a word with the same meaning in one click and the search finds it from then on.

**Try it before installing:** search the demo shop at https://getasorto.com/shop/ (English and Polish products). The user guide is at https://getasorto.com/docs/.

**What customers can type**

* Needs and tastes: *"chocolatey coffee that is not sour, for milk"*
* Problems: *"my espresso machine leaves white residue"* finds a descaler
* Occasions: *"gift for dad under 150"* finds gift sets within the budget
* Everyday words instead of jargon: *"glass funnel for coffee"* finds pour-over drippers
* Prices and availability: *"grinder up to 300"*, *"available right now"*
* Typos, product codes and SKUs: still found

**Built for real shops**

* Works with products as they are: missing descriptions, page builder leftovers, spec tables, manufacturer copy in English, brands, global attributes and ACF fields.
* Never worse than the regular search: products containing all typed words are always shown.
* Unrelated searches return "no results" instead of random products (strictness is adjustable).
* Polish and other European languages: word forms, and typos without accents ("mlynek reczny" finds "młynek ręczny"). The admin is translated into Polish.
* Multilingual shops (Polylang, WPML): customers see products in the language of the page.

**Easy for shop owners**

* Setup screen: choose smart search or AI search, see what each costs, prepare your products with one click.
* Suggestions while typing, styled by your theme, accessible (keyboard and screen readers). They appear at once, AI improves them a moment later.
* Works with the WooCommerce product search and your theme's main search box, block and classic themes.
* "Try it" tab: the regular search and Asorto side by side for the same words.
* Statistics: what customers search for, what they cannot find, and searches Asorto found that the regular search missed.
* Synonyms: tell the search which words mean the same in your shop ("sofa, couch"), in both modes, for free.

**Costs under control**

* You use your own OpenAI account; the plugin shows the expected cost before preparing products (1,000 products cost less than USD 0.01).
* Monthly spending limit, an hourly allowance per visitor, and bots never use AI: they get the free smart search.
* If the AI service is unavailable or the limit is reached, customers still get results from the free smart search.

== Installation ==

1. Install and activate WooCommerce.
2. Upload the plugin folder to `/wp-content/plugins/` or install it from the Plugins screen, then activate it.
3. Click "Finish setup" next to the plugin, or open WooCommerce → Smart Search. Choose smart search or AI search, and prepare your products.

= Requirements =

* WordPress 6.5 or newer
* WooCommerce 8.0 or newer
* PHP 8.1 or newer
* MySQL 5.6+ or MariaDB 10.0.5+ with InnoDB (standard on current hosting)

You can also define the key in `wp-config.php`:

`define( 'ASORTO_EMBEDDING_API_KEY', 'sk-...' );`

== Frequently Asked Questions ==

= Why does the WooCommerce search show "No products were found"? =

The regular search looks for the exact typed words in product titles and descriptions. "Sofas" does not find "sofa", a typo finds nothing, and "under 150" is treated as words. Asorto understands word forms, typos, prices and stock for free, and with AI search also needs and occasions like "gift for dad".

= Does it find products by SKU or product code, also with typos? =

Yes. A search that is exactly a SKU shows that product first, and product codes with small typos are still found.

= Can I see what customers searched for and could not find? =

Yes. The Statistics tab shows the most common searches, the searches that found nothing, and searches Asorto found that the regular search missed. Under a search that found nothing you can add a word with the same meaning in one click.

= Can I add synonyms for free? =

Yes, in both modes. In Settings write one group per line ("sofa, couch, settee"); other word forms are understood too, and nothing has to be prepared again.

= Does it work in Polish and in multilingual shops? =

Yes. Word forms and typos without accents work in Polish and other European languages, and the admin is fully translated into Polish. With Polylang or WPML customers see only products in the language of the page.

= Do I need an OpenAI account? =

No. Smart search works without any account and costs nothing. Only AI search needs an OpenAI API key (https://platform.openai.com/api-keys). Preparing 1,000 products costs less than USD 0.01, a single search a small fraction of that.

= Will my search break if OpenAI is down? =

No. Searches fall back to the plugin's keyword index, and to the regular WooCommerce search if needed. You get a notice (and an optional e-mail) in the admin.

= Does it work with my theme? =

It works with classic and block themes because it improves the regular WooCommerce product search instead of replacing templates. Live suggestions inherit your theme's fonts and colors. If your theme has no search box, add one with the "Smart Search" block, the [asorto_search] shortcode, or one switch in Smart Search → Appearance.

= Does it change my products, orders or theme? =

No. Products, orders, menus and theme files are only read. The plugin keeps its data (search index, statistics, settings) in its own tables and options. Deactivating stops it; deleting the plugin removes all of its data and leaves your shop exactly as it was before.

= How many products are supported? =

The built-in index (your WordPress database) handles catalogs of up to about 10,000 products comfortably. Larger catalogs can use a Qdrant server (Advanced settings).

= Which data leaves my site? =

See "External services" below and the suggested text in Settings → Privacy.

== External services ==

This plugin connects to the **OpenAI API** (https://api.openai.com) to create embeddings: numerical representations of text used to compare meaning.

* **When:** when products are prepared or changed (product name, categories, tags, attributes, descriptions and SKU are sent) and when a visitor searches (the search phrase is sent; no IP address, account or other personal data).
* **Why:** to find products by meaning instead of exact words.
* OpenAI terms of use: https://openai.com/policies/terms-of-use
* OpenAI privacy policy: https://openai.com/policies/privacy-policy

Optionally, if you choose it in the Advanced settings, product vectors are stored on your **Qdrant** server (self-hosted or Qdrant Cloud, https://qdrant.tech). Qdrant Cloud terms: https://qdrant.tech/legal/terms_and_conditions/, privacy policy: https://qdrant.tech/legal/privacy-policy/

You can use an OpenAI-compatible service other than OpenAI by changing the API address; its own terms then apply.

Search analytics are stored only in your WordPress database as anonymous daily totals.

== Screenshots ==

1. Suggestions while customers type: "gift for dad under 150" finds gifts for men within the budget.
2. Setup: choose the free smart search or AI search with your own OpenAI key, with measured quality and a cost calculator.
3. Dashboard: products ready, AI costs against the limit set in Asorto, searches of the last 30 days.
4. Try it: the regular WooCommerce search next to Asorto for the same words.
5. Statistics: top searches, searches that found nothing, and one click to add a word with the same meaning.
6. Appearance: colors, corners and what the suggestions show, with a live preview.

== Changelog ==

= 1.0.1 =
* Safer: if anything goes wrong inside smart search, the regular WooCommerce search answers instead of an error page.
* Shop tools that search products through the REST API (the WooCommerce mobile app, stock and accounting software) and searches for drafts or private products get the regular WordPress results again.
* Short words now also find their other forms in product titles ("sofy" finds "Sofa").

= 1.0.0 =
* First release.
* Smart search without an account: word forms, typos, product codes, prices ("up to 300", also in the shop's own currency) and stock, never fewer results than the regular search.
* AI search with your own OpenAI key: understands needs, problems and occasions; falls back to smart search if AI is unavailable.
* Live suggestions while customers type, styled by the theme; AI improves them a moment later.
* Synonyms in both modes, with one-click additions from searches that found nothing.
* Setup screen with measured quality and a cost calculator, dashboard, "Try it" comparison and search statistics.
* Cost protection: monthly spending limit, hourly allowance per visitor, no AI for bots, alerts.
* Multilingual shops with Polylang or WPML. Polish translation.

== Upgrade Notice ==

= 1.0.1 =
Safety update: errors inside smart search fall back to the regular search, shop tools get the regular results. Recommended for all shops.

= 1.0.0 =
First release.
