flexCommunicator 0.1.0__py3-none-any.whl

flexCommunicator/clientLibraries/flcpy/validityFrame/validityFrameManager.py

@@ -0,0 +1,958 @@
+#**************************************************************************
+# * Copyright (C) 2025-present Bert Van Acker (B.MKR) <bva.bmkr@gmail.com>
+# *
+# * This file is part of the flexIA project.
+# *
+# * flexIA can not be copied and/or distributed without the express
+# * permission of Bert Van Acker
+# *************************************************************************
+import tempfile
+import zipfile
+import json
+import importlib.util
+from pathlib import Path
+
+from flexCommunicator.clientLibraries.flcpy.validityFrame.runtimeMonitor import *
+
+class RuntimeMonitorObserverable(object):
+    def __init__(self, monitor_info, logger=None, custom_check_function=None, custom_source_path=None):
+        self.info = monitor_info
+        self.logger = logger
+        self.custom_check_function = custom_check_function
+        self.custom_source_path = custom_source_path
+        self.name = monitor_info["name"]
+        self.description = monitor_info.get("description")
+        self.guid = monitor_info.get("guid")
+        self.observes = monitor_info.get("observes", [])
+        self.spec_status = dict(monitor_info.get("spec_status", {}))
+        self.last_observed_values = dict(monitor_info.get("last_observed_values", {}))
+        self.status = monitor_info.get("status")
+
+    def __getitem__(self, key):
+        return self.info[key]
+
+    def get(self, key, default=None):
+        return self.info.get(key, default)
+
+    def set(self, value):
+        """Set observed values and evaluate the monitor."""
+        if isinstance(value, dict):
+            data_vector = value
+        elif len(self.observes) == 1:
+            feature = self.observes[0].get("feature") or self.observes[0].get("name")
+            data_vector = {feature: value}
+        else:
+            raise ValueError("Monitor '" + self.name + "' observes multiple features; pass a dict of feature values")
+
+        return self.check(data_vector)
+
+    def check(self, data_vector):
+        """Evaluate observed values and update monitor status."""
+        evaluations = {}
+        if self.custom_check_function is not None:
+            custom_evaluations = self.custom_check_function(data_vector, monitor=self)
+            if custom_evaluations is None:
+                custom_evaluations = {}
+            if not isinstance(custom_evaluations, dict):
+                raise ValueError("Custom monitor check must return a feature-to-bool dictionary")
+            evaluations.update(custom_evaluations)
+
+        for observed_property in self.observes:
+            feature = observed_property.get("feature") or observed_property.get("name")
+            if feature not in data_vector:
+                continue
+
+            self.last_observed_values[feature] = data_vector[feature]
+            if feature not in evaluations:
+                evaluations[feature] = self._checkObservedProperty(observed_property, data_vector[feature])
+
+        for feature, is_valid in evaluations.items():
+            self.spec_status[feature] = "valid" if is_valid else "invalid"
+
+        if evaluations:
+            self.status = "valid" if all(evaluations.values()) else "invalid"
+        else:
+            self.status = "unknown"
+
+        return evaluations
+
+
+class validityFrameManager(object):
+    def __init__(self, name, logger, model_loader_mode="internal", model_loader_function=None, monitor_loader_mode="internal", monitor_loader_function=None):
+        self.name = name
+        self.logger = logger
+        self.path_to_fmu = None
+        self.path_to_vf = None
+        self._unpacked_vf_dir = None
+        self._temp_dir = None
+        self.vf_instance = None
+        self.model = None
+        self.runtime_monitors = {}
+        self.saifety_architecture = None
+        self.saifety_architecture_path = None
+        self.traceability_graph = None
+        self.traceability_graph_path = None
+        self._operational_data = None
+        self._operational_path = None
+        self._metadata_data = None
+        self._metadata_path = None
+        self.model_loader_mode = model_loader_mode
+        self.model_loader_function = model_loader_function
+        self.model_loader_path = None
+        self.monitor_loader_mode = monitor_loader_mode
+        self.monitor_loader_function = monitor_loader_function
+        self.monitor_loader_paths = {}
+
+        #flexIA runtime monitor instances
+        self.flexia_runtime_monitors = []
+
+    def _log(self, level, message):
+        if self.logger is None:
+            print(message)
+            return
+
+        getattr(self.logger, level)(message)
+
+    def load(self, path_to_vf):
+        """Load the validity frame from a folder or a zipped .vf archive."""
+        self.path_to_fmu = path_to_vf
+        self._log("info", "Loading validity frame: " + str(path_to_vf))
+        self.path_to_vf = self._resolveValidityFramePath(path_to_vf)
+
+        # TODO: instantiate/load the VF FMU once the concrete loader is selected.
+        self.vf_instance = None
+        self._loadRuntimeMonitors()
+        self.model = self.getModel()
+        self._loadMetadata()
+        self.generateSAIfetyArchitecture()
+        self.generateTraceabilityGraph()
+        self._registerRuntime()
+        return self
+
+    def dump(self):
+        """Show metadata of the loaded validity frame."""
+        metadata = {
+            "name": self.name,
+            "path_to_fmu": self.path_to_fmu,
+            "path_to_vf": str(self.path_to_vf) if self.path_to_vf is not None else None,
+            "loaded": self.vf_instance is not None,
+            "model": self.model,
+            "model_loader_mode": self.model_loader_mode,
+            "model_loader_path": str(self.model_loader_path) if self.model_loader_path else None,
+            "monitor_loader_mode": self.monitor_loader_mode,
+            "monitor_loader_paths": {name: str(path) for name, path in self.monitor_loader_paths.items()},
+            "runtime_monitors": list(self.runtime_monitors.keys()),
+            "saifety_architecture_path": str(self.saifety_architecture_path) if self.saifety_architecture_path else None,
+            "traceability_graph_path": str(self.traceability_graph_path) if self.traceability_graph_path else None,
+        }
+        self._log("info", "Validity frame metadata: " + json.dumps(metadata, indent=2))
+        return metadata
+
+    def update(self, runtimeMonitorName, value):
+        """Update a runtime monitor value."""
+        return self._setRuntimeMonitor(runtimeMonitorName, value)
+
+    def configureModelLoader(self, mode="internal", load_model_function=None):
+        """Configure how getModel loads the AI model."""
+        supported_modes = ["internal", "linked", "auto"]
+        if mode not in supported_modes:
+            raise ValueError("Unsupported model loader mode: " + str(mode))
+
+        if mode == "linked" and load_model_function is None:
+            raise ValueError("linked model loader mode requires a load_model_function")
+
+        self.model_loader_mode = mode
+        self.model_loader_function = load_model_function
+        self.model_loader_path = None
+        return self
+
+    def configureMonitorLoader(self, mode="internal", check_function=None):
+        """Configure how runtime monitors use custom check code."""
+        supported_modes = ["internal", "linked", "auto"]
+        if mode not in supported_modes:
+            raise ValueError("Unsupported monitor loader mode: " + str(mode))
+
+        if mode == "linked" and check_function is None:
+            raise ValueError("linked monitor loader mode requires a check_function")
+
+        self.monitor_loader_mode = mode
+        self.monitor_loader_function = check_function
+        self.monitor_loader_paths = {}
+        for monitor in self.runtime_monitors.values():
+            custom_check_function, custom_source_path = self._getMonitorCheckFunction(monitor.info)
+            monitor.custom_check_function = custom_check_function
+            monitor.custom_source_path = custom_source_path
+            if custom_source_path is not None:
+                self.monitor_loader_paths[monitor.name] = custom_source_path
+
+        return self
+
+    def getModel(self):
+        """Return the model contained by the validity frame instance."""
+        if self.model_loader_mode == "internal":
+            return self._getModelInternal(self)
+
+        if self.model_loader_mode == "linked":
+            return self._callLoadModelFunction(self.model_loader_function)
+
+        if self.model_loader_mode == "auto":
+            load_model_function = self._autoDiscoverLoadModelFunction()
+            return self._callLoadModelFunction(load_model_function)
+
+        raise ValueError("Unsupported model loader mode: " + str(self.model_loader_mode))
+
+    def _getModelInternal(self, vf_instance):
+        """Internal model loading implementation."""
+        # TODO: extract and return the contained model from vf_instance.
+        self._log("info", "Using internal validity frame model loader")
+        return None
+
+    def _callLoadModelFunction(self, load_model_function):
+        """Call a custom load_model function with the expected VF context."""
+        if load_model_function is None:
+            raise ValueError("No load_model function configured")
+
+        model_location = self._getModelLocation()
+        self._log("info", "Using custom load_model function for model location: " + str(model_location))
+        original_logger = self.logger
+        if self.logger is None:
+            self.logger = _ConsoleLogger()
+
+        try:
+            return load_model_function(str(model_location), validityframe=self)
+        finally:
+            self.logger = original_logger
+
+    def _autoDiscoverLoadModelFunction(self):
+        """Discover a load_model function under Resources/loaders."""
+        loader_file = self._findModelLoaderFile()
+        self.model_loader_path = loader_file
+
+        module_name = "vf_model_loader_" + self._toIdentifier(str(loader_file))
+        spec = importlib.util.spec_from_file_location(module_name, loader_file)
+        if spec is None or spec.loader is None:
+            raise ImportError("Unable to import model loader from: " + str(loader_file))
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+
+        if not hasattr(module, "load_model"):
+            raise AttributeError("Model loader does not define load_model(): " + str(loader_file))
+
+        self._log("info", "Auto-discovered model loader: " + str(loader_file))
+        return module.load_model
+
+    def _loadPythonModuleFromFile(self, module_prefix, python_file):
+        """Load a Python module from a VF resource file."""
+        module_name = module_prefix + "_" + self._toIdentifier(str(python_file))
+        spec = importlib.util.spec_from_file_location(module_name, python_file)
+        if spec is None or spec.loader is None:
+            raise ImportError("Unable to import Python module from: " + str(python_file))
+
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+    def _findModelLoaderFile(self):
+        """Find the most appropriate Resources/loaders/*.py file."""
+        loaders_dir = self._findResourcesDirectory() / "loaders"
+        if not loaders_dir.is_dir():
+            raise FileNotFoundError("Resources/loaders directory not found in validity frame: " + str(self.path_to_vf))
+
+        model_structure = self._getActiveModelStructure()
+        model_type = model_structure.get("_modelType")
+        if model_type:
+            preferred_loader = loaders_dir / (str(model_type) + ".py")
+            if preferred_loader.is_file() and self._pythonFileDefinesLoadModel(preferred_loader):
+                return preferred_loader
+
+        loader_files = []
+        for loader_file in loaders_dir.glob("*.py"):
+            if loader_file.name == "__init__.py":
+                continue
+            if self._pythonFileDefinesLoadModel(loader_file):
+                loader_files.append(loader_file)
+
+        if len(loader_files) == 1:
+            return loader_files[0]
+
+        if not loader_files:
+            raise FileNotFoundError("No load_model() function found in Resources/loaders")
+
+        raise ValueError("Multiple load_model() functions found in Resources/loaders; configure a linked loader explicitly")
+
+    def _pythonFileDefinesLoadModel(self, python_file):
+        """Return True when a loader file appears to define load_model."""
+        with python_file.open("r", encoding="utf-8") as source_file:
+            for line in source_file:
+                if line.strip().startswith("def load_model("):
+                    return True
+
+        return False
+
+    def _getMonitorCheckFunction(self, monitor_info):
+        """Return a custom check function for a monitor according to configuration."""
+        if self.monitor_loader_mode == "internal":
+            return None, None
+
+        if self.monitor_loader_mode == "linked":
+            return self.monitor_loader_function, None
+
+        if self.monitor_loader_mode == "auto":
+            monitor_file = self._findMonitorCodeFile(monitor_info)
+            if monitor_file is None:
+                return None, None
+
+            module = self._loadPythonModuleFromFile("vf_monitor", monitor_file)
+            if hasattr(module, "custom_validate_vector"):
+                self._log("info", "Auto-discovered monitor custom code: " + str(monitor_file))
+                return module.custom_validate_vector, monitor_file
+
+            if hasattr(module, "check"):
+                self._log("info", "Auto-discovered monitor check function: " + str(monitor_file))
+                return module.check, monitor_file
+
+            raise AttributeError("Monitor custom code does not define custom_validate_vector() or check(): " + str(monitor_file))
+
+        raise ValueError("Unsupported monitor loader mode: " + str(self.monitor_loader_mode))
+
+    def _findMonitorCodeFile(self, monitor_info):
+        """Find custom monitor code under Resources/monitors."""
+        monitors_dir = self._findResourcesDirectory() / "monitors"
+        if not monitors_dir.is_dir():
+            return None
+
+        monitor_name = monitor_info["name"]
+        preferred_monitor = monitors_dir / (monitor_name + ".py")
+        if preferred_monitor.is_file() and self._pythonFileDefinesMonitorCheck(preferred_monitor):
+            return preferred_monitor
+
+        for monitor_file in monitors_dir.glob("*.py"):
+            if monitor_file.name == "__init__.py":
+                continue
+            if monitor_file.stem == monitor_name and self._pythonFileDefinesMonitorCheck(monitor_file):
+                return monitor_file
+
+        return None
+
+    def _pythonFileDefinesMonitorCheck(self, python_file):
+        """Return True when a monitor code file appears to define custom check logic."""
+        with python_file.open("r", encoding="utf-8") as source_file:
+            for line in source_file:
+                stripped_line = line.strip()
+                if stripped_line.startswith("def custom_validate_vector(") or stripped_line.startswith("def check("):
+                    return True
+
+        return False
+
+    def _findResourcesDirectory(self):
+        """Find the Resources directory in the loaded validity frame."""
+        resources_path = self.path_to_vf / "Resources"
+        if resources_path.is_dir():
+            return resources_path
+
+        resources_dirs = [path for path in self.path_to_vf.glob("*/Resources") if path.is_dir()]
+        if len(resources_dirs) == 1:
+            return resources_dirs[0]
+
+        if not resources_dirs:
+            raise FileNotFoundError("Resources directory not found in validity frame: " + str(self.path_to_vf))
+
+        raise ValueError("Multiple Resources directories found in validity frame: " + str(self.path_to_vf))
+
+    def _getModelLocation(self):
+        """Resolve the model artifact location passed to custom load_model functions."""
+        model_structure = self._getActiveModelStructure()
+        model_location = model_structure.get("_modelRef") or self._operational_data.get("_modelReference")
+        if model_location is None:
+            return self.path_to_vf
+
+        model_location = Path(model_location)
+        if model_location.is_absolute():
+            return model_location
+
+        return self.path_to_vf / model_location
+
+
+    def _loadRuntimeMonitors(self):
+        """Load runtime monitors from the validity frame."""
+        if self.path_to_vf is None:
+            raise ValueError("No validity frame has been loaded")
+
+        operational_path = self._findOperationalFile()
+        with operational_path.open("r", encoding="utf-8") as operational_file:
+            operational_data = json.load(operational_file)
+
+        self._operational_data = operational_data
+        self._operational_path = operational_path
+
+        runtime_monitor_definitions = operational_data.get("_runtime_monitors", [])
+        if not isinstance(runtime_monitor_definitions, list):
+            raise ValueError("Operational.json field '_runtime_monitors' must be a list")
+
+        self.runtime_monitors = {}
+        for monitor_definition in runtime_monitor_definitions:
+            monitor_info = self._extractRuntimeMonitorInfo(monitor_definition)
+
+            # -- flexIA runtime monitor instantiation --
+            _monitor = runtimeMonitor(name=monitor_info['name'], initial_value=0.0, type=VF_RUNTIME_MONITOR_TYPE.LOCAL,check=CONTRACT_CHECK_TYPE.BOUND_CHECK,bound=[0.7, 0.9])
+            #TODO: implement specific monitors here! (BOUND, SET, CUSTOM_CODE,...)
+
+            # store for registration
+            self.flexia_runtime_monitors.append(_monitor)
+
+
+            _monitorObserverable = RuntimeMonitorObserverable(
+                monitor_info=monitor_info,
+                logger=self.logger,
+                custom_check_function="",       #TODO: check for custom code
+                custom_source_path="",          #TODO: check for custom code source path
+            )
+
+            self.runtime_monitors[monitor_info["name"]] = _monitorObserverable
+
+
+
+        self._logRuntimeMonitorSummary(operational_path)
+
+        # TODO: translate the extracted runtime monitor metadata into runtime
+        # monitors in the flexIA framework.
+        return self.runtime_monitors
+
+    def _loadMetadata(self):
+        """Load metadata from the validity frame."""
+        if self.path_to_vf is None:
+            raise ValueError("No validity frame has been loaded")
+
+        metadata_path = self._findMetadataFile()
+        with metadata_path.open("r", encoding="utf-8") as metadata_file:
+            metadata_data = json.load(metadata_file)
+
+        self._metadata_data = metadata_data
+        self._metadata_path = metadata_path
+        self._log("info", "Loaded validity frame metadata from " + str(metadata_path))
+        return metadata_data
+
+    def generateSAIfetyArchitecture(self):
+        """Generate the SAIfety architecture JSON from Operational.json."""
+        if self._operational_data is None:
+            raise ValueError("Operational.json data must be loaded before generating the SAIfety architecture")
+
+        model_structure = self._getActiveModelStructure()
+        model_name = model_structure.get("_name") or self.name
+        model_id = "model_" + self._toIdentifier(model_name)
+
+        inputs = self._extractSAIfetyPorts(model_structure.get("_inports", []), "input")
+        outputs = self._extractSAIfetyPorts(model_structure.get("_outports", []), "output")
+
+        component = {
+            "id": self._toIdentifier(model_name),
+            "name": model_name,
+            "description": model_structure.get("_description"),
+            "inputs": inputs,
+            "outputs": outputs,
+            "ai_architecture": {
+                "pattern": "single_ai_component",
+                "models": [
+                    {
+                        "id": model_id,
+                        "name": model_name,
+                        "type": model_structure.get("_modelType"),
+                    }
+                ],
+                "flow": self._generateSAIfetyFlow(inputs, outputs, model_id),
+            },
+        }
+
+        architecture = {
+            "component": component,
+            "monitors": self._extractSAIfetyMonitors(inputs, outputs),
+        }
+
+        self.saifety_architecture = architecture
+        self.saifety_architecture_path = self._getSAIfetyArchitecturePath()
+        with self.saifety_architecture_path.open("w", encoding="utf-8") as architecture_file:
+            json.dump(architecture, architecture_file, indent=2)
+            architecture_file.write("\n")
+
+        self._log("info", "Generated SAIfety architecture: " + str(self.saifety_architecture_path))
+        return architecture
+
+    def generateTraceabilityGraph(self):
+        """Generate the traceability graph JSON from Metadata.json and Operational.json."""
+        if self._metadata_data is None:
+            raise ValueError("Metadata.json data must be loaded before generating the traceability graph")
+        if self._operational_data is None:
+            raise ValueError("Operational.json data must be loaded before generating the traceability graph")
+
+        graph = {
+            "directed": True,
+            "multigraph": False,
+            "graph": {},
+            "nodes": [],
+            "edges": [],
+        }
+        node_ids = set()
+        edge_ids = set()
+
+        specifications_by_guid = {}
+        for specification in self._metadata_data.get("_specifications", []):
+            specification_id = self._getTraceabilitySpecificationId(specification)
+            specifications_by_guid[specification.get("_GUID")] = specification_id
+            self._addTraceabilityNode(graph, node_ids, {
+                "type": "specification",
+                "status": specification.get("_status"),
+                "layer": 0,
+                "guid": specification.get("_GUID"),
+                "id": specification_id,
+            })
+
+        for property_definition in self._metadata_data.get("_properties", []):
+            property_id = self._getTraceabilityPropertyId(property_definition)
+            satisfies = property_definition.get("_satisfies") or []
+            self._addTraceabilityNode(graph, node_ids, {
+                "type": "property",
+                "status": None,
+                "layer": 1,
+                "satisfies": satisfies,
+                "guid": property_definition.get("_GUID"),
+                "id": property_id,
+            })
+
+            for specification_guid in satisfies:
+                specification_id = specifications_by_guid.get(specification_guid)
+                self._addTraceabilityEdge(graph, edge_ids, property_id, specification_id)
+
+        monitor_links_by_specification_guid = self._addTraceabilityMonitorNodes(
+            graph,
+            node_ids,
+            edge_ids,
+            specifications_by_guid,
+        )
+        self._addTraceabilityValueNodes(
+            graph,
+            node_ids,
+            edge_ids,
+            specifications_by_guid,
+            monitor_links_by_specification_guid,
+        )
+
+        self.traceability_graph = graph
+        self.traceability_graph_path = self._getTraceabilityGraphPath()
+        with self.traceability_graph_path.open("w", encoding="utf-8") as graph_file:
+            json.dump(graph, graph_file, indent=2)
+            graph_file.write("\n")
+
+        self._log("info", "Generated traceability graph: " + str(self.traceability_graph_path))
+        return graph
+
+    def _addTraceabilityMonitorNodes(self, graph, node_ids, edge_ids, specifications_by_guid):
+        """Add runtime and design-time monitor nodes and their traceability edges."""
+        monitor_links_by_specification_guid = {}
+        monitor_definitions = []
+        monitor_definitions.extend(self._operational_data.get("_runtime_monitors", []))
+        monitor_definitions.extend(self._operational_data.get("_design_time_monitors", []))
+
+        for monitor_definition in monitor_definitions:
+            monitor_id = monitor_definition.get("_description") or monitor_definition.get("_name")
+            self._addTraceabilityNode(graph, node_ids, {
+                "type": "monitor",
+                "status": monitor_definition.get("_status"),
+                "layer": 2,
+                "guid": monitor_definition.get("_GUID"),
+                "id": monitor_id,
+            })
+
+            for observed_property in monitor_definition.get("observes", []):
+                specification_guid = observed_property.get("_GUID")
+                monitor_links_by_specification_guid.setdefault(specification_guid, []).append(monitor_id)
+
+                property_id = self._findTraceabilityPropertyForSpecification(specification_guid)
+                self._addTraceabilityEdge(graph, edge_ids, property_id, monitor_id)
+
+                specification_id = specifications_by_guid.get(specification_guid)
+                self._addTraceabilityEdge(graph, edge_ids, monitor_id, specification_id)
+
+        return monitor_links_by_specification_guid
+
+    def _addTraceabilityValueNodes(self, graph, node_ids, edge_ids, specifications_by_guid, monitor_links_by_specification_guid):
+        """Add value nodes derived from specification constraints."""
+        for specification in self._metadata_data.get("_specifications", []):
+            value_id = self._formatTraceabilityValue(specification)
+            if value_id is None:
+                continue
+
+            specification_guid = specification.get("_GUID")
+            self._addTraceabilityNode(graph, node_ids, {
+                "type": "value",
+                "status": None,
+                "layer": 1,
+                "guid": specification_guid,
+                "id": value_id,
+            })
+
+            specification_id = specifications_by_guid.get(specification_guid)
+            self._addTraceabilityEdge(graph, edge_ids, value_id, specification_id)
+
+            for monitor_id in monitor_links_by_specification_guid.get(specification_guid, []):
+                self._addTraceabilityEdge(graph, edge_ids, value_id, monitor_id)
+
+    def _addTraceabilityNode(self, graph, node_ids, node):
+        """Add a graph node once."""
+        node_id = node.get("id")
+        if node_id in node_ids:
+            return
+
+        node_ids.add(node_id)
+        graph["nodes"].append(node)
+
+    def _addTraceabilityEdge(self, graph, edge_ids, source, target):
+        """Add a directed graph edge once."""
+        if source is None or target is None:
+            return
+
+        edge_id = (source, target)
+        if edge_id in edge_ids:
+            return
+
+        edge_ids.add(edge_id)
+        graph["edges"].append({
+            "source": source,
+            "target": target,
+        })
+
+    def _findTraceabilityPropertyForSpecification(self, specification_guid):
+        """Find the metadata property that satisfies a specification."""
+        for property_definition in self._metadata_data.get("_properties", []):
+            if specification_guid in (property_definition.get("_satisfies") or []):
+                return self._getTraceabilityPropertyId(property_definition)
+
+        return None
+
+    def _getTraceabilityPropertyId(self, property_definition):
+        """Return a display id for a property node."""
+        return property_definition.get("_name") or property_definition.get("_GUID")
+
+    def _getTraceabilitySpecificationId(self, specification):
+        """Return a display id for a specification node."""
+        return (
+            specification.get("_description")
+            or specification.get("_feature")
+            or specification.get("_name")
+            or specification.get("_GUID")
+        )
+
+    def _formatTraceabilityValue(self, specification):
+        """Format specification values as traceability value nodes."""
+        value = specification.get("_value") or {}
+        specification_type = specification.get("_type")
+
+        if specification_type == "property_range":
+            return "[" + str(value.get("_valueMin")) + " - " + str(value.get("_valueMax")) + "]"
+
+        if specification_type == "property_min":
+            return ">=" + str(value.get("_valueMin"))
+
+        if specification_type == "property_max":
+            return "<=" + str(value.get("_valueMax"))
+
+        if specification_type == "property_mean":
+            return str(value.get("_average")) + " +/- " + str(value.get("_deviation"))
+
+        return None
+
+    def _getActiveModelStructure(self):
+        """Return the active model structure, or the first model for now."""
+        model_structures = self._operational_data.get("_modelStructures", [])
+        if not model_structures:
+            raise ValueError("Operational.json does not contain any model structures")
+
+        active_model_structure = self._operational_data.get("_activeModelStructure")
+        if active_model_structure:
+            for model_structure in model_structures:
+                if model_structure.get("_name") == active_model_structure or model_structure.get("_GUID") == active_model_structure:
+                    return model_structure
+
+        return model_structures[0]
+
+    def _extractSAIfetyPorts(self, port_definitions, port_prefix):
+        """Extract SAIfety input/output port definitions."""
+        ports = []
+        for port_definition in port_definitions:
+            port_name = port_definition.get("_name") or port_definition.get("_GUID") or "unnamed"
+            port = {
+                "id": port_prefix + "_" + self._toIdentifier(port_name),
+                "name": port_name,
+                "datatype": port_definition.get("_datatype"),
+                "dimensions": None,
+                "shape": [],
+                "unit": port_definition.get("_unit"),
+                "value_range": self._extractValueRange(port_definition),
+                "description": port_definition.get("_description"),
+                "source_guid": port_definition.get("_GUID"),
+                "mapping": port_definition.get("_mapping"),
+            }
+            ports.append(port)
+
+        return ports
+
+    def _extractValueRange(self, port_definition):
+        """Extract a SAIfety value range from an Operational.json port."""
+        min_value = port_definition.get("_min")
+        max_value = port_definition.get("_max")
+        if min_value is None and max_value is None:
+            return None
+
+        return {
+            "min": min_value,
+            "max": max_value,
+        }
+
+    def _generateSAIfetyFlow(self, inputs, outputs, model_id):
+        """Build the single-component AI flow."""
+        flow = []
+        for input_port in inputs:
+            flow.append({
+                "from": input_port["id"],
+                "to": model_id,
+            })
+
+        for output_port in outputs:
+            flow.append({
+                "from": model_id,
+                "to": output_port["id"],
+            })
+
+        return flow
+
+    def _extractSAIfetyMonitors(self, inputs, outputs):
+        """Link runtime monitors to known component ports where possible."""
+        port_targets = {}
+        for port in inputs + outputs:
+            port_targets[port["name"]] = port["id"]
+            port_targets[self._toIdentifier(port["name"])] = port["id"]
+
+        monitors = []
+        for monitor_name, monitor_info in self.runtime_monitors.items():
+            if monitor_info["observes"]:
+                for observed_property in monitor_info["observes"]:
+                    feature = observed_property.get("feature") or observed_property.get("name") or monitor_name
+                    monitors.append({
+                        "name": feature,
+                        "monitor": monitor_name,
+                        "target": self._resolveSAIfetyMonitorTarget(feature, port_targets),
+                        "expression": self._buildSAIfetyMonitorExpression(observed_property),
+                    })
+            else:
+                monitors.append({
+                    "name": monitor_name,
+                    "monitor": monitor_name,
+                    "target": "environment",
+                    "expression": None,
+                })
+
+        return monitors
+
+    def _resolveSAIfetyMonitorTarget(self, feature, port_targets):
+        """Resolve a monitor target to an input/output id when names match."""
+        if feature in port_targets:
+            return port_targets[feature]
+
+        feature_id = self._toIdentifier(feature)
+        if feature_id in port_targets:
+            return port_targets[feature_id]
+
+        return "environment"
+
+    def _buildSAIfetyMonitorExpression(self, observed_property):
+        """Build a readable monitor expression from observed property metadata."""
+        feature = observed_property.get("feature") or observed_property.get("name") or "value"
+        property_type = observed_property.get("type")
+        value = observed_property.get("value") or {}
+
+        if property_type == "property_range":
+            min_value = value.get("_valueMin")
+            max_value = value.get("_valueMax")
+            return str(min_value) + " <= " + feature + " <= " + str(max_value)
+
+        if property_type == "property_min":
+            return feature + " >= " + str(value.get("_valueMin"))
+
+        if property_type == "property_max":
+            return feature + " <= " + str(value.get("_valueMax"))
+
+        if property_type == "property_mean":
+            average = value.get("_average")
+            deviation = value.get("_deviation")
+            if average is not None and deviation is not None:
+                return str(average - deviation) + " <= " + feature + " <= " + str(average + deviation)
+
+        return None
+
+    def _getSAIfetyArchitecturePath(self):
+        """Return the output path for the generated SAIfety architecture."""
+        if self._operational_path is not None:
+            return self._operational_path.parents[1] / "SAIfetyArchitecture.json"
+
+        return self.path_to_vf / "SAIfetyArchitecture.json"
+
+    def _getTraceabilityGraphPath(self):
+        """Return the output path for the generated traceability graph."""
+        if self._metadata_path is not None:
+            return self._metadata_path.parents[1] / "TraceabilityGraph.json"
+
+        return self.path_to_vf / "TraceabilityGraph.json"
+
+    def _toIdentifier(self, value):
+        """Convert names from Operational.json into stable JSON ids."""
+        identifier = []
+        for character in str(value).strip():
+            if character.isalnum():
+                identifier.append(character.lower())
+            else:
+                identifier.append("_")
+
+        compact_identifier = "_".join(part for part in "".join(identifier).split("_") if part)
+        return compact_identifier or "unnamed"
+
+    def _findOperationalFile(self):
+        """Find the Operational.json file in the loaded validity frame."""
+        operational_path = self.path_to_vf / "Operational" / "Operational.json"
+        if operational_path.is_file():
+            return operational_path
+
+        operational_files = list(self.path_to_vf.glob("*/Operational/Operational.json"))
+        if len(operational_files) == 1:
+            return operational_files[0]
+
+        if not operational_files:
+            raise FileNotFoundError("Operational.json not found in validity frame: " + str(self.path_to_vf))
+
+        raise ValueError("Multiple Operational.json files found in validity frame: " + str(self.path_to_vf))
+
+    def _findMetadataFile(self):
+        """Find the Metadata.json file in the loaded validity frame."""
+        metadata_path = self.path_to_vf / "Metadata" / "Metadata.json"
+        if metadata_path.is_file():
+            return metadata_path
+
+        metadata_files = list(self.path_to_vf.glob("*/Metadata/Metadata.json"))
+        if len(metadata_files) == 1:
+            return metadata_files[0]
+
+        if not metadata_files:
+            raise FileNotFoundError("Metadata.json not found in validity frame: " + str(self.path_to_vf))
+
+        raise ValueError("Multiple Metadata.json files found in validity frame: " + str(self.path_to_vf))
+
+    def _extractRuntimeMonitorInfo(self, monitor_definition):
+        """Extract the runtime monitor metadata used for flexIA translation."""
+        monitor_name = monitor_definition.get("_name")
+        if not monitor_name:
+            raise ValueError("Runtime monitor without '_name' found in Operational.json")
+
+        observes = []
+        for observed_property in monitor_definition.get("observes", []):
+            observes.append({
+                "name": observed_property.get("_name"),
+                "description": observed_property.get("_description"),
+                "guid": observed_property.get("_GUID"),
+                "feature": observed_property.get("_feature"),
+                "status": observed_property.get("_status"),
+                "type": observed_property.get("_type"),
+                "value": observed_property.get("_value"),
+            })
+
+        return {
+            "name": monitor_name,
+            "description": monitor_definition.get("_description"),
+            "guid": monitor_definition.get("_GUID"),
+            "timestamp": monitor_definition.get("_timestamp"),
+            "status": monitor_definition.get("_status"),
+            "type": monitor_definition.get("_type"),
+            "validate_point_function": monitor_definition.get("_validate_point_function"),
+            "package_name": monitor_definition.get("_packageName"),
+            "observes": observes,
+            "spec_status": monitor_definition.get("spec_status", {}),
+            "last_observed_values": monitor_definition.get("last_observed_values", {}),
+            "parent": monitor_definition.get("parent"),
+            "source": monitor_definition,
+        }
+
+    def _logRuntimeMonitorSummary(self, operational_path):
+        """Print a compact summary of the loaded runtime monitors."""
+        self._log(
+            "info",
+            "Loaded " + str(len(self.runtime_monitors)) +
+            " runtime monitor(s) from " + str(operational_path),
+        )
+
+        for monitor_name, monitor_info in self.runtime_monitors.items():
+            observed_features = []
+            for observed_property in monitor_info["observes"]:
+                feature = observed_property.get("feature") or "<unnamed>"
+                property_type = observed_property.get("type") or "<unknown>"
+                observed_features.append(feature + " (" + property_type + ")")
+
+            if observed_features:
+                observes_summary = ", ".join(observed_features)
+            else:
+                observes_summary = "no observed properties"
+
+            self._log(
+                "info",
+                "  - " + monitor_name +
+                " [" + str(monitor_info.get("type")) + "] " +
+                "status=" + str(monitor_info.get("status")) +
+                ", observes: " + observes_summary,
+            )
+
+    def _registerRuntime(self):
+        """Register loaded runtime monitors."""
+        # TODO: register runtime monitors with the owning runtime/node.
+        return True
+
+    def _setRuntimeMonitor(self, runtimeMonitorName, value):
+        """Set a runtime monitor value."""
+        if runtimeMonitorName not in self.runtime_monitors:
+            self._log("warning", "Runtime monitor not found: " + str(runtimeMonitorName))
+            return False
+
+        monitor = self.runtime_monitors[runtimeMonitorName]
+        if not hasattr(monitor, "set"):
+            self._log("warning", "Runtime monitor is not translated to a flexIA runtime monitor yet: " + str(runtimeMonitorName))
+            return False
+
+        monitor.set(value)
+        return True
+
+    def _resolveValidityFramePath(self, path_to_fmu):
+        """Return the VF folder path, unpacking .vf archives when needed."""
+        vf_path = Path(path_to_fmu)
+        if vf_path.is_dir():
+            return vf_path
+
+        if vf_path.is_file() and vf_path.suffix == ".vf":
+            return self._unpackValidityFrame(vf_path)
+
+        raise ValueError("Validity frame must be a folder or a .vf archive: " + str(path_to_fmu))
+
+    def _unpackValidityFrame(self, vf_archive):
+        """Unpack a zipped .vf archive and return the unpacked folder."""
+        if not zipfile.is_zipfile(vf_archive):
+            raise ValueError("Validity frame archive is not a valid zip file: " + str(vf_archive))
+
+        self._temp_dir = tempfile.TemporaryDirectory(prefix="validity_frame_")
+        unpack_dir = Path(self._temp_dir.name) / vf_archive.stem
+        unpack_dir.mkdir(parents=True, exist_ok=True)
+
+        with zipfile.ZipFile(vf_archive, "r") as archive:
+            for member in archive.infolist():
+                member_path = unpack_dir / member.filename
+                if not member_path.resolve().is_relative_to(unpack_dir.resolve()):
+                    raise ValueError("Unsafe path found in validity frame archive: " + member.filename)
+            archive.extractall(unpack_dir)
+
+        self._unpacked_vf_dir = unpack_dir
+        self._log("info", "Unpacked validity frame archive to: " + str(unpack_dir))
+        return unpack_dir