=== Creator Assistant Hub ===
Contributors: alessandrolioce
Tags: ai, openai, embeddings, vector-search, semantic-search
Requires at least: 6.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPL-2.0+
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The AI infrastructure for your WordPress content. Vectorize posts with OpenAI embeddings and store them in Qdrant for semantic search.

== Description ==

Creator Assistant Hub is the core infrastructure plugin of the Creator Assistant ecosystem. It connects your WordPress site to OpenAI and Qdrant to automatically generate and store vector embeddings for your content, enabling semantic search and AI-powered features.

**How it works**

The Hub is the shared infrastructure layer for the Creator Assistant ecosystem. When a compatible add-on is active and activates a vectorizer, the plugin generates vector embeddings via the OpenAI API and stores them in your Qdrant vector database cluster whenever a post is published or updated. This makes your content available for semantic search and retrieval by Creator Assistant add-ons. Without an active add-on, the Hub runs in standby mode: no content is sent to external services.

**Key features**

* **Automatic post vectorization**: when an add-on activates a vectorizer, embeddings are generated and stored whenever a post is published or updated. Without an active add-on, no vectorization takes place.
* **Chunk-based vectorization**: splits post content into word-level segments and stores each chunk as a separate Qdrant point, enabling fine-grained retrieval (activated by add-ons via filter).
* **Summary-based vectorization**: generates a short AI summary of each post via the OpenAI Responses API, then embeds and stores a single point per post for high-level semantic search (activated by add-ons via filter).
* **Background batch vectorization**: an hourly cron job automatically picks up any existing posts that have not yet been vectorized, so your entire content library is indexed without manual intervention.
* **OpenAI integration**: uses the `text-embedding-3-small` model (1536 dimensions) via the OpenAI Embeddings API for all vectorizers; the Summary vectorizer additionally calls the OpenAI Responses API (`gpt-4.1-nano`) to generate post summaries.
* **Qdrant integration**: stores and retrieves vector embeddings from your Qdrant Cloud cluster. Two collections are used: `post_chunk` for chunk-level points and `post_summary` for post-level summary points.
* **Block editor panel**: shows the vectorization status of each post directly in the block editor sidebar (document settings panel).
* **Post list column**: adds a "Vector Status" column to the posts and pages admin list, showing the vectorization status of each entry at a glance.
* **Settings page**: configure OpenAI API key, Qdrant endpoint and API key, and cache expiration from a dedicated admin page.
* **API response caching**: configurable cache duration to reduce API usage and latency.
* **Site Health check**: reports the Hub service status in the WordPress Site Health screen.
* **Qdrant keep-alive**: sends a daily lightweight ping to prevent free-tier Qdrant Cloud clusters from being suspended.
* **WPML compatible**: detects the post language via WPML hooks (when WPML is active) and includes it in the Qdrant payload for multilingual filtering.
* **Extensible**: exposes actions and filters so add-ons can register additional post types, override vectorizer behaviour, customise Qdrant payloads, and add settings tabs.

**Requirements**

* An [OpenAI](https://platform.openai.com/) account with a valid API key.
* A [Qdrant Cloud](https://cloud.qdrant.io/) account with an active cluster (free tier is supported).
* WordPress 6.8 or higher.
* PHP 7.4 or higher.

== Installation ==

1. Upload the `creator-assistant-hub` folder to the `/wp-content/plugins/` directory, or install the plugin directly from the WordPress plugin screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Creator Assistant → Hub** in the WordPress admin menu.
4. Accept the Terms of Service and Privacy Policy.
5. Enter your **OpenAI API key** in the OpenAI section.
6. Enter your **Qdrant endpoint URL** and **Qdrant API key** in the Qdrant section.
7. Save the settings. Green status notices will confirm that both services are connected.
8. Install a compatible Creator Assistant add-on (such as Creator Assistant Search) to activate vectorization. Once an add-on is active, new and updated posts are vectorized automatically on save, and existing posts in your library are picked up by the built-in hourly background batch. More add-ons are coming soon.

== External services ==

This plugin connects to up to three third-party services. By using this plugin you agree to their respective terms and privacy policies.

* **OpenAI**: used to generate vector embeddings from your post content via the Embeddings API. When the Summary vectorizer is active (enabled by an add-on), post content is also sent to the Responses API to generate a short AI summary before embedding.
  * 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)

* **Qdrant Cloud**: used to store and query vector embeddings.
  * Service: [https://cloud.qdrant.io/](https://cloud.qdrant.io/)
  * Privacy Policy: [https://qdrant.tech/legal/privacy-policy/](https://qdrant.tech/legal/privacy-policy/)
  * Terms of Service: [https://qdrant.tech/legal/terms_and_conditions/](https://qdrant.tech/legal/terms_and_conditions/)

* **Google (OAuth sign-in), through a proxy run by the plugin author**: used only if you click "Connect with Google" in the plugin settings, so that Creator Assistant add-ons can read data from your Google services. Nothing is sent before you click it, and "Disconnect" revokes the connection.
  * What is sent: your browser goes to Google's consent screen (the only scope the Hub requests is your account email; add-ons may request more, and say so on the settings page). When you accept, Google returns an authorization code to an AWS Lambda proxy (`*.lambda-url.eu-north-1.on.aws`) operated by the plugin author, which exchanges it with Google for tokens, because the Google client secret must not be shipped in a public plugin, and hands the tokens back to your site. The same proxy is called to refresh the access token. The proxy does not store the tokens; your site keeps the refresh token encrypted in its own database. The plugin also calls Google's userinfo endpoint to show the connected email, and Google's revoke endpoint when you disconnect.
  * Service: [https://accounts.google.com/](https://accounts.google.com/)
  * Google Privacy Policy: [https://policies.google.com/privacy](https://policies.google.com/privacy)
  * Google Terms of Service: [https://policies.google.com/terms](https://policies.google.com/terms)
  * Proxy operator (plugin author) Privacy Policy: [https://www.creator-assistant.it/privacy-policy](https://www.creator-assistant.it/privacy-policy)
  * Proxy operator Terms of Service: [https://www.creator-assistant.it/terms-of-service](https://www.creator-assistant.it/terms-of-service)

Data is only transmitted to OpenAI and Qdrant after you explicitly accept the Creator Assistant Terms of Service in the plugin settings and provide your own API credentials, and to Google only after you click "Connect with Google". No data is transmitted automatically upon activation.

== Frequently Asked Questions ==

= Do I need a paid OpenAI plan? =

Yes. The OpenAI API is a pay-as-you-go service: a valid payment method and prepaid credits are required. There is no free tier for API usage. The `text-embedding-3-small` model used by the Hub is very affordable: generating embeddings for a typical blog post costs a fraction of a cent. Check [OpenAI pricing](https://openai.com/pricing) for details.

= Does the plugin work with the free tier of Qdrant Cloud? =

Yes. The free tier of Qdrant Cloud provides a single cluster that may be suspended after a period of inactivity. The built-in keep-alive feature sends a daily ping to prevent this.

= Which post types are vectorized? =

By default, posts and pages are vectorized. Add-ons can register additional post types via the available hooks.

= Where can I see the vectorization status of a post? =

In two places:

1. **Block editor**: open any post or page in the editor. A **Creator Assistant** panel in the document settings sidebar (top-right area) shows the vectorization status for each active vectorizer.
2. **Post list**: a **Vector Status** column in the Posts and Pages admin list shows a green checkmark with the date of last vectorization, or a greyed-out label if the post has not yet been vectorized.

= How do I check whether the service is properly configured? =

Go to **Tools → Site Health**. A dedicated test named **Creator Assistant Hub service** reports whether the Terms of Service have been accepted and both OpenAI and Qdrant are connected and ready.

Also verify that WP-Cron is running correctly on your site. Vectorization is processed asynchronously via WP-Cron: if WP-Cron is disabled (e.g. `DISABLE_WP_CRON` is set to `true` in `wp-config.php`), posts will not be vectorized automatically. You can check this under **Tools → Site Health → Info → WordPress constants**. On some managed hosting plans, a real server-side cron job is used instead; make sure it is configured and firing regularly.

= Can I disable API response caching? =

Yes. In the **Cache** tab of the Hub settings page, set the cache expiration to **Disabled**.

= Is my API key stored securely? =

API keys are stored in the WordPress options table in the same way as other plugin settings. Make sure your WordPress database and hosting environment are secure. Keys are never exposed in the front end or in REST API responses accessible to non-administrators.

= Do I need an active add-on for vectorization to work? =

Yes. The Hub is a core infrastructure plugin: its vectorizers are disabled by default and must be activated by a compatible add-on (such as Creator Assistant Search). Without an active add-on, the plugin registers no vectorizers and no content is sent to OpenAI or Qdrant, even after you configure your API credentials.

= Does the plugin modify my posts, pages, or any existing content? =

No. The Hub only reads your content to generate vector embeddings. It never writes back to the post body, title, status, slug, or any other standard post field. Your content stays exactly as you wrote it.

The only things the Hub writes to your WordPress database are:

1. A **post meta entry** on each vectorized post that records when it was indexed (keys: `_creator_assistant_hub_post_vectorizer_post_chunk` and `_creator_assistant_hub_post_vectorizer_post_summary`). This metadata is invisible to visitors, does not appear in SEO tools, and has no effect on how WordPress renders the post.
2. The **plugin settings** you enter (API keys, cache TTL, Terms of Service acceptance), stored in the WordPress options table.

Everything else (the actual vector embeddings) lives in your Qdrant Cloud cluster, not in your WordPress database.

= Does the background cron job modify my content? =

No. The hourly background cron reads post content to generate embeddings but never writes to the post itself. The only write operation it performs is updating the post meta timestamp once vectorization is complete.

= What happens to my data if I deactivate or delete the plugin? =

**Deactivating** the plugin stops all vectorization and background processing; your post meta timestamps and settings are preserved so they are ready if you reactivate.

**Deleting** the plugin removes all plugin-created data from your WordPress database (post meta entries and options). Your Qdrant collections are not deleted automatically. You can remove them manually from your Qdrant Cloud dashboard if you no longer need them.

Your posts, pages, and all their original content are completely unaffected either way.

= What is the difference between Chunk and Summary vectorization? =

The Hub provides two vectorization strategies, each stored in a separate Qdrant collection:

* **Chunk**: the post content is split into word-level segments. Each segment is embedded individually and stored as a separate point in the `post_chunk` collection. This enables precise, paragraph-level retrieval.
* **Summary**: an AI-generated summary of the post is produced via the OpenAI Responses API, then embedded and stored as a single point in the `post_summary` collection. This enables high-level, concept-based semantic search.

Add-ons can enable either or both strategies independently via the `creator_assistant_hub_post_vectorizer_post_chunk` and `creator_assistant_hub_post_vectorizer_post_summary` filters.

= Does the plugin support multilingual sites? =

Yes. When WPML is active, the plugin detects the language of each post and includes it in the Qdrant payload. Add-ons can then filter search results by language. Sites without WPML are fully supported and unaffected.

= Can other plugins or add-ons extend the Hub? =

Yes. The Hub exposes WordPress actions and filters that add-ons can use to register additional settings sections, tabs, and custom behaviour. Developer documentation will be published on [creator-assistant.it](https://www.creator-assistant.it).

== Screenshots ==

1. The Hub settings page: General tab with Terms of Service acceptance.
2. OpenAI configuration tab with connection status notice.
3. Qdrant configuration tab with connection status notice.
4. Cache configuration tab to control how long API responses are cached.
5. Tools tab with reset, force reindex, and Qdrant self-test actions.
6. Vectorization status panel in the block editor sidebar.
7. "Vector Status" column in the posts admin list.
8. Creator Assistant Hub service test in the Site Health screen.

== Development ==

The source files for all compiled assets are included in the plugin: front-end
assets under `assets/src/`, and the block-editor integration under `src/`.

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

1. Install dependencies: `npm install`
2. Build the front-end assets: `npm run build`
   * JS only: `npm run build:js` (uses [esbuild](https://esbuild.github.io/))
   * CSS only: `npm run build:css` (uses PostCSS + Sass)
3. Build the block-editor integration: `npm run build:editor` (uses [@wordpress/scripts](https://www.npmjs.com/package/@wordpress/scripts))

Front-end JS source files are in `assets/src/js/` and compiled to `assets/dist/js/`.
Front-end CSS/SCSS source files are in `assets/src/css/` and compiled to `assets/dist/css/`.
Block-editor source files are in `src/` and compiled to `build/`.

== Changelog ==

= 1.2.0 =
* New: a single manager for changes to post content, for add-ons (filter `creator_assistant_hub_content_injectors`).
* New: action `creator_assistant_hub_post_vectorized`.
* New: `Qdrant_Client::scroll_points()` accepts a filter and can skip the vectors.
* New: `OpenAi_Client::get_structured_response()` accepts the model, reasoning effort and timeout (filter `creator_assistant_hub_openai_structured_options`).
* New: action `creator_assistant_hub_cluster_batch_received`, fired once per `POST .../clusters` after the per-cluster `creator_assistant_hub_clusters_received` actions, with `array( 'collection', 'source_service', 'clusters' )` (the raw top-level clusters, children and members included, so a listener can read a hierarchical tree).
* New: `GET .../collections/{collection}/points` accepts `match[<field>]=v1,v2` query parameters to restrict the points to those whose payload field equals one of the values.
* New: `Clients\Clustering_Client` (trigger and task status of the clustering Lambda) and the `CREATOR_ASSISTANT_HUB_CLUSTERING_LAMBDA_URL` constant, shared by the add-ons that cluster a collection.
* Changed: the clustering job identifies itself as `clustering-job`; the previous name `planner-clustering-lambda` is still accepted until the deployed image is rebuilt.

= 1.1.0 =
* New: `creator_assistant_hub_menu_positions` filter (menu slug => integer position, lower first) to order the entries of the Creator Assistant admin menu. Each add-on declares the position of its own entry and the Hub sorts the menu; the Hub page always stays first, so the top-level menu keeps opening it, and entries without a position go last, in the order they were added. Before, the order was the order of registration, and a post type added under the menu came even before the Hub page.
* Changed: the text passed to the vectorizers, and to the `creator_assistant_hub_post_vectorizer_text` filter, is now lightweight Markdown: headings, paragraphs, lists, quotes, code blocks and tables keep their structure instead of being flattened into one line. Classic-editor content (no `<p>` tags) keeps its paragraphs too. Parts returned by that filter are joined as separate paragraphs, so `Document::normalize_array()` now returns separate paragraphs instead of one line. New helpers `Document::html_to_markdown()` and `Document::normalize_markdown()`; `Document::html_to_text()` is unchanged.
* Changed: post summaries are now 3-5 sentences of plain prose, stating the topic, angle and subtopics of the post, without lists, Markdown or opening phrases like "This article". The instructions are exposed as `OpenAi_Client::SUMMARIZE_INSTRUCTIONS`, and the summary cache key includes them, so a prompt change never returns a stale summary. A truncated response (status `incomplete`) is still returned, but is not cached.
* Note: after updating, every collection must be re-indexed with the "force reindex" action of the Tools tab, because both the vectorized text and the summaries change. Summaries are longer, so the OpenAI output cost per post roughly doubles. Product summaries of creator-assistant-search-pro go through the new prompt too. If you use creator-assistant-planner, re-tune its similarity thresholds after re-indexing.
* Fixed: a post with a code example containing HTML (for instance `&lt;div&gt;` in a code block) is no longer left without chunks. The chunk that contains markup now has its tags stripped before it is indexed, instead of the whole post being discarded and retried by the cron on every run.
* Fixed: post summaries were never generated when the configured chat model is a reasoning model (for example gpt-5-nano). The request allowed 300 output tokens, reasoning included, and the model spent them all thinking and returned no text. It now allows 2000.
* Changed: every option, transient, admin-post action, query argument, CSS class and Qdrant collection now carries the plugin's full prefix (`creator_assistant_hub_*`, `creator-assistant-hub-*`) instead of `cah_*`, `ca-*` or no prefix. Custom CSS targeting the old `.ca-*` classes needs the new names.
* New: several WordPress sites can share one Qdrant cluster. Every collection name now carries a random identifier of the site (`creator_assistant_<id>_hub_post_chunk`), created the first time it is needed and stored in an option, so it does not change when the domain does and two sites never write into the same collection. It can be overridden with the `creator_assistant_hub_qdrant_namespace` filter, and a new one can be generated from the Tools tab, which a copy of a site (staging) should do. The `creator_assistant_hub_qdrant_namespace_changed` action fires when it changes.
* Changed: Qdrant cannot rename a collection, so on the first admin page load after updating the old ones (`post_chunk`, `post_summary`) are deleted and every post is indexed again into the new ones by the hourly cron; the cost is one more round of OpenAI embeddings.
* New: REST endpoints `GET /wp-json/creator-assistant-hub/v1/collections/{collection}/points` and `POST /wp-json/creator-assistant-hub/v1/clusters`, both authenticated via an RS256 JWT bearer token. Intended for a future external clustering service; not yet part of the public plugin, as no service is authorized to call them until its key pair is generated and registered.
* New: filter `creator_assistant_hub_authorized_cluster_services` (service name => PEM public key) to add or remove the external services allowed to call those two endpoints. A service signs its JWT with its own private key, with its name as `iss` and `creator-assistant-hub` as `aud`.
* New: extensibility hook `creator_assistant_hub_clusters_received`, fired once per top-level cluster after `POST .../clusters` stores it, with payload `array( 'id', 'collection', 'source_service', 'centroid_point_id', 'aggregate', 'core_points' )`, forwarded as the clustering job sent it (Hub does no Qdrant reads here: resolving a label or the text of the core points is up to the listener).
* Changed: `label` in that payload is no longer an OpenAI-generated paraphrase of the whole cluster, and the hook no longer carries `label` or `member_queries` at all - saves one OpenAI call per cluster. `OpenAi_Client::generate_label()` has been removed as a result.
* New: the "Google Connection" settings section now shows a plain-language description of what connecting a Google account is for. New filter `creator_assistant_hub_google_connected_services` (default: empty array) lets add-ons that use the Google connection list, in their own words, why the site owner should enable it; when the filter returns a non-empty array, an intro sentence and the list are shown above the connect/disconnect button.
* Fix: in `SCRIPT_DEBUG` mode, the two Sass-authored stylesheets (`ai-animated-border`, `settings-tabs`) threw a fatal error instead of loading — their compiled `dist` file is the only browser-usable form, but the asset loader always looked for a same-named file in `src` first. It now falls back to `dist` for them.
* New: extensibility hooks `creator_assistant_hub_google_connected` and `creator_assistant_hub_google_disconnected`, fired after a Google account is connected or disconnected, so add-ons that cache data read through the connection (property lists, account info, …) can drop that cache instead of serving it stale until its own TTL expires.
* Fixed: a payload index declared by an add-on through `creator_assistant_hub_post_chunk_required_payload_indexes` or `creator_assistant_hub_post_summary_required_payload_indexes` (the `lang` index of creator-assistant-hub-pro, the product fields of creator-assistant-search-pro) was created only by the next post vectorization. Activating or updating the add-on on a site already indexed made every filtered search fail with "Index required but not found" until some post was saved. The indexes are now synced on the next admin page, cron run or WP-CLI command, with no Qdrant call while the declared indexes are unchanged. An index Qdrant rejects is no longer marked as created: the next vectorization tries again, and the sync after 15 minutes. New method `Post_Vectorizer::sync_payload_indexes()`; a strategy declares its indexes by overriding `Post_Abstract::get_required_payload_indexes()`.
* Changed: `Qdrant_Client::collection_exists()` now returns `null` not only without credentials but also when the request fails (network error, non-2xx status, unreadable body), instead of `false`: `false` now always means Qdrant answered that the collection does not exist. Compare the result with `true`/`false` explicitly. New `Qdrant_Client::is_configured()` tells the two `null` cases apart. A failed check no longer makes the payload-index sync, the collection creation before a vectorization or the upgrade of the collection names treat an existing collection as missing.
* Fix: a failed Google connection attempt (consent denied, the OAuth proxy unreachable, no refresh token in its response, …) silently bounced back to the same "Connect with Google" button with no indication anything went wrong — the only trace was a `WP_DEBUG`-gated log line. The "Google Connection" settings section now shows an error notice in that case.

= 1.0.2 =
* New: `CreatorAssistantHub\Utils\Settings_Tabs`, a shared renderer for the family's tabbed settings pages. It owns the tab markup, the CSS classes, the tab-switching script and the validation of add-on-supplied tab definitions, so every add-on with its own settings page gets the same behaviour without copying it. Enqueue `Settings_Tabs::ASSET_HANDLE` (or declare it as a dependency of your own handle) to pull in the stylesheet and script.
* Fix: a settings section that no tab claims is now rendered in the first tab instead of being dropped. Dropping it removed its fields from the form entirely, so the value could never be saved and the add-on author got no hint why.
* Change: a tab can declare `hide_submit => true` to hide the Save button while it is active. Replaces the previous hard-coded list of tab slugs in the script.

= 1.0.1 =
* Fix: added `Plugin::run_at_init()`, a helper that defers a callback to the `init` hook (or runs it immediately if `init` has already fired). Creator Assistant Search 1.0.0 already calls this method for its theme-aware registration logic (depends on `wp_is_block_theme()`); without this update, sites running both plugins hit a fatal error.

= 1.0.0 =
* Initial release.
* Automatic post and page vectorization using OpenAI `text-embedding-3-small`.
* Qdrant Cloud integration for vector storage and retrieval.
* Settings page with TOS acceptance, OpenAI, Qdrant, and cache configuration.
* Block editor sidebar panel showing per-post vectorization status.
* Post list column ("Vector Status") with per-vectorizer status indicators.
* Hourly background batch cron to automatically vectorize existing content.
* Site Health integration reporting service status.
* Daily Qdrant keep-alive cron for free-tier clusters.
* Extensibility hooks for add-ons, by category. Settings: `creator_assistant_hub_loaded`, `creator_assistant_hub_after_register_settings`, `creator_assistant_hub_settings_tabs`, `creator_assistant_hub_sanitize_settings`; OpenAI models: `creator_assistant_hub_openai_embedding_model`, `creator_assistant_hub_openai_chat_model`, `creator_assistant_hub_embedding_dimension`; vectorizer control: `creator_assistant_hub_post_vectorizer_post_chunk`, `creator_assistant_hub_post_vectorizer_post_summary`, `creator_assistant_hub_skip_vectorizer`, `creator_assistant_hub_post_vectorizer_text`, `creator_assistant_hub_post_vectorizer_chunks`; post types: `creator_assistant_hub_additional_post_types`, `creator_assistant_hub_excluded_post_types`; Qdrant payloads: `creator_assistant_hub_post_vectorizer_post_chunk_payload`, `creator_assistant_hub_post_vectorizer_post_summary_payload`, `creator_assistant_hub_post_vectorizer_post_chunk_search_filter`; collection lifecycle: `creator_assistant_hub_post_vectorizer_post_chunk_collection_created`, `creator_assistant_hub_post_vectorizer_post_summary_collection_created`.

== Upgrade Notice ==

= 1.1.0 =
After updating, run "Force reindex" from the Tools tab: the indexed text and the summaries change, and the Qdrant collections are renamed, so every post is indexed again (one more round of OpenAI costs). Update the Hub before updating Search or Knowledge.

= 1.0.2 =
Adds the shared settings-tabs renderer used by add-on settings pages. Update the Hub before updating an add-on that requires it.

= 1.0.1 =
Fixes a fatal error on sites running Creator Assistant Search alongside the Hub. Update immediately.

= 1.0.0 =
Initial release. No upgrade steps required.
