from typing import Dict, Any
import json
from pathlib import Path


def open_metadata(path: str, filename: str = "metadata.json") -> Dict[str, Any]:
    """
    Open metadata file and return its contents as a dictionary.

    Args:
        path: The directory path where the metadata file is located.
        filename: The name of the metadata file (default: "metadata.json").

    Returns:
        A dictionary containing the metadata.
    """
    with open(Path(path) / filename, 'r', encoding='utf-8') as f:
        try:
            return json.load(f)
        except json.JSONDecodeError as e:
            raise ValueError(f"Error decoding JSON from {filename}: {e}")
        except FileNotFoundError:
            raise FileNotFoundError(f"Metadata file {filename} not found in {path}")
        except Exception as e:
            raise RuntimeError(f"Unexpected error reading metadata: {e}")


def merge_metadata(
    base_metadata: Dict[str, Any],
    additional_metadata: Dict[str, Any]
) -> Dict[str, Any]:
    """
    Merge two metadata dictionaries.

    Args:
        base_metadata: The base metadata dictionary.
        additional_metadata: The additional metadata dictionary to merge.

    Returns:
        A new dictionary containing the merged metadata.
    """
    merged = base_metadata.copy()
    for key, value in additional_metadata.items():
        merged[key] = value
    return merged