implica 0.3.0__py3-none-any.whl

implica/graph/graph.py

@@ -0,0 +1,443 @@
+"""
+Graph structure for the implicational logic system.
+
+This module defines the Graph class which manages nodes and edges with
+optimized data structures for large graphs.
+"""
+
+from typing import Iterator, Optional
+
+from .connection import Connection
+from .elements import Node, Edge
+from ..core.types import BaseType
+
+
+class Graph:
+    """
+    A graph representing the implicational logic model.
+
+    The graph uses optimized data structures:
+    - Dict for O(1) node and edge lookups by uid
+    - Sets for O(1) membership checks
+    - Adjacency lists for efficient edge traversal
+
+    The graph maintains type consistency through validation.
+    """
+
+    def __init__(self):
+        """Initialize an empty graph."""
+        # Core storage: uid -> object
+        self._nodes: dict[str, Node] = {}
+        self._edges: dict[str, Edge] = {}
+
+        # Adjacency lists for efficient traversal
+        # node_uid -> set of outgoing edge uids
+        self._outgoing_edges: dict[str, set[str]] = {}
+        # node_uid -> set of incoming edge uids
+        self._incoming_edges: dict[str, set[str]] = {}
+
+    # ========== Low-level API (internal use) ==========
+
+    def _add_node(self, node: Node) -> None:
+        """
+        Add a node to the graph (low-level API).
+
+        Args:
+            node: The node to add
+
+        Raises:
+            ValueError: If a node with the same uid already exists
+        """
+        uid = node.uid
+
+        if uid in self._nodes:
+            raise ValueError(f"Node with uid '{uid}' already exists in the graph")
+
+        self._nodes[uid] = node
+        self._outgoing_edges[uid] = set()
+        self._incoming_edges[uid] = set()
+
+    def _remove_node(self, node_uid: str) -> None:
+        """
+        Remove a node from the graph (low-level API).
+
+        This also removes all edges connected to the node.
+
+        Args:
+            node_uid: The uid of the node to remove
+
+        Raises:
+            KeyError: If the node doesn't exist
+        """
+        if node_uid not in self._nodes:
+            raise KeyError(f"Node with uid '{node_uid}' not found in the graph")
+
+        # Remove all connected edges
+        outgoing = list(self._outgoing_edges[node_uid])
+        incoming = list(self._incoming_edges[node_uid])
+
+        for edge_uid in outgoing:
+            self._remove_edge(edge_uid)
+
+        for edge_uid in incoming:
+            self._remove_edge(edge_uid)
+
+        # Remove the node
+        del self._nodes[node_uid]
+        del self._outgoing_edges[node_uid]
+        del self._incoming_edges[node_uid]
+
+    def _add_edge(self, edge: Edge) -> None:
+        """
+        Add an edge to the graph (low-level API).
+
+        Args:
+            edge: The edge to add
+
+        Raises:
+            ValueError: If the edge already exists
+            KeyError: If source or destination nodes don't exist
+        """
+        uid = edge.uid
+        src_uid = edge.src_node.uid
+        dst_uid = edge.dst_node.uid
+
+        if uid in self._edges:
+            raise ValueError(f"Edge with uid '{uid}' already exists in the graph")
+
+        if src_uid not in self._nodes:
+            raise KeyError(f"Source node with uid '{src_uid}' not found in the graph")
+
+        if dst_uid not in self._nodes:
+            raise KeyError(
+                f"Destination node with uid '{dst_uid}' not found in the graph"
+            )
+
+        # Verify nodes match
+        if self._nodes[src_uid] != edge.src_node:
+            raise ValueError(f"Source node mismatch for uid '{src_uid}'")
+
+        if self._nodes[dst_uid] != edge.dst_node:
+            raise ValueError(f"Destination node mismatch for uid '{dst_uid}'")
+
+        self._edges[uid] = edge
+        self._outgoing_edges[src_uid].add(uid)
+        self._incoming_edges[dst_uid].add(uid)
+
+    def _remove_edge(self, edge_uid: str) -> None:
+        """
+        Remove an edge from the graph (low-level API).
+
+        Args:
+            edge_uid: The uid of the edge to remove
+
+        Raises:
+            KeyError: If the edge doesn't exist
+        """
+        if edge_uid not in self._edges:
+            raise KeyError(f"Edge with uid '{edge_uid}' not found in the graph")
+
+        edge = self._edges[edge_uid]
+        src_uid = edge.src_node.uid
+        dst_uid = edge.dst_node.uid
+
+        del self._edges[edge_uid]
+        self._outgoing_edges[src_uid].discard(edge_uid)
+        self._incoming_edges[dst_uid].discard(edge_uid)
+
+    # ========== Public query API ==========
+
+    def has_node(self, node_uid: str) -> bool:
+        """
+        Check if a node exists in the graph.
+
+        Args:
+            node_uid: The uid of the node
+
+        Returns:
+            bool: True if the node exists, False otherwise
+        """
+        return node_uid in self._nodes
+
+    def get_node(self, node_uid: str) -> Node:
+        """
+        Get a node by its uid.
+
+        Args:
+            node_uid: The uid of the node
+
+        Returns:
+            Node: The node
+
+        Raises:
+            KeyError: If the node doesn't exist
+        """
+        if node_uid not in self._nodes:
+            raise KeyError(f"Node with uid '{node_uid}' not found in the graph")
+        return self._nodes[node_uid]
+
+    def get_node_by_type(self, type: BaseType) -> Optional[Node]:
+        """
+        Get a node by its type.
+
+        Args:
+            type: The type to search for
+
+        Returns:
+            Optional[Node]: The node if found, None otherwise
+        """
+        uid = type.uid
+        return self._nodes.get(uid)
+
+    def has_edge(self, edge_uid: str) -> bool:
+        """
+        Check if an edge exists in the graph.
+
+        Args:
+            edge_uid: The uid of the edge
+
+        Returns:
+            bool: True if the edge exists, False otherwise
+        """
+        return edge_uid in self._edges
+
+    def get_edge(self, edge_uid: str) -> Edge:
+        """
+        Get an edge by its uid.
+
+        Args:
+            edge_uid: The uid of the edge
+
+        Returns:
+            Edge: The edge
+
+        Raises:
+            KeyError: If the edge doesn't exist
+        """
+        if edge_uid not in self._edges:
+            raise KeyError(f"Edge with uid '{edge_uid}' not found in the graph")
+        return self._edges[edge_uid]
+
+    def get_edges_for_node(self, node_uid: str) -> list[Edge]:
+        """
+        Get all edges connected to a node (both incoming and outgoing).
+
+        Args:
+            node_uid: The uid of the node
+
+        Returns:
+            list[Edge]: List of connected edges
+        """
+        if node_uid not in self._nodes:
+            return []
+
+        edge_uids = self._outgoing_edges[node_uid] | self._incoming_edges[node_uid]
+        return [self._edges[uid] for uid in edge_uids]
+
+    def get_outgoing_edges(self, node_uid: str) -> list[Edge]:
+        """
+        Get all outgoing edges from a node.
+
+        Args:
+            node_uid: The uid of the node
+
+        Returns:
+            list[Edge]: List of outgoing edges
+        """
+        if node_uid not in self._nodes:
+            return []
+
+        return [self._edges[uid] for uid in self._outgoing_edges[node_uid]]
+
+    def get_incoming_edges(self, node_uid: str) -> list[Edge]:
+        """
+        Get all incoming edges to a node.
+
+        Args:
+            node_uid: The uid of the node
+
+        Returns:
+            list[Edge]: List of incoming edges
+        """
+        if node_uid not in self._nodes:
+            return []
+
+        return [self._edges[uid] for uid in self._incoming_edges[node_uid]]
+
+    def nodes(self) -> Iterator[Node]:
+        """
+        Iterate over all nodes in the graph.
+
+        Returns:
+            Iterator[Node]: An iterator over all nodes
+        """
+        return iter(self._nodes.values())
+
+    def edges(self) -> Iterator[Edge]:
+        """
+        Iterate over all edges in the graph.
+
+        Returns:
+            Iterator[Edge]: An iterator over all edges
+        """
+        return iter(self._edges.values())
+
+    def node_count(self) -> int:
+        """
+        Get the number of nodes in the graph.
+
+        Returns:
+            int: The number of nodes
+        """
+        return len(self._nodes)
+
+    def edge_count(self) -> int:
+        """
+        Get the number of edges in the graph.
+
+        Returns:
+            int: The number of edges
+        """
+        return len(self._edges)
+
+    # ========== Validation ==========
+
+    def validate(self) -> bool:
+        """
+        Validate the graph for consistency.
+
+        Checks:
+        - All edges reference existing nodes
+        - Edge node references match stored nodes
+        - Adjacency lists are consistent
+        - Adjacency lists only reference existing nodes
+        - Each edge in adjacency lists matches the correct source/destination
+        - No orphaned entries in adjacency structures
+
+        Returns:
+            bool: True if the graph is valid
+
+        Raises:
+            ValueError: If validation fails
+        """
+        # First: Check that all nodes have corresponding adjacency list entries
+        # This must be done before we try to access adjacency lists
+        for node_uid in self._nodes:
+            if node_uid not in self._outgoing_edges:
+                raise ValueError(
+                    f"Node '{node_uid}' missing from outgoing edges structure"
+                )
+
+            if node_uid not in self._incoming_edges:
+                raise ValueError(
+                    f"Node '{node_uid}' missing from incoming edges structure"
+                )
+
+        # Second: Check that all adjacency list keys correspond to existing nodes
+        for node_uid in self._outgoing_edges:
+            if node_uid not in self._nodes:
+                raise ValueError(
+                    f"Outgoing edges structure contains orphaned node '{node_uid}'"
+                )
+
+        for node_uid in self._incoming_edges:
+            if node_uid not in self._nodes:
+                raise ValueError(
+                    f"Incoming edges structure contains orphaned node '{node_uid}'"
+                )
+
+        # Third: Check all edges reference valid nodes
+        for edge_uid, edge in self._edges.items():
+            src_uid = edge.src_node.uid
+            dst_uid = edge.dst_node.uid
+
+            if src_uid not in self._nodes:
+                raise ValueError(
+                    f"Edge '{edge_uid}' references non-existent source node '{src_uid}'"
+                )
+
+            if dst_uid not in self._nodes:
+                raise ValueError(
+                    f"Edge '{edge_uid}' references non-existent destination node '{dst_uid}'"
+                )
+
+            # Check node references match
+            if self._nodes[src_uid] != edge.src_node:
+                raise ValueError(
+                    f"Edge '{edge_uid}' source node doesn't match stored node '{src_uid}'"
+                )
+
+            if self._nodes[dst_uid] != edge.dst_node:
+                raise ValueError(
+                    f"Edge '{edge_uid}' destination node doesn't match stored node '{dst_uid}'"
+                )
+
+            # Check adjacency lists
+            if edge_uid not in self._outgoing_edges[src_uid]:
+                raise ValueError(
+                    f"Edge '{edge_uid}' not in outgoing edges of node '{src_uid}'"
+                )
+
+            if edge_uid not in self._incoming_edges[dst_uid]:
+                raise ValueError(
+                    f"Edge '{edge_uid}' not in incoming edges of node '{dst_uid}'"
+                )
+
+        # Fourth: Check adjacency lists reference valid edges and correct nodes
+        for node_uid in self._nodes:
+            # Validate outgoing edges
+            for edge_uid in self._outgoing_edges[node_uid]:
+                if edge_uid not in self._edges:
+                    raise ValueError(
+                        f"Outgoing edge list of node '{node_uid}' references "
+                        f"non-existent edge '{edge_uid}'"
+                    )
+
+                # Verify the edge actually originates from this node
+                edge = self._edges[edge_uid]
+                if edge.src_node.uid != node_uid:
+                    raise ValueError(
+                        f"Edge '{edge_uid}' in outgoing list of node '{node_uid}' "
+                        f"has incorrect source node '{edge.src_node.uid}'"
+                    )
+
+            # Validate incoming edges
+            for edge_uid in self._incoming_edges[node_uid]:
+                if edge_uid not in self._edges:
+                    raise ValueError(
+                        f"Incoming edge list of node '{node_uid}' references "
+                        f"non-existent edge '{edge_uid}'"
+                    )
+
+                # Verify the edge actually terminates at this node
+                edge = self._edges[edge_uid]
+                if edge.dst_node.uid != node_uid:
+                    raise ValueError(
+                        f"Edge '{edge_uid}' in incoming list of node '{node_uid}' "
+                        f"has incorrect destination node '{edge.dst_node.uid}'"
+                    )
+
+        return True
+
+    # ========== Connection API ==========
+
+    def connect(self) -> Connection:
+        """
+        Create a connection for transactional graph modifications.
+
+        Returns:
+            Connection: A new connection object
+        """
+
+        return Connection(self)
+
+    def __str__(self) -> str:
+        """Return a string representation of the graph."""
+        return f"Graph(nodes={self.node_count()}, edges={self.edge_count()})"
+
+    def __repr__(self) -> str:
+        """Return a detailed representation."""
+        return (
+            f"Graph(nodes={self.node_count()}, edges={self.edge_count()}, "
+            f"node_list={list(self._nodes.keys())})"
+        )

implica/mutations/__init__.py

@@ -0,0 +1,29 @@
+from .base import Mutation
+from .add_node import AddNode
+from .remove_node import RemoveNode
+from .try_add_node import TryAddNode
+from .try_remove_node import TryRemoveNode
+from .add_edge import AddEdge
+from .remove_edge import RemoveEdge
+from .try_add_edge import TryAddEdge
+from .try_remove_edge import TryRemoveEdge
+from .add_many_nodes import AddManyNodes
+from .add_many_edges import AddManyEdges
+from .remove_many_nodes import RemoveManyNodes
+from .remove_many_edges import RemoveManyEdges
+
+__all__ = [
+    "Mutation",
+    "AddNode",
+    "RemoveNode",
+    "TryAddNode",
+    "TryRemoveNode",
+    "AddEdge",
+    "RemoveEdge",
+    "TryAddEdge",
+    "TryRemoveEdge",
+    "AddManyNodes",
+    "AddManyEdges",
+    "RemoveManyNodes",
+    "RemoveManyEdges",
+]

implica/mutations/add_edge.py

@@ -0,0 +1,45 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class AddEdge(Mutation):
+    """Mutation to add an edge to the graph."""
+
+    def __init__(self, edge: Edge):
+        """
+        Initialize the AddEdge mutation.
+
+        Args:
+            edge: The edge to add
+        """
+        self.edge = edge
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Add the edge to the graph.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            ValueError: If the edge already exists or nodes don't exist
+        """
+        graph._add_edge(self.edge)
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove the edge from the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        graph._remove_edge(self.edge.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"AddEdge({self.edge})"

implica/mutations/add_many_edges.py

@@ -0,0 +1,60 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Edge
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class AddManyEdges(Mutation):
+    """Mutation to add multiple edges to the graph."""
+
+    def __init__(self, edges: list[Edge]):
+        """
+        Initialize the AddManyEdges mutation.
+
+        Args:
+            edges: List of edges to add
+        """
+        self.edges = edges
+        self._added_edges: list[Edge] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Add all edges to the graph.
+
+        If any edge fails to be added, all previously added edges are rolled back.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            ValueError: If any edge already exists or nodes don't exist
+        """
+        self._added_edges = []
+
+        try:
+            for edge in self.edges:
+                graph._add_edge(edge)
+                self._added_edges.append(edge)
+        except Exception:
+            # Rollback: remove all edges that were added
+            for edge in self._added_edges:
+                graph._remove_edge(edge.uid)
+            self._added_edges = []
+            raise
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove all added edges from the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        for edge in reversed(self._added_edges):
+            graph._remove_edge(edge.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"AddManyEdges(count={len(self.edges)})"

implica/mutations/add_many_nodes.py

@@ -0,0 +1,60 @@
+from typing import TYPE_CHECKING
+
+from ..graph.elements import Node
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph.graph import Graph
+
+
+class AddManyNodes(Mutation):
+    """Mutation to add multiple nodes to the graph."""
+
+    def __init__(self, nodes: list[Node]):
+        """
+        Initialize the AddManyNodes mutation.
+
+        Args:
+            nodes: List of nodes to add
+        """
+        self.nodes = nodes
+        self._added_nodes: list[Node] = []
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Add all nodes to the graph.
+
+        If any node fails to be added, all previously added nodes are rolled back.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            ValueError: If any node already exists
+        """
+        self._added_nodes = []
+
+        try:
+            for node in self.nodes:
+                graph._add_node(node)
+                self._added_nodes.append(node)
+        except Exception:
+            # Rollback: remove all nodes that were added
+            for node in self._added_nodes:
+                graph._remove_node(node.uid)
+            self._added_nodes = []
+            raise
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove all added nodes from the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        for node in reversed(self._added_nodes):
+            graph._remove_node(node.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"AddManyNodes(count={len(self.nodes)})"

implica/mutations/add_node.py

@@ -0,0 +1,45 @@
+from typing import TYPE_CHECKING
+
+from ..graph import Edge, Node
+from .base import Mutation
+
+if TYPE_CHECKING:
+    from ..graph import Graph
+
+
+class AddNode(Mutation):
+    """Mutation to add a node to the graph."""
+
+    def __init__(self, node: Node):
+        """
+        Initialize the AddNode mutation.
+
+        Args:
+            node: The node to add
+        """
+        self.node = node
+
+    def forward(self, graph: "Graph") -> None:
+        """
+        Add the node to the graph.
+
+        Args:
+            graph: The graph to modify
+
+        Raises:
+            ValueError: If the node already exists
+        """
+        graph._add_node(self.node)
+
+    def backward(self, graph: "Graph") -> None:
+        """
+        Remove the node from the graph.
+
+        Args:
+            graph: The graph to modify
+        """
+        graph._remove_node(self.node.uid)
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        return f"AddNode({self.node})"