legal-ai/mcp-server/src/legal_mcp/services/practice_area.py

"""Practice area + appeal subtype: derivation, validation, constants.

Two orthogonal axes used to separate legal domains across the system:

  practice_area  — top-level domain (multi-tenant axis). Examples:
                   appeals_committee, national_insurance, labor_law.
  appeal_subtype — refines within a domain. For appeals_committee:
                   building_permit (1xxx), betterment_levy (8xxx),
                   compensation_197 (9xxx), unknown.

Both columns are denormalized into documents/chunks/decisions/style_corpus
so vector searches can filter cheaply.
"""

from __future__ import annotations

import re

# ── Enums ──────────────────────────────────────────────────────────

PRACTICE_AREAS: set[str] = {
    "appeals_committee",
    "national_insurance",
    "labor_law",
}

APPEALS_COMMITTEE_SUBTYPES: set[str] = {
    "building_permit",
    "betterment_levy",
    "compensation_197",
    "unknown",
}

DEFAULT_PRACTICE_AREA = "appeals_committee"

# Subtypes per practice_area (extend when adding domains)
SUBTYPES_BY_AREA: dict[str, set[str]] = {
    "appeals_committee": APPEALS_COMMITTEE_SUBTYPES,
    "national_insurance": {"unknown"},
    "labor_law": {"unknown"},
}


# ── Derivation ─────────────────────────────────────────────────────

_FIRST_DIGIT = re.compile(r"^\s*(\d)")

_APPEALS_COMMITTEE_DIGIT_TO_SUBTYPE = {
    "1": "building_permit",
    "8": "betterment_levy",
    "9": "compensation_197",
}


def derive_subtype(case_number: str, practice_area: str = DEFAULT_PRACTICE_AREA) -> str:
    """Infer the appeal_subtype from case_number.

    For appeals_committee, the convention is:
      1xxx → building_permit, 8xxx → betterment_levy, 9xxx → compensation_197.

    For other practice areas there is no public numbering convention yet,
    so we return 'unknown' until a real rule is defined.
    """
    if practice_area != "appeals_committee":
        return "unknown"
    m = _FIRST_DIGIT.match(case_number or "")
    if not m:
        return "unknown"
    return _APPEALS_COMMITTEE_DIGIT_TO_SUBTYPE.get(m.group(1), "unknown")


# ── Validation ─────────────────────────────────────────────────────


def validate(practice_area: str, appeal_subtype: str | None) -> None:
    """Raise ValueError on unknown values. appeal_subtype=None is allowed."""
    if practice_area not in PRACTICE_AREAS:
        raise ValueError(
            f"unknown practice_area: {practice_area!r}. "
            f"expected one of {sorted(PRACTICE_AREAS)}"
        )
    if appeal_subtype is None:
        return
    allowed = SUBTYPES_BY_AREA.get(practice_area, {"unknown"})
    if appeal_subtype not in allowed:
        raise ValueError(
            f"unknown appeal_subtype {appeal_subtype!r} for practice_area "
            f"{practice_area!r}. expected one of {sorted(allowed)}"
        )


def is_override(case_number: str, practice_area: str, appeal_subtype: str) -> bool:
    """True iff the user-supplied subtype disagrees with what derive_subtype
    would have produced (and the derived value is not 'unknown')."""
    derived = derive_subtype(case_number, practice_area)
    return derived != "unknown" and derived != appeal_subtype