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

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/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.3.dist-info → metaspn_entities-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.3
+Version: 0.1.4
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -69,3 +69,33 @@ schema-compatible with `metaspn-schemas` entity events.
   - `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.3.dist-info → metaspn_entities-0.1.4.dist-info}/RECORD

@@ -1,11 +1,12 @@
-metaspn_entities/__init__.py,sha256=7hsZse74SfsKugEKs3P6hIyfSDuzDWdeUFQdnev2yBo,259
+metaspn_entities/__init__.py,sha256=BkVyTYAyQBV8h9EO66VAygcIoK4oPbPQe6wW6oMdMTk,407
+metaspn_entities/adapter.py,sha256=eNB5kr1tinav85WPA4YCldRDJBgb6uYe3ZWCRVjdOms,4654
 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.4.dist-info/licenses/LICENSE,sha256=tvVpto97dUnh1-KVYPs1rCr5dzyX8jUyNmT7F7ZPVAM,1077
+metaspn_entities-0.1.4.dist-info/METADATA,sha256=qg5xn2Rg0Aw4KTakgJTKchlUjodGHutwxYxCqiOYeAY,3436
+metaspn_entities-0.1.4.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+metaspn_entities-0.1.4.dist-info/top_level.txt,sha256=YP2V8Z1Statrs3YAI-tGvyC73vLjPHr9Vkal4yqXkhs,17
+metaspn_entities-0.1.4.dist-info/RECORD,,