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

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/.github/workflows/run_tests.yml

@@ -9,7 +9,7 @@ jobs:
 
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.12"]
 
     env:
         PYTHONPATH: ${{ github.workspace }}

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

@@ -2,6 +2,21 @@
 
 <!--next-version-placeholder-->
 
+## v1.3.2 (18-Jun-2025)
+
+- Improved error logging for answer polling
+- Documentation fix
+
+## v1.3.1 (17-Jun-2025)
+
+- **BREAKING CHANGE**: Removed topic_search from documentstore (moved to userclient only)
+- Added comprehensive userclient document management: documents_list(), documents_load(), document_pages_load()
+- Enhanced userclient with hybrid_search functionality
+- Topic search models moved from documentstore to userclient.topic_search module
+- Deprecated documentstore.search_documents() in favor of documentsearch.hybrid_search()
+- Added extensive test coverage for new userclient document methods
+- Clean up of packaging
+
 ## v1.3.0 (15-Jun-2025)
 
 - Added topic-search & hybrid-search support for documentstore and userclient

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/CLAUDE.md

@@ -47,11 +47,11 @@ DeepSights (main client)
 
 ### Key Features
 
-**Search & Retrieval**: Vector-based document search with embeddings, hybrid search combining text/vector results, and recency weighting algorithms.
+**Search & Retrieval**: Vector-based document search with embeddings, hybrid search combining text/vector results, recency weighting algorithms, and AI-powered topic search (via user client).
 
-**Document Management**: Complete lifecycle (upload/search/download/delete) with page-level search and batch operations.
+**Document Management**: Complete lifecycle (upload/search/download/delete) with page-level search and batch operations. User client provides permission-based document listing, loading, and page access.
 
-**AI Integration**: User impersonation for AI answers and report generation with permission-based access control.
+**AI Integration**: User impersonation for AI answers and report generation with permission-based access control. Enhanced user client capabilities include document management, hybrid search, and topic search.
 
 ## Environment Configuration
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepsights-api
-Version: 1.3.0
+Version: 1.3.2
 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
@@ -61,7 +61,7 @@ The **Content Store** holds public and paid 3rd party content, including industr
 
 ### User Client
 
-The **User Client** serves to impersonate existing platform users with their access permissions. The `userclient` API supports obtaining AI-generated answers and reports in reponse to business questions.
+The **User Client** serves to impersonate existing platform users with their access permissions. The `userclient` API supports obtaining AI-generated answers and reports in response to business questions, as well as document management operations with user-specific permissions including document listing, loading, page access, hybrid search, and topic search capabilities.
 
 
 ## Getting started
@@ -129,25 +129,56 @@ response = uc.answersV2.create_and_wait(
 )
 
 print(response.answer)
-print(f"Sources: {len(response.sources)} documents cited")
+print(f"Sources: {len(response.document_sources)} documents cited")
 ```
 
 #### Document Search & Retrieval
 ```python
-# Search your document store
-documents = ds.documentstore.documents.search(
+# Hybrid search combining text and vector search
+results = ds.documentstore.documents.search(
     query="consumer behavior trends 2024",
-    limit=10
+    extended_search=False
 )
 
-for doc in documents.results:
-    print(f"{doc.title} - {doc.upload_date}")
+for result in results:
+    print(f"📄 {result.artifact_title}")
+    print(f"📝 {result.artifact_summary[:100]}...")
+    print(f"📑 {len(result.page_references)} relevant pages\n")
+```
+
+#### User-Specific Document Management
+```python
+# Access documents through user permissions
+uc = ds.get_userclient("analyst@company.com")
+
+# List documents with user-specific access
+total_docs, documents = uc.documents.documents_list(
+    page_size=20,
+    sort_field="creation_date",
+    sort_order="DESC"
+)
+
+# Load specific documents with pages
+loaded_docs = uc.documents.documents_load(
+    document_ids=["doc_id_1", "doc_id_2"],
+    load_pages=True
+)
+
+# Load specific document pages
+pages = uc.documents.document_pages_load(["page_id_1", "page_id_2"])
+
+# Hybrid search through user client
+search_results = uc.documents.search(
+    query="consumer behavior insights",
+    extended_search=True
+)
 ```
 
 #### Topic Search with AI Analysis
 ```python
-# AI-powered topic search for comprehensive insights
-results = ds.documentstore.documents.topic_search(
+# AI-powered topic search available through user client
+uc = ds.get_userclient("analyst@company.com") 
+results = uc.topic_search.search(
     query="sustainable packaging trends", 
     extended_search=True
 )
@@ -157,10 +188,6 @@ for result in results:
     print(f"📊 Relevance: {result.relevance_class}")
     print(f"📝 Summary: {result.artifact_summary[:100]}...")
     print(f"📑 {len(result.page_references)} relevant pages found\n")
-
-# User client version with OAuth authentication
-uc = ds.get_userclient("analyst@company.com") 
-user_results = uc.topic_search.search("market disruption AI")
 ```
 
 #### Content Store Access

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

@@ -31,7 +31,7 @@ The **Content Store** holds public and paid 3rd party content, including industr
 
 ### User Client
 
-The **User Client** serves to impersonate existing platform users with their access permissions. The `userclient` API supports obtaining AI-generated answers and reports in reponse to business questions.
+The **User Client** serves to impersonate existing platform users with their access permissions. The `userclient` API supports obtaining AI-generated answers and reports in response to business questions, as well as document management operations with user-specific permissions including document listing, loading, page access, hybrid search, and topic search capabilities.
 
 
 ## Getting started
@@ -99,25 +99,56 @@ response = uc.answersV2.create_and_wait(
 )
 
 print(response.answer)
-print(f"Sources: {len(response.sources)} documents cited")
+print(f"Sources: {len(response.document_sources)} documents cited")
 ```
 
 #### Document Search & Retrieval
 ```python
-# Search your document store
-documents = ds.documentstore.documents.search(
+# Hybrid search combining text and vector search
+results = ds.documentstore.documents.search(
     query="consumer behavior trends 2024",
-    limit=10
+    extended_search=False
 )
 
-for doc in documents.results:
-    print(f"{doc.title} - {doc.upload_date}")
+for result in results:
+    print(f"📄 {result.artifact_title}")
+    print(f"📝 {result.artifact_summary[:100]}...")
+    print(f"📑 {len(result.page_references)} relevant pages\n")
+```
+
+#### User-Specific Document Management
+```python
+# Access documents through user permissions
+uc = ds.get_userclient("analyst@company.com")
+
+# List documents with user-specific access
+total_docs, documents = uc.documents.documents_list(
+    page_size=20,
+    sort_field="creation_date",
+    sort_order="DESC"
+)
+
+# Load specific documents with pages
+loaded_docs = uc.documents.documents_load(
+    document_ids=["doc_id_1", "doc_id_2"],
+    load_pages=True
+)
+
+# Load specific document pages
+pages = uc.documents.document_pages_load(["page_id_1", "page_id_2"])
+
+# Hybrid search through user client
+search_results = uc.documents.search(
+    query="consumer behavior insights",
+    extended_search=True
+)
 ```
 
 #### Topic Search with AI Analysis
 ```python
-# AI-powered topic search for comprehensive insights
-results = ds.documentstore.documents.topic_search(
+# AI-powered topic search available through user client
+uc = ds.get_userclient("analyst@company.com") 
+results = uc.topic_search.search(
     query="sustainable packaging trends", 
     extended_search=True
 )
@@ -127,10 +158,6 @@ for result in results:
     print(f"📊 Relevance: {result.relevance_class}")
     print(f"📝 Summary: {result.artifact_summary[:100]}...")
     print(f"📑 {len(result.page_references)} relevant pages found\n")
-
-# User client version with OAuth authentication
-uc = ds.get_userclient("analyst@company.com") 
-user_results = uc.topic_search.search("market disruption AI")
 ```
 
 #### Content Store Access

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

@@ -17,9 +17,6 @@ This module contains the client library to interact with the Market Logic DeepSi
 """
 
 from deepsights.deepsights import DeepSights
-from deepsights.documentstore import (
-    SortingField,
-    SortingOrder,
-)
+from deepsights.documentstore.resources import SortingField, SortingOrder
 
 __all__ = ["SortingField", "SortingOrder", "DeepSights"]

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

@@ -98,7 +98,7 @@ class API:
 
         # set keep-alive headers
         self._session.headers.update(
-            {"Connection": "keep-alive", "User-Agent": "deepsights-api/1.3.0"}
+            {"Connection": "keep-alive", "User-Agent": "deepsights-api/1.3.2"}
         )
 
         # store default timeout

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/contentstore/resources/_search.py

@@ -152,7 +152,6 @@ def contentstore_vector_search(
     recency_weight: float = 0.0,
     search_from_timestamp: datetime = None,
     search_to_timestamp: datetime = None,
-    apply_evidence_filter: bool = False,
     search_only_ai_allowed_content: bool = True,
 ) -> List[BaseModel]:
     """
@@ -170,7 +169,6 @@ def contentstore_vector_search(
         recency_weight (float, optional): The weight to apply to recency in result ranking. Defaults to 0.0.
         search_from_timestamp (datetime, optional): The start timestamp for the search. Defaults to None.
         search_to_timestamp (datetime, optional): The end timestamp for the search. Defaults to None.
-        apply_evidence_filter (bool, optional): Whether to apply the evidence filter. Defaults to False.
         search_only_ai_allowed_content (bool, optional): Whether to search only AI-allowed content. Defaults to True.
 
     Returns:
@@ -202,7 +200,6 @@ def contentstore_vector_search(
         "content_restrictions": (
             "ALLOWED_FOR_AI_SUMMARIZATION" if search_only_ai_allowed_content else "NONE"
         ),
-        "use_evidence_filtering": apply_evidence_filter,
     }
     response = api.post("item-service/items/_vector-search", body=body)
 

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/contentstore/resources/news.py

@@ -59,7 +59,6 @@ class NewsResource(APIResource):
         search_from_timestamp: datetime = None,
         search_to_timestamp: datetime = None,
         search_only_ai_allowed_content: bool = True,
-        apply_evidence_filter: bool = False,
     ) -> List[NewsSearchResult]:
         """
         Perform a vector-based search for news articles.
@@ -74,7 +73,6 @@ class NewsResource(APIResource):
             search_from_timestamp (datetime, optional): The start timestamp for the search. Defaults to None.
             search_to_timestamp (datetime, optional): The end timestamp for the search. Defaults to None.
             search_only_ai_allowed_content (bool, optional): Whether to search only AI-allowed content. Defaults to True.
-            apply_evidence_filter (bool, optional): Whether to apply the evidence filter. Defaults to False.
         Returns:
 
             List[NewsSearchResult]: A list of search results as NewsSearchResult objects.
@@ -94,7 +92,6 @@ class NewsResource(APIResource):
             search_from_timestamp=search_from_timestamp,
             search_to_timestamp=search_to_timestamp,
             search_only_ai_allowed_content=search_only_ai_allowed_content,
-            apply_evidence_filter=apply_evidence_filter,
         )
 
     #################################################

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/contentstore/resources/secondary.py

@@ -59,7 +59,6 @@ class SecondaryResource(APIResource):
         search_from_timestamp: datetime = None,
         search_to_timestamp: datetime = None,
         search_only_ai_allowed_content: bool = True,
-        apply_evidence_filter: bool = False,
     ) -> List[SecondarySearchResult]:
         """
         Perform a vector-based search for secondary reports.
@@ -74,7 +73,6 @@ class SecondaryResource(APIResource):
             search_from_timestamp (datetime, optional): The start timestamp for the search. Defaults to None.
             search_to_timestamp (datetime, optional): The end timestamp for the search. Defaults to None.
             search_only_ai_allowed_content (bool, optional): Whether to search only AI-allowed content. Defaults to True.
-            apply_evidence_filter (bool, optional): Whether to apply the evidence filter. Defaults to False.
         Returns:
 
             List[SecondarySearchResult]: A list of search results as SecondarySearchResult objects.
@@ -94,7 +92,6 @@ class SecondaryResource(APIResource):
             search_from_timestamp=search_from_timestamp,
             search_to_timestamp=search_to_timestamp,
             search_only_ai_allowed_content=search_only_ai_allowed_content,
-            apply_evidence_filter=apply_evidence_filter,
         )
 
     #################################################

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/deepsights/_mip_identity.py

@@ -66,17 +66,20 @@ class MIPIdentityResolver(APIKeyAPI):
     #################################################
     def get_oauth_token(self, email: str) -> Optional[str]:
         """
-        Retrieves an oauth token to be used to impersonate the given user.
+        Retrieves an OAuth token for impersonating a user.
 
         Args:
-            email (str): The email of the user to impersonate.
+            email (str): Email address of the user to impersonate.
 
         Returns:
-            Optional[str]: The oauth token of the user, or None if not found
+            Optional[str]: OAuth token if user exists, None otherwise.
 
         Raises:
-            ValueError: If the provided email address is invalid.
+            ValueError: If email format is invalid.
         """
+        if not self._api_key:
+            return None
+
         self._check_email(email)
         body = {"user_email": email}
 
@@ -89,8 +92,6 @@ class MIPIdentityResolver(APIKeyAPI):
         except HTTPError as e:
             if e.response.status_code == 404:
                 return None
-            # Let other HTTP errors (500, 503, 429, etc.) bubble up
-            # as they should be handled by the base API retry logic
             raise
 
         return response["access_token"]

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/deepsights/deepsights.py

@@ -97,3 +97,12 @@ class DeepSights(APIKeyAPI):
                 self.userclients[user_email] = UserClient(oauth_token)
 
             return self.userclients[user_email]
+
+    def get_userclient_by_token(self, oauth_token: str) -> UserClient:
+        """
+        Retrieves a user client for the given OAuth token.
+
+        Args:
+            oauth_token (str): The OAuth token to be used for authentication.
+        """
+        return UserClient(oauth_token)

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/documentstore/__init__.py

@@ -17,6 +17,6 @@ This module contains the client for the document store in the DeepSights API.
 """
 
 from deepsights.documentstore.documentstore import DocumentStore
-from deepsights.documentstore.resources.documents import SortingField, SortingOrder
+from deepsights.documentstore.resources import SortingField, SortingOrder
 
 __all__ = ["DocumentStore", "SortingField", "SortingOrder"]

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/documentstore/resources/__init__.py

@@ -18,6 +18,8 @@ This module contains models and resources for interacting with the document stor
 
 from deepsights.documentstore.resources.documents import (
     DocumentResource,
+)
+from deepsights.documentstore.resources.documents._model import (
     SortingField,
     SortingOrder,
 )

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/documentstore/resources/documents/__init__.py

@@ -16,25 +16,20 @@
 This module contains the resource to interact with documents via the DeepSights API.
 """
 
-from deepsights.documentstore.resources.documents._list import (
+from deepsights.documentstore.resources.documents._model import (
+    HybridSearchPageReference,
+    HybridSearchResult,
     SortingField,
     SortingOrder,
 )
-from deepsights.documentstore.resources.documents._model import (
-    TopicSearchResult,
-    TopicSearchPageReference,
-    HybridSearchResult,
-    HybridSearchPageReference,
+from deepsights.documentstore.resources.documents.documents import (
+    DocumentResource,
 )
-from deepsights.documentstore.resources.documents.documents import DocumentResource
 
 __all__ = [
-    "DocumentResource", 
-    "SortingField", 
+    "DocumentResource",
+    "SortingField",
     "SortingOrder",
-    "TopicSearchResult",
-    "TopicSearchPageReference",
     "HybridSearchResult",
     "HybridSearchPageReference",
 ]
-

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/documentstore/resources/documents/_list.py

@@ -20,28 +20,11 @@ from typing import List
 
 from deepsights.api import APIResource
 from deepsights.documentstore.resources.documents._cache import set_document
-from deepsights.documentstore.resources.documents._model import Document
-
-
-#################################################
-class SortingOrder:
-    """
-    Represents the sorting order for documents.
-    """
-
-    ASCENDING = "ASC"
-    DESCENDING = "DESC"
-
-
-#################################################
-class SortingField:
-    """
-    Represents the sorting field for documents.
-    """
-
-    TITLE = "title"
-    PUBLICATION_DATE = "publication_date"
-    CREATION_DATE = "origin.creation_time"
+from deepsights.documentstore.resources.documents._model import (
+    Document,
+    SortingField,
+    SortingOrder,
+)
 
 
 #################################################

{deepsights_api-1.3.0 → deepsights_api-1.3.2}/deepsights/documentstore/resources/documents/_model.py

@@ -32,6 +32,27 @@ from deepsights.utils import (
 )
 
 
+#################################################
+class SortingOrder:
+    """
+    Represents the sorting order for documents.
+    """
+
+    ASCENDING = "ASC"
+    DESCENDING = "DESC"
+
+
+#################################################
+class SortingField:
+    """
+    Represents the sorting field for documents.
+    """
+
+    TITLE = "title"
+    PUBLICATION_DATE = "publication_date"
+    CREATION_DATE = "origin.creation_time"
+
+
 #################################################
 class DocumentPage(DeepSightsIdModel):
     """
@@ -172,70 +193,6 @@ class DocumentSearchResult(DeepSightsIdModel):
         return super().__repr__()
 
 
-#################################################
-class TopicSearchPageReference(DeepSightsBaseModel):
-    """
-    Represents a page reference in topic search results.
-
-    Attributes:
-        id (str): The ID of the page.
-        external_id (str): External ID of the artifact page.
-        number (int): Page number.
-        title (str): The title of the page.
-    """
-
-    id: str = Field(
-        description="The ID of the page.",
-        validation_alias=AliasChoices("id", "page_id"),
-    )
-    external_id: Optional[str] = Field(
-        description="External ID of the artifact page.",
-        validation_alias=AliasChoices("external_id", "page_external_id"),
-    )
-    number: Optional[int] = Field(
-        description="Page number.",
-        validation_alias=AliasChoices("number", "page_number"),
-    )
-    title: Optional[str] = Field(
-        description="The title of the page.",
-        validation_alias=AliasChoices("title", "page_title"),
-    )
-    text: Optional[str] = Field(
-        description="The text of the page.",
-        validation_alias=AliasChoices("text", "page_text"),
-    )
-    relevance_class: Optional[str] = Field(description="Relevance classification.")
-    relevance_assessment: Optional[str] = Field(description="Relevance assessment.")
-
-
-#################################################
-class TopicSearchResult(DeepSightsBaseModel):
-    """
-    Represents a topic search result for a document.
-
-    Attributes:
-        artifact_id (str): The ID of the artifact.
-        artifact_title (str): The title of the artifact.
-        artifact_summary (str): Summary of the artifact.
-        artifact_source (str): Source of the artifact.
-        artifact_publication_date (datetime): Publication date of the artifact.
-        page_references (List[TopicSearchPageReference]): Page references.
-        relevance_class (str): Relevance classification.
-    """
-
-    artifact_id: str = Field(description="The ID of the artifact.")
-    artifact_title: str = Field(description="The title of the artifact.")
-    artifact_summary: Optional[str] = Field(description="Summary of the artifact.")
-    artifact_source: Optional[str] = Field(description="Source of the artifact.")
-    artifact_publication_date: Optional[datetime] = Field(
-        description="Publication date of the artifact."
-    )
-    page_references: List[TopicSearchPageReference] = Field(
-        description="Page references."
-    )
-    relevance_class: Optional[str] = Field(description="Relevance classification.")
-
-
 #################################################
 class HybridSearchPageReference(DeepSightsBaseModel):
     """

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

@@ -27,7 +27,6 @@ from deepsights.documentstore.resources.documents._model import (
     DocumentPageSearchResult,
     DocumentSearchResult,
     HybridSearchResult,
-    TopicSearchResult,
 )
 from deepsights.utils import promote_exact_matches, rerank_by_recency
 
@@ -140,6 +139,11 @@ def documents_search(
             "The 'query' argument is only used when 'promote_exact_match' is set to True."
         )
 
+    # emit deprecation warning
+    print(
+        "WARNING: The documents_search function is deprecated and will be removed in a future version. Please use the hybrid_search function instead."
+    )
+
     # get the page matches
     page_matches = document_pages_search(
         resource,
@@ -200,46 +204,6 @@ def documents_search(
     return results
 
 
-#################################################
-def topic_search(
-    resource: APIResource, query: str, extended_search: bool = False
-) -> List[TopicSearchResult]:
-    """
-    Searches for documents by topic using AI-powered analysis.
-
-    Args:
-        resource (APIResource): An instance of the DeepSights API resource.
-        query (str): The search query topic.
-        extended_search (bool, optional): Whether to perform extended search. Defaults to False.
-
-    Returns:
-        List[TopicSearchResult]: The list of topic search results.
-    """
-    # Input validation
-    if query is None:
-        raise ValueError("The 'query' argument is required.")
-    if not isinstance(query, str):
-        raise ValueError("The 'query' must be a string.")
-    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.")
-
-    body = {
-        "query": query,
-        "extended_search": extended_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]
-
-
 #################################################
 def hybrid_search(
     resource: APIResource, query: str, extended_search: bool = False
@@ -270,11 +234,11 @@ def hybrid_search(
         "query": query,
         "extended_search": extended_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", [])
     return [HybridSearchResult(**result) for result in search_results]

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

@@ -33,7 +33,6 @@ from deepsights.documentstore.resources.documents._search import (
     document_pages_search,
     documents_search,
     hybrid_search,
-    topic_search,
 )
 from deepsights.documentstore.resources.documents._upload import (
     document_upload,
@@ -54,8 +53,7 @@ class DocumentResource(APIResource):
     load = documents_load
     load_pages = document_pages_load
     download = document_download
-    search = documents_search
+    search_documents = documents_search
     search_pages = document_pages_search
-    hybrid_search = hybrid_search
-    topic_search = topic_search
+    search = hybrid_search
     list = documents_list