accessibilityamodal/category_overrides.py

"""Apply human-reviewed accessibility category overrides by sample id."""

from __future__ import annotations

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


PROJECT_ROOT = Path(__file__).resolve().parents[1]
DEFAULT_CATEGORY_OVERRIDES_PATH = PROJECT_ROOT / "configs" / "accessibility_review_overrides.json"
GEOMETRY_REVIEW_REQUIRED_CATEGORIES = frozenset(
    {"stairs", "ramp", "curb_cut", "raised_curb"}
)


def load_reviewed_category_overrides(
    path: str | Path | None = None,
) -> dict[str, dict[str, Any]]:
    source = DEFAULT_CATEGORY_OVERRIDES_PATH if path is None else Path(path)
    if not source.is_absolute():
        source = PROJECT_ROOT / source
    if not source.is_file():
        return {}
    value = json.loads(source.read_text(encoding="utf-8"))
    if not isinstance(value, dict):
        raise ValueError(f"Category override config must contain an object: {source}")
    return {
        str(sample_id): entry
        for sample_id, entry in value.items()
        if isinstance(entry, dict)
    }


def resolve_reviewed_category(
    sample_id: str,
    fallback_category: str,
    overrides: Mapping[str, Mapping[str, Any]],
) -> str:
    fallback_category = str(fallback_category or "").strip().lower()
    entry = overrides.get(sample_id)
    if not entry or entry.get("category_reviewed") is not True:
        return fallback_category
    category = entry.get("category")
    if not isinstance(category, str) or not category.strip():
        raise ValueError(
            f"Reviewed category override for {sample_id!r} must contain a non-empty category"
        )
    return category.strip().lower()


def geometry_category_is_explicitly_reviewed(
    sample_id: str,
    metadata: Mapping[str, Any] | None,
    overrides: Mapping[str, Mapping[str, Any]],
) -> bool:
    """Return whether the geometry-driving category itself was reviewed."""
    if metadata and metadata.get("category_reviewed") is True:
        return True
    override = overrides.get(sample_id)
    return bool(override and override.get("category_reviewed") is True)


def resolve_geometry_category_for_modeling(
    sample_id: str,
    fallback_category: str,
    metadata: Mapping[str, Any] | None,
    overrides: Mapping[str, Mapping[str, Any]],
    *,
    allow_unreviewed_level_change: bool = False,
) -> str:
    """Resolve category and fail closed for unreviewed level-change geometry."""
    category = resolve_reviewed_category(sample_id, fallback_category, overrides)
    if not category:
        raise ValueError(f"Sample {sample_id!r} has no category for 3D geometry routing")
    if (
        not allow_unreviewed_level_change
        and category in GEOMETRY_REVIEW_REQUIRED_CATEGORIES
        and not geometry_category_is_explicitly_reviewed(sample_id, metadata, overrides)
    ):
        raise ValueError(
            f"Sample {sample_id!r} category {category!r} requires explicit category review "
            "before selecting a 3D geometry prior. Run "
            "tools/audit_accessibility_geometry_categories.py or add a reviewed override."
        )
    return category