metaspn-entities 0.1.0__tar.gz → 0.1.4__tar.gz

{metaspn_entities-0.1.0 → metaspn_entities-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.0
+Version: 0.1.4
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -55,3 +55,47 @@ 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.
+
+## M0 Ingestion Adapter
+
+For worker/runtime integration, use `resolve_normalized_social_signal(...)` with a
+normalized signal envelope.
+
+```python
+from metaspn_entities import EntityResolver, resolve_normalized_social_signal
+
+resolver = EntityResolver()
+signal = {
+    "source": "social.ingest",
+    "payload_type": "SocialPostSeen",
+    "payload": {
+        "platform": "twitter",
+        "author_handle": "@some_handle",
+        "profile_url": "https://example.com/profiles/some-handle",
+    },
+}
+
+result = resolve_normalized_social_signal(resolver, signal)
+print(result.entity_id, result.confidence)
+for event in result.emitted_events:
+    print(event.event_type, event.payload)
+```
+
+Adapter behavior:
+- Extracts deterministic identifier candidates from normalized payloads.
+- Resolves a primary identifier, then adds remaining identifiers as aliases.
+- Returns only events produced during the adapter call.

metaspn_entities-0.1.4/README.md

@@ -0,0 +1,76 @@
+# metaspn-entities
+
+Identity layer for MetaSPN systems.
+
+## Features
+
+- Canonical entity IDs
+- Deterministic identifier normalization + alias resolution
+- Merge history and reversible soft undo
+- SQLite backend using stdlib `sqlite3`
+- Event emission payloads for `EntityResolved`, `EntityMerged`, `EntityAliasAdded`
+- Optional filesystem snapshot export
+
+## Quick usage
+
+```python
+from metaspn_entities import EntityResolver
+
+resolver = EntityResolver()
+resolution = resolver.resolve("twitter_handle", "@some_handle")
+events = resolver.drain_events()
+print(resolution.entity_id, resolution.confidence)
+```
+
+## API notes
+
+- `resolve(identifier_type, value, context=None) -> EntityResolution`
+- `add_alias(entity_id, identifier_type, value, ...)`
+- `merge_entities(from_entity_id, to_entity_id, reason, ...)`
+- `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.
+
+## M0 Ingestion Adapter
+
+For worker/runtime integration, use `resolve_normalized_social_signal(...)` with a
+normalized signal envelope.
+
+```python
+from metaspn_entities import EntityResolver, resolve_normalized_social_signal
+
+resolver = EntityResolver()
+signal = {
+    "source": "social.ingest",
+    "payload_type": "SocialPostSeen",
+    "payload": {
+        "platform": "twitter",
+        "author_handle": "@some_handle",
+        "profile_url": "https://example.com/profiles/some-handle",
+    },
+}
+
+result = resolve_normalized_social_signal(resolver, signal)
+print(result.entity_id, result.confidence)
+for event in result.emitted_events:
+    print(event.event_type, event.payload)
+```
+
+Adapter behavior:
+- Extracts deterministic identifier candidates from normalized payloads.
+- Resolves a primary identifier, then adds remaining identifiers as aliases.
+- Returns only events produced during the adapter call.

{metaspn_entities-0.1.0 → metaspn_entities-0.1.4}/metaspn_entities/__init__.py

@@ -1,9 +1,12 @@
+from .adapter import SignalResolutionResult, resolve_normalized_social_signal
 from .events import EmittedEvent
 from .models import EntityResolution
 from .resolver import EntityResolver
 from .sqlite_backend import SQLiteEntityStore
 
 __all__ = [
+    "resolve_normalized_social_signal",
+    "SignalResolutionResult",
     "EntityResolver",
     "EntityResolution",
     "EmittedEvent",

metaspn_entities-0.1.4/metaspn_entities/adapter.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Tuple
+
+from .events import EmittedEvent
+from .models import EntityType
+from .resolver import EntityResolver
+
+
+@dataclass(frozen=True)
+class SignalResolutionResult:
+    entity_id: str
+    confidence: float
+    emitted_events: List[EmittedEvent]
+
+
+def resolve_normalized_social_signal(
+    resolver: EntityResolver,
+    signal_envelope: Mapping[str, Any] | Any,
+    *,
+    default_entity_type: str = EntityType.PERSON,
+    caused_by: str = "m0-ingestion",
+) -> SignalResolutionResult:
+    """Resolve a normalized social signal envelope into a canonical entity.
+
+    The adapter is intentionally deterministic:
+    - Identifier extraction order is fixed.
+    - Primary resolution always uses the highest-priority available identifier.
+    - Remaining identifiers are added as aliases in deterministic order.
+    """
+
+    # Keep adapter call output scoped to actions taken in this invocation only.
+    resolver.drain_events()
+
+    envelope = _coerce_envelope(signal_envelope)
+    payload = _coerce_payload(envelope.get("payload"))
+    source = str(envelope.get("source") or "unknown-source")
+
+    identifiers = _extract_identifiers(payload)
+    if not identifiers:
+        raise ValueError("No resolvable identifiers found in normalized social signal payload")
+
+    primary_type, primary_value, primary_confidence = identifiers[0]
+    resolution = resolver.resolve(
+        primary_type,
+        primary_value,
+        context={
+            "confidence": primary_confidence,
+            "entity_type": default_entity_type,
+            "caused_by": caused_by,
+            "provenance": source,
+        },
+    )
+
+    for alias_type, alias_value, alias_confidence in identifiers[1:]:
+        resolver.add_alias(
+            resolution.entity_id,
+            alias_type,
+            alias_value,
+            confidence=alias_confidence,
+            caused_by=caused_by,
+            provenance=source,
+        )
+
+    emitted = resolver.drain_events()
+    return SignalResolutionResult(
+        entity_id=resolution.entity_id,
+        confidence=resolution.confidence,
+        emitted_events=emitted,
+    )
+
+
+def _coerce_envelope(signal_envelope: Mapping[str, Any] | Any) -> Dict[str, Any]:
+    if isinstance(signal_envelope, Mapping):
+        return dict(signal_envelope)
+    if hasattr(signal_envelope, "to_dict") and callable(signal_envelope.to_dict):
+        return dict(signal_envelope.to_dict())
+    raise TypeError("signal_envelope must be a mapping or provide to_dict()")
+
+
+def _coerce_payload(payload: Any) -> Dict[str, Any]:
+    if payload is None:
+        return {}
+    if isinstance(payload, Mapping):
+        return dict(payload)
+    if hasattr(payload, "to_dict") and callable(payload.to_dict):
+        return dict(payload.to_dict())
+    raise TypeError("signal payload must be a mapping or provide to_dict()")
+
+
+def _extract_identifiers(payload: Dict[str, Any]) -> List[Tuple[str, str, float]]:
+    platform = str(payload.get("platform") or "").strip().lower()
+
+    candidates: List[Tuple[int, str, str, float]] = []
+
+    # Highest confidence identifiers first.
+    if isinstance(payload.get("email"), str) and payload["email"].strip():
+        candidates.append((0, "email", payload["email"].strip(), 0.98))
+
+    for key in ("profile_url", "author_url", "canonical_url"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            candidates.append((1, "canonical_url", value.strip(), 0.96))
+            break
+
+    handle = payload.get("author_handle") or payload.get("handle")
+    if isinstance(handle, str) and handle.strip():
+        handle_type = f"{platform}_handle" if platform else "handle"
+        candidates.append((2, handle_type, handle.strip(), 0.93))
+
+    if isinstance(payload.get("domain"), str) and payload["domain"].strip():
+        candidates.append((3, "domain", payload["domain"].strip(), 0.9))
+
+    for key in ("display_name", "name"):
+        value = payload.get(key)
+        if isinstance(value, str) and value.strip():
+            candidates.append((4, "name", value.strip(), 0.7))
+            break
+
+    # Deduplicate by (identifier_type, raw value) while preserving deterministic order.
+    seen: set[Tuple[str, str]] = set()
+    ordered: List[Tuple[str, str, float]] = []
+    for _, id_type, id_value, confidence in sorted(candidates, key=lambda c: (c[0], c[1], c[2])):
+        key = (id_type, id_value)
+        if key in seen:
+            continue
+        seen.add(key)
+        ordered.append((id_type, id_value, confidence))
+
+    return ordered

metaspn_entities-0.1.4/metaspn_entities/events.py

@@ -0,0 +1,65 @@
+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:
+    event_type: str
+    payload: Dict[str, Any]
+
+
+class EventFactory:
+    @staticmethod
+    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,
+                "resolver": resolver,
+                "resolved_at": EventFactory._now().isoformat(),
+                "confidence": confidence,
+                "schema_version": DEFAULT_SCHEMA_VERSION,
+            },
+        )
+
+    @staticmethod
+    def entity_merged(entity_id: str, merged_from: tuple[str, ...], reason: str | None = None) -> EmittedEvent:
+        return EmittedEvent(
+            event_type="EntityMerged",
+            payload={
+                "entity_id": entity_id,
+                "merged_from": list(merged_from),
+                "merged_at": EventFactory._now().isoformat(),
+                "reason": reason,
+                "schema_version": DEFAULT_SCHEMA_VERSION,
+            },
+        )
+
+    @staticmethod
+    def entity_alias_added(entity_id: str, alias: str, alias_type: str) -> EmittedEvent:
+        return EmittedEvent(
+            event_type="EntityAliasAdded",
+            payload={
+                "entity_id": entity_id,
+                "alias": alias,
+                "alias_type": alias_type,
+                "added_at": EventFactory._now().isoformat(),
+                "schema_version": DEFAULT_SCHEMA_VERSION,
+            },
+        )

{metaspn_entities-0.1.0 → metaspn_entities-0.1.4}/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 → metaspn_entities-0.1.4}/metaspn_entities.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.0
+Version: 0.1.4
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -55,3 +55,47 @@ 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.
+
+## M0 Ingestion Adapter
+
+For worker/runtime integration, use `resolve_normalized_social_signal(...)` with a
+normalized signal envelope.
+
+```python
+from metaspn_entities import EntityResolver, resolve_normalized_social_signal
+
+resolver = EntityResolver()
+signal = {
+    "source": "social.ingest",
+    "payload_type": "SocialPostSeen",
+    "payload": {
+        "platform": "twitter",
+        "author_handle": "@some_handle",
+        "profile_url": "https://example.com/profiles/some-handle",
+    },
+}
+
+result = resolve_normalized_social_signal(resolver, signal)
+print(result.entity_id, result.confidence)
+for event in result.emitted_events:
+    print(event.event_type, event.payload)
+```
+
+Adapter behavior:
+- Extracts deterministic identifier candidates from normalized payloads.
+- Resolves a primary identifier, then adds remaining identifiers as aliases.
+- Returns only events produced during the adapter call.

{metaspn_entities-0.1.0 → metaspn_entities-0.1.4}/metaspn_entities.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 metaspn_entities/__init__.py
+metaspn_entities/adapter.py
 metaspn_entities/events.py
 metaspn_entities/models.py
 metaspn_entities/normalize.py
@@ -12,4 +13,6 @@ metaspn_entities.egg-info/SOURCES.txt
 metaspn_entities.egg-info/dependency_links.txt
 metaspn_entities.egg-info/requires.txt
 metaspn_entities.egg-info/top_level.txt
+tests/test_adapter.py
+tests/test_event_contract.py
 tests/test_resolver.py

{metaspn_entities-0.1.0 → metaspn_entities-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "metaspn-entities"
-version = "0.1.0"
+version = "0.1.4"
 description = "Canonical entity resolution, aliasing, and merges for MetaSPN systems"
 readme = "README.md"
 requires-python = ">=3.10"

metaspn_entities-0.1.4/tests/test_adapter.py

@@ -0,0 +1,136 @@
+import importlib
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+from metaspn_entities import SQLiteEntityStore
+from metaspn_entities.adapter import resolve_normalized_social_signal
+from metaspn_entities.resolver import EntityResolver
+
+
+class AdapterTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.db_path = str(Path(self.tempdir.name) / "entities.db")
+        self.store = SQLiteEntityStore(self.db_path)
+        self.resolver = EntityResolver(self.store)
+
+    def tearDown(self) -> None:
+        self.store.close()
+        self.tempdir.cleanup()
+
+    def test_same_author_over_multiple_posts(self) -> None:
+        first_signal = {
+            "source": "social.ingest",
+            "payload_type": "SocialPostSeen",
+            "payload": {
+                "platform": "twitter",
+                "post_id": "p1",
+                "author_handle": "@same_author",
+                "url": "https://x.com/same_author/status/1",
+            },
+        }
+        second_signal = {
+            "source": "social.ingest",
+            "payload_type": "SocialPostSeen",
+            "payload": {
+                "platform": "twitter",
+                "post_id": "p2",
+                "author_handle": "same_author",
+                "url": "https://x.com/same_author/status/2",
+            },
+        }
+
+        first = resolve_normalized_social_signal(self.resolver, first_signal)
+        second = resolve_normalized_social_signal(self.resolver, second_signal)
+
+        self.assertEqual(first.entity_id, second.entity_id)
+
+    def test_cross_platform_identifier_normalization(self) -> None:
+        twitter_signal = {
+            "source": "social.ingest",
+            "payload_type": "SocialPostSeen",
+            "payload": {
+                "platform": "twitter",
+                "post_id": "p100",
+                "author_handle": "alice",
+                "profile_url": "https://example.com/team/alice/",
+            },
+        }
+        linkedin_signal = {
+            "source": "social.ingest",
+            "payload_type": "ProfileSnapshotSeen",
+            "payload": {
+                "platform": "linkedin",
+                "profile_id": "li-77",
+                "handle": "alice-smith",
+                "profile_url": "http://www.example.com/team/alice",
+            },
+        }
+
+        first = resolve_normalized_social_signal(self.resolver, twitter_signal)
+        second = resolve_normalized_social_signal(self.resolver, linkedin_signal)
+
+        self.assertEqual(first.entity_id, second.entity_id)
+
+    def test_idempotent_rerun_behavior(self) -> None:
+        signal = {
+            "source": "social.ingest",
+            "payload_type": "SocialPostSeen",
+            "payload": {
+                "platform": "twitter",
+                "post_id": "idempotent-1",
+                "author_handle": "rerun_author",
+                "profile_url": "https://example.org/rerun_author",
+            },
+        }
+
+        first = resolve_normalized_social_signal(self.resolver, signal)
+        second = resolve_normalized_social_signal(self.resolver, signal)
+
+        self.assertEqual(first.entity_id, second.entity_id)
+        self.assertEqual(
+            [event.event_type for event in second.emitted_events],
+            ["EntityResolved"],
+        )
+
+    def test_emitted_events_parse_with_metaspn_schemas(self) -> None:
+        entities_module = None
+        try:
+            entities_module = importlib.import_module("metaspn_schemas.entities")
+        except Exception:
+            sibling_src = Path(__file__).resolve().parents[2] / "metaspn-schemas" / "src"
+            if sibling_src.exists():
+                sys.path.insert(0, str(sibling_src))
+                entities_module = importlib.import_module("metaspn_schemas.entities")
+
+        if entities_module is None:
+            self.skipTest("metaspn_schemas is unavailable")
+
+        signal = {
+            "source": "social.ingest",
+            "payload_type": "SocialPostSeen",
+            "payload": {
+                "platform": "twitter",
+                "post_id": "schema-1",
+                "author_handle": "schema_user",
+                "profile_url": "https://example.net/schema_user",
+            },
+        }
+
+        result = resolve_normalized_social_signal(self.resolver, signal)
+        for event in result.emitted_events:
+            if event.event_type == "EntityResolved":
+                parsed = entities_module.EntityResolved.from_dict(event.payload)
+                self.assertEqual(parsed.entity_id, result.entity_id)
+            elif event.event_type == "EntityAliasAdded":
+                parsed = entities_module.EntityAliasAdded.from_dict(event.payload)
+                self.assertTrue(parsed.alias)
+            elif event.event_type == "EntityMerged":
+                parsed = entities_module.EntityMerged.from_dict(event.payload)
+                self.assertTrue(parsed.merged_from)
+
+
+if __name__ == "__main__":
+    unittest.main()

metaspn_entities-0.1.4/tests/test_event_contract.py

@@ -0,0 +1,98 @@
+import importlib
+import sys
+import tempfile
+import unittest
+from datetime import datetime
+from pathlib import Path
+
+from metaspn_entities import EntityResolver, SQLiteEntityStore
+
+
+class EventContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.tempdir = tempfile.TemporaryDirectory()
+        self.db_path = str(Path(self.tempdir.name) / "entities.db")
+        self.store = SQLiteEntityStore(self.db_path)
+        self.resolver = EntityResolver(self.store)
+
+    def tearDown(self) -> None:
+        self.store.close()
+        self.tempdir.cleanup()
+
+    def test_entity_resolved_payload_shape(self) -> None:
+        self.resolver.resolve("twitter_handle", "contract_user")
+        event = self.resolver.drain_events()[-1]
+
+        self.assertEqual(event.event_type, "EntityResolved")
+        self.assertEqual(
+            sorted(event.payload.keys()),
+            ["confidence", "entity_id", "resolved_at", "resolver", "schema_version"],
+        )
+        self.assertIsInstance(event.payload["resolver"], str)
+        self.assertGreaterEqual(float(event.payload["confidence"]), 0.0)
+        datetime.fromisoformat(event.payload["resolved_at"])
+
+    def test_entity_merged_payload_shape(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "merge_a")
+        b = self.resolver.resolve("twitter_handle", "merge_b")
+        self.resolver.drain_events()
+
+        self.resolver.merge_entities(a.entity_id, b.entity_id, reason="dedupe")
+        event = self.resolver.drain_events()[-1]
+
+        self.assertEqual(event.event_type, "EntityMerged")
+        self.assertEqual(
+            sorted(event.payload.keys()),
+            ["entity_id", "merged_at", "merged_from", "reason", "schema_version"],
+        )
+        self.assertEqual(event.payload["entity_id"], b.entity_id)
+        self.assertEqual(event.payload["merged_from"], [a.entity_id])
+        datetime.fromisoformat(event.payload["merged_at"])
+
+    def test_entity_alias_added_payload_shape(self) -> None:
+        created = self.resolver.resolve("twitter_handle", "alias_contract")
+        self.resolver.drain_events()
+
+        events = self.resolver.add_alias(created.entity_id, "email", "alias@example.com")
+        self.assertEqual(len(events), 1)
+        event = events[0]
+
+        self.assertEqual(event.event_type, "EntityAliasAdded")
+        self.assertEqual(
+            sorted(event.payload.keys()),
+            ["added_at", "alias", "alias_type", "entity_id", "schema_version"],
+        )
+        self.assertEqual(event.payload["entity_id"], created.entity_id)
+        self.assertEqual(event.payload["alias_type"], "email")
+        self.assertEqual(event.payload["alias"], "alias@example.com")
+        datetime.fromisoformat(event.payload["added_at"])
+
+    def test_schema_round_trip_when_metaspn_schemas_is_available(self) -> None:
+        # Try import from installed package first, then from sibling checkout if present.
+        entities_module = None
+        try:
+            entities_module = importlib.import_module("metaspn_schemas.entities")
+        except Exception:
+            sibling_src = Path(__file__).resolve().parents[2] / "metaspn-schemas" / "src"
+            if sibling_src.exists():
+                sys.path.insert(0, str(sibling_src))
+                entities_module = importlib.import_module("metaspn_schemas.entities")
+
+        if entities_module is None:
+            self.skipTest("metaspn_schemas is unavailable")
+
+        self.resolver.resolve("twitter_handle", "roundtrip_user")
+        resolved_event = self.resolver.drain_events()[-1]
+
+        entity_resolved = entities_module.EntityResolved.from_dict(resolved_event.payload)
+        self.assertEqual(entity_resolved.entity_id, resolved_event.payload["entity_id"])
+
+        created = self.resolver.resolve("twitter_handle", "roundtrip_alias")
+        self.resolver.drain_events()
+        alias_event = self.resolver.add_alias(created.entity_id, "email", "rt@example.com")[0]
+        entity_alias = entities_module.EntityAliasAdded.from_dict(alias_event.payload)
+        self.assertEqual(entity_alias.alias, "rt@example.com")
+
+
+if __name__ == "__main__":
+    unittest.main()

metaspn_entities-0.1.0/README.md

@@ -1,32 +0,0 @@
-# metaspn-entities
-
-Identity layer for MetaSPN systems.
-
-## Features
-
-- Canonical entity IDs
-- Deterministic identifier normalization + alias resolution
-- Merge history and reversible soft undo
-- SQLite backend using stdlib `sqlite3`
-- Event emission payloads for `EntityResolved`, `EntityMerged`, `EntityAliasAdded`
-- Optional filesystem snapshot export
-
-## Quick usage
-
-```python
-from metaspn_entities import EntityResolver
-
-resolver = EntityResolver()
-resolution = resolver.resolve("twitter_handle", "@some_handle")
-events = resolver.drain_events()
-print(resolution.entity_id, resolution.confidence)
-```
-
-## API notes
-
-- `resolve(identifier_type, value, context=None) -> EntityResolution`
-- `add_alias(entity_id, identifier_type, value, ...)`
-- `merge_entities(from_entity_id, to_entity_id, reason, ...)`
-- `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

metaspn_entities-0.1.0/metaspn_entities/events.py

@@ -1,49 +0,0 @@
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Any, Dict
-
-
-@dataclass(frozen=True)
-class EmittedEvent:
-    event_type: str
-    payload: Dict[str, Any]
-
-
-class EventFactory:
-    @staticmethod
-    def entity_resolved(entity_id: str, identifier_type: str, value: str, confidence: float, created_new_entity: bool) -> EmittedEvent:
-        return EmittedEvent(
-            event_type="EntityResolved",
-            payload={
-                "entity_id": entity_id,
-                "identifier_type": identifier_type,
-                "value": value,
-                "confidence": confidence,
-                "created_new_entity": created_new_entity,
-            },
-        )
-
-    @staticmethod
-    def entity_merged(from_entity_id: str, to_entity_id: str, reason: str, caused_by: str) -> EmittedEvent:
-        return EmittedEvent(
-            event_type="EntityMerged",
-            payload={
-                "from_entity_id": from_entity_id,
-                "to_entity_id": to_entity_id,
-                "reason": reason,
-                "caused_by": caused_by,
-            },
-        )
-
-    @staticmethod
-    def entity_alias_added(entity_id: str, identifier_type: str, normalized_value: str, caused_by: str) -> EmittedEvent:
-        return EmittedEvent(
-            event_type="EntityAliasAdded",
-            payload={
-                "entity_id": entity_id,
-                "identifier_type": identifier_type,
-                "normalized_value": normalized_value,
-                "caused_by": caused_by,
-            },
-        )