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

metaspn_entities/__init__.py

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

metaspn_entities/context.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+
+@dataclass(frozen=True)
+class EntityContext:
+    entity_id: str
+    aliases: List[Dict[str, Any]]
+    identifiers: List[Dict[str, Any]]
+    recent_evidence: List[Dict[str, Any]]
+    confidence_summary: Dict[str, Any]
+
+
+@dataclass(frozen=True)
+class RecommendationContext:
+    entity_id: str
+    identity_confidence: float
+    activity_recency_days: float
+    interaction_history_summary: Dict[str, Any]
+    preferred_channel_hint: str
+    relationship_stage_hint: str
+    continuity: Dict[str, Any]
+
+
+def build_confidence_summary(
+    aliases: List[Dict[str, Any]],
+    identifiers: List[Dict[str, Any]],
+    evidence: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    identifier_confidences = sorted(float(item["confidence"]) for item in identifiers)
+    alias_confidences = sorted(float(item["confidence"]) for item in aliases)
+    source_set = sorted(
+        {
+            str(item.get("provenance"))
+            for item in evidence
+            if item.get("provenance") not in (None, "")
+        }
+    )
+
+    identifier_avg = _avg(identifier_confidences)
+    alias_avg = _avg(alias_confidences)
+    source_diversity = min(1.0, len(source_set) / 3.0)
+
+    overall = min(1.0, (0.65 * identifier_avg) + (0.25 * alias_avg) + (0.10 * source_diversity))
+    by_identifier_type = _rollup_by_identifier_type(identifiers)
+
+    return {
+        "overall_confidence": round(overall, 6),
+        "identifier_confidence_avg": round(identifier_avg, 6),
+        "alias_confidence_avg": round(alias_avg, 6),
+        "unique_source_count": len(source_set),
+        "evidence_count": len(evidence),
+        "by_identifier_type": by_identifier_type,
+    }
+
+
+def _avg(values: List[float]) -> float:
+    if not values:
+        return 0.0
+    return sum(values) / len(values)
+
+
+def _rollup_by_identifier_type(identifiers: List[Dict[str, Any]]) -> Dict[str, Dict[str, float]]:
+    grouped: Dict[str, List[float]] = {}
+    for item in identifiers:
+        key = str(item["identifier_type"])
+        grouped.setdefault(key, []).append(float(item["confidence"]))
+
+    rollup: Dict[str, Dict[str, float]] = {}
+    for key in sorted(grouped):
+        values = sorted(grouped[key])
+        rollup[key] = {
+            "count": float(len(values)),
+            "avg_confidence": round(_avg(values), 6),
+            "max_confidence": round(max(values), 6),
+        }
+    return rollup
+
+
+def build_recommendation_context(
+    entity_id: str,
+    aliases: List[Dict[str, Any]],
+    identifiers: List[Dict[str, Any]],
+    *,
+    now: datetime | None = None,
+) -> RecommendationContext:
+    current_now = now or datetime.now(timezone.utc)
+    evidence_count = len(identifiers)
+    recent_seen = _latest_seen(identifiers)
+    activity_recency_days = _recency_days(recent_seen, current_now)
+
+    summary = build_confidence_summary(aliases, identifiers, identifiers)
+    preferred_channel = _preferred_channel_hint(identifiers)
+    relationship_stage = _relationship_stage_hint(
+        evidence_count=evidence_count,
+        recency_days=activity_recency_days,
+        confidence=summary["overall_confidence"],
+    )
+
+    provenance_counts: Dict[str, int] = {}
+    for item in identifiers:
+        provenance = str(item.get("provenance") or "unknown")
+        provenance_counts[provenance] = provenance_counts.get(provenance, 0) + 1
+
+    interaction_history_summary = {
+        "evidence_count": evidence_count,
+        "distinct_sources": len(provenance_counts),
+        "sources": {k: provenance_counts[k] for k in sorted(provenance_counts)},
+    }
+
+    continuity = {
+        "canonical_entity_id": entity_id,
+        "alias_count": len(aliases),
+        "identifier_count": len(identifiers),
+    }
+
+    return RecommendationContext(
+        entity_id=entity_id,
+        identity_confidence=float(summary["overall_confidence"]),
+        activity_recency_days=activity_recency_days,
+        interaction_history_summary=interaction_history_summary,
+        preferred_channel_hint=preferred_channel,
+        relationship_stage_hint=relationship_stage,
+        continuity=continuity,
+    )
+
+
+def _latest_seen(identifiers: List[Dict[str, Any]]) -> datetime | None:
+    timestamps = [
+        _parse_iso(str(item.get("last_seen_at")))
+        for item in identifiers
+        if item.get("last_seen_at")
+    ]
+    clean = [ts for ts in timestamps if ts is not None]
+    if not clean:
+        return None
+    return max(clean)
+
+
+def _parse_iso(raw: str) -> datetime | None:
+    text = raw.strip()
+    if not text:
+        return None
+    if text.endswith("Z"):
+        text = text[:-1] + "+00:00"
+    try:
+        dt = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _recency_days(last_seen: datetime | None, now: datetime) -> float:
+    if last_seen is None:
+        return float("inf")
+    delta = now - last_seen
+    seconds = max(0.0, delta.total_seconds())
+    return round(seconds / 86400.0, 6)
+
+
+def _preferred_channel_hint(identifiers: List[Dict[str, Any]]) -> str:
+    weights = {
+        "email": 5,
+        "linkedin_handle": 4,
+        "twitter_handle": 3,
+        "github_handle": 3,
+        "canonical_url": 2,
+        "domain": 1,
+        "name": 0,
+    }
+    scores: Dict[str, int] = {}
+    for item in identifiers:
+        id_type = str(item["identifier_type"])
+        score = weights.get(id_type, 1)
+        scores[id_type] = scores.get(id_type, 0) + score
+    if not scores:
+        return "unknown"
+    return sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))[0][0]
+
+
+def _relationship_stage_hint(*, evidence_count: int, recency_days: float, confidence: float) -> str:
+    if evidence_count >= 6 and recency_days <= 30 and confidence >= 0.8:
+        return "engaged"
+    if evidence_count >= 3 and recency_days <= 90 and confidence >= 0.65:
+        return "warm"
+    return "cold"

metaspn_entities/resolver.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional
 
+from .context import RecommendationContext, EntityContext, build_confidence_summary, build_recommendation_context
 from .events import EmittedEvent, EventFactory
 from .models import (
     DEFAULT_MATCH_CONFIDENCE,
@@ -135,6 +136,36 @@ class EntityResolver:
     def aliases_for_entity(self, entity_id: str) -> List[Dict[str, Any]]:
         return self.store.list_aliases_for_entity(entity_id)
 
+    def confidence_summary(self, entity_id: str) -> Dict[str, Any]:
+        canonical_id = self.store.canonical_entity_id(entity_id)
+        aliases = self.store.list_aliases_for_entity(canonical_id)
+        identifiers = self.store.list_identifier_records_for_entity(canonical_id)
+        return build_confidence_summary(aliases, identifiers, identifiers)
+
+    def entity_context(self, entity_id: str, recent_limit: int = 10) -> EntityContext:
+        canonical_id = self.store.canonical_entity_id(entity_id)
+        aliases = self.store.list_aliases_for_entity(canonical_id)
+        identifiers = self.store.list_identifier_records_for_entity(canonical_id)
+        recent_evidence = sorted(
+            identifiers,
+            key=lambda row: (str(row["last_seen_at"]), str(row["identifier_type"]), str(row["normalized_value"])),
+            reverse=True,
+        )[: max(recent_limit, 0)]
+        summary = build_confidence_summary(aliases, identifiers, recent_evidence)
+        return EntityContext(
+            entity_id=canonical_id,
+            aliases=aliases,
+            identifiers=identifiers,
+            recent_evidence=recent_evidence,
+            confidence_summary=summary,
+        )
+
+    def recommendation_context(self, entity_id: str) -> RecommendationContext:
+        canonical_id = self.store.canonical_entity_id(entity_id)
+        aliases = self.store.list_aliases_for_entity(canonical_id)
+        identifiers = self.store.list_identifier_records_for_entity(canonical_id)
+        return build_recommendation_context(canonical_id, aliases, identifiers)
+
     def export_snapshot(self, output_path: str) -> None:
         self.store.export_snapshot(output_path)
 

metaspn_entities/sqlite_backend.py

@@ -276,3 +276,37 @@ class SQLiteEntityStore:
                     "normalized_value": row["normalized_value"],
                     "confidence": row["confidence"],
                 }
+
+    def list_identifier_records_for_entity(self, entity_id: str) -> List[Dict[str, Any]]:
+        target = self.canonical_entity_id(entity_id)
+        rows = self.conn.execute(
+            """
+            SELECT
+              a.entity_id,
+              i.identifier_type,
+              i.value,
+              i.normalized_value,
+              i.confidence,
+              i.first_seen_at,
+              i.last_seen_at,
+              i.provenance
+            FROM aliases a
+            JOIN identifiers i
+              ON a.identifier_type = i.identifier_type
+             AND a.normalized_value = i.normalized_value
+            ORDER BY i.identifier_type, i.normalized_value
+            """
+        ).fetchall()
+        return [
+            {
+                "identifier_type": row["identifier_type"],
+                "value": row["value"],
+                "normalized_value": row["normalized_value"],
+                "confidence": row["confidence"],
+                "first_seen_at": row["first_seen_at"],
+                "last_seen_at": row["last_seen_at"],
+                "provenance": row["provenance"],
+            }
+            for row in rows
+            if self.canonical_entity_id(row["entity_id"]) == target
+        ]

{metaspn_entities-0.1.4.dist-info → metaspn_entities-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaspn-entities
-Version: 0.1.4
+Version: 0.1.6
 Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
 Author: MetaSPN Contributors
 License-Expression: MIT
@@ -99,3 +99,26 @@ 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.
+
+## M1 Context API
+
+Profiler/router workers can read consolidated context using:
+
+- `resolver.entity_context(entity_id, recent_limit=10)`
+- `resolver.confidence_summary(entity_id)`
+
+Both APIs resolve canonical redirects first, so merged IDs return coherent context.
+
+## M2 Recommendation Context API
+
+Recommendation and drafter workers can consume:
+
+- `resolver.recommendation_context(entity_id)`
+
+The recommendation context includes:
+- identity confidence
+- activity recency (days)
+- interaction history summary (evidence count + source distribution)
+- preferred channel hint
+- relationship stage hint (`cold` / `warm` / `engaged`)
+- merge-safe continuity fields keyed to canonical entity IDs

metaspn_entities-0.1.6.dist-info/RECORD

@@ -0,0 +1,13 @@
+metaspn_entities/__init__.py,sha256=aija_xk40mk4JreYPiKKIpKwt6eQdUQRlrriwNkgZB0,639
+metaspn_entities/adapter.py,sha256=eNB5kr1tinav85WPA4YCldRDJBgb6uYe3ZWCRVjdOms,4654
+metaspn_entities/context.py,sha256=sUpW50Z99R0iQ5ryVR9uk7WqUaiKCxMyTQlvuV3DvVk,6054
+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=lmjQj5W2ny1_FnzNB-_cywReL_5ScOOHohV_TcY4usM,8345
+metaspn_entities/sqlite_backend.py,sha256=Ed0CGAfDGlzKuD-v3xkxumGf8My4WByMQRtrO9JHK84,11790
+metaspn_entities-0.1.6.dist-info/licenses/LICENSE,sha256=tvVpto97dUnh1-KVYPs1rCr5dzyX8jUyNmT7F7ZPVAM,1077
+metaspn_entities-0.1.6.dist-info/METADATA,sha256=Lp2AXFXLhnY46SlExYN4pnqora7_DH9wcwF5IAMuOD0,4130
+metaspn_entities-0.1.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+metaspn_entities-0.1.6.dist-info/top_level.txt,sha256=YP2V8Z1Statrs3YAI-tGvyC73vLjPHr9Vkal4yqXkhs,17
+metaspn_entities-0.1.6.dist-info/RECORD,,

metaspn_entities-0.1.4.dist-info/RECORD

@@ -1,12 +0,0 @@
-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.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,,