axis_naming.py

"""
axis_naming.py — Canonical Axis product naming decoder.

Shared between NERVE and AxisX. One source of truth for Axis model name semantics.
Never duplicate this logic — always import from here.

Usage:
    from axis_naming import decode_model, nl_to_naming_filters

    naming = decode_model("P3268-SLVE")
    # {'product_line': 'P', 'product_line_name': 'Professional',
    #  'form_factor': 'Fixed dome', 'extensions': ['S','L','V','E'],
    #  'is_outdoor': True, 'is_vandal_resistant': True, ...}
"""

import re
from typing import Optional


# ---------------------------------------------------------------------------
# Product line definitions
# ---------------------------------------------------------------------------

PRODUCT_LINE_NAMES: dict[str, str] = {
    "P": "Professional",
    "M": "Affordable, intuitive video",
    "Q": "High performance",
    "F": "Discreet surveillance",
    "C": "Companion cameras",
    "V": "Radar and visual",
    "D": "Audio",
    "A": "Access control",
    "I": "Intercom",
    "W": "Body-worn cameras",
    "T": "Accessories",
    "S": "Recorders and storage",
    "X": "Specialty",
    "TQ": "Accessories",
    "TU": "Accessories",
    "XC": "Explosion-protected",
    "XF": "Specialty",
}

# ---------------------------------------------------------------------------
# Extension definitions
# ---------------------------------------------------------------------------

# Multi-character extensions (checked before single-char iteration)
MULTI_EXTENSION_MAP: dict[str, tuple[str, Optional[str]]] = {
    "ATEX": ("Explosion-protected (ATEX)", "is_explosion_protected"),
    "XP": ("Explosion-protected", "is_explosion_protected"),
    "LR": ("Long-range IR", "has_led"),
}

# Single-character extensions: suffix char -> (display_name, boolean_flag_field | None)
SINGLE_EXTENSION_MAP: dict[str, tuple[str, Optional[str]]] = {
    "E": ("Outdoor-ready", "is_outdoor"),
    "V": ("Vandal-resistant", "is_vandal_resistant"),
    "L": ("LED illumination", "has_led"),
    "S": ("Stainless steel", "is_stainless"),
    "W": ("Wireless", "is_wireless"),
    "H": ("Heater", None),
    "T": ("Thermal", None),
    "R": ("Recessed", None),
    "B": ("Built-in audio", None),
}

# ---------------------------------------------------------------------------
# Form factor by series + 2-digit model prefix  (e.g. "P32" -> "Fixed dome")
# ---------------------------------------------------------------------------

FORM_FACTOR_MAP: dict[str, str] = {
    # P-series
    "P32": "Fixed dome",
    "P33": "PTZ dome",
    "P34": "Fixed dome",
    "P37": "Panoramic",
    "P38": "Fixed box",
    "P42": "Fixed dome",
    "P43": "Fixed dome",
    "P55": "PTZ",
    "P56": "PTZ",
    "P57": "PTZ",
    "P58": "PTZ",
    "P92": "Thermal",
    "P93": "Thermal",
    # M-series
    "M20": "Fixed minidome",
    "M30": "Fixed dome",
    "M31": "Fixed dome",
    "M32": "Fixed dome",
    "M33": "Fixed cube",
    "M34": "Vandal dome",
    "M40": "Fixed box",
    "M41": "Fixed box",
    "M42": "Fixed dome",
    "M43": "Fixed dome",
    "M44": "Fixed dome",
    "M50": "PTZ dome",
    "M53": "Mini PTZ",
    "M57": "Fixed fisheye",
    "M70": "Fixed box",
    "M71": "Video encoder",
    # Q-series
    "Q35": "Fixed dome",
    "Q36": "Panoramic",
    "Q37": "Panoramic",
    "Q60": "PTZ",
    "Q61": "PTZ",
    "Q62": "PTZ",
    "Q63": "PTZ",
    "Q64": "PTZ",
    "Q65": "PTZ",
    "Q70": "Fixed box",
    "Q82": "Thermal",
    "Q86": "Thermal",
    "Q87": "Thermal",
    # F-series (discreet/covert)
    "F10": "Pinhole camera",
    "F40": "Fixed fisheye",
    "F90": "Modular pinhole",
    "F92": "Modular pinhole",
    # C-series
    "C10": "Companion dome",
    # V-series
    "V54": "Radar",
    "V56": "Radar",
    # D-series (audio)
    "D10": "Speaker",
    "D20": "Speaker",
    "D40": "Speaker",
    "D42": "Speaker",
    "D43": "Speaker",
    # W-series
    "W10": "Body-worn camera",
    "W20": "Body-worn camera",
    "W40": "Body-worn camera",
    # A-series (access control)
    "A10": "Access controller",
    "A12": "Access controller",
    "A16": "Access controller",
    "A17": "Access controller",
    "A18": "Access controller",
    "A40": "Access controller",
    "A41": "Access controller",
    "A46": "Access controller",
    "A82": "Access controller",
    "A91": "Intercom",
    # I-series
    "I84": "Intercom",
    "I91": "Intercom",
    # S-series (recorders)
    "S10": "Network recorder",
    "S11": "Network recorder",
    "S12": "Network recorder",
    "S13": "Network recorder",
    "S22": "Network recorder",
    "S30": "Network recorder",
    "S31": "Network recorder",
    "S32": "Network recorder",
    "S33": "Network recorder",
    "S34": "Network recorder",
    "S35": "Network recorder",
    "S92": "Network recorder",
}

SERIES_FORM_FACTOR_FALLBACK: dict[str, str] = {
    "D": "Speaker/audio",
    "A": "Access controller",
    "I": "Intercom",
    "W": "Body-worn camera",
    "T": "Accessory",
    "TQ": "Accessory",
    "TU": "Accessory",
    "S": "Recorder",
    "X": "Specialty",
    "XC": "Explosion-protected camera",
    "XF": "Specialty",
}

# ---------------------------------------------------------------------------
# Resolution lookup: series+4digits -> (resolution_name, resolution_pixels)
# Best-effort for known camera families; returns (None, None) when unknown.
# ---------------------------------------------------------------------------

RESOLUTION_MAP: dict[str, tuple[str, str]] = {
    # P-series
    "P3245": ("HDTV 1080/2MP", "1920×1080"),
    "P3248": ("HDTV 1080/2MP", "1920×1080"),
    "P3265": ("HDTV 1080/2MP", "1920×1080"),
    "P3268": ("4K/8MP", "3840×2160"),
    "P3307": ("HDTV 720/1MP", "1280×720"),
    "P3364": ("HDTV 1080/2MP", "1920×1080"),
    "P3365": ("HDTV 1080/2MP", "1920×1080"),
    "P3707": ("5MP", "2560×1920"),
    "P3735": ("5MP", "2592×1944"),
    "P3738": ("5MP", "2592×1944"),
    "P3807": ("20MP", "5120×3840"),
    "P3905": ("HDTV 1080/2MP", "1920×1080"),
    "P3915": ("HDTV 1080/2MP", "1920×1080"),
    "P3925": ("HDTV 1080/2MP", "1920×1080"),
    "P3935": ("HDTV 1080/2MP", "1920×1080"),
    "P4705": ("4K/8MP", "3840×2160"),
    "P4707": ("4K/8MP", "3840×2160"),
    # M-series
    "M3044": ("VGA", "640×480"),
    "M3045": ("HDTV 720/1MP", "1280×720"),
    "M3046": ("HDTV 1080/2MP", "1920×1080"),
    "M3057": ("6MP", "3072×2048"),
    "M3058": ("4K/8MP", "3840×2160"),
    "M3064": ("1.3MP", "1280×960"),
    "M3065": ("HDTV 1080/2MP", "1920×1080"),
    "M3066": ("4MP", "2688×1520"),
    "M3067": ("6MP", "3072×2048"),
    "M3068": ("4K/8MP", "3840×2160"),
    "M3085": ("HDTV 1080/2MP", "1920×1080"),
    "M3086": ("4K/8MP", "3840×2160"),
    "M3088": ("4K/8MP", "3840×2160"),
    "M3106": ("1.3MP", "1280×960"),
    "M3116": ("HDTV 1080/2MP", "1920×1080"),
    "M3227": ("4MP", "2688×1520"),
    "M3228": ("4MP", "2688×1520"),
    "M3307": ("HDTV 720/1MP", "1280×720"),
    "M3308": ("HDTV 1080/2MP", "1920×1080"),
    "M4025": ("HDTV 1080/2MP", "1920×1080"),
    "M4026": ("HDTV 1080/2MP", "1920×1080"),
    "M4075": ("5MP", "2560×1920"),
    "M4076": ("5MP", "2560×1920"),
    "M4205": ("HDTV 1080/2MP", "1920×1080"),
    "M4206": ("HDTV 1080/2MP", "1920×1080"),
    "M4215": ("HDTV 1080/2MP", "1920×1080"),
    "M4216": ("HDTV 1080/2MP", "1920×1080"),
    "M4225": ("HDTV 1080/2MP", "1920×1080"),
    "M4226": ("HDTV 1080/2MP", "1920×1080"),
    "M4308": ("4K/8MP", "3840×2160"),
    # Q-series
    "Q3515": ("HDTV 1080/2MP", "1920×1080"),
    "Q3517": ("5MP", "2592×1944"),
    "Q3536": ("4MP", "2688×1520"),
    "Q3538": ("4MP", "2688×1520"),
    "Q3615": ("HDTV 1080/2MP", "1920×1080"),
    "Q3617": ("5MP", "2592×1944"),
    "Q3626": ("4MP", "2688×1520"),
    "Q3628": ("4MP", "2688×1520"),
    "Q6034": ("HDTV 720/1MP", "1280×720"),
    "Q6035": ("HDTV 1080/2MP", "1920×1080"),
    "Q6045": ("HDTV 1080/2MP", "1920×1080"),
    "Q6055": ("HDTV 1080/2MP", "1920×1080"),
    "Q6074": ("HDTV 1080/2MP", "1920×1080"),
    "Q6075": ("HDTV 1080/2MP", "1920×1080"),
    "Q6100": ("5MP", "2592×1944"),
    "Q6135": ("HDTV 1080/2MP", "1920×1080"),
}


# ---------------------------------------------------------------------------
# Parsing helpers
# ---------------------------------------------------------------------------

def _parse_model_string(model_short: str) -> tuple[str, str, str]:
    """
    Parse model string into (series, model_number, suffix).

    'P3268-SLVE' -> ('P',  '3268', 'SLVE')
    'M4225-LVE'  -> ('M',  '4225', 'LVE')
    'TQ3601-E'   -> ('TQ', '3601', 'E')
    'W102'       -> ('W',  '102',  '')
    'A1210-B'    -> ('A',  '1210', 'B')
    """
    upper = model_short.upper().strip()

    # Two-letter series prefixes (TQ, TU, XC, XF, XP)
    m = re.match(r"^(TQ|TU|XC|XF|XP)(\d+[A-Z]?\d*)(?:-([A-Z0-9]+))?$", upper)
    if m:
        return m.group(1), m.group(2), m.group(3) or ""

    # Single-letter series prefix
    m = re.match(r"^([A-Z])(\d+[A-Z]?\d*)(?:-([A-Z0-9]+))?$", upper)
    if m:
        return m.group(1), m.group(2), m.group(3) or ""

    # Fallback
    if upper and upper[0].isalpha():
        return upper[0], upper[1:], ""
    return "", model_short, ""


def _decode_extensions(suffix: str) -> tuple[list[str], list[str], dict[str, bool]]:
    """
    Decode suffix string into extension codes, display names, and boolean flags.

    'SLVE' -> (['S','L','V','E'],
               ['Stainless steel','LED illumination','Vandal-resistant','Outdoor-ready'],
               {'is_outdoor': True, 'is_vandal_resistant': True, ...})
    """
    flags: dict[str, bool] = {
        "is_outdoor": False,
        "is_vandal_resistant": False,
        "has_led": False,
        "is_rugged": False,
        "is_stainless": False,
        "is_wireless": False,
        "is_explosion_protected": False,
        "is_panoramic": False,
    }
    extensions: list[str] = []
    extension_names: list[str] = []

    if not suffix:
        return extensions, extension_names, flags

    remaining = suffix.upper()

    # Multi-char patterns first (longest first)
    for token in ("ATEX", "XP", "LR"):
        if token in remaining:
            display, flag_field = MULTI_EXTENSION_MAP[token]
            extensions.append(token)
            extension_names.append(display)
            if flag_field:
                flags[flag_field] = True
            remaining = remaining.replace(token, "", 1)

    # Single-char extensions
    for char in remaining:
        if char in SINGLE_EXTENSION_MAP:
            display, flag_field = SINGLE_EXTENSION_MAP[char]
            extensions.append(char)
            extension_names.append(display)
            if flag_field:
                flags[flag_field] = True

    return extensions, extension_names, flags


def _lookup_form_factor(series: str, model_number: str) -> str:
    """Look up form factor from series and model number prefix."""
    digits_prefix = re.match(r"(\d{2})", model_number)
    if digits_prefix:
        key = series + digits_prefix.group(1)
        if key in FORM_FACTOR_MAP:
            return FORM_FACTOR_MAP[key]
    return SERIES_FORM_FACTOR_FALLBACK.get(series, "Unknown")


def _lookup_resolution(
    series: str, model_number: str
) -> tuple[Optional[str], Optional[str]]:
    """Look up resolution name and pixel string. Returns (None, None) when unknown."""
    digits = re.match(r"(\d{4})", model_number)
    if digits:
        key = series + digits.group(1)
        if key in RESOLUTION_MAP:
            return RESOLUTION_MAP[key]
    return None, None


# ---------------------------------------------------------------------------
# Public API
# ---------------------------------------------------------------------------

def decode_model(model_short: str) -> dict:
    """
    Decode an Axis model string into the structured naming block.

    Applied at ingest time immediately after filename parsing.
    Returns the 'naming' dict for a product record.

    Example:
        decode_model("P3268-SLVE")
        -> {
            'product_line': 'P',
            'product_line_name': 'Professional',
            'form_factor': 'Fixed dome',
            'resolution_name': '4K/8MP',
            'resolution_pixels': '3840×2160',
            'extensions': ['S', 'L', 'V', 'E'],
            'extension_names': ['Stainless steel', 'LED illumination',
                                 'Vandal-resistant', 'Outdoor-ready'],
            'is_outdoor': True,
            'is_vandal_resistant': True,
            'has_led': True,
            'is_rugged': True,
            'is_stainless': True,
            'is_wireless': False,
            'is_explosion_protected': False,
            'is_panoramic': False,
            'summary': 'P-line fixed dome, 4K/8MP, Stainless steel, ...',
        }
    """
    series, model_number, suffix = _parse_model_string(model_short)
    extensions, extension_names, flags = _decode_extensions(suffix)

    # Product line name (two-letter series like TQ has its own entry)
    product_line = series[0] if series else ""
    product_line_name = (
        PRODUCT_LINE_NAMES.get(series)
        or PRODUCT_LINE_NAMES.get(product_line, "Unknown")
    )

    form_factor = _lookup_form_factor(series, model_number)

    # Derive panoramic from form factor
    if any(w in form_factor.lower() for w in ("panoramic", "fisheye")):
        flags["is_panoramic"] = True

    # Rugged = stainless + outdoor
    if flags["is_stainless"] and flags["is_outdoor"]:
        flags["is_rugged"] = True

    resolution_name, resolution_pixels = _lookup_resolution(series, model_number)

    # Summary string
    ff_lower = form_factor.lower()
    if ff_lower not in ("unknown", "accessory", "specialty"):
        base = f"{series}-line {ff_lower}"
    else:
        base = f"{series}-series"
    summary_parts = [base]
    if resolution_name:
        summary_parts.append(resolution_name)
    summary_parts.extend(extension_names)
    summary = ", ".join(summary_parts)

    return {
        "product_line": product_line,
        "product_line_name": product_line_name,
        "form_factor": form_factor,
        "resolution_name": resolution_name,
        "resolution_pixels": resolution_pixels,
        "extensions": extensions,
        "extension_names": extension_names,
        "is_outdoor": flags["is_outdoor"],
        "is_vandal_resistant": flags["is_vandal_resistant"],
        "has_led": flags["has_led"],
        "is_rugged": flags["is_rugged"],
        "is_stainless": flags["is_stainless"],
        "is_wireless": flags["is_wireless"],
        "is_explosion_protected": flags["is_explosion_protected"],
        "is_panoramic": flags["is_panoramic"],
        "summary": summary,
    }


def enrich_with_naming(product: dict) -> dict:
    """
    Add the decoded naming block to a product record.

    Called at ingest time immediately after filename/model parsing.
    Modifies product dict in-place and returns it.
    """
    model_short = product.get("model_short") or ""
    if model_short:
        product["naming"] = decode_model(model_short)
    return product


# ---------------------------------------------------------------------------
# Filter helpers  (operate on lists of full product dicts)
# ---------------------------------------------------------------------------

def filter_outdoor(products: list[dict]) -> list[dict]:
    """Return only outdoor-capable products."""
    return [p for p in products if (p.get("naming") or {}).get("is_outdoor")]


def filter_vandal(products: list[dict]) -> list[dict]:
    """Return only vandal-resistant products."""
    return [p for p in products if (p.get("naming") or {}).get("is_vandal_resistant")]


def filter_by_form_factor(products: list[dict], form_factor: str) -> list[dict]:
    """Filter by form factor (case-insensitive partial match)."""
    ff_lower = form_factor.lower()
    return [
        p for p in products
        if ff_lower in ((p.get("naming") or {}).get("form_factor") or "").lower()
    ]


def nl_to_naming_filters(query: str) -> dict:
    """
    Map natural language terms to naming filter flags for CorpusQuery.search().

    Example:
        nl_to_naming_filters("outdoor vandal dome cameras")
        -> {'is_outdoor': True, 'is_vandal_resistant': True, 'form_factor': 'dome'}
    """
    q = query.lower()
    filters: dict = {}

    if any(w in q for w in ("outdoor", "outside", "weatherproof", "environmental", "ip66", "ip67", "ip68")):
        filters["is_outdoor"] = True
    if any(w in q for w in ("vandal", "ik10", "tamper-resistant", "tamper resistant")):
        filters["is_vandal_resistant"] = True
    if any(w in q for w in ("led illumin", " ir ", "infrared", "low light", "night vision")):
        filters["has_led"] = True
    if any(w in q for w in ("stainless", "marine grade", "corrosion")):
        filters["is_stainless"] = True
    if any(w in q for w in ("wireless", "wifi", "wi-fi")):
        filters["is_wireless"] = True
    if any(w in q for w in ("explosion", "atex", "hazardous area", "explosive")):
        filters["is_explosion_protected"] = True
    if any(w in q for w in ("panoramic", "fisheye", "360 degree", "360-degree", "overview")):
        filters["is_panoramic"] = True

    # Form factor
    if "dome" in q:
        filters["form_factor"] = "dome"
    elif "ptz" in q or "pan-tilt" in q:
        filters["form_factor"] = "ptz"
    elif any(w in q for w in ("panoramic", "fisheye")):
        filters["form_factor"] = "panoramic"
    elif "box" in q or "bullet" in q:
        filters["form_factor"] = "box"
    elif "pinhole" in q or "covert" in q:
        filters["form_factor"] = "pinhole"

    return filters