metaspn-entities 0.1.0__py3-none-any.whl → 0.1.3__py3-none-any.whl

metaspn_entities/events.py

@@ -1,8 +1,18 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import datetime, timezone
 from typing import Any, Dict
 
+DEFAULT_SCHEMA_VERSION = "0.1"
+try:
+    from metaspn_schemas.core import DEFAULT_SCHEMA_VERSION as _SCHEMA_VERSION
+
+    DEFAULT_SCHEMA_VERSION = _SCHEMA_VERSION
+except Exception:
+    # Keep local behavior deterministic when dependency is not importable in dev sandboxes.
+    pass
+
 
 @dataclass(frozen=True)
 class EmittedEvent:
@@ -12,38 +22,44 @@ class EmittedEvent:
 
 class EventFactory:
     @staticmethod
-    def entity_resolved(entity_id: str, identifier_type: str, value: str, confidence: float, created_new_entity: bool) -> EmittedEvent:
+    def _now() -> datetime:
+        return datetime.now(timezone.utc).replace(microsecond=0)
+
+    @staticmethod
+    def entity_resolved(entity_id: str, resolver: str, confidence: float) -> EmittedEvent:
         return EmittedEvent(
             event_type="EntityResolved",
             payload={
                 "entity_id": entity_id,
-                "identifier_type": identifier_type,
-                "value": value,
+                "resolver": resolver,
+                "resolved_at": EventFactory._now().isoformat(),
                 "confidence": confidence,
-                "created_new_entity": created_new_entity,
+                "schema_version": DEFAULT_SCHEMA_VERSION,
             },
         )
 
     @staticmethod
-    def entity_merged(from_entity_id: str, to_entity_id: str, reason: str, caused_by: str) -> EmittedEvent:
+    def entity_merged(entity_id: str, merged_from: tuple[str, ...], reason: str | None = None) -> EmittedEvent:
         return EmittedEvent(
             event_type="EntityMerged",
             payload={
-                "from_entity_id": from_entity_id,
-                "to_entity_id": to_entity_id,
+                "entity_id": entity_id,
+                "merged_from": list(merged_from),
+                "merged_at": EventFactory._now().isoformat(),
                 "reason": reason,
-                "caused_by": caused_by,
+                "schema_version": DEFAULT_SCHEMA_VERSION,
             },
         )
 
     @staticmethod
-    def entity_alias_added(entity_id: str, identifier_type: str, normalized_value: str, caused_by: str) -> EmittedEvent:
+    def entity_alias_added(entity_id: str, alias: str, alias_type: str) -> EmittedEvent:
         return EmittedEvent(
             event_type="EntityAliasAdded",
             payload={
                 "entity_id": entity_id,
-                "identifier_type": identifier_type,
-                "normalized_value": normalized_value,
-                "caused_by": caused_by,
+                "alias": alias,
+                "alias_type": alias_type,
+                "added_at": EventFactory._now().isoformat(),
+                "schema_version": DEFAULT_SCHEMA_VERSION,
             },
         )

metaspn_entities/resolver.py

@@ -39,12 +39,11 @@ class EntityResolver:
                 created_new_entity=False,
                 matched_identifiers=matched_identifiers,
             )
-            self._event_buffer.append(
-                EventFactory.entity_resolved(entity_id, identifier_type, value, resolution.confidence, False)
-            )
+            self._event_buffer.append(EventFactory.entity_resolved(entity_id, caused_by, resolution.confidence))
             return resolution
 
         entity_id = self.store.create_entity(entity_type)
+        created_entity_id = entity_id
         added, conflicting_entity_id = self.store.add_alias(
             identifier_type=identifier_type,
             normalized_value=normalized,
@@ -58,9 +57,7 @@ class EntityResolver:
             merge_reason = f"auto-merge on {identifier_type}:{normalized}"
             self.store.merge_entities(entity_id, conflicting_entity_id, merge_reason, "auto-merge")
             entity_id = self.store.canonical_entity_id(conflicting_entity_id)
-            self._event_buffer.append(
-                EventFactory.entity_merged(entity_id, conflicting_entity_id, merge_reason, "auto-merge")
-            )
+            self._event_buffer.append(EventFactory.entity_merged(entity_id, (created_entity_id,), merge_reason))
 
         matched_identifiers = list(self.store.iter_identifiers_for_entity(entity_id))
         resolution = EntityResolution(
@@ -70,10 +67,8 @@ class EntityResolver:
             matched_identifiers=matched_identifiers,
         )
         if added:
-            self._event_buffer.append(EventFactory.entity_alias_added(entity_id, identifier_type, normalized, caused_by))
-        self._event_buffer.append(
-            EventFactory.entity_resolved(entity_id, identifier_type, value, resolution.confidence, True)
-        )
+            self._event_buffer.append(EventFactory.entity_alias_added(entity_id, normalized, identifier_type))
+        self._event_buffer.append(EventFactory.entity_resolved(entity_id, caused_by, resolution.confidence))
         return resolution
 
     def add_alias(
@@ -102,7 +97,7 @@ class EntityResolver:
             if identifier_type in AUTO_MERGE_IDENTIFIER_TYPES:
                 reason = f"auto-merge on {identifier_type}:{normalized}"
                 self.store.merge_entities(canonical_entity_id, conflicting_entity_id, reason, "auto-merge")
-                event = EventFactory.entity_merged(canonical_entity_id, conflicting_entity_id, reason, "auto-merge")
+                event = EventFactory.entity_merged(conflicting_entity_id, (canonical_entity_id,), reason)
                 self._event_buffer.append(event)
                 return [event]
             raise ValueError(
@@ -112,7 +107,7 @@ class EntityResolver:
         if not added:
             return []
 
-        event = EventFactory.entity_alias_added(canonical_entity_id, identifier_type, normalized, caused_by)
+        event = EventFactory.entity_alias_added(canonical_entity_id, normalized, identifier_type)
         self._event_buffer.append(event)
         return [event]
 
@@ -120,7 +115,7 @@ class EntityResolver:
         self.store.ensure_entity(from_entity_id)
         self.store.ensure_entity(to_entity_id)
         self.store.merge_entities(from_entity_id, to_entity_id, reason, caused_by)
-        event = EventFactory.entity_merged(from_entity_id, to_entity_id, reason, caused_by)
+        event = EventFactory.entity_merged(self.store.canonical_entity_id(to_entity_id), (from_entity_id,), reason)
         self._event_buffer.append(event)
         return event
 
@@ -130,7 +125,7 @@ class EntityResolver:
             self.store.remove_redirect(from_entity_id)
             self.store.set_entity_status(from_entity_id, EntityStatus.ACTIVE)
         self.store.merge_entities(to_entity_id, from_entity_id, reason, caused_by)
-        event = EventFactory.entity_merged(to_entity_id, from_entity_id, reason, caused_by)
+        event = EventFactory.entity_merged(self.store.canonical_entity_id(from_entity_id), (to_entity_id,), reason)
         self._event_buffer.append(event)
         return event
 

{metaspn_entities-0.1.0.dist-info → metaspn_entities-0.1.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.0
+Version: 0.1.3
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -55,3 +55,17 @@ print(resolution.entity_id, resolution.confidence)
 - `undo_merge(from_entity_id, to_entity_id, ...)` (implemented as reverse merge with redirect correction)
 - `drain_events() -> list[EmittedEvent]`
 - `export_snapshot(output_path)` to inspect SQLite state as JSON
+
+## Event Contract Guarantees
+
+`drain_events()` returns `EmittedEvent` objects whose `event_type` and `payload` are
+schema-compatible with `metaspn-schemas` entity events.
+
+- `EntityResolved` payload keys:
+  - `entity_id`, `resolver`, `resolved_at`, `confidence`, `schema_version`
+- `EntityMerged` payload keys:
+  - `entity_id`, `merged_from`, `merged_at`, `reason`, `schema_version`
+- `EntityAliasAdded` payload keys:
+  - `entity_id`, `alias`, `alias_type`, `added_at`, `schema_version`
+
+Datetime fields are emitted as UTC ISO-8601 strings for deterministic serialization.

metaspn_entities-0.1.3.dist-info/RECORD

@@ -0,0 +1,11 @@
+metaspn_entities/__init__.py,sha256=7hsZse74SfsKugEKs3P6hIyfSDuzDWdeUFQdnev2yBo,259
+metaspn_entities/events.py,sha256=Hkc3gy5_vRTSR0MKUvF24dTqNqOkG423_PTUe7csUfw,2066
+metaspn_entities/models.py,sha256=b2EFsc1EIT9Ao_bKA2I52-5W_0fTwhsyO6VFRG8gZg8,1377
+metaspn_entities/normalize.py,sha256=nPAHRfipgS6zHy2x70ZFd5HB1W4FKmeTF8Kd4TYz5tI,1125
+metaspn_entities/resolver.py,sha256=350XMAng6qJvZqRmmikP7mRZtA22pZ2CwZcvmk-q8tU,6654
+metaspn_entities/sqlite_backend.py,sha256=0QmHkMd4XZxdSmgvn_s6xsRr5Ocv0b6dERF_QSUuelM,10562
+metaspn_entities-0.1.3.dist-info/licenses/LICENSE,sha256=tvVpto97dUnh1-KVYPs1rCr5dzyX8jUyNmT7F7ZPVAM,1077
+metaspn_entities-0.1.3.dist-info/METADATA,sha256=NWxTysmpuXB1KY-lQl4QqKOnisF6eqAfBmJWi7PtzWI,2524
+metaspn_entities-0.1.3.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+metaspn_entities-0.1.3.dist-info/top_level.txt,sha256=YP2V8Z1Statrs3YAI-tGvyC73vLjPHr9Vkal4yqXkhs,17
+metaspn_entities-0.1.3.dist-info/RECORD,,

metaspn_entities-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-metaspn_entities/__init__.py,sha256=7hsZse74SfsKugEKs3P6hIyfSDuzDWdeUFQdnev2yBo,259
-metaspn_entities/events.py,sha256=plfAg6GYwAwYPz0CC6ryS82WUl6oo23NR-vPZyFAJdA,1567
-metaspn_entities/models.py,sha256=b2EFsc1EIT9Ao_bKA2I52-5W_0fTwhsyO6VFRG8gZg8,1377
-metaspn_entities/normalize.py,sha256=nPAHRfipgS6zHy2x70ZFd5HB1W4FKmeTF8Kd4TYz5tI,1125
-metaspn_entities/resolver.py,sha256=aM37vYLev_CmYVxriRyVrQq8x49LW4olIdPyeZIH4Ag,6737
-metaspn_entities/sqlite_backend.py,sha256=0QmHkMd4XZxdSmgvn_s6xsRr5Ocv0b6dERF_QSUuelM,10562
-metaspn_entities-0.1.0.dist-info/licenses/LICENSE,sha256=tvVpto97dUnh1-KVYPs1rCr5dzyX8jUyNmT7F7ZPVAM,1077
-metaspn_entities-0.1.0.dist-info/METADATA,sha256=R-cIauos_ZIaWF10KiICr_TsCw8zATTj8VPkXQIDazM,1950
-metaspn_entities-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-metaspn_entities-0.1.0.dist-info/top_level.txt,sha256=YP2V8Z1Statrs3YAI-tGvyC73vLjPHr9Vkal4yqXkhs,17
-metaspn_entities-0.1.0.dist-info/RECORD,,