GH-3540: Allow user-provided embeddings in VectorStore

[aniketg-21]

🚀 Motivation

Current VectorStore implementations (e.g., ChromaVectorStore) automatically generate embeddings from Document.content using the configured EmbeddingModel. However, more advanced use cases require greater flexibility:

1. Precomputed embeddings: Embeddings may be generated externally, such as via batch pipelines or fine-tuned models.
2. Embedding semantic intent: In some cases, embeddings should reflect a prompt, summary, or intent—not the raw content.
3. Structured data: When storing structured formats (e.g., JSON), embedding the full raw structure often reduces semantic quality.

🔧 Enhancement

This PR introduces support for user-supplied embeddings, allowing applications to decouple document storage from semantic representation. This separation enables more accurate and intentional embedding strategies for search and retrieval.

• If no embedding is provided, the default behavior—auto-generating embeddings from content—is preserved.
• This change improves semantic search relevance without compromising the integrity or structure of stored documents.

✅ Backward Compatibility

Fully maintained. The default pipeline continues to auto-generate embeddings when none are explicitly provided.

🧪 Testing & Limitations

This feature has been tested with SimpleVectorStore. Other implementations (e.g., Pinecone, Milvus) were not tested due to environment constraints and may require further validation or adapter adjustments.

✅ Issue Closed

Closes #3540

[markpollack]

had a brief look, thanks for the PR. design wise

void add(List<Document> documents, List<float[]> embeddings);

should instead be a pair object, so that there is no ambiguity of which document has which embedding vs. two separate args

[aniketg-21]

@markpollack thanks for your suggestion. @sobychacko its ready to be reviewed.

[sobychacko]

@aniketg-21 Apologies for not getting back to this PR sooner — it wasn't in the roadmap for previous releases, but we're finally at a point where we're pulling the general themes you describe into a feature item for 2.1.x.

Thanks for putting this together, and for iterating on Mark's feedback — really appreciate the effort here.

The underlying need (bringing your own precomputed embeddings) is something we definitely want, and I've actually got a version of this in progress on our end as part of a broader set of vector store additions — so I'd like to bring this in through that. The tradeoff I'm weighing is backward compatibility: changing the doAdd signature and adding a non-default method to the VectorStore interface ends up breaking custom stores that extend AbstractObservationVectorStore, so I'm going with a purely additive path — a new upsert(List<EmbeddedDocument>) default method that stores opt into, leaving add/doAdd untouched.

Your direction carries straight over, though: the EmbeddedDocument pair object is exactly what Mark was pointing at, and the embedding validation you added (dimension consistency, NaN/Inf checks) is something I want to keep. I'm going with upsert (replace-by-id) rather than a plain add since it's retry-safe and a bit more useful as a primitive.

Since it's already in progress on our side, please hold off on any further changes here — I don't want you spending cycles on work that'd end up superseded. I'll keep this open and link back once it's up so the lineage is clear and you get credit. Thanks again — the proposal and discussion here genuinely helped shape it. 🙏

[aniketg-21]

Thanks for the update and detailed context!

The additive upsert(List<EmbeddedDocument>) approach makes total sense—maintaining backward compatibility. I'm glad the discussion, validation checks, and general structure were useful in shaping the feature for 2.1.x.

I'll hold off on further changes here as requested.
Thanks again, and I look forward to seeing it land in 2.1.x! 🚀

[sobychacko]

As discussed above we are closing this PR. The new PR based on the new design is here: #7002

Thanks @aniketg-21 for the initial inspiration for these changes.