add preview models and api method

CHANGELOG.md

@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- add preview models for merged items without cardinality validation
+- add `BackendApiConnector.fetch_preview_items` for fetching previews
+
 ### Changes
 
 ### Deprecated

mex/common/backend_api/connector.py

@@ -8,6 +8,7 @@
     IdentifiersResponse,
     MergedItemsResponse,
     MergedModelTypeAdapter,
+    PreviewItemsResponse,
     RuleSetResponseTypeAdapter,
 )
 from mex.common.connector import HTTPConnector
@@ -185,6 +186,40 @@ def preview_merged_item(
         )
         return MergedModelTypeAdapter.validate_python(response)
 
+    def fetch_preview_items(
+        self,
+        query_string: str | None,
+        entity_type: list[str] | None,
+        skip: int,
+        limit: int,
+    ) -> PreviewItemsResponse:
+        """Fetch merged item previews that match the given set of filters.
+
+        Args:
+            query_string: Full-text search query
+            entity_type: The item's entityType
+            skip: How many items to skip for pagination
+            limit: How many items to return in one page
+
+        Raises:
+            HTTPError: If search was not accepted, crashes or times out
+
+        Returns:
+            One page of preview items and the total count that was matched
+        """
+        # Note: this is forward-compat for MX-1649, backend might not support this yet!
+        response = self.request(
+            method="GET",
+            endpoint="preview-item",
+            params={
+                "q": query_string,
+                "entityType": entity_type,
+                "skip": str(skip),
+                "limit": str(limit),
+            },
+        )
+        return PreviewItemsResponse.model_validate(response)
+
     def get_rule_set(
         self,
         stable_target_id: str,

mex/common/backend_api/models.py

@@ -5,6 +5,7 @@
 from mex.common.models import (
     AnyExtractedModel,
     AnyMergedModel,
+    AnyPreviewModel,
     AnyRuleSetResponse,
     BaseModel,
 )
@@ -31,6 +32,13 @@ class MergedItemsResponse(BaseModel):
     total: int
 
 
+class PreviewItemsResponse(BaseModel):
+    """Response model for a list of preview items including a total count."""
+
+    items: list[AnyPreviewModel]
+    total: int
+
+
 class IdentifiersResponse(BaseModel):
     """Response models for a list of identifiers."""
 

mex/common/models/__init__.py

@@ -21,6 +21,7 @@
 - `BaseT` defines all fields according to `mex-model` except for provenance fields
 - `ExtractedT` defines an automatically extracted metadata item including provenance
 - `MergedT` defines the result of merging extracted items and rules into a single item
+- `PreviewT` defines a preview of a merged item without enforcing cardinality validation
 
 - `AdditiveT` defines a rule to add values to specific fields of a merged item
 - `SubtractiveT` defines a rule to subtract (or block) specific values for specific
@@ -54,6 +55,7 @@
 - BaseT: _OptionalLists, _RequiredLists, _OptionalValues, _RequiredValues
 - ExtractedT: BaseT, ExtractedData
 - MergedT: BaseT, MergedItem
+- PreviewT: _OptionalLists, _SparseLists, _OptionalValues, _SparseValues, PreviewItem
 
 - AdditiveT: _OptionalLists, _SparseLists, _OptionalValues, _SparseValues, AdditiveRule
 - SubtractiveT: _OptionalLists, _SparseLists, _VariadicValues, SubtractiveRule
@@ -78,6 +80,7 @@
     ExtractedAccessPlatform,
     MergedAccessPlatform,
     PreventiveAccessPlatform,
+    PreviewAccessPlatform,
     SubtractiveAccessPlatform,
 )
 from mex.common.models.activity import (
@@ -88,13 +91,14 @@
     ExtractedActivity,
     MergedActivity,
     PreventiveActivity,
+    PreviewActivity,
     SubtractiveActivity,
 )
 from mex.common.models.base.extracted_data import ExtractedData
 from mex.common.models.base.field_info import GenericFieldInfo
 from mex.common.models.base.filter import generate_entity_filter_schema
 from mex.common.models.base.mapping import generate_mapping_schema
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import AdditiveRule, PreventiveRule, SubtractiveRule
 from mex.common.models.bibliographic_resource import (
@@ -105,6 +109,7 @@
     ExtractedBibliographicResource,
     MergedBibliographicResource,
     PreventiveBibliographicResource,
+    PreviewBibliographicResource,
     SubtractiveBibliographicResource,
 )
 from mex.common.models.consent import (
@@ -115,6 +120,7 @@
     ExtractedConsent,
     MergedConsent,
     PreventiveConsent,
+    PreviewConsent,
     SubtractiveConsent,
 )
 from mex.common.models.contact_point import (
@@ -125,6 +131,7 @@
     ExtractedContactPoint,
     MergedContactPoint,
     PreventiveContactPoint,
+    PreviewContactPoint,
     SubtractiveContactPoint,
 )
 from mex.common.models.distribution import (
@@ -135,6 +142,7 @@
     ExtractedDistribution,
     MergedDistribution,
     PreventiveDistribution,
+    PreviewDistribution,
     SubtractiveDistribution,
 )
 from mex.common.models.organization import (
@@ -145,6 +153,7 @@
     OrganizationRuleSetRequest,
     OrganizationRuleSetResponse,
     PreventiveOrganization,
+    PreviewOrganization,
     SubtractiveOrganization,
 )
 from mex.common.models.organizational_unit import (
@@ -155,6 +164,7 @@
     OrganizationalUnitRuleSetRequest,
     OrganizationalUnitRuleSetResponse,
     PreventiveOrganizationalUnit,
+    PreviewOrganizationalUnit,
     SubtractiveOrganizationalUnit,
 )
 from mex.common.models.person import (
@@ -165,6 +175,7 @@
     PersonRuleSetRequest,
     PersonRuleSetResponse,
     PreventivePerson,
+    PreviewPerson,
     SubtractivePerson,
 )
 from mex.common.models.primary_source import (
@@ -173,6 +184,7 @@
     ExtractedPrimarySource,
     MergedPrimarySource,
     PreventivePrimarySource,
+    PreviewPrimarySource,
     PrimarySourceRuleSetRequest,
     PrimarySourceRuleSetResponse,
     SubtractivePrimarySource,
@@ -183,6 +195,7 @@
     ExtractedResource,
     MergedResource,
     PreventiveResource,
+    PreviewResource,
     ResourceRuleSetRequest,
     ResourceRuleSetResponse,
     SubtractiveResource,
@@ -193,6 +206,7 @@
     ExtractedVariable,
     MergedVariable,
     PreventiveVariable,
+    PreviewVariable,
     SubtractiveVariable,
     VariableRuleSetRequest,
     VariableRuleSetResponse,
@@ -203,6 +217,7 @@
     ExtractedVariableGroup,
     MergedVariableGroup,
     PreventiveVariableGroup,
+    PreviewVariableGroup,
     SubtractiveVariableGroup,
     VariableGroupRuleSetRequest,
     VariableGroupRuleSetResponse,
@@ -334,6 +349,20 @@
     "PreventiveRule",
     "PreventiveVariable",
     "PreventiveVariableGroup",
+    "PreviewAccessPlatform",
+    "PreviewActivity",
+    "PreviewBibliographicResource",
+    "PreviewConsent",
+    "PreviewContactPoint",
+    "PreviewDistribution",
+    "PreviewItem",
+    "PreviewOrganization",
+    "PreviewOrganizationalUnit",
+    "PreviewPerson",
+    "PreviewPrimarySource",
+    "PreviewResource",
+    "PreviewVariable",
+    "PreviewVariableGroup",
     "PrimarySourceRuleSetRequest",
     "PrimarySourceRuleSetResponse",
     "ResourceRuleSetRequest",
@@ -426,6 +455,28 @@
     cls.__name__: cls for cls in MERGED_MODEL_CLASSES
 }
 
+AnyPreviewModel = (
+    PreviewAccessPlatform
+    | PreviewActivity
+    | PreviewBibliographicResource
+    | PreviewConsent
+    | PreviewContactPoint
+    | PreviewDistribution
+    | PreviewOrganization
+    | PreviewOrganizationalUnit
+    | PreviewPerson
+    | PreviewPrimarySource
+    | PreviewResource
+    | PreviewVariable
+    | PreviewVariableGroup
+)
+PREVIEW_MODEL_CLASSES: Final[list[type[AnyPreviewModel]]] = list(
+    get_args(AnyPreviewModel)
+)
+PREVIEW_MODEL_CLASSES_BY_NAME: Final[dict[str, type[AnyPreviewModel]]] = {
+    cls.__name__: cls for cls in PREVIEW_MODEL_CLASSES
+}
+
 AnyAdditiveModel = (
     AdditiveAccessPlatform
     | AdditiveActivity

mex/common/models/access_platform.py

@@ -5,7 +5,7 @@
 from pydantic import AfterValidator, Field, computed_field
 
 from mex.common.models.base.extracted_data import ExtractedData
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import (
     AdditiveRule,
@@ -104,6 +104,17 @@ class MergedAccessPlatform(BaseAccessPlatform, MergedItem):
     identifier: Annotated[MergedAccessPlatformIdentifier, Field(frozen=True)]
 
 
+class PreviewAccessPlatform(
+    _OptionalLists, _OptionalValues, _SparseValues, PreviewItem
+):
+    """Preview for merging all extracted data and rules for an access platform."""
+
+    entityType: Annotated[
+        Literal["PreviewAccessPlatform"], Field(alias="$type", frozen=True)
+    ] = "PreviewAccessPlatform"
+    identifier: Annotated[MergedAccessPlatformIdentifier, Field(frozen=True)]
+
+
 class AdditiveAccessPlatform(
     _OptionalLists, _OptionalValues, _SparseValues, AdditiveRule
 ):

mex/common/models/activity.py

@@ -8,7 +8,7 @@
 from pydantic import AfterValidator, Field, computed_field
 
 from mex.common.models.base.extracted_data import ExtractedData
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import (
     AdditiveRule,
@@ -129,6 +129,15 @@ class MergedActivity(BaseActivity, MergedItem):
     identifier: Annotated[MergedActivityIdentifier, Field(frozen=True)]
 
 
+class PreviewActivity(_OptionalLists, _SparseLists, PreviewItem):
+    """Preview for merging all extracted data and rules for an activity."""
+
+    entityType: Annotated[
+        Literal["PreviewActivity"], Field(alias="$type", frozen=True)
+    ] = "PreviewActivity"
+    identifier: Annotated[MergedActivityIdentifier, Field(frozen=True)]
+
+
 class AdditiveActivity(_OptionalLists, _SparseLists, AdditiveRule):
     """Rule to add values to merged activity items."""
 

mex/common/models/base/merged_item.py

@@ -3,3 +3,7 @@
 
 class MergedItem(BaseEntity):
     """Base model for all merged item classes."""
+
+
+class PreviewItem(BaseEntity):
+    """Base model for previews of merged items."""

mex/common/models/bibliographic_resource.py

@@ -5,7 +5,7 @@
 from pydantic import Field, computed_field
 
 from mex.common.models.base.extracted_data import ExtractedData
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import (
     AdditiveRule,
@@ -225,6 +225,17 @@ class MergedBibliographicResource(BaseBibliographicResource, MergedItem):
     identifier: Annotated[MergedBibliographicResourceIdentifier, Field(frozen=True)]
 
 
+class PreviewBibliographicResource(
+    _OptionalLists, _SparseLists, _OptionalValues, _SparseValues, PreviewItem
+):
+    """Preview for merging all extracted data and rules for a bibliographic resource."""
+
+    entityType: Annotated[
+        Literal["PreviewBibliographicResource"], Field(alias="$type", frozen=True)
+    ] = "PreviewBibliographicResource"
+    identifier: Annotated[MergedBibliographicResourceIdentifier, Field(frozen=True)]
+
+
 class AdditiveBibliographicResource(
     _OptionalLists, _SparseLists, _OptionalValues, _SparseValues, AdditiveRule
 ):

mex/common/models/consent.py

@@ -5,7 +5,7 @@
 from pydantic import Field, computed_field
 
 from mex.common.models.base.extracted_data import ExtractedData
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import (
     AdditiveRule,
@@ -84,6 +84,15 @@ class MergedConsent(BaseConsent, MergedItem):
     identifier: Annotated[MergedConsentIdentifier, Field(frozen=True)]
 
 
+class PreviewConsent(_OptionalValues, _SparseValues, PreviewItem):
+    """Preview for merging all extracted data and rules for a consent."""
+
+    entityType: Annotated[
+        Literal["PreviewConsent"], Field(alias="$type", frozen=True)
+    ] = "PreviewConsent"
+    identifier: Annotated[MergedConsentIdentifier, Field(frozen=True)]
+
+
 class AdditiveConsent(_OptionalValues, _SparseValues, AdditiveRule):
     """Rule to add values to merged consent items."""
 

mex/common/models/contact_point.py

@@ -5,7 +5,7 @@
 from pydantic import Field, computed_field
 
 from mex.common.models.base.extracted_data import ExtractedData
-from mex.common.models.base.merged_item import MergedItem
+from mex.common.models.base.merged_item import MergedItem, PreviewItem
 from mex.common.models.base.model import BaseModel
 from mex.common.models.base.rules import (
     AdditiveRule,
@@ -68,6 +68,15 @@ class MergedContactPoint(BaseContactPoint, MergedItem):
     identifier: Annotated[MergedContactPointIdentifier, Field(frozen=True)]
 
 
+class PreviewContactPoint(_SparseLists, PreviewItem):
+    """Preview for merging all extracted data and rules for a contact point."""
+
+    entityType: Annotated[
+        Literal["PreviewContactPoint"], Field(alias="$type", frozen=True)
+    ] = "PreviewContactPoint"
+    identifier: Annotated[MergedContactPointIdentifier, Field(frozen=True)]
+
+
 class AdditiveContactPoint(_SparseLists, AdditiveRule):
     """Rule to add values to merged contact point items."""