[theaminulai]

What?

Closes #1037

Documents the architecture and developer-facing APIs for Embeddings support, scoped specifically to the embeddings foundation from #962 — not a general plugin architecture rewrite (see the note on #1042 below).

Why?

docs/experiments/embeddings.md already covered the storage/CRUD layer (Embedding_Repository, Embedding_Record) and the similarity/ranking utilities (Vector_Math, Vector_Ranker) in real depth, but said nothing about how a vector actually gets generated or how embedding providers and models connect through the PHP AI Client. A developer building semantic search or frontend chat on top of this foundation had no single place that covered the whole pipeline end to end.

How?

Expanded docs/experiments/embeddings.md (kept the existing storage/CRUD and comparison content, which was already accurate) with:

• Generating embeddings — generate_embeddings(), why a model is always required with no auto-selection fallback (vectors from different models are never comparable), the $args shape, and the EmbeddingBuilder it wraps.
• How providers and models connect — AiClient::defaultRegistry(), ai_provider connectors (wp_get_connectors() / get_ai_connectors()), and EmbeddingGenerationModelInterface as the contract a model implements to support embeddings.
• Lifecycle events — BeforeGenerateEmbeddingEvent/AfterGenerateEmbeddingEvent are PSR events dispatched by EmbeddingBuilder through an injected event dispatcher, not WordPress do_action() hooks — and generate_embeddings() does not wire one up, so they only fire for code that builds its own EmbeddingBuilder directly. Verified this by reading includes/helpers.php's generate_embeddings() and confirming no non-vendor code in the plugin constructs an EmbeddingBuilder with a dispatcher.
• Implementation note: the SDK overlay — includes/SDK_Overlay.php conditionally serves the embeddings classes from this plugin's vendored copy only when the environment's own PHP AI Client SDK doesn't already provide them, so includes/Vendor/AiClient/src/... isn't always what actually runs.
• Trying it from WP-CLI — a short pointer to the existing wp ai embeddings generate/compare commands as a way to exercise the whole pipeline without writing PHP (including the --dry-run default-true gotcha).

Retitled the doc from "Storing Embeddings" to "Embeddings: Architecture and Developer API" to match the new scope, updated its one inbound link in docs/DEVELOPER_GUIDE.md, and added a link from CONTRIBUTING.md, which had none.

Every class, method, and behavior described was checked directly against the current source — includes/helpers.php, includes/Embeddings/*, includes/CLI/Embeddings_Command.php, includes/SDK_Overlay.php, and the vendored EmbeddingBuilder/EmbeddingResult/event classes — not written from a general impression of the codebase.

Re: #1042

A previous attempt at this (#1042) was closed for being scoped too broadly — it rewrote the whole plugin's architecture overview rather than focusing on embeddings. This PR only touches embeddings-specific documentation and the two existing docs that link to it.

Testing Instructions

Documentation-only change; no code paths affected. Please review for accuracy, and check that the internal anchor links in docs/experiments/embeddings.md resolve, and that the updated links in docs/DEVELOPER_GUIDE.md and CONTRIBUTING.md point at the right file.

[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.

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

Co-authored-by: theaminulai <theaminuldev@git.wordpress.org>
Co-authored-by: dkotter <dkotter@git.wordpress.org>
Co-authored-by: jeffpaul <jeffpaul@git.wordpress.org>

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.60%. Comparing base (123ab42) to head (40e6813).
⚠️ Report is 41 commits behind head on develop.

Additional details and impacted files

@@              Coverage Diff              @@
##             develop    #1088      +/-   ##
=============================================
+ Coverage      80.23%   81.60%   +1.36%     
- Complexity      2998     3081      +83     
=============================================
  Files            124      129       +5     
  Lines          11978    12283     +305     
=============================================
+ Hits            9611    10023     +412     
+ Misses          2367     2260     -107     

Flag	Coverage Δ
unit	81.60% <ø> (+1.36%)	⬆️

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.

[jeffpaul]

@dkotter probably worth pulling into 1.4.0?

[dkotter]

I don't think we need to link to this from here

[dkotter]

Any particular reason this file has been modified so much? The underlying issue here was around documentation for embeddings, not general plugin architecture. I'd suggest we revert the changes here