mbdlyb.gdb ========== .. py:module:: mbdlyb.gdb .. autoapi-nested-parse:: Graph database persistence layer for MBD models. This module provides Neo4j-based persistence for MBD network structures, enabling storage and retrieval of complex model hierarchies in a graph database. It defines graph-backed versions of all core MBD classes with automatic FQN management and relationship handling. Key classes: - GMBDElement: Base class for graph-backed MBD elements - GMBDNode: Graph-backed node with state management - GMBDNet: Graph-backed network/subnet - GMBDRelation: Base for graph-backed relationships - GMBDDependency, GMBDInfluence: Specific relationship types Attributes ---------- .. autoapisummary:: mbdlyb.gdb.LBL_INFLUENCE mbdlyb.gdb.LBL_PARTOF mbdlyb.gdb.MBDLYB_CLASSES Classes ------- .. autoapisummary:: mbdlyb.gdb.GMBDDependency mbdlyb.gdb.GMBDElement mbdlyb.gdb.GMBDIdentifiable mbdlyb.gdb.GMBDInfluence mbdlyb.gdb.GMBDInfluenceableNode mbdlyb.gdb.GMBDNet mbdlyb.gdb.GMBDNode mbdlyb.gdb.GMBDRelation mbdlyb.gdb.GPartOfRelation Functions --------- .. autoapisummary:: mbdlyb.gdb.cls mbdlyb.gdb.get_object mbdlyb.gdb.set_config Module Contents --------------- .. py:class:: GMBDDependency(**kwargs: dict[str, Any]) Bases: :py:obj:`GMBDRelation` Graph-backed dependency relationship between MBD nodes. Represents a causal or informational dependency where one node's state depends on another node's state in the Bayesian network. .. py:class:: GMBDElement(*args: Any, **kwargs: Any) Bases: :py:obj:`neomodel.StructuredNode`, :py:obj:`GMBDIdentifiable` Base graph-backed MBD element with FQN management. Represents any element in the MBD model stored in the graph database. Handles hierarchical naming through fully qualified names (FQNs) and maintains relationships to parent networks. :ivar __label__: Neo4j node label (used for polymorphism). :ivar name: The element's local name within its parent network. :ivar net: Relationship to the parent network (if any). :ivar fqn_: The fully qualified name stored in the database. .. py:method:: compute_fqn() -> mbdlyb.fqn.FQN Compute the FQN based on hierarchy. For root elements, returns just the name. For nested elements, combines parent FQN with the local name. :returns: Computed FQN for this element. .. py:method:: get_net() -> GMBDNet Get the parent network. :returns: The parent GMBDNet or raises if at root. .. py:method:: get_path_to(destination: GMBDElement) -> list[GMBDElement] Get the path from this element to a destination element. :param destination: The target element. :returns: List of elements along the path (not including self or destination). .. py:method:: get_root() -> GMBDNet Get the root network in the hierarchy. :returns: The topmost network in the hierarchy. .. py:method:: load(node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet]) -> Type[mbdlyb.MBDElement] :abstractmethod: Load this graph element into an in-memory MBD element. :param node_map: Mapping from UIDs to (GMBDElement, MBDElement) tuples. :param net: The MBD network being loaded. :returns: An MBDElement representing this graph element. :raises NotImplementedError: This base implementation must be overridden by subclasses. .. py:method:: set_net(net: GMBDNet) Set the parent network and update FQN. :param net: The new parent network. .. py:method:: update_fqn(prefix: Optional[mbdlyb.fqn.FQN] = None) Update and save the FQN in the database. :param prefix: Optional FQN prefix. If None, computes FQN from hierarchy. .. py:method:: validate() -> list[mbdlyb.messages.ValidationMessage] Validate this element for consistency. :returns: List of validation messages (empty if valid). .. py:property:: at_root :type: bool Check if this element is at the root of the hierarchy. :returns: True if this element has no parent network. .. py:property:: fqn :type: mbdlyb.fqn.FQN Get the fully qualified name of this element. :returns: FQN object representing the complete path to this element. .. py:attribute:: fqn_ .. py:attribute:: name .. py:attribute:: net .. py:class:: GMBDIdentifiable Mixin for graph-backed elements with unique identifiers. Provides a unique ID property for all graph database entities. :ivar uid: Unique identifier for this element in the database. .. py:attribute:: uid .. py:class:: GMBDInfluence(**kwargs: dict[str, Any]) Bases: :py:obj:`GMBDRelation` Graph-backed influence relationship between MBD nodes. Represents the influence of one or more nodes on another node's state or behavior. .. py:class:: GMBDInfluenceableNode[T](*args: Any, **kwargs: Any) Bases: :py:obj:`GMBDNode`\ [\ :py:obj:`T`\ ] Graph-backed node that can be influenced by other nodes. Extends GMBDNode with the ability to track influencing relationships, representing nodes whose behavior or state can be affected by other nodes. :ivar influencers: Relationship tracking nodes that influence this node. .. py:attribute:: influencers .. py:class:: GMBDNet(*args: Any, **kwargs: Any) Bases: :py:obj:`GMBDElement` Graph-backed MBD network with hierarchical structure support. Represents a Bayesian network or sub-network stored in the graph database. Manages hierarchical decomposition through PART_OF relationships and handles loading of complete networks with all relations. :ivar __label__: Neo4j node label for network type. :ivar elements: All elements contained in this network. :ivar mbdnodes: All nodes contained in this network. :ivar subnets: All sub-networks contained in this network. .. py:method:: get_element(fqn: Union[mbdlyb.fqn.FQN, str], skipped_root: bool = False) -> GMBDElement Get an element by fully qualified name. Recursively searches for an element by FQN through the hierarchy. :param fqn: The fully qualified name (as FQN or string). :param skipped_root: Internal flag for recursive calls to skip root matching. :returns: The GMBDElement matching the FQN. :raises ElementNotFoundError: If the element is not found. .. py:method:: has_element(fqn: Union[mbdlyb.fqn.FQN, str]) -> bool Check if an element exists in this network by FQN. :param fqn: The fully qualified name to search for. :returns: True if the element exists, False otherwise. .. py:method:: load(node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet] = None) -> Type[mbdlyb.MBDNet] :abstractmethod: Load this graph network into an in-memory MBD network. :param node_map: Mapping from UIDs to (GMBDElement, MBDElement) tuples. :param net: The MBD network being loaded (for recursive calls). :returns: An MBDNet object representing this network. :raises NotImplementedError: Must be implemented by subclasses. .. py:method:: load_from_db(uid: str) -> mbdlyb.MBDNet :classmethod: Load a complete network from the graph database. Loads the network and all its elements and relationships into memory. :param uid: The UID of the network to load. :returns: Complete in-memory MBDNet object with all hierarchy and relations. .. py:method:: relation_kwargs(net: mbdlyb.MBDNet) -> dict[str, Any] Get keyword arguments for relation loading. Allows subclasses to customize how relations are created during loading. :param net: The MBD network being loaded. :returns: Dictionary of keyword arguments for relation creation. .. py:method:: update_fqn(prefix: Optional[mbdlyb.fqn.FQN] = None) Update FQN for this network and all contained elements. :param prefix: Optional FQN prefix for hierarchical updates. .. py:method:: validate() -> list[mbdlyb.messages.ValidationMessage] Validate this network and all contained elements. :returns: List of validation messages for any issues found. .. py:attribute:: elements .. py:attribute:: mbdnodes .. py:attribute:: subnets .. py:class:: GMBDNode[T](*args: Any, **kwargs: Any) Bases: :py:obj:`GMBDElement` Graph-backed MBD node with state management. Extends GMBDElement to represent system components with discrete states. Manages parent dependencies and provides state normalization checks. Type parameter: T: The type of state values (typically str or float). :ivar __label__: Neo4j node label for this node type. :ivar _DEFAULT_STATES: Default states if none are explicitly set. :ivar states_: Array property storing custom states. .. py:method:: parents() -> list[GMBDNode] :abstractmethod: Get the parent nodes this node depends on. :returns: List of parent nodes. :raises NotImplementedError: Must be implemented by subclasses. .. py:property:: has_custom_states :type: bool Check if this node has custom (non-default) states. :returns: True if custom states are defined. .. py:property:: is_normalized_state :type: bool Check if states are normalized to [0, 1] range. :returns: True if all states are numeric with min=0 and max=1. .. py:property:: states :type: list[T] Get the possible states of this node. :returns: The custom states if set, otherwise the default states. .. py:attribute:: states_ .. py:class:: GMBDRelation(**kwargs: dict[str, Any]) Bases: :py:obj:`neomodel.StructuredRel`, :py:obj:`GMBDIdentifiable` Base class for graph-backed MBD relationships. Represents edges in the graph database connecting MBD elements. Subclasses define specific relationship types (dependencies, influences). .. py:method:: load(from_uid: str, to_uid: str, node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet], **kwargs) -> Type[mbdlyb.MBDRelation] :abstractmethod: Load this relationship into an MBD object. Converts the graph-backed relationship to an in-memory MBD relation. :param from_uid: Unique ID of the source node in the graph. :param to_uid: Unique ID of the target node in the graph. :param node_map: Mapping from UIDs to (GMBDElement, MBDElement) tuples. :param net: The MBD network being loaded. :param \*\*kwargs: Additional keyword arguments for subclasses. :returns: An MBDRelation object or subclass representing this relationship. :raises NotImplementedError: This base implementation must be overridden. .. py:class:: GPartOfRelation(**kwargs: dict[str, Any]) Bases: :py:obj:`GMBDDependency` Graph-backed part-of relationship for hierarchical decomposition. Represents hierarchical relationships where elements are parts of networks. .. py:function:: cls(c: type[GMBDElement]) -> type[GMBDElement] Get the registered graph-backed class for an MBD class. Allows mapping of MBD classes to their graph-backed equivalents. :param c: The MBD class to look up. :returns: The corresponding graph-backed class if registered, otherwise the input class. .. py:function:: get_object[T](klass: type[T], **kwargs) -> Optional[T] Get a single object from the database. Queries for an object matching the given criteria. Returns None if not found. :param klass: The class to query for. :param \*\*kwargs: Query criteria as keyword arguments. :returns: The matching object or None if no match exists. .. py:function:: set_config(protocol: str, username: str, password: str, host: str, port: int, database: str = None) -> None Configure the Neo4j graph database connection. Sets up the database URL for neomodel to use in all database operations. :param protocol: Connection protocol (e.g., 'neo4j', 'neo4j+s'). :param username: Database user name. :param password: Database password. :param host: Database host address. :param port: Database port number. :param database: Optional database name for multi-database support. :returns: None .. py:data:: LBL_INFLUENCE :value: 'INFLUENCE' .. py:data:: LBL_PARTOF :value: 'PART_OF' .. py:data:: MBDLYB_CLASSES :type: dict[type[GMBDElement], type[GMBDElement]]