digital-brain 0.1.3 → 1.0.3

package/scripts/digital_brain_imessage_sync.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+import argparse
+import hashlib
+import json
+import sqlite3
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+CORE_DATA_EPOCH_OFFSET = 978_307_200
+DEFAULT_DB = Path.home() / "Library" / "Messages" / "chat.db"
+
+
+def main():
+    args = parse_args()
+    if not args.db.exists():
+        raise SystemExit(
+            f"Apple Messages database not found: {args.db}\n"
+            "Open Messages on macOS and grant Terminal Full Disk Access if macOS blocks access."
+        )
+
+    vault = args.vault.resolve()
+    source_dir = vault / "08 Sources" / "iMessage"
+    raw_dir = source_dir / "Raw"
+    chats_dir = source_dir / "ChatsByMonth"
+    state_dir = source_dir / ".sync-state"
+    for directory in (raw_dir, chats_dir, state_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    seen_path = state_dir / "imessage-seen-message-ids.json"
+    seen = load_seen(seen_path)
+    added = sync_once(args, seen, raw_dir, chats_dir)
+    save_seen(seen_path, seen)
+    print(f"Imported {added} iMessage messages.")
+
+
+def sync_once(args, seen, raw_dir, chats_dir):
+    cutoff = datetime.now(timezone.utc).timestamp() - args.days * 24 * 60 * 60 if args.days else None
+    conn = sqlite3.connect(f"file:{args.db}?mode=ro", uri=True)
+    conn.row_factory = sqlite3.Row
+    rows = conn.execute(
+        """
+        SELECT m.ROWID message_pk, m.guid guid, m.date message_date,
+               m.is_from_me is_from_me, m.text text, m.service service,
+               h.id handle_id,
+               c.ROWID chat_pk, c.display_name display_name, c.chat_identifier chat_identifier
+        FROM message m
+        LEFT JOIN handle h ON h.ROWID = m.handle_id
+        LEFT JOIN chat_message_join cmj ON cmj.message_id = m.ROWID
+        LEFT JOIN chat c ON c.ROWID = cmj.chat_id
+        WHERE m.text IS NOT NULL
+          AND length(m.text) > 0
+        ORDER BY m.date ASC, m.ROWID ASC
+        """
+    ).fetchall()
+    conn.close()
+
+    added = 0
+    for row in rows:
+        record = row_to_record(row, args.self_name, args.privacy_mode)
+        if cutoff and datetime.fromisoformat(record["timestamp"]).timestamp() < cutoff:
+            continue
+        if args.chat and args.chat.lower() not in record["chatName"].lower():
+            continue
+        if record["id"] in seen:
+            continue
+        append_jsonl(raw_dir, record)
+        append_markdown(chats_dir, record, args.markdown_mode)
+        seen.add(record["id"])
+        added += 1
+    return added
+
+
+def row_to_record(row, self_name, privacy_mode):
+    timestamp = apple_timestamp(row["message_date"])
+    body = row["text"] or ""
+    from_me = bool(row["is_from_me"])
+    chat_name = row["display_name"] or row["chat_identifier"] or row["handle_id"] or "iMessage"
+    return {
+        "id": compound_id(row, timestamp),
+        "source": "Apple Messages chat.db",
+        "sourceSystem": "iMessage",
+        "timestamp": timestamp,
+        "chatPk": row["chat_pk"],
+        "chatName": chat_name,
+        "chatIdentifier": row["chat_identifier"],
+        "isGroup": bool(row["display_name"]) or str(row["chat_identifier"] or "").startswith("chat"),
+        "fromMe": from_me,
+        "author": self_name if from_me else (row["handle_id"] or "Unknown"),
+        "handleId": row["handle_id"],
+        "service": row["service"],
+        "body": "" if privacy_mode == "metadata-only" else body,
+        "bodyHash": hashlib.sha256(body.encode("utf-8")).hexdigest() if privacy_mode == "metadata-only" else "",
+        "bodyCharCount": len(body),
+    }
+
+
+def apple_timestamp(value):
+    raw = float(value or 0)
+    seconds = raw / 1_000_000_000 if abs(raw) > 10_000_000_000 else raw
+    return datetime.fromtimestamp(seconds + CORE_DATA_EPOCH_OFFSET, tz=timezone.utc).isoformat()
+
+
+def compound_id(row, timestamp):
+    return "::".join([
+        "imessage",
+        str(row["chat_pk"] or row["chat_identifier"] or row["handle_id"] or "unknown-chat"),
+        str(row["guid"] or "no-guid"),
+        str(row["message_pk"] or "no-pk"),
+        timestamp,
+    ])
+
+
+def append_jsonl(raw_dir, record):
+    with (raw_dir / f"{record['timestamp'][:10]}.jsonl").open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def append_markdown(chats_dir, record, mode):
+    if mode == "none":
+        return
+    directory = chats_dir / record["timestamp"][:7]
+    directory.mkdir(parents=True, exist_ok=True)
+    file_path = directory / f"{safe_filename(record['chatName'])}.md"
+    if not file_path.exists():
+        write_text_atomic(file_path, f"# {escape_markdown(record['chatName'])}\n\nSynced from Apple Messages.\n\n")
+    speaker = escape_markdown(record["author"])
+    body = escape_markdown(" ".join(record["body"].split()))
+    with file_path.open("a", encoding="utf-8") as f:
+        f.write(f"- {record['timestamp']} | {speaker}: {body}\n")
+
+
+def load_seen(path):
+    if not path.exists():
+        return set()
+    try:
+        return set(json.loads(path.read_text(encoding="utf-8")))
+    except Exception:
+        return set()
+
+
+def save_seen(path, seen):
+    write_text_atomic(path, json.dumps(sorted(seen), indent=2))
+
+
+def safe_filename(value):
+    cleaned = "".join("-" if char in '/:\\?%*"<>|' else char for char in value)
+    return (" ".join(cleaned.split()).strip() or "iMessage")[:120]
+
+
+def escape_markdown(value):
+    text = str(value).replace("\n", " ").replace("\r", " ")
+    return text.replace("\\", "\\\\").replace("[", "\\[").replace("]", "\\]").replace("|", "\\|")
+
+
+def write_text_atomic(path, content):
+    temp = path.with_name(f"{path.name}.{time.time_ns()}.tmp")
+    temp.write_text(content, encoding="utf-8")
+    temp.replace(path)
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--vault", type=Path, required=True)
+    parser.add_argument("--days", type=int, default=30)
+    parser.add_argument("--chat", default="")
+    parser.add_argument("--db", type=Path, default=DEFAULT_DB)
+    parser.add_argument("--self-name", default="Me")
+    parser.add_argument("--markdown-mode", choices=["chat", "month", "none"], default="none")
+    parser.add_argument("--privacy-mode", choices=["standard", "metadata-only"], default="standard")
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/digital_brain_linkedin_export_import.py

@@ -0,0 +1,214 @@
+#!/usr/bin/env python3
+import argparse
+import csv
+import json
+import tempfile
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+def main():
+    args = parse_args()
+    with unpack(args.input) as source:
+        import_archive(args.vault.resolve(), source, args.days)
+
+
+def import_archive(vault, source, days):
+    linkedin = vault / "08 Sources" / "LinkedIn"
+    raw_dir = linkedin / "Raw"
+    state_dir = linkedin / ".sync-state"
+    people_dir = vault / "04 People"
+    for directory in (raw_dir, state_dir, people_dir):
+        directory.mkdir(parents=True, exist_ok=True)
+
+    cutoff = datetime.now(timezone.utc).timestamp() - days * 24 * 60 * 60 if days else None
+    seen_path = state_dir / "linkedin-seen-message-ids.json"
+    seen = load_seen(seen_path)
+    imported_messages = 0
+    imported_connections = write_connections(source, people_dir)
+
+    for file in find_csvs(source, "message"):
+        for row in read_csv(file):
+            record = message_record(row, file)
+            if not record:
+                continue
+            if cutoff and datetime.fromisoformat(record["timestamp"]).timestamp() < cutoff:
+                continue
+            if record["id"] in seen:
+                continue
+            append_jsonl(raw_dir, record)
+            seen.add(record["id"])
+            imported_messages += 1
+
+    save_seen(seen_path, seen)
+    print(f"Imported {imported_messages} LinkedIn messages.")
+    print(f"Indexed {imported_connections} LinkedIn connections.")
+
+
+def write_connections(source, people_dir):
+    files = find_csvs(source, "connection")
+    if not files:
+        return 0
+    rows = []
+    for file in files:
+        rows.extend(read_csv(file))
+    lines = ["# LinkedIn Connections", "", "Imported from LinkedIn data archive.", ""]
+    count = 0
+    for row in rows:
+        name = first_value(row, ["First Name", "FirstName", "First name"])
+        last = first_value(row, ["Last Name", "LastName", "Last name"])
+        full_name = " ".join(part for part in [name, last] if part).strip() or first_value(row, ["Name", "Full Name"])
+        company = first_value(row, ["Company", "Company Name"])
+        position = first_value(row, ["Position", "Title"])
+        connected_on = first_value(row, ["Connected On", "ConnectedOn"])
+        if not full_name:
+            continue
+        detail = ", ".join(part for part in [position, company, connected_on] if part)
+        lines.append(f"- {full_name}{f' - {detail}' if detail else ''}")
+        count += 1
+    if count:
+        (people_dir / "LinkedIn Connections.md").write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return count
+
+
+def message_record(row, file):
+    body = first_value(row, ["Content", "Message", "Body", "Text"])
+    if not body:
+        return None
+    timestamp = parse_timestamp(first_value(row, ["Date", "Created At", "Timestamp", "Sent Date"]))
+    if not timestamp:
+        return None
+    sender = first_value(row, ["From", "Sender", "Sender Name", "From Name"]) or "Unknown"
+    recipients = first_value(row, ["To", "Recipient", "Recipients", "To Name"]) or "Unknown"
+    explicit_conversation = first_value(row, ["Conversation Title", "Subject", "Conversation"])
+    conversation = explicit_conversation or other_party(sender, recipients)
+    return {
+        "id": f"linkedin-{file.name}-{timestamp}-{sender}-{hash(body)}",
+        "source": "LinkedIn data archive",
+        "sourceSystem": "LinkedIn",
+        "timestamp": timestamp,
+        "chatName": conversation,
+        "isGroup": "," in recipients,
+        "fromMe": False,
+        "author": sender,
+        "to": recipients,
+        "body": body,
+    }
+
+
+def other_party(sender, recipients):
+    if sender and sender.lower() not in {"me", "you"}:
+        return sender
+    if recipients and recipients.lower() not in {"me", "you"}:
+        return recipients.split(",")[0].strip()
+    return sender or recipients or "Unknown"
+
+
+def parse_timestamp(value):
+    if not value:
+        return ""
+    value = value.strip()
+    formats = [
+        "%Y-%m-%d %H:%M:%S",
+        "%Y-%m-%dT%H:%M:%S.%fZ",
+        "%Y-%m-%dT%H:%M:%SZ",
+        "%m/%d/%Y, %I:%M %p",
+        "%m/%d/%Y",
+        "%Y-%m-%d",
+    ]
+    for fmt in formats:
+        try:
+            return datetime.strptime(value, fmt).replace(tzinfo=timezone.utc).isoformat()
+        except ValueError:
+            pass
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc).isoformat()
+    except ValueError:
+        return ""
+
+
+def append_jsonl(raw_dir, record):
+    with (raw_dir / f"{record['timestamp'][:10]}.jsonl").open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+
+def find_csvs(source, needle):
+    return sorted(path for path in source.rglob("*.csv") if needle.lower() in path.name.lower())
+
+
+def read_csv(path):
+    with path.open("r", encoding="utf-8-sig", newline="") as f:
+        return list(csv.DictReader(f))
+
+
+def first_value(row, keys):
+    for key in keys:
+        value = row.get(key)
+        if value:
+            return value.strip()
+    lower = {key.lower(): value for key, value in row.items()}
+    for key in keys:
+        value = lower.get(key.lower())
+        if value:
+            return value.strip()
+    return ""
+
+
+def load_seen(path):
+    if not path.exists():
+        return set()
+    try:
+        return set(json.loads(path.read_text(encoding="utf-8")))
+    except Exception:
+        return set()
+
+
+def save_seen(path, seen):
+    path.write_text(json.dumps(sorted(seen), indent=2), encoding="utf-8")
+
+
+def unpack(input_path):
+    input_path = input_path.resolve()
+    if input_path.is_dir():
+        return NullContext(input_path)
+    temp = tempfile.TemporaryDirectory()
+    with zipfile.ZipFile(input_path) as archive:
+        archive.extractall(temp.name)
+    return TempContext(Path(temp.name), temp)
+
+
+class NullContext:
+    def __init__(self, path):
+        self.path = path
+
+    def __enter__(self):
+        return self.path
+
+    def __exit__(self, *_):
+        return False
+
+
+class TempContext:
+    def __init__(self, path, temp):
+        self.path = path
+        self.temp = temp
+
+    def __enter__(self):
+        return self.path
+
+    def __exit__(self, *_):
+        self.temp.cleanup()
+        return False
+
+
+def parse_args():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--vault", type=Path, required=True)
+    parser.add_argument("--input", type=Path, required=True)
+    parser.add_argument("--days", type=int, default=3650)
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/digital_brain_relationship_extractor.py

@@ -3,6 +3,7 @@ import argparse
 import json
 import math
 import re
+import time
 from collections import Counter, defaultdict
 from datetime import datetime, timezone
 from pathlib import Path
@@ -17,26 +18,36 @@ SLANG = {"lol", "lmao", "haha", "hahaha", "bro", "bruh", "wtf", "omg", "ngl", "i
 def main():
     args = parse_args()
     vault = args.vault.resolve()
-    whatsapp = vault / "08 Sources" / "WhatsApp"
-    output_dir = whatsapp / "Analysis"
+    sources = vault / "08 Sources"
+    output_dir = sources / "Analysis"
     output_dir.mkdir(parents=True, exist_ok=True)
-    messages = load_messages(whatsapp / "Raw", args.days)
+    messages = load_messages(sources, args.days)
     profiles = build_profiles(messages, args.min_messages)
-    (output_dir / "relationship_profiles.json").write_text(json.dumps(profiles, indent=2, ensure_ascii=False), encoding="utf-8")
+    people = build_people(profiles)
+    write_json_atomic(output_dir / "relationship_profiles.json", profiles)
+    write_json_atomic(output_dir / "person_identity_map.json", people)
     write_markdown(output_dir / "Relationship Map.md", profiles, args.days)
+    write_people_memory(vault / "06 AI Memory" / "Person Context Index.md", people, args.days)
+    write_legacy_whatsapp_outputs(vault, output_dir)
     print(f"Analyzed {len(messages)} messages.")
     print(f"Wrote {len(profiles)} relationship profiles.")
+    print(f"Wrote {len(people)} canonical person records.")
 
 
-def load_messages(raw_dir, days):
+def load_messages(sources_dir, days):
     cutoff = datetime.now(timezone.utc).timestamp() - days * 24 * 60 * 60 if days else None
     messages = []
-    for path in sorted(raw_dir.glob("*.jsonl")):
+    raw_files = sorted(sources_dir.glob("*/Raw/*.jsonl"))
+    for path in raw_files:
         with path.open("r", encoding="utf-8") as f:
             for line in f:
                 if not line.strip():
                     continue
-                record = json.loads(line)
+                try:
+                    record = json.loads(line)
+                except json.JSONDecodeError:
+                    print(f"Skipping corrupt JSONL line in {path}")
+                    continue
                 dt = datetime.fromisoformat(record["timestamp"].replace("Z", "+00:00"))
                 if cutoff and dt.timestamp() < cutoff:
                     continue
@@ -48,13 +59,15 @@ def load_messages(raw_dir, days):
 def build_profiles(messages, min_messages):
     by_chat = defaultdict(list)
     for message in messages:
-        by_chat[message.get("chatName") or "Unknown Chat"].append(message)
-    profiles = [profile_chat(name, items) for name, items in by_chat.items() if len(items) >= min_messages]
+        key = f"{message.get('sourceSystem') or source_system(message)}::{message.get('chatName') or 'Unknown Chat'}"
+        by_chat[key].append(message)
+    profiles = [profile_chat(key, items) for key, items in by_chat.items() if len(items) >= min_messages]
     profiles.sort(key=lambda p: (p["messageCount"], p["lastSeen"]), reverse=True)
     return profiles
 
 
-def profile_chat(chat_name, messages):
+def profile_chat(chat_key, messages):
+    source, chat_name = split_chat_key(chat_key)
     count = len(messages)
     outbound = sum(1 for m in messages if m.get("fromMe"))
     inbound = count - outbound
@@ -72,8 +85,15 @@ def profile_chat(chat_name, messages):
     sentiment = normalized_sentiment(positive, negative, count)
     tags = infer_tags(any(m.get("isGroup") for m in messages), count, inbound, outbound, warmth, friction, operational, work, logistics, text.count("?"))
     guess = infer_relationship(tags, count, warmth, friction, operational, work, outbound / count)
+    identity = infer_identity(source, chat_name, messages)
     return {
         "chatName": chat_name,
+        "sourceSystem": source,
+        "displayName": f"{chat_name} ({source})",
+        "identityName": identity["name"],
+        "canonicalPersonKey": identity["key"],
+        "identityConfidence": identity["confidence"],
+        "identityEvidence": identity["evidence"],
         "messageCount": count,
         "inbound": inbound,
         "outbound": outbound,
@@ -130,12 +150,110 @@ def infer_relationship(tags, count, warmth, friction, operational, work, balance
     return "general relationship, needs human labeling"
 
 
+def infer_identity(source, chat_name, messages):
+    is_group = any(m.get("isGroup") for m in messages)
+    if is_group:
+        return {
+            "name": chat_name,
+            "key": f"group::{source.lower()}::{normalize_identity(chat_name)}",
+            "confidence": "medium",
+            "evidence": "group chat kept source-specific",
+        }
+    candidates = []
+    if source in {"Slack", "LinkedIn"}:
+        candidates.extend((m.get("author") or "").strip() for m in messages if not m.get("fromMe"))
+    if source == "LinkedIn":
+        candidates.extend((m.get("to") or "").split(",")[0].strip() for m in messages if m.get("fromMe"))
+    candidates.append(chat_name)
+    name = best_identity_name(candidates) or chat_name
+    key = f"person::{normalize_identity(name)}"
+    confidence = "medium" if normalize_identity(name) == normalize_identity(chat_name) else "low"
+    if source in {"Slack", "LinkedIn"} and normalize_identity(name) != normalize_identity(chat_name):
+        confidence = "medium"
+    return {
+        "name": name,
+        "key": key,
+        "confidence": confidence,
+        "evidence": f"{source} direct chat identity",
+    }
+
+
+def best_identity_name(candidates):
+    cleaned = [candidate for candidate in candidates if usable_identity_name(candidate)]
+    if not cleaned:
+        return ""
+    counts = Counter(normalize_identity(candidate) for candidate in cleaned)
+    best_key, _ = counts.most_common(1)[0]
+    for candidate in cleaned:
+        if normalize_identity(candidate) == best_key:
+            return candidate
+    return cleaned[0]
+
+
+def usable_identity_name(value):
+    if not value:
+        return False
+    normalized = normalize_identity(value)
+    if not normalized or normalized in {"me", "you", "unknown", "unknown chat", "imessage"}:
+        return False
+    return True
+
+
+def normalize_identity(value):
+    text = str(value or "").lower()
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"https?://\S+", " ", text)
+    text = re.sub(r"[^a-z0-9@+]+", " ", text)
+    return " ".join(text.split())
+
+
+def build_people(profiles):
+    grouped = defaultdict(list)
+    for profile in profiles:
+        key = profile.get("canonicalPersonKey")
+        if key and not key.startswith("group::"):
+            grouped[key].append(profile)
+    people = []
+    for key, items in grouped.items():
+        items.sort(key=lambda item: (item["messageCount"], item["lastSeen"]), reverse=True)
+        sources = sorted({item["sourceSystem"] for item in items})
+        names = [item.get("identityName") or item["chatName"] for item in items]
+        people.append({
+            "canonicalPersonKey": key,
+            "displayName": names[0],
+            "aliases": sorted({name for name in names if name}),
+            "sources": sources,
+            "sourceProfiles": [
+                {
+                    "sourceSystem": item["sourceSystem"],
+                    "chatName": item["chatName"],
+                    "displayName": item["displayName"],
+                    "messageCount": item["messageCount"],
+                    "firstSeen": item["firstSeen"],
+                    "lastSeen": item["lastSeen"],
+                    "relationshipGuess": item["relationshipGuess"],
+                    "typingStyle": item["typingStyle"],
+                    "identityConfidence": item["identityConfidence"],
+                    "identityEvidence": item["identityEvidence"],
+                }
+                for item in items
+            ],
+            "totalMessages": sum(item["messageCount"] for item in items),
+            "firstSeen": min(item["firstSeen"] for item in items),
+            "lastSeen": max(item["lastSeen"] for item in items),
+        })
+    people.sort(key=lambda person: (len(person["sources"]), person["totalMessages"], person["lastSeen"]), reverse=True)
+    return people
+
+
 def write_markdown(path, profiles, days):
     lines = ["# Relationship Map", "", f"Window: last {days} days", "", "Generated signals. Treat as editable working notes.", ""]
     for profile in profiles:
         lines.extend([
-            f"## {profile['chatName']}",
+            f"## {profile['displayName']}",
             "",
+            f"- Source: {profile['sourceSystem']}",
+            f"- Canonical person: {profile['identityName']} ({profile['canonicalPersonKey']})",
             f"- Guess: {profile['relationshipGuess']}",
             f"- Messages: {profile['messageCount']} ({profile['inbound']} inbound, {profile['outbound']} outbound)",
             f"- Dates: {profile['firstSeen']} to {profile['lastSeen']}",
@@ -144,7 +262,66 @@ def write_markdown(path, profiles, days):
             f"- Typing style: {typing_style_summary(profile['typingStyle'])}",
             "",
         ])
-    path.write_text("\n".join(lines), encoding="utf-8")
+    write_text_atomic(path, "\n".join(lines))
+
+
+def write_people_memory(path, people, days):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = ["# Person Context Index", "", f"Window: last {days} days", "", "Canonical people matched across sources. Treat matches as provisional unless manually confirmed.", ""]
+    for person in people:
+        lines.extend([
+            f"## {person['displayName']}",
+            "",
+            f"- Canonical key: `{person['canonicalPersonKey']}`",
+            f"- Aliases: {', '.join(person['aliases'])}",
+            f"- Sources: {', '.join(person['sources'])}",
+            f"- Messages: {person['totalMessages']}",
+            f"- Dates: {person['firstSeen']} to {person['lastSeen']}",
+            "- Source-specific context:",
+        ])
+        for source in person["sourceProfiles"]:
+            style = typing_style_summary(source.get("typingStyle", {}))
+            lines.append(f"  - {source['sourceSystem']} / {source['chatName']}: {source['relationshipGuess']}; {source['messageCount']} messages; style {style}")
+        lines.append("")
+    write_text_atomic(path, "\n".join(lines) + "\n")
+
+
+def write_legacy_whatsapp_outputs(vault, output_dir):
+    legacy_dir = vault / "08 Sources" / "WhatsApp" / "Analysis"
+    legacy_dir.mkdir(parents=True, exist_ok=True)
+    for name in ("relationship_profiles.json", "person_identity_map.json", "Relationship Map.md"):
+        source = output_dir / name
+        target = legacy_dir / name
+        if source.exists():
+            write_text_atomic(target, source.read_text(encoding="utf-8"))
+
+
+def write_json_atomic(path, data):
+    write_text_atomic(path, json.dumps(data, indent=2, ensure_ascii=False))
+
+
+def write_text_atomic(path, content):
+    temp = path.with_name(f"{path.name}.{time.time_ns()}.tmp")
+    temp.write_text(content, encoding="utf-8")
+    temp.replace(path)
+
+
+def source_system(message):
+    source = message.get("source") or ""
+    if "Slack" in source:
+        return "Slack"
+    if "LinkedIn" in source:
+        return "LinkedIn"
+    if "WhatsApp" in source:
+        return "WhatsApp"
+    return "Unknown"
+
+
+def split_chat_key(key):
+    if "::" not in key:
+        return "Unknown", key
+    source, chat_name = key.split("::", 1)
+    return source, chat_name
 
 
 def score(words, lexicon):