[VeshRaazThapa]

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.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 3f5bf350-8f3b-417b-96a7-b265185099f8

📥 Commits

Reviewing files that changed from the base of the PR and between 9a8afee and f7bee66.

📒 Files selected for processing (2)

• sdks/javascript/sdk/README.md
• sdks/python/sdk/README.md

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The JavaScript and Python SDK READMEs now document that Moss does not normalize caller-provided embeddings. They explain when cosine-similarity ranking matches and how unnormalized vectors can change result ordering.

Changes

Embedding documentation

Layer / File(s)	Summary
Normalization guidance sdks/javascript/sdk/README.md, sdks/python/sdk/README.md	Documents that caller-provided document and query vectors must be L2-normalized for cosine-similarity rankings to match. The JavaScript documentation also notes that hosted APIs may return normalized vectors while local models often do not.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~3 minutes

Change: Other

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation change about unit-normalizing custom embeddings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

✨ Simplify code

• Create a new PR

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Codex review

No issues found.

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}