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

Adds a private knowledge base post type indexed to Qdrant for precise AI responses.

== Description ==

Creator Assistant Knowledge is an add-on for [Creator Assistant - Hub](https://wordpress.org/plugins/creator-assistant-hub/) that lets you maintain a private, admin-only knowledge base. Entries are vectorized and stored in your Qdrant cluster so the AI can draw on them when answering search queries — without ever exposing them to site visitors.

**Your existing posts and pages are never modified.** The plugin creates a new private post type (`ca_knowledge`) and creates draft entries when visitors give negative feedback on an AI answer. No public content is touched.

**Key features**

* **Private knowledge base** — a dedicated `Knowledge` section appears in the WordPress admin where you can write private articles, FAQs, and reference material for the AI. These entries are completely invisible to visitors: they have no public URL, do not appear in search results, and are never linked from the frontend.
* **Automatic indexing into a private collection** - knowledge entries are vectorized by Creator Assistant Hub whenever they are published or updated, into a Qdrant collection this plugin owns (`creator_assistant_knowledge_chunk`) rather than the shared one. Nothing else on the site can read them: only the AI Overview answer does.
* **Feedback loop** — when a visitor reports that an AI Overview answer did not help (or a search query receives no answer at all), the plugin automatically creates a draft knowledge entry pre-filled with the query and the AI response. Admins can review and improve these drafts, then publish them so the AI learns from the gap.
* **No duplicate drafts** - before creating one, the plugin compares the query with the searches already assigned to existing entries. The same question asked in different words is added to the entry that already covers it instead of producing a second draft, and the entry counts one more request. How similar two searches have to be is a setting.
* **Sorted by demand** - the entry list shows how many times each gap was asked for, and the column sorts, so you can answer the questions people actually ask first.
* **Origin at a glance** - the entry list also shows why each draft exists: a negative rating, an unanswered search, or written by hand, so you know which entries came from a real gap before you open them.
* **Sources shown only to editors** - knowledge entries contribute to the AI answer, and the AI Overview panel lists them as sources only for users who can edit them, linking to the edit screen. A visitor never sees them: a source with no public URL would be a dead link, and the knowledge base stays invisible end-to-end.

**Requirements**

* [Creator Assistant - Hub](https://wordpress.org/plugins/creator-assistant-hub/) installed, activated, and configured.
* [Creator Assistant Search](https://wordpress.org/plugins/creator-assistant-search/) (for the feedback feature).
* WordPress 6.6 or higher.
* PHP 7.4 or higher.

== Installation ==

1. Make sure **Creator Assistant - Hub** and **Creator Assistant Search** are installed and configured.
2. Upload the `creator-assistant-knowledge` folder to the `/wp-content/plugins/` directory.
3. Activate the plugin through the **Plugins** screen in WordPress.
4. A **Knowledge** menu item appears in the WordPress admin. Create and publish entries there; they will be vectorized automatically.

== Screenshots ==

1. The control on the search results page. Under an AI Overview answer, with its sources, visitors see a single button to report that it did not answer their question. That report (or a search with no answer at all) is what creates a draft knowledge entry.
2. The Knowledge list in the admin. Each entry shows how many different searches were assigned to it, how many times it was asked for (the column sorts, so you can answer the most requested gaps first) and its origin: a negative rating, an unanswered search, or written by hand.
3. A knowledge entry created from visitor feedback. The "Assigned searches" panel in the editor sidebar groups every wording of the same question under the one entry and shows how many times it was asked for: cover them in the content so the AI can answer them.
4. The Knowledge settings page. The similarity threshold decides how close two searches must be to count as the same question and be grouped under one entry instead of creating a new draft.

== External services ==

This plugin relies on **Creator Assistant - Hub** for its connections to OpenAI and Qdrant; see the Hub's own "External services" section for full details on that data flow. This plugin's own use of those services:

* **OpenAI**: knowledge base entries are sent to the Embeddings API (via the Hub) whenever they are published or updated, to generate the vector used to index them and to match visitor searches against private entries.
  * 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**: knowledge entry vectors are stored in two collections this plugin owns (`creator_assistant_<id>_knowledge_chunk` and `creator_assistant_<id>_knowledge_intent`, where `<id>` is the random identifier Creator Assistant Hub gives each site so several sites can share one Qdrant cluster), separate from the Hub's shared collection so nothing else can read them.
  * 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/)

Data is only transmitted once you have configured Creator Assistant - Hub with your own API credentials and accepted its Terms of Service. Nothing is transmitted automatically upon activation of this plugin.

== Frequently Asked Questions ==

= Will knowledge entries appear on my site? =

No. The `ca_knowledge` post type is registered as strictly private:

* `publicly_queryable: false` — direct URL requests return a 404.
* `exclude_from_search: true` — entries never appear in WordPress search results.
* `has_archive: false` — no archive page exists.
* `rewrite: false` — no pretty permalink is generated.

There is no way for a visitor to access or discover knowledge entries from the frontend.

= Does the plugin modify my existing posts or pages? =

No. Creator Assistant Knowledge only creates new entries in its own private post type. Your existing posts, pages, custom post types, and all their content are completely untouched.

= There is no way to say the answer was good. Why? =

Because nothing would be done with it. This plugin acts on gaps: what it can do with "this did not help" is open a draft entry for an admin to answer. A button that records nothing would be a control that lies about what it does, so there is only one, and it reports a problem.

= When a visitor reports an answer, does that create a public post? =

No. The plugin creates a **draft** entry of the private `ca_knowledge` post type. Drafts are never publicly visible. The entry is pre-filled with the search query and the AI response so an admin can review it, improve it, and publish it to the knowledge base — at which point it becomes available to the AI but remains invisible to visitors (see above).

= Does every report create a new draft? =

No. Before creating a draft the plugin embeds the query and compares it with the searches already assigned to existing entries, published or draft. Above a similarity threshold the query is recorded on the entry that already covers it and no new draft is created, so a gap asked in ten different wordings produces one entry with ten recorded searches instead of ten drafts. The searches assigned to an entry are listed in a panel in the editor sidebar, and the entry list shows how many wordings and how many requests each entry has collected.

= How do I change how aggressively drafts are merged? =

Creator Assistant, then Knowledge. The similarity threshold is the only setting there, and the page explains what the numbers mean.

The whole range is usable. At 1 nothing is ever merged and every new wording gets its own entry. At 0 everything is merged: after the first entry, no new one is created and every unanswered search is filed under it. In between, raise it and you get a second draft for a question you already have, which you can see and merge by hand; lower it and a distinct question ends up filed under an entry that does not answer it, and nobody notices. The two mistakes do not cost the same, so when in doubt, raise it.

= Why does the AI Overview panel not appear on my classic theme when only knowledge entries match? =

Because there is nothing for the results loop to render. Knowledge entries are private, so they are never put into the search results, and on a classic theme the panel is injected on `loop_start`, which WordPress does not fire when the loop is empty. Block themes are unaffected: the panel is injected around the query block, which renders either way.

If your site runs a classic theme and you want the panel on those searches too, place it explicitly with the `[creator_assistant_search_ai_overview]` shortcode or the AI Overview block in your search template, instead of relying on automatic insertion.

= What does the plugin write to my database? =

Two things:

1. **`ca_knowledge` posts** — entries you create in the Knowledge admin section, plus any drafts created automatically from visitor feedback. All are private and never visible on the frontend.
2. A **post meta entry** (`_creator_assistant_knowledge_reason`) on feedback-generated drafts, recording whether the draft was created because of a negative rating (`negative_feedback`) or an unanswered query (`no_answer`).
3. **Post meta entries** (`_creator_assistant_knowledge_queries`), one per search assigned to an entry, so the admin can see which wordings that entry has to cover.
4. A **post meta entry** (`_creator_assistant_knowledge_hits`) counting how many times an entry was asked for.
5. One **option** (`creator_assistant_knowledge_intent_threshold`), the similarity threshold from the settings page.

No existing post content, meta, status, or taxonomy data is ever modified.

= What happens if I deactivate or delete the plugin? =

**Deactivating** the plugin hides the Knowledge admin section and stops feedback processing; your knowledge entries are preserved in the database.

**Deleting** the plugin removes all knowledge entries and their post meta from your WordPress database, and drops the two Qdrant collections it owns (`creator_assistant_<id>_knowledge_chunk` and `creator_assistant_<id>_knowledge_intent`, where `<id>` is the random identifier Creator Assistant Hub gives each site so several sites can share one Qdrant cluster). Your regular posts, pages, all public content and the shared vector collections are completely unaffected.

= What happens to the deduplication data if I reset the Hub or change its embedding model? =

Creator Assistant - Hub's Reset button, and switching to a different embedding model, both invalidate every stored query vector: the whole point of the similarity comparison is that queries embedded with different models are not comparable. When either happens, this plugin drops its query-matching collection (`creator_assistant_knowledge_intent`) and rebuilds it in the background, in small batches, from the searches already assigned to your entries. Nothing you have written is lost: the entries, their assigned searches and their request counts all stay as they were, only the vectors used to recognise a reworded question are recomputed.

== Development ==

The plugin ships no compiled assets: `assets/js/feedback.js`, `assets/js/editor-panel.js` and `assets/css/feedback.css` are hand-written and need no build step. Only the PHP development tooling has to be installed to work on it.

`composer install` installs PHPCS with the WordPress and VIP standards, PHPStan and PHPUnit. Then:

* `npm run lint:php` runs PHPCS, `npm run fix:php` applies the automatic fixes.
* `npm run analyse:php` runs PHPStan, which also scans the Hub and Search sibling plugins because their classes are used throughout.
* `npm test` runs the unit tests. They use hand-written WordPress stubs and load neither WordPress, a database, nor the Hub.
* `npm run check` runs the WordPress.org Plugin Check CLI.

== Changelog ==

= 1.0.0 =
* Initial release.
* Private `ca_knowledge` post type, admin-only, excluded from all public queries.
* Automatic indexing via Creator Assistant Hub into a Qdrant collection the plugin owns, not the shared one.
* Feedback control on AI Overview panels, for reporting an answer that did not help, and the endpoint behind it.
* Automatic draft creation for negative feedback and unanswered queries, with semantic deduplication of similar queries and a configurable similarity threshold.
* Request counter per entry, shown as a sortable column, so the most asked gaps can be answered first.
* Feedback endpoint protected by a nonce.
* Knowledge entries listed as AI Overview sources only for users who can edit them.
* The Knowledge page comes last in the Creator Assistant menu, after Search and its Analytics (needs a Creator Assistant Hub version with the `creator_assistant_hub_menu_positions` filter).

== Upgrade Notice ==

= 1.0.0 =
Initial release. No upgrade steps required.
