modules/proverbs.py

import os
import pandas as pd
from rapidfuzz import process, fuzz

# ============================================================
# DATA LOCATION
# ============================================================

BASE_DIR = os.path.dirname(
    os.path.dirname(
        os.path.abspath(__file__)
    )
)

PROVERB_FILE = os.path.join(
    BASE_DIR,
    "data",
    "proverbs.csv"
)

# ============================================================
# LOAD PROVERBS
# ============================================================

def load_proverbs():

    try:

        df = pd.read_csv(
            PROVERB_FILE,
            encoding="utf-8"
        )

        df.columns = (
            df.columns
            .str.strip()
        )

        df.fillna("", inplace=True)

        print("Proverbs loaded successfully")
        print("Columns:", df.columns.tolist())
        print("Records:", len(df))

        return df

    except Exception as e:

        print(
            f"Proverb loading error: {e}"
        )

        return pd.DataFrame()

# ============================================================
# GLOBAL DATAFRAME
# ============================================================

proverb_df = load_proverbs()

# ============================================================
# SEARCH PROVERB
# ============================================================

def search_proverb(text, df=None):

    if df is None:
        df = proverb_df

    if df.empty:
        return "Proverb database unavailable."

    if not text:
        return "Please enter a proverb or keyword."

    query = text.strip()

    if not query:
        return "Please enter a proverb or keyword."

    # ========================================================
    # VERIFY REQUIRED COLUMNS
    # ========================================================

    required_columns = ["Kiembu", "English"]

    for col in required_columns:

        if col not in df.columns:

            return (
                f"Missing column '{col}' "
                f"in proverbs.csv"
            )

    # ========================================================
    # EXACT MATCH
    # ========================================================

    exact_match = df[
        df["Kiembu"]
        .astype(str)
        .str.lower()
        .str.strip()
        == query.lower()
    ]

    if not exact_match.empty:

        proverb = exact_match.iloc[0]["Kiembu"]
        meaning = exact_match.iloc[0]["English"]

        return f"""
### Proverb Found

**Kiembu**

{proverb}

**English Meaning**

{meaning}
"""

    # ========================================================
    # FUZZY SEARCH
    # ========================================================

    choices = (
        df["Kiembu"]
        .astype(str)
        .tolist()
    )

    best_match = process.extractOne(
        query,
        choices,
        scorer=fuzz.WRatio
    )

    if not best_match:

        return "No proverb found."

    proverb = best_match[0]
    score = best_match[1]

    if score < 70:

        return (
            "No close proverb found.\n\n"
            f"Best similarity score: {score}"
        )

    row = df[
        df["Kiembu"]
        .astype(str)
        == proverb
    ]

    if row.empty:
        return "No proverb found."

    meaning = row.iloc[0]["English"]

    return f"""
### Suggested Proverb

**Kiembu**

{proverb}

**English Meaning**

{meaning}
"""