cognite-neat 0.123.42__py3-none-any.whl → 0.124.0__py3-none-any.whl

cognite/neat/_data_model/models/conceptual/_data_model.py

@@ -0,0 +1,51 @@
+from collections import Counter
+
+from pydantic import Field, ValidationInfo, field_validator
+
+from cognite.neat._data_model.models.entities._constants import PREFIX_PATTERN, SUFFIX_PATTERN, VERSION_PATTERN
+from cognite.neat._utils.text import humanize_collection
+from cognite.neat.v0.core._data_model.models.entities._single_value import ConceptEntity
+
+from ._base import ResourceMetadata
+from ._concept import Concept
+
+
+class DataModel(ResourceMetadata):
+    space: str = Field(
+        description="Id of the space that the concept belongs to.",
+        min_length=1,
+        max_length=43,
+        pattern=PREFIX_PATTERN,
+        alias="prefix",
+    )
+    external_id: str = Field(
+        description="External-id of the concept.",
+        min_length=1,
+        max_length=255,
+        pattern=SUFFIX_PATTERN,
+        alias="suffix",
+    )
+    version: str = Field(
+        description="Version of the concept.",
+        max_length=43,
+        pattern=VERSION_PATTERN,
+    )
+
+    concepts: list[Concept] = Field(
+        description="References to the concepts from where this concept will inherit properties.",
+    )
+
+    @field_validator("concepts", mode="after")
+    def cannot_have_duplicates(cls, value: list[Concept], info: ValidationInfo) -> list[Concept]:
+        concept_ids = [
+            ConceptEntity(prefix=concept.space, suffix=concept.external_id, version=concept.version)
+            for concept in value
+        ]
+
+        counts = Counter(concept_ids)
+        duplicates = {concept for concept, count in counts.items() if count > 1}
+
+        if duplicates:
+            raise ValueError(f"Duplicate concepts found: {humanize_collection(duplicates)}")
+
+        return value

cognite/neat/_data_model/models/conceptual/_property.py

@@ -78,11 +78,12 @@ class Property(ResourceMetadata):
             return value
 
         max_count = info.data.get("max_count")
+        min_count = info.data.get("min_count")
 
-        if max_count is None or max_count > 1:
+        if max_count is None or max_count > 1 or (min_count and min_count > 1):
             raise ValueError(
                 "Setting default value is only supported for single-valued properties."
-                f" Property has max_count={max_count or 'Inf'}."
+                f" Property has min_count={info.data.get('min_count')} and max_count={info.data.get('max_count')}."
             )
         return value
 

cognite/neat/_data_model/models/dms/__init__.py

@@ -1,6 +1,7 @@
 from cognite.neat._data_model.models.dms._base import Resource, WriteableResource
 from cognite.neat._data_model.models.dms._constraints import (
     Constraint,
+    ConstraintAdapter,
     ConstraintDefinition,
     RequiresConstraintDefinition,
     UniquenessConstraintDefinition,
@@ -14,10 +15,14 @@ from cognite.neat._data_model.models.dms._container import (
 from cognite.neat._data_model.models.dms._data_types import (
     BooleanProperty,
     DataType,
+    DataTypeAdapter,
     DateProperty,
     DirectNodeRelation,
     EnumProperty,
+    EnumValue,
     FileCDFExternalIdReference,
+    Float32Property,
+    Float64Property,
     FloatProperty,
     Int32Property,
     Int64Property,
@@ -29,7 +34,7 @@ from cognite.neat._data_model.models.dms._data_types import (
     TimeseriesCDFExternalIdReference,
     TimestampProperty,
 )
-from cognite.neat._data_model.models.dms._indexes import BtreeIndex, Index, IndexDefinition, InvertedIndex
+from cognite.neat._data_model.models.dms._indexes import BtreeIndex, Index, IndexAdapter, IndexDefinition, InvertedIndex
 from cognite.neat._data_model.models.dms._space import Space, SpaceRequest, SpaceResponse
 
 from ._data_model import DataModelRequest, DataModelResponse
@@ -68,6 +73,7 @@ __all__ = [
     "BtreeIndex",
     "ConnectionPropertyDefinition",
     "Constraint",
+    "ConstraintAdapter",
     "ConstraintDefinition",
     "ConstraintOrIndexState",
     "Container",
@@ -80,12 +86,17 @@ __all__ = [
     "DataModelRequest",
     "DataModelResponse",
     "DataType",
+    "DataTypeAdapter",
     "DateProperty",
     "DirectNodeRelation",
     "EnumProperty",
+    "EnumValue",
     "FileCDFExternalIdReference",
+    "Float32Property",
+    "Float64Property",
     "FloatProperty",
     "Index",
+    "IndexAdapter",
     "IndexDefinition",
     "Int32Property",
     "Int64Property",

cognite/neat/_data_model/models/dms/_base.py

@@ -20,7 +20,7 @@ class Resource(BaseModelObject):
 T_Resource = TypeVar("T_Resource", bound=Resource)
 
 
-class WriteableResource(Generic[T_Resource], Resource, ABC):
+class WriteableResource(Resource, Generic[T_Resource], ABC):
     @abstractmethod
     def as_request(self) -> T_Resource:
         """Convert the response model to a request model by removing read-only fields."""

cognite/neat/_data_model/models/dms/_constraints.py

@@ -1,10 +1,11 @@
 from abc import ABC
 from typing import Annotated, Literal
 
-from pydantic import Field
+from pydantic import Field, TypeAdapter
 
 from ._base import BaseModelObject
 from ._references import ContainerReference
+from ._types import Bool
 
 
 class ConstraintDefinition(BaseModelObject, ABC):
@@ -16,7 +17,7 @@ class UniquenessConstraintDefinition(ConstraintDefinition):
     properties: list[str] = Field(
         description="List of properties included in the constraint.", min_length=1, max_length=10
     )
-    by_space: bool | None = Field(default=None, description="Whether to make the constraint space-specific.")
+    by_space: Bool | None = Field(default=None, description="Whether to make the constraint space-specific.")
 
 
 class RequiresConstraintDefinition(ConstraintDefinition):
@@ -28,3 +29,5 @@ Constraint = Annotated[
     UniquenessConstraintDefinition | RequiresConstraintDefinition,
     Field(discriminator="constraint_type"),
 ]
+
+ConstraintAdapter: TypeAdapter[Constraint] = TypeAdapter(Constraint)

cognite/neat/_data_model/models/dms/_data_types.py

@@ -1,9 +1,8 @@
+import re
 from abc import ABC
 from typing import Annotated, Literal
 
-from pydantic import Field, field_validator
-
-from cognite.neat._utils.text import humanize_collection
+from pydantic import Field, TypeAdapter, field_validator
 
 from ._base import BaseModelObject
 from ._constants import ENUM_VALUE_IDENTIFIER_PATTERN, FORBIDDEN_ENUM_VALUES, INSTANCE_ID_PATTERN
@@ -111,6 +110,7 @@ class DirectNodeRelation(ListablePropertyTypeDefinition):
 
 class EnumValue(BaseModelObject):
     name: str | None = Field(
+        None,
         max_length=255,
         description="The name of the enum value.",
     )
@@ -121,6 +121,9 @@ class EnumValue(BaseModelObject):
     )
 
 
+_ENUM_KEY = re.compile(ENUM_VALUE_IDENTIFIER_PATTERN)
+
+
 class EnumProperty(PropertyTypeDefinition):
     type: Literal["enum"] = "enum"
     unknown_value: str | None = Field(
@@ -129,22 +132,33 @@ class EnumProperty(PropertyTypeDefinition):
         "provide forward-compatibility, Specifying what value to use if the client does not "
         "recognize the returned value. It is not possible to ingest the unknown value, "
         "but it must be part of the allowed values.",
+        min_length=1,
+        max_length=128,
+        pattern=ENUM_VALUE_IDENTIFIER_PATTERN,
     )
     values: dict[str, EnumValue] = Field(
         description="A set of all possible values for the enum property.",
         min_length=1,
         max_length=32,
-        pattern=ENUM_VALUE_IDENTIFIER_PATTERN,
     )
 
     @field_validator("values", mode="after")
     def _valid_enum_value(cls, val: dict[str, EnumValue]) -> dict[str, EnumValue]:
-        invalid_enum_values = set(val.keys()).intersection(FORBIDDEN_ENUM_VALUES)
-        if invalid_enum_values:
-            raise ValueError(
-                "Enum values cannot be any of the following reserved values: "
-                f"{humanize_collection(invalid_enum_values)}"
-            )
+        errors: list[str] = []
+        for key in val.keys():
+            if not _ENUM_KEY.match(key):
+                errors.append(
+                    f"Enum value {key!r} is not valid. Enum values must match "
+                    f"the pattern: {ENUM_VALUE_IDENTIFIER_PATTERN}"
+                )
+            if len(key) > 128 or len(key) < 1:
+                errors.append(f"Enum value {key!r} must be between 1 and 128 characters long.")
+            if key.lower() in FORBIDDEN_ENUM_VALUES:
+                errors.append(
+                    f"Enum value {key!r} cannot be any of the following reserved values: {FORBIDDEN_ENUM_VALUES}"
+                )
+        if errors:
+            raise ValueError(";".join(errors))
         return val
 
 
@@ -165,3 +179,5 @@ DataType = Annotated[
     | EnumProperty,
     Field(discriminator="type"),
 ]
+
+DataTypeAdapter: TypeAdapter[DataType] = TypeAdapter(DataType)

cognite/neat/_data_model/models/dms/_indexes.py

@@ -1,9 +1,10 @@
 from abc import ABC
 from typing import Annotated, Literal
 
-from pydantic import Field
+from pydantic import Field, TypeAdapter
 
 from ._base import BaseModelObject
+from ._types import Bool
 
 
 class IndexDefinition(BaseModelObject, ABC):
@@ -13,8 +14,8 @@ class IndexDefinition(BaseModelObject, ABC):
 
 class BtreeIndex(IndexDefinition):
     index_type: Literal["btree"] = "btree"
-    by_space: bool | None = Field(default=None, description="Whether to make the index space-specific.")
-    cursorable: bool | None = Field(
+    by_space: Bool | None = Field(default=None, description="Whether to make the index space-specific.")
+    cursorable: Bool | None = Field(
         default=None, description="Whether the index can be used for cursor-based pagination."
     )
 
@@ -24,3 +25,5 @@ class InvertedIndex(IndexDefinition):
 
 
 Index = Annotated[BtreeIndex | InvertedIndex, Field(discriminator="index_type")]
+
+IndexAdapter: TypeAdapter[Index] = TypeAdapter(Index)

cognite/neat/_data_model/models/dms/_types.py

@@ -0,0 +1,17 @@
+from typing import Annotated, Any
+
+from pydantic import BeforeValidator
+
+
+def str_as_bool(value: Any) -> Any:
+    if isinstance(value, str):
+        val = value.lower()
+        if val in {"true", "1", "yes"}:
+            return True
+        if val in {"false", "0", "no"}:
+            return False
+    # All other cases are handled by Pydantic's built-in bool validator
+    return value
+
+
+Bool = Annotated[bool, BeforeValidator(str_as_bool, str)]

cognite/neat/_data_model/models/dms/_view_property.py

@@ -1,7 +1,7 @@
 from abc import ABC
 from typing import Annotated, Literal
 
-from pydantic import Field, Json
+from pydantic import Field, Json, TypeAdapter
 
 from ._base import BaseModelObject, Resource, WriteableResource
 from ._constants import CONTAINER_AND_VIEW_PROPERTIES_IDENTIFIER_PATTERN
@@ -130,53 +130,40 @@ class ReverseDirectRelationProperty(ConnectionPropertyDefinition, ABC):
         description="The node(s) containing the direct relation property can be read "
         "through the view specified in 'source'."
     )
+    through: ContainerDirectReference | ViewDirectReference = Field(
+        description="The view of the node containing the direct relation property."
+    )
 
 
 class SingleReverseDirectRelationPropertyRequest(ReverseDirectRelationProperty):
     connection_type: Literal["single_reverse_direct_relation"] = "single_reverse_direct_relation"
-    # The API support through as either ViewDirectReference or ContainerDirectReference. However, in Neat
-    # we only use ContainerDirectReference. This is for simplicity and it improves performance as the server
-    # does not have to resolve the view to a container first.
-    through: ContainerDirectReference = Field(
-        description="The view of the node containing the direct relation property."
-    )
+
+
+class MultiReverseDirectRelationPropertyRequest(ReverseDirectRelationProperty):
+    connection_type: Literal["multi_reverse_direct_relation"] = "multi_reverse_direct_relation"
 
 
 class SingleReverseDirectRelationPropertyResponse(
     ReverseDirectRelationProperty, WriteableResource[SingleReverseDirectRelationPropertyRequest]
 ):
     connection_type: Literal["single_reverse_direct_relation"] = "single_reverse_direct_relation"
-    through: ContainerDirectReference | ViewDirectReference = Field(
-        description="The view of the node containing the direct relation property."
+    target_list: bool = Field(
+        description="Whether or not this reverse direct relation targets a list of direct relations.",
     )
 
     def as_request(self) -> SingleReverseDirectRelationPropertyRequest:
-        if isinstance(self.through, ViewDirectReference):
-            raise TypeError("Cannot convert to request when 'through' is a ViewDirectReference.")
         return SingleReverseDirectRelationPropertyRequest.model_validate(self.model_dump(by_alias=True))
 
 
-class MultiReverseDirectRelationPropertyRequest(ReverseDirectRelationProperty):
-    connection_type: Literal["multi_reverse_direct_relation"] = "multi_reverse_direct_relation"
-    # The API support through as either ViewDirectReference or ContainerDirectReference. However, in Neat
-    # we only use ContainerDirectReference. This is for simplicity and it improves performance as the server
-    # does not have to resolve the view to a container first.
-    through: ContainerDirectReference = Field(
-        description="The view of the node containing the direct relation property."
-    )
-
-
 class MultiReverseDirectRelationPropertyResponse(
     ReverseDirectRelationProperty, WriteableResource[MultiReverseDirectRelationPropertyRequest]
 ):
     connection_type: Literal["multi_reverse_direct_relation"] = "multi_reverse_direct_relation"
-    through: ContainerDirectReference | ViewDirectReference = Field(
-        description="The view of the node containing the direct relation property."
+    target_list: bool = Field(
+        description="Whether or not this reverse direct relation targets a list of direct relations.",
     )
 
     def as_request(self) -> MultiReverseDirectRelationPropertyRequest:
-        if isinstance(self.through, ViewDirectReference):
-            raise TypeError("Cannot convert to request when 'through' is a ViewDirectReference.")
         return MultiReverseDirectRelationPropertyRequest.model_validate(self.model_dump(by_alias=True))
 
 
@@ -196,3 +183,5 @@ ViewResponseProperty = Annotated[
     | ViewCorePropertyResponse,
     Field(discriminator="connection_type"),
 ]
+
+ViewRequestPropertyAdapter: TypeAdapter[ViewRequestProperty] = TypeAdapter(ViewRequestProperty)

cognite/neat/_data_model/models/entities/__init__.py

@@ -19,7 +19,7 @@ from ._data_types import (
     Timeseries,
 )
 from ._identifiers import URI, NameSpace
-from ._parser import ParsedEntity, parse_entity
+from ._parser import ParsedEntity, parse_entities, parse_entity
 
 __all__ = [
     "URI",
@@ -45,5 +45,6 @@ __all__ = [
     "Undefined",
     "Unknown",
     "UnknownEntity",
+    "parse_entities",
     "parse_entity",
 ]

cognite/neat/_data_model/models/entities/_parser.py

@@ -1,4 +1,6 @@
+import re
 from dataclasses import dataclass
+from typing import Literal
 
 SPECIAL_CHARACTERS = ":()=,"
 
@@ -11,6 +13,18 @@ class ParsedEntity:
     suffix: str
     properties: dict[str, str]
 
+    def __str__(self) -> str:
+        props_str = ""
+        if self.properties:
+            joined = ",".join(f"{k}={v}" for k, v in sorted(self.properties.items(), key=lambda x: x[0]))
+            props_str = f"({joined})"
+        if self.prefix:
+            return f"{self.prefix}:{self.suffix}{props_str}"
+        return f"{self.suffix}{props_str}"
+
+    def __hash__(self) -> int:
+        return hash(str(self))
+
 
 class _EntityParser:
     """A parser for entity strings in the format 'prefix:suffix(prop1=val1,prop2=val2)'."""
@@ -192,3 +206,21 @@ def parse_entity(entity_string: str) -> ParsedEntity:
     """
     parser = _EntityParser(entity_string)
     return parser.parse()
+
+
+def parse_entities(entities_str: str, separator: Literal[","] = ",") -> list[ParsedEntity] | None:
+    """Parse a comma-separated string of entities.
+
+    Args:
+        entities_str: A comma-separated string of entities.
+        separator: The separator used to split entities.
+        A list of `ParsedEntity` objects or None if the input string is empty.
+    """
+    if not entities_str.strip():
+        return None
+    if separator != ",":
+        raise ValueError("Only ',' is supported as a separator currently.")
+    # Regex to split on the separator but ignore separators within parentheses
+    pattern = rf"{separator}(?![^()]*\))"
+    parts = re.split(pattern, entities_str)
+    return [parse_entity(part.strip()) for part in parts if part.strip()]

cognite/neat/_session/_session.py

@@ -0,0 +1,33 @@
+from ._state_machine import EmptyState, ForbiddenState, State
+
+
+class NeatSession:
+    """A session is an interface for neat operations. It works as
+    a manager for handling user interactions and orchestrating
+    the state machine for data model and instance operations.
+    """
+
+    def __init__(self) -> None:
+        self.state: State = EmptyState()
+
+    def _execute_event(self, event: str) -> bool:
+        """Place holder function for executing events and transitioning states.
+        It will be modified to include actual logic as we progress with v1 of neat.
+
+        """
+        print(f"\n--- Executing event: '{event}' from {self.state} ---")
+
+        old_state = self.state
+        new_state = self.state.on_event(event)
+
+        # Handle ForbiddenState
+        if isinstance(new_state, ForbiddenState):
+            print(f"❌ Event '{event}' is FORBIDDEN from {old_state}")
+            # Return to previous state (as per your table logic)
+            self.state = new_state.on_event("undo")
+            print(f"↩️  Returned to: {self.state}")
+            return False
+        else:
+            self.state = new_state
+            print(f"✅ Transition successful: {old_state} → {self.state}")
+            return True

cognite/neat/_session/_state_machine/__init__.py

@@ -0,0 +1,23 @@
+from ._base import State
+from ._states import (
+    ConceptualPhysicalState,
+    ConceptualState,
+    EmptyState,
+    ForbiddenState,
+    InstancesConceptualPhysicalState,
+    InstancesConceptualState,
+    InstancesState,
+    PhysicalState,
+)
+
+__all__ = [
+    "ConceptualPhysicalState",
+    "ConceptualState",
+    "EmptyState",
+    "ForbiddenState",
+    "InstancesConceptualPhysicalState",
+    "InstancesConceptualState",
+    "InstancesState",
+    "PhysicalState",
+    "State",
+]

cognite/neat/_session/_state_machine/_base.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+
+
+class State(ABC):
+    def __init__(self) -> None:
+        # this will be reference to the actual store in the session
+        # used to store data models and instances, here only as a placeholder
+        self._store = None
+
+    @abstractmethod
+    def on_event(self, event: str) -> "State":
+        """
+        Handle events that are delegated to this State.
+        """
+        raise NotImplementedError("on_event() must be implemented by the subclass.")
+
+    def __repr__(self) -> str:
+        """
+        Leverages the __str__ method to describe the State.
+        """
+        return self.__str__()
+
+    def __str__(self) -> str:
+        """
+        Returns the name of the State.
+        """
+        return self.__class__.__name__

cognite/neat/_session/_state_machine/_states.py

@@ -0,0 +1,150 @@
+from ._base import State
+
+
+class EmptyState(State):
+    """
+    The initial state with empty NEAT store.
+    """
+
+    def on_event(self, event: str) -> State:
+        if event == "read_instances":
+            return InstancesState()
+        elif event == "read_conceptual":
+            return ConceptualState()
+        elif event == "read_physical":
+            return PhysicalState()
+
+        return ForbiddenState(self)
+
+
+class InstancesState(State):
+    """
+    State with instances loaded to the store.
+    """
+
+    def on_event(self, event: str) -> State:
+        # One can keep on reading instances to stay in the same state
+        if event == "read_instances":
+            return InstancesState()
+        # We either read conceptual model or infer it from instances
+        # if read conceptual, we need to make sure that conceptual model is compatible with instances
+        elif event in ["infer_conceptual", "read_conceptual"]:
+            return InstancesConceptualState()
+
+        # transforming instances keeps us in the same state
+        elif event == "transform_instances":
+            return InstancesState()
+        # we should allow writing out instances in RDF format but not to CDF
+        elif event == "write_instances":
+            return InstancesState()
+
+        # all other operations are forbidden
+        return ForbiddenState(self)
+
+
+class ConceptualState(State):
+    """
+    State with conceptual model loaded.
+    """
+
+    def on_event(self, event: str) -> State:
+        # re-reading of model means transformation of
+        # the current model has been done outside of NeatSession
+        # requires checking that the new model is compatible with the existing
+        if event == "read_conceptual":
+            return ConceptualState()
+
+        # when reading: requires linking between models
+        # when converting: links are automatically created
+        elif event == "read_physical" or event == "convert_to_physical":
+            return ConceptualPhysicalState()
+        elif event == "transform_conceptual":
+            return ConceptualState()
+        elif event == "write_conceptual":
+            return ConceptualState()
+
+        return ForbiddenState(self)
+
+
+class PhysicalState(State):
+    """
+    State with physical model loaded.
+    """
+
+    def on_event(self, event: str) -> State:
+        if event == "read_physical":
+            return PhysicalState()
+        elif event == "transform_physical":
+            return PhysicalState()
+        elif event == "write_physical":
+            return PhysicalState()
+        elif event == "convert_to_conceptual" or event == "read_conceptual":
+            return ConceptualPhysicalState()
+
+        return ForbiddenState(self)
+
+
+class InstancesConceptualState(State):
+    """
+    State with both instances and conceptual model loaded.
+    """
+
+    def on_event(self, event: str) -> State:
+        if event == "read_conceptual":
+            return InstancesConceptualState()
+        elif event == "transform_conceptual":
+            return InstancesConceptualState()
+        elif event in ["write_instances", "write_conceptual"]:
+            return InstancesConceptualState()
+        elif event in ["read_physical", "convert_to_physical"]:
+            return InstancesConceptualPhysicalState()
+
+        return ForbiddenState(self)
+
+
+class ConceptualPhysicalState(State):
+    """
+    State with both conceptual and physical models loaded.
+    """
+
+    def on_event(self, event: str) -> State:
+        if event == "read_physical":
+            return ConceptualPhysicalState()
+        elif event == "transform_physical":
+            return ConceptualPhysicalState()
+        elif event in ["write_conceptual", "write_physical"]:
+            return ConceptualPhysicalState()
+
+        return ForbiddenState(self)
+
+
+class InstancesConceptualPhysicalState(State):
+    """
+    State with instances, conceptual, and physical models loaded.
+    """
+
+    def on_event(self, event: str) -> State:
+        if event == "read_physical":
+            return InstancesConceptualPhysicalState()
+        elif event == "transform_physical":
+            return InstancesConceptualPhysicalState()
+        elif event in ["write_instances", "write_conceptual", "write_physical"]:
+            return InstancesConceptualPhysicalState()
+
+        return ForbiddenState(self)
+
+
+class ForbiddenState(State):
+    """
+    State representing forbidden transitions - returns to previous state.
+    """
+
+    def __init__(self, previous_state: State):
+        self.previous_state = previous_state
+        print(f"Forbidden action attempted. Returning to previous state: {previous_state}")
+
+    def on_event(self, event: str) -> State:
+        # only "undo" to trigger going back to previous state
+        if event.strip().lower() == "undo":
+            return self.previous_state
+        return self

cognite/neat/_utils/validation.py

@@ -1,23 +1,63 @@
+from collections.abc import Callable, Mapping
+from typing import Literal
+
 from pydantic import ValidationError
 from pydantic_core import ErrorDetails
 
 
-def humanize_validation_error(error: ValidationError) -> list[str]:
+def as_json_path(loc: tuple[str | int, ...]) -> str:
+    """Converts a location tuple to a JSON path.
+
+    Args:
+        loc: The location tuple to convert.
+
+    Returns:
+        A JSON path string.
+    """
+    if not loc:
+        return ""
+    # +1 to convert from 0-based to 1-based indexing
+    prefix = ""
+    if isinstance(loc[0], int):
+        prefix = "item"
+
+    suffix = ".".join([str(x) if isinstance(x, str) else f"[{x + 1}]" for x in loc]).replace(".[", "[")
+    return f"{prefix}{suffix}"
+
+
+def humanize_validation_error(
+    error: ValidationError,
+    parent_loc: tuple[int | str, ...] = tuple(),
+    humanize_location: Callable[[tuple[int | str, ...]], str] = as_json_path,
+    field_name: Literal["field", "column", "value"] = "field",
+    field_renaming: Mapping[str, str] | None = None,
+) -> list[str]:
     """Converts a ValidationError to a human-readable format.
 
     This overwrites the default error messages from Pydantic to be better suited for Toolkit users.
 
     Args:
         error: The ValidationError to convert.
-
+        parent_loc: Optional location tuple to prepend to each error location.
+            This is useful when the error is for a nested model and you want to include the location
+            of the parent model.
+        humanize_location: A function that converts a location tuple to a human-readable string.
+            The default is `as_json_path`, which converts the location to a JSON path.
+            This can for example be replaced when the location comes from an Excel table.
+        field_name: The name use for "field" in error messages. Default is "field". This can be changed to
+            "column" or "value" to better fit the context.
+        field_renaming: Optional mapping of field names to source names.
+            This is useful when the field names in the model are different from the names in the source.
+            For example, if the model field is "asset_id" but the source column is "Asset ID",
+            you can provide a mapping {"asset_id": "Asset ID"} to have the error messages use the source names.
     Returns:
         A list of human-readable error messages.
     """
     errors: list[str] = []
     item: ErrorDetails
-
+    field_renaming = field_renaming or {}
     for item in error.errors(include_input=True, include_url=False):
-        loc = item["loc"]
+        loc = (*parent_loc, *item["loc"])
         error_type = item["type"]
         if error_type == "missing":
             msg = f"Missing required field: {loc[-1]!r}"
@@ -50,32 +90,22 @@ def humanize_validation_error(error: ValidationError) -> list[str]:
             #  This is hard to read, so we simplify it to just the field name.
             loc = tuple(["dict" if isinstance(x, str) and "json-or-python" in x else x for x in loc])
 
+        error_suffix = f"{msg[:1].casefold()}{msg[1:]}"
         if len(loc) > 1 and error_type in {"extra_forbidden", "missing"}:
-            # We skip the last element as this is in the message already
-            msg = f"In {as_json_path(loc[:-1])} {msg[:1].casefold()}{msg[1:]}"
+            if field_name == "column":
+                # This is a table so we modify the error message.
+                msg = (
+                    f"In {humanize_location(loc[:-1])} the column {field_renaming.get(str(loc[-1]), loc[-1])!r} "
+                    "cannot be empty."
+                )
+            else:
+                # We skip the last element as this is in the message already
+                msg = f"In {humanize_location(loc[:-1])} {error_suffix.replace('field', field_name)}"
         elif len(loc) > 1:
-            msg = f"In {as_json_path(loc)} {msg[:1].casefold()}{msg[1:]}"
+            msg = f"In {humanize_location(loc)} {error_suffix}"
         elif len(loc) == 1 and isinstance(loc[0], str) and error_type not in {"extra_forbidden", "missing"}:
-            msg = f"In field {loc[0]} {msg[:1].casefold()}{msg[1:]}"
+            msg = f"In {field_name} {loc[0]!r}, {error_suffix}"
+        if not msg.endswith("."):
+            msg += "."
         errors.append(msg)
     return errors
-
-
-def as_json_path(loc: tuple[str | int, ...]) -> str:
-    """Converts a location tuple to a JSON path.
-
-    Args:
-        loc: The location tuple to convert.
-
-    Returns:
-        A JSON path string.
-    """
-    if not loc:
-        return ""
-    # +1 to convert from 0-based to 1-based indexing
-    prefix = ""
-    if isinstance(loc[0], int):
-        prefix = "item "
-
-    suffix = ".".join([str(x) if isinstance(x, str) else f"[{x + 1}]" for x in loc]).replace(".[", "[")
-    return f"{prefix}{suffix}"

cognite/neat/_version.py

@@ -1,2 +1,2 @@
-__version__ = "0.123.42"
+__version__ = "0.124.0"
 __engine__ = "^2.0.4"

cognite/neat/v0/core/_store/_instance.py

@@ -12,6 +12,7 @@ from rdflib import Dataset, Graph, Namespace, URIRef
 from rdflib.graph import DATASET_DEFAULT_GRAPH_ID
 from rdflib.plugins.stores.sparqlstore import SPARQLUpdateStore
 
+from cognite.neat.v0.core._constants import NAMED_GRAPH_NAMESPACE
 from cognite.neat.v0.core._instances._shared import quad_formats, rdflib_to_oxi_type
 from cognite.neat.v0.core._instances.extractors import RdfFileExtractor, TripleExtractors
 from cognite.neat.v0.core._instances.queries import Queries
@@ -450,3 +451,35 @@ class NeatInstanceStore:
     def empty(self) -> bool:
         """Cheap way to check if the graph store is empty."""
         return not self.queries.select.has_data()
+
+    def diff(self, current_named_graph: URIRef, new_named_graph: URIRef) -> None:
+        """
+        Compare two named graphs and store diff results in dedicated named graphs.
+
+        Stores triples to add in DIFF_ADD and triples to delete in DIFF_DELETE.
+
+        Args:
+            current_named_graph: URI of the current named graph
+            new_named_graph: URI of the new/updated named graph
+
+        Raises:
+            NeatValueError: If either named graph doesn't exist in the store
+        """
+        if current_named_graph not in self.named_graphs:
+            raise NeatValueError(f"Current named graph not found: {current_named_graph}")
+        if new_named_graph not in self.named_graphs:
+            raise NeatValueError(f"New named graph not found: {new_named_graph}")
+
+        # Clear previous diff results using SPARQL
+        self.dataset.update(f"CLEAR SILENT GRAPH <{NAMED_GRAPH_NAMESPACE['DIFF_ADD']}>")
+        self.dataset.update(f"CLEAR SILENT GRAPH <{NAMED_GRAPH_NAMESPACE['DIFF_DELETE']}>")
+
+        # Store new diff results
+        self._add_triples(
+            self.queries.select.get_triples_to_add(current_named_graph, new_named_graph),
+            named_graph=NAMED_GRAPH_NAMESPACE["DIFF_ADD"],
+        )
+        self._add_triples(
+            self.queries.select.get_triples_to_delete(current_named_graph, new_named_graph),
+            named_graph=NAMED_GRAPH_NAMESPACE["DIFF_DELETE"],
+        )

cognite/neat/v0/session/_base.py

@@ -25,6 +25,7 @@ from cognite.neat.v0.core._store._data_model import DataModelEntity
 from cognite.neat.v0.core._utils.auxiliary import local_import
 
 from ._collector import _COLLECTOR, Collector
+from ._diff import DiffAPI
 from ._drop import DropAPI
 from ._explore import ExploreAPI
 from ._fix import FixAPI
@@ -110,6 +111,7 @@ class NeatSession:
         self.template = TemplateAPI(self._state)
         self._explore = ExploreAPI(self._state)
         self.plugins = PluginAPI(self._state)
+        self._diff = DiffAPI(self._state)
         self.opt = OptAPI()
         self.opt._display()
         if load_engine != "skip" and (engine_version := load_neat_engine(client, load_engine)):

cognite/neat/v0/session/_diff.py

@@ -0,0 +1,51 @@
+from typing import cast
+
+from rdflib.query import ResultRow
+
+from cognite.neat.v0.core._constants import NAMED_GRAPH_NAMESPACE
+
+from ._state import SessionState
+
+
+class DiffAPI:
+    """Compare RDF graphs (private API)."""
+
+    def __init__(self, state: SessionState) -> None:
+        self._state = state
+
+    def instances(self, current_named_graph: str, new_named_graph: str) -> None:
+        """
+        Compare two named graphs and store diff results.
+
+        Results stored in DIFF_ADD and DIFF_DELETE named graphs.
+
+        Args:
+            current_named_graph: Name of the current graph (e.g., "CURRENT")
+            new_named_graph: Name of the new graph (e.g., "NEW")
+        """
+        current_uri = NAMED_GRAPH_NAMESPACE[current_named_graph]
+        new_uri = NAMED_GRAPH_NAMESPACE[new_named_graph]
+
+        self._state.instances.store.diff(current_uri, new_uri)
+        self._print_summary()
+
+    def _print_summary(self) -> None:
+        """Print diff summary with triple counts."""
+        store = self._state.instances.store
+
+        add_query = (
+            f"SELECT (COUNT(*) as ?count) WHERE {{ GRAPH <{NAMED_GRAPH_NAMESPACE['DIFF_ADD']}> {{ ?s ?p ?o }} }}"
+        )
+        delete_query = (
+            f"SELECT (COUNT(*) as ?count) WHERE {{ GRAPH <{NAMED_GRAPH_NAMESPACE['DIFF_DELETE']}> {{ ?s ?p ?o }} }}"
+        )
+
+        add_result = cast(ResultRow, next(iter(store.dataset.query(add_query))))
+        delete_result = cast(ResultRow, next(iter(store.dataset.query(delete_query))))
+
+        add_count = int(add_result[0])
+        delete_count = int(delete_result[0])
+
+        print("Diff complete:")
+        print(f"  {add_count} triples to add (stored in DIFF_ADD)")
+        print(f"  {delete_count} triples to delete (stored in DIFF_DELETE)")

{cognite_neat-0.123.42.dist-info → cognite_neat-0.124.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognite-neat
-Version: 0.123.42
+Version: 0.124.0
 Summary: Knowledge graph transformation
 Project-URL: Documentation, https://cognite-neat.readthedocs-hosted.com/
 Project-URL: Homepage, https://cognite-neat.readthedocs-hosted.com/

{cognite_neat-0.123.42.dist-info → cognite_neat-0.124.0.dist-info}/RECORD

@@ -1,6 +1,6 @@
 cognite/neat/__init__.py,sha256=Lo4DbjDOwnhCYUoAgPp5RG1fDdF7OlnomalTe7n1ydw,211
 cognite/neat/_issues.py,sha256=uv0fkkWwTKqNmTmHqyoBB3L6yMCh42EZpEkLGmIJYOY,812
-cognite/neat/_version.py,sha256=KPC_vMI9YJae3HbWzCydHnx-9mFGFnywrlkj0xH-U6U,47
+cognite/neat/_version.py,sha256=0GwMYSFb5nGMLM9dHslSjNFrEuvigs26DxXB6nxHwqk,46
 cognite/neat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/_data_model/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/_data_model/_constants.py,sha256=NGGvWHlQqhkkSBP_AqoofGYjNph3SiZX6QPINlMsy04,107
@@ -11,32 +11,39 @@ cognite/neat/_data_model/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm
 cognite/neat/_data_model/models/conceptual/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/_data_model/models/conceptual/_base.py,sha256=SFkoBJDM51pqew_isHFJoB20OgfofpwVRnTrg-rKkNY,710
 cognite/neat/_data_model/models/conceptual/_concept.py,sha256=0Pk4W2TJ_Y0Z7oPHpzely1kPXrAkmkyqw6a0n3il6LY,2248
+cognite/neat/_data_model/models/conceptual/_data_model.py,sha256=mSX0z8i29ufcRUhvC_NPeo2xGidlK3B1n89kngY_SqQ,1695
 cognite/neat/_data_model/models/conceptual/_properties.py,sha256=CpF37vJYBTLT4DH4ZOu2U-JyWtkb_27V8fw52qiaE_k,4007
-cognite/neat/_data_model/models/conceptual/_property.py,sha256=CpF37vJYBTLT4DH4ZOu2U-JyWtkb_27V8fw52qiaE_k,4007
-cognite/neat/_data_model/models/dms/__init__.py,sha256=I_yw2GoEjUdLk8VOiLSlU4BWgE3u_GgCHJayeEa1w1w,3583
-cognite/neat/_data_model/models/dms/_base.py,sha256=R8SP3Zi9daTBqewYKGjuNEkrWc-j91f-6t34CN-9YJ0,719
+cognite/neat/_data_model/models/conceptual/_property.py,sha256=blSZQxX52zaILAtjUkldPzPeysz7wnG-UGSNU5tacI8,4138
+cognite/neat/_data_model/models/dms/__init__.py,sha256=ZIoXXe6I_0Z-x8K6n4UghzCQbt-KDlzAvXLYVd7dn8w,3829
+cognite/neat/_data_model/models/dms/_base.py,sha256=F49CLKUmtjTaaW0NrQbjqGkpWNgnZMV8m8uomCU_FJU,719
 cognite/neat/_data_model/models/dms/_constants.py,sha256=wBkLjAPwufPc2naxOfPA1XC0CM2RbDbo6Dpiv9dPrew,1344
-cognite/neat/_data_model/models/dms/_constraints.py,sha256=7Nv-EoNl6lSHUQh6r15Ei0LzR3gWV006K3RlAi1Ic68,956
+cognite/neat/_data_model/models/dms/_constraints.py,sha256=QxcsHzdaYe3E5_xTIdtQDfkLPOzKa2c-0D02QKLto9o,1064
 cognite/neat/_data_model/models/dms/_container.py,sha256=SgrMCRo04A1gqayJsCia6oMhYT7q3NaeMBZMOQNI-lA,5967
 cognite/neat/_data_model/models/dms/_data_model.py,sha256=GNa05JEj_eSRGoKB8vkR85-Qv-IhPlDR3gXZNQMfe6g,2537
-cognite/neat/_data_model/models/dms/_data_types.py,sha256=XSGQWVzYFRYAzKsDln20nC2kqiHQC6JAvDeTzCBPT-0,5202
-cognite/neat/_data_model/models/dms/_indexes.py,sha256=MsiHbGCH50QaF1mw_pIY-AZ5dY37vS3fQECOd2rBXWo,780
+cognite/neat/_data_model/models/dms/_data_types.py,sha256=0cNChruCvIVLpCfk81L2u4ZrOg7V4zOU3GOibk2X4Hw,5773
+cognite/neat/_data_model/models/dms/_indexes.py,sha256=eM4VP6KtuPPSv4cuMRjBQI5TknmlSqwhW4sIPlExWfY,873
 cognite/neat/_data_model/models/dms/_references.py,sha256=LJ7xlXATf7AP_Uj-8LlxatQk5GG1Tu4CHGK63cJqUU4,3078
 cognite/neat/_data_model/models/dms/_schema.py,sha256=2JFLcm52smzPdtZ69Lf02UbYAD8I_hpRbI7ZAzdxJJs,641
 cognite/neat/_data_model/models/dms/_space.py,sha256=-1LkRmQaAdIj2EYDcVv5Mcejl5uswgAEVv7DztpIUk4,1680
-cognite/neat/_data_model/models/dms/_view_property.py,sha256=wiRxb5qtzGnBooBUzN7xtwMBZiZ9aRFcN5ML4lCTXdQ,8331
+cognite/neat/_data_model/models/dms/_types.py,sha256=5-cgC53AG186OZUqkltv7pMjcGNLuH7Etbn8IUcgk1c,447
+cognite/neat/_data_model/models/dms/_view_property.py,sha256=ROf2vYngQS4QPHt86VlwyQJBBOlKL-EylfePgX6Szwg,7422
 cognite/neat/_data_model/models/dms/_views.py,sha256=afUZisM-6r0_IeSwn8ZVFAqWfodHBWrMcFnk_a-ewSI,6579
-cognite/neat/_data_model/models/entities/__init__.py,sha256=qdtIpyy2hjfdMwEHya-efOCvWassaalQla15RnqK00E,798
+cognite/neat/_data_model/models/entities/__init__.py,sha256=7dDyES7fYl9LEREal59F038RdEvfGRpUOc6n_MtSgjU,836
 cognite/neat/_data_model/models/entities/_base.py,sha256=PaNrD29iwxuqTpRWbmESMTxRhhKXmRyDF_cLZEC69dg,3927
 cognite/neat/_data_model/models/entities/_constants.py,sha256=EK9Bus8UgFgxK5cVFMTAqWSl6aWkDe7d59hpUmlHlBs,517
 cognite/neat/_data_model/models/entities/_data_types.py,sha256=DfdEWGek7gODro-_0SiiInhPGwul4zn-ASACQfn8HUY,2838
 cognite/neat/_data_model/models/entities/_identifiers.py,sha256=uBiK4ot3V0b_LGXuJ7bfha6AEcFI3p2letr1z2iSvig,1923
-cognite/neat/_data_model/models/entities/_parser.py,sha256=ZLGw0cFV-B7JuaAUJ65Jbjf6o-vidz9_BZvilS6lAZw,6455
+cognite/neat/_data_model/models/entities/_parser.py,sha256=zef_pSDZYMZrJl4IKreFDR577KutfhtN1xpH3Ayjt2o,7669
+cognite/neat/_session/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cognite/neat/_session/_session.py,sha256=A2RKC4EQjMaKDr-QUiIPJgBXFqst9p1RIV2_yJrfvuE,1240
+cognite/neat/_session/_state_machine/__init__.py,sha256=8bStbS8ivqJbdyL2yR-_1K3OKOojsaKRrYcYTJac0ek,480
+cognite/neat/_session/_state_machine/_base.py,sha256=gdk1uIj--f50v2_X9zxqFRYTXiCgqtmjwkaxJxAJW5k,773
+cognite/neat/_session/_state_machine/_states.py,sha256=RX6C0YNNT9mX0C6c-ZTiUVh6pmMT5ZNXiOuSs80vVXU,4853
 cognite/neat/_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 cognite/neat/_utils/auxiliary.py,sha256=Cx-LP8dfN782R3iUcm--q26zdzQ0k_RFnVbJ0bwVZMI,1345
 cognite/neat/_utils/text.py,sha256=1el5Ty1T0tdhTF0gp6L8AAzUxaFmAUAIFy_VvfG_kkM,1194
 cognite/neat/_utils/useful_types.py,sha256=6Fpw_HlWFj8ZYjGPd0KzguBczuI8GFhj5wBceGsaeak,211
-cognite/neat/_utils/validation.py,sha256=qBC3V3BpkZSrsDG4xfINaB_U0e05e2lCt85oIW3on4I,3253
+cognite/neat/_utils/validation.py,sha256=Rwd-oABdnHyiwd2WR1H4F2JYTdshNIKzHqErbo-MDns,5113
 cognite/neat/_utils/http_client/__init__.py,sha256=gJBrOH1tIzEzLforHbeakYimTn4RlelyANps-jtpREI,894
 cognite/neat/_utils/http_client/_client.py,sha256=2RVwTbbPFlQ8eJVLKNUXwnc4Yq_783PkY44zwr6LlT8,11509
 cognite/neat/_utils/http_client/_config.py,sha256=C8IF1JoijmVMjA_FEMgAkiD1buEV1cY5Og3t-Ecyfmk,756
@@ -183,7 +190,7 @@ cognite/neat/v0/core/_issues/warnings/_resources.py,sha256=L4iTuVYgfwcaCRTbTCVoo
 cognite/neat/v0/core/_issues/warnings/user_modeling.py,sha256=neM9IJzLGWFcBiuo5p5CLFglXjrUXR61FNqvupNw7Y0,4147
 cognite/neat/v0/core/_store/__init__.py,sha256=wpsF8xjIQ5V21NOh45XQV813n_EzgyPOt0VVinYjnDI,140
 cognite/neat/v0/core/_store/_data_model.py,sha256=09JlHEkJVEPHCju8ixRUUsvRcZb0UrDE7wevB7tq4PI,19682
-cognite/neat/v0/core/_store/_instance.py,sha256=kFiodxzqLu233TWz3HAa-XTKIKndN9WRAEUNnomQhaI,17434
+cognite/neat/v0/core/_store/_instance.py,sha256=NokBDdPkp1K6Ce53dwx3jsBePgGUX0ggXPCGC5HvnGw,18935
 cognite/neat/v0/core/_store/_provenance.py,sha256=Q96wkVXRovO_uTlNvwCAOl6pAoWItTgFq1F79L_FqBk,7335
 cognite/neat/v0/core/_store/exceptions.py,sha256=dTaBSt7IV7XWtS3EsE8lBX1Dv3tfWX1nIEgGHkluy3s,1668
 cognite/neat/v0/core/_utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -207,8 +214,9 @@ cognite/neat/v0/plugins/_data_model.py,sha256=MSfb9Gtz-whsY3-usMaPYBxpc9-C5qN3gW
 cognite/neat/v0/plugins/_issues.py,sha256=9lbLlxgPSVHjirOhEHyNQ0Pf3NH82Psj_DuTCcJDQQQ,943
 cognite/neat/v0/plugins/_manager.py,sha256=Pmaw5yjobMJ64OYaODX3FTaH1Q7hW9rzbz0A8wyIZcI,3683
 cognite/neat/v0/session/__init__.py,sha256=fxQ5URVlUnmEGYyB8Baw7IDq-uYacqkigbc4b-Pr9Fw,58
-cognite/neat/v0/session/_base.py,sha256=cLVrNEIizWKdPb2LRtXYxQRQczAnyHXJ46Ak1P4X03k,12967
+cognite/neat/v0/session/_base.py,sha256=cCGRKBqSQfkUbekvoIpGPUWPNk7K1yUCqczyCwhvcn8,13036
 cognite/neat/v0/session/_collector.py,sha256=YCPeapbxBK-vAFMq7ekLy0Pn796M9AM7B8hxFtgsOUU,4236
+cognite/neat/v0/session/_diff.py,sha256=F03wOfCwwKMS3ZW9U4Zcv_0QhQR7fBlSxVEuA3SoIk0,1773
 cognite/neat/v0/session/_drop.py,sha256=8C9WDJglaO1lpej4jihOMTtEXjQn8wKL8JjZ1yxAvbE,4248
 cognite/neat/v0/session/_experimental.py,sha256=0peZPZ9JpmzQE05wHbng2tWmPPLLTAVfWZEEUhdnI6o,1274
 cognite/neat/v0/session/_explore.py,sha256=YQF8ubCm-dkpO5WuVfYGTkQjhF_XKHFcG6Ko5jwz-R0,1605
@@ -231,7 +239,7 @@ cognite/neat/v0/session/engine/__init__.py,sha256=D3MxUorEs6-NtgoICqtZ8PISQrjrr4
 cognite/neat/v0/session/engine/_import.py,sha256=1QxA2_EK613lXYAHKQbZyw2yjo5P9XuiX4Z6_6-WMNQ,169
 cognite/neat/v0/session/engine/_interface.py,sha256=3W-cYr493c_mW3P5O6MKN1xEQg3cA7NHR_ev3zdF9Vk,533
 cognite/neat/v0/session/engine/_load.py,sha256=u0x7vuQCRoNcPt25KJBJRn8sJabonYK4vtSZpiTdP4k,5201
-cognite_neat-0.123.42.dist-info/METADATA,sha256=R-A1tkY3opZDSbVVDo2flVy7ZlawJvUISZCllr6i_mM,9148
-cognite_neat-0.123.42.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cognite_neat-0.123.42.dist-info/licenses/LICENSE,sha256=W8VmvFia4WHa3Gqxq1Ygrq85McUNqIGDVgtdvzT-XqA,11351
-cognite_neat-0.123.42.dist-info/RECORD,,
+cognite_neat-0.124.0.dist-info/METADATA,sha256=uQiuJcVRVFPhAyKUSXFn7DyXW8kfBE75pCQgnZxU8Ec,9147
+cognite_neat-0.124.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cognite_neat-0.124.0.dist-info/licenses/LICENSE,sha256=W8VmvFia4WHa3Gqxq1Ygrq85McUNqIGDVgtdvzT-XqA,11351
+cognite_neat-0.124.0.dist-info/RECORD,,