cognite-neat 0.106.0__tar.gz → 0.108.0__tar.gz

{cognite_neat-0.106.0 → cognite_neat-0.108.0}/PKG-INFO

@@ -1,8 +1,7 @@
 Metadata-Version: 2.3
 Name: cognite-neat
-Version: 0.106.0
+Version: 0.108.0
 Summary: Knowledge graph transformation
-Home-page: https://cognite-neat.readthedocs-hosted.com/
 License: Apache-2.0
 Author: Nikola Vasiljevic
 Author-email: nikola.vasiljevic@cognite.com
@@ -54,6 +53,7 @@ Requires-Dist: tomli (>=2.0.1,<3.0.0) ; python_version < "3.11"
 Requires-Dist: typing_extensions (>=4.8,<5.0) ; python_version < "3.11"
 Requires-Dist: urllib3 (>=2,<3)
 Project-URL: Documentation, https://cognite-neat.readthedocs-hosted.com/
+Project-URL: Homepage, https://cognite-neat.readthedocs-hosted.com/
 Project-URL: Repository, https://github.com/cognitedata/neat
 Description-Content-Type: text/markdown
 

{cognite_neat-0.106.0 → cognite_neat-0.108.0}/cognite/neat/_constants.py

@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
 from cognite.client import data_modeling as dm
 from cognite.client.data_classes.data_modeling.ids import DataModelId
 from rdflib import DC, DCTERMS, FOAF, OWL, RDF, RDFS, SH, SKOS, XSD, Namespace, URIRef
+from rdflib.namespace import DefinedNamespace
 
 from cognite import neat
 
@@ -73,10 +74,22 @@ DEFAULT_NAMESPACE = Namespace("http://purl.org/cognite/neat/")
 CDF_NAMESPACE = Namespace("https://cognitedata.com/")
 DEFAULT_BASE_URI = URIRef(DEFAULT_NAMESPACE)
 CLASSIC_CDF_NAMESPACE = Namespace("http://purl.org/cognite/cdf-classic#")
-UNKNOWN_TYPE = DEFAULT_NAMESPACE.UnknownType
 XML_SCHEMA_NAMESPACE = Namespace("http://www.w3.org/2001/XMLSchema#")
 
 
+class NEAT(DefinedNamespace):
+    """
+    NEAT internal data model used for internal purposes of the NEAT library
+
+    """
+
+    _fail = True
+    _NS = Namespace("http://thisisneat.io/internal/")
+
+    type: URIRef  # type property used to express a type of a subject
+    UnknownType: URIRef  # Unknown type used to express that the type of a subject is unknown
+
+
 def get_default_prefixes_and_namespaces() -> dict[str, Namespace]:
     return {
         "owl": OWL._NS,
@@ -154,3 +167,24 @@ READONLY_PROPERTIES_BY_CONTAINER: Mapping[dm.ContainerId, frozenset[str]] = {
 
 def is_readonly_property(container: dm.ContainerId, property_: str) -> bool:
     return container in READONLY_PROPERTIES_BY_CONTAINER and property_ in READONLY_PROPERTIES_BY_CONTAINER[container]
+
+
+DMS_RESERVED_PROPERTIES = frozenset(
+    {
+        "createdTime",
+        "deletedTime",
+        "edge_id",
+        "extensions",
+        "externalId",
+        "lastUpdatedTime",
+        "node_id",
+        "project_id",
+        "property_group",
+        "seq",
+        "space",
+        "version",
+        "tg_table_name",
+        "startNode",
+        "endNode",
+    }
+)

{cognite_neat-0.106.0 → cognite_neat-0.108.0}/cognite/neat/_graph/_shared.py

@@ -7,6 +7,10 @@ MIMETypes: TypeAlias = Literal[
 RDFTypes: TypeAlias = Literal["xml", "rdf", "owl", "n3", "ttl", "turtle", "nt", "nq", "nquads", "trig"]
 
 
+def quad_formats() -> list[str]:
+    return ["trig", "nquads", "nq", "nt"]
+
+
 def rdflib_to_oxi_type(rdflib_format: str) -> str | None:
     """Convert an RDFlib format to a MIME type.
 

{cognite_neat-0.106.0 → cognite_neat-0.108.0}/cognite/neat/_graph/extractors/__init__.py

@@ -1,6 +1,6 @@
 from cognite.neat._session.engine._interface import Extractor as EngineExtractor
 
-from ._base import BaseExtractor
+from ._base import BaseExtractor, KnowledgeGraphExtractor
 from ._classic_cdf._assets import AssetsExtractor
 from ._classic_cdf._classic import ClassicGraphExtractor
 from ._classic_cdf._data_sets import DataSetExtractor
@@ -12,6 +12,7 @@ from ._classic_cdf._sequences import SequencesExtractor
 from ._classic_cdf._timeseries import TimeSeriesExtractor
 from ._dexpi import DexpiExtractor
 from ._dms import DMSExtractor
+from ._dms_graph import DMSGraphExtractor
 from ._iodd import IODDExtractor
 from ._mock_graph_generator import MockGraphGenerator
 from ._rdf_file import RdfFileExtractor
@@ -21,11 +22,13 @@ __all__ = [
     "BaseExtractor",
     "ClassicGraphExtractor",
     "DMSExtractor",
+    "DMSGraphExtractor",
     "DataSetExtractor",
     "DexpiExtractor",
     "EventsExtractor",
     "FilesExtractor",
     "IODDExtractor",
+    "KnowledgeGraphExtractor",
     "LabelsExtractor",
     "MockGraphGenerator",
     "RdfFileExtractor",
@@ -51,6 +54,7 @@ TripleExtractors = (
     | ClassicGraphExtractor
     | DataSetExtractor
     | EngineExtractor
+    | DMSGraphExtractor
 )
 
 

cognite_neat-0.108.0/cognite/neat/_graph/extractors/_base.py

@@ -0,0 +1,58 @@
+from abc import abstractmethod
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+from rdflib import URIRef
+
+from cognite.neat._constants import DEFAULT_NAMESPACE
+from cognite.neat._rules.models import InformationRules
+from cognite.neat._shared import Triple
+from cognite.neat._utils.auxiliary import class_html_doc
+
+if TYPE_CHECKING:
+    from cognite.neat._store._provenance import Agent as ProvenanceAgent
+
+
+class BaseExtractor:
+    """This is the base class for all extractors. It defines the interface that
+    extractors must implement.
+    """
+
+    def _get_activity_names(self) -> list[str]:
+        """Returns the name of the activities that the extractor performs,
+        i.e., the actions that it performs when you call extract().."""
+        # This method can be overridden by subclasses that runs multiple extractors
+        # for example the ClassicGraphExtractor
+        return [type(self).__name__]
+
+    @abstractmethod
+    def extract(self) -> Iterable[Triple]:
+        raise NotImplementedError()
+
+    @classmethod
+    def _repr_html_(cls) -> str:
+        return class_html_doc(cls)
+
+
+class KnowledgeGraphExtractor(BaseExtractor):
+    """A knowledge graph extractor extracts triples with a schema"""
+
+    @abstractmethod
+    def get_information_rules(self) -> InformationRules:
+        """Returns the information rules that the extractor uses."""
+        raise NotImplementedError()
+
+    @property
+    def description(self) -> str:
+        return self.__doc__.strip().split("\n")[0] if self.__doc__ else "Missing"
+
+    @property
+    def source_uri(self) -> URIRef:
+        raise NotImplementedError
+
+    @property
+    def agent(self) -> "ProvenanceAgent":
+        """Provenance agent for the importer."""
+        from cognite.neat._store._provenance import Agent as ProvenanceAgent
+
+        return ProvenanceAgent(id_=DEFAULT_NAMESPACE[f"agent/{type(self).__name__}"])

{cognite_neat-0.106.0 → cognite_neat-0.108.0}/cognite/neat/_graph/extractors/_classic_cdf/_base.py

@@ -1,6 +1,8 @@
 import json
 import re
 import sys
+import typing
+import urllib.parse
 import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterable, Sequence, Set
@@ -16,7 +18,8 @@ from rdflib import RDF, XSD, Literal, Namespace, URIRef
 
 from cognite.neat._constants import DEFAULT_NAMESPACE
 from cognite.neat._graph.extractors._base import BaseExtractor
-from cognite.neat._issues.warnings import CDFAuthWarning
+from cognite.neat._issues.errors import NeatValueError
+from cognite.neat._issues.warnings import CDFAuthWarning, NeatValueWarning
 from cognite.neat._shared import Triple
 from cognite.neat._utils.auxiliary import string_to_ideal_type
 from cognite.neat._utils.collection_ import iterate_progress_bar_if_above_config_threshold
@@ -72,6 +75,8 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         camel_case (bool, optional): Whether to use camelCase instead of snake_case for property names.
             Defaults to True.
         as_write (bool, optional): Whether to use the write/request format of the items. Defaults to False.
+        prefix (str, optional): A prefix to add to the rdf type. Defaults to None.
+        identifier (Literal["id", "externalId"], optional): The identifier to use. Defaults to "id".
     """
 
     _default_rdf_type: str
@@ -89,6 +94,8 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         skip_metadata_values: Set[str] | None = DEFAULT_SKIP_METADATA_VALUES,
         camel_case: bool = True,
         as_write: bool = False,
+        prefix: str | None = None,
+        identifier: typing.Literal["id", "externalId"] = "id",
     ):
         self.namespace = namespace or DEFAULT_NAMESPACE
         self.items = items
@@ -99,9 +106,19 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         self.skip_metadata_values = skip_metadata_values
         self.camel_case = camel_case
         self.as_write = as_write
+        self.prefix = prefix
+        self.identifier = identifier
+        # If identifier=externalId, we need to keep track of the external ids
+        # and use them in linking of Files, Sequences, TimeSeries, and Events.
+        self.asset_external_ids_by_id: dict[int, str] = {}
+        self.lookup_dataset_external_id: Callable[[int], str] | None = None
+        # Used by the ClassicGraphExtractor to log URIRefs
+        self._log_urirefs = False
+        self._uriref_by_external_id: dict[str, URIRef] = {}
 
     def extract(self) -> Iterable[Triple]:
         """Extracts an asset with the given asset_id."""
+        from ._assets import AssetsExtractor
 
         if self.total is not None and self.total > 0:
             to_iterate = iterate_progress_bar_if_above_config_threshold(
@@ -109,21 +126,40 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
             )
         else:
             to_iterate = self.items
+        if self.identifier == "externalId" and isinstance(self, AssetsExtractor):
+            to_iterate = self._store_asset_external_ids(to_iterate)  # type: ignore[attr-defined]
+
         for no, asset in enumerate(to_iterate):
             yield from self._item2triples(asset)
             if self.limit and no >= self.limit:
                 break
 
+    def _store_asset_external_ids(self, items: Iterable[T_CogniteResource]) -> Iterable[T_CogniteResource]:
+        for item in items:
+            if hasattr(item, "id") and hasattr(item, "external_id"):
+                self.asset_external_ids_by_id[item.id] = item.external_id
+            yield item
+
     def _item2triples(self, item: T_CogniteResource) -> list[Triple]:
-        id_value: str | None
-        if hasattr(item, "id"):
-            id_value = str(item.id)
+        if self.identifier == "id":
+            id_value: str | None
+            if hasattr(item, "id"):
+                id_value = str(item.id)
+            else:
+                id_value = self._fallback_id(item)
+            if id_value is None:
+                return []
+            id_suffix = id_value
+        elif self.identifier == "externalId":
+            if not hasattr(item, "external_id"):
+                return []
+            id_suffix = self._external_id_as_uri_suffix(item.external_id)
         else:
-            id_value = self._fallback_id(item)
-        if id_value is None:
-            return []
+            raise NeatValueError(f"Unknown identifier {self.identifier}")
 
-        id_ = self.namespace[f"{self._instance_id_prefix}{id_value}"]
+        id_ = self.namespace[f"{self._instance_id_prefix}{id_suffix}"]
+        if self._log_urirefs and hasattr(item, "external_id"):
+            self._uriref_by_external_id[item.external_id] = id_
 
         type_ = self._get_rdf_type(item)
 
@@ -152,10 +188,25 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         """This can be overridden to handle special cases for the item."""
         return []
 
+    @classmethod
+    def _external_id_as_uri_suffix(cls, external_id: str | None) -> str:
+        if external_id == "":
+            warnings.warn(NeatValueWarning(f"Empty external id in {cls._default_rdf_type}"), stacklevel=2)
+            return "empty"
+        elif external_id == "\x00":
+            warnings.warn(NeatValueWarning(f"Null external id in {cls._default_rdf_type}"), stacklevel=2)
+            return "null"
+        elif external_id is None:
+            warnings.warn(NeatValueWarning(f"None external id in {cls._default_rdf_type}"), stacklevel=2)
+            return "None"
+        # The external ID needs to pass the ^[^\\x00]{1,256}$ regex for the DMS API.
+        # In addition, neat internals requires the external ID to be a valid URI.
+        return urllib.parse.quote(external_id)
+
     def _fallback_id(self, item: T_CogniteResource) -> str | None:
         raise AttributeError(
             f"Item of type {type(item)} does not have an id attribute. "
-            f"Please implement the _fallback_id method in the extractor."
+            "Please implement the _fallback_id method in the extractor."
         )
 
     def _metadata_to_triples(self, id_: URIRef, metadata: dict[str, str]) -> Iterable[Triple]:
@@ -174,13 +225,34 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         type_ = self._default_rdf_type
         if self.to_type:
             type_ = self.to_type(item) or type_
+        if self.prefix:
+            type_ = f"{self.prefix}{type_}"
         return self._SPACE_PATTERN.sub("_", type_)
 
     def _as_object(self, raw: Any, key: str) -> Literal | URIRef:
+        """Return properly formatted object part of s-p-o triple"""
         if key in {"data_set_id", "dataSetId"}:
-            return self.namespace[f"{InstanceIdPrefix.data_set}{raw}"]
+            if self.identifier == "externalId" and self.lookup_dataset_external_id:
+                try:
+                    data_set_external_id = self.lookup_dataset_external_id(raw)
+                except KeyError:
+                    return Literal("Unknown data set")
+                else:
+                    return self.namespace[
+                        f"{InstanceIdPrefix.data_set}{self._external_id_as_uri_suffix(data_set_external_id)}"
+                    ]
+            else:
+                return self.namespace[f"{InstanceIdPrefix.data_set}{raw}"]
         elif key in {"assetId", "asset_id", "assetIds", "asset_ids", "parentId", "rootId", "parent_id", "root_id"}:
-            return self.namespace[f"{InstanceIdPrefix.asset}{raw}"]
+            if self.identifier == "id":
+                return self.namespace[f"{InstanceIdPrefix.asset}{raw}"]
+            else:
+                try:
+                    asset_external_id = self._external_id_as_uri_suffix(self.asset_external_ids_by_id[raw])
+                except KeyError:
+                    return Literal("Unknown asset", datatype=XSD.string)
+                else:
+                    return self.namespace[f"{InstanceIdPrefix.asset}{asset_external_id}"]
         elif key in {
             "startTime",
             "endTime",
@@ -218,9 +290,23 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         skip_metadata_values: Set[str] | None = DEFAULT_SKIP_METADATA_VALUES,
         camel_case: bool = True,
         as_write: bool = False,
+        prefix: str | None = None,
+        identifier: typing.Literal["id", "externalId"] = "id",
     ):
         total, items = cls._handle_no_access(lambda: cls._from_dataset(client, data_set_external_id))
-        return cls(items, namespace, to_type, total, limit, unpack_metadata, skip_metadata_values, camel_case, as_write)
+        return cls(
+            items,
+            namespace,
+            to_type,
+            total,
+            limit,
+            unpack_metadata,
+            skip_metadata_values,
+            camel_case,
+            as_write,
+            prefix,
+            identifier,
+        )
 
     @classmethod
     @abstractmethod
@@ -241,9 +327,23 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         skip_metadata_values: Set[str] | None = DEFAULT_SKIP_METADATA_VALUES,
         camel_case: bool = True,
         as_write: bool = False,
+        prefix: str | None = None,
+        identifier: typing.Literal["id", "externalId"] = "id",
     ):
         total, items = cls._handle_no_access(lambda: cls._from_hierarchy(client, root_asset_external_id))
-        return cls(items, namespace, to_type, total, limit, unpack_metadata, skip_metadata_values, camel_case, as_write)
+        return cls(
+            items,
+            namespace,
+            to_type,
+            total,
+            limit,
+            unpack_metadata,
+            skip_metadata_values,
+            camel_case,
+            as_write,
+            prefix,
+            identifier,
+        )
 
     @classmethod
     @abstractmethod
@@ -263,9 +363,23 @@ class ClassicCDFBaseExtractor(BaseExtractor, ABC, Generic[T_CogniteResource]):
         skip_metadata_values: Set[str] | None = DEFAULT_SKIP_METADATA_VALUES,
         camel_case: bool = True,
         as_write: bool = False,
+        prefix: str | None = None,
+        identifier: typing.Literal["id", "externalId"] = "id",
     ):
         total, items = cls._from_file(file_path)
-        return cls(items, namespace, to_type, total, limit, unpack_metadata, skip_metadata_values, camel_case, as_write)
+        return cls(
+            items,
+            namespace,
+            to_type,
+            total,
+            limit,
+            unpack_metadata,
+            skip_metadata_values,
+            camel_case,
+            as_write,
+            prefix,
+            identifier,
+        )
 
     @classmethod
     @abstractmethod