"""Relative path layout under ``prompt_media_upload_root``.

Layout::

    <root>/<workspace_id>/<project_id>/<filename>
    <root>/<workspace_id>/<project_id>/<session_id>/<filename>   # when chat/session is provided

``workspace_id`` is the tenant; ``project_id`` scopes the project; ``session_id`` is the
prompt chat session (optional).
"""
from __future__ import annotations
from typing import Optional
from uuid import UUID


def build_storage_relative_path(
    workspace_id: UUID,
    project_id: UUID,
    storage_filename: str,
    *,
    session_id: Optional[UUID] = None,
) -> str:
    """Return POSIX-style path segments under the upload root (no leading slash)."""
    w, p = str(workspace_id), str(project_id)
    fn = storage_filename.replace("\\", "/").lstrip("/")
    if session_id:
        return f"{w}/{p}/{session_id}/{fn}"
    return f"{w}/{p}/{fn}"