Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
7.3 KB
Raw Blame
"""Serializable messaging conversation snapshots."""

from dataclasses import dataclass, field
from typing import Any

from loguru import logger

from ..models import MessageScope
from .identity import TreeIdentity
from .node import MessageNode, MessageState


@dataclass(frozen=True)
class TreeSnapshot:
    """Detached persisted representation of one conversation tree."""

    scope: MessageScope
    root_id: str
    nodes: dict[str, dict[str, Any]]

    @property
    def identity(self) -> TreeIdentity:
        return TreeIdentity(scope=self.scope, root_id=self.root_id)

    def to_json(self) -> dict[str, Any]:
        return {
            "scope": {
                "platform": self.scope.platform,
                "chat_id": self.scope.chat_id,
            },
            "root_id": self.root_id,
            "nodes": dict(self.nodes),
        }

    @classmethod
    def from_json(cls, data: Any) -> TreeSnapshot | None:
        if not isinstance(data, dict):
            return None
        root_id = data.get("root_id")
        nodes = data.get("nodes")
        if root_id is None or not isinstance(nodes, dict):
            return None
        normalized_root_id = str(root_id)
        scope_data = data.get("scope")
        scope: MessageScope | None = None
        if isinstance(scope_data, dict):
            platform = scope_data.get("platform")
            chat_id = scope_data.get("chat_id")
            if platform is not None and chat_id is not None:
                scope = MessageScope(platform=str(platform), chat_id=str(chat_id))
        if scope is None:
            scope = _legacy_scope(normalized_root_id, nodes)
        if scope is None:
            logger.warning(
                "Skipping messaging tree snapshot without recoverable scope: "
                "root_id={}",
                normalized_root_id,
            )
            return None
        return cls(scope=scope, root_id=normalized_root_id, nodes=dict(nodes))

    def lookup_ids(self) -> set[str]:
        lookup_ids: set[str] = set()
        for node_key, node_data in self.nodes.items():
            lookup_ids.add(str(node_key))
            if not isinstance(node_data, dict):
                continue
            node_id = node_data.get("node_id")
            if node_id is not None:
                lookup_ids.add(str(node_id))
            status_message_id = node_data.get("status_message_id")
            if status_message_id is not None:
                lookup_ids.add(str(status_message_id))
        return lookup_ids


@dataclass(frozen=True)
class ConversationSnapshot:
    """Detached persisted conversation trees keyed by customer identity."""

    trees: dict[TreeIdentity, TreeSnapshot] = field(default_factory=dict)

    @property
    def is_empty(self) -> bool:
        return not self.trees

    def to_json(self) -> dict[str, Any]:
        return {"trees": [tree.to_json() for tree in self.trees.values()]}

    @classmethod
    def from_json(cls, data: Any) -> ConversationSnapshot:
        if not isinstance(data, dict):
            return cls()
        raw_trees = data.get("trees", [])
        if isinstance(raw_trees, dict):
            candidates = raw_trees.values()
        elif isinstance(raw_trees, list):
            candidates = raw_trees
        else:
            return cls()

        trees: dict[TreeIdentity, TreeSnapshot] = {}
        for raw_tree in candidates:
            snapshot = TreeSnapshot.from_json(raw_tree)
            if snapshot is None:
                continue
            trees[snapshot.identity] = snapshot
        return cls(trees=trees)

    def get_tree(self, identity: TreeIdentity) -> TreeSnapshot | None:
        return self.trees.get(identity)

    def with_tree(self, tree_snapshot: TreeSnapshot) -> ConversationSnapshot:
        trees = dict(self.trees)
        trees[tree_snapshot.identity] = tree_snapshot
        return ConversationSnapshot(trees=trees)

    def without_tree(self, identity: TreeIdentity) -> ConversationSnapshot:
        trees = dict(self.trees)
        trees.pop(identity, None)
        return ConversationSnapshot(trees=trees)

    def without_scope(self, scope: MessageScope) -> ConversationSnapshot:
        """Remove every tree belonging to one platform chat."""
        return ConversationSnapshot(
            trees={
                identity: tree
                for identity, tree in self.trees.items()
                if identity.scope != scope
            }
        )


def _legacy_scope(
    root_id: str,
    nodes: dict[str, Any],
) -> MessageScope | None:
    """Derive scope from pre-scope snapshots without retaining a runtime shim."""
    root = nodes.get(root_id)
    if not isinstance(root, dict):
        root = next(
            (
                node
                for node in nodes.values()
                if isinstance(node, dict) and str(node.get("node_id")) == root_id
            ),
            None,
        )
    if not isinstance(root, dict):
        return None
    return node_scope_from_snapshot(root)


def node_scope_from_snapshot(data: dict[str, Any]) -> MessageScope | None:
    """Read the redundant scope carried by legacy node payloads, if present."""
    incoming = data.get("incoming")
    if not isinstance(incoming, dict):
        return None
    platform = incoming.get("platform")
    chat_id = incoming.get("chat_id")
    if platform is None or chat_id is None:
        return None
    return MessageScope(platform=str(platform), chat_id=str(chat_id))


def node_to_snapshot(node: MessageNode) -> dict[str, Any]:
    return {
        "node_id": node.node_id,
        "status_message_id": node.status_message_id,
        "state": node.state.value,
        "parent_id": node.parent_id,
        "parent_reference_id": node.parent_reference_id,
        "session_id": node.session_id,
    }


def node_from_snapshot(data: dict[str, Any], scope: MessageScope) -> MessageNode:
    state = MessageState(data["state"])
    status_message_id = _optional_id(
        data.get("status_message_id"),
        "status_message_id",
    )
    if state in (MessageState.PENDING, MessageState.IN_PROGRESS) and (
        status_message_id is None
    ):
        raise ValueError("Runnable tree snapshot node requires a status message")
    parent_id = _optional_id(data.get("parent_id"), "parent_id")
    parent_reference_id = _optional_id(
        data.get("parent_reference_id"),
        "parent_reference_id",
    )
    if parent_reference_id is None:
        parent_reference_id = parent_id
    return MessageNode(
        node_id=_required_id(data.get("node_id"), "node_id"),
        scope=scope,
        prompt="",
        status_message_id=status_message_id,
        state=state,
        parent_id=parent_id,
        parent_reference_id=parent_reference_id,
        session_id=_optional_id(data.get("session_id"), "session_id"),
    )


def _required_id(value: Any, field_name: str) -> str:
    normalized = _optional_id(value, field_name)
    if normalized is None:
        raise ValueError(f"Tree snapshot {field_name} is required")
    return normalized


def _optional_id(value: Any, field_name: str) -> str | None:
    if value is None:
        return None
    if isinstance(value, bool) or not isinstance(value, str | int):
        raise ValueError(f"Tree snapshot {field_name} must be a string or integer")
    normalized = str(value)
    if not normalized:
        raise ValueError(f"Tree snapshot {field_name} cannot be empty")
    return normalized