fameio 3.4.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

fameio/output/metadata/compiler.py

@@ -0,0 +1,75 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Compiling metadata files accompanying the output CSV files."""
+
+from __future__ import annotations
+
+import ast
+from typing import Final, Any
+
+from fameprotobuf.input_file_pb2 import InputData
+
+from fameio.input.metadata import Metadata
+from fameio.logs import log_error, log
+from fameio.output.metadata import MetadataCompilationError
+from fameio.output.metadata.locator import Locator
+from fameio.tools import keys_to_lower
+
+
+class MetadataCompiler(Locator):
+    """Compiles metadata for output files based on ExecutionData and InputData."""
+
+    ENTRY_SCHEMA: Final[str] = "Schema".lower()
+    ENTRY_SCENARIO: Final[str] = "Scenario".lower()
+    ENTRY_EXECUTION: Final[str] = "Execution".lower()
+    SEPARATOR: Final[str] = ":"
+
+    _ERR_MALFORMED_DICT_STRING = "Input data reading failed: Malformed string representation of metadata dictionaries."
+    _INFO_NOT_FOUND = "Could not find element at '{}' in input section of provided file."
+
+    def __init__(
+        self, execution_data: dict[str, Any], input_data: InputData, agent_columns: dict[str, list[str]]
+    ) -> None:
+        """Initialises a new MetadataCompiler.
+
+        Args:
+            execution_data: to read execution metadata from
+            input_data: to read schema and scenario metadata from
+            agent_columns: agents and their output columns
+        """
+        super().__init__(agent_columns)
+        try:
+            self._data: dict[str, dict] = {
+                self.ENTRY_SCHEMA: ast.literal_eval(input_data.schema),
+                self.ENTRY_SCENARIO: {
+                    Metadata.KEY_METADATA: ast.literal_eval(input_data.metadata) if input_data.metadata else {}
+                },
+                self.ENTRY_EXECUTION: execution_data,
+            }
+        except (ValueError, TypeError, SyntaxError, MemoryError, RecursionError) as e:
+            raise log_error(MetadataCompilationError(self._ERR_MALFORMED_DICT_STRING)) from e
+
+    def _replace(self, data_identifier: str) -> Any | None:
+        identifier = data_identifier[1:-1]
+        address = identifier.split(self.SEPARATOR)
+        data_source = address[0].lower()
+        try:
+            if data_source in self._data:
+                return self._get_from(self._data[data_source], address[1:])
+        except KeyError:
+            log().info(self._INFO_NOT_FOUND.format(self.SEPARATOR.join(address)))
+            return None
+        return None
+
+    @staticmethod
+    def _get_from(base: dict, address: list[str]) -> Any:
+        """Returns element in `base` at given `address`.
+
+        Raises:
+            KeyError: if element cannot be found; error not logged
+        """
+        element = base
+        for entry in address:
+            element = keys_to_lower(element)[entry.lower()]
+        return element

fameio/output/metadata/json_writer.py

@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Writing of data to JSON files."""
+
+import json
+from pathlib import Path
+
+from fameio.logs import log, log_error
+from fameio.output import OutputError
+
+METADATA_FILE_NAME = "metadata.json"
+
+_ERR_OPEN_FILE = "Could not open file for writing: '{}'"
+_INFO_DESTINATION = "Saving JSON to file to {}"
+
+
+class JsonWriterError(OutputError):
+    """An error occurred during writing a JSON file."""
+
+
+def data_to_json_file(data: dict, base_path: Path) -> None:
+    """Save the given data to a JSON file at given path.
+
+    Args:
+        data: to be saved to JSON file
+        base_path: at which the JSON file will be created
+
+    Raises:
+        JsonWriterError: if file could not be opened or written, logged with level "ERROR"
+    """
+    log().info(_INFO_DESTINATION.format(base_path))
+    try:
+        with open(Path(base_path, METADATA_FILE_NAME), "w", encoding="utf-8") as f:
+            json.dump(data, f)
+    except OSError as e:
+        raise log_error(JsonWriterError(_ERR_OPEN_FILE.format(base_path))) from e

fameio/output/metadata/locator.py

@@ -0,0 +1,242 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Locating replacement strings in complex template dictionaries."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from typing import Any, Final
+
+from fameio.logs import log_error
+from fameio.output.metadata import MetadataCompilationError
+from fameio.tools import keys_to_lower
+
+
+class Locator(ABC):
+    """Locates replacement strings within a given template and organises their replacement."""
+
+    KEY_BASE: Final[str] = "base".lower()
+    KEY_PER_AGENT: Final[str] = "perAgent".lower()
+    KEY_PER_COLUMN: Final[str] = "perColumn".lower()
+
+    PLACEHOLDER_START: Final[str] = "<"
+    PLACEHOLDER_END: Final[str] = ">"
+    _PLACEHOLDER_PATTERN: Final[re.Pattern] = re.compile(PLACEHOLDER_START + ".*?" + PLACEHOLDER_END)
+
+    KEY_AGENT: Final[str] = "Agent".lower()
+    KEY_COLUMN: Final[str] = "Column".lower()
+
+    ITERATION_START: Final[str] = "{{"
+    ITERATION_END: Final[str] = "}}"
+    _PER_AGENT_PATTERN: Final[str] = ITERATION_START + KEY_PER_AGENT + ITERATION_END
+    _PER_COLUMN_PATTERN: Final[str] = ITERATION_START + KEY_PER_COLUMN + ITERATION_END
+
+    _ESC = "\\"
+    ITERABLE_START: Final[str] = "("
+    ITERABLE_END: Final[str] = ")"
+    _AGENT_PATTERN: Final[re.Pattern] = re.compile(
+        f"{_ESC}{ITERABLE_START}{KEY_AGENT}{_ESC}{ITERABLE_END}", re.IGNORECASE
+    )
+    _COLUMN_PATTERN: Final[re.Pattern] = re.compile(
+        f"{_ESC}{ITERABLE_START}{KEY_COLUMN}{_ESC}{ITERABLE_END}", re.IGNORECASE
+    )
+
+    _ERR_MUST_BE_DICT = "Element '{}' in metadata template must be a dictionary."
+
+    def __init__(self, agent_columns: dict[str, list[str]]) -> None:
+        """Initialise a new Locator.
+
+        Args:
+            agent_columns: agents and their output columns
+        """
+        self._agent_columns: dict = agent_columns
+        self._per_agent_template: dict = {}
+        self._per_column_template: dict = {}
+        self._current_agent: str = ""
+        self._current_column: str = ""
+
+    def locate_and_replace(self, template: dict) -> dict:
+        """Returns copy of given `template` with filled-in metadata to each placeholder - if available.
+
+        Args:
+            template: dict with placeholders to be filled
+
+        Returns:
+            template with filled in placeholders (if any)
+
+        Raises:
+            MetadataCompilationError: if template is ill-formatted, logged with level "ERROR"
+        """
+        template = keys_to_lower(template)
+        per_agent_template = template.get(self.KEY_PER_AGENT, {})
+        self._ensure_is_dict(per_agent_template, self.KEY_PER_AGENT)
+        self._per_agent_template = per_agent_template
+
+        per_column_template = template.get(self.KEY_PER_COLUMN, {})
+        self._ensure_is_dict(per_column_template, self.KEY_PER_COLUMN)
+        self._per_column_template = per_column_template
+
+        self._current_column = ""
+        self._current_agent = ""
+
+        return self._fill_dict(template.get(self.KEY_BASE, {}))
+
+    def _ensure_is_dict(self, item: Any, key: str) -> None:
+        """Raises an error if given `item` is not a dictionary.
+
+        Args:
+            item: to be tested if it is a dictionary
+            key: to be specified in error message
+
+        Raises:
+            MetadataCompilationError: if given `item` is not a dictionary, logged with level "ERROR"
+        """
+        if not isinstance(item, dict):
+            raise log_error(MetadataCompilationError(self._ERR_MUST_BE_DICT.format(key)))
+
+    def _fill_dict(self, template: dict) -> dict:
+        """Fills in metadata to each value of the given dictionary `template`.
+
+        Args:
+            template: dict with placeholders to be filled
+
+        Returns:
+            template with filled in placeholders (if any)
+        """
+        result: dict = {}
+        for key, value in template.items():
+            if isinstance(value, dict):
+                result[key] = self._fill_dict(value)
+            elif isinstance(value, list):
+                result[key] = self._fill_list(value)
+            else:
+                result[key] = self._fill_value(value)
+        return result
+
+    def _fill_list(self, values: list) -> list:
+        """Fills in metadata to each value of the given `values` list.
+
+        Args:
+            values: list of elements with potential placeholders to be filled
+
+        Returns:
+            values, potentially with filled-in placeholders
+        """
+        result: list = []
+        for value in values:
+            if isinstance(value, dict):
+                result.append(self._fill_dict(value))
+            elif isinstance(value, list):
+                result.append(self._fill_list(value))
+            else:
+                filled_value = self._fill_value(value)
+                if isinstance(filled_value, list):
+                    result.extend(filled_value)
+                else:
+                    result.append(filled_value)
+        return result
+
+    def _fill_value(self, value: str | int | float) -> Any:
+        """Checks for placeholders, iterables, or iteration template markers to replace.
+
+        Returns replacement or original value if replacement cannot be found.
+
+        Args:
+            value: to replace or return if no replacement is needed / available
+
+        Returns:
+            replacement or original value if replacement is not needed / available
+        """
+        if isinstance(value, (int, float)):
+            return value
+        if self._is_agent_replacement(value):
+            value = self._replace_agent(value)
+        if self._is_column_replacement(value):
+            value = self._replace_column(value)
+        if self._has_basic_placeholder(value):
+            return self._replace_all(value)
+        if self._is_per_column(value):
+            return self._per_column()
+        if self._is_per_agent(value):
+            return self._per_agent()
+        return value
+
+    def _has_basic_placeholder(self, value: str) -> bool:
+        """Returns true if given value contains placeholder symbols."""
+        return self.PLACEHOLDER_START in value and self.PLACEHOLDER_END in value
+
+    def _replace_all(self, value: str) -> str | Any:
+        """Replaces all placeholders in given `value` and returns the string with all replacements.
+
+        If the whole string is a single placeholder, replace it completely with the replacement content - of any type.
+        Otherwise, replace the placeholders within the string with the replacement content.
+        """
+        matches = re.findall(self._PLACEHOLDER_PATTERN, value)
+        if len(matches) == 1:
+            if re.fullmatch(self._PLACEHOLDER_PATTERN, value):
+                return self._replace(value)
+        return re.sub(self._PLACEHOLDER_PATTERN, self._callback_wrapper, value)
+
+    @abstractmethod
+    def _replace(self, data_identifier: str) -> Any | None:
+        """Returns replacement for given data identifier, or None if replacement cannot be found.
+
+        Args:
+            data_identifier: locator for the replacement data
+
+        Returns:
+            either the found replacement data (of any type), or None if no data is found
+        """
+
+    def _callback_wrapper(self, match: re.Match) -> str:
+        """Extracts replacement string from given match and calls for its replacement."""
+        return str(self._replace(match.group(0)))
+
+    def _is_agent_replacement(self, value: str) -> bool:
+        """Returns true if given value contains placeholder and agent iterable placeholder."""
+        return re.search(self._AGENT_PATTERN, value) is not None
+
+    def _replace_agent(self, value) -> str:
+        """Replace all occurrences of agent iterable pattern in given string."""
+        return re.sub(self._AGENT_PATTERN, str(self._current_agent), value)
+
+    def _is_column_replacement(self, value: str) -> bool:
+        """Returns true if given value contains placeholder and agent iterable placeholder."""
+        return re.search(self._COLUMN_PATTERN, value) is not None
+
+    def _replace_column(self, value) -> str:
+        """Replace all occurrences of column iterable pattern in given string."""
+        return re.sub(self._COLUMN_PATTERN, str(self._current_column), value)
+
+    def _is_per_column(self, value: str) -> bool:
+        """Returns true if given value is the 'perColumn' section."""
+        return value.strip().lower() == self._PER_COLUMN_PATTERN
+
+    def _per_column(self) -> list:
+        """Returns list of metadata for all columns of current agent."""
+        column_metadata = []
+        if len(self._per_column_template) > 0:
+            for column in self._agent_columns[self._current_agent]:
+                template = self._per_column_template
+                self._current_column = column
+                column_metadata.append(self._fill_dict(template))
+        return column_metadata
+
+    def _is_per_agent(self, value: str) -> bool:
+        """Returns true if given value is the 'perAgent' section."""
+        return value.strip().lower() == self._PER_AGENT_PATTERN
+
+    def _per_agent(self) -> list:
+        """Returns list of metadata for all agents.
+
+        Returns empty list if either the per-agent template is missing, or no agents are registered for output.
+        """
+        agent_metadata = []
+        if len(self._per_agent_template) > 0:
+            for agent in self._agent_columns.keys():
+                template = self._per_agent_template
+                self._current_agent = agent
+                agent_metadata.append(self._fill_dict(template))
+        return agent_metadata

fameio/output/metadata/oeo_template.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+OEO_TEMPLATE = {
+    "base": {
+        "@context": "https://raw.githubusercontent.com/OpenEnergyPlatform/oemetadata/production/oemetadata/latest/context.json",
+        "name": "<schema:metadata:name>_result_metadata",
+        "title": "Results for <schema:metadata:name> run <scenario:metadata:RunId>.",
+        "description": """Input compiled with FAME-Io <execution:InputCompilation:SoftwareVersions:FameIo>.
+        Simulated by FAME-Core <execution:ModelRun:SoftwareVersions:FameCore>.
+        Extracted by FAME-Io <execution:OutputExtraction:SoftwareVersions:FameIo>.""",
+        "resources": ["{{perAgent}}"],
+        "metaMetadata": {
+            "metadataVersion": "OEMetadata-2.0.4",
+            "metadataLicense": {
+                "name": "CC0-1.0",
+                "title": "Creative Commons Zero v1.0 Universal",
+                "path": "https://creativecommons.org/publicdomain/zero/1.0",
+            },
+        },
+    },
+    "perAgent": {
+        "name": "(agent).*.csv",
+        "topics": [],
+        "title": "Results for (agent)",
+        "path": "./(agent).*.csv",
+        "description": "Simulation outputs by simulated time of agent type '(agent)'",
+        "languages": ["en-GB"],
+        "subject": "<schema:AgentTypes:(agent):metadata:subject>",
+        "keywords": "<schema:AgentTypes:(agent):metadata:keywords>",
+        "publicationDate": "<scenario:metadata:output:publicationDate>",
+        "embargoPeriod": "<scenario:metadata:output:embargoPeriod>",
+        "context": {
+            "title": "<schema:metadata:title>",
+            "homepage": "<schema:metadata:homepage>",
+            "documentation": "<schema:metadata:documentation>",
+            "sourceCode": "<schema:metadata:sourceCode>",
+            "publisher": "<schema:metadata:publisher>",
+            "publisherLogo": "<schema:metadata:publisherLogo>",
+            "contact": "<schema:metadata:contact>",
+            "fundingAgency": "<schema:metadata:fundingAgency>",
+            "fundingAgencyLogo": "<schema:metadata:fundingAgencyLogo>",
+            "grantNo": "<schema:metadata:grantNo>",
+        },
+        "spatial": {},
+        "temporal": {},
+        "sources": [],
+        "licenses": "<scenario:metadata:output:licenses>",
+        "contributors": "<schema:metadata:contributors>",
+        "type": "table",
+        "format": "CSV",
+        "encoding": "UTF-8",
+        "schema": {
+            "fields": [
+                {
+                    "name": "AgentId",
+                    "description": "Unique ID of the agent in the simulation",
+                    "type": "integer",
+                    "nullable": False,
+                    "unit": "n/a",
+                    "isAbout": [],
+                    "valueReference": [],
+                },
+                {
+                    "name": "TimeStep",
+                    "description": "Simulated time these values are associated with",
+                    "type": "integer or time stamp",
+                    "nullable": False,
+                    "unit": "n/a",
+                    "isAbout": [
+                        {"name": "TimeStamp", "@id": "https://openenergyplatform.org/ontology/oeo/OEO_00140043"}
+                    ],
+                    "valueReference": [],
+                },
+                "{{perColumn}}",
+            ],
+            "primaryKey": ["AgentId", "TimeStep"],
+            "foreignKeys": [],
+            "dialect": {"delimiter": ";", "decimalSeparator": "."},
+            "review": {},
+        },
+    },
+    "perColumn": {
+        "name": "(column)",
+        "description": "<schema:AgentTypes:(agent):outputs:(column):metadata:description>",
+        "type": "decimal",
+        "nullable": True,
+        "unit": "<schema:AgentTypes:(agent):outputs:(column):metadata:unit>",
+        "isAbout": "<schema:AgentTypes:(agent):outputs:(column):metadata:isAbout>",
+        "valueReference": "<schema:AgentTypes:(agent):outputs:(column):metadata:valueReference>",
+    },
+}

fameio/output/metadata/template_reader.py

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""Reading of metadata templates in YAML or JSON format."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from fameio.input import YamlLoaderError
+from fameio.input.loader import ALLOWED_SUFFIXES as YAML_SUFFIXES, load_yaml
+from fameio.logs import log_error
+from fameio.output.metadata import MetadataCompilationError
+
+JSON_SUFFIX: str = ".json"
+ENCODING = "UTF-8"
+
+_ERR_UNKNOWN_ENDING = "Template file ending '{}' corresponds neither to a JSON or YAML file."
+_ERR_READING_FILE = "Could not read template file: '{}'"
+
+
+def read_template_file(file: Path) -> dict:
+    """Reads and returns metadata template `file` encoded in UTF-8.
+
+    Args:
+        file: to be read
+
+    Returns:
+        dictionary content of the file
+
+    Raises:
+        MetadataCompilationError: if template file has unknown type, could not be opened/read, logged with level "ERROR"
+    """
+    file_ending = file.suffix.lower()
+    if _has_yaml_ending(file_ending) or _has_json_ending(file_ending):
+        return _read_yaml(file)
+    raise log_error(MetadataCompilationError(_ERR_UNKNOWN_ENDING.format(file_ending)))
+
+
+def _has_yaml_ending(file_ending: str) -> bool:
+    """Returns True if `file_ending` corresponds to a YAML file."""
+    return file_ending in YAML_SUFFIXES
+
+
+def _has_json_ending(file_ending: str) -> bool:
+    """Returns True if `file_ending` corresponds to a JSON file."""
+    return file_ending == JSON_SUFFIX
+
+
+def _read_yaml(file: Path) -> dict:
+    """Returns content of the provided yaml file
+
+    Args:
+        file: to be opened and read
+
+    Returns:
+        file content as dict
+
+    Raises:
+        MetadataCompilationError: if file could not be opened or read, logged with level "ERROR"
+    """
+    try:
+        return load_yaml(file, encoding=ENCODING)
+    except YamlLoaderError as e:
+        raise log_error(MetadataCompilationError(_ERR_READING_FILE.format(file))) from e

fameio/output/output_dao.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Accessing output content of protobuf messages."""
+
 from __future__ import annotations
 
 from typing import Iterable

fameio/output/reader.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Reading of protobuf files."""
 from __future__ import annotations
 
 import struct

fameio/output/yaml_writer.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Writing of data to YAML files."""
+
 from pathlib import Path
 
 import yaml
@@ -8,7 +10,7 @@ import yaml
 from fameio.logs import log, log_error
 from fameio.output import OutputError
 
-_ERR_OPEN_FILE = "Could not open file for reading: '{}'"
+_ERR_OPEN_FILE = "Could not open file for writing: '{}'"
 
 _INFO_DESTINATION = "Saving scenario to file at {}"
 

fameio/scripts/__init__.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+"""Main scripts callable from command line."""
 import sys
 
 from fameio.scripts.convert_results import DEFAULT_CONFIG as DEFAULT_CONVERT_CONFIG
@@ -13,6 +14,7 @@ from fameio.cli.reformat import handle_args as handle_reformat_args
 
 # noinspection PyPep8Naming
 def makeFameRunConfig():
+    """Compiles FAME simulation input files in protobuf format."""
     cli_config = handle_make_config_args(sys.argv[1:])
     try:
         make_config(cli_config)
@@ -22,6 +24,7 @@ def makeFameRunConfig():
 
 # noinspection PyPep8Naming
 def convertFameResults():
+    """Converts a protobuf file to human-readable outputs."""
     cli_config = handle_convert_results_args(sys.argv[1:], DEFAULT_CONVERT_CONFIG)
     try:
         convert_results(cli_config)
@@ -31,6 +34,7 @@ def convertFameResults():
 
 # noinspection PyPep8Naming
 def reformatTimeSeries():
+    """Reformats a timeseries file to speed up its future usage in scenarios."""
     cli_config = handle_reformat_args(sys.argv[1:])
     try:
         reformat(cli_config)

fameio/scripts/convert_results.py

@@ -19,6 +19,10 @@ from fameio.output.csv_writer import CsvWriter
 from fameio.output.data_transformer import DataTransformer, INDEX
 from fameio.output.execution_dao import ExecutionDao
 from fameio.output.input_dao import InputDao
+from fameio.output.metadata.compiler import MetadataCompiler
+from fameio.output.metadata.json_writer import data_to_json_file
+from fameio.output.metadata.oeo_template import OEO_TEMPLATE
+from fameio.output.metadata.template_reader import read_template_file
 from fameio.output.output_dao import OutputDAO
 from fameio.output.reader import Reader
 from fameio.output.yaml_writer import data_to_yaml_file
@@ -73,7 +77,7 @@ def _extract_and_convert_data(config: dict[Options, Any], file_stream: BinaryIO,
     execution_dao = ExecutionDao()
     while data_storages := reader.read():
         execution_dao.store_execution_metadata(data_storages)
-        if config[Options.INPUT_RECOVERY]:
+        if config[Options.INPUT_RECOVERY] or config[Options.METADATA]:
             input_dao.store_inputs(data_storages)
         output = OutputDAO(data_storages, agent_type_log)
         for agent_name in output.get_sorted_agents_to_extract():
@@ -95,6 +99,8 @@ def _extract_and_convert_data(config: dict[Options, Any], file_stream: BinaryIO,
             log().warning(_WARN_OUTPUT_SUPPRESSED.format(agent_type_log.get_agents_with_output()))
         else:
             log().warning(_WARN_OUTPUT_MISSING)
+    elif config[Options.METADATA]:
+        write_metadata(config, input_dao, execution_dao, agent_type_log)
     log().info("Data conversion completed.")
 
 
@@ -143,8 +149,35 @@ def _memory_saving_apply_conversions(config: dict[Options, Any], output_writer:
         output_writer.write_to_files(agent_name, parsed_data)
 
 
+def write_metadata(
+    config: dict[Options, Any], input_dao: InputDao, execution_dao: ExecutionDao, agent_type_log: AgentTypeLog
+):
+    """Reads metadata templates, fills in available metadata, and writes output to a JSON file.
+
+    Args:
+        config: to determined metadata template, and output path
+        input_dao: contains input data
+        execution_dao: contains execution metadata
+        agent_type_log: contains log about which agent output was created
+
+    Raises:
+        OutputError: in case templates could not be read or filled-in, or JSON writing failed, logged with level "ERROR"
+    """
+    compiler = MetadataCompiler(
+        input_data=input_dao.get_input_data(),
+        execution_data=execution_dao.get_metadata_dict(),
+        agent_columns=agent_type_log.get_agent_columns(),
+    )
+
+    template_file = config[Options.METADATA_TEMPLATE]
+    template = OEO_TEMPLATE if template_file is None else read_template_file(template_file)
+    metadata = compiler.locate_and_replace(template)
+    base_path = config[Options.OUTPUT] if config[Options.OUTPUT] is not None else Path(".")
+    data_to_json_file(metadata, base_path)
+
+
 def run(config: dict[Options, Any] | None = None) -> None:
-    """Reads configured file in protobuf format and extracts its content to .CSV and .YAML file(s).
+    """Reads configured file in protobuf format and extracts its content to CSV and YAML file(s).
 
     Args:
         config: script configuration options

fameio/scripts/exception.py

@@ -1,6 +1,7 @@
 # SPDX-FileCopyrightText: 2025 German Aerospace Center <fame@dlr.de>
 #
 # SPDX-License-Identifier: Apache-2.0
+"""Defines exceptions on the script level."""
 
 
 class ScriptError(Exception):