personal_knowledge_library 3.1.1__tar.gz → 3.2.0__tar.gz

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: personal_knowledge_library
-Version: 3.1.1
+Version: 3.2.0
 Summary: Library to access Wacom's Personal Knowledge graph.
 License: Apache-2.0
 Keywords: semantic-knowledge,knowledge-graph

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/__init__.py

@@ -17,7 +17,7 @@ __license__ = "Wacom"
 __maintainer__ = ["Markus Weber"]
 __email__ = "markus.weber@wacom.com"
 __status__ = "beta"
-__version__ = "3.1.1"
+__version__ = "3.2.0"
 
 import loguru
 

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/base/__init__.py

@@ -15,8 +15,12 @@ The access is used to access the knowledge graph, there are different types of a
     - Public access: the user can access all the entities.
     - Group access: the user can access the entities that are in the same group.
 """
-__all__ = ["access", "entity", "ontology"]
+__all__ = ["access", "entity", "language", "ontology", "response", "search", "tenant"]
 
 from knowledge.base import access
 from knowledge.base import entity
+from knowledge.base import language
 from knowledge.base import ontology
+from knowledge.base import response
+from knowledge.base import search
+from knowledge.base import tenant

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/base/language.py

@@ -21,7 +21,7 @@ FR: LanguageCode = LanguageCode("fr")
 IT: LanguageCode = LanguageCode("it")
 ES: LanguageCode = LanguageCode("es")
 # ----------------------------------------------------------------------------------------------------------------------
-SUPPORTED_LOCALES: List[LocaleCode] = [JA_JP, EN_US, DE_DE, BG_BG, FR_FR, IT_IT, ES_ES]
-SUPPORTED_LANGUAGES: List[LanguageCode] = [JA, EN, DE, BG, FR, IT, ES]
+SUPPORTED_LOCALES: List[LocaleCode] = [JA_JP, EN_US, DE_DE, BG_BG, IT_IT]
+SUPPORTED_LANGUAGES: List[LanguageCode] = [JA, EN, DE, BG, IT]
 LANGUAGE_LOCALE_MAPPING: Dict[LanguageCode, LocaleCode] = dict(list(zip(SUPPORTED_LANGUAGES, SUPPORTED_LOCALES)))
 LOCALE_LANGUAGE_MAPPING: Dict[LocaleCode, LanguageCode] = dict(list(zip(SUPPORTED_LOCALES, SUPPORTED_LANGUAGES)))

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/base/ontology.py

@@ -1833,7 +1833,7 @@ class ThingObject(abc.ABC):
     @property
     def source_system(self) -> Optional[str]:
         """Default reference system for the entity."""
-        if SYSTEM_SOURCE_REFERENCE_ID in self.__data_properties:
+        if SYSTEM_SOURCE_SYSTEM in self.__data_properties:
             # The en_US is the default language for the source reference system
             for sr in self.data_properties[SYSTEM_SOURCE_SYSTEM]:
                 if sr.language_code == EN_US:
@@ -2179,7 +2179,9 @@ class ThingObject(abc.ABC):
         labels.extend([la.__dict__() for la in self.label])
         labels.extend([la.__dict__() for la in self.alias])
         dict_object: Dict[str, Any] = {
-            SOURCE_REFERENCE_ID_TAG: self.source_reference_id if self.source_reference_id is None else reference_id,
+            SOURCE_REFERENCE_ID_TAG: (
+                self.default_source_reference_id() if self.source_reference_id is not None else reference_id
+            ),
             SOURCE_SYSTEM_TAG: self.source_system,
             IMAGE_TAG: self.image,
             LABELS_TAG: labels,

personal_knowledge_library-3.2.0/knowledge/base/response.py

@@ -0,0 +1,361 @@
+# -*- coding: utf-8 -*-
+# Copyright © 2025-present Wacom. All rights reserved.
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+from typing import Literal
+
+
+class JobStatus:
+    """
+    JobStatus
+    ---------
+    Represents the status of a job.
+
+    Parameters
+    ----------
+    user_id: str
+        Identifies the user who started the job.
+    tenant_id: str
+        Identifies the tenant where the entities are imported.
+    internal_job_id: str
+        Identifies the internal job ID.
+    job_id: str
+        Identifies the job ID.
+    status: Literal["Pending", "InProgress", "Completed", "Failed", "Retrying"]
+        The status of the job. Possible values are:
+        - Pending - The job is pending.
+        - InProgress - The job is in progress.
+        - Completed - The job is completed.
+        - Failed - The job has failed.
+        - Retrying - The job is being retried.
+    processed_entities: int
+        The number of processed entities.
+    processed_relations: int
+        The number of processed relations.
+    processed_images: int
+        The number of processed images.
+    started_at: Optional[datetime]
+        The timestamp when the job started.
+    finished_at: Optional[datetime]
+        The timestamp when the job finished.
+    """
+
+    PENDING: str = "Pending"
+    """The job is pending. It has not started yet, as another job is in progress."""
+    IN_PROGRESS: str = "InProgress"
+    """The job is in progress. It has started but not yet completed."""
+    COMPLETED: str = "Completed"
+    """The job is completed."""
+    FAILED: str = "Failed"
+    """The job has failed."""
+    RETRYING: str = "Retrying"
+    """The job is being retried."""
+
+    def __init__(
+        self,
+        user_id: str,
+        tenant_id: str,
+        internal_job_id: str,
+        job_id: str,
+        status: Literal["Pending", "InProgress", "Completed", "Failed", "Retrying"],
+        processed_entities: int = 0,
+        processed_relations: int = 0,
+        processed_images: int = 0,
+        started_at: Optional[datetime] = None,
+        finished_at: Optional[datetime] = None,
+        failures: int = 0,
+    ):
+        self._userId: str = user_id
+        self._tenantId: str = tenant_id
+        self._internalJobId: str = internal_job_id
+        self._jobId: str = job_id
+        self._status: Literal["Pending", "InProgress", "Completed", "Failed", "Retrying"] = status
+        self._processed_entities: int = processed_entities
+        self._processed_relations: int = processed_relations
+        self._processed_images: int = processed_images
+        self._started_at: Optional[datetime] = started_at
+        self._finished_at: Optional[datetime] = finished_at
+        self._failures: int = failures
+
+    @property
+    def user_id(self) -> str:
+        """
+        Identifies the user who started the job.
+        """
+        return self._userId
+
+    @property
+    def tenant_id(self) -> str:
+        """
+        Identifies the tenant where the entities are imported.
+        """
+        return self._tenantId
+
+    @property
+    def internal_job_id(self) -> str:
+        """
+        Identifies the internal job ID.
+        """
+        return self._internalJobId
+
+    @property
+    def job_id(self) -> str:
+        """
+        Identifies the job ID.
+        """
+        return self._jobId
+
+    @property
+    def status(self) -> Literal["Pending", "InProgress", "Completed", "Failed", "Retrying"]:
+        """
+        The status of the job. Possible values are:
+        - Pending - The job is pending.
+        - InProgress - The job is in progress.
+        - Completed - The job is completed.
+        - Failed - The job has failed.
+        - Retrying - The job is being retried.
+        """
+        return self._status
+
+    @property
+    def processed_entities(self) -> int:
+        """
+        The number of processed entities.
+        """
+        return self._processed_entities
+
+    @property
+    def processed_relations(self) -> int:
+        """
+        The number of processed relations.
+        """
+        return self._processed_relations
+
+    @property
+    def processed_images(self) -> int:
+        """
+        The number of processed images.
+        """
+        return self._processed_images
+
+    @property
+    def started_at(self) -> Optional[datetime]:
+        """
+        The timestamp when the job started.
+        """
+        return self._started_at
+
+    @property
+    def finished_at(self) -> Optional[datetime]:
+        """
+        The timestamp when the job finished.
+        """
+        return self._finished_at
+
+    @property
+    def failures(self) -> int:
+        """
+        The number of failures encountered during the job.
+        """
+        return self._failures
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "JobStatus":
+        """
+        Create a JobStatus instance from a dictionary.
+        Parameters
+        ----------
+        data: Dict[str, Any]
+            Response data from the API.
+
+        Returns
+        -------
+        instance: JobStatus
+            Instance of JobStatus.
+        """
+        return cls(
+            user_id=data.get("userId"),
+            tenant_id=data.get("tenantId"),
+            internal_job_id=data.get("internalJobId"),
+            job_id=data.get("jobId"),
+            status=data.get("status"),
+            processed_entities=data.get("processed", {}).get("entities", 0),
+            processed_relations=data.get("processed", {}).get("relations", 0),
+            processed_images=data.get("processed", {}).get("images", 0),
+            started_at=datetime.fromisoformat(data.get("startedAt", datetime.now().isoformat())),
+            finished_at=datetime.fromisoformat(data.get("finishedAt", datetime.now().isoformat())),
+            failures=data.get("failures", 0),
+        )
+
+    def __repr__(self):
+        return (
+            f"JobStatus(userId={self.user_id}, tenantId={self.tenant_id}, internalJobId={self.internal_job_id}, "
+            f"jobId={self.job_id}, status={self.status}, failures={self.failures}, "
+            f"processed_entities={self.processed_entities}, "
+            f"processed_relations={self.processed_relations}, processed_images={self.processed_images}, "
+            f"started_at={self.started_at}, finished_at={self.finished_at})"
+        )
+
+
+class ErrorDetail:
+    """
+    ErrorDetail
+    ----------
+    Represents an error detail.
+
+    Parameters
+    ----------
+    severity: str
+        The severity of the error.
+    reason: str
+        The reason for the error.
+    position_offset: int
+        The position offset of the error in the file.
+    timestamp: str
+        The timestamp of the error in ISO 8601 format.
+    """
+
+    def __init__(self, severity: str, reason: str, position_offset: int, timestamp: str):
+        self._severity = severity
+        self._reason = reason
+        self._position_offset = position_offset
+        self._timestamp = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+
+    @property
+    def severity(self) -> str:
+        """The severity of the error."""
+        return self._severity
+
+    @property
+    def reason(self) -> str:
+        """The reason for the error."""
+        return self._reason
+
+    @property
+    def position_offset(self) -> int:
+        """The position offset of the error in the file."""
+        return self._position_offset
+
+    @property
+    def timestamp(self) -> datetime:
+        """The timestamp of the error in ISO 8601 format."""
+        return self._timestamp
+
+
+class ErrorLogEntry:
+    """
+    ErrorLogEntry
+    -------------
+    Represents an entry in the error log.
+
+    """
+
+    def __init__(self, source_reference_id: Optional[str], errors: List[ErrorDetail]):
+        self._source_reference_id = source_reference_id
+        self._errors = errors
+
+    @property
+    def source_reference_id(self) -> Optional[str]:
+        """The source reference ID."""
+        return self._source_reference_id
+
+    @property
+    def errors(self) -> List[ErrorDetail]:
+        """The list of errors."""
+        return self._errors
+
+
+class ErrorLogResponse:
+    """
+    ErrorLogResponse
+    ----------------
+    Represents the response for error log.
+    """
+
+    def __init__(self, next_page_id: str, error_log: List[ErrorLogEntry]):
+        self._next_page_id = next_page_id
+        self._error_log = error_log
+
+    @property
+    def next_page_id(self) -> str:
+        """The ID of the next page."""
+        return self._next_page_id
+
+    @property
+    def error_log(self) -> List[ErrorLogEntry]:
+        """The list of error log entries."""
+        return self._error_log
+
+    @classmethod
+    def from_dict(cls, param: Dict[str, Any]) -> "ErrorLogResponse":
+        """
+        Create an ErrorLogResponse instance from a dictionary.
+        Parameters
+        ----------
+        param: Dict[str, Any]
+            Response data from the API.
+
+        Returns
+        -------
+        instance: ErrorLogResponse
+            Instance of ErrorLogResponse.
+        """
+        error_log_entries = []
+        for entry in param.get("errorLog", []):
+            errors = [
+                ErrorDetail(
+                    severity=e["severity"],
+                    reason=e["reason"],
+                    position_offset=e["positionOffset"],
+                    timestamp=e["timestamp"],
+                )
+                for e in entry.get("errors", [])
+            ]
+            error_log_entries.append(ErrorLogEntry(source_reference_id=entry.get("sourceReferenceId"), errors=errors))
+
+        return ErrorLogResponse(next_page_id=param["nextPageId"], error_log=error_log_entries)
+
+
+class NewEntityUrisResponse:
+    """
+    NewEntityUrisResponse
+    -------------------
+    Represents the response for new entities.
+
+    Parameters
+    ----------
+    new_entities_uris: List[str]
+        The list of URIs of new entities.
+    next_page_id: Optional[str]
+        Next page ID for pagination.
+    """
+
+    def __init__(self, new_entities_uris: List[str], next_page_id: Optional[str]):
+        self._new_entities_uris: List[str] = new_entities_uris
+        self._next_page_id: Optional[str] = next_page_id
+
+    @property
+    def new_entities_uris(self) -> List[str]:
+        """The list the uris of new entities."""
+        return self._new_entities_uris
+
+    @property
+    def next_page_id(self) -> Optional[str]:
+        """The ID of the next page."""
+        return self._next_page_id
+
+    @classmethod
+    def from_dict(cls, param: Dict[str, Any]) -> "NewEntityUrisResponse":
+        """
+        Create a NewEntityUrisResponse instance from a dictionary.
+        Parameters
+        ----------
+        param: Dict[str, Any]
+            Response data from the API.
+
+        Returns
+        -------
+        instance: NewEntityUrisResponse
+            Instance of NewEntityUrisResponse.
+        """
+        return cls(new_entities_uris=param["uris"], next_page_id=param.get("nextPage"))

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/ontomapping/__init__.py

@@ -543,6 +543,7 @@ def build_configuration(mapping: Dict[str, Any]) -> MappingConfiguration:
         conf.add_property(property_config)
     return conf
 
+
 def register_ontology(rdf_str: str):
     """
     Registers the ontology.
@@ -553,6 +554,7 @@ def register_ontology(rdf_str: str):
     """
     ontology_graph.parse(data=rdf_str, format="xml")
 
+
 def load_configuration(configuration: Path):
     """
     Loads the configuration.

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/public/client.py

@@ -348,8 +348,9 @@ class WikiDataAPIClient:
         return WikiDataAPIClient.__wikidata_task__(qid)
 
     @staticmethod
-    def retrieve_entities(qids: Union[List[str], Set[str]], progress: Optional[Callable[[int, int], None]] = None) \
-            -> List[WikidataThing]:
+    def retrieve_entities(
+        qids: Union[List[str], Set[str]], progress: Optional[Callable[[int, int], None]] = None
+    ) -> List[WikidataThing]:
         """
         Retrieve multiple Wikidata things.
         Parameters

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/services/__init__.py

@@ -3,7 +3,7 @@
 """
 This package contains the services for the knowledge graph functionality.
 """
-from typing import List
+from typing import List, Literal
 
 # ------------------------------------------------- Constants ----------------------------------------------------------
 USER_AGENT_HEADER_FLAG: str = "User-Agent"
@@ -52,6 +52,7 @@ PRUNE_PARAM: str = "prune"
 NEL_PARAM: str = "nelType"
 
 APPLICATION_JSON_HEADER: str = "application/json"
+IndexType = Literal["NEL", "ElasticSearch", "VectorSearchWord", "VectorSearchDocument"]
 
 DEFAULT_TIMEOUT: int = 60
 DEFAULT_TOKEN_REFRESH_TIME: int = 360
@@ -119,6 +120,7 @@ __all__ = [
     "STATUS_FORCE_LIST",
     "DEFAULT_BACKOFF_FACTOR",
     "DEFAULT_MAX_RETRIES",
+    "IndexType",
 ]
 
 from knowledge.services import base

{personal_knowledge_library-3.1.1 → personal_knowledge_library-3.2.0}/knowledge/services/asyncio/graph.py

@@ -36,7 +36,7 @@ from knowledge.base.ontology import (
     ObjectProperty,
 )
 from knowledge.nel.base import KnowledgeGraphEntity, EntityType, KnowledgeSource, EntitySource
-from knowledge.services import AUTHORIZATION_HEADER_FLAG, IS_OWNER_PARAM
+from knowledge.services import AUTHORIZATION_HEADER_FLAG, IS_OWNER_PARAM, IndexType
 from knowledge.services import (
     SUBJECT_URI,
     RELATION_URI,
@@ -570,6 +570,121 @@ class AsyncWacomKnowledgeService(AsyncServiceAPIClient):
                     )
         await asyncio.sleep(0.25 if self.use_graceful_shutdown else 0.0)
 
+    async def add_entity_indexes(
+        self,
+        entity_uri: str,
+        targets: List[IndexType],
+        auth_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> Dict[IndexType, Any]:
+        """
+        Updates index targets of an entity. The index targets can be set to "NEL", "ElasticSearch", "VectorSearchWord",
+        or "VectorSearchDocument".
+        If the target is already set for the entity, there will be no changes.
+
+        Parameters
+        ----------
+        entity_uri: str
+            URI of entity
+        targets: List[Literal["NEL", "ElasticSearch", "VectorSearchWord", "VectorSearchDocument"]]
+            List of indexing targets
+        auth_key: Optional[str]
+            If the auth key is set the logged-in user (if any) will be ignored and the auth key will be used.
+        timeout: int
+            Timeout for the request (default: 60 seconds)
+
+        Returns
+        -------
+        update_status: Dict[str, Any]
+            Status per target (depending on the targets of entity and the ones set in the request). If the entity
+            already has the target set, the status will be "Target already exists" for that target,
+            otherwise it will be "UPSERT".
+
+        Raises
+        ------
+        WacomServiceException
+            If the graph service returns an error code
+        """
+        if auth_key is None:
+            auth_key, _ = await self.handle_token()
+        url: str = f"{self.service_base_url}{AsyncWacomKnowledgeService.ENTITY_ENDPOINT}/{entity_uri}/indexes"
+        # Header info
+        headers: dict = {
+            USER_AGENT_HEADER_FLAG: self.user_agent,
+            CONTENT_TYPE_HEADER_FLAG: APPLICATION_JSON_HEADER,
+            AUTHORIZATION_HEADER_FLAG: f"Bearer {auth_key}",
+        }
+        async with AsyncServiceAPIClient.__async_session__() as session:
+            async with session.patch(
+                url, json=targets, headers=headers, timeout=timeout, verify_ssl=self.verify_calls
+            ) as response:
+                if not response.ok:
+                    raise await handle_error(
+                        f"Update of entity indexes failed. URI:={entity_uri}.",
+                        response,
+                        payload={"targets": targets},
+                        headers=headers,
+                    )
+                response_dict: Dict[str, Any] = await response.json(loads=orjson.loads)
+        await asyncio.sleep(0.25 if self.use_graceful_shutdown else 0.0)
+        return response_dict
+
+    async def remove_entity_indexes(
+        self,
+        entity_uri: str,
+        targets: List[IndexType],
+        auth_key: Optional[str] = None,
+        timeout: int = DEFAULT_TIMEOUT,
+    ) -> Dict[IndexType, Any]:
+        """
+        Deletes the search index for a given entity.
+
+        Parameters
+        ----------
+        entity_uri: str
+            URI of entity
+        targets: List[Literal["NEL", "ElasticSearch", "VectorSearchWord", "VectorSearchDocument"]]
+            List of indexing targets
+        auth_key: Optional[str]
+            If the auth key is set the logged-in user (if any) will be ignored and the auth key will be used.
+        timeout: int
+            Timeout for the request (default: 60 seconds)
+
+        Returns
+        -------
+        update_status: Dict[str, Any]
+            Status per target (depending on the targets of entity and the ones set in the request), e.g.,
+            response will only contain {"NEL: "DELETE"}, if NEL is the only target in the request.
+
+        Raises
+        ------
+        WacomServiceException
+            If the graph service returns an error code
+        """
+        if auth_key is None:
+            auth_key, _ = await self.handle_token()
+        url: str = f"{self.service_base_url}{AsyncWacomKnowledgeService.ENTITY_ENDPOINT}/{entity_uri}/indexes"
+        # Header info
+        headers: dict = {
+            USER_AGENT_HEADER_FLAG: self.user_agent,
+            CONTENT_TYPE_HEADER_FLAG: APPLICATION_JSON_HEADER,
+            AUTHORIZATION_HEADER_FLAG: f"Bearer {auth_key}",
+        }
+        async with AsyncServiceAPIClient.__async_session__() as session:
+            async with session.delete(
+                url, json=targets, headers=headers, timeout=timeout, verify_ssl=self.verify_calls
+            ) as response:
+                if not response.ok:
+                    raise await handle_error(
+                        f"Deletion of entity indexes failed. URI:={entity_uri}.",
+                        response,
+                        payload={"targets": targets},
+                        headers=headers,
+                    )
+                response_dict: Dict[str, Any] = await response.json(loads=orjson.loads)
+        await asyncio.sleep(0.25 if self.use_graceful_shutdown else 0.0)
+        return response_dict
+
     async def relations(
         self, uri: str, auth_key: Optional[str] = None
     ) -> Dict[OntologyPropertyReference, ObjectProperty]: