# Try CWD
cwd_path = Path.cwd() / "family.yaml"
if cwd_path.exists():
    return cwd_path

# Try XDG config dir
xdg_path = Path.home() / ".config" / "family-assistant" / "family.yaml"
if xdg_path.exists():
    return xdg_path

return None

Caches after first successful load. Raises FileNotFoundError if no
family.yaml can be found anywhere.
"""
global _family_config
if _family_config is not None:
    return _family_config

config_path = _resolve_family_config_path()
if config_path is None:
    raise FileNotFoundError(
        "No family.yaml found. Set FAMILY_CONFIG_PATH or run "
        "'family-assistant setup' to create one."
    )

with open(config_path, "r") as f:
    _family_config = yaml.safe_load(f)

if not _family_config or "family" not in _family_config:
    raise ValueError(f"family.yaml at {config_path} is missing the 'family' key")

return _family_config

Returns a string like:
  "Alex (dad), Jordan (mom), Charlie (son, child — needs adult),
   Sam (daughter, child — needs adult), Rover (dog — needs adult)"
"""
config = load_family_config()
members = config.get("family", {}).get("members", [])
parts = []
for m in members:
    name = m["name"]
    role = m.get("role", "")
    needs_adult = m.get("needs_adult", False)
    is_child = role.lower() in ("son", "daughter", "child")

    detail_parts = []
    if role:
        detail_parts.append(role)
    if is_child and needs_adult:
        detail_parts.append("child — needs adult")
    elif needs_adult:
        detail_parts.append("needs adult")

    if detail_parts:
        parts.append(f"{name} ({', '.join(detail_parts)})")
    else:
        parts.append(name)

return ", ".join(parts)

E.g. {"chuck": "Charlie"} from a member with nicknames: [Chuck].
"""
config = load_family_config()
members = config.get("family", {}).get("members", [])
nick_map = {}
for m in members:
    name = m["name"]
    for nick in m.get("nicknames", []):
        nick_map[nick.lower()] = name
return nick_map

Uses deterministic math from baseline_grade, baseline_year, and
advancement_month. Falls back to school_grade if baseline fields
are missing (backward compat).

Grade mapping: -2=Pre-Pre-K, -1=Pre-K, 0=Kindergarten, 1=1st, 2=2nd, ...
"""
# Backward compat: if only school_grade is set, use it directly
if "baseline_grade" not in member:
    return member.get("school_grade", "")

baseline_grade = member["baseline_grade"]
baseline_year = member.get("baseline_year", 2025)
advancement_month = member.get("advancement_month", 9)

now = datetime.now(CHICAGO_TZ)
current_year = now.year
current_month = now.month

# How many school years have elapsed since baseline?
# A school year starts in advancement_month of baseline_year.
# If current date is past advancement_month of year X, we're in the X-X+1 school year.
if current_month >= advancement_month:
    school_years_elapsed = current_year - baseline_year
else:
    school_years_elapsed = current_year - baseline_year - 1

if school_years_elapsed < 0:
    school_years_elapsed = 0

current_grade_int = baseline_grade + school_years_elapsed
return _grade_int_to_string(current_grade_int)

-2 → Pre-Pre-K, -1 → Pre-K, 0 → Kindergarten,
1 → 1st, 2 → 2nd, 3 → 3rd, 4+ → Nth (with proper ordinal suffix)
"""
if grade_int <= -2:
    return "Pre-Pre-K"
if grade_int == -1:
    return "Pre-K"
if grade_int == 0:
    return "Kindergarten"
# Ordinal suffix
if grade_int == 1:
    return "1st grade"
if grade_int == 2:
    return "2nd grade"
if grade_int == 3:
    return "3rd grade"
if 11 <= grade_int % 100 <= 13:
    return f"{grade_int}th grade"
if grade_int % 10 == 1:
    return f"{grade_int}st grade"
if grade_int % 10 == 2:
    return f"{grade_int}nd grade"
if grade_int % 10 == 3:
    return f"{grade_int}rd grade"
return f"{grade_int}th grade"

Uses dynamic grade computation from baseline_grade/baseline_year/
advancement_month. Falls back to school_grade for backward compat.

Returns a string like:
  "Charlie (1st grade, sports: soccer/t-ball, clubs: none),
   Sam (Pre-K, sports: none, clubs: none)"
Returns empty string if no children have profile fields.
"""
config = load_family_config()
members = config.get("family", {}).get("members", [])
profiles = []
for m in members:
    role = m.get("role", "").lower()
    if role not in ("son", "daughter", "child"):
        continue
    name = m["name"]
    grade = _compute_current_grade(m)
    sports = m.get("sports", [])
    clubs = m.get("clubs", [])

    parts = []
    if grade:
        parts.append(grade)
    if sports:
        parts.append(f"sports: {', '.join(sports)}")
    else:
        parts.append("sports: none")
    if clubs:
        parts.append(f"clubs: {', '.join(clubs)}")
    else:
        parts.append("clubs: none")

    detail = ", ".join(parts)
    profiles.append(f"{name} ({detail})")

if not profiles:
    return ""
return "Children profiles: " + "; ".join(profiles)

E.g. "Normalize nicknames: Chuck→Charlie"
Returns empty string if no nicknames defined.
"""
config = load_family_config()
members = config.get("family", {}).get("members", [])
rules = []
for m in members:
    name = m["name"]
    for nick in m.get("nicknames", []):
        rules.append(f"{nick}→{name}")

if not rules:
    return ""
return "Normalize nicknames: " + ", ".join(rules)

Injects family-specific placeholders into prompts:
  {family_members} — formatted list of family members
  {nickname_rules} — nickname normalization instructions

Returns:
    dict with keys 'appointment_extract', 'appointment_retry', 'conflict_resolve'
"""
# Load family context for prompt injection
family_members = get_family_members_str()
nickname_rules = get_nickname_rules_str()
children_profiles = get_children_profiles_str()

prompts = {}
for name, filename in [
    ("appointment_extract", "appointment_extract.txt"),
    ("appointment_retry", "appointment_retry.txt"),
    ("conflict_resolve", "conflict_resolve.txt"),
    ("email_classify", "email_classify.txt"),
    ("newsletter_extract", "newsletter_extract.txt"),
    ("newsletter_dedup", "newsletter_dedup.txt"),
]:
    path = _PROMPTS_DIR / filename
    text = path.read_text()
    # Inject family placeholders
    text = text.replace("{family_members}", family_members)
    text = text.replace("{nickname_rules}", nickname_rules)
    text = text.replace("{children_profiles}", children_profiles)
    prompts[name] = text
return prompts