=== Commervia AI Search for WooCommerce ===
Contributors: commervia
Tags: woocommerce, product search, ajax search, ai search, ecommerce
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Fast hybrid WooCommerce product search with instant local results and optional AI enrichment for natural-language queries.

== Description ==

Commervia AI Search for WooCommerce improves product discovery with a hybrid local-first search engine, instant AJAX results and relevance-weighted matching across your WooCommerce catalog.

Simple and structured product searches are resolved immediately against a dedicated normalized local index. Natural-language searches can show useful local results first and, when the administrator has enabled OpenAI, optionally receive a second semantic interpretation that can refine or reorder the result set.

The plugin works locally without requiring a Commervia account or an AI service.

= Search features =

* Hybrid local-first search: common product queries do not wait for AI interpretation.
* Instant AJAX product results while shoppers type.
* Dedicated normalized product index for titles, categories, tags, attributes, SKU and EAN/barcode values.
* Three query levels: direct, enriched and semantic.
* Local previews can be refined by optional AI interpretation only when the query benefits from it.
* Normalization for common spacing, plural and hyphen variations such as `powerbank`, `power bank` and plurals.
* Candidate preselection limits full relevance scoring to the strongest local matches.
* Adaptive debounce and cancellation of superseded browser requests.
* Separate browser caches for local previews and final enriched results.
* Relevance weighting for product titles, SKU and EAN/barcode values.
* Matching across categories, tags, attributes and product descriptions.
* Exact, highly relevant and relevant result labels.
* Quick product details directly from the search results.
* A link to view the complete matching result set.
* Automatic enhancement of WooCommerce product-search forms.
* Support for the WooCommerce Product Search block.
* Mobile-aware positioning for search forms near the top or bottom of the viewport.
* Configurable minimum characters, delay, result limits, cache duration and accent color.
* Optional custom selectors for themes or search forms with non-standard markup.

= Optional AI interpretation =

The local search remains fully functional without OpenAI.

When an administrator supplies their own OpenAI API key, explicitly enables AI query interpretation and consents to the external service, OpenAI is used only when the query benefits from semantic interpretation. Direct searches such as `powerbank`, `cafetera` or `batería externa` can remain entirely local. Product matching and selection still take place locally in WordPress.

= Separate Search Pro add-on =

Visual image search and configurable custom-meta search are available through a separate Commervia AI Search Pro for WooCommerce add-on distributed outside WordPress.org. Their implementation is not included in this WordPress.org plugin.

The free plugin is complete, remains usable permanently and never expires.

== Installation ==

1. Install and activate WooCommerce.
2. Install and activate Commervia AI Search for WooCommerce.
3. Go to **WooCommerce > AI Search**.
4. Configure the search behavior and save the settings.
5. Test a product search on the storefront.
6. Optional: add your own OpenAI API key, enable AI interpretation and provide explicit consent.

== Screenshots ==

1. Real storefront instant results panel while the customer searches in natural language.
2. Real quick product view with price, availability and matching interpretation.
3. Real administration screen with the core Free Search behavior settings.
4. Real administration screen with optional OpenAI interpretation settings and the separate Pro add-on panel.

== Frequently Asked Questions ==

= Is OpenAI required? =

No. The relevance-weighted local search works without an API key. OpenAI is optional and can improve interpretation of natural-language searches.

= Does the plugin send my product catalog to OpenAI? =

No. Only the shopper's search text and the technical parameters documented below are sent when the administrator has explicitly enabled and consented to the service. Product matching stays inside WordPress.

= Does the free plugin expire? =

No. All functionality included in this WordPress.org plugin remains available permanently.

= Does it work with WooCommerce product search forms? =

Yes. It can automatically enhance standard WooCommerce product-search forms and the Product Search block. An additional CSS selector can also be configured for custom theme search forms.

= Where are visual search and custom meta-key search? =

They are delivered by a separate Pro add-on distributed outside WordPress.org. The add-on implementation is not present in this WordPress.org plugin.

= How are translations handled? =

The plugin source is fully internationalized and ready for community translations through translate.wordpress.org.

= Can I use this together with Commervia AI? =

Commervia AI already contains a broader search module. When the complete plugin is active, Commervia AI Search avoids loading a duplicate storefront search interface.

== External services ==

This plugin can connect directly to the OpenAI API only after an administrator:

1. enters their own OpenAI API key;
2. enables AI query interpretation; and
3. explicitly consents to sending the search text to OpenAI.

Data sent to OpenAI:

* the text entered in the product search;
* the site language;
* the selected OpenAI model; and
* technical parameters required to request a structured JSON response.

The complete product catalog, WooCommerce orders and customer data are not sent. OpenAI's response is used only to extract search terms and filters; product selection runs locally in WordPress.

Service: OpenAI API  
Terms of Use: https://openai.com/policies/terms-of-use/  
Privacy Policy: https://openai.com/policies/privacy-policy/

Links to Search Pro or Commervia AI contact commervia.ai only when an administrator deliberately clicks them. The free plugin does not create a Commervia account and does not transmit site data to Commervia automatically.

== Privacy ==

The plugin stores its settings and a normalized product-search index in the WordPress database. The local index contains product search fields only and does not contain orders or customer data. The OpenAI API key is encrypted locally using Sodium and the WordPress security keys. Search responses may be stored temporarily in WordPress transients to improve performance. A functional language preference is stored for up to one year in browser local storage and the `commervia_ai_search_language` cookie. The plugin adds no telemetry or remote tracking.

== Changelog ==

= 1.0.5 =
* Added a hybrid local-first search pipeline with direct, enriched and semantic query levels.
* Added a dedicated normalized local product index for faster candidate lookup.
* Simple product searches can now return without waiting for an OpenAI request.
* Natural-language searches can show local results first and be refined when optional AI interpretation arrives.
* Added normalization for spacing, plurals and common product-name variations such as `powerbank` / `power bank`.
* Added structured specification matching for values such as capacity, power, dimensions and storage.
* Limited full relevance scoring to the strongest indexed candidates when possible.
* Added adaptive debounce, immediate cancellation of superseded requests and separate local/final browser caches.
* Preserved the fully separated Free/Pro architecture required by the WordPress.org Plugin Directory.
* Tested with WooCommerce 11.0.

= 1.0.4 =
* Hardened request rate limiting so client-controlled cookies cannot create new rate-limit buckets.
* Clarified the separation between the fully functional free plugin and separately distributed add-ons.
* Added generic extension hooks without bundling add-on search implementations in the WordPress.org package.
* Tested with WooCommerce 11.0.
