alpha-avatar-plugins-memory 0.6.2__tar.gz → 0.6.3__tar.gz

{alpha_avatar_plugins_memory-0.6.2 → alpha_avatar_plugins_memory-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-avatar-plugins-memory
-Version: 0.6.2
+Version: 0.6.3
 Summary: AlphaAvatar Framework plugin for memory service
 Project-URL: Source, https://github.com/AlphaAvatar/AlphaAvatar
 License-Expression: Apache-2.0

alpha_avatar_plugins_memory-0.6.3/alphaavatar/plugins/memory/graph/__init__.py

@@ -0,0 +1,24 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .graph_alias import save_graph_aliases
+from .graph_builder import build_graph_from_mentions
+from .graph_lookup import GraphLookup
+from .graph_store import save_memory_graph_stubs
+
+__all__ = [
+    "save_graph_aliases",
+    "build_graph_from_mentions",
+    "GraphLookup",
+    "save_memory_graph_stubs",
+]

alpha_avatar_plugins_memory-0.6.3/alphaavatar/plugins/memory/graph/graph_alias.py

@@ -0,0 +1,144 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import json
+import pathlib
+from typing import Any
+
+
+def _json_dumps(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, default=str)
+
+
+def _json_loads(line: str) -> dict[str, Any] | None:
+    try:
+        data = json.loads(line)
+        return data if isinstance(data, dict) else None
+    except Exception:
+        return None
+
+
+def _read_alias_map(path: pathlib.Path) -> dict[str, dict[str, Any]]:
+    if not path.exists():
+        return {}
+
+    out: dict[str, dict[str, Any]] = {}
+
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+
+        row = _json_loads(line)
+        if not row:
+            continue
+
+        alias_key = str(row.get("alias_key", "")).strip()
+        canonical_key = str(row.get("canonical_key", "")).strip()
+
+        if not alias_key or not canonical_key:
+            continue
+
+        out[alias_key] = row
+
+    return out
+
+
+def _write_aliases(path: pathlib.Path, aliases: dict[str, dict[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    rows = sorted(
+        aliases.values(),
+        key=lambda x: (
+            str(x.get("canonical_key", "")),
+            str(x.get("alias_key", "")),
+        ),
+    )
+
+    text = "\n".join(_json_dumps(row) for row in rows)
+    path.write_text(text + ("\n" if text else ""), encoding="utf-8")
+
+
+def save_graph_aliases(
+    *,
+    graph_path: str | pathlib.Path,
+    aliases: list[dict[str, Any]],
+) -> dict[str, Any]:
+    graph_path = pathlib.Path(graph_path)
+    aliases_path = graph_path / "aliases.jsonl"
+
+    alias_map = _read_alias_map(aliases_path)
+
+    updated = 0
+    skipped = 0
+    conflicts: list[dict[str, Any]] = []
+
+    for alias in aliases:
+        alias_key = str(alias.get("alias_key", "")).strip()
+        canonical_key = str(alias.get("canonical_key", "")).strip()
+
+        if not alias_key or not canonical_key or alias_key == canonical_key:
+            skipped += 1
+            continue
+
+        # local detector keys must already be scoped before aliasing
+        if alias_key.startswith(("face:", "voice:", "object:")) and ":local:" not in alias_key:
+            skipped += 1
+            conflicts.append(
+                {
+                    "alias_key": alias_key,
+                    "canonical_key": canonical_key,
+                    "reason": "unscoped_local_key",
+                }
+            )
+            continue
+
+        old = alias_map.get(alias_key)
+
+        if old:
+            old_canonical = str(old.get("canonical_key", "")).strip()
+            old_weight = float(old.get("weight", 0.0))
+            new_weight = float(alias.get("weight", 0.0))
+
+            # If conflict, only replace when new confidence is higher.
+            if old_canonical and old_canonical != canonical_key and new_weight < old_weight:
+                conflicts.append(
+                    {
+                        "alias_key": alias_key,
+                        "old_canonical_key": old_canonical,
+                        "new_canonical_key": canonical_key,
+                        "old_weight": old_weight,
+                        "new_weight": new_weight,
+                        "reason": "lower_confidence_conflict",
+                    }
+                )
+                skipped += 1
+                continue
+
+            merged = dict(old)
+            merged.update(alias)
+            alias_map[alias_key] = merged
+        else:
+            alias_map[alias_key] = alias
+
+        updated += 1
+
+    _write_aliases(aliases_path, alias_map)
+
+    return {
+        "aliases_file": str(aliases_path),
+        "aliases": len(alias_map),
+        "updated": updated,
+        "skipped": skipped,
+        "conflicts": conflicts,
+    }

alpha_avatar_plugins_memory-0.6.3/alphaavatar/plugins/memory/graph/graph_builder.py

@@ -0,0 +1,230 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import hashlib
+from collections.abc import Iterable
+from itertools import combinations
+
+from alphaavatar.agents.memory import MemoryItem
+from alphaavatar.agents.memory.schema.graph import (
+    GraphNodeMention,
+    MemoryGraphLink,
+    MemoryGraphNode,
+)
+
+LOCAL_NODE_TYPES = {"face", "voice", "speaker", "object"}
+
+GLOBAL_KEY_PREFIXES = (
+    "user:",
+    "tool:",
+    "project:",
+    "concept:",
+    "artifact:",
+    "image:",
+    "audio:",
+    "turn:",
+    "memory_item:",
+)
+
+
+def _is_global_key(key: str) -> bool:
+    return key.startswith(GLOBAL_KEY_PREFIXES)
+
+
+def _is_scoped_local_key(key: str) -> bool:
+    return ":local:" in key
+
+
+def _normalize_node_type(node_type: str | None) -> str:
+    value = str(node_type or "text").strip().lower()
+    if value == "speaker":
+        return "voice"
+    return value
+
+
+def _norm_text(value: str) -> str:
+    return " ".join(str(value or "").strip().lower().split())
+
+
+def _scope_local_key(
+    *,
+    key: str,
+    node_type: str,
+    session_id: str,
+) -> tuple[str, str]:
+    """
+    Return:
+    - scoped/global graph key
+    - key_scope: global | session
+    """
+    key = str(key or "").strip()
+    node_type = _normalize_node_type(node_type)
+
+    if not key:
+        return "", "unknown"
+
+    if _is_global_key(key) or _is_scoped_local_key(key):
+        return key, "global" if _is_global_key(key) else "session"
+
+    if node_type in LOCAL_NODE_TYPES:
+        # key examples:
+        #   face:tmp_1 -> tmp_1
+        #   voice:speaker_1 -> speaker_1
+        #   tmp_1 -> tmp_1
+        if ":" in key:
+            _, local_id = key.split(":", 1)
+        else:
+            local_id = key
+
+        return f"{node_type}:local:{session_id}:{local_id}", "session"
+
+    return key, "global"
+
+
+def _stable_key(*, node_type: str, content: str) -> str:
+    raw = f"{node_type}:{_norm_text(content)}"
+    digest = hashlib.sha256(raw.encode("utf-8", errors="ignore")).hexdigest()[:16]
+    return f"{node_type}:{digest}"
+
+
+def normalize_mention(
+    mention: GraphNodeMention,
+    *,
+    session_id: str,
+) -> MemoryGraphNode | None:
+    content = str(mention.content or "").strip()
+    if not content:
+        return None
+
+    node_type = _normalize_node_type(mention.type)
+
+    raw_key = str(mention.key or "").strip()
+    if raw_key:
+        key, key_scope = _scope_local_key(
+            key=raw_key,
+            node_type=node_type,
+            session_id=session_id,
+        )
+    else:
+        if node_type in LOCAL_NODE_TYPES:
+            digest = hashlib.sha256(
+                f"{node_type}:{_norm_text(content)}".encode("utf-8", errors="ignore")
+            ).hexdigest()[:16]
+            key = f"{node_type}:local:{session_id}:{digest}"
+            key_scope = "session"
+        else:
+            key = _stable_key(node_type=node_type, content=content)
+            key_scope = "global"
+
+    extra_data = {}
+    if raw_key:
+        extra_data.setdefault("raw_key", raw_key)
+    extra_data.setdefault("key_scope", key_scope)
+
+    return MemoryGraphNode(
+        key=key,
+        type=node_type,
+        content=content,
+        weight=mention.weight,
+        extra_data=extra_data,
+    )
+
+
+def build_memory_item_node(item: MemoryItem) -> MemoryGraphNode:
+    return MemoryGraphNode(
+        key=f"memory_item:{item.memory_id}",
+        type="text",
+        content=item.value,
+        weight=1.0,
+        extra_data={
+            "node_kind": "memory_item",
+            "memory_id": item.memory_id,
+            "session_id": item.session_id,
+            "object_ids": item.object_ids,
+            "memory_type": str(item.memory_type),
+            "topic": item.topic,
+            "timestamp": item.timestamp,
+        },
+    )
+
+
+def _is_memory_item_node(node: MemoryGraphNode) -> bool:
+    return (node.extra_data or {}).get("node_kind") == "memory_item"
+
+
+def build_graph_from_mentions(
+    *,
+    item: MemoryItem,
+    mentions: Iterable[GraphNodeMention],
+) -> tuple[list[MemoryGraphNode], list[MemoryGraphLink]]:
+    item_node = build_memory_item_node(item)
+
+    nodes_by_key: dict[str, MemoryGraphNode] = {
+        item_node.key: item_node,
+    }
+
+    for mention in mentions:
+        node = normalize_mention(mention, session_id=item.session_id)
+        if node is None:
+            continue
+
+        old = nodes_by_key.get(node.key)
+        if old is not None:
+            old.weight = max(old.weight, node.weight)
+            old.extra_data.update(node.extra_data)
+        else:
+            nodes_by_key[node.key] = node
+
+    nodes = list(nodes_by_key.values())
+    mention_nodes = [node for node in nodes if not _is_memory_item_node(node)]
+
+    links: list[MemoryGraphLink] = []
+
+    # memory item -> node
+    for node in mention_nodes:
+        links.append(
+            MemoryGraphLink(
+                source_id=item_node.id,
+                target_id=node.id,
+                source_key=item_node.key,
+                target_key=node.key,
+                weight=node.weight,
+                extra_data={
+                    "memory_id": item.memory_id,
+                    "session_id": item.session_id,
+                    "object_ids": item.object_ids,
+                    "link_kind": "memory_item_contains_node",
+                },
+            )
+        )
+
+    # node -> node weak co-occurrence links
+    max_pair_nodes = 12
+    for left, right in combinations(mention_nodes[:max_pair_nodes], 2):
+        links.append(
+            MemoryGraphLink(
+                source_id=left.id,
+                target_id=right.id,
+                source_key=left.key,
+                target_key=right.key,
+                weight=min(left.weight, right.weight),
+                extra_data={
+                    "memory_id": item.memory_id,
+                    "session_id": item.session_id,
+                    "object_ids": item.object_ids,
+                    "link_kind": "co_occurs_in_memory_item",
+                },
+            )
+        )
+
+    return nodes, links

alpha_avatar_plugins_memory-0.6.3/alphaavatar/plugins/memory/graph/graph_lookup.py

@@ -0,0 +1,232 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import json
+import pathlib
+from collections import defaultdict, deque
+from typing import Any
+
+
+def _json_loads(line: str) -> dict[str, Any] | None:
+    try:
+        data = json.loads(line)
+        return data if isinstance(data, dict) else None
+    except Exception:
+        return None
+
+
+def _read_jsonl(path: pathlib.Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+
+    rows: list[dict[str, Any]] = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+
+        item = _json_loads(line)
+        if item:
+            rows.append(item)
+
+    return rows
+
+
+def _norm_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    values = value if isinstance(value, list) else [value]
+    out: list[str] = []
+    seen: set[str] = set()
+
+    for x in values:
+        s = str(x).strip()
+        if not s or s in seen:
+            continue
+        seen.add(s)
+        out.append(s)
+
+    return out
+
+
+class GraphLookup:
+    def __init__(self, graph_path: str | pathlib.Path):
+        self.graph_path = pathlib.Path(graph_path)
+
+        self.nodes_path = self.graph_path / "nodes.jsonl"
+        self.links_path = self.graph_path / "links.jsonl"
+        self.node_items_path = self.graph_path / "node_items.jsonl"
+        self.aliases_path = self.graph_path / "aliases.jsonl"
+
+        self._aliases = self._load_aliases()
+        self._reverse_aliases = self._build_reverse_aliases()
+        self._neighbors = self._load_neighbors()
+        self._node_items = self._load_node_items()
+
+    def _load_aliases(self) -> dict[str, str]:
+        aliases: dict[str, str] = {}
+
+        for row in _read_jsonl(self.aliases_path):
+            alias_key = str(row.get("alias_key", "")).strip()
+            canonical_key = str(row.get("canonical_key", "")).strip()
+
+            if alias_key and canonical_key and alias_key != canonical_key:
+                aliases[alias_key] = canonical_key
+
+        return aliases
+
+    def _build_reverse_aliases(self) -> dict[str, list[str]]:
+        reverse: dict[str, list[str]] = defaultdict(list)
+
+        for alias_key, canonical_key in self._aliases.items():
+            reverse[canonical_key].append(alias_key)
+
+        return dict(reverse)
+
+    def _load_neighbors(self) -> dict[str, list[tuple[str, float]]]:
+        neighbors: dict[str, list[tuple[str, float]]] = defaultdict(list)
+
+        for row in _read_jsonl(self.links_path):
+            source_key = str(row.get("source_key", "")).strip()
+            target_key = str(row.get("target_key", "")).strip()
+            weight = float(row.get("weight", 1.0))
+
+            if not source_key or not target_key or source_key == target_key:
+                continue
+
+            neighbors[source_key].append((target_key, weight))
+            neighbors[target_key].append((source_key, weight))
+
+        return dict(neighbors)
+
+    def _load_node_items(self) -> dict[str, list[dict[str, Any]]]:
+        node_items: dict[str, list[dict[str, Any]]] = defaultdict(list)
+
+        for row in _read_jsonl(self.node_items_path):
+            node_key = str(row.get("node_key", "")).strip()
+            if not node_key:
+                continue
+            node_items[node_key].append(row)
+
+        return dict(node_items)
+
+    def resolve_keys(self, node_key: str) -> list[str]:
+        """
+        Return canonical key + known aliases.
+        This avoids rewriting VDB immediately after merge.
+        """
+        node_key = str(node_key).strip()
+        if not node_key:
+            return []
+
+        canonical = self._aliases.get(node_key, node_key)
+
+        keys = [canonical, node_key]
+        keys.extend(self._reverse_aliases.get(canonical, []))
+
+        out: list[str] = []
+        seen: set[str] = set()
+        for key in keys:
+            if key and key not in seen:
+                seen.add(key)
+                out.append(key)
+
+        return out
+
+    def expand_node_keys(
+        self,
+        *,
+        node_keys: list[str],
+        max_hops: int = 1,
+        max_neighbors_per_node: int = 16,
+        min_weight: float = 0.0,
+    ) -> list[str]:
+        """
+        Expand graph nodes through weak links.
+
+        max_hops=0: only resolved keys
+        max_hops=1: include direct neighbors
+        max_hops=2: include neighbors of neighbors
+        """
+        start_keys: list[str] = []
+        for key in node_keys:
+            start_keys.extend(self.resolve_keys(key))
+
+        visited: set[str] = set()
+        ordered: list[str] = []
+
+        queue = deque((key, 0) for key in start_keys)
+
+        while queue:
+            key, hop = queue.popleft()
+            if key in visited:
+                continue
+
+            visited.add(key)
+            ordered.append(key)
+
+            if hop >= max_hops:
+                continue
+
+            neighbors = sorted(
+                self._neighbors.get(key, []),
+                key=lambda x: x[1],
+                reverse=True,
+            )
+
+            for neighbor_key, weight in neighbors[:max_neighbors_per_node]:
+                if weight < min_weight:
+                    continue
+                if neighbor_key not in visited:
+                    queue.append((neighbor_key, hop + 1))
+
+        return ordered
+
+    def find_memory_ids_by_node_keys(
+        self,
+        *,
+        node_keys: list[str],
+        object_ids: list[str] | None = None,
+        session_id: str | None = None,
+        memory_type: str | None = None,
+        limit: int = 100,
+    ) -> list[str]:
+        wanted_objects = set(_norm_list(object_ids))
+
+        out: list[str] = []
+        seen: set[str] = set()
+
+        for node_key in node_keys:
+            for row in self._node_items.get(node_key, []):
+                if session_id and str(row.get("session_id", "")) != session_id:
+                    continue
+
+                if memory_type and str(row.get("memory_type", "")) != memory_type:
+                    continue
+
+                if wanted_objects:
+                    row_objects = set(_norm_list(row.get("object_ids")))
+                    if not (wanted_objects & row_objects):
+                        continue
+
+                memory_id = str(row.get("memory_id", "")).strip()
+                if not memory_id or memory_id in seen:
+                    continue
+
+                seen.add(memory_id)
+                out.append(memory_id)
+
+                if len(out) >= limit:
+                    return out
+
+        return out