#529 docs(sdk): note that custom embeddings must be unit-normalized

Summary

The custom-embeddings sections of the Python and JavaScript SDK READMEs do not say that Moss does not normalize caller-provided vectors. Rankings only match cosine similarity when document and query embeddings are unit length.

The existing examples use OpenAI, which returns normalized vectors, so the requirement is invisible there. Local models often return un-normalized vectors and rank differently.

How I found it

Plugging a local static embedding model (a model2vec distillation of LaBSE, 256-d) into DocumentInfo(embedding=...) and QueryOptions(embedding=...) on moss 1.13.0. On a 20-query Nepali-to-English test set, raw vectors gave 14/20 top-1 inside Moss while local cosine gave 17/20. L2-normalizing the vectors before sending them made Moss return 17/20, identical to local cosine.

Demo and numbers: https://github.com/VeshRaazThapa/moss-nepali-demo

Changes

• sdks/python/sdk/README.md: short note after the custom-embeddings example
• sdks/javascript/sdk/README.md: same note

Docs only, no code changes.

Summary by CodeRabbit

• Documentation
  • Added guidance for custom embeddings in the JavaScript and Python SDK documentation.
  • Clarified that embeddings are not normalized automatically and should be L2-normalized for cosine-similarity rankings to align with expectations.
  • Noted that unnormalized embeddings still return results but may affect result ordering.