Upload 4 files

Dockerfile

@@ -0,0 +1,32 @@
+FROM python:3.11-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential gcc g++ \
+    libgomp1 && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Install torch CPU separately to avoid index-url conflicts
+RUN pip install --no-cache-dir torch --index-url https://download.pytorch.org/whl/cpu
+
+# Install Qwen2.5-7B compatible transformers + core deps
+RUN pip install --no-cache-dir \
+    "transformers>=4.53.0" \
+    accelerate \
+    gradio \
+    "spacy>=3.7.0,<3.8.0"
+
+# Install bitsandbytes (4-bit quantisation) and CodeCarbon (sustainability tracking)
+RUN pip install --no-cache-dir \
+    "bitsandbytes>=0.43.0" \
+    "codecarbon>=2.4.0"
+
+RUN python -m spacy download en_core_web_sm
+
+COPY bias_detector.py .
+COPY app.py .
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

app.py

@@ -0,0 +1,194 @@
+# ============================================
+# app.py — Gradio interface for HuggingFace Spaces
+# Provides both a web UI and automatic API endpoints
+# ============================================
+
+import gradio as gr
+from bias_detector import BiasDetector
+
+# Load models once at startup
+bd = BiasDetector()
+
+# Session-level sustainability log (accumulated across all requests in one session)
+_session_log: list[dict] = []
+
+
+def _format_sustainability(s: dict) -> str:
+    """Format a sustainability dict into a human-readable string."""
+    return (
+        f"⚡ Energy:  {s['energy_kwh']:.6f} kWh\n"
+        f"💨 CO₂eq:  {s['co2_grams']:.4f} gCO₂e\n"
+        f"💧 Water:  {s['water_liters']:.6f} L"
+    )
+
+
+def _session_totals() -> dict:
+    """Sum all sustainability metrics recorded so far this session."""
+    return {
+        "energy_kwh":   sum(r["energy_kwh"]   for r in _session_log),
+        "co2_grams":    sum(r["co2_grams"]     for r in _session_log),
+        "water_liters": sum(r["water_liters"]  for r in _session_log),
+    }
+
+
+def _build_history_table() -> str:
+    """Return a plain-text table of all requests so far."""
+    if not _session_log:
+        return "No requests yet this session."
+    lines = [
+        f"{'#':<4} {'Type':<20} {'Energy (kWh)':<16} {'CO₂ (gCO₂e)':<16} {'Water (L)':<12}",
+        "-" * 72,
+    ]
+    for i, r in enumerate(_session_log, 1):
+        lines.append(
+            f"{i:<4} {r['type']:<20} "
+            f"{r['energy_kwh']:<16.6f} "
+            f"{r['co2_grams']:<16.4f} "
+            f"{r['water_liters']:<12.6f}"
+        )
+    totals = _session_totals()
+    lines.append("-" * 72)
+    lines.append(
+        f"{'TOTAL':<24} "
+        f"{totals['energy_kwh']:<16.6f} "
+        f"{totals['co2_grams']:<16.4f} "
+        f"{totals['water_liters']:<12.6f}"
+    )
+    return "\n".join(lines)
+
+
+# ---- Endpoint functions ----
+
+def bias_detection(text):
+    """Endpoint: analyze + rewrite a job posting."""
+    rewrite = bd.rewrite_job_posting(text)
+    result  = rewrite["analysis"]
+
+    summary = (
+        f"Overall: {result['overall_label']}\n"
+        f"Bias Score: {result['bias_score']}\n"
+        f"ML Model: {result['ml_model_result']['label']} "
+        f"({round(result['ml_model_result']['score'], 3)})\n"
+        f"Masculine-coded words: {result['masculine_count']}\n"
+        f"Feminine-coded words: {result['feminine_count']}"
+    )
+
+    flagged_summary = ""
+    for f in result["flagged_words"]:
+        flagged_summary += f"• \"{f['word']}\" → {f['category']}\n"
+    if not flagged_summary:
+        flagged_summary = "No gendered words detected by lexicon."
+
+    # Log sustainability
+    s = rewrite["sustainability"]
+    _session_log.append({"type": "Job posting rewrite", **s})
+
+    totals = _session_totals()
+    return (
+        summary,
+        flagged_summary,
+        rewrite["fully_rewritten"],
+        _format_sustainability(s),
+        _build_history_table(),
+        _format_sustainability(totals),
+    )
+
+
+def anonymize(text):
+    """Endpoint: anonymize a CV/letter."""
+    result = bd.anonymize_document(text)
+
+    # Log sustainability
+    s = result["sustainability"]
+    _session_log.append({"type": "CV anonymization", **s})
+
+    totals = _session_totals()
+    return (
+        result["surface_anonymized"],
+        result["fully_anonymized"],
+        _format_sustainability(s),
+        _build_history_table(),
+        _format_sustainability(totals),
+    )
+
+
+def refresh_sustainability():
+    """Refresh the sustainability tab manually."""
+    totals = _session_totals()
+    return _build_history_table(), _format_sustainability(totals)
+
+
+# ---- Build Gradio UI ----
+
+with gr.Blocks(title="Nubias: Gender Bias Detector & CV Anonymizer") as demo:
+    gr.Markdown("# 🌍 Nubias: Gender Bias Detector & CV Anonymizer")
+    gr.Markdown(
+        "Detecting gender bias in job postings and anonymizing CVs/letters "
+        "to promote fair hiring practices — aligned with **SDG 5: Gender Equality**."
+    )
+
+    # Shared sustainability components (declared here, rendered inside the tab below)
+    history_box = gr.Textbox(label="Request History",  lines=12, interactive=False, visible=False)
+    totals_box  = gr.Textbox(label="Session Totals",   lines=4,  interactive=False, visible=False)
+
+    with gr.Tab("Job Posting Analyzer"):
+        gr.Markdown("### Analyze and rewrite a job posting for gendered language")
+        input_posting = gr.Textbox(
+            label="Paste job posting here",
+            lines=8,
+            placeholder="e.g. We are looking for an aggressive self-starter who can dominate the market...",
+        )
+        btn_analyze    = gr.Button("Analyze & Rewrite", variant="primary")
+        output_summary = gr.Textbox(label="Bias Analysis", lines=5)
+        output_flagged = gr.Textbox(label="Flagged Words", lines=5)
+        output_rewrite = gr.Textbox(label="Gender-Neutral Rewrite", lines=8)
+        output_sustain_j = gr.Textbox(label="♻️ This Request — Sustainability", lines=4)
+
+    with gr.Tab("CV / Letter Anonymizer"):
+        gr.Markdown("### Anonymize a CV, cover letter, or recommendation letter")
+        input_cv = gr.Textbox(
+            label="Paste document text here",
+            lines=8,
+            placeholder="e.g. Sarah Johnson (sarah@email.com) is an exceptionally warm leader...",
+        )
+        btn_anonymize    = gr.Button("Anonymize", variant="primary")
+        output_surface   = gr.Textbox(
+            label="Surface Anonymized (names, emails, pronouns, titles removed)", lines=6
+        )
+        output_full      = gr.Textbox(
+            label="Fully Anonymized (gendered style words neutralized + LLM pass)", lines=6
+        )
+        output_sustain_c = gr.Textbox(label="♻️ This Request — Sustainability", lines=4)
+
+    with gr.Tab("♻️ Sustainability"):
+        gr.Markdown(
+            "### Environmental impact of Nubias this session\n"
+            "Estimates are based on measured CPU energy draw (via **CodeCarbon**) "
+            "and a data-centre Water Usage Effectiveness (WUE) of **1.6 L / kWh**.\n\n"
+            "Carbon intensity uses CodeCarbon's location-aware grid data. "
+            "All figures are per-request and cumulative for the current session."
+        )
+        tab_history = gr.Textbox(label="Request History", lines=12, interactive=False)
+        tab_totals  = gr.Textbox(label="Session Totals",  lines=4,  interactive=False)
+        btn_refresh = gr.Button("🔄 Refresh", variant="secondary")
+        btn_refresh.click(
+            refresh_sustainability,
+            inputs=[],
+            outputs=[tab_history, tab_totals],
+        )
+
+    # Wire action buttons — both update the sustainability tab directly
+    btn_analyze.click(
+        bias_detection,
+        inputs=input_posting,
+        outputs=[output_summary, output_flagged, output_rewrite,
+                 output_sustain_j, tab_history, tab_totals],
+    )
+    btn_anonymize.click(
+        anonymize,
+        inputs=input_cv,
+        outputs=[output_surface, output_full, output_sustain_c,
+                 tab_history, tab_totals],
+    )
+
+demo.launch(server_name="0.0.0.0", server_port=7860)

bias_detector.py

@@ -0,0 +1,665 @@
+# ============================================
+# Nubias: Gender Bias Detector & CV Anonymizer
+# ============================================
+# Usage:
+#   from bias_detector import BiasDetector
+#   bd = BiasDetector()
+#   bias_result = bd.analyze_job_posting("We need an aggressive go-getter.")
+#   rewrite_result = bd.rewrite_job_posting("We need an aggressive go-getter.")
+#   anon_result = bd.anonymize_document("Sarah is a warm and nurturing leader.")
+#
+# Each public method returns a dict that includes a "sustainability" key:
+#   {
+#     "energy_kwh":  float,   # estimated kWh consumed by this request
+#     "co2_grams":   float,   # gCO2e for this request
+#     "water_liters": float,  # estimated water used for cooling
+#   }
+# ============================================
+
+import re
+import torch
+import spacy
+from collections import Counter
+from transformers import (
+    pipeline,
+    AutoTokenizer,
+    AutoModelForCausalLM,
+    BitsAndBytesConfig,
+)
+from codecarbon import EmissionsTracker
+
+
+# ---------------------------------------------------------------------------
+# Water Usage Effectiveness constant.
+# Industry average for hyperscale data centres ≈ 1.6 L / kWh of IT load.
+# Source: Mytton (2021), "Hiding greenhouse gas emissions in the cloud".
+# ---------------------------------------------------------------------------
+_WUE_LITERS_PER_KWH = 1.6
+
+
+def _build_sustainability(tracker: EmissionsTracker) -> dict:
+    """
+    Stop the tracker and convert its output into the three metrics we report.
+    CodeCarbon gives energy in kWh and emissions in kg CO2e.
+    """
+    tracker.stop()
+    energy_kwh  = tracker.final_emissions_data.energy_consumed   # kWh
+    co2_kg      = tracker.final_emissions_data.emissions          # kg CO2e
+    co2_grams   = co2_kg * 1000
+    water_liters = energy_kwh * _WUE_LITERS_PER_KWH
+    return {
+        "energy_kwh":   round(energy_kwh,   6),
+        "co2_grams":    round(co2_grams,    4),
+        "water_liters": round(water_liters, 6),
+    }
+
+
+class BiasDetector:
+    def __init__(self, llm_model_name: str = "Qwen/Qwen2.5-7B-Instruct"):
+        """
+        Initialize all models. Call once at startup, reuse for every request.
+
+        Args:
+            llm_model_name: HuggingFace instruction-tuned model for rewriting
+                            and CV anonymization. Defaults to Qwen2.5-7B-Instruct
+                            loaded in 4-bit to fit on CPU-only Spaces (~4.5 GB RAM).
+        """
+        print("Loading bias detection model...")
+        self.classifier = pipeline(
+            "text-classification",
+            model="valurank/distilroberta-bias",
+            device=0 if torch.cuda.is_available() else -1,
+        )
+
+        print("Loading spaCy NER model...")
+        self.nlp = spacy.load("en_core_web_sm")
+
+        print(f"Loading {llm_model_name} in 4-bit quantisation...")
+        bnb_config = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_compute_dtype=torch.float16,
+            bnb_4bit_use_double_quant=True,
+            bnb_4bit_quant_type="nf4",
+        )
+        self.tokenizer = AutoTokenizer.from_pretrained(llm_model_name)
+        self.llm = AutoModelForCausalLM.from_pretrained(
+            llm_model_name,
+            quantization_config=bnb_config,
+            device_map="auto",
+        )
+
+        print("All models loaded successfully!")
+
+        # ----- Detection Lexicon (stem-based) -----
+
+        self.detection_lexicon = {
+            "masculine": [
+                "active", "adventurous", "aggress", "ambitio", "analy", "assert",
+                "autonom", "challeng", "compet", "confident", "courag", "decisive",
+                "determin", "dominant", "force", "independen", "individual",
+                "intellect", "lead", "logic", "objective", "outspoken", "persist",
+                "self-confiden", "self-relian", "self-sufficien", "superior",
+                "rockstar", "ninja", "manpower", "chairman", "he/him",
+                "fearless", "strong-willed", "ruthless", "hustle", "crush",
+                "conquer", "warrior", "battle-tested", "go-getter",
+            ],
+            "feminine": [
+                "affectionate", "cheer", "commit", "communal", "compassion",
+                "connect", "considerate", "cooperat", "depend", "empath",
+                "gentle", "honest", "interpersonal", "interdependen", "kind",
+                "loyal", "nurtur", "pleasant", "polite", "respon", "sensitiv",
+                "support", "sympath", "tender", "trust", "understand", "warm",
+                "yield", "collaborative", "caring", "welcoming", "friendly",
+                "helpful", "people-oriented", "team-oriented", "encouraging",
+                "agreeable", "devoted", "gracious", "modest",
+            ],
+        }
+
+        # ----- Word-level replacements for job posting rewriting -----
+
+        self.word_replacements = {
+            "aggressive": "proactive",
+            "aggressively": "proactively",
+            "ambitious": "motivated",
+            "dominant": "experienced",
+            "dominate": "excel in",
+            "manpower": "workforce",
+            "chairman": "chairperson",
+            "ninja": "specialist",
+            "rockstar": "top performer",
+            "fearless": "confident",
+            "ruthless": "results-driven",
+            "crush": "achieve",
+            "conquer": "succeed in",
+            "warrior": "professional",
+            "hustle": "dedication",
+            "go-getter": "self-starter",
+            "nurturing": "supportive",
+            "warm": "approachable",
+            "sympathetic": "understanding",
+            "gentle": "thoughtful",
+            "tender": "considerate",
+            "yielding": "flexible",
+            "caring": "attentive",
+            "agreeable": "cooperative",
+            "devoted": "dedicated",
+            "modest": "professional",
+        }
+
+        # ----- Gendered style word replacements for CV anonymization -----
+
+        self.style_replacements = {
+            # Feminine-coded → neutral
+            "warm": "effective",
+            "nurturing": "supportive",
+            "nurture": "develop",
+            "nurtured": "developed",
+            "gentle": "measured",
+            "caring": "attentive",
+            "compassionate": "considerate",
+            "compassion": "consideration",
+            "sympathetic": "understanding",
+            "sympathy": "understanding",
+            "affectionate": "personable",
+            "tender": "thoughtful",
+            "devoted": "dedicated",
+            "gracious": "professional",
+            "motherly": "mentoring",
+            "sweet": "pleasant",
+            "yielding": "flexible",
+            "submissive": "cooperative",
+            "emotional": "perceptive",
+            "cheerful": "positive",
+            "pleasant": "professional",
+            "polite": "courteous",
+            "agreeable": "cooperative",
+            "modest": "understated",
+            "friendly": "collegial",
+            "welcoming": "inclusive",
+            # Masculine-coded → neutral
+            "aggressive": "proactive",
+            "aggressively": "proactively",
+            "dominant": "strong",
+            "dominated": "excelled in",
+            "forceful": "effective",
+            "forcefully": "effectively",
+            "ambitious": "motivated",
+            "fierce": "determined",
+            "fiercely": "with determination",
+            "ruthless": "results-oriented",
+            "bold": "decisive",
+            "boldly": "decisively",
+            "fearless": "confident",
+            "fearlessly": "confidently",
+            "commanding": "authoritative",
+            "headstrong": "resolute",
+        }
+
+        # ----- System prompts -----
+
+        self.JOB_REWRITE_PROMPT = """You are a job posting editor. Your ONLY job is to rewrite job postings to be gender-neutral.
+
+Rules:
+1. Replace masculine-coded words (aggressive, dominant, fearless, ninja, rockstar) with neutral alternatives
+2. Replace feminine-coded words (nurturing, warm, sympathetic) with neutral alternatives
+3. Keep ALL job requirements, qualifications, and responsibilities intact
+4. Keep the same professional tone and structure
+5. Do NOT add or remove job requirements
+6. Output ONLY the rewritten job posting, nothing else
+
+Example:
+Input: "We need an aggressive go-getter who can crush the competition and dominate the market."
+Output: "We need a motivated professional who can deliver strong results and excel in the market."
+"""
+
+        self.CV_ANONYMIZE_PROMPT = """You are a document anonymizer specializing in gender-neutral language.
+You will receive a CV or letter that has already been partially anonymized (names replaced with [CANDIDATE]/[PERSON_N], emails with [EMAIL], pronouns neutralized).
+Your job is to do a final pass to catch any remaining gendered language the lexicon missed.
+
+Rules:
+1. Replace any remaining gendered pronouns (he, she, his, her, him, himself, herself) with they/their/them/themselves
+2. Replace any remaining gendered titles or nouns with neutral equivalents
+3. Replace any remaining gendered descriptors with neutral alternatives
+4. Do NOT change [CANDIDATE], [PERSON_2], [PERSON_3], [EMAIL] placeholders — keep them exactly as-is
+5. Do NOT add, invent, or remove any factual content
+6. Do NOT add commentary or explanation
+7. Output ONLY the anonymized text, nothing else
+"""
+
+    # =============================================
+    # HELPER: LLM generation
+    # =============================================
+
+    def _generate(self, system_prompt: str, user_message: str, max_extra_tokens: int = 300) -> str:
+        """Run a single LLM inference call. Used by both rewrite and anonymize."""
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {"role": "user",   "content": user_message},
+        ]
+
+        input_text = self.tokenizer.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        inputs = self.tokenizer(input_text, return_tensors="pt").to(self.llm.device)
+
+        with torch.no_grad():
+            outputs = self.llm.generate(
+                **inputs,
+                max_new_tokens=len(inputs["input_ids"][0]) + max_extra_tokens,
+                temperature=0.3,
+                do_sample=True,
+                top_p=0.9,
+                repetition_penalty=1.2,
+            )
+
+        generated = outputs[0][inputs["input_ids"].shape[1]:]
+        result = self.tokenizer.decode(generated, skip_special_tokens=True).strip()
+
+        # Strip LLM commentary that sometimes follows the output
+        cutoff_markers = [
+            "\nI made", "\nI changed", "\nI replaced", "\nI also",
+            "\nNote:", "\nChanges:", "\nExplanation:",
+            "\nHere's", "\nThe revised", "\nThis version",
+            "\nIn this", "\nBy replacing",
+        ]
+        for marker in cutoff_markers:
+            if marker in result:
+                result = result[:result.index(marker)].strip()
+
+        # Strip wrapping quotes
+        if result.startswith('"') and result.endswith('"'):
+            result = result[1:-1].strip()
+
+        return result
+
+    # =============================================
+    # HELPER: Lexicon-based style word replacement
+    # =============================================
+
+    def _replace_style_words(self, text: str, replacements_dict: dict) -> str:
+        """Replace gendered style words using a dictionary. Preserves capitalization."""
+        result = text
+        for old_word, new_word in replacements_dict.items():
+            pattern = re.compile(r"\b" + re.escape(old_word) + r"\b", re.IGNORECASE)
+
+            def replace_keep_case(match, replacement=new_word):
+                original = match.group(0)
+                if original[0].isupper():
+                    return replacement[0].upper() + replacement[1:]
+                return replacement
+
+            result = pattern.sub(replace_keep_case, result)
+        return result
+
+    # =============================================
+    # PHASE 1A: BIAS DETECTION IN JOB POSTINGS
+    # =============================================
+
+    def _run_bias_analysis(self, text: str) -> dict:
+        """
+        Core bias detection logic (no tracker). Called internally by both
+        analyze_job_posting() and rewrite_job_posting() to avoid nested trackers.
+        """
+        # 1. ML model score
+        ml_result = self.classifier(text)[0]
+
+        # 2. Lexicon scan using stem matching
+        flagged_words = []
+        words_in_text = text.lower().split()
+
+        for category, stems in self.detection_lexicon.items():
+            for stem in stems:
+                for word in words_in_text:
+                    if word.startswith(stem) or stem in word:
+                        flagged_words.append({
+                            "word":     word.strip(".,;:!?()\"'"),
+                            "stem":     stem,
+                            "category": category + "-coded",
+                        })
+
+        # Remove duplicates
+        seen = set()
+        unique_flags = []
+        for f in flagged_words:
+            if f["word"] not in seen:
+                seen.add(f["word"])
+                unique_flags.append(f)
+
+        # 3. Combined bias score
+        ml_bias_score = (
+            1 - ml_result["score"]
+            if ml_result["label"] == "NEUTRAL"
+            else ml_result["score"]
+        )
+        lexicon_boost  = min(len(unique_flags) * 0.15, 0.5)
+        combined_score = min(ml_bias_score + lexicon_boost, 1.0)
+
+        # 4. Overall label
+        overall_label = "BIASED" if combined_score >= 0.5 else "NEUTRAL"
+
+        return {
+            "overall_label":   overall_label,
+            "bias_score":      round(combined_score, 3),
+            "ml_model_result": ml_result,
+            "flagged_words":   unique_flags,
+            "masculine_count": sum(1 for f in unique_flags if f["category"] == "masculine-coded"),
+            "feminine_count":  sum(1 for f in unique_flags if f["category"] == "feminine-coded"),
+        }
+
+    def analyze_job_posting(self, text: str) -> dict:
+        """
+        Hybrid bias detector: ML model + lexicon scan.
+        Tracks energy, CO2, and water consumption for the full request.
+
+        Returns dict with: overall_label, bias_score, ml_model_result,
+        flagged_words, masculine_count, feminine_count, sustainability.
+        """
+        tracker = EmissionsTracker(
+            project_name="nubias_bias_detection",
+            log_level="error",
+            save_to_file=False,
+        )
+        tracker.start()
+
+        result = self._run_bias_analysis(text)
+        sustainability = _build_sustainability(tracker)
+
+        return {**result, "sustainability": sustainability}
+
+    # =============================================
+    # PHASE 1B: JOB POSTING REWRITER
+    # =============================================
+
+    def rewrite_job_posting(self, text: str) -> dict:
+        """
+        Rewrites a job posting to remove gendered language.
+        Combines lexicon-based replacements with Qwen2.5-7B rewriting.
+        Sustainability covers the full pipeline (classifier + LLM).
+
+        Returns dict with: original, analysis, lexicon_fixed,
+        fully_rewritten, sustainability.
+        """
+        tracker = EmissionsTracker(
+            project_name="nubias_job_rewrite",
+            log_level="error",
+            save_to_file=False,
+        )
+        tracker.start()
+
+        # 1. Bias detection (use private method to avoid nested trackers)
+        analysis = self._run_bias_analysis(text)
+
+        # 2. Lexicon-based quick fix
+        lexicon_fixed = self._replace_style_words(text, self.word_replacements)
+
+        # 3. LLM rewrite for deeper neutralization
+        rewritten = self._generate(
+            self.JOB_REWRITE_PROMPT,
+            f"Rewrite this job posting to be gender-neutral. Output ONLY the rewritten text:\n\n{lexicon_fixed}",
+            max_extra_tokens=300,
+        )
+
+        # Fallback if LLM output looks broken
+        if len(rewritten) < 10 or len(rewritten) > len(text) * 3:
+            rewritten = lexicon_fixed
+
+        sustainability = _build_sustainability(tracker)
+
+        return {
+            "original":        text,
+            "analysis":        analysis,
+            "lexicon_fixed":   lexicon_fixed,
+            "fully_rewritten": rewritten,
+            "sustainability":  sustainability,
+        }
+
+    # =============================================
+    # PHASE 2: CV / LETTER GENDER ANONYMIZER
+    # =============================================
+
+    def _surface_anonymize(self, text: str) -> str:
+        """
+        Step A: Replace emails with [EMAIL].
+        Step B: spaCy NER → frequency-based person labelling.
+                Most-mentioned person → [CANDIDATE].
+                Others → [PERSON_2], [PERSON_3], … in order of first appearance.
+        Step C: Rule-based pronoun / title / gendered-noun replacement.
+        """
+
+        # --- Step A: Email addresses ---
+        anonymized = re.sub(
+            r"[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,}",
+            "[EMAIL]",
+            text,
+        )
+
+        # --- Step B: Person names via spaCy NER ---
+        doc = self.nlp(anonymized)
+
+        # Collect all PERSON spans and count mention frequency per canonical name
+        # (use the first token as a rough canonical key to handle "Sarah" vs "Sarah Johnson")
+        person_spans = [
+            (ent.start_char, ent.end_char, ent.text)
+            for ent in doc.ents
+            if ent.label_ == "PERSON"
+        ]
+
+        # Count frequency by normalised name (lower-case first token)
+        name_freq: Counter = Counter()
+        first_seen: dict = {}   # normalised_name → first start_char
+        for start, end, name in person_spans:
+            key = name.strip().lower().split()[0]
+            name_freq[key] += 1
+            if key not in first_seen:
+                first_seen[key] = start
+
+        if name_freq:
+            # Most-frequent name is the candidate
+            candidate_key = name_freq.most_common(1)[0][0]
+
+            # Remaining names ordered by first appearance
+            other_keys = sorted(
+                [k for k in name_freq if k != candidate_key],
+                key=lambda k: first_seen[k],
+            )
+            label_map = {candidate_key: "[CANDIDATE]"}
+            for i, k in enumerate(other_keys, start=2):
+                label_map[k] = f"[PERSON_{i}]"
+
+            # Replace spans in reverse order to preserve char offsets
+            for start, end, name in reversed(person_spans):
+                key = name.strip().lower().split()[0]
+                label = label_map.get(key, "[PERSON]")
+                anonymized = anonymized[:start] + label + anonymized[end:]
+
+        # --- Step C: Pronouns, titles, gendered nouns ---
+        replacements = [
+            # Pronoun + verb agreement (she/he → they)
+            (r"\b[Ss]he has\b",            "They have"),
+            (r"\b[Ss]he is\b",             "They are"),
+            (r"\b[Ss]he was\b",            "They were"),
+            (r"\b[Ss]he works\b",          "They work"),
+            (r"\b[Ss]he often\b",          "They often"),
+            (r"\b[Ss]he also\b",           "They also"),
+            (r"\b[Ss]he always\b",         "They always"),
+            (r"\b[Ss]he then\b",           "They then"),
+            (r"\b[Ss]he quickly\b",        "They quickly"),
+            (r"\b[Ss]he approached\b",     "They approached"),
+            (r"\b[Ss]he independently\b",  "They independently"),
+            (r"\b[Hh]e has\b",             "They have"),
+            (r"\b[Hh]e is\b",             "They are"),
+            (r"\b[Hh]e was\b",             "They were"),
+            (r"\b[Hh]e works\b",           "They work"),
+            (r"\b[Hh]e often\b",           "They often"),
+            (r"\b[Hh]e also\b",            "They also"),
+            (r"\b[Hh]e always\b",          "They always"),
+            (r"\b[Hh]e then\b",            "They then"),
+            (r"\b[Hh]e quickly\b",         "They quickly"),
+            # Object pronoun: verb + her/him → verb + them
+            (r"\benable [Hh]er\b",  "enable them"),
+            (r"\benable [Hh]im\b",  "enable them"),
+            (r"\bmade [Hh]er\b",    "made them"),
+            (r"\bmade [Hh]im\b",    "made them"),
+            (r"\bmake [Hh]er\b",    "make them"),
+            (r"\bmake [Hh]im\b",    "make them"),
+            (r"\bhelped [Hh]er\b",  "helped them"),
+            (r"\bhelped [Hh]im\b",  "helped them"),
+            (r"\ballow [Hh]er\b",   "allow them"),
+            (r"\ballow [Hh]im\b",   "allow them"),
+            (r"\bgave [Hh]er\b",    "gave them"),
+            (r"\bgave [Hh]im\b",    "gave them"),
+            (r"\btold [Hh]er\b",    "told them"),
+            (r"\btold [Hh]im\b",    "told them"),
+            (r"\basked [Hh]er\b",   "asked them"),
+            (r"\basked [Hh]im\b",   "asked them"),
+            (r"\bshowed [Hh]er\b",  "showed them"),
+            (r"\bshowed [Hh]im\b",  "showed them"),
+            (r"\btaught [Hh]er\b",  "taught them"),
+            (r"\btaught [Hh]im\b",  "taught them"),
+            (r"\boffered [Hh]er\b", "offered them"),
+            (r"\boffered [Hh]im\b", "offered them"),
+            (r"\bsent [Hh]er\b",    "sent them"),
+            (r"\bsent [Hh]im\b",    "sent them"),
+            (r"\bserve [Hh]er\b",   "serve them"),
+            (r"\bserve [Hh]im\b",   "serve them"),
+            # Possessive before nouns
+            (r"\b[Hh]er(?=\s+\w)",  "their"),
+            (r"\b[Hh]is(?=\s+\w)",  "their"),
+            # Standalone pronouns
+            (r"\bShe\b",       "They"),
+            (r"\bshe\b",       "they"),
+            (r"\bHe\b",        "They"),
+            (r"\bhe\b",        "they"),
+            (r"\b[Hh]im\b",   "them"),
+            (r"\b[Hh]erself\b",  "themselves"),
+            (r"\b[Hh]imself\b",  "themselves"),
+            # Titles (remove)
+            (r"\bMrs?\.\s*", ""),
+            (r"\bMs\.\s*",   ""),
+            (r"\bMiss\s+",   ""),
+            # Gendered nouns
+            (r"\b[Hh]usband\b",    "spouse"),
+            (r"\b[Ww]ife\b",       "spouse"),
+            (r"\b[Mm]other\b",     "parent"),
+            (r"\b[Ff]ather\b",     "parent"),
+            (r"\b[Ss]on\b",        "child"),
+            (r"\b[Dd]aughter\b",   "child"),
+            (r"\b[Bb]rother\b",    "sibling"),
+            (r"\b[Ss]ister\b",     "sibling"),
+            (r"\b[Bb]oyfriend\b",  "partner"),
+            (r"\b[Gg]irlfriend\b", "partner"),
+            (r"\b[Ss]pokesman\b",  "spokesperson"),
+            (r"\b[Ss]pokeswoman\b","spokesperson"),
+            (r"\b[Cc]hairman\b",   "chairperson"),
+            (r"\b[Cc]hairwoman\b", "chairperson"),
+            (r"\b[Mm]anpower\b",   "workforce"),
+            (r"\b[Gg]irl\b",       "person"),
+            (r"\b[Bb]oy\b",        "person"),
+            (r"\b[Ww]oman\b",      "person"),
+            (r"\b[Ww]omen\b",      "people"),
+            (r"\b[Mm]an\b",        "person"),
+            (r"\b[Mm]en\b",        "people"),
+            (r"\b[Ll]ady\b",       "person"),
+            (r"\b[Ll]adies\b",     "people"),
+            (r"\b[Gg]entleman\b",  "person"),
+            (r"\b[Gg]entlemen\b",  "people"),
+            (r"\b[Ff]emale\b",     "person"),
+            (r"\b[Ff]emales\b",    "people"),
+            (r"\b[Mm]ale\b",       "person"),
+            (r"\b[Mm]ales\b",      "people"),
+        ]
+
+        for pattern, replacement in replacements:
+            anonymized = re.sub(pattern, replacement, anonymized)
+
+        # Clean up artefacts
+        anonymized = re.sub(r"\s{2,}", " ", anonymized)
+        anonymized = re.sub(r"\.\s*\.", ".", anonymized)
+        return anonymized.strip()
+
+    def anonymize_document(self, text: str) -> dict:
+        """
+        Full anonymization pipeline:
+          Step A: Email regex → [EMAIL]
+          Step B: spaCy NER → frequency-based [CANDIDATE] / [PERSON_N] labels
+          Step C: Rule-based → replace pronouns, titles, gendered nouns
+          Step D: Lexicon-based → replace gendered style words
+          Step E: LLM final pass → catch anything the lexicon missed
+        Sustainability covers the full pipeline.
+
+        Returns dict with: original, surface_anonymized,
+        fully_anonymized, sustainability.
+        """
+        tracker = EmissionsTracker(
+            project_name="nubias_cv_anonymize",
+            log_level="error",
+            save_to_file=False,
+        )
+        tracker.start()
+
+        # Steps A–C: surface anonymization (emails, names, pronouns, titles)
+        surface_result = self._surface_anonymize(text)
+
+        # Step D: Style word neutralization
+        lexicon_result = self._replace_style_words(surface_result, self.style_replacements)
+
+        # Step E: LLM final pass
+        llm_result = self._generate(
+            self.CV_ANONYMIZE_PROMPT,
+            f"Perform a final gender-neutralization pass on this text. Output ONLY the result:\n\n{lexicon_result}",
+            max_extra_tokens=400,
+        )
+
+        # Fallback if LLM output looks broken
+        fully_anonymized = (
+            llm_result
+            if len(llm_result) >= len(lexicon_result) * 0.5
+            else lexicon_result
+        )
+
+        sustainability = _build_sustainability(tracker)
+
+        return {
+            "original":           text,
+            "surface_anonymized": surface_result,
+            "fully_anonymized":   fully_anonymized,
+            "sustainability":     sustainability,
+        }
+
+
+# =============================================
+# Quick test (run this file directly to verify)
+# =============================================
+if __name__ == "__main__":
+    bd = BiasDetector()
+
+    print("=" * 50)
+    print("TEST 1: Job Posting Bias Detection")
+    print("=" * 50)
+    test_posting = "We need an aggressive go-getter who can dominate the competition."
+    result = bd.analyze_job_posting(test_posting)
+    print(f"Label: {result['overall_label']}")
+    print(f"Score: {result['bias_score']}")
+    print(f"Flagged: {[f['word'] for f in result['flagged_words']]}")
+    print(f"Sustainability: {result['sustainability']}")
+
+    print("\n" + "=" * 50)
+    print("TEST 2: Job Posting Rewrite")
+    print("=" * 50)
+    result = bd.rewrite_job_posting(test_posting)
+    print(f"Original:  {result['original']}")
+    print(f"Lexicon:   {result['lexicon_fixed']}")
+    print(f"Rewritten: {result['fully_rewritten']}")
+    print(f"Sustainability: {result['sustainability']}")
+
+    print("\n" + "=" * 50)
+    print("TEST 3: CV Anonymization")
+    print("=" * 50)
+    test_cv = """Dr. Sarah Johnson (sarah.johnson@email.com) is an exceptionally warm and nurturing leader.
+She has always been deeply compassionate and sympathetic toward her colleagues.
+Her husband mentioned she is also a devoted mother who balances work and family gracefully.
+I, Prof. Michael Davies, am delighted to recommend her for this position."""
+    result = bd.anonymize_document(test_cv)
+    print(f"SURFACE:\n{result['surface_anonymized']}\n")
+    print(f"FULLY ANONYMIZED:\n{result['fully_anonymized']}")
+    print(f"Sustainability: {result['sustainability']}")

requirements.txt

@@ -0,0 +1,11 @@
+transformers>=4.53.0
+torch>=2.0.0
+accelerate
+gradio
+numpy<2.0.0
+spacy>=3.7.0,<3.8.0
+thinc>=8.2.0,<8.3.0
+blis>=0.7.9,<1.1.0
+en-core-web-sm @ https://github.com/explosion/spacy-models/releases/download/en_core_web_sm-3.7.1/en_core_web_sm-3.7.1-py3-none-any.whl
+bitsandbytes>=0.43.0
+codecarbon>=2.4.0