metaspn-entities 0.1.6__tar.gz → 0.1.8__tar.gz

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.6
+Version: 0.1.8
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -122,3 +122,29 @@ The recommendation context includes:
 - preferred channel hint
 - relationship stage hint (`cold` / `warm` / `engaged`)
 - merge-safe continuity fields keyed to canonical entity IDs
+
+## M3 Outcome Attribution API
+
+Outcome evaluators can map attempt/outcome references back to canonical entity lineage:
+
+- `resolver.attribute_outcome(references)`
+
+Supported references include `entity_id`, `email`, `canonical_url`, handles, domains, and names.
+
+Attribution guarantees:
+- canonical merge redirects are resolved before returning `entity_id`
+- output includes explicit confidence for downstream learning logic
+- deterministic tie-breaks are applied by score, then hit count, then entity ID
+
+## Demo Pipeline Invocation
+
+For demo digest identity resolution (without direct DB queries in renderer), use:
+
+- `resolve_demo_social_identity(resolver, social_payload)`
+
+Returned payload includes:
+- `entity_id`
+- `confidence`
+- `matched_identifiers`
+- `why` metadata (confidence summary, counts, relationship hint)
+- emitted event payloads for auditability

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/README.md

@@ -97,3 +97,29 @@ The recommendation context includes:
 - preferred channel hint
 - relationship stage hint (`cold` / `warm` / `engaged`)
 - merge-safe continuity fields keyed to canonical entity IDs
+
+## M3 Outcome Attribution API
+
+Outcome evaluators can map attempt/outcome references back to canonical entity lineage:
+
+- `resolver.attribute_outcome(references)`
+
+Supported references include `entity_id`, `email`, `canonical_url`, handles, domains, and names.
+
+Attribution guarantees:
+- canonical merge redirects are resolved before returning `entity_id`
+- output includes explicit confidence for downstream learning logic
+- deterministic tie-breaks are applied by score, then hit count, then entity ID
+
+## Demo Pipeline Invocation
+
+For demo digest identity resolution (without direct DB queries in renderer), use:
+
+- `resolve_demo_social_identity(resolver, social_payload)`
+
+Returned payload includes:
+- `entity_id`
+- `confidence`
+- `matched_identifiers`
+- `why` metadata (confidence summary, counts, relationship hint)
+- emitted event payloads for auditability

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities/__init__.py

@@ -1,5 +1,7 @@
 from .adapter import SignalResolutionResult, resolve_normalized_social_signal
+from .attribution import OutcomeAttribution
 from .context import RecommendationContext, EntityContext, build_confidence_summary, build_recommendation_context
+from .demo import resolve_demo_social_identity
 from .events import EmittedEvent
 from .models import EntityResolution
 from .resolver import EntityResolver
@@ -8,6 +10,8 @@ from .sqlite_backend import SQLiteEntityStore
 __all__ = [
     "resolve_normalized_social_signal",
     "SignalResolutionResult",
+    "OutcomeAttribution",
+    "resolve_demo_social_identity",
     "EntityContext",
     "RecommendationContext",
     "build_confidence_summary",

metaspn_entities-0.1.8/metaspn_entities/attribution.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple
+
+from .normalize import normalize_identifier
+
+
+@dataclass(frozen=True)
+class OutcomeAttribution:
+    entity_id: Optional[str]
+    confidence: float
+    matched_references: List[Dict[str, Any]] = field(default_factory=list)
+    strategy: str = "confidence-weighted-reference-v1"
+
+
+def normalize_outcome_references(references: Mapping[str, Any] | Sequence[Mapping[str, Any]]) -> List[Tuple[str, str]]:
+    refs: List[Tuple[str, str]] = []
+    if isinstance(references, Mapping):
+        for raw_type in sorted(references):
+            value = references[raw_type]
+            if value is None:
+                continue
+            if isinstance(value, str) and value.strip():
+                refs.append((str(raw_type), value.strip()))
+        return refs
+
+    for item in references:
+        id_type = str(item.get("identifier_type") or item.get("type") or "").strip()
+        value = str(item.get("value") or "").strip()
+        if not id_type or not value:
+            continue
+        refs.append((id_type, value))
+    return refs
+
+
+def rank_entity_candidates(
+    references: Iterable[Tuple[str, str]],
+    resolve_reference: Any,
+) -> OutcomeAttribution:
+    candidate_scores: Dict[str, float] = {}
+    candidate_hits: Dict[str, int] = {}
+    matched: List[Dict[str, Any]] = []
+    total_refs = 0
+
+    for identifier_type, value in references:
+        total_refs += 1
+        match = resolve_reference(identifier_type, value)
+        matched.append(
+            {
+                "identifier_type": identifier_type,
+                "value": value,
+                "normalized_value": match.get("normalized_value"),
+                "matched_entity_id": match.get("entity_id"),
+                "reference_confidence": float(match.get("confidence", 0.0)),
+            }
+        )
+        entity_id = match.get("entity_id")
+        confidence = float(match.get("confidence", 0.0))
+        if entity_id:
+            candidate_scores[entity_id] = candidate_scores.get(entity_id, 0.0) + confidence
+            candidate_hits[entity_id] = candidate_hits.get(entity_id, 0) + 1
+
+    if not candidate_scores:
+        return OutcomeAttribution(entity_id=None, confidence=0.0, matched_references=matched)
+
+    ranked = sorted(
+        candidate_scores.items(),
+        key=lambda kv: (
+            -kv[1],
+            -candidate_hits.get(kv[0], 0),
+            kv[0],
+        ),
+    )
+    best_entity_id, best_score = ranked[0]
+    denom = max(1, total_refs)
+    normalized_confidence = min(1.0, round(best_score / float(denom), 6))
+    return OutcomeAttribution(
+        entity_id=best_entity_id,
+        confidence=normalized_confidence,
+        matched_references=matched,
+    )
+
+
+def normalize_reference(identifier_type: str, value: str) -> Tuple[str, str]:
+    if identifier_type == "entity_id":
+        return identifier_type, value
+    return identifier_type, normalize_identifier(identifier_type, value)

metaspn_entities-0.1.8/metaspn_entities/demo.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping
+
+from .models import EntityType
+from .resolver import EntityResolver
+
+
+def resolve_demo_social_identity(
+    resolver: EntityResolver,
+    social_payload: Mapping[str, Any],
+    *,
+    caused_by: str = "demo-pipeline",
+) -> Dict[str, Any]:
+    platform = str(social_payload.get("platform") or "").strip().lower()
+    source = str(social_payload.get("source") or social_payload.get("provenance") or "demo")
+
+    handle = social_payload.get("author_handle") or social_payload.get("handle")
+    if not isinstance(handle, str) or not handle.strip():
+        raise ValueError("demo payload requires author_handle or handle")
+    handle = handle.strip()
+
+    handle_type = f"{platform}_handle" if platform else "handle"
+    resolution = resolver.resolve(
+        handle_type,
+        handle,
+        context={
+            "entity_type": EntityType.PERSON,
+            "caused_by": caused_by,
+            "provenance": source,
+            "confidence": 0.93,
+        },
+    )
+
+    for key in ("profile_url", "author_url", "canonical_url"):
+        url = social_payload.get(key)
+        if isinstance(url, str) and url.strip():
+            resolver.add_alias(
+                resolution.entity_id,
+                "canonical_url",
+                url.strip(),
+                confidence=0.96,
+                caused_by=caused_by,
+                provenance=source,
+            )
+            break
+
+    email = social_payload.get("email")
+    if isinstance(email, str) and email.strip():
+        resolver.add_alias(
+            resolution.entity_id,
+            "email",
+            email.strip(),
+            confidence=0.98,
+            caused_by=caused_by,
+            provenance=source,
+        )
+
+    canonical_id = resolver.store.canonical_entity_id(resolution.entity_id)
+    context = resolver.entity_context(canonical_id)
+    digest_payload = {
+        "entity_id": canonical_id,
+        "confidence": context.confidence_summary["overall_confidence"],
+        "matched_identifiers": [
+            {
+                "identifier_type": item["identifier_type"],
+                "value": item["value"],
+                "confidence": item["confidence"],
+                "last_seen_at": item["last_seen_at"],
+            }
+            for item in context.identifiers
+        ],
+        "why": {
+            "matched_identifier_count": len(context.identifiers),
+            "alias_count": len(context.aliases),
+            "confidence_summary": context.confidence_summary,
+            "relationship_stage_hint": resolver.recommendation_context(canonical_id).relationship_stage_hint,
+        },
+        "events": [event.payload for event in resolver.drain_events()],
+    }
+    return digest_payload

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities/normalize.py

@@ -7,7 +7,17 @@ def normalize_identifier(identifier_type: str, value: str) -> str:
     identifier_type = identifier_type.strip().lower()
     value = value.strip()
 
-    if identifier_type in {"twitter_handle", "github_handle", "handle"}:
+    if identifier_type in {
+        "twitter_handle",
+        "x_handle",
+        "linkedin_handle",
+        "github_handle",
+        "instagram_handle",
+        "tiktok_handle",
+        "bluesky_handle",
+        "youtube_handle",
+        "handle",
+    }:
         return value.lstrip("@").lower()
 
     if identifier_type == "email":

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities/resolver.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
+from .attribution import OutcomeAttribution, normalize_outcome_references, normalize_reference, rank_entity_candidates
 from .context import RecommendationContext, EntityContext, build_confidence_summary, build_recommendation_context
 from .events import EmittedEvent, EventFactory
 from .models import (
@@ -166,6 +167,34 @@ class EntityResolver:
         identifiers = self.store.list_identifier_records_for_entity(canonical_id)
         return build_recommendation_context(canonical_id, aliases, identifiers)
 
+    def attribute_outcome(self, references: Any) -> OutcomeAttribution:
+        refs = normalize_outcome_references(references)
+
+        def _resolve_ref(identifier_type: str, value: str) -> Dict[str, Any]:
+            raw_type, normalized = normalize_reference(identifier_type, value)
+            if raw_type == "entity_id":
+                entity = self.store.get_entity(normalized)
+                if not entity:
+                    return {"entity_id": None, "confidence": 0.0, "normalized_value": normalized}
+                return {
+                    "entity_id": self.store.canonical_entity_id(str(entity["entity_id"])),
+                    "confidence": 0.99,
+                    "normalized_value": normalized,
+                }
+
+            alias = self.store.find_alias(raw_type, normalized)
+            if not alias:
+                return {"entity_id": None, "confidence": 0.0, "normalized_value": normalized}
+
+            canonical = self.store.canonical_entity_id(str(alias["entity_id"]))
+            identifier = self.store.get_identifier(raw_type, normalized)
+            alias_conf = float(alias["confidence"])
+            identifier_conf = float(identifier["confidence"]) if identifier else 0.0
+            confidence = round(max(alias_conf, identifier_conf), 6)
+            return {"entity_id": canonical, "confidence": confidence, "normalized_value": normalized}
+
+        return rank_entity_candidates(refs, _resolve_ref)
+
     def export_snapshot(self, output_path: str) -> None:
         self.store.export_snapshot(output_path)
 

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities/sqlite_backend.py

@@ -103,6 +103,12 @@ class SQLiteEntityStore:
             (identifier_type, normalized_value),
         ).fetchone()
 
+    def get_identifier(self, identifier_type: str, normalized_value: str) -> Optional[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM identifiers WHERE identifier_type = ? AND normalized_value = ?",
+            (identifier_type, normalized_value),
+        ).fetchone()
+
     def upsert_identifier(
         self,
         identifier_type: str,

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.6
+Version: 0.1.8
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -122,3 +122,29 @@ The recommendation context includes:
 - preferred channel hint
 - relationship stage hint (`cold` / `warm` / `engaged`)
 - merge-safe continuity fields keyed to canonical entity IDs
+
+## M3 Outcome Attribution API
+
+Outcome evaluators can map attempt/outcome references back to canonical entity lineage:
+
+- `resolver.attribute_outcome(references)`
+
+Supported references include `entity_id`, `email`, `canonical_url`, handles, domains, and names.
+
+Attribution guarantees:
+- canonical merge redirects are resolved before returning `entity_id`
+- output includes explicit confidence for downstream learning logic
+- deterministic tie-breaks are applied by score, then hit count, then entity ID
+
+## Demo Pipeline Invocation
+
+For demo digest identity resolution (without direct DB queries in renderer), use:
+
+- `resolve_demo_social_identity(resolver, social_payload)`
+
+Returned payload includes:
+- `entity_id`
+- `confidence`
+- `matched_identifiers`
+- `why` metadata (confidence summary, counts, relationship hint)
+- emitted event payloads for auditability

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/metaspn_entities.egg-info/SOURCES.txt

@@ -3,7 +3,9 @@ README.md
 pyproject.toml
 metaspn_entities/__init__.py
 metaspn_entities/adapter.py
+metaspn_entities/attribution.py
 metaspn_entities/context.py
+metaspn_entities/demo.py
 metaspn_entities/events.py
 metaspn_entities/models.py
 metaspn_entities/normalize.py
@@ -15,7 +17,9 @@ 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_attribution.py
 tests/test_context.py
+tests/test_demo_support.py
 tests/test_event_contract.py
 tests/test_recommendation_context.py
 tests/test_resolver.py

{metaspn_entities-0.1.6 → metaspn_entities-0.1.8}/pyproject.toml

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

metaspn_entities-0.1.8/tests/test_attribution.py

@@ -0,0 +1,66 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from metaspn_entities.resolver import EntityResolver
+from metaspn_entities.sqlite_backend import SQLiteEntityStore
+
+
+class AttributionTests(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_merge_after_attempt_before_outcome(self) -> None:
+        attempt = self.resolver.resolve("twitter_handle", "attempt_user")
+        winner = self.resolver.resolve("twitter_handle", "winner_user")
+        self.resolver.add_alias(attempt.entity_id, "email", "attempt@example.com", confidence=0.9)
+
+        # Merge happens between attempt capture and outcome ingestion.
+        self.resolver.merge_entities(attempt.entity_id, winner.entity_id, reason="dedupe")
+
+        result = self.resolver.attribute_outcome(
+            {
+                "entity_id": attempt.entity_id,
+                "email": "attempt@example.com",
+            }
+        )
+        self.assertEqual(result.entity_id, winner.entity_id)
+        self.assertGreater(result.confidence, 0.9)
+
+    def test_undo_merge_edge_case(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "undo_attr_a")
+        b = self.resolver.resolve("twitter_handle", "undo_attr_b")
+        self.resolver.merge_entities(a.entity_id, b.entity_id, reason="dedupe")
+        self.resolver.undo_merge(a.entity_id, b.entity_id)
+
+        # After undo implementation, b redirects to a.
+        result = self.resolver.attribute_outcome({"entity_id": b.entity_id})
+        self.assertEqual(result.entity_id, a.entity_id)
+        self.assertAlmostEqual(result.confidence, 0.99, places=6)
+
+    def test_conflicting_aliases_tie_break_by_confidence(self) -> None:
+        high = self.resolver.resolve("twitter_handle", "high_conf")
+        low = self.resolver.resolve("twitter_handle", "low_conf")
+
+        self.resolver.add_alias(high.entity_id, "email", "high@example.com", confidence=0.95)
+        self.resolver.add_alias(low.entity_id, "canonical_url", "https://low.example.com/profile", confidence=0.60)
+
+        result = self.resolver.attribute_outcome(
+            {
+                "email": "HIGH@example.com",
+                "canonical_url": "https://low.example.com/profile/",
+            }
+        )
+        self.assertEqual(result.entity_id, high.entity_id)
+        self.assertAlmostEqual(result.confidence, 0.475, places=6)
+
+
+if __name__ == "__main__":
+    unittest.main()

metaspn_entities-0.1.8/tests/test_demo_support.py

@@ -0,0 +1,84 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from metaspn_entities.demo import resolve_demo_social_identity
+from metaspn_entities.resolver import EntityResolver
+from metaspn_entities.sqlite_backend import SQLiteEntityStore
+
+
+class DemoSupportTests(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_repeated_days_stable_entity(self) -> None:
+        day_1 = {
+            "platform": "x",
+            "author_handle": "@DemoAuthor",
+            "profile_url": "https://x.com/demoauthor",
+            "source": "demo.day1",
+        }
+        day_2 = {
+            "platform": "x",
+            "author_handle": "demoauthor",
+            "profile_url": "https://x.com/demoauthor/",
+            "source": "demo.day2",
+        }
+
+        first = resolve_demo_social_identity(self.resolver, day_1)
+        second = resolve_demo_social_identity(self.resolver, day_2)
+
+        self.assertEqual(first["entity_id"], second["entity_id"])
+
+    def test_alias_collision_merge_safe_continuity(self) -> None:
+        one = resolve_demo_social_identity(
+            self.resolver,
+            {
+                "platform": "twitter",
+                "author_handle": "alpha_demo",
+                "profile_url": "https://example.com/u/shared",
+                "source": "demo.a",
+            },
+        )
+        two = resolve_demo_social_identity(
+            self.resolver,
+            {
+                "platform": "linkedin",
+                "author_handle": "beta_demo",
+                "profile_url": "http://www.example.com/u/shared/",
+                "source": "demo.b",
+            },
+        )
+
+        # canonical_url collision should keep one canonical identity for both reruns.
+        self.assertEqual(one["entity_id"], two["entity_id"])
+
+    def test_digest_payload_contains_explainability_context(self) -> None:
+        payload = resolve_demo_social_identity(
+            self.resolver,
+            {
+                "platform": "bluesky",
+                "author_handle": "DigestUser",
+                "profile_url": "https://bsky.app/profile/digestuser",
+                "source": "demo.digest",
+            },
+        )
+
+        self.assertIn("entity_id", payload)
+        self.assertIn("confidence", payload)
+        self.assertIn("matched_identifiers", payload)
+        self.assertIn("why", payload)
+        self.assertIn("confidence_summary", payload["why"])
+        self.assertGreaterEqual(payload["why"]["matched_identifier_count"], 1)
+        self.assertIsInstance(payload["events"], list)
+
+
+if __name__ == "__main__":
+    unittest.main()