Document what semantic_search results actually contain - #21
Merged
Conversation
The response gained a matched_on field, and semantic_score is now a bounded 0-1 similarity rather than an unbounded value. Both arrive through this client untouched, since it returns the API's sections verbatim, but neither was described here. The range matters because the endpoint applies no relevance cut-off by design: callers are expected to filter on the score themselves, which they cannot do safely without knowing what it ranges over.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs + version bump only; no behaviour change.
Since 2.2.0 the
/search/semanticendpoint changed twice (yeti-platform/yeti#1353 and #1354):semantic_scoreis now a bounded 0-1 similarity. It was previously derived on the assumption of a cosine distance when the index actually uses squared L2, which produced negative scores for genuinely good matches.matched_on, naming which of an object's indexed documents matched —self, orapproach:Nfor a DFIQ question's Nth approach, now that questions are indexed as several documents.Both already reach callers, since
semantic_search()returns the API'ssectionsverbatim. The client just never described them.The range is the part worth documenting: the endpoint deliberately applies no relevance cut-off, because a sensible threshold depends on the corpus and query. Callers are expected to filter on
semantic_scorethemselves — which they can't do safely without knowing what it ranges over. A caller who assumed 0-1 under the old scheme would have discarded most of their real results.Verified against a live 2.8.0 instance: a DFIQ query returns
semantic_score: 0.7714,matched_on: "self".Bumped to 2.2.1 so the corrected documentation reaches PyPI users.
Test plan
python -m unittest tests/api.py— 31 tests pass