backend/app/utils.py

"""
utils.py — small project-wide utility functions.
"""

from datetime import datetime


def job_folder_name(job_id: str, created_at: datetime) -> str:
    """Convert a UUID job_id + creation datetime to a human-readable folder name.

    Format:  {YYYY-MM-DD}_{HHMMSS}_{first 4 hex chars of UUID}
    Example: "2026-06-20_153045_fc1f"  for job_id "fc1f461f-a0b0-4396-..."

    Why this format?
    - Date + time prefix makes folders sort chronologically in any file browser.
    - 4-char UUID suffix distinguishes same-second creations (65 536 possibilities
      per second — negligible collision risk for a single-user local tool).
    - job_id[:4] is always hex because UUIDs start with hex digits before the
      first dash (e.g. "fc1f" from "fc1f461f-...").

    Recomputing from immutable inputs
    ----------------------------------
    Both job_id and created_at are fixed at job-creation time and never change,
    so calling this function again later (e.g. in generate.py) always yields
    the identical string — no need to store the folder name separately.
    """
    return f"{created_at:%Y-%m-%d}_{created_at:%H%M%S}_{job_id[:4]}"