implica 0.3.0__py3-none-any.whl

implica/graph/connection.py

@@ -0,0 +1,389 @@
+"""
+Connection system for transactional graph modifications.
+
+This module defines the Connection class which accumulates mutations and
+executes them transactionally with automatic rollback on failure.
+"""
+
+from typing import TYPE_CHECKING
+
+from .elements import Node
+from ..core.combinator import Combinator
+from ..mutations import (
+    Mutation,
+    AddNode,
+    RemoveNode,
+    AddEdge,
+    RemoveEdge,
+    AddManyNodes,
+    AddManyEdges,
+    TryAddNode,
+    TryAddEdge,
+    RemoveManyNodes,
+    RemoveManyEdges,
+    TryRemoveNode,
+    TryRemoveEdge,
+)
+
+if TYPE_CHECKING:
+    from .graph import Graph
+
+
+class Connection:
+    """
+    A connection for making transactional modifications to a graph.
+
+    Usage:
+        with graph.connect() as conn:
+            conn.add_node(node1)
+            conn.add_edge(edge1)
+        # Changes are committed automatically if no exception occurs
+        # Otherwise, all changes are rolled back
+
+    Can also be used without context manager:
+        conn = graph.connect()
+        conn.add_node(node1)
+        conn.commit()  # or conn.rollback()
+    """
+
+    def __init__(self, graph: "Graph"):
+        """
+        Initialize a connection.
+
+        Args:
+            graph: The graph to operate on
+        """
+        self.graph = graph
+        self.mutations: list[Mutation] = []
+        self._committed = False
+        self._rolled_back = False
+
+    def add_node(self, node: Node) -> "Connection":
+        """
+        Add a mutation to create a node.
+
+        Args:
+            node: The node to add
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(AddNode(node))
+        return self
+
+    def remove_node(self, node_uid: str) -> "Connection":
+        """
+        Add a mutation to remove a node.
+
+        Args:
+            node_uid: The uid of the node to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(RemoveNode(node_uid))
+        return self
+
+    def add_edge(self, combinator: Combinator) -> "Connection":
+        """
+        Add a mutation to create an edge from a combinator.
+
+        The edge will be created with nodes corresponding to the combinator's
+        input and output types. The nodes must exist when the mutation is applied.
+
+        Args:
+            combinator: The combinator for this edge
+
+        Returns:
+            Connection: Self for method chaining
+
+        Raises:
+            ValueError: If the combinator doesn't have an Application type
+        """
+        self._check_state()
+
+        # Import here to avoid circular import
+        from .elements import edge
+        from ..core.types import Application
+
+        # Validate combinator type
+        if not isinstance(combinator.type, Application):
+            raise ValueError(
+                f"Combinator must have an Application type to create an edge, "
+                f"got {type(combinator.type).__name__}"
+            )
+
+        # Create the edge - validation that nodes exist will happen at forward() time
+        e = edge(combinator)
+        self.mutations.append(AddEdge(e))
+        return self
+
+    def remove_edge(self, edge_uid: str) -> "Connection":
+        """
+        Add a mutation to remove an edge.
+
+        Args:
+            edge_uid: The uid of the edge to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(RemoveEdge(edge_uid))
+        return self
+
+    def add_many_nodes(self, nodes: list[Node]) -> "Connection":
+        """
+        Add a mutation to create multiple nodes.
+
+        Args:
+            nodes: List of nodes to add
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(AddManyNodes(nodes))
+        return self
+
+    def add_many_edges(self, combinators: list[Combinator]) -> "Connection":
+        """
+        Add a mutation to create multiple edges from combinators.
+
+        Args:
+            combinators: List of combinators for the edges
+
+        Returns:
+            Connection: Self for method chaining
+
+        Raises:
+            ValueError: If any combinator doesn't have an Application type
+        """
+        self._check_state()
+
+        # Import here to avoid circular import
+        from .elements import edge
+        from ..core.types import Application
+
+        # Validate all combinators and create edges
+        edges = []
+        for combinator in combinators:
+            if not isinstance(combinator.type, Application):
+                raise ValueError(
+                    f"Combinator must have an Application type to create an edge, "
+                    f"got {type(combinator.type).__name__}"
+                )
+            edges.append(edge(combinator))
+
+        self.mutations.append(AddManyEdges(edges))
+        return self
+
+    def try_add_node(self, node: Node) -> "Connection":
+        """
+        Add a mutation to create a node, or do nothing if it already exists.
+
+        Args:
+            node: The node to add
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(TryAddNode(node))
+        return self
+
+    def try_add_edge(self, combinator: Combinator) -> "Connection":
+        """
+        Add a mutation to create an edge from a combinator, or do nothing if it already exists.
+
+        Args:
+            combinator: The combinator for this edge
+
+        Returns:
+            Connection: Self for method chaining
+
+        Raises:
+            ValueError: If the combinator doesn't have an Application type
+        """
+        self._check_state()
+
+        # Import here to avoid circular import
+        from .elements import edge
+        from ..core.types import Application
+
+        # Validate combinator type
+        if not isinstance(combinator.type, Application):
+            raise ValueError(
+                f"Combinator must have an Application type to create an edge, "
+                f"got {type(combinator.type).__name__}"
+            )
+
+        # Create the edge
+        e = edge(combinator)
+        self.mutations.append(TryAddEdge(e))
+        return self
+
+    def remove_many_nodes(self, node_uids: list[str]) -> "Connection":
+        """
+        Add a mutation to remove multiple nodes.
+
+        Args:
+            node_uids: List of node uids to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(RemoveManyNodes(node_uids))
+        return self
+
+    def remove_many_edges(self, edge_uids: list[str]) -> "Connection":
+        """
+        Add a mutation to remove multiple edges.
+
+        Args:
+            edge_uids: List of edge uids to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(RemoveManyEdges(edge_uids))
+        return self
+
+    def try_remove_node(self, node_uid: str) -> "Connection":
+        """
+        Add a mutation to remove a node, or do nothing if it doesn't exist.
+
+        Args:
+            node_uid: The uid of the node to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(TryRemoveNode(node_uid))
+        return self
+
+    def try_remove_edge(self, edge_uid: str) -> "Connection":
+        """
+        Add a mutation to remove an edge, or do nothing if it doesn't exist.
+
+        Args:
+            edge_uid: The uid of the edge to remove
+
+        Returns:
+            Connection: Self for method chaining
+        """
+        self._check_state()
+        self.mutations.append(TryRemoveEdge(edge_uid))
+        return self
+
+    def commit(self) -> None:
+        """
+        Commit all mutations to the graph.
+
+        If any mutation fails or the graph doesn't validate after all mutations,
+        all changes are rolled back.
+
+        Raises:
+            RuntimeError: If already committed or rolled back
+            Exception: Any exception from mutations or validation
+        """
+        self._check_state()
+
+        applied_count = 0
+
+        try:
+            # Apply all mutations
+            for mutation in self.mutations:
+                mutation.forward(self.graph)
+                applied_count += 1
+
+            # Validate the graph
+            self.graph.validate()
+
+            # Mark as committed
+            self._committed = True
+
+        except Exception as e:
+            # Rollback all applied mutations in reverse order
+            for i in range(applied_count - 1, -1, -1):
+                try:
+                    self.mutations[i].backward(self.graph)
+                except Exception as rollback_error:
+                    # Log rollback error but continue rolling back
+                    print(f"Warning: Error during rollback: {rollback_error}")
+
+            self._rolled_back = True
+
+            # Re-raise the original exception
+            raise RuntimeError(
+                f"Transaction failed and was rolled back. "
+                f"Applied {applied_count}/{len(self.mutations)} mutations before failure."
+            ) from e
+
+    def rollback(self) -> None:
+        """
+        Explicitly rollback all mutations without applying them.
+
+        Raises:
+            RuntimeError: If already committed or rolled back
+        """
+        self._check_state()
+        self._rolled_back = True
+
+    def _check_state(self) -> None:
+        """
+        Check that the connection is in a valid state for operations.
+
+        Raises:
+            RuntimeError: If already committed or rolled back
+        """
+        if self._committed:
+            raise RuntimeError("Connection has already been committed")
+        if self._rolled_back:
+            raise RuntimeError("Connection has already been rolled back")
+
+    def __enter__(self) -> "Connection":
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """
+        Exit the context manager.
+
+        Commits if no exception occurred, otherwise rolls back.
+
+        Returns:
+            bool: False to propagate any exception
+        """
+        if exc_type is None:
+            # No exception, commit
+            try:
+                self.commit()
+            except Exception:
+                # Let the commit exception propagate
+                return False
+        else:
+            # Exception occurred, rollback
+            if not self._rolled_back:
+                self.rollback()
+
+        # Don't suppress the exception
+        return False
+
+    def __str__(self) -> str:
+        """Return a string representation."""
+        status = (
+            "committed"
+            if self._committed
+            else ("rolled_back" if self._rolled_back else "open")
+        )
+        return f"Connection(mutations={len(self.mutations)}, status={status})"
+
+    def __repr__(self) -> str:
+        """Return a detailed representation."""
+        return f"Connection(graph={self.graph}, mutations={self.mutations}, committed={self._committed}, rolled_back={self._rolled_back})"

implica/graph/elements.py

@@ -0,0 +1,194 @@
+"""
+Graph elements for the implicational logic graph.
+
+This module defines the Node and Edge types that compose the graph structure.
+"""
+
+import hashlib
+from functools import cached_property
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from ..core.combinator import Combinator
+from ..core.types import BaseType, Application
+
+
+class Node(BaseModel):
+    """
+    A node in the implicational logic graph.
+
+    Each node represents a type (either a Variable or an Application).
+    Nodes are identified by their type's uid for efficient lookup.
+    """
+
+    type: BaseType = Field(..., description="The type represented by this node")
+
+    model_config = ConfigDict(frozen=True)  # Make immutable
+
+    @cached_property
+    def uid(self) -> str:
+        """
+        Return the unique identifier for this node.
+
+        The uid is the same as the type's uid, making nodes uniquely
+        identifiable by their type.
+
+        Returns:
+            str: The node's unique identifier
+        """
+        return self.type.uid
+
+    def __str__(self) -> str:
+        """Return a string representation of the node."""
+        return f"Node({self.type})"
+
+    def __repr__(self) -> str:
+        """Return a detailed representation."""
+        return f"Node(type={repr(self.type)})"
+
+    def __hash__(self) -> int:
+        """Make node hashable based on its type's uid."""
+        return hash(self.uid)
+
+    def __eq__(self, other: Any) -> bool:
+        """Check equality based on type's uid."""
+        if not isinstance(other, Node):
+            return False
+        return self.uid == other.uid
+
+
+class Edge(BaseModel):
+    """
+    An edge in the implicational logic graph.
+
+    Each edge represents a combinator that transforms from the source node's
+    type to the destination node's type.
+
+    The edge is valid if and only if:
+    - src_node.type matches the combinator's input type
+    - dst_node.type matches the combinator's output type
+    """
+
+    src_node: Node = Field(..., description="Source node of the edge")
+    dst_node: Node = Field(..., description="Destination node of the edge")
+    combinator: Combinator = Field(
+        ..., description="The combinator for this transformation"
+    )
+
+    model_config = ConfigDict(frozen=True)  # Make immutable
+
+    @model_validator(mode="after")
+    def validate_combinator_type(self) -> "Edge":
+        """
+        Validate that the combinator's type matches the transformation.
+
+        The combinator must have an Application type where:
+        - input_type matches the source node's type
+        - output_type matches the destination node's type
+
+        Returns:
+            Edge: The validated edge instance
+
+        Raises:
+            ValueError: If the combinator type doesn't match the edge transformation
+        """
+        # Check if combinator type is an Application
+        if not isinstance(self.combinator.type, Application):
+            raise ValueError(
+                f"Combinator must have an Application type, "
+                f"got {type(self.combinator.type).__name__}"
+            )
+
+        # Check if input type matches source node
+        if self.combinator.type.input_type.uid != self.src_node.type.uid:
+            raise ValueError(
+                f"Combinator input type {self.combinator.type.input_type} "
+                f"does not match source node type {self.src_node.type}"
+            )
+
+        # Check if output type matches destination node
+        if self.combinator.type.output_type.uid != self.dst_node.type.uid:
+            raise ValueError(
+                f"Combinator output type {self.combinator.type.output_type} "
+                f"does not match destination node type {self.dst_node.type}"
+            )
+
+        return self
+
+    @cached_property
+    def uid(self) -> str:
+        """
+        Return a unique identifier for this edge.
+
+        The uid is composed of the source uid, combinator uid, and destination uid.
+
+        Returns:
+            str: SHA256 hash of the edge structure
+        """
+        content = f"Edge({self.src_node.uid},{self.combinator.uid},{self.dst_node.uid})"
+        return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+    def __str__(self) -> str:
+        """Return a string representation of the edge."""
+        return f"{self.src_node.type} --[{self.combinator}]--> {self.dst_node.type}"
+
+    def __repr__(self) -> str:
+        """Return a detailed representation."""
+        return (
+            f"Edge(src_node={repr(self.src_node)}, "
+            f"dst_node={repr(self.dst_node)}, "
+            f"combinator={repr(self.combinator)})"
+        )
+
+    def __hash__(self) -> int:
+        """Make edge hashable based on its uid."""
+        return hash(self.uid)
+
+    def __eq__(self, other: Any) -> bool:
+        """Check equality based on uid."""
+        if not isinstance(other, Edge):
+            return False
+        return self.uid == other.uid
+
+
+# Helper functions
+def node(type: BaseType) -> Node:
+    """
+    Helper function to create a Node.
+
+    Args:
+        type: The type for the node
+
+    Returns:
+        Node: A new Node instance
+    """
+    return Node(type=type)
+
+
+def edge(combinator: Combinator) -> Edge:
+    """
+    Helper function to create an Edge from a Combinator.
+
+    The combinator must have an Application type, and the edge will be created
+    with nodes corresponding to the input and output types.
+
+    Args:
+        combinator: The combinator for this edge
+
+    Returns:
+        Edge: A new Edge instance
+
+    Raises:
+        ValueError: If the combinator doesn't have an Application type
+    """
+    if not isinstance(combinator.type, Application):
+        raise ValueError(
+            f"Combinator must have an Application type to create an edge, "
+            f"got {type(combinator.type).__name__}"
+        )
+
+    src_node = node(combinator.type.input_type)
+    dst_node = node(combinator.type.output_type)
+
+    return Edge(src_node=src_node, dst_node=dst_node, combinator=combinator)