Semantic (vector) search for the AI plugin — fixes, tests & validation atop #891

[ColinM-sys]

Summary

WordPress's AI plugin does not yet ship semantic / vector search — it exists only in in-progress PRs. This PR moves that capability toward a mergeable state.

Credit / authorship — this builds directly on others' work:

• Feat: Add semantic search experiment to AI plugin #891 (@priyanshuhaldar007) — the Semantic Search experiment (wp-admin search, Cmd-K palette, indexing). This branch contains that work.
• Add native vector search #683 (@artpi) — native MariaDB VECTOR index (the future high-performance backend).
• Bring over embeddings support from the PHP AI Client #892 — the AI Client embedding support this feature calls via generate_embeddings().

I'm not the author of the underlying feature; this PR adds fixes + tests + validation on top of #891 and reports a key upstream finding.

What THIS PR adds on top of #891

1. Fixes the PHPCS blocker (the only failing lint on Feat: Add semantic search experiment to AI plugin #891): replaces posts_per_page => -1 (VIP-prohibited, unbounded) in Vector_Search::search() with a bounded, filterable lookup.
2. Embedding_Store::get_indexed_ids( $post_types, $limit ) — scores only posts that actually have an embedding (efficiency + fixes the lint), bounded by the new wpai_semantic_search_max_candidates filter (default 2000). Uses SELECT DISTINCT to avoid duplicate candidates.
3. Tests: test_get_indexed_ids_returns_only_indexed_posts, test_get_indexed_ids_respects_limit.
4. Confirms Feat: Add semantic search experiment to AI plugin #891 already routes embeddings through the AI Client with no provider-specific code, which addresses the earlier CHANGES_REQUESTED review (now stale).

Validation

• wp-env (WP 7.0.4, MariaDB 12.3.2): plugin loads, no fatals, experiment registers.
• Live smoke tests pass (index / exclude-unindexed / limit / cosine).
• End-to-end semantic search verified through the real production path (Indexer → Embedding_Generator → AI Client → Google embedding provider → Vector_Search), using the Google embedding provider (PR ai-provider-for-google#30) with gemini-embedding-001 (3072-dim):
  • Query "how do I keep furniture from rocking on an uneven floor" → top result: "Leveling a wobbly cafe table" (0.773), zero shared keywords.
  • Query "iced caffeine drink recipe" → top result: "Cold brew coffee at home" (0.662).

Dependency: what else needs to merge for this to work end-to-end

This feature generates embeddings through the AI Client, so it needs an AI provider plugin that ships embedding execution. The client side is already in place (#892, merged), but no released provider does embeddings yet (Google 1.1.0 / OpenAI 1.0.3 / Ollama 1.1.1). That support is in the provider PRs below, and at least one of these must merge and be released for semantic search to work out of the box:

• Add embedding model support ai-provider-for-google#30 (verified working against this branch above)
• Add OpenAI embedding model support ai-provider-for-openai#34
• Add support for embeddings Fueled/ai-provider-for-ollama#69

Until one ships, the feature installs and loads but reports "no provider with embedding support configured." This is the same upstream dependency that has #891/#683 marked "blocked"; it lives in the provider layer, not this plugin.

This branch overlaps #891 (it includes that work because #891 isn't merged to develop yet). It's offered to help #891 land; happy to instead submit the delta directly onto #891's branch if maintainers prefer.

[codecov]

Codecov Report

❌ Patch coverage is 21.89474% with 371 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.95%. Comparing base (a0f5ea2) to head (9e69699).

Files with missing lines	Patch %	Lines
...ncludes/Experiments/Semantic_Search/Index_Page.php	0.00%	102 Missing ⚠️
...es/Experiments/Semantic_Search/REST_Controller.php	0.00%	100 Missing ⚠️
...riments/Semantic_Search/List_Table_Integration.php	0.00%	45 Missing ⚠️
...es/Experiments/Semantic_Search/Semantic_Search.php	35.48%	40 Missing ⚠️
...udes/Experiments/Semantic_Search/Vector_Search.php	31.37%	35 Missing ⚠️
includes/Experiments/Semantic_Search/Indexer.php	0.00%	27 Missing ⚠️
...xperiments/Semantic_Search/Embedding_Generator.php	39.28%	17 Missing ⚠️
includes/REST/Models_Controller.php	25.00%	3 Missing ⚠️
...es/Experiments/Semantic_Search/Embedding_Store.php	96.42%	2 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #943      +/-   ##
=============================================
- Coverage      76.01%   73.95%   -2.07%     
- Complexity      3032     3123      +91     
=============================================
  Files            132      140       +8     
  Lines          12001    12476     +475     
=============================================
+ Hits            9123     9227     +104     
- Misses          2878     3249     +371     

Flag	Coverage Δ
unit	73.95% <21.89%> (-2.07%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @priyanshuhaldar007, @ColinM-sys.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: priyanshuhaldar007, ColinM-sys.

Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>
Co-authored-by: dugyen <ugyensupport@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[jeffpaul]

@ColinM-sys please see the new tracking issue for embedding integration in the AI plugin (#962) and whether you might be interested in coordinating with @artpi and @priyanshuhaldar007 who've also worked on #683 and #891 respectively on the smaller, more reviewable PRs on the path toward implementing embedding support... thanks!

[dugyen]

Tested via WP Playground preview

Used the PR's own Playground preview link (CI artifact pr-943-9e69699e8c44599376120f95a20387c84a0fe367.zip, fresh install on WP 7.1).

Install & load

• Plugin installs/activates cleanly — no fatals.
• WP Playground's PHP error log after install + enabling the experiment: 0 errors, 0 warnings (only unrelated core "Info" notice from wp_maybe_inline_styles, present on any Playground WP 7.1 boot).

Feature registration

• Settings → AI → Admin Experiments lists "Semantic Search" with the description from this PR, and toggling it on triggers 3 admin-ajax.php calls, all 200 OK, no console errors.

Runtime behavior without an embedding provider

• As disclosed in the PR description, no released provider ships embedding support yet. With the experiment on and no connector configured, Posts search degrades gracefully to normal keyword search ("No posts found" for a semantic-only query) — no crash, no exception. Matches the documented "no provider with embedding support configured" behavior.
• Wasn't able to verify the actual vector-similarity ranking claims (the "wobbly table" / "cold brew" examples) since that needs the unreleased Google/OpenAI/Ollama provider branches this PR names as dependencies.

CI

• All PHP matrix jobs (7.4–8.4 × WP 7.0/latest/trunk), PHPCS, static analysis, JS checks, Plugin Check, E2E, build, dependency-review — pass.
• codecov/patch and codecov/project are failing (coverage threshold, not test failures) — likely Vector_Search/Embedding_Store isn't fully covered by the two new tests added here.

Net: the plugin-side code in this PR is clean and mergeable-safe on its own — installs without fatals/warnings and degrades gracefully with no provider configured. The real blocker for the feature actually working end-to-end is still the provider layer (#962), same as noted for #891/#683.

[ColinM-sys]

Thanks @jeffpaul — I'm in, and #962's approach makes sense. Happy to coordinate with @artpi and @priyanshuhaldar007.

From #943 I can carve out focused PRs against develop:

1. Storage/CRUD layer — Embedding_Store including the bounded get_indexed_ids() lookup (this replaces the unbounded posts_per_page => -1 query that was blocking Feat: Add semantic search experiment to AI plugin #891 on PHPCS), with its tests.
2. Similarity/calculation utilities — the candidate scoring path, bounded by the wpai_semantic_search_max_candidates filter (default 2000), with tests.
3. Semantic search (New Experiment: Semantic search in wp admin #844) on top once the foundation lands — the wp-admin integration from Feat: Add semantic search experiment to AI plugin #891, which I've validated end-to-end (via ai-provider-for-google#30, gemini-embedding-001).

On the testing note in #962: I run local models daily, so I can build the Ollama-based test workflow — validating embedding generation and similarity against a local model with zero provider API costs.

Thanks @dugyen for the independent Playground testing above — good confirmation that the plugin-side code is safe standalone and degrades gracefully without a provider, which should make the carved-out foundation PRs straightforward to review.

I'll watch php-ai-client#274 (per @dkotter's note on #962) and branch the foundation PRs to line up with it. Happy to take whichever piece is most useful first, or split differently if @artpi or @priyanshuhaldar007 are already picking things up. I'll keep #943 open as the working end-to-end reference until the pieces land, then close it.