Add joint/centroid embedding and concept-to-concept similarity queries

[nicoloesch]

Summary

Adds two composition methods to EmbeddingReaderInterface:

• get_joint_embedding(concept_ids, weights=None) (weighted-mean centroid, normalized for cosine space), and
• get_similar_concepts(concept_id, k, *, concept_filter=None) (single-call nearest-neighbor lookup, built on the former).

Both are pure compositions of existing get_embeddings_by_concept_ids/get_nearest_concepts. No backend or schema changes.

• Closes Add joint/centroid embedding query to EmbeddingReaderInterface #31
• Closes Add single-call concept-to-concept similarity query #32

[nicoloesch]

Lint PR is failing because it is not adhering to our current CI/CD. Related to #39 and the decisions there.

[gkennos]

also in docs/usage/interface-guide.md add docs for the two new functions

[nicoloesch]

Accepted and implemented all review comments. I addressed the obfuscation of k and limit using another data structure that mirrors what is already in omop_graph and tracked here: AustralianCancerDataNetwork/OMOP_Alchemy#11
Folr more information, look at the response to the comment.

[nicoloesch]

Update: reverted the EmbeddingConceptFilter/CDMConceptFilter type split from this PR (commits d39a723, c7cb1b9).

That split fixed the k/limit precedence issue correctly, but it's a breaking change to a released public type: EmbeddingConceptFilter.limit is used directly by omop-graph in 3 places, and removing it isn't worth a v2.0 bump on its own right now.

Replaced it with a backward-compatible fix instead: the underlying SQL-level bug (backends overriding k with concept_filter.limit) is still fixed, and EmbeddingReaderInterface now emits a DeprecationWarning whenever concept_filter.limit is used for KNN search, raising ValueError if it's given alongside a conflicting explicit k. EmbeddingConceptFilter itself is untouched. No downstream consumer needs to change anything for this release.

The real type split is tracked as a separate, future breaking-change issue: #48.

Label: breaking back to feature.

[gkennos]

still breaking - don't think there are active consumers, honestly, but since we are actively pursuing improved release hygiene, it seems worth retaining for now

[nicoloesch]

Decided to restore the function and add the DeprecationWarning so we can remove it in 2.0. It should now just be a feature.