metaspn-entities 0.1.0__tar.gz

metaspn_entities-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaSPN Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaspn_entities-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: metaspn-entities
+Version: 0.1.0
+Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
+Author: MetaSPN Contributors
+License-Expression: MIT
+Keywords: entity-resolution,identity,aliasing,dedupe,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: metaspn-schemas
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# 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/README.md

@@ -0,0 +1,32 @@
+# 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/__init__.py

@@ -0,0 +1,11 @@
+from .events import EmittedEvent
+from .models import EntityResolution
+from .resolver import EntityResolver
+from .sqlite_backend import SQLiteEntityStore
+
+__all__ = [
+    "EntityResolver",
+    "EntityResolution",
+    "EmittedEvent",
+    "SQLiteEntityStore",
+]

metaspn_entities-0.1.0/metaspn_entities/events.py

@@ -0,0 +1,49 @@
+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,
+            },
+        )

metaspn_entities-0.1.0/metaspn_entities/models.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+DEFAULT_MATCH_CONFIDENCE = 0.95
+DEFAULT_NEW_ENTITY_CONFIDENCE = 0.6
+
+
+class EntityStatus:
+    ACTIVE = "active"
+    MERGED = "merged"
+
+
+class EntityType:
+    PERSON = "person"
+    ORG = "org"
+    PROJECT = "project"
+
+
+@dataclass(frozen=True)
+class Entity:
+    entity_id: str
+    entity_type: str
+    created_at: str
+    status: str
+
+
+@dataclass(frozen=True)
+class Identifier:
+    identifier_type: str
+    value: str
+    normalized_value: str
+    confidence: float
+    first_seen_at: str
+    last_seen_at: str
+    provenance: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class Alias:
+    identifier_type: str
+    normalized_value: str
+    entity_id: str
+    confidence: float
+    created_at: str
+    caused_by: str
+    provenance: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class MergeRecord:
+    merge_id: int
+    from_entity_id: str
+    to_entity_id: str
+    reason: str
+    timestamp: str
+    caused_by: str
+
+
+@dataclass(frozen=True)
+class EntityResolution:
+    entity_id: str
+    confidence: float
+    created_new_entity: bool
+    matched_identifiers: List[Dict[str, Any]] = field(default_factory=list)
+
+
+
+def utcnow_iso() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()

metaspn_entities-0.1.0/metaspn_entities/normalize.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+
+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"}:
+        return value.lstrip("@").lower()
+
+    if identifier_type == "email":
+        return value.lower()
+
+    if identifier_type == "domain":
+        cleaned = value.lower()
+        if cleaned.startswith("http://") or cleaned.startswith("https://"):
+            cleaned = urlparse(cleaned).netloc or cleaned
+        return cleaned.lstrip("www.")
+
+    if identifier_type in {"linkedin_url", "url", "canonical_url"}:
+        parsed = urlparse(value)
+        if parsed.scheme:
+            host = parsed.netloc.lower().lstrip("www.")
+            path = parsed.path.rstrip("/")
+            return f"{host}{path}".lower()
+        return value.lower().rstrip("/")
+
+    if identifier_type == "name":
+        return " ".join(value.lower().split())
+
+    return value.lower()
+
+
+AUTO_MERGE_IDENTIFIER_TYPES = {"email", "canonical_url", "url"}

metaspn_entities-0.1.0/metaspn_entities/resolver.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .events import EmittedEvent, EventFactory
+from .models import (
+    DEFAULT_MATCH_CONFIDENCE,
+    DEFAULT_NEW_ENTITY_CONFIDENCE,
+    EntityResolution,
+    EntityStatus,
+    EntityType,
+)
+from .normalize import AUTO_MERGE_IDENTIFIER_TYPES, normalize_identifier
+from .sqlite_backend import SQLiteEntityStore
+
+
+class EntityResolver:
+    def __init__(self, store: Optional[SQLiteEntityStore] = None) -> None:
+        self.store = store or SQLiteEntityStore()
+        self._event_buffer: List[EmittedEvent] = []
+
+    def resolve(self, identifier_type: str, value: str, context: Optional[Dict[str, Any]] = None) -> EntityResolution:
+        context = context or {}
+        confidence = float(context.get("confidence", DEFAULT_MATCH_CONFIDENCE))
+        provenance = context.get("provenance")
+        entity_type = context.get("entity_type", EntityType.PERSON)
+        caused_by = context.get("caused_by", "resolver")
+
+        normalized = normalize_identifier(identifier_type, value)
+        self.store.upsert_identifier(identifier_type, value, normalized, confidence, provenance)
+
+        existing_alias = self.store.find_alias(identifier_type, normalized)
+        if existing_alias:
+            entity_id = self.store.canonical_entity_id(existing_alias["entity_id"])
+            matched_identifiers = list(self.store.iter_identifiers_for_entity(entity_id))
+            resolution = EntityResolution(
+                entity_id=entity_id,
+                confidence=max(float(existing_alias["confidence"]), confidence),
+                created_new_entity=False,
+                matched_identifiers=matched_identifiers,
+            )
+            self._event_buffer.append(
+                EventFactory.entity_resolved(entity_id, identifier_type, value, resolution.confidence, False)
+            )
+            return resolution
+
+        entity_id = self.store.create_entity(entity_type)
+        added, conflicting_entity_id = self.store.add_alias(
+            identifier_type=identifier_type,
+            normalized_value=normalized,
+            entity_id=entity_id,
+            confidence=confidence,
+            caused_by=caused_by,
+            provenance=provenance,
+        )
+
+        if conflicting_entity_id and identifier_type in AUTO_MERGE_IDENTIFIER_TYPES:
+            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")
+            )
+
+        matched_identifiers = list(self.store.iter_identifiers_for_entity(entity_id))
+        resolution = EntityResolution(
+            entity_id=entity_id,
+            confidence=confidence if added else DEFAULT_NEW_ENTITY_CONFIDENCE,
+            created_new_entity=True,
+            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)
+        )
+        return resolution
+
+    def add_alias(
+        self,
+        entity_id: str,
+        identifier_type: str,
+        value: str,
+        confidence: float = DEFAULT_MATCH_CONFIDENCE,
+        caused_by: str = "manual",
+        provenance: Optional[str] = None,
+    ) -> List[EmittedEvent]:
+        self.store.ensure_entity(entity_id)
+        canonical_entity_id = self.store.canonical_entity_id(entity_id)
+        normalized = normalize_identifier(identifier_type, value)
+        self.store.upsert_identifier(identifier_type, value, normalized, confidence, provenance)
+
+        added, conflicting_entity_id = self.store.add_alias(
+            identifier_type=identifier_type,
+            normalized_value=normalized,
+            entity_id=canonical_entity_id,
+            confidence=confidence,
+            caused_by=caused_by,
+            provenance=provenance,
+        )
+        if conflicting_entity_id and conflicting_entity_id != canonical_entity_id:
+            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")
+                self._event_buffer.append(event)
+                return [event]
+            raise ValueError(
+                f"Alias already mapped to another entity: {identifier_type}:{normalized} -> {conflicting_entity_id}"
+            )
+
+        if not added:
+            return []
+
+        event = EventFactory.entity_alias_added(canonical_entity_id, identifier_type, normalized, caused_by)
+        self._event_buffer.append(event)
+        return [event]
+
+    def merge_entities(self, from_entity_id: str, to_entity_id: str, reason: str, caused_by: str = "manual") -> EmittedEvent:
+        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)
+        self._event_buffer.append(event)
+        return event
+
+    def undo_merge(self, from_entity_id: str, to_entity_id: str, caused_by: str = "manual") -> EmittedEvent:
+        reason = f"undo merge {from_entity_id}->{to_entity_id}"
+        if self.store.get_redirect_target(from_entity_id) == to_entity_id:
+            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)
+        self._event_buffer.append(event)
+        return event
+
+    def merge_history(self) -> List[Dict[str, Any]]:
+        return self.store.list_merge_history()
+
+    def aliases_for_entity(self, entity_id: str) -> List[Dict[str, Any]]:
+        return self.store.list_aliases_for_entity(entity_id)
+
+    def export_snapshot(self, output_path: str) -> None:
+        self.store.export_snapshot(output_path)
+
+    def drain_events(self) -> List[EmittedEvent]:
+        events = list(self._event_buffer)
+        self._event_buffer.clear()
+        return events

metaspn_entities-0.1.0/metaspn_entities/sqlite_backend.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from .models import EntityStatus, utcnow_iso
+
+
+SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS entities (
+  entity_id TEXT PRIMARY KEY,
+  entity_type TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  status TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS identifiers (
+  identifier_type TEXT NOT NULL,
+  value TEXT NOT NULL,
+  normalized_value TEXT NOT NULL,
+  confidence REAL NOT NULL,
+  first_seen_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL,
+  provenance TEXT,
+  UNIQUE(identifier_type, normalized_value)
+);
+
+CREATE TABLE IF NOT EXISTS aliases (
+  identifier_type TEXT NOT NULL,
+  normalized_value TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  confidence REAL NOT NULL,
+  created_at TEXT NOT NULL,
+  caused_by TEXT NOT NULL,
+  provenance TEXT,
+  UNIQUE(identifier_type, normalized_value)
+);
+
+CREATE TABLE IF NOT EXISTS merge_records (
+  merge_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  from_entity_id TEXT NOT NULL,
+  to_entity_id TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  timestamp TEXT NOT NULL,
+  caused_by TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS entity_redirects (
+  from_entity_id TEXT PRIMARY KEY,
+  to_entity_id TEXT NOT NULL,
+  timestamp TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  caused_by TEXT NOT NULL
+);
+"""
+
+
+class SQLiteEntityStore:
+    def __init__(self, db_path: str = ":memory:") -> None:
+        self.db_path = db_path
+        self.conn = sqlite3.connect(db_path)
+        self.conn.row_factory = sqlite3.Row
+        self.conn.executescript(SCHEMA_SQL)
+        self.conn.commit()
+
+    def close(self) -> None:
+        self.conn.close()
+
+    def create_entity(self, entity_type: str) -> str:
+        entity_id = f"ent_{uuid.uuid4().hex}"
+        now = utcnow_iso()
+        self.conn.execute(
+            "INSERT INTO entities(entity_id, entity_type, created_at, status) VALUES (?, ?, ?, ?)",
+            (entity_id, entity_type, now, EntityStatus.ACTIVE),
+        )
+        self.conn.commit()
+        return entity_id
+
+    def get_entity(self, entity_id: str) -> Optional[sqlite3.Row]:
+        row = self.conn.execute("SELECT * FROM entities WHERE entity_id = ?", (entity_id,)).fetchone()
+        return row
+
+    def canonical_entity_id(self, entity_id: str) -> str:
+        current = entity_id
+        visited = set()
+        while True:
+            if current in visited:
+                raise ValueError(f"Cycle detected in merge redirects for {entity_id}")
+            visited.add(current)
+            row = self.conn.execute(
+                "SELECT to_entity_id FROM entity_redirects WHERE from_entity_id = ?", (current,)
+            ).fetchone()
+            if not row:
+                return current
+            current = row["to_entity_id"]
+
+    def find_alias(self, identifier_type: str, normalized_value: str) -> Optional[sqlite3.Row]:
+        return self.conn.execute(
+            "SELECT * FROM aliases WHERE identifier_type = ? AND normalized_value = ?",
+            (identifier_type, normalized_value),
+        ).fetchone()
+
+    def upsert_identifier(
+        self,
+        identifier_type: str,
+        value: str,
+        normalized_value: str,
+        confidence: float,
+        provenance: Optional[str],
+    ) -> None:
+        now = utcnow_iso()
+        existing = self.conn.execute(
+            "SELECT * FROM identifiers WHERE identifier_type = ? AND normalized_value = ?",
+            (identifier_type, normalized_value),
+        ).fetchone()
+        if existing:
+            self.conn.execute(
+                "UPDATE identifiers SET value = ?, confidence = ?, last_seen_at = ?, provenance = ? WHERE identifier_type = ? AND normalized_value = ?",
+                (
+                    value,
+                    max(confidence, existing["confidence"]),
+                    now,
+                    provenance or existing["provenance"],
+                    identifier_type,
+                    normalized_value,
+                ),
+            )
+        else:
+            self.conn.execute(
+                "INSERT INTO identifiers(identifier_type, value, normalized_value, confidence, first_seen_at, last_seen_at, provenance) VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (identifier_type, value, normalized_value, confidence, now, now, provenance),
+            )
+        self.conn.commit()
+
+    def add_alias(
+        self,
+        identifier_type: str,
+        normalized_value: str,
+        entity_id: str,
+        confidence: float,
+        caused_by: str,
+        provenance: Optional[str] = None,
+    ) -> Tuple[bool, Optional[str]]:
+        now = utcnow_iso()
+        existing = self.find_alias(identifier_type, normalized_value)
+        canonical_target = self.canonical_entity_id(entity_id)
+
+        if existing:
+            existing_entity = self.canonical_entity_id(existing["entity_id"])
+            if existing_entity == canonical_target:
+                self.conn.execute(
+                    "UPDATE aliases SET confidence = ?, provenance = ? WHERE identifier_type = ? AND normalized_value = ?",
+                    (
+                        max(confidence, existing["confidence"]),
+                        provenance or existing["provenance"],
+                        identifier_type,
+                        normalized_value,
+                    ),
+                )
+                self.conn.commit()
+                return False, None
+            return False, existing_entity
+
+        self.conn.execute(
+            "INSERT INTO aliases(identifier_type, normalized_value, entity_id, confidence, created_at, caused_by, provenance) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (identifier_type, normalized_value, canonical_target, confidence, now, caused_by, provenance),
+        )
+        self.conn.commit()
+        return True, None
+
+    def reassign_aliases(self, from_entity_id: str, to_entity_id: str) -> None:
+        self.conn.execute(
+            "UPDATE aliases SET entity_id = ? WHERE entity_id = ?",
+            (to_entity_id, from_entity_id),
+        )
+
+    def get_redirect_target(self, from_entity_id: str) -> Optional[str]:
+        row = self.conn.execute(
+            "SELECT to_entity_id FROM entity_redirects WHERE from_entity_id = ?",
+            (from_entity_id,),
+        ).fetchone()
+        if not row:
+            return None
+        return str(row["to_entity_id"])
+
+    def remove_redirect(self, from_entity_id: str) -> None:
+        self.conn.execute("DELETE FROM entity_redirects WHERE from_entity_id = ?", (from_entity_id,))
+        self.conn.commit()
+
+    def set_entity_status(self, entity_id: str, status: str) -> None:
+        self.conn.execute("UPDATE entities SET status = ? WHERE entity_id = ?", (status, entity_id))
+        self.conn.commit()
+
+    def merge_entities(self, from_entity_id: str, to_entity_id: str, reason: str, caused_by: str) -> int:
+        from_canonical = self.canonical_entity_id(from_entity_id)
+        to_canonical = self.canonical_entity_id(to_entity_id)
+
+        if from_canonical == to_canonical:
+            raise ValueError("Entities are already merged")
+
+        timestamp = utcnow_iso()
+        self.conn.execute(
+            "INSERT OR REPLACE INTO entity_redirects(from_entity_id, to_entity_id, timestamp, reason, caused_by) VALUES (?, ?, ?, ?, ?)",
+            (from_canonical, to_canonical, timestamp, reason, caused_by),
+        )
+        self.conn.execute(
+            "UPDATE entities SET status = ? WHERE entity_id = ?",
+            (EntityStatus.MERGED, from_canonical),
+        )
+        self.conn.execute(
+            "UPDATE entities SET status = ? WHERE entity_id = ?",
+            (EntityStatus.ACTIVE, to_canonical),
+        )
+        cursor = self.conn.execute(
+            "INSERT INTO merge_records(from_entity_id, to_entity_id, reason, timestamp, caused_by) VALUES (?, ?, ?, ?, ?)",
+            (from_canonical, to_canonical, reason, timestamp, caused_by),
+        )
+        self.conn.commit()
+        return int(cursor.lastrowid)
+
+    def list_aliases_for_entity(self, entity_id: str) -> List[Dict[str, Any]]:
+        target = self.canonical_entity_id(entity_id)
+        rows = self.conn.execute(
+            "SELECT identifier_type, normalized_value, entity_id, confidence FROM aliases ORDER BY identifier_type, normalized_value"
+        ).fetchall()
+        return [
+            {
+                "identifier_type": row["identifier_type"],
+                "normalized_value": row["normalized_value"],
+                "entity_id": row["entity_id"],
+                "confidence": row["confidence"],
+            }
+            for row in rows
+            if self.canonical_entity_id(row["entity_id"]) == target
+        ]
+
+    def list_merge_history(self) -> List[Dict[str, Any]]:
+        rows = self.conn.execute(
+            "SELECT merge_id, from_entity_id, to_entity_id, reason, timestamp, caused_by FROM merge_records ORDER BY merge_id"
+        ).fetchall()
+        return [dict(row) for row in rows]
+
+    def export_snapshot(self, output_path: str) -> None:
+        payload: Dict[str, Any] = {}
+        for table in ["entities", "identifiers", "aliases", "merge_records", "entity_redirects"]:
+            rows = self.conn.execute(f"SELECT * FROM {table}").fetchall()
+            payload[table] = [dict(row) for row in rows]
+
+        path = Path(output_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+    def ensure_entity(self, entity_id: str) -> None:
+        row = self.get_entity(entity_id)
+        if not row:
+            raise ValueError(f"Unknown entity_id: {entity_id}")
+
+    def iter_identifiers_for_entity(self, entity_id: str) -> Iterable[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
+            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()
+        for row in rows:
+            if self.canonical_entity_id(row["entity_id"]) == target:
+                yield {
+                    "identifier_type": row["identifier_type"],
+                    "value": row["value"],
+                    "normalized_value": row["normalized_value"],
+                    "confidence": row["confidence"],
+                }

metaspn_entities-0.1.0/metaspn_entities.egg-info/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: metaspn-entities
+Version: 0.1.0
+Summary: Canonical entity resolution, aliasing, and merges for MetaSPN systems
+Author: MetaSPN Contributors
+License-Expression: MIT
+Keywords: entity-resolution,identity,aliasing,dedupe,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Database
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: metaspn-schemas
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# 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.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+metaspn_entities/__init__.py
+metaspn_entities/events.py
+metaspn_entities/models.py
+metaspn_entities/normalize.py
+metaspn_entities/resolver.py
+metaspn_entities/sqlite_backend.py
+metaspn_entities.egg-info/PKG-INFO
+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_resolver.py

metaspn_entities-0.1.0/metaspn_entities.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

metaspn_entities-0.1.0/metaspn_entities.egg-info/requires.txt

@@ -0,0 +1,5 @@
+metaspn-schemas
+
+[dev]
+build>=1.2.0
+twine>=5.0.0

metaspn_entities-0.1.0/metaspn_entities.egg-info/top_level.txt

@@ -0,0 +1 @@
+metaspn_entities

metaspn_entities-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metaspn-entities"
+version = "0.1.0"
+description = "Canonical entity resolution, aliasing, and merges for MetaSPN systems"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  {name = "MetaSPN Contributors"}
+]
+keywords = ["entity-resolution", "identity", "aliasing", "dedupe", "sqlite"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Database",
+]
+dependencies = [
+  "metaspn-schemas"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2.0",
+  "twine>=5.0.0"
+]
+
+[tool.setuptools]
+packages = ["metaspn_entities"]

metaspn_entities-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metaspn_entities-0.1.0/tests/test_resolver.py

@@ -0,0 +1,87 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from metaspn_entities import EntityResolver, SQLiteEntityStore
+
+
+class ResolverTests(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_exact_match_resolution(self) -> None:
+        first = self.resolver.resolve("twitter_handle", "@same")
+        second = self.resolver.resolve("twitter_handle", "same")
+        self.assertEqual(first.entity_id, second.entity_id)
+        self.assertFalse(second.created_new_entity)
+
+    def test_alias_addition(self) -> None:
+        created = self.resolver.resolve("twitter_handle", "alpha")
+        events = self.resolver.add_alias(created.entity_id, "email", "alpha@example.com", caused_by="manual")
+        self.assertEqual(len(events), 1)
+
+        again = self.resolver.resolve("email", "ALPHA@example.com")
+        self.assertEqual(again.entity_id, created.entity_id)
+
+    def test_merge_correctness(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "person_a")
+        b = self.resolver.resolve("twitter_handle", "person_b")
+        self.resolver.merge_entities(a.entity_id, b.entity_id, reason="manual dedupe", caused_by="reviewer")
+
+        merged = self.resolver.resolve("twitter_handle", "person_a")
+        self.assertEqual(merged.entity_id, b.entity_id)
+
+    def test_merge_history(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "x_a")
+        b = self.resolver.resolve("twitter_handle", "x_b")
+        self.resolver.merge_entities(a.entity_id, b.entity_id, reason="dedupe", caused_by="reviewer")
+        history = self.resolver.merge_history()
+        self.assertEqual(len(history), 1)
+        self.assertEqual(history[0]["from_entity_id"], a.entity_id)
+        self.assertEqual(history[0]["to_entity_id"], b.entity_id)
+
+    def test_merge_undo_via_reverse_merge(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "undo_a")
+        b = self.resolver.resolve("twitter_handle", "undo_b")
+        self.resolver.merge_entities(a.entity_id, b.entity_id, reason="dedupe", caused_by="reviewer")
+        merged = self.resolver.resolve("twitter_handle", "undo_a")
+        self.assertEqual(merged.entity_id, b.entity_id)
+        self.resolver.undo_merge(a.entity_id, b.entity_id, caused_by="reviewer")
+
+        current_a = self.resolver.resolve("twitter_handle", "undo_a")
+        current_b = self.resolver.resolve("twitter_handle", "undo_b")
+        self.assertEqual(current_a.entity_id, a.entity_id)
+        self.assertEqual(current_b.entity_id, a.entity_id)
+
+    def test_confidence_behavior(self) -> None:
+        first = self.resolver.resolve("email", "test@example.com", context={"confidence": 0.7})
+        second = self.resolver.resolve("email", "test@example.com", context={"confidence": 0.4})
+        self.assertEqual(first.entity_id, second.entity_id)
+        self.assertGreaterEqual(second.confidence, 0.7)
+
+    def test_auto_merge_on_email(self) -> None:
+        a = self.resolver.resolve("twitter_handle", "owner_a")
+        b = self.resolver.resolve("twitter_handle", "owner_b")
+
+        self.resolver.add_alias(a.entity_id, "email", "shared@example.com")
+        events = self.resolver.add_alias(b.entity_id, "email", "shared@example.com")
+        self.assertEqual(len(events), 1)
+        self.assertEqual(events[0].event_type, "EntityMerged")
+
+        # resolving either alias should route to same canonical entity
+        one = self.resolver.resolve("twitter_handle", "owner_a")
+        two = self.resolver.resolve("twitter_handle", "owner_b")
+        self.assertEqual(one.entity_id, two.entity_id)
+        shared = self.resolver.resolve("email", "shared@example.com")
+        self.assertEqual(one.entity_id, shared.entity_id)
+
+
+if __name__ == "__main__":
+    unittest.main()