Skip to content

Document what semantic_search results actually contain - #21

Merged
tomchop merged 1 commit into
mainfrom
document-semantic-search-response
Aug 28, 2026
Merged

Document what semantic_search results actually contain#21
tomchop merged 1 commit into
mainfrom
document-semantic-search-response

Conversation

@tomchop

@tomchop tomchop commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

Docs + version bump only; no behaviour change.

Since 2.2.0 the /search/semantic endpoint changed twice (yeti-platform/yeti#1353 and #1354):

  • semantic_score is 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.
  • Results gained matched_on, naming which of an object's indexed documents matched — self, or approach:N for a DFIQ question's Nth approach, now that questions are indexed as several documents.

Both already reach callers, since semantic_search() returns the API's sections verbatim. 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_score themselves — 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
  • No code changed outside the docstring and the version string

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.
@tomchop
tomchop merged commit c1b0be3 into main Aug 28, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant