cognite-neat 0.123.43__py3-none-any.whl → 0.125.0__py3-none-any.whl

cognite/neat/_data_model/importers/__init__.py

@@ -1,3 +1,4 @@
 from ._base import DMSImporter
+from ._table_importer.importer import DMSTableImporter
 
-__all__ = ["DMSImporter"]
+__all__ = ["DMSImporter", "DMSTableImporter"]

cognite/neat/_data_model/importers/_table_importer/data_classes.py

@@ -0,0 +1,141 @@
+from collections.abc import Mapping
+from typing import Annotated, cast
+
+from pydantic import AliasGenerator, BaseModel, BeforeValidator, Field, model_validator
+from pydantic.alias_generators import to_camel
+
+from cognite.neat._data_model.models.entities import ParsedEntity, parse_entities, parse_entity
+from cognite.neat._utils.text import title_case
+from cognite.neat._utils.useful_types import CellValueType
+
+
+def parse_entity_str(v: str) -> ParsedEntity:
+    try:
+        return parse_entity(v)
+    except ValueError as e:
+        raise ValueError(f"Invalid entity syntax: {e}") from e
+
+
+def parse_entities_str(v: str) -> list[ParsedEntity] | None:
+    try:
+        return parse_entities(v)
+    except ValueError as e:
+        raise ValueError(f"Invalid entity list syntax: {e}") from e
+
+
+Entity = Annotated[ParsedEntity, BeforeValidator(parse_entity_str, str)]
+EntityList = Annotated[list[ParsedEntity], BeforeValidator(parse_entities_str, str)]
+
+
+class TableObj(
+    BaseModel,
+    extra="ignore",
+    alias_generator=AliasGenerator(
+        validation_alias=title_case,
+        serialization_alias=to_camel,
+    ),
+): ...
+
+
+class MetadataValue(TableObj):
+    key: str
+    value: CellValueType
+
+
+class DMSProperty(TableObj):
+    view: Entity
+    view_property: str
+    name: str | None = None
+    description: str | None = None
+    connection: Entity | None
+    value_type: Entity
+    min_count: int | None
+    max_count: int | None
+    immutable: bool | None = None
+    default: CellValueType | None = None
+    auto_increment: bool | None = None
+    container: Entity | None = None
+    container_property: str | None = None
+    container_property_name: str | None = None
+    container_property_description: str | None = None
+    index: EntityList | None = None
+    constraint: EntityList | None = None
+
+
+class DMSView(TableObj):
+    view: Entity
+    name: str | None = None
+    description: str | None = None
+    implements: EntityList | None = None
+    filter: str | None = None
+    in_model: bool | None = None
+
+
+class DMSContainer(TableObj):
+    container: Entity
+    name: str | None = None
+    description: str | None = None
+    constraint: EntityList | None = None
+    used_for: str | None = None
+
+
+class DMSEnum(TableObj):
+    collection: str
+    value: str
+    name: str | None = None
+    description: str | None = None
+
+
+class DMSNode(TableObj):
+    node: Entity
+
+
+class TableDMS(TableObj):
+    metadata: list[MetadataValue]
+    properties: list[DMSProperty]
+    views: list[DMSView]
+    containers: list[DMSContainer] = Field(default_factory=list)
+    enum: list[DMSEnum] = Field(default_factory=list)
+    nodes: list[DMSNode] = Field(default_factory=list)
+
+    @model_validator(mode="before")
+    def _title_case_keys(
+        cls, data: dict[str, list[dict[str, CellValueType]]]
+    ) -> dict[str, list[dict[str, CellValueType]]]:
+        if isinstance(data, dict):
+            # We are case-insensitive on the table names.
+            return {title_case(k): v for k, v in data.items()}
+        return data
+
+
+DMS_API_MAPPING: Mapping[str, Mapping[str, str]] = {
+    "Views": {
+        "space": "View",
+        "externalId": "View",
+        "version": "View",
+        **{
+            cast(str, field_.serialization_alias): cast(str, field_.validation_alias)
+            for field_id, field_ in DMSView.model_fields.items()
+            if field_id != "View"
+        },
+    },
+    "Containers": {
+        "space": "Container",
+        "externalId": "Container",
+        **{
+            cast(str, field_.serialization_alias): cast(str, field_.validation_alias)
+            for field_id, field_ in DMSContainer.model_fields.items()
+            if field_id != "Container"
+        },
+    },
+    "Properties": {
+        "space": "View",
+        "externalId": "View",
+        "property": "ViewProperty",
+        **{
+            cast(str, field_.serialization_alias): cast(str, field_.validation_alias)
+            for field_id, field_ in DMSProperty.model_fields.items()
+            if field_id not in ("View", "ViewProperty")
+        },
+    },
+}

cognite/neat/_data_model/importers/_table_importer/importer.py

@@ -0,0 +1,76 @@
+from collections.abc import Mapping
+from typing import ClassVar, cast
+
+from pydantic import ValidationError
+
+from cognite.neat._data_model.importers._base import DMSImporter
+from cognite.neat._data_model.models.dms import (
+    RequestSchema,
+)
+from cognite.neat._exceptions import DataModelImportError
+from cognite.neat._issues import ModelSyntaxError
+from cognite.neat._utils.useful_types import CellValueType
+from cognite.neat._utils.validation import as_json_path, humanize_validation_error
+
+from .data_classes import TableDMS
+
+
+class DMSTableImporter(DMSImporter):
+    """Imports DMS from a table structure.
+
+    The tables can are expected to be a dictionary where the keys are the table names and the values
+    are lists of dictionaries representing the rows in the table.
+    """
+
+    # We can safely cast as we know the validation_alias is always set to a str.
+    REQUIRED_SHEETS = tuple(
+        cast(str, field_.validation_alias) for field_ in TableDMS.model_fields.values() if field_.is_required()
+    )
+    REQUIRED_SHEET_MESSAGES: ClassVar[Mapping[str, str]] = {
+        f"Missing required column: {sheet!r}": f"Missing required sheet: {sheet!r}" for sheet in REQUIRED_SHEETS
+    }
+
+    def __init__(self, tables: dict[str, list[dict[str, CellValueType]]]) -> None:
+        self._table = tables
+
+    def to_data_model(self) -> RequestSchema:
+        raise NotImplementedError()
+
+    def _read_tables(self) -> TableDMS:
+        try:
+            # Check tables, columns, data type and entity syntax.
+            table = TableDMS.model_validate(self._table)
+        except ValidationError as e:
+            errors = self._create_error_messages(e)
+            raise DataModelImportError(errors) from None
+        return table
+
+    def _create_error_messages(self, error: ValidationError) -> list[ModelSyntaxError]:
+        errors: list[ModelSyntaxError] = []
+        seen: set[str] = set()
+        for message in humanize_validation_error(
+            error,
+            humanize_location=self._location,
+            field_name="column",
+            missing_required_descriptor="missing",
+        ):
+            # Replace messages about missing required columns with missing required sheets.
+            message = self.REQUIRED_SHEET_MESSAGES.get(message, message)
+            if message in seen:
+                # We treat all rows as the same, so we get duplicated errors for each row.
+                continue
+            seen.add(message)
+            errors.append(ModelSyntaxError(message=message))
+        return errors
+
+    @staticmethod
+    def _location(loc: tuple[str | int, ...]) -> str:
+        if isinstance(loc[0], str) and len(loc) == 2:  # Sheet + row.
+            # We skip the row as we treat all rows as the same. For example, if a required column is missing in one
+            # row, it is missing in all rows.
+            return f"{loc[0]} sheet"
+        elif len(loc) == 3 and isinstance(loc[0], str) and isinstance(loc[1], int) and isinstance(loc[2], str):
+            # This means there is something wrong in a specific cell.
+            return f"{loc[0]} sheet row {loc[1] + 1} column {loc[2]!r}"
+        # This should be unreachable as the TableDMS model only has 2 levels.
+        return as_json_path(loc)

cognite/neat/_data_model/importers/_table_importer/source.py

@@ -0,0 +1,89 @@
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+
+from .data_classes import DMS_API_MAPPING
+
+
+@dataclass
+class SpreadsheetReadContext:
+    """This class is used to store information about the source spreadsheet.
+
+    It is used to adjust row numbers to account for header rows and empty rows
+    such that the error/warning messages are accurate.
+    """
+
+    header_row: int = 1
+    empty_rows: list[int] = field(default_factory=list)
+    skipped_rows: list[int] = field(default_factory=list)
+    is_one_indexed: bool = True
+
+    def __post_init__(self) -> None:
+        self.empty_rows.sort()
+        self.skipped_rows.sort()
+
+    def adjusted_row_number(self, row_no: int) -> int:
+        output = row_no
+        for empty_row in self.empty_rows:
+            if empty_row <= output:
+                output += 1
+            else:
+                break
+
+        for skipped_rows in self.skipped_rows:
+            if skipped_rows <= output:
+                output += 1
+            else:
+                break
+
+        return output + self.header_row + (1 if self.is_one_indexed else 0)
+
+
+@dataclass
+class TableSource:
+    source: str
+    table_read: dict[str, SpreadsheetReadContext] = field(default_factory=dict)
+
+    def location(self, path: tuple[int | str, ...]) -> str:
+        table_id: str | None = None
+        row_no: int | None = None
+        column: str | None = None
+        if len(path) >= 1 and isinstance(path[0], str):
+            table_id = path[0]
+        if len(path) >= 2 and isinstance(path[1], int):
+            row_no = path[1]
+        if len(path) >= 3 and isinstance(path[2], str):
+            column = path[2]
+            column = self.field_to_column(table_id, column)
+        if isinstance(row_no, int):
+            row_no = self.adjust_row_number(table_id, row_no)
+        location_parts = []
+        if table_id is not None:
+            location_parts.append(f"table {table_id!r}")
+        if row_no is not None:
+            location_parts.append(f"row {row_no}")
+        if column is not None:
+            location_parts.append(f"column {column!r}")
+        if len(path) > 4:
+            location_parts.append("-> " + ".".join(str(p) for p in path[3:]))
+
+        return " ".join(location_parts)
+
+    def adjust_row_number(self, table_id: str | None, row_no: int) -> int:
+        table_read = table_id and self.table_read.get(table_id)
+        if table_read:
+            return table_read.adjusted_row_number(row_no)
+        return row_no + 1  # Convert to 1-indexed if no table read info is available
+
+    @classmethod
+    def field_to_column(cls, table_id: str | None, field_: str) -> str:
+        """Maps the field name used in the DMS API to the column named used by Neat."""
+        mapping = cls.field_mapping(table_id)
+        if mapping is not None:
+            return mapping.get(field_, field_)
+        return field_
+
+    @classmethod
+    def field_mapping(cls, table_id: str | int | None) -> Mapping[str, str] | None:
+        if not isinstance(table_id, str):
+            return None
+        return DMS_API_MAPPING.get(table_id)

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()]