=== Creator Assistant Search ===
Contributors: alessandrolioce
Tags: ai, artificial-intelligence, search, semantic-search, openai
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: creator-assistant-hub
Stable tag: 1.1.0
License: GPL-2.0+
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Make your site search truly intelligent.

== Description ==

Creator Assistant Search is an add-on for [Creator Assistant - Hub](https://wordpress.org/plugins/creator-assistant-hub/) that brings AI-powered search to your WordPress site. When a visitor performs a search, the plugin retrieves the most semantically relevant content from your Qdrant vector database and generates a concise AI Overview (displayed at the top of the search results page) using OpenAI's chat models.

**How it works**

1. When a search query is submitted, the plugin converts it into a vector embedding via the Hub and queries your Qdrant collection for the most relevant content chunks.
2. The matching chunks are assembled into a prompt and sent to the OpenAI Chat API to generate a short, direct answer.
3. The answer is streamed progressively to the browser and displayed as an **AI Overview** panel above your search results, in both block themes and classic themes. Subsequent searches for the same query return the cached result instantly.

**Key features**

* **AI Overview panel**: a concise AI-generated answer appears at the top of every search results page, based exclusively on your own site content.
* **Semantic search**: results are ranked by semantic relevance (vector similarity) rather than keyword matching alone.
* **Block theme and classic theme support**: the AI Overview is injected via the `render_block_core/query` filter in block themes, and via the `loop_start` action in classic themes.
* **Animated UI**: the overview uses the Hub's animated border component and the typed-text effect for a modern look.
* **Source attribution**: the panel lists the source posts used to generate the answer.
* **Language-aware**: the AI response is generated in the language of your site.
* **Color scheme**: choose between automatic (follows system preference), light, or dark mode for the AI Overview panel from the WordPress Customizer (**Appearance → Customize → AI Overview**).
* **Streaming response**: the AI answer is delivered via Server-Sent Events and typed progressively into the panel, with no page reload required.
* **Customizable prompt**: from **Creator Assistant → Search**, use the default prompt, add your own instructions to it, or replace it entirely. The prompt actually in use is always shown on the page.
* **Two kinds of answer**: the AI answers the question directly when your content contains the answer, and otherwise explains briefly what it found, so a search for recipes or guides does not get a made-up definitive answer.
* **Shortcode and block**: turn off the automatic insertion and place the panel yourself, with the "AI Overview" block in the Search template of a block theme, or the `[creator_assistant_search_ai_overview]` shortcode in `search.php` of a classic theme. Both render exactly the same panel.
* **Extensible**: exposes filters and actions so other add-ons can customise the sources list, script data, prompt context, and the prompt itself block by block.

**Requirements**

* [Creator Assistant - Hub](https://wordpress.org/plugins/creator-assistant-hub/) **1.0.2 or higher**, with OpenAI and Qdrant configured and at least one vectorizer active. The settings page uses the shared tab renderer the Hub publishes in 1.0.2, so update the Hub first: WordPress cannot express a minimum version in `Requires Plugins`.
* WordPress 6.6 or higher.
* PHP 7.4 or higher.

== Installation ==

1. Install and configure **Creator Assistant - Hub** first. Make sure the OpenAI API key, Qdrant endpoint, and API key are saved and both connections show a green status.
2. Upload the `creator-assistant-search` folder to the `/wp-content/plugins/` directory, or install the plugin directly from the WordPress plugin screen.
3. Activate the plugin through the **Plugins** screen in WordPress.
4. The plugin activates the Hub's vectorizer automatically. Existing posts will be indexed by the Hub's hourly background cron; new and updated posts are vectorized on save.
5. Perform a search on your site. An **AI Overview** panel will appear at the top of the results once at least some content has been vectorized.

== External services ==

This plugin sends data to OpenAI to generate the AI Overview shown on your search results page. By using this plugin you agree to OpenAI's terms and privacy policy.

* **OpenAI**: when a visitor performs a search, the matching content chunks retrieved from your Qdrant database (via Creator Assistant - Hub) are assembled into a prompt together with the visitor's search term and sent to the Chat Completions API to generate the AI Overview answer.
  * Service: [https://platform.openai.com/](https://platform.openai.com/)
  * Privacy Policy: [https://openai.com/policies/privacy-policy](https://openai.com/policies/privacy-policy)
  * Terms of Use: [https://openai.com/policies/terms-of-use](https://openai.com/policies/terms-of-use)

This plugin relies on **Creator Assistant - Hub** for the OpenAI embeddings and Qdrant vector-search connections used to find relevant content for each query. See the Hub's own "External services" section for details on that part of the data flow.

Data is only sent to OpenAI when a visitor performs a search on your site. Nothing is transmitted automatically upon activation.

== Frequently Asked Questions ==

= Does this plugin work without Creator Assistant - Hub? =

No. Creator Assistant Search is an add-on that requires Creator Assistant - Hub to be installed and configured. The Hub provides the OpenAI and Qdrant connections that this plugin relies on.

= Which post types are included in the search? =

By default, posts and pages are vectorized and included in search results. If you have Creator Assistant - Hub Pro, you can exclude specific post types from the Content tab in the Hub settings page.

= Does the AI Overview appear for every search? =

The AI Overview appears when the plugin finds at least one relevant content chunk for the search term. If no relevant content is found in your Qdrant collection, the standard search results are shown without the overview panel.

= The AI Overview never appears: what should I check? =

This usually means your content has not been vectorized yet. Vectorization is handled entirely by Creator Assistant - Hub: new and updated posts are vectorized on save, and existing posts are picked up by the Hub's hourly WP-Cron batch, which requires WP-Cron to be running on your site. See the "How do I check whether the service is properly configured?" question in the [Creator Assistant - Hub](https://wordpress.org/plugins/creator-assistant-hub/) readme for the Site Health check and WP-Cron troubleshooting steps.

= How long does the AI Overview take to appear? =

The overview is generated asynchronously via Server-Sent Events: the page loads with the standard search results immediately. The AI answer is then streamed progressively into the panel character by character (typically within a few seconds). If the answer for the same query was already cached, it appears almost instantly.

= Is the AI Overview cached? =

Yes. The generated answer is cached for one hour using WordPress transients. Repeated searches for the same query within that window return the cached result without any OpenAI API call.

Administrators can bypass the cache for a specific search by appending `?cas_no_cache=1` to the search URL (e.g. `https://example.com/?s=shoes&cas_no_cache=1`). This forces a fresh OpenAI call and overwrites the cached result. The bypass is only available to users with the `manage_options` capability and has no effect for regular visitors.

= Does the plugin modify my posts, pages, or theme files? =

No. Creator Assistant Search is entirely non-destructive. It injects the AI Overview panel above search results using standard WordPress hooks (`render_block_core/query` for block themes, `loop_start` for classic themes). No theme files are ever touched. Your posts, pages, and all their content remain exactly as they are.

= Are my visitors' search queries stored in the database? =

Search queries are never stored in plain text in your database. The plugin uses an anonymous hash of the query as a transient cache key for the AI response. The cached answer expires automatically after one hour and is then deleted. No query logs, no user identifiers, no permanent records.

The search term itself is sent to OpenAI to generate the AI answer (subject to OpenAI's privacy policy), but it is not stored persistently by this plugin.

= Does the AI Overview replace my existing search results? =

No. The AI Overview is an additional panel displayed above your standard search results. It does not remove, reorder, or replace any of them. If no relevant content is found in your Qdrant collection, the standard results are shown without any panel at all.

= Can I customise the appearance of the AI Overview? =

Yes, in two ways:

1. **Color scheme**: go to **Appearance → Customize → AI Overview** and choose between automatic (follows the visitor's system preference), light, or dark mode. Changes are previewed live in the Customizer.
2. **Custom CSS**: the panel uses CSS classes prefixed with `creator-assistant-search__ai-overview` that you can override in your theme stylesheet. The animated border and typed-text effect are provided by Creator Assistant - Hub's shared assets.

= Can I place the AI Overview panel somewhere else? =

Yes, but it has to go in whatever renders your **search results page**. The panel is built from the site's main search query, so it produces nothing anywhere else. Putting the block or the shortcode in a normal page or in a page template will show nothing at all.

First, in **Creator Assistant → Search**, turn off "Insert the AI Overview automatically in search results". Leaving it on means two sources competing for the same panel: it is still shown at most once per page, but whichever renders first wins, so it may not appear where you placed it.

Then place it, depending on your theme:

* **Block theme**: go to **Appearance → Editor → Templates → Search** and insert the "AI Overview" block, usually right above the query loop that lists the results. If your theme has no Search template, use its Index template instead.
* **Classic theme**: add the `[creator_assistant_search_ai_overview]` shortcode to `search.php` in your child theme.

Both render exactly the same panel. A custom "search page" built with a query loop on a normal page will not work: WordPress does not treat that as a search results page, so the panel has no query to answer.

= Can I change what the AI is told to do? =

Yes. In **Creator Assistant → Search** you can keep the default prompt, add your own instructions on top of it, or replace it completely. The page always shows the prompt currently in use, including the sections added by add-ons such as Creator Assistant - Search Pro.

Adding instructions is usually the better choice: your text is appended to the default prompt, so you keep the improvements shipped with future plugin updates.

== Screenshots ==

1. The AI Overview panel with source attribution, displayed above search results in a block theme.
2. The Customizer color scheme control for the AI Overview panel.
3. The AI Overview panel in dark mode.
4. The Search settings page: keep the default prompt, add your own instructions to it, or replace it entirely. The prompt actually in use is always shown, and the Display section turns the automatic insertion off in favour of the shortcode or the block.
5. The "AI Overview" block selected in the Search template in the Site Editor. The list view shows where it belongs, between the search form and the list of posts. That placement matters: the panel is built from the search query, so in a normal page or a page template it would show nothing at all.

== Changelog ==

= 1.1.0 =
* New: "AI Overview" block for the block editor, so the panel can be placed manually in the Search template instead of relying on automatic insertion.
* New: `[creator_assistant_search_ai_overview]` shortcode for classic themes, rendering exactly the same panel as the block.
* New: automatic insertion of the AI Overview can now be turned off from the settings page, in favour of the shortcode or the block.
* New: customizable prompt on the **Creator Assistant → Search** settings page — keep the default, add your own instructions on top of it, or replace it entirely. The prompt actually in use is always shown on the page.
* New: the settings page groups its sections into tabs when an add-on (such as Creator Assistant - Search Pro) adds one, using the shared tab renderer published by Creator Assistant - Hub 1.0.2.
* New: `creator_assistant_search_prompt_blocks` filter to customise the AI instructions block by block.
* Fix: the AI could occasionally answer with the internal mode label (e.g. "DIRECT ANSWER") instead of a real answer.
* Fix: resolved a WordPress.org Plugin Check warning on the block's `render.php`.
* Now requires Creator Assistant - Hub 1.0.2 or higher.

= 1.0.0 =
* Initial release.
* AI Overview panel with semantic search via Qdrant and OpenAI Chat API.
* Support for block themes (`render_block_core/query`) and classic themes (`loop_start`).
* Animated border and typed-text UI components from Creator Assistant - Hub.
* Source attribution list below the AI answer.
* Language-aware AI responses using the site locale.
* One-hour answer cache (transients) to reduce API usage.
* Color scheme setting (auto/light/dark) in the WordPress Customizer with live preview.
* Streaming AI response via Server-Sent Events (SSE).
* Extensibility hooks: `creator_assistant_search_query_no_answer` (action, fired when the AI returns no usable answer), `creator_assistant_search_sources` (filter, customise the sources list), `creator_assistant_search_script_data` (filter, customise JS data), `creator_assistant_search_get_prompt_context` (filter, access prompt context for other add-ons).

== Development ==

The source files for all compiled assets are included in the plugin under `assets/src/` (front-end JS and CSS) and `src/` (block editor).

Build tools required: [Node.js](https://nodejs.org/) (includes npm).

1. Install dependencies: `npm install`
2. Build everything: `npm run build`
   * JS only: `npm run build:js` (uses [esbuild](https://esbuild.github.io/))
   * CSS only: `npm run build:css` (uses PostCSS + Sass)
   * Block editor only: `npm run build:editor` (uses [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts))
3. Watch during development: `npm run watch` for JS and CSS, `npm run start:editor` for the block.
4. Run the test suite: `composer install`, then `npm test` (PHPUnit with WordPress stubs, no database required).

Source JS files are in `assets/src/js/` and compiled to `assets/dist/js/`.
Source CSS/SCSS files are in `assets/src/css/` and compiled to `assets/dist/css/`.
Block sources are in `src/blocks/` and compiled to `build/blocks/`.

== Upgrade Notice ==

= 1.1.0 =
Requires Creator Assistant - Hub 1.0.2 or higher (the new tabbed settings page uses the tab renderer the Hub publishes starting in that version). Update the Hub first.

= 1.0.0 =
Initial release. No upgrade steps required.
