deepsights-api 0.2.0__py3-none-any.whl

deepsights/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2024 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 the client library to interact with the Market Logic DeepSights and ContentStore APIs.
+"""
+
+from deepsights.api import *
+from deepsights.documents import *
+from deepsights.contentstore import *
+from deepsights.answers import *
+from deepsights.reports import *

deepsights/answers/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2024 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 the functions to retrieve answers from the DeepSights API.
+"""
+
+from deepsights.answers.model import DocumentAnswer, DocumentAnswerPageReference
+from deepsights.answers.answer import (
+    answer_set_create,
+    answer_set_wait_for_completion,
+    answer_set_get,
+    answer_set_get_sync,
+)
+from deepsights.answers.answer_v1 import answers_get

deepsights/answers/answer.py

@@ -0,0 +1,106 @@
+# Copyright 2024 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 the functions to retrieve answers from the DeepSights API.
+"""
+
+from deepsights.api import DeepSights
+from deepsights.minions._minions import minion_wait_for_completion
+from deepsights.answers.model import DocumentAnswerSet, DocumentAnswer
+
+
+#################################################
+def answer_set_create(api: DeepSights, question: str) -> str:
+    """
+    Creates a new answer set by submitting a question to the DeepSights API.
+
+    Args:
+
+        api (DeepSights): An instance of the DeepSights API client.
+        question (str): The question to be submitted for the answers.
+
+    Returns:
+
+        str: The ID of the created answer's minion job.
+    """
+
+    body = {"input": question}
+    response = api.post("/minion-commander-service/answer-sets", body=body, timeout=5)
+
+    return response["minion_job"]["id"]
+
+
+#################################################
+def answer_set_wait_for_completion(api: DeepSights, answer_set_id: str, timeout=30):
+    """
+    Waits for the completion of an answer set.
+
+    Args:
+
+        api (DeepSights): The DeepSights API instance.
+        answer_set_id (str): The ID of the answer set.
+        timeout (int, optional): The maximum time to wait for the answer set to complete, in seconds.
+        Defaults to 30.
+
+    Raises:
+
+        ValueError: If the answer set fails to complete.
+    """
+    return minion_wait_for_completion(api, "answer-sets", answer_set_id, timeout)
+
+
+#################################################
+def answer_set_get(api: DeepSights, answer_set_id: str) -> DocumentAnswerSet:
+    """
+    Loads an answer set from the DeepSights API.
+
+    Args:
+
+        api (DeepSights): An instance of the DeepSights API client.
+        answer_set_id (str): The ID of the answer set to load.
+
+    Returns:
+
+        DocumentAnswerSet: The answer set.
+    """
+    response = api.get(f"/minion-commander-service/answer-sets/{answer_set_id}")
+
+    return DocumentAnswerSet(
+        answers=[
+            DocumentAnswer.model_validate(answer)
+            for answer in response["context"]["summarized_search_results"]
+        ]
+    )
+
+
+#################################################
+def answer_set_get_sync(api: DeepSights, question: str) -> DocumentAnswerSet:
+    """
+    Submits a question to the DeepSights API and waits for the answer set to complete.
+
+    Args:
+
+        api (DeepSights): An instance of the DeepSights API client.
+        question (str): The question to be submitted for the answers.
+
+    Returns:
+
+        DocumentAnswerSet: The answer set.
+    """
+    answer_set_id = answer_set_create(api, question)
+
+    answer_set_wait_for_completion(api, answer_set_id)
+
+    return answer_set_get(api, answer_set_id)

deepsights/answers/answer_v1.py

@@ -0,0 +1,55 @@
+# Copyright 2024 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 the functions to retrieve answers v1 from the DeepSights API.
+"""
+
+import logging
+from typing import List
+from deepsights.api import DeepSights
+from deepsights.answers.model import DocumentAnswer
+
+
+#################################################
+def answers_get(api: DeepSights, question: str, timeout=30) -> List[DocumentAnswer]:
+    """
+    Retrieves answers for a given question.
+
+    This function is deprecated and will be removed in a future release. 
+    Please use the answer_set_create, answer_set_wait_for_completion, 
+    and answer_set_get functions instead.
+
+    Args:
+
+        api (DeepSights): The DeepSights API client.
+        question (str): The question to retrieve answers for.
+        timeout (int, optional): The timeout for the request. Defaults to 30.
+
+    Returns:
+
+        List[DocumentAnswer]: The list of answers for the question.
+    """
+
+    # deprecation warning
+    logging.warning(
+        "===== DEPRECATION WARNING =====\n"
+        "The answers_get function is deprecated and will be removed in a future release. "
+        "Please use the answer_set_create, answer_set_wait_for_completion, and answer_set_get functions instead."
+    )
+
+    body = {"search_term": question}
+    response = api.post("/answer-service/answer-sets", body=body, timeout=timeout)
+
+    return [DocumentAnswer.model_validate(answer) for answer in response["answers"]]

deepsights/answers/model.py

@@ -0,0 +1,107 @@
+# Copyright 2024 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 the models for answers in the DeepSights API.
+"""
+
+from typing import Optional, List
+from datetime import datetime
+from pydantic import Field, BaseModel,  AliasChoices
+from deepsights.utils import DeepSightsIdModel, DeepSightsIdTitleModel
+
+
+#################################################
+class BaseAnswer(DeepSightsIdTitleModel):
+    """
+    Represents a base answer object.
+
+    Attributes:
+
+        answer (str): The summary of the answer.
+        artifact_id (str): The ID of the artifact.
+        artifact_type (str): The type of the artifact.
+        artifact_description (Optional[str]): The human-readable summary of the artifact.
+        timestamp (datetime, optional): The publication date of the answer. Defaults to None.
+    """
+
+    answer: str = Field(alias="summary", description="The answer from the artifact.")
+    artifact_id: str = Field(
+        description="The ID of the artifact from which the answer is derived."
+    )
+    artifact_type: str = Field(
+        description="The type of the artifact from which the answer is derived."
+    )
+    artifact_description: Optional[str] = Field(
+        alias="artifact_summary",
+        default=None,
+        description="The human-readable summary of the artifact.",
+    )
+    timestamp: Optional[datetime] = Field(
+        alias="publication_date",
+        default=None,
+        description="The publication date of the artifact from which the answer is derived.",
+    )
+
+
+#################################################
+class DocumentAnswerPageReference(DeepSightsIdModel):
+    """
+    Represents a reference to a specific page in a document.
+
+    Attributes:
+
+        page_number (int): The page number in the document.
+    """
+
+    page_number: int = Field(
+        validation_alias=AliasChoices("page_number", "number"),
+        description="The page number in the document."
+    )
+
+
+#################################################
+class DocumentAnswer(BaseAnswer):
+    """
+    Represents an answer that is a document.
+
+    Attributes:
+
+        artifact_type (str): The type of the artifact, which is set to "DOCUMENT".
+        pages (Optional[int]): The total number of pages in the document.
+    """
+
+    artifact_type: str = Field(
+        default="DOCUMENT",
+        description="The type of the artifact from which the answer is derived.",
+    )
+    pages: List[DocumentAnswerPageReference] = Field(
+        alias="page_references",
+        description="The references to the pages in the document.",
+    )
+
+
+#################################################
+class DocumentAnswerSet(BaseModel):
+    """
+    Represents an answer set that contains document answers.
+
+    Attributes:
+
+        answers (List[DocumentAnswer]): The list of document answers in the set.
+    """
+
+    answers: List[DocumentAnswer] = Field(
+        description="The list of document answers in the set."
+    )

deepsights/api/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2024 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 the base functions to interact with the DeepSights API.
+"""
+
+from deepsights.api.api import DeepSights, ContentStore
+from deepsights.api.model import APIProfile, QuotaInfo, QuotaStatus
+from deepsights.api.quota import quota_get_status, api_get_profile

deepsights/api/api.py

@@ -0,0 +1,231 @@
+# Copyright 2024 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 the base functions to interact with the DeepSights API.
+"""
+
+import os
+import logging
+from typing import Dict
+from tenacity import (
+    retry,
+    stop_after_attempt,
+    wait_random_exponential,
+    retry_if_exception_type,
+)
+from requests import Session
+from requests.exceptions import Timeout
+from ratelimit import limits, sleep_and_retry
+
+
+#################################################
+class API:
+    """
+    Represents an API client for interacting with the DeepSights APIs.
+    """
+
+    #######################################
+    def __init__(
+        self, endpoint_base: str, api_key: str, api_key_env_var: str = None
+    ) -> None:
+        """
+        Initializes the API client.
+
+        Args:
+
+            endpoint_base (str): The base URL of the API endpoint.
+            api_key (str): The API key to be used for authentication.
+            api_key_env_var (str, optional): The name of the environment variable that contains the API key.
+                If not provided, the API key must be passed directly as an argument. Defaults to None.
+
+        Raises:
+
+            AssertionError: If neither API key nor environment variable is provided.
+        """
+
+        # fall back to environment variable
+        assert (
+            api_key or api_key_env_var
+        ), "Must provide either API key or environment variable"
+        if not api_key:
+            api_key = os.environ.get(api_key_env_var)
+        self._api_key = api_key
+
+        # record endpoint base
+        self._endpoint_base = endpoint_base
+        if not self._endpoint_base.endswith("/"):
+            self._endpoint_base += "/"
+        # prepare session
+        self._session = Session()
+        self._session.headers.update({"X-Api-Key": self._api_key})
+
+    #######################################
+    def _endpoint(self, path: str) -> str:
+        """
+        Constructs the full endpoint URL by appending the given path to the base endpoint.
+
+        Args:
+
+            path (str): The path to be appended to the base endpoint.
+
+        Returns:
+
+            str: The full endpoint URL.
+        """
+        return self._endpoint_base + path
+
+    #######################################
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_random_exponential(max=5),
+        retry=retry_if_exception_type(Timeout),
+    )
+    @sleep_and_retry
+    @limits(calls=1000, period=60)
+    def get(self, path: str, params: Dict = None, timeout=15) -> Dict:
+        """
+        Sends a GET request to the specified path with optional parameters.
+
+        Args:
+
+            path (str): The path to send the GET request to.
+            params (Dict, optional): Optional parameters to include in the request. Defaults to None
+            timeout (int, optional): The timeout in seconds for the request. Defaults to 15.
+
+        Returns:
+
+            The JSON body of the server's response to the request.
+        """
+
+        response = self._session.get(
+            self._endpoint(path), params=params, timeout=timeout
+        )
+
+        if response.status_code != 200:
+            logging.error(
+                "GET %s failed with status code %s", path, response.status_code
+            )
+            response.raise_for_status()
+
+        return response.json()
+
+    #######################################
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_random_exponential(max=5),
+        retry=retry_if_exception_type(Timeout),
+    )
+    @sleep_and_retry
+    @limits(calls=100, period=60)
+    def post(self, path: str, body: Dict, params: Dict = None, timeout=15) -> Dict:
+        """
+        Sends a POST request to the specified path with optional parameters.
+
+        Args:
+
+            path (str): The path to send the POST request to.
+            body (Dict): The JSON body to include in the request.
+            params (Dict, optional): Optional parameters to include in the request. Defaults to None.
+            timeout (int, optional): The timeout in seconds for the request. Defaults to 15.
+
+        Returns:
+
+            Dict: The JSON body of the server's response to the request.
+        """
+
+        response = self._session.post(
+            self._endpoint(path), params=params, json=body, timeout=timeout
+        )
+
+        if response.status_code != 200:
+            logging.error(
+                "POST %s failed with status code %s", path, response.status_code
+            )
+            response.raise_for_status()
+
+        return response.json()
+
+    #######################################
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_random_exponential(max=5),
+        retry=retry_if_exception_type(Timeout),
+    )
+    @sleep_and_retry
+    @limits(calls=1000, period=60)
+    def delete(self, path: str, timeout=5):
+        """
+        Sends a DELETE request to the specified path.
+
+        Args:
+
+            path (str): The path to send the DELETE request to.
+            timeout (int, optional): The timeout for the request in seconds. Defaults to 5.
+
+        Raises:
+
+            HTTPError: If the DELETE request fails with a non-200 status code.
+        """
+        response = self._session.delete(self._endpoint(path), timeout=timeout)
+
+        if response.status_code != 200:
+            logging.error(
+                "DELETE %s failed with status code %s", path, response.status_code
+            )
+            response.raise_for_status()
+
+
+#################################################
+class ContentStore(API):
+    """
+    This class provides methods to interact with the ContentStore API.
+    """
+
+    #######################################
+    def __init__(self, api_key: str = None) -> None:
+        """
+        Initializes the API client.
+
+        Args:
+
+            api_key (str, optional): The API key to be used for authentication. If not provided, it will be fetched from the environment variable CONTENTSTORE_API_KEY.
+        """
+        super().__init__(
+            endpoint_base="https://apigee.mlsdevcloud.com/secondary-content/api/",
+            api_key=api_key,
+            api_key_env_var="CONTENTSTORE_API_KEY",
+        )
+
+
+#################################################
+class DeepSights(API):
+    """
+    This class provides methods to interact with the DeepSights API.
+    """
+
+    #######################################
+    def __init__(self, api_key: str = None) -> None:
+        """
+        Initializes the API client.
+
+        Args:
+        
+            api_key (str, optional): The API key to be used for authentication. If not provided, it will be fetched from the environment variable DEEPSIGHTS_API_KEY.
+        """
+        super().__init__(
+            endpoint_base="https://api.deepsights.ai/ds/v1/",
+            api_key=api_key,
+            api_key_env_var="DEEPSIGHTS_API_KEY",
+        )

deepsights/api/model.py

@@ -0,0 +1,96 @@
+# Copyright 2024 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 the models for the DeepSights API.
+"""
+
+from typing import Optional
+from datetime import datetime
+from pydantic import Field
+from deepsights.utils import DeepSightsBaseModel
+
+
+#################################################
+class APIProfile(DeepSightsBaseModel):
+    """
+    Represents the profile of an API key.
+
+    Attributes:
+
+        app (str): The name of the application associated with the API key.
+        tenant (str): The name of the tenant associated with the API key.
+        user (Optional[str]): The user ID associated with the API key.
+        day_quota (Optional[int]): The daily request quota limit for the API key.
+        minute_quota (Optional[int]): The minute request quota limit for the API key.
+    """
+
+    app: str = Field(
+        description="The name of the application associated with the API key."
+    )
+    tenant: str = Field(
+        description="The name of the tenant associated with the API key."
+    )
+    user: Optional[str] = Field(description="The user ID associated with the API key.")
+    day_quota: Optional[int] = Field(
+        alias="daily_quota_limit",
+        description="The daily request quota limit for the API key; if None, unlimited.",
+    )
+    minute_quota: Optional[int] = Field(
+        alias="minute_quota_limit",
+        description="The minute request quota limit for the API key; if None, unlimited.",
+    )
+
+
+#################################################
+class QuotaInfo(DeepSightsBaseModel):
+    """
+    Represents information about the quota for API requests.
+
+    Attributes:
+
+        quota (Optional[int]): The request quota limit.
+        quota_used (Optional[int]): The number of requests used.
+        quota_reset_at (datetime): The time at which the quota will be reset.
+    """
+
+    quota: Optional[int] = Field(
+        alias="quota_limit",
+        description="The request quota limit per time period; if None, unlimited.",
+    )
+    quota_used: Optional[int] = Field(
+        description="The number of requests used in this time period."
+    )
+    quota_reset_at: datetime = Field(
+        description="The time at which the quota will be reset."
+    )
+
+
+#################################################
+class QuotaStatus(DeepSightsBaseModel):
+    """
+    Represents the quota status for the API.
+
+    Attributes:
+    
+        day_quota (QuotaInfo): The daily quota limit and status.
+        minute_quota (QuotaInfo): The minute quota limit and status.
+    """
+
+    day_quota: QuotaInfo = Field(
+        alias="daily", description="The daily quota limit and status."
+    )
+    minute_quota: QuotaInfo = Field(
+        alias="minute", description="The minute quota limit and status."
+    )