mbdlyb.gdb

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

`LBL_INFLUENCE`
`LBL_PARTOF`
`MBDLYB_CLASSES`

Classes

`GMBDDependency`	Graph-backed dependency relationship between MBD nodes.
`GMBDElement`	Base graph-backed MBD element with FQN management.
`GMBDIdentifiable`	Mixin for graph-backed elements with unique identifiers.
`GMBDInfluence`	Graph-backed influence relationship between MBD nodes.
`GMBDInfluenceableNode`	Graph-backed node that can be influenced by other nodes.
`GMBDNet`	Graph-backed MBD network with hierarchical structure support.
`GMBDNode`	Graph-backed MBD node with state management.
`GMBDRelation`	Base class for graph-backed MBD relationships.
`GPartOfRelation`	Graph-backed part-of relationship for hierarchical decomposition.

Functions

`cls`(→ type[GMBDElement])	Get the registered graph-backed class for an MBD class.
`get_object`(→ Optional[T])	Get a single object from the database.
`set_config`(→ None)	Configure the Neo4j graph database connection.

Module Contents

class mbdlyb.gdb.GMBDDependency(**kwargs: dict[str, Any])

Bases: 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.

class mbdlyb.gdb.GMBDElement(*args: Any, **kwargs: Any)

Bases: neomodel.StructuredNode, 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.

Variables:

__label__ – Neo4j node label (used for polymorphism).
name – The element’s local name within its parent network.
net – Relationship to the parent network (if any).
fqn – The fully qualified name stored in the database.

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.

get_net() → GMBDNet

Get the parent network.

Returns:: The parent GMBDNet or raises if at root.

get_path_to(destination: GMBDElement) → list[GMBDElement]

Get the path from this element to a destination element.

Parameters:: destination – The target element.
Returns:: List of elements along the path (not including self or destination).

get_root() → GMBDNet

Get the root network in the hierarchy.

Returns:: The topmost network in the hierarchy.

abstractmethod load(node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet]) → Type[mbdlyb.MBDElement]

Load this graph element into an in-memory MBD element.

Parameters:

node_map – Mapping from UIDs to (GMBDElement, MBDElement) tuples.
net – The MBD network being loaded.

Returns:

An MBDElement representing this graph element.

Raises:

NotImplementedError – This base implementation must be overridden by subclasses.

set_net(net: GMBDNet)

Set the parent network and update FQN.

Parameters:: net – The new parent network.

update_fqn(prefix: mbdlyb.fqn.FQN | None = None)

Update and save the FQN in the database.

Parameters:: prefix – Optional FQN prefix. If None, computes FQN from hierarchy.

validate() → list[mbdlyb.messages.ValidationMessage]

Validate this element for consistency.

Returns:: List of validation messages (empty if valid).

property at_root: bool

Check if this element is at the root of the hierarchy.

Returns:: True if this element has no parent network.

property fqn: mbdlyb.fqn.FQN

Get the fully qualified name of this element.

Returns:: FQN object representing the complete path to this element.

fqn_

name

net

class mbdlyb.gdb.GMBDIdentifiable

Mixin for graph-backed elements with unique identifiers.

Provides a unique ID property for all graph database entities.

Variables:: uid – Unique identifier for this element in the database.

uid

class mbdlyb.gdb.GMBDInfluence(**kwargs: dict[str, Any])

Bases: GMBDRelation

Graph-backed influence relationship between MBD nodes.

Represents the influence of one or more nodes on another node’s state or behavior.

class mbdlyb.gdb.GMBDInfluenceableNode[T](*args: Any, **kwargs: Any)

Bases: GMBDNode[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.

Variables:: influencers – Relationship tracking nodes that influence this node.

influencers

class mbdlyb.gdb.GMBDNet(*args: Any, **kwargs: Any)

Bases: 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.

Variables:

__label__ – Neo4j node label for network type.
elements – All elements contained in this network.
mbdnodes – All nodes contained in this network.
subnets – All sub-networks contained in this network.

get_element(fqn: 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.

Parameters:

fqn – The fully qualified name (as FQN or string).
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.

has_element(fqn: mbdlyb.fqn.FQN | str) → bool

Check if an element exists in this network by FQN.

Parameters:: fqn – The fully qualified name to search for.
Returns:: True if the element exists, False otherwise.

abstractmethod load(node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet] = None) → Type[mbdlyb.MBDNet]

Load this graph network into an in-memory MBD network.

Parameters:

node_map – Mapping from UIDs to (GMBDElement, MBDElement) tuples.
net – The MBD network being loaded (for recursive calls).

Returns:

An MBDNet object representing this network.

Raises:

NotImplementedError – Must be implemented by subclasses.

classmethod load_from_db(uid: str) → mbdlyb.MBDNet

Load a complete network from the graph database.

Loads the network and all its elements and relationships into memory.

Parameters:: uid – The UID of the network to load.
Returns:: Complete in-memory MBDNet object with all hierarchy and relations.

relation_kwargs(net: mbdlyb.MBDNet) → dict[str, Any]

Get keyword arguments for relation loading.

Allows subclasses to customize how relations are created during loading.

Parameters:: net – The MBD network being loaded.
Returns:: Dictionary of keyword arguments for relation creation.

update_fqn(prefix: mbdlyb.fqn.FQN | None = None)

Update FQN for this network and all contained elements.

Parameters:: prefix – Optional FQN prefix for hierarchical updates.

validate() → list[mbdlyb.messages.ValidationMessage]

Validate this network and all contained elements.

Returns:: List of validation messages for any issues found.

elements

mbdnodes

subnets

class mbdlyb.gdb.GMBDNode[T](*args: Any, **kwargs: Any)

Bases: 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).

Variables:

__label__ – Neo4j node label for this node type.
_DEFAULT_STATES – Default states if none are explicitly set.
states – Array property storing custom states.

abstractmethod parents() → list[GMBDNode]

Get the parent nodes this node depends on.

Returns:: List of parent nodes.
Raises:: NotImplementedError – Must be implemented by subclasses.

property has_custom_states: bool

Check if this node has custom (non-default) states.

Returns:: True if custom states are defined.

property is_normalized_state: bool

Check if states are normalized to [0, 1] range.

Returns:: True if all states are numeric with min=0 and max=1.

property states: list[T]

Get the possible states of this node.

Returns:: The custom states if set, otherwise the default states.

states_

class mbdlyb.gdb.GMBDRelation(**kwargs: dict[str, Any])

Bases: neomodel.StructuredRel, GMBDIdentifiable

Base class for graph-backed MBD relationships.

Represents edges in the graph database connecting MBD elements. Subclasses define specific relationship types (dependencies, influences).

abstractmethod load(from_uid: str, to_uid: str, node_map: dict[str, tuple[GMBDElement, mbdlyb.MBDElement]], net: Type[mbdlyb.MBDNet], **kwargs) → Type[mbdlyb.MBDRelation]

Load this relationship into an MBD object.

Converts the graph-backed relationship to an in-memory MBD relation.

Parameters:

from_uid – Unique ID of the source node in the graph.
to_uid – Unique ID of the target node in the graph.
node_map – Mapping from UIDs to (GMBDElement, MBDElement) tuples.
net – The MBD network being loaded.
**kwargs – Additional keyword arguments for subclasses.

Returns:

An MBDRelation object or subclass representing this relationship.

Raises:

NotImplementedError – This base implementation must be overridden.

class mbdlyb.gdb.GPartOfRelation(**kwargs: dict[str, Any])

Bases: GMBDDependency

Graph-backed part-of relationship for hierarchical decomposition.

Represents hierarchical relationships where elements are parts of networks.

mbdlyb.gdb.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.

Parameters:: c – The MBD class to look up.
Returns:: The corresponding graph-backed class if registered, otherwise the input class.

mbdlyb.gdb.get_object[T](klass: type[T], **kwargs) → T | None

Get a single object from the database.

Queries for an object matching the given criteria. Returns None if not found.

Parameters:

klass – The class to query for.
**kwargs – Query criteria as keyword arguments.

Returns:

The matching object or None if no match exists.

mbdlyb.gdb.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.

Parameters:

protocol – Connection protocol (e.g., ‘neo4j’, ‘neo4j+s’).
username – Database user name.
password – Database password.
host – Database host address.
port – Database port number.
database – Optional database name for multi-database support.

Returns:

None

mbdlyb.gdb.LBL_INFLUENCE = 'INFLUENCE'

mbdlyb.gdb.LBL_PARTOF = 'PART_OF'

mbdlyb.gdb.MBDLYB_CLASSES: dict[type[GMBDElement], type[GMBDElement]]