Service Interfaces (Protocols)¶

@runtime_checkable
class IGraphService(Protocol):
    """Contract for all graph-mutation and graph-query operations."""

    def create_graph(
        self,
        workspace_id: WorkspaceId,
        type_name: str,
        name: str,
    ) -> Graph:
        """Create a new graph in the given workspace.

        Args:
            workspace_id: Owning workspace.
            type_name: Registered graph type name.
            name: Human-readable display name.

        Returns:
            Newly created :class:`~knowledge_platform.core.graph.Graph`.
        """
        ...

    def get_graph(self, graph_id: GraphId) -> Graph:
        """Retrieve a graph by ID.

        Args:
            graph_id: Target identifier.

        Returns:
            The :class:`~knowledge_platform.core.graph.Graph`.

        Raises:
            KeyError: If not found.
        """
        ...

    def list_graphs(self, workspace_id: WorkspaceId) -> list[Graph]:
        """List all graphs in a workspace.

        Args:
            workspace_id: Owning workspace.

        Returns:
            Possibly empty list of graphs.
        """
        ...

    def delete_graph(self, graph_id: GraphId) -> None:
        """Permanently delete a graph.

        Args:
            graph_id: Target identifier.
        """
        ...

    def add_node(
        self,
        graph_id: GraphId,
        type_name: str,
        attributes: dict[str, object],
    ) -> Node:
        """Create and add a node to a graph.

        Args:
            graph_id: Owning graph.
            type_name: Node type registered on the graph's type.
            attributes: Initial attribute payload.

        Returns:
            The created :class:`~knowledge_platform.core.node.Node`.
        """
        ...

    def update_node(self, node_id: NodeId, attributes: dict[str, object]) -> Node:
        """Update attributes on an existing node.

        Args:
            node_id: Target node.
            attributes: Attributes to merge (partial update).

        Returns:
            Updated :class:`~knowledge_platform.core.node.Node`.
        """
        ...

    def remove_node(self, graph_id: GraphId, node_id: NodeId) -> None:
        """Remove a node and all its incident edges.

        Args:
            graph_id: Owning graph.
            node_id: Target node.
        """
        ...

    def add_edge(
        self,
        graph_id: GraphId,
        source_id: NodeId,
        target_id: NodeId,
        type_name: str,
        attributes: dict[str, object],
    ) -> Edge:
        """Create and add a directed edge between two nodes.

        Args:
            graph_id: Owning graph.
            source_id: Origin node.
            target_id: Destination node.
            type_name: Edge type registered on the graph's type.
            attributes: Initial attribute payload.

        Returns:
            The created :class:`~knowledge_platform.core.edge.Edge`.
        """
        ...

    def remove_edge(self, graph_id: GraphId, edge_id: EdgeId) -> None:
        """Remove an edge.

        Args:
            graph_id: Owning graph.
            edge_id: Target edge.
        """
        ...

@runtime_checkable
class IWorkspaceService(Protocol):
    """Contract for workspace lifecycle operations."""

    def create_workspace(self, name: str) -> Workspace:
        """Create a new local workspace.

        Args:
            name: Display name.

        Returns:
            Newly created :class:`~knowledge_platform.workspace.Workspace`.
        """
        ...

    def get_workspace(self, workspace_id: WorkspaceId) -> Workspace:
        """Retrieve a workspace by ID.

        Args:
            workspace_id: Target identifier.

        Returns:
            The :class:`~knowledge_platform.workspace.Workspace`.

        Raises:
            KeyError: If not found.
        """
        ...

    def list_workspaces(self) -> list[Workspace]:
        """Return all known workspaces.

        Returns:
            Possibly empty list.
        """
        ...