topos-node 0.1.0__py3-none-any.whl

shared/schema_registry.py

@@ -0,0 +1,229 @@
+"""
+Stage 9 schema registry: machine-readable contract for table/column canonical names,
+types, and categories (informational vs organizational).
+
+Source of truth: docs/SCHEMA_CONVENTIONS.md §7.
+Used by: engine, control plane, and UI (via assist APIs).
+Organizational columns are non-filterable by default.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+# -----------------------------------------------------------------------------
+# Column entry: one row per (table, column) with current DB name, canonical name, type, category.
+# For Stage 9 rename targets, current_column_name != canonical_column_name (current = name in DB today).
+# -----------------------------------------------------------------------------
+
+CATEGORY_INFORMATIONAL = "informational"
+CATEGORY_ORGANIZATIONAL = "organizational"
+
+
+def _row(
+    table: str,
+    current: str,
+    canonical: str,
+    type_name: str,
+    category: str,
+) -> Dict[str, Any]:
+    """Build a registry row; rename_target True when current != canonical."""
+    return {
+        "table_name": table,
+        "current_column_name": current,
+        "canonical_column_name": canonical,
+        "type": type_name,
+        "category": category,
+        "filterable_by_default": category == CATEGORY_INFORMATIONAL,
+        "rename_target": current != canonical,
+    }
+
+
+# Registry: all Stage 9 mapped tables from SCHEMA_CONVENTIONS.md §7.1–§7.7.
+# §7.0 rename targets: current = name in DB today; canonical = name after migration.
+SCHEMA_REGISTRY: List[Dict[str, Any]] = [
+    # ----- conversation_messages (7.1) -----
+    _row("conversation_messages", "message_id", "message_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "conversation_id", "conversation_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "sender_type", "sender_type", "text", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "sender_id", "sender_id", "text", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "reply_to_message_id", "reply_to_message_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "message_type", "message_type", "text", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "event_type", "event_type", "text", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "content", "content", "text", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "ts", "event_at", "timestamp_utc", CATEGORY_INFORMATIONAL),  # rename
+    _row("conversation_messages", "source_id", "source_id", "text", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "metadata_json", "metadata_json", "json", CATEGORY_INFORMATIONAL),
+    _row("conversation_messages", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("conversation_messages", "from_self", "is_from_self", "integer", CATEGORY_ORGANIZATIONAL),  # rename
+    _row("conversation_messages", "owner_user_id", "owner_user_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    # ----- ai_chat_messages (7.2) -----
+    _row("ai_chat_messages", "message_id", "message_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("ai_chat_messages", "conversation_id", "conversation_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("ai_chat_messages", "sender_type", "sender_type", "text", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_messages", "sender_id", "sender_id", "text", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_messages", "ts", "event_at", "timestamp_utc", CATEGORY_INFORMATIONAL),  # rename
+    _row("ai_chat_messages", "content", "content", "text", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_messages", "content_rendered", "content_rendered", "text", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_messages", "metadata_json", "metadata_json", "json", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_messages", "seq", "sequence", "integer", CATEGORY_ORGANIZATIONAL),  # rename
+    _row("ai_chat_messages", "source_id", "source_id", "text", CATEGORY_ORGANIZATIONAL),
+    # ----- ai_chat_conversations (7.3) -----
+    _row("ai_chat_conversations", "conversation_id", "conversation_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("ai_chat_conversations", "owner_user_id", "owner_user_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("ai_chat_conversations", "title", "title", "text", CATEGORY_INFORMATIONAL),
+    _row("ai_chat_conversations", "source", "source_id", "text", CATEGORY_ORGANIZATIONAL),  # rename
+    _row("ai_chat_conversations", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("ai_chat_conversations", "updated_at", "updated_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    # ----- browser_visits (7.4) -----
+    _row("browser_visits", "record_id", "record_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "url", "url", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "visited_at", "visited_at", "timestamp_utc", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "title", "title", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "favicon_url", "favicon_url", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "hostname", "hostname", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "device_name", "device_name", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "tab_id", "tab_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "window_id", "window_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "incognito", "incognito", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "transition_type", "transition_type", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "pinned", "pinned", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "audible", "audible", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "muted", "muted", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "opener_tab_id", "opener_tab_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_visits", "referred_by", "referred_by", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_visits", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    # ----- browser_events (7.5) -----
+    _row("browser_events", "record_id", "record_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "event_type", "event_type", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "url", "url", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "visited_at", "visited_at", "timestamp_utc", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "title", "title", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "favicon_url", "favicon_url", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "hostname", "hostname", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "device_name", "device_name", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "transition_type", "transition_type", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "content", "content", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "tab_id", "tab_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "window_id", "window_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "incognito", "incognito", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "pinned", "pinned", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "audible", "audible", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "muted", "muted", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "opener_tab_id", "opener_tab_id", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("browser_events", "starred_at", "starred_at", "timestamp_utc", CATEGORY_INFORMATIONAL),
+    _row("browser_events", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    # ----- browser_url_classification (7.6) -----
+    _row("browser_url_classification", "source_table", "enriched_from_table", "identifier", CATEGORY_ORGANIZATIONAL),  # rename
+    _row("browser_url_classification", "record_id", "record_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_url_classification", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("browser_url_classification", "url", "url", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_url_classification", "title", "title", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_url_classification", "url_category", "url_category", "text", CATEGORY_INFORMATIONAL),
+    _row("browser_url_classification", "url_confidence", "url_confidence", "real", CATEGORY_INFORMATIONAL),
+    _row("browser_url_classification", "model_name", "model_name", "text", CATEGORY_ORGANIZATIONAL),
+    _row("browser_url_classification", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("browser_url_classification", "updated_at", "updated_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    # ----- message_emotions (7.7) -----
+    _row("message_emotions", "message_id", "message_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("message_emotions", "source_id", "source_id", "text", CATEGORY_ORGANIZATIONAL),
+    _row("message_emotions", "emotion_label", "emotion_label", "text", CATEGORY_INFORMATIONAL),
+    _row("message_emotions", "confidence", "confidence", "real", CATEGORY_INFORMATIONAL),
+    _row("message_emotions", "model", "model_name", "text", CATEGORY_ORGANIZATIONAL),  # rename
+    _row("message_emotions", "all_emotions", "all_emotions_json", "json", CATEGORY_INFORMATIONAL),  # rename
+    _row("message_emotions", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    # ----- contacts (Stage 11: contacts:resolve — canonical messenger address book) -----
+    # See topos/storage/canonical/conversations_tables.py CREATE TABLE contacts / contact_identifiers
+    _row("contacts", "contact_id", "contact_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "source_id", "source_id", "text", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "display_name", "display_name", "text", CATEGORY_INFORMATIONAL),
+    _row("contacts", "known_usernames_json", "known_usernames_json", "json", CATEGORY_INFORMATIONAL),
+    _row("contacts", "is_self", "is_self", "integer", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "last_import_source", "last_import_source", "text", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "last_import_run_id", "last_import_run_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "last_imported_at", "last_imported_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "sharing_policy_json", "sharing_policy_json", "json", CATEGORY_INFORMATIONAL),
+    _row("contacts", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("contacts", "updated_at", "updated_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("contact_identifiers", "dataset_id", "dataset_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("contact_identifiers", "source_id", "source_id", "text", CATEGORY_ORGANIZATIONAL),
+    _row("contact_identifiers", "identifier", "identifier", "text", CATEGORY_INFORMATIONAL),
+    _row("contact_identifiers", "identifier_type", "identifier_type", "text", CATEGORY_INFORMATIONAL),
+    _row("contact_identifiers", "contact_id", "contact_id", "identifier", CATEGORY_ORGANIZATIONAL),
+    _row("contact_identifiers", "created_at", "created_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+    _row("contact_identifiers", "updated_at", "updated_at", "timestamp_utc", CATEGORY_ORGANIZATIONAL),
+]
+
+# Tables covered by this registry (for validation and iteration).
+STAGE_9_TABLE_NAMES = [
+    "conversation_messages",
+    "ai_chat_messages",
+    "ai_chat_conversations",
+    "browser_visits",
+    "browser_events",
+    "browser_url_classification",
+    "message_emotions",
+    "contacts",
+    "contact_identifiers",
+]
+
+
+def get_columns_for_table(
+    table_name: str,
+    *,
+    include_organizational: bool = True,
+    use_canonical_names: bool = False,
+) -> List[Dict[str, Any]]:
+    """
+    Return column entries for a table. Used by assist APIs and UI.
+
+    include_organizational: If False, return only informational columns (default filterable set).
+    use_canonical_names: If True, return canonical_column_name as the column name to display/use;
+        if False, return current_column_name (name in DB today).
+    """
+    rows = [r for r in SCHEMA_REGISTRY if r["table_name"] == table_name]
+    if not include_organizational:
+        rows = [r for r in rows if r["category"] == CATEGORY_INFORMATIONAL]
+    if use_canonical_names:
+        return [{**r, "column_name": r["canonical_column_name"]} for r in rows]
+    return [{**r, "column_name": r["current_column_name"]} for r in rows]
+
+
+def get_informational_columns(table_name: str) -> List[Dict[str, Any]]:
+    """Return only informational (filterable-by-default) columns for a table."""
+    return get_columns_for_table(table_name, include_organizational=False)
+
+
+def get_rename_targets() -> List[Dict[str, Any]]:
+    """Return all columns that are Stage 9 migration rename targets (current != canonical)."""
+    return [r for r in SCHEMA_REGISTRY if r["rename_target"]]
+
+
+def get_registry_as_list(
+    *,
+    include_organizational: bool = True,
+) -> List[Dict[str, Any]]:
+    """Return full registry as list of dicts (e.g. for JSON export or API)."""
+    if include_organizational:
+        return list(SCHEMA_REGISTRY)
+    return [r for r in SCHEMA_REGISTRY if r["category"] == CATEGORY_INFORMATIONAL]
+
+
+def get_table_names() -> List[str]:
+    """Return list of table names in the registry."""
+    return list(STAGE_9_TABLE_NAMES)
+
+
+def resolve_column_to_canonical(table_name: str, current_column_name: str) -> Optional[str]:
+    """
+    Given a table and the current (DB) column name, return the canonical name.
+    If not in registry or no rename, returns current_column_name (or None if unknown).
+    """
+    for r in SCHEMA_REGISTRY:
+        if r["table_name"] == table_name and r["current_column_name"] == current_column_name:
+            return r["canonical_column_name"]
+    return None

topos/__init__.py

@@ -0,0 +1,5 @@
+"""Topos control plane package root."""
+
+from .__version__ import __version__, __version_info__
+
+__all__ = ["__version__", "__version_info__"]

topos/__version__.py

@@ -0,0 +1,6 @@
+"""Topos Control Plane Version Information."""
+
+__version__ = "0.0.0"
+__version_info__ = (0, 0, 0)
+
+__all__ = ["__version__", "__version_info__"]

topos/analytics/__init__.py

@@ -0,0 +1,15 @@
+"""Analytics layer for Topos."""
+
+from .messenger_communities import (
+    compute_and_persist_messenger_analytics,
+    compute_importance_and_communities,
+    ensure_messenger_analytics_tables,
+)
+from .messenger_graph import extract_messenger_graph
+
+__all__ = [
+    "extract_messenger_graph",
+    "compute_importance_and_communities",
+    "compute_and_persist_messenger_analytics",
+    "ensure_messenger_analytics_tables",
+]

topos/analytics/duckdb_adapter.py

@@ -0,0 +1,48 @@
+"""DuckDB adapter for analytics queries."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+try:
+    import duckdb
+except ImportError:
+    duckdb = None  # type: ignore
+
+logger = logging.getLogger("topos.analytics.duckdb")
+
+
+class DuckDBAdapter:
+    def __init__(self, db_path: Optional[Path] = None):
+        if duckdb is None:
+            raise ImportError("duckdb package not installed")
+        self.conn = duckdb.connect(str(db_path) if db_path else ":memory:")
+
+    def attach_sqlite(self, sqlite_path: str) -> None:
+        escaped_path = sqlite_path.replace("'", "''")
+        self.conn.execute(f"ATTACH '{escaped_path}' AS projection (TYPE SQLITE)")
+
+    def query_jsonl_file(
+        self,
+        file_path: str,
+        dataset_id: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        escaped_path = file_path.replace("'", "''")
+        query = f"SELECT * FROM read_ndjson('{escaped_path}')"
+        if dataset_id:
+            query += f" WHERE dataset_id = '{dataset_id}'"
+        result = self.conn.execute(query).fetchall()
+        columns = [desc[0] for desc in self.conn.description] if self.conn.description else []
+        return [dict(zip(columns, row)) for row in result]
+
+    def execute(self, query: str, params: Optional[List[Any]] = None) -> List[Dict[str, Any]]:
+        params = params or []
+        result = self.conn.execute(query, params).fetchall()
+        columns = [desc[0] for desc in self.conn.description] if self.conn.description else []
+        return [dict(zip(columns, row)) for row in result]
+
+    def close(self) -> None:
+        if self.conn:
+            self.conn.close()

topos/analytics/messenger_communities.py

@@ -0,0 +1,349 @@
+"""Messenger graph importance and community detection (Sprint 02)."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Sequence
+
+import networkx as nx
+
+from .messenger_graph import extract_messenger_graph
+
+MESSENGER_SOCIAL_EDGES_TABLE = "messenger_social_edges"
+MESSENGER_PARTICIPANT_IMPORTANCE_TABLE = "messenger_participant_importance"
+MESSENGER_COMMUNITIES_TABLE = "messenger_communities"
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _source_scope(source_ids: Optional[Sequence[str]]) -> str:
+    if not source_ids:
+        return "all"
+    normalized = sorted({str(s).strip() for s in source_ids if str(s).strip()})
+    return ",".join(normalized) if normalized else "all"
+
+
+def ensure_messenger_analytics_tables(conn: Any) -> None:
+    """Create Sprint 02 derived messenger analytics tables."""
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {MESSENGER_SOCIAL_EDGES_TABLE} (
+            dataset_id TEXT NOT NULL,
+            period_key TEXT NOT NULL,
+            source_scope TEXT NOT NULL DEFAULT 'all',
+            source_id TEXT NOT NULL,
+            target_id TEXT NOT NULL,
+            weight REAL NOT NULL,
+            edge_type TEXT,
+            edge_type_counts_json TEXT,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (dataset_id, period_key, source_scope, source_id, target_id)
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE INDEX IF NOT EXISTS idx_{MESSENGER_SOCIAL_EDGES_TABLE}_dataset_period
+        ON {MESSENGER_SOCIAL_EDGES_TABLE}(dataset_id, period_key, source_scope)
+        """
+    )
+
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE} (
+            dataset_id TEXT NOT NULL,
+            period_key TEXT NOT NULL,
+            source_scope TEXT NOT NULL DEFAULT 'all',
+            participant_id TEXT NOT NULL,
+            centrality_degree REAL NOT NULL,
+            centrality_betweenness REAL NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (dataset_id, period_key, source_scope, participant_id)
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE INDEX IF NOT EXISTS idx_{MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}_dataset_period
+        ON {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}(dataset_id, period_key, source_scope)
+        """
+    )
+
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {MESSENGER_COMMUNITIES_TABLE} (
+            dataset_id TEXT NOT NULL,
+            period_key TEXT NOT NULL,
+            source_scope TEXT NOT NULL DEFAULT 'all',
+            participant_id TEXT NOT NULL,
+            community_id INTEGER NOT NULL,
+            created_at TEXT NOT NULL,
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (dataset_id, period_key, source_scope, participant_id)
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE INDEX IF NOT EXISTS idx_{MESSENGER_COMMUNITIES_TABLE}_dataset_period
+        ON {MESSENGER_COMMUNITIES_TABLE}(dataset_id, period_key, source_scope)
+        """
+    )
+    conn.commit()
+
+
+def build_networkx_graph(period_payload: Dict[str, Any]) -> nx.Graph:
+    """Build an undirected weighted graph from Sprint 01 period payload."""
+    graph = nx.Graph()
+    for node in period_payload.get("nodes", []):
+        node_id = str(node.get("id") or "").strip()
+        if not node_id:
+            continue
+        graph.add_node(node_id, **node)
+
+    for edge in period_payload.get("edges", []):
+        source_id = str(edge.get("source") or "").strip()
+        target_id = str(edge.get("target") or "").strip()
+        if not source_id or not target_id or source_id == target_id:
+            continue
+        weight = float(edge.get("weight") or 0.0)
+        graph.add_edge(source_id, target_id, weight=max(weight, 0.0))
+    return graph
+
+
+def compute_importance_and_communities(period_payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Compute centrality metrics and Louvain communities for one period."""
+    graph = build_networkx_graph(period_payload)
+    node_ids = list(graph.nodes())
+    if not node_ids:
+        return {"importance": {}, "communities": {}, "graph": graph}
+
+    degree = nx.degree_centrality(graph)
+    # Use unweighted betweenness to keep metric stable with strength-based edges.
+    betweenness = nx.betweenness_centrality(graph, weight=None, normalized=True)
+
+    if graph.number_of_edges() > 0:
+        try:
+            from community import community_louvain  # type: ignore
+
+            communities = community_louvain.best_partition(graph, weight="weight", random_state=42)
+        except Exception:
+            # Fallback keeps pipeline functional if python-louvain is unavailable at runtime.
+            communities = {}
+            for idx, component in enumerate(nx.connected_components(graph)):
+                for node_id in component:
+                    communities[node_id] = idx
+    else:
+        communities = {node_id: idx for idx, node_id in enumerate(sorted(node_ids))}
+
+    importance: Dict[str, Dict[str, float]] = {}
+    for node_id in node_ids:
+        importance[node_id] = {
+            "centrality_degree": float(degree.get(node_id, 0.0)),
+            "centrality_betweenness": float(betweenness.get(node_id, 0.0)),
+        }
+    return {
+        "importance": importance,
+        "communities": {k: int(v) for k, v in communities.items()},
+        "graph": graph,
+    }
+
+
+def _persist_period_results(
+    conn: Any,
+    *,
+    dataset_id: str,
+    period_key: str,
+    source_scope: str,
+    period_payload: Dict[str, Any],
+    importance: Dict[str, Dict[str, float]],
+    communities: Dict[str, int],
+) -> Dict[str, int]:
+    now = _utc_now()
+    conn.execute(
+        f"""
+        DELETE FROM {MESSENGER_SOCIAL_EDGES_TABLE}
+        WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+        """,
+        (dataset_id, period_key, source_scope),
+    )
+    conn.execute(
+        f"""
+        DELETE FROM {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}
+        WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+        """,
+        (dataset_id, period_key, source_scope),
+    )
+    conn.execute(
+        f"""
+        DELETE FROM {MESSENGER_COMMUNITIES_TABLE}
+        WHERE dataset_id = ? AND period_key = ? AND source_scope = ?
+        """,
+        (dataset_id, period_key, source_scope),
+    )
+
+    edge_rows = []
+    for edge in period_payload.get("edges", []):
+        source_id = str(edge.get("source") or "").strip()
+        target_id = str(edge.get("target") or "").strip()
+        if not source_id or not target_id:
+            continue
+        edge_rows.append(
+            (
+                dataset_id,
+                period_key,
+                source_scope,
+                source_id,
+                target_id,
+                float(edge.get("weight") or 0.0),
+                str(edge.get("edge_type") or ""),
+                json.dumps(edge.get("edge_type_counts") or {}, ensure_ascii=False),
+                now,
+                now,
+            )
+        )
+    if edge_rows:
+        conn.executemany(
+            f"""
+            INSERT INTO {MESSENGER_SOCIAL_EDGES_TABLE}
+            (
+                dataset_id, period_key, source_scope, source_id, target_id,
+                weight, edge_type, edge_type_counts_json, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            edge_rows,
+        )
+
+    importance_rows = []
+    for participant_id, metrics in importance.items():
+        importance_rows.append(
+            (
+                dataset_id,
+                period_key,
+                source_scope,
+                participant_id,
+                float(metrics.get("centrality_degree", 0.0)),
+                float(metrics.get("centrality_betweenness", 0.0)),
+                now,
+                now,
+            )
+        )
+    if importance_rows:
+        conn.executemany(
+            f"""
+            INSERT INTO {MESSENGER_PARTICIPANT_IMPORTANCE_TABLE}
+            (
+                dataset_id, period_key, source_scope, participant_id,
+                centrality_degree, centrality_betweenness, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            importance_rows,
+        )
+
+    community_rows = []
+    for participant_id, community_id in communities.items():
+        community_rows.append(
+            (
+                dataset_id,
+                period_key,
+                source_scope,
+                participant_id,
+                int(community_id),
+                now,
+                now,
+            )
+        )
+    if community_rows:
+        conn.executemany(
+            f"""
+            INSERT INTO {MESSENGER_COMMUNITIES_TABLE}
+            (
+                dataset_id, period_key, source_scope, participant_id,
+                community_id, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+            """,
+            community_rows,
+        )
+    conn.commit()
+    return {
+        "edges_written": len(edge_rows),
+        "importance_written": len(importance_rows),
+        "communities_written": len(community_rows),
+    }
+
+
+def compute_and_persist_messenger_analytics(
+    *,
+    dataset_id: str,
+    conn: Optional[Any] = None,
+    start_ts: Optional[str] = None,
+    end_ts: Optional[str] = None,
+    source_ids: Optional[Sequence[str]] = None,
+    period_granularity: str = "month",
+    cumulative: bool = False,
+) -> Dict[str, Any]:
+    """Run Sprint 01 extraction + Sprint 02 metrics and persist derived analytics."""
+    if conn is not None:
+        db = conn
+    else:
+        from ..core.state import get_db_connection
+
+        db = get_db_connection()
+    if db is None:
+        raise RuntimeError("Database connection not available")
+
+    ensure_messenger_analytics_tables(db)
+    extraction = extract_messenger_graph(
+        dataset_id=dataset_id,
+        conn=db,
+        start_ts=start_ts,
+        end_ts=end_ts,
+        source_ids=source_ids,
+        period_granularity=period_granularity,
+        cumulative=cumulative,
+    )
+
+    scope = _source_scope(source_ids)
+    periods_out: List[Dict[str, Any]] = []
+    totals = {"edges_written": 0, "importance_written": 0, "communities_written": 0}
+
+    for period_payload in extraction.get("periods", []):
+        period_key = str(period_payload.get("period_key") or "")
+        if not period_key:
+            continue
+        computed = compute_importance_and_communities(period_payload)
+        writes = _persist_period_results(
+            db,
+            dataset_id=dataset_id,
+            period_key=period_key,
+            source_scope=scope,
+            period_payload=period_payload,
+            importance=computed["importance"],
+            communities=computed["communities"],
+        )
+        for key in totals:
+            totals[key] += writes[key]
+        periods_out.append(
+            {
+                "period_key": period_key,
+                **writes,
+                "nodes_count": len(period_payload.get("nodes", [])),
+                "edges_count": len(period_payload.get("edges", [])),
+            }
+        )
+
+    return {
+        "dataset_id": dataset_id,
+        "period_granularity": period_granularity,
+        "source_scope": scope,
+        "periods": periods_out,
+        "totals": totals,
+    }