synapse-framework 0.2.4__py3-none-any.whl

synapse/graph/base.py

@@ -0,0 +1,130 @@
+"""Abstract base interface for pluggable knowledge graph stores in Synapse."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseGraphStore(ABC):
+    """Abstract interface that all Synapse knowledge graph backends must implement.
+
+    Ensures interchangeability between NetworkX, in-memory graphs, Neo4j,
+    or other graph databases.
+    """
+
+    @abstractmethod
+    def add_node_entity(
+        self,
+        name: str,
+        entity_type: str = "Default",
+        color: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        """Adds or updates an entity node in the graph."""
+
+    @abstractmethod
+    def add_relation(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        source_type: str = "Default",
+        target_type: str = "Default",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Adds a directed relation edge between source and target entities."""
+
+    def add_node(
+        self,
+        name: str,
+        entity_type: str = "Default",
+        color: str | None = None,
+        attributes: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Convenience alias for add_node_entity."""
+        attrs = dict(attributes or {})
+        attrs.update(kwargs)
+        self.add_node_entity(name=name, entity_type=entity_type, color=color, attributes=attrs)
+
+    def add_edge(
+        self,
+        source: str,
+        target_or_rel: str,
+        target: str | None = None,
+        relation: str = "CONNECTED_TO",
+        source_type: str = "Default",
+        target_type: str = "Default",
+        metadata: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Convenience alias for add_relation.
+
+        Supports both:
+          add_edge(u, v, relation="CONNECTED_TO")
+          add_edge(u, "RELATION", v)
+        """
+        meta = dict(metadata or {})
+        meta.update(kwargs)
+        if target is not None:
+            # 3 positional args: source, target_or_rel, target
+            # e.g., add_edge("alice", "WORKS_AT", "synapse") -> relation="WORKS_AT", target="synapse"
+            # or add_edge("alice", "synapse", "WORKS_AT") -> relation="WORKS_AT", target="synapse"
+            if target_or_rel.isupper() and not target.isupper():
+                actual_rel = target_or_rel
+                actual_target = target
+            else:
+                actual_target = target_or_rel
+                actual_rel = target
+            self.add_relation(
+                source=source,
+                relation=actual_rel,
+                target=actual_target,
+                source_type=source_type,
+                target_type=target_type,
+                metadata=meta,
+            )
+        else:
+            # 2 positional args: source, target
+            self.add_relation(
+                source=source,
+                relation=relation,
+                target=target_or_rel,
+                source_type=source_type,
+                target_type=target_type,
+                metadata=meta,
+            )
+
+
+    @abstractmethod
+    def find_relation_for(self, entity: str) -> list[str]:
+        """Finds all incoming and outgoing relational facts for a given entity."""
+
+    @abstractmethod
+    def get_3d_payload(self) -> dict[str, Any]:
+        """Returns node and link data formatted for 3D force-directed visualization."""
+
+    @abstractmethod
+    def get_stats(self) -> dict[str, Any]:
+        """Returns summary node and edge counts."""
+
+    def count_nodes(self) -> int:
+        """Returns the total number of nodes in the graph."""
+        return int(self.get_stats().get("total_nodes", 0))
+
+    def count_edges(self) -> int:
+        """Returns the total number of edges in the graph."""
+        return int(self.get_stats().get("total_edges", 0))
+
+    def clear(self) -> None:
+        """Clears all nodes and edges from the graph."""
+
+    def load(self) -> None:
+        """Loads state from persistent storage if applicable."""
+
+    def save(self) -> None:
+        """Persists state to storage if applicable."""
+
+
+__all__ = ["BaseGraphStore"]

synapse/graph/memory.py

@@ -0,0 +1,20 @@
+"""Pure in-memory knowledge graph implementation for Synapse."""
+
+from __future__ import annotations
+
+from synapse.graph.networkx_store import NetworkXGraph
+
+
+class InMemoryGraph(NetworkXGraph):
+    """Ephemeral knowledge graph residing purely in RAM with zero disk footprints."""
+
+    def __init__(self, palette: dict[str, str] | None = None) -> None:
+        super().__init__(filepath=None, palette=palette)
+
+
+def in_memory_graph(palette: dict[str, str] | None = None) -> InMemoryGraph:
+    """Factory helper creating an in-memory knowledge graph."""
+    return InMemoryGraph(palette=palette)
+
+
+__all__ = ["InMemoryGraph", "in_memory_graph"]

synapse/graph/neo4j_store.py

@@ -0,0 +1,176 @@
+"""Neo4j graph database adapter for Synapse."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from synapse.config import DESIGN_TOKENS
+from synapse.graph.base import BaseGraphStore
+
+
+class Neo4jGraph(BaseGraphStore):
+    """Neo4j graph database adapter connecting to enterprise or AuraDB clusters."""
+
+    def __init__(
+        self,
+        uri: str = "bolt://localhost:7687",
+        auth: tuple[str, str] | Any | None = None,
+        database: str = "neo4j",
+        palette: dict[str, str] | None = None,
+    ) -> None:
+        self.uri = uri
+        self.database = database
+        self.palette = palette or DESIGN_TOKENS["palettes"]["zinc"]
+        self.driver = None
+
+        try:
+            from neo4j import GraphDatabase
+
+            self.driver = GraphDatabase.driver(uri, auth=auth)
+        except ImportError:
+            # Fallback in-memory representation if neo4j package is omitted
+            from synapse.graph.memory import InMemoryGraph
+
+            self._fallback = InMemoryGraph(palette=self.palette)
+
+    def add_node_entity(
+        self,
+        name: str,
+        entity_type: str = "Default",
+        color: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        if not self.driver:
+            return self._fallback.add_node_entity(name, entity_type, color, attributes)
+
+        assigned_color = color or self.palette.get(
+            entity_type, self.palette.get("Default", "#71717a")
+        )
+        props = {"name": name, "type": entity_type, "color": assigned_color}
+        if attributes:
+            props.update(attributes)
+
+        query = """
+        MERGE (n:Entity {name: $name})
+        SET n += $props
+        """
+        with self.driver.session(database=self.database) as session:
+            session.run(query, name=name, props=props)
+
+    def add_relation(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        source_type: str = "Default",
+        target_type: str = "Default",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        if not self.driver:
+            return self._fallback.add_relation(
+                source, relation, target, source_type, target_type, metadata
+            )
+
+        self.add_node_entity(source, entity_type=source_type)
+        self.add_node_entity(target, entity_type=target_type)
+
+        clean_rel = relation.strip().upper().replace(" ", "_")
+        query = f"""
+        MATCH (s:Entity {{name: $source}})
+        MATCH (t:Entity {{name: $target}})
+        MERGE (s)-[r:{clean_rel}]->(t)
+        SET r += $props
+        """
+        with self.driver.session(database=self.database) as session:
+            session.run(query, source=source, target=target, props=metadata or {})
+
+    def find_relation_for(self, entity: str) -> list[str]:
+        if not self.driver:
+            return self._fallback.find_relation_for(entity)
+
+        facts: list[str] = []
+        query = """
+        MATCH (s:Entity {name: $entity})-[r]->(t:Entity)
+        RETURN s.name as source, type(r) as relation, t.name as target
+        UNION
+        MATCH (s:Entity)-[r]->(t:Entity {name: $entity})
+        RETURN s.name as source, type(r) as relation, t.name as target
+        """
+        with self.driver.session(database=self.database) as session:
+            result = session.run(query, entity=entity)
+            for record in result:
+                facts.append(
+                    f"{record['source']} -> {record['relation']} -> {record['target']}"
+                )
+        return facts
+
+    def get_3d_payload(self) -> dict[str, Any]:
+        if not self.driver:
+            return self._fallback.get_3d_payload()
+
+        nodes: list[dict[str, Any]] = []
+        links: list[dict[str, Any]] = []
+
+        query = """
+        MATCH (s:Entity)-[r]->(t:Entity)
+        RETURN s, r, t LIMIT 500
+        """
+        with self.driver.session(database=self.database) as session:
+            res = session.run(query)
+            seen_nodes = set()
+            for record in res:
+                s_node = record["s"]
+                t_node = record["t"]
+                r_rel = record["r"]
+
+                for n in (s_node, t_node):
+                    nid = n["name"]
+                    if nid not in seen_nodes:
+                        seen_nodes.add(nid)
+                        ntype = n.get("type", "Default")
+                        color = n.get("color", self.palette.get(ntype, "#71717a"))
+                        nodes.append({
+                            "id": nid,
+                            "name": nid,
+                            "label": nid,
+                            "type": ntype,
+                            "color": color,
+                            "val": 5.0,
+                        })
+
+                links.append({
+                    "source": s_node["name"],
+                    "target": t_node["name"],
+                    "relation": r_rel.type,
+                    "label": r_rel.type,
+                })
+
+        return {"nodes": nodes, "links": links}
+
+    def get_stats(self) -> dict[str, Any]:
+        if not self.driver:
+            return self._fallback.get_stats()
+
+        query = """
+        CALL { MATCH (n:Entity) RETURN count(n) as nodes }
+        CALL { MATCH ()-[r]->() RETURN count(r) as edges }
+        RETURN nodes, edges
+        """
+        with self.driver.session(database=self.database) as session:
+            res = session.run(query).single()
+            if res:
+                return {"total_nodes": res["nodes"], "total_edges": res["edges"]}
+        return {"total_nodes": 0, "total_edges": 0}
+
+
+def neo4j(
+    uri: str = "bolt://localhost:7687",
+    auth: tuple[str, str] | Any | None = None,
+    database: str = "neo4j",
+    palette: dict[str, str] | None = None,
+) -> Neo4jGraph:
+    """Factory helper to configure a Neo4j graph database adapter."""
+    return Neo4jGraph(uri=uri, auth=auth, database=database, palette=palette)
+
+
+__all__ = ["Neo4jGraph", "neo4j"]

synapse/graph/networkx_store.py

@@ -0,0 +1,221 @@
+"""NetworkX knowledge graph implementation for Synapse."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import networkx as nx
+
+from synapse.config import DESIGN_TOKENS
+from synapse.graph.base import BaseGraphStore
+
+PALETTE: dict[str, str] = DESIGN_TOKENS["palettes"]["zinc"]
+
+
+class NetworkXGraph(BaseGraphStore):
+    """NetworkX directed knowledge graph supporting file persistence or ephemeral RAM."""
+
+    def __init__(
+        self,
+        filepath: str | Path | None = None,
+        palette: dict[str, str] | None = None,
+    ) -> None:
+        """Initializes NetworkX knowledge graph.
+
+        Args:
+            filepath: Optional persistent JSON file path. If None, operates purely in RAM.
+            palette: Optional dictionary mapping entity types to hex color strings.
+        """
+        self.filepath = Path(filepath).resolve() if filepath else None
+        self.palette = palette or PALETTE
+        self.graph: nx.DiGraph = nx.DiGraph()
+        if self.filepath:
+            self.load()
+
+    def add_node_entity(
+        self,
+        name: str,
+        entity_type: str = "Default",
+        color: str | None = None,
+        attributes: dict[str, Any] | None = None,
+    ) -> None:
+        """Adds or updates an entity node in the graph."""
+        clean_name = name.strip()
+        if not clean_name:
+            return
+
+        assigned_color = color or self.palette.get(
+            entity_type, self.palette.get("Default", "#71717a")
+        )
+        node_data: dict[str, Any] = {
+            "name": clean_name,
+            "type": entity_type,
+            "color": assigned_color,
+        }
+        if attributes:
+            node_data.update(attributes)
+
+        if clean_name in self.graph:
+            self.graph.nodes[clean_name].update(node_data)
+        else:
+            self.graph.add_node(clean_name, **node_data)
+
+        self.save()
+
+    def add_relation(
+        self,
+        source: str,
+        relation: str,
+        target: str,
+        source_type: str = "Default",
+        target_type: str = "Default",
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Adds a directed relation edge between source and target entities."""
+        s = source.strip()
+        t = target.strip()
+        r = relation.strip().upper().replace(" ", "_")
+
+        if not s or not t:
+            return
+
+        self.add_node_entity(s, entity_type=source_type)
+        self.add_node_entity(t, entity_type=target_type)
+
+        edge_data: dict[str, Any] = {"relation": r}
+        if metadata:
+            edge_data.update(metadata)
+
+        self.graph.add_edge(s, t, **edge_data)
+        self.save()
+
+    def find_relation_for(self, entity: str) -> list[str]:
+        """Finds all relational facts directly connected to an entity."""
+        facts: list[str] = []
+        clean = entity.strip()
+        if clean not in self.graph:
+            # Case-insensitive search
+            found = next(
+                (n for n in self.graph.nodes if str(n).lower() == clean.lower()),
+                None,
+            )
+            if not found:
+                return facts
+            clean = str(found)
+
+        # Outgoing edges
+        for _, target, data in self.graph.out_edges(clean, data=True):
+            rel = data.get("relation", "RELATION")
+            facts.append(f"{clean} -> {rel} -> {target}")
+
+        # Incoming edges
+        for source, _, data in self.graph.in_edges(clean, data=True):
+            rel = data.get("relation", "RELATION")
+            facts.append(f"{source} -> {rel} -> {clean}")
+
+        return facts
+
+    def get_3d_payload(self) -> dict[str, Any]:
+        """Serializes nodes and edges into 3D force-directed layout format."""
+        nodes: list[dict[str, Any]] = []
+        for node_id, data in self.graph.nodes(data=True):
+            node_type = data.get("type", "Default")
+            color = data.get("color", self.palette.get(node_type, "#71717a"))
+            degree = self.graph.degree(node_id)
+            val = max(3.5, min(14.0, degree * 2.2))
+            nodes.append({
+                "id": str(node_id),
+                "name": str(node_id),
+                "label": str(node_id),
+                "type": node_type,
+                "color": color,
+                "degree": degree,
+                "val": val,
+                "metadata": data,
+            })
+
+        links: list[dict[str, Any]] = []
+        for u, v, data in self.graph.edges(data=True):
+            rel = data.get("relation", "RELATION")
+            links.append({
+                "source": str(u),
+                "target": str(v),
+                "relation": rel,
+                "label": rel,
+                "metadata": data,
+            })
+
+        return {"nodes": nodes, "links": links}
+
+    def get_stats(self) -> dict[str, Any]:
+        """Returns summary node and edge counts."""
+        return {
+            "total_nodes": self.graph.number_of_nodes(),
+            "total_edges": self.graph.number_of_edges(),
+        }
+
+    def count_nodes(self) -> int:
+        """Returns the total number of nodes in the graph."""
+        return self.graph.number_of_nodes()
+
+    def count_edges(self) -> int:
+        """Returns the total number of edges in the graph."""
+        return self.graph.number_of_edges()
+
+    def clear(self) -> None:
+        """Clears all nodes and edges from the graph."""
+        self.graph.clear()
+        self.save()
+
+    def load(self) -> None:
+        """Loads graph state from persistent JSON file if configured."""
+        if not self.filepath or not self.filepath.exists():
+            return
+        try:
+            content = self.filepath.read_text(encoding="utf-8")
+            if not content.strip():
+                return
+            data = json.loads(content)
+            self.graph = nx.node_link_graph(data, edges="links")
+        except Exception:
+            pass  # nosec B110
+
+    def save(self) -> None:
+        """Persists graph state to JSON file if configured."""
+        if not self.filepath:
+            return
+        try:
+            self.filepath.parent.mkdir(parents=True, exist_ok=True)
+            payload = nx.node_link_data(self.graph, edges="links")
+            self.filepath.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+        except Exception:
+            pass  # nosec B110
+
+
+def networkx(
+    filepath: str | Path | None = None,
+    palette: dict[str, str] | None = None,
+) -> NetworkXGraph:
+    """Factory helper creating a NetworkX knowledge graph.
+
+    Args:
+        filepath: Optional path to JSON persistence file. If None, runs purely in RAM.
+        palette: Optional dictionary mapping entity types to colors.
+
+    Example:
+        ```python
+        from synapse.graph import networkx
+
+        # File-backed persistence:
+        graph = networkx("data/graph.json")
+
+        # In-memory ephemeral (zero disk files):
+        graph = networkx()
+        ```
+    """
+    return NetworkXGraph(filepath=filepath, palette=palette)
+
+
+__all__ = ["PALETTE", "NetworkXGraph", "networkx"]

synapse/inspector/__init__.py

@@ -0,0 +1,5 @@
+"""Interactive Inspector UI for Synapse."""
+
+from synapse.inspector.template import INSPECTOR_HTML, render_inspector_html
+
+__all__ = ["INSPECTOR_HTML", "render_inspector_html"]