deepsights-api 1.3.2__tar.gz → 1.3.4__tar.gz

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 <!--next-version-placeholder-->
 
+## v1.3.4 (11-Jul-2025)
+
+- Extended hybrid search query length limitation to 512 chars
+
+## v1.3.3 (26-Jun-2025)
+
+- Auto-refresh token for userclient
+- Streamlined rate limiting and error handling
+ 
+
 ## v1.3.2 (18-Jun-2025)
 
 - Improved error logging for answer polling

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepsights-api
-Version: 1.3.2
+Version: 1.3.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
@@ -202,14 +202,48 @@ for item in content.results:
     print(f"{item.title} - {item.source}")
 ```
 
-#### Error Handling
+#### Error Handling & Rate Limiting
 ```python
+import time
+import deepsights
+
+ds = deepsights.DeepSights()
+uc = ds.get_userclient("analyst@company.com")
+
+try:
+    # Ask multiple questions - will demonstrate rate limiting
+    for i in range(15):  # Exceeds 10/minute limit for answers
+        response = uc.answersV2.create(f"Question {i}: Market trends?")
+        print(f"✅ Question {i+1} processed")
+        
+except deepsights.RateLimitError as e:
+    print(f"🚫 Rate limit exceeded: {e}")
+    
+    if e.retry_after:
+        print(f"⏱️  Client-side limit - wait {e.retry_after} seconds")
+        time.sleep(e.retry_after)
+    else:
+        print("⏱️  Server busy - try again later")
+        
+except deepsights.AuthenticationError as e:
+    print(f"🔐 Authentication failed: {e}")
+    
+except deepsights.DeepSightsError as e:
+    print(f"⚠️  API error: {e}")
+
+# Alternative: Handle all rate limiting uniformly
 try:
     response = uc.answersV2.create_and_wait("Your question here")
-except deepsights.exceptions.AuthenticationError:
-    print("Invalid API key or permissions")
-except deepsights.exceptions.RateLimitError:
-    print("Rate limit exceeded - please wait")
+    
+except deepsights.RateLimitError as e:
+    # Handles both client-side (10/min) and server-side (persistent 429) limits
+    print(f"Rate limit hit: {e}")
+    
+    # Implement your retry strategy
+    if e.retry_after:
+        time.sleep(e.retry_after)  # Known wait time
+    else:
+        time.sleep(60)  # Conservative fallback for server limits
 ```
 
 All return values are [Pydantic objects](https://docs.pydantic.dev/latest/) with `.schema_human()` for exploring available properties. See [main.py](https://github.com/marketlogicsoftware/deepsights-api/blob/main/main.py) for more examples.
@@ -217,10 +251,43 @@ All return values are [Pydantic objects](https://docs.pydantic.dev/latest/) with
 
 ## Developer Information
 
-### Rate Limits
-- **GET requests**: 1,000 per 60 seconds
-- **POST requests**: 100 per 60 seconds
-- Automatic exponential backoff retry logic included
+### Rate Limits & Error Handling
+
+The DeepSights API implements **comprehensive rate limiting** to ensure fair usage and optimal performance:
+
+#### Client-Side Rate Limits
+- **AI Answers**: 10 requests per 60 seconds (`uc.answersV2.create()`)
+- **AI Reports**: 3 requests per 60 seconds (`uc.reports.create()`)
+- **General GET requests**: 1,000 per 60 seconds
+- **General POST requests**: 100 per 60 seconds
+
+#### Behavior
+- **Client-side limits**: Immediate `RateLimitError` with `retry_after` information
+- **Server-side limits**: Automatic retry with exponential backoff (up to 3 attempts)
+- **Persistent server limits**: Convert to `RateLimitError` after retries for consistent handling
+
+#### Exception Hierarchy
+```python
+deepsights.DeepSightsError          # Base exception
+├── deepsights.RateLimitError       # Rate limiting (client + server)
+└── deepsights.AuthenticationError  # Invalid API keys/permissions
+```
+
+#### Best Practices
+```python
+# Recommended error handling pattern
+try:
+    response = uc.answersV2.create_and_wait("Your question")
+    
+except deepsights.RateLimitError as e:
+    # Single handler for all rate limiting scenarios
+    wait_time = e.retry_after or 60  # Use provided time or conservative fallback
+    print(f"Rate limited, waiting {wait_time} seconds...")
+    time.sleep(wait_time)
+    
+except deepsights.AuthenticationError:
+    print("Check your API keys and permissions")
+```
 
 ### Caching
 - User client responses cached for 240 seconds (TTL)

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/README.md

@@ -172,14 +172,48 @@ for item in content.results:
     print(f"{item.title} - {item.source}")
 ```
 
-#### Error Handling
+#### Error Handling & Rate Limiting
 ```python
+import time
+import deepsights
+
+ds = deepsights.DeepSights()
+uc = ds.get_userclient("analyst@company.com")
+
+try:
+    # Ask multiple questions - will demonstrate rate limiting
+    for i in range(15):  # Exceeds 10/minute limit for answers
+        response = uc.answersV2.create(f"Question {i}: Market trends?")
+        print(f"✅ Question {i+1} processed")
+        
+except deepsights.RateLimitError as e:
+    print(f"🚫 Rate limit exceeded: {e}")
+    
+    if e.retry_after:
+        print(f"⏱️  Client-side limit - wait {e.retry_after} seconds")
+        time.sleep(e.retry_after)
+    else:
+        print("⏱️  Server busy - try again later")
+        
+except deepsights.AuthenticationError as e:
+    print(f"🔐 Authentication failed: {e}")
+    
+except deepsights.DeepSightsError as e:
+    print(f"⚠️  API error: {e}")
+
+# Alternative: Handle all rate limiting uniformly
 try:
     response = uc.answersV2.create_and_wait("Your question here")
-except deepsights.exceptions.AuthenticationError:
-    print("Invalid API key or permissions")
-except deepsights.exceptions.RateLimitError:
-    print("Rate limit exceeded - please wait")
+    
+except deepsights.RateLimitError as e:
+    # Handles both client-side (10/min) and server-side (persistent 429) limits
+    print(f"Rate limit hit: {e}")
+    
+    # Implement your retry strategy
+    if e.retry_after:
+        time.sleep(e.retry_after)  # Known wait time
+    else:
+        time.sleep(60)  # Conservative fallback for server limits
 ```
 
 All return values are [Pydantic objects](https://docs.pydantic.dev/latest/) with `.schema_human()` for exploring available properties. See [main.py](https://github.com/marketlogicsoftware/deepsights-api/blob/main/main.py) for more examples.
@@ -187,10 +221,43 @@ All return values are [Pydantic objects](https://docs.pydantic.dev/latest/) with
 
 ## Developer Information
 
-### Rate Limits
-- **GET requests**: 1,000 per 60 seconds
-- **POST requests**: 100 per 60 seconds
-- Automatic exponential backoff retry logic included
+### Rate Limits & Error Handling
+
+The DeepSights API implements **comprehensive rate limiting** to ensure fair usage and optimal performance:
+
+#### Client-Side Rate Limits
+- **AI Answers**: 10 requests per 60 seconds (`uc.answersV2.create()`)
+- **AI Reports**: 3 requests per 60 seconds (`uc.reports.create()`)
+- **General GET requests**: 1,000 per 60 seconds
+- **General POST requests**: 100 per 60 seconds
+
+#### Behavior
+- **Client-side limits**: Immediate `RateLimitError` with `retry_after` information
+- **Server-side limits**: Automatic retry with exponential backoff (up to 3 attempts)
+- **Persistent server limits**: Convert to `RateLimitError` after retries for consistent handling
+
+#### Exception Hierarchy
+```python
+deepsights.DeepSightsError          # Base exception
+├── deepsights.RateLimitError       # Rate limiting (client + server)
+└── deepsights.AuthenticationError  # Invalid API keys/permissions
+```
+
+#### Best Practices
+```python
+# Recommended error handling pattern
+try:
+    response = uc.answersV2.create_and_wait("Your question")
+    
+except deepsights.RateLimitError as e:
+    # Single handler for all rate limiting scenarios
+    wait_time = e.retry_after or 60  # Use provided time or conservative fallback
+    print(f"Rate limited, waiting {wait_time} seconds...")
+    time.sleep(wait_time)
+    
+except deepsights.AuthenticationError:
+    print("Check your API keys and permissions")
+```
 
 ### Caching
 - User client responses cached for 240 seconds (TTL)

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/__init__.py

@@ -16,7 +16,17 @@
 This module contains the client library to interact with the Market Logic DeepSights and ContentStore APIs.
 """
 
+from deepsights import exceptions
 from deepsights.deepsights import DeepSights
 from deepsights.documentstore.resources import SortingField, SortingOrder
+from deepsights.exceptions import AuthenticationError, DeepSightsError, RateLimitError
 
-__all__ = ["SortingField", "SortingOrder", "DeepSights"]
+__all__ = [
+    "SortingField",
+    "SortingOrder",
+    "DeepSights",
+    "exceptions",
+    "AuthenticationError",
+    "DeepSightsError",
+    "RateLimitError",
+]

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/api/api.py

@@ -29,6 +29,8 @@ from tenacity import (
     wait_random_exponential,
 )
 
+from deepsights.exceptions import AuthenticationError, RateLimitError
+
 
 def _should_retry_http_error(exception: Exception) -> bool:
     """
@@ -53,6 +55,50 @@ def _should_retry_http_error(exception: Exception) -> bool:
     return isinstance(exception, (ConnectionError, Timeout))
 
 
+def _handle_http_error(response):
+    """
+    Handles HTTP errors and raises appropriate custom exceptions.
+
+    Args:
+        response: The HTTP response object
+
+    Raises:
+        AuthenticationError: If status code is 401 (Unauthorized)
+        HTTPError: For other HTTP errors
+    """
+    if response.status_code == 401:
+        raise AuthenticationError("Invalid API key or insufficient permissions")
+    elif response.status_code in [429, 502, 503]:
+        raise HTTPError(f"Retriable error {response.status_code}", response=response)
+    else:
+        response.raise_for_status()
+
+
+def _handle_persistent_rate_limit(func):
+    """
+    Decorator to catch persistent 429 errors after retries and convert them to RateLimitError.
+
+    This ensures consistent exception handling for both client-side and server-side rate limiting.
+    """
+
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except HTTPError as e:
+            if (
+                hasattr(e, "response")
+                and e.response is not None
+                and e.response.status_code == 429
+            ):
+                raise RateLimitError(
+                    "Server rate limit exceeded after retries. Please wait before making another request.",
+                    retry_after=None,  # Server didn't provide retry-after info
+                ) from e
+            raise
+
+    return wrapper
+
+
 #################################################
 class API:
     """
@@ -98,7 +144,7 @@ class API:
 
         # set keep-alive headers
         self._session.headers.update(
-            {"Connection": "keep-alive", "User-Agent": "deepsights-api/1.3.2"}
+            {"Connection": "keep-alive", "User-Agent": "deepsights-api/1.3.4"}
         )
 
         # store default timeout
@@ -120,6 +166,7 @@ class API:
         return self._endpoint_base + path.strip("/")
 
     #######################################
+    @_handle_persistent_rate_limit
     @retry(
         stop=stop_after_attempt(3),
         wait=wait_random_exponential(max=5),
@@ -143,6 +190,8 @@ class API:
             The JSON body of the server's response to the request.
 
         Raises:
+            AuthenticationError: If the request fails with a 401 status code.
+            RateLimitError: If the request fails with persistent 429 status code after retries.
             HTTPError: If the GET request fails with a non-200 status code and not in the expected_statuscodes list.
         """
         timeout = timeout or self._default_timeout
@@ -154,15 +203,12 @@ class API:
             response.status_code not in [200, 201, 202]
             and response.status_code not in expected_statuscodes
         ):
-            if response.status_code in [429, 502, 503]:
-                raise HTTPError(
-                    f"Retriable error {response.status_code}", response=response
-                )
-            response.raise_for_status()
+            _handle_http_error(response)
 
         return response.json()
 
     #######################################
+    @_handle_persistent_rate_limit
     @retry(
         stop=stop_after_attempt(3),
         wait=wait_random_exponential(max=5),
@@ -189,6 +235,8 @@ class API:
             bytes: The raw content of the server's response.
 
         Raises:
+            AuthenticationError: If the request fails with a 401 status code.
+            RateLimitError: If the request fails with persistent 429 status code after retries.
             HTTPError: If the GET request fails with a non-200 status code and not in the expected_statuscodes list.
         """
         timeout = timeout or self._default_timeout
@@ -200,15 +248,12 @@ class API:
             response.status_code not in [200, 201, 202]
             and response.status_code not in expected_statuscodes
         ):
-            if response.status_code in [429, 502, 503]:
-                raise HTTPError(
-                    f"Retriable error {response.status_code}", response=response
-                )
-            response.raise_for_status()
+            _handle_http_error(response)
 
         return response.content
 
     #######################################
+    @_handle_persistent_rate_limit
     @retry(
         stop=stop_after_attempt(3),
         wait=wait_random_exponential(max=5),
@@ -236,6 +281,11 @@ class API:
 
         Returns:
             Dict: The JSON body of the server's response to the request.
+
+        Raises:
+            AuthenticationError: If the request fails with a 401 status code.
+            RateLimitError: If the request fails with persistent 429 status code after retries.
+            HTTPError: For other HTTP errors.
         """
         timeout = timeout or self._default_timeout
         response = self._session.post(
@@ -246,15 +296,12 @@ class API:
             response.status_code not in [200, 201, 202]
             and response.status_code not in expected_statuscodes
         ):
-            if response.status_code in [429, 502, 503]:
-                raise HTTPError(
-                    f"Retriable error {response.status_code}", response=response
-                )
-            response.raise_for_status()
+            _handle_http_error(response)
 
         return response.json()
 
     #######################################
+    @_handle_persistent_rate_limit
     @retry(
         stop=stop_after_attempt(3),
         wait=wait_random_exponential(max=5),
@@ -273,6 +320,8 @@ class API:
 
         Raises:
 
+            AuthenticationError: If the request fails with a 401 status code.
+            RateLimitError: If the request fails with persistent 429 status code after retries.
             HTTPError: If the DELETE request fails with a non-200 status code.
         """
         timeout = timeout or self._default_timeout
@@ -282,11 +331,7 @@ class API:
             response.status_code not in [200, 204]
             and response.status_code not in expected_statuscodes
         ):
-            if response.status_code in [429, 502, 503]:
-                raise HTTPError(
-                    f"Retriable error {response.status_code}", response=response
-                )
-            response.raise_for_status()
+            _handle_http_error(response)
 
 
 #################################################

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/documentstore/resources/documents/_search.py

@@ -219,6 +219,8 @@ def hybrid_search(
     Returns:
         List[HybridSearchResult]: The list of hybrid search results.
     """
+    MAX_QUERY_LENGTH = 512
+
     # Input validation
     if query is None:
         raise ValueError("The 'query' argument is required.")
@@ -227,8 +229,8 @@ def hybrid_search(
     query = query.strip()
     if len(query) == 0:
         raise ValueError("The 'query' cannot be empty.")
-    if len(query) > 100:
-        raise ValueError("The 'query' must be 100 characters or less.")
+    if len(query) > MAX_QUERY_LENGTH:
+        raise ValueError(f"The 'query' must be {MAX_QUERY_LENGTH} characters or less.")
 
     body = {
         "query": query,

deepsights_api-1.3.4/deepsights/exceptions.py

@@ -0,0 +1,44 @@
+# Copyright 2024-2025 Market Logic Software AG. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+This module contains custom exception classes for the DeepSights API.
+"""
+
+
+class DeepSightsError(Exception):
+    """Base exception class for all DeepSights API errors."""
+
+    pass
+
+
+class AuthenticationError(DeepSightsError):
+    """Raised when authentication fails due to invalid credentials or permissions."""
+
+    pass
+
+
+class RateLimitError(DeepSightsError):
+    """Raised when API rate limits are exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: float = None):
+        """
+        Initialize RateLimitError.
+
+        Args:
+            message: Error message describing the rate limit violation
+            retry_after: Optional seconds to wait before retrying
+        """
+        super().__init__(message)
+        self.retry_after = retry_after

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/userclient/resources/answersV2/answerV2.py

@@ -16,7 +16,10 @@
 This module contains the functions to retrieve reports from the DeepSights self.
 """
 
+from ratelimit import RateLimitException, limits
+
 from deepsights.api import APIResource
+from deepsights.exceptions import RateLimitError
 from deepsights.userclient.resources.answersV2._model import AnswerV2
 from deepsights.utils import (
     PollingFailedError,
@@ -32,6 +35,7 @@ class AnswerV2Resource(APIResource):
     """
 
     #################################################
+    @limits(calls=10, period=60)
     def create(self, question: str) -> str:
         """
         Creates a new answer V2 by submitting a question to the DeepSights self.
@@ -43,12 +47,21 @@ class AnswerV2Resource(APIResource):
         Returns:
 
             str: The ID of the created answer's minion job.
-        """
 
-        body = {"input": question}
-        response = self.api.post("/end-user-gateway-service/answers-v2", body=body)
+        Raises:
 
-        return response["answer_v2"]["minion_job"]["id"]
+            RateLimitError: If the rate limit of 10 calls per 60 seconds is exceeded.
+        """
+        try:
+            body = {"input": question}
+            response = self.api.post("/end-user-gateway-service/answers-v2", body=body)
+
+            return response["answer_v2"]["minion_job"]["id"]
+        except RateLimitException as e:
+            raise RateLimitError(
+                "Answer creation rate limit exceeded (10 calls per 60 seconds). Please wait before making another request.",
+                retry_after=60,
+            ) from e
 
     #################################################
     def wait_for_answer(self, answer_id: str, timeout=90) -> AnswerV2:
@@ -148,6 +161,7 @@ class AnswerV2Resource(APIResource):
             )
 
     #################################################
+    @limits(calls=10, period=60)
     def create_and_wait(self, question: str, timeout=90) -> AnswerV2:
         """
         Submits a question to the DeepSights API and waits for the answer to complete.
@@ -163,7 +177,14 @@ class AnswerV2Resource(APIResource):
 
         Raises:
 
+            RateLimitError: If the rate limit of 10 calls per 60 seconds is exceeded.
             PollingTimeoutError: If the answer fails to complete within timeout.
             PollingFailedError: If the answer fails to complete.
         """
-        return self.wait_for_answer(self.create(question), timeout=timeout)
+        try:
+            return self.wait_for_answer(self.create(question), timeout=timeout)
+        except RateLimitException as e:
+            raise RateLimitError(
+                "Answer creation rate limit exceeded (10 calls per 60 seconds). Please wait before making another request.",
+                retry_after=60,
+            ) from e

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/userclient/resources/documents/documents.py

@@ -48,6 +48,8 @@ class DocumentResource(APIResource):
     Represents a resource for performing hybrid searches via the DeepSights API.
     """
 
+    MAX_QUERY_LENGTH = 512
+
     #################################################
     def search(
         self, query: str, extended_search: bool = False
@@ -68,8 +70,10 @@ class DocumentResource(APIResource):
         query = query.strip()
         if len(query) == 0:
             raise ValueError("The 'query' cannot be empty.")
-        if len(query) > 100:
-            raise ValueError("The 'query' must be 100 characters or less.")
+        if len(query) > self.MAX_QUERY_LENGTH:
+            raise ValueError(
+                f"The 'query' must be {self.MAX_QUERY_LENGTH} characters or less."
+            )
 
         body = {
             "query": query,
@@ -171,7 +175,7 @@ class DocumentResource(APIResource):
         # load uncached document pages
         def _load_document_page(page_id: str) -> DocumentPage:
             result = self.api.get(
-                f"/end-user-gateway-service/pages/{page_id}", timeout=5
+                f"/end-user-gateway-service/artifacts/pages/{page_id}", timeout=5
             )
 
             # map the document page

{deepsights_api-1.3.2 → deepsights_api-1.3.4}/deepsights/userclient/resources/reports/report.py

@@ -16,7 +16,10 @@
 This module contains the functions to retrieve reports from the DeepSights self.
 """
 
+from ratelimit import RateLimitException, limits
+
 from deepsights.api import APIResource
+from deepsights.exceptions import RateLimitError
 from deepsights.userclient.resources.reports._model import Report
 from deepsights.utils import (
     PollingFailedError,
@@ -32,6 +35,7 @@ class ReportResource(APIResource):
     """
 
     #################################################
+    @limits(calls=3, period=60)
     def create(self, question: str) -> str:
         """
         Creates a new report by submitting a question to the DeepSights self.
@@ -43,12 +47,23 @@ class ReportResource(APIResource):
         Returns:
 
             str: The ID of the created report's minion job.
-        """
 
-        body = {"input": question}
-        response = self.api.post("/end-user-gateway-service/desk-researches", body=body)
+        Raises:
+
+            RateLimitError: If the rate limit of 3 calls per 60 seconds is exceeded.
+        """
+        try:
+            body = {"input": question}
+            response = self.api.post(
+                "/end-user-gateway-service/desk-researches", body=body
+            )
 
-        return response["desk_research"]["minion_job"]["id"]
+            return response["desk_research"]["minion_job"]["id"]
+        except RateLimitException as e:
+            raise RateLimitError(
+                "Report creation rate limit exceeded (3 calls per 60 seconds). Please wait before making another request.",
+                retry_after=60,
+            ) from e
 
     #################################################
     def wait_for_report(self, report_id: str, timeout=600) -> Report: