From b96c2b1ae1a94da3e633e84e1a8987fbab74f3a0 Mon Sep 17 00:00:00 2001 From: Thomas Chopitea Date: Thu, 27 Aug 2026 17:21:16 +0000 Subject: [PATCH] Document what semantic_search results actually contain 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. --- pyproject.toml | 2 +- yeti/api.py | 17 +++++++++++++---- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index b7d2217..1d41585 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "yeti-python" -version = "2.2.0" +version = "2.2.1" description = "Python bindings for the Yeti API" authors = ["tomchop"] license = "Apache" diff --git a/yeti/api.py b/yeti/api.py index 79ad183..6b0a737 100644 --- a/yeti/api.py +++ b/yeti/api.py @@ -475,10 +475,19 @@ def semantic_search( Returns: The response from the API; a list of dicts, one per searched type, - each with a 'type' key, a 'results' key (a list of dicts representing - matched objects, each including a 'semantic_score' field where higher - is more similar), and a 'total' key (the number of results returned - for that type). + each with a 'type' key, a 'results' key, and a 'total' key (the + number of results returned for that type). + + Each result is a matched object with two search fields added: + 'semantic_score', a similarity between 0 and 1 where 1 is + near-identical and 0 unrelated, and 'matched_on', naming which of + the object's indexed documents matched -- 'self' for the object's + own name and description, or 'approach:N' for the Nth approach of a + DFIQ question. + + The API applies no relevance cut-off, since a useful threshold + depends on the corpus and the query. Filter on 'semantic_score' if + you need one. """ params: dict[str, Any] = {"query": query, "count": count} if root_type: