cognite-neat 0.123.43__tar.gz → 0.124.0__tar.gz

{cognite_neat-0.123.43 → cognite_neat-0.124.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cognite-neat
-Version: 0.123.43
+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.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.124.0/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-0.123.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.123.43 → cognite_neat-0.124.0}/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-0.124.0/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-0.124.0/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-0.124.0/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-0.124.0/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