deepsights-api 1.7.2__tar.gz → 1.7.4__tar.gz

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 <!--next-version-placeholder-->
 
+## v1.7.4 (09-Sep-2026)
+
+- Treat null `context`, `search_results`, and `items` in search responses as empty result sets instead of crashing when the backend is degraded (documentstore, userclient, and contentstore search functions).
+
+## v1.7.3 (02-Sep-2026)
+
+- Exclude the production OpenAPI specification from source distributions.
+
 ## v1.7.2 (12-May-2026)
 
 - Add optional content type filtering to topic search for userclient and documentstore clients.

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: deepsights-api
-Version: 1.7.2
+Version: 1.7.4
 Summary: Python library for the DeepSights APIs
 Project-URL: Documentation, https://marketlogicsoftware.github.io/deepsights-api/
 Project-URL: Repository, https://github.com/marketlogicsoftware/deepsights-api

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/deepsights/_version.py

@@ -2,4 +2,4 @@ __all__ = ["__version__"]
 
 # Single-source version for the package.
 # Update this value when releasing.
-__version__ = "1.7.2"
+__version__ = "1.7.4"

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/deepsights/contentstore/resources/_model.py

@@ -49,9 +49,9 @@ class ContentStoreSearchResult(DeepSightsIdTitleModel):
 
     Attributes:
 
-        description (str): The description of the item.
+        description (Optional[str], optional): The description of the item. Defaults to None.
         image_url (Optional[str], optional): The URL of the item's image. Defaults to None.
-        url (str): The URL of the item.
+        url (Optional[str], optional): The URL of the item. Defaults to None.
         language (Optional[str], optional): The language of the item. Defaults to None.
         publication_date (Optional[datetime], optional): The publication_date of the item's publication. Defaults to None.
         source (Optional[str], optional): The source of the item. Defaults to None.
@@ -59,9 +59,9 @@ class ContentStoreSearchResult(DeepSightsIdTitleModel):
         rank (Optional[int], optional): The final rank of the item in the search results. Defaults to None.
     """
 
-    description: str = Field(description="The description of the item.")
+    description: Optional[str] = Field(description="The description of the item; may be None.", default=None)
     image_url: Optional[str] = Field(description="The URL of the item's thumbnail image.", default=None)
-    url: str = Field(description="The URL of the item.")
+    url: Optional[str] = Field(description="The URL of the item; may be None.", default=None)
     language: Optional[str] = Field(description="The language of the item; may be None.", default=None)
     publication_date: Optional[datetime] = Field(
         alias="published_at",

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/deepsights/contentstore/resources/_search.py

@@ -158,7 +158,8 @@ def contentstore_hybrid_search(
     response = api.post("item-service/items/_hybrid-search", body=body)
 
     # parse
-    results: List[T] = [search_result(i) for i in response["items"]]
+    # a degraded backend may return HTTP 200 with "items": null; treat as empty
+    results: List[T] = [search_result(i) for i in response.get("items") or []]
 
     # record rank
     for rank, result in enumerate(results):
@@ -223,7 +224,8 @@ def contentstore_vector_search(
     response = api.post("item-service/items/_vector-search", body=body)
 
     # parse
-    results: List[T] = [search_result(i) for i in response["items"]]
+    # a degraded backend may return HTTP 200 with "items": null; treat as empty
+    results: List[T] = [search_result(i) for i in response.get("items") or []]
 
     # re-rank
     return rerank_by_recency(results, recency_weight=recency_weight)
@@ -291,7 +293,8 @@ def contentstore_text_search(
     response = api.post("item-service/items/_text-search", body=body)
 
     # parse
-    results: List[T] = [search_result(i) for i in response["items"]]
+    # a degraded backend may return HTTP 200 with "items": null; treat as empty
+    results: List[T] = [search_result(i) for i in response.get("items") or []]
 
     # record rank
     for rank, result in enumerate(results):

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/deepsights/documentstore/resources/documents/_search.py

@@ -253,8 +253,9 @@ def hybrid_search(
 
     response = resource.api.post("supercharged-search-service/hybrid-searches", body=body)
 
-    # Extract the search results from the response
-    search_results = response.get("context", {}).get("search_results", [])
+    # Extract the search results from the response; a degraded backend may return
+    # HTTP 200 with "context": null or "search_results": null, treat both as empty
+    search_results = (response.get("context") or {}).get("search_results") or []
     return [HybridSearchResult(**result) for result in search_results]
 
 
@@ -303,6 +304,7 @@ def topic_search(
 
     response = resource.api.post("supercharged-search-service/topic-searches", body=body)
 
-    # Extract the search results from the response
-    search_results = response.get("context", {}).get("search_results", [])
-    return [TopicSearchResult(**result) for result in search_results if len(result) > 0]
+    # Extract the search results from the response; a degraded backend may return
+    # HTTP 200 with "context": null or "search_results": null, treat both as empty
+    search_results = (response.get("context") or {}).get("search_results") or []
+    return [TopicSearchResult(**result) for result in search_results if result]

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/deepsights/userclient/resources/documents/documents.py

@@ -91,9 +91,10 @@ def topic_search(
 
     response = resource.api.post("end-user-gateway-service/topic-searches", body=body)
 
-    # Extract the search results from the response
-    search_results = response.get("context", {}).get("search_results", [])
-    return [TopicSearchResult(**result) for result in search_results if len(result) > 0]
+    # Extract the search results from the response; a degraded backend may return
+    # HTTP 200 with "context": null or "search_results": null, treat both as empty
+    search_results = (response.get("context") or {}).get("search_results") or []
+    return [TopicSearchResult(**result) for result in search_results if result]
 
 
 #################################################
@@ -125,8 +126,9 @@ def hybrid_search(resource: APIResource, query: str, extended_search: bool = Fal
     # Temporarily allow 5xx responses to debug the error
     response = resource.api.post("end-user-gateway-service/hybrid-searches", body=body)
 
-    # Extract the search results from the response
-    search_results = response.get("context", {}).get("search_results", [])
+    # Extract the search results from the response; a degraded backend may return
+    # HTTP 200 with "context": null or "search_results": null, treat both as empty
+    search_results = (response.get("context") or {}).get("search_results") or []
     return [HybridSearchResult(**result) for result in search_results]
 
 

{deepsights_api-1.7.2 → deepsights_api-1.7.4}/pyproject.toml

@@ -65,6 +65,9 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["deepsights"]
 
+[tool.hatch.build.targets.sdist]
+exclude = ["/ds-b2b-client-product-prod.yaml"]
+
 [tool.hatch.metadata]
 allow-direct-references = true
 

deepsights_api-1.7.4/tests/deepsights/contentstore/test_contentstore_search_null_tolerance_unit.py

@@ -0,0 +1,84 @@
+"""
+Unit tests for null-tolerant parsing of Content Store search responses (no network).
+
+A degraded backend may return HTTP 200 with "items": null (or no "items" key);
+this must be treated as an empty result set.
+"""
+
+from typing import Any, cast
+
+import pytest
+
+from deepsights.contentstore.resources._model import ContentStoreSearchResult
+from deepsights.contentstore.resources._search import (
+    contentstore_hybrid_search,
+    contentstore_text_search,
+    contentstore_vector_search,
+)
+
+
+class _DummyAPI:
+    def __init__(self, response):
+        self._response = response
+
+    def post(self, path, params=None, body=None, timeout=None, expected_statuscodes=None):
+        return self._response
+
+
+_ITEM = {
+    "id": "item-1",
+    "title": "Title",
+    "description": "Description",
+    "url": "https://example.com",
+    "language": "en",
+    "publication_date": "2024-01-02T03:04:05Z",
+    "source": "Source",
+    "source_id": "src-1",
+}
+
+_NULL_RESPONSES = [{"items": None}, {}]
+_NULL_IDS = ["items-null", "no-items-key"]
+
+
+def _search_result(i: Any) -> ContentStoreSearchResult:
+    return ContentStoreSearchResult(**i)
+
+
+@pytest.mark.parametrize("response", _NULL_RESPONSES, ids=_NULL_IDS)
+def test_hybrid_search_null_response_returns_empty(response):
+    api = cast(Any, _DummyAPI(response))
+    assert contentstore_hybrid_search(api, "query", item_type="NEWS", search_result=_search_result) == []
+
+
+@pytest.mark.parametrize("response", _NULL_RESPONSES, ids=_NULL_IDS)
+def test_text_search_null_response_returns_empty(response):
+    api = cast(Any, _DummyAPI(response))
+    assert contentstore_text_search(api, "query", item_type="NEWS", search_result=_search_result) == []
+
+
+@pytest.mark.parametrize("response", _NULL_RESPONSES, ids=_NULL_IDS)
+def test_vector_search_null_response_returns_empty(response):
+    api = cast(Any, _DummyAPI(response))
+    assert contentstore_vector_search(api, [0.0] * 1536, item_type="NEWS", search_result=_search_result) == []
+
+
+def test_hybrid_search_parses_non_empty_payload_and_records_rank():
+    api = cast(Any, _DummyAPI({"items": [_ITEM, {**_ITEM, "id": "item-2"}]}))
+    results = contentstore_hybrid_search(api, "query", item_type="NEWS", search_result=_search_result)
+    assert [r.id for r in results] == ["item-1", "item-2"]
+    assert [r.rank for r in results] == [1, 2]
+
+
+def test_text_search_parses_non_empty_payload_and_records_rank():
+    api = cast(Any, _DummyAPI({"items": [_ITEM]}))
+    results = contentstore_text_search(api, "query", item_type="NEWS", search_result=_search_result)
+    assert len(results) == 1
+    assert results[0].id == "item-1"
+    assert results[0].rank == 1
+
+
+def test_vector_search_parses_non_empty_payload():
+    api = cast(Any, _DummyAPI({"items": [_ITEM]}))
+    results = contentstore_vector_search(api, [0.0] * 1536, item_type="NEWS", search_result=_search_result)
+    assert len(results) == 1
+    assert results[0].id == "item-1"

deepsights_api-1.7.4/tests/deepsights/documentstore/test_documentstore_search_null_tolerance_unit.py

@@ -0,0 +1,98 @@
+"""
+Unit tests for null-tolerant parsing of documentstore search responses (no network).
+
+A degraded backend may return HTTP 200 with "context": null or
+"search_results": null; both must be treated as an empty result set.
+"""
+
+import pytest
+
+from deepsights.api.resource import APIResource
+from deepsights.documentstore.resources.documents._search import hybrid_search, topic_search
+
+
+class _DummyAPI:
+    def __init__(self, response):
+        self._response = response
+
+    def post(self, path, params=None, body=None, timeout=None, expected_statuscodes=None):
+        return self._response
+
+
+_ARTIFACT = {
+    "artifact_id": "art-1",
+    "artifact_title": "Title",
+    "artifact_summary": "Summary",
+    "artifact_source": "Source",
+    "artifact_content_type": "standalone_document",
+    "artifact_publication_date": "2024-01-02T03:04:05Z",
+}
+
+_HYBRID_RESULT = {
+    **_ARTIFACT,
+    "page_references": [{"id": "page-1", "external_id": None, "number": 1, "title": "P1", "text": "Text"}],
+}
+
+_TOPIC_RESULT = {
+    **_ARTIFACT,
+    "page_references": [
+        {
+            "id": "page-1",
+            "external_id": None,
+            "number": 1,
+            "title": "P1",
+            "text": "Text",
+            "relevance_class": "HIGH",
+            "relevance_assessment": "Good match",
+        }
+    ],
+    "relevance_class": "HIGH",
+    "relevance_assessment": "Good match",
+}
+
+
+@pytest.mark.parametrize(
+    "response",
+    [
+        {"context": None},
+        {"context": {"search_results": None}},
+        {"context": {}},
+        {},
+    ],
+    ids=["context-null", "search-results-null", "context-empty", "no-context-key"],
+)
+def test_hybrid_search_null_response_returns_empty(response):
+    resource = APIResource(api=_DummyAPI(response))
+    assert hybrid_search(resource, "query") == []
+
+
+@pytest.mark.parametrize(
+    "response",
+    [
+        {"context": None},
+        {"context": {"search_results": None}},
+        {"context": {}},
+        {},
+    ],
+    ids=["context-null", "search-results-null", "context-empty", "no-context-key"],
+)
+def test_topic_search_null_response_returns_empty(response):
+    resource = APIResource(api=_DummyAPI(response))
+    assert topic_search(resource, "query") == []
+
+
+def test_hybrid_search_parses_non_empty_payload():
+    resource = APIResource(api=_DummyAPI({"context": {"search_results": [_HYBRID_RESULT]}}))
+    results = hybrid_search(resource, "query")
+    assert len(results) == 1
+    assert results[0].artifact_id == "art-1"
+    assert results[0].page_references[0].id == "page-1"
+
+
+def test_topic_search_parses_non_empty_payload_and_skips_empty_entries():
+    resource = APIResource(api=_DummyAPI({"context": {"search_results": [_TOPIC_RESULT, {}, None]}}))
+    results = topic_search(resource, "query")
+    assert len(results) == 1
+    assert results[0].artifact_id == "art-1"
+    assert results[0].relevance_class == "HIGH"
+    assert results[0].page_references[0].relevance_class == "HIGH"

deepsights_api-1.7.4/tests/deepsights/userclient/documents/test_userclient_search_null_tolerance_unit.py

@@ -0,0 +1,87 @@
+"""
+Unit tests for null-tolerant parsing of userclient search responses (no network).
+
+A degraded backend may return HTTP 200 with "context": null or
+"search_results": null; both must be treated as an empty result set.
+"""
+
+import pytest
+
+from deepsights.api.resource import APIResource
+from deepsights.userclient.resources.documents.documents import hybrid_search, topic_search
+
+
+class _DummyAPI:
+    def __init__(self, response):
+        self._response = response
+
+    def post(self, path, params=None, body=None, timeout=None, expected_statuscodes=None):
+        return self._response
+
+
+_ARTIFACT = {
+    "artifact_id": "art-1",
+    "artifact_title": "Title",
+    "artifact_summary": "Summary",
+    "artifact_source": "Source",
+    "artifact_content_type": "standalone_document",
+    "artifact_publication_date": "2024-01-02T03:04:05Z",
+}
+
+_HYBRID_RESULT = {
+    **_ARTIFACT,
+    "page_references": [{"id": "page-1", "external_id": None, "number": 1, "title": "P1", "text": "Text"}],
+}
+
+_TOPIC_RESULT = {
+    **_ARTIFACT,
+    "page_references": [
+        {
+            "id": "page-1",
+            "external_id": None,
+            "number": 1,
+            "title": "P1",
+            "text": "Text",
+            "relevance_class": "HIGH",
+            "relevance_assessment": "Good match",
+        }
+    ],
+    "relevance_class": "HIGH",
+    "relevance_assessment": "Good match",
+}
+
+_NULL_RESPONSES = [
+    {"context": None},
+    {"context": {"search_results": None}},
+    {"context": {}},
+    {},
+]
+_NULL_IDS = ["context-null", "search-results-null", "context-empty", "no-context-key"]
+
+
+@pytest.mark.parametrize("response", _NULL_RESPONSES, ids=_NULL_IDS)
+def test_hybrid_search_null_response_returns_empty(response):
+    resource = APIResource(api=_DummyAPI(response))
+    assert hybrid_search(resource, "query") == []
+
+
+@pytest.mark.parametrize("response", _NULL_RESPONSES, ids=_NULL_IDS)
+def test_topic_search_null_response_returns_empty(response):
+    resource = APIResource(api=_DummyAPI(response))
+    assert topic_search(resource, "query") == []
+
+
+def test_hybrid_search_parses_non_empty_payload():
+    resource = APIResource(api=_DummyAPI({"context": {"search_results": [_HYBRID_RESULT]}}))
+    results = hybrid_search(resource, "query")
+    assert len(results) == 1
+    assert results[0].artifact_id == "art-1"
+    assert results[0].page_references[0].id == "page-1"
+
+
+def test_topic_search_parses_non_empty_payload_and_skips_empty_entries():
+    resource = APIResource(api=_DummyAPI({"context": {"search_results": [_TOPIC_RESULT, {}, None]}}))
+    results = topic_search(resource, "query")
+    assert len(results) == 1
+    assert results[0].artifact_id == "art-1"
+    assert results[0].relevance_class == "HIGH"