import logging
import os
from datetime import datetime, timezone


def setup_logging(debug: bool = False) -> None:
    level = logging.DEBUG if debug else logging.INFO
    logging.basicConfig(level=level, format='%(asctime)s %(levelname)s %(name)s: %(message)s')


def save_debug_artifact(filename: str, content: str | bytes) -> str:
    debug_dir = "debug"
    os.makedirs(debug_dir, exist_ok=True)
    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    path = os.path.join(debug_dir, f"{timestamp}_{filename}")
    mode = 'wb' if isinstance(content, (bytes, bytearray)) else 'w'
    with open(path, mode) as f:
        f.write(content)  # type: ignore[arg-type]
    return path