Add all project files for HF Spaces deployment

Dockerfile

@@ -0,0 +1,55 @@
+# ---------- Frontend build ----------
+FROM node:20-bullseye AS fe
+WORKDIR /app/frontend
+COPY frontend/package*.json ./
+RUN npm ci
+COPY frontend/ ./
+RUN npm run build
+
+# ---------- Backend build ----------
+FROM python:3.11-slim AS be
+ENV PIP_NO_CACHE_DIR=1 PYTHONUNBUFFERED=1 PIP_PREFER_BINARY=1
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends \
+build-essential gcc g++ gfortran make pkg-config \
+libopenblas-dev liblapack-dev git \
+&& rm -rf /var/lib/apt/lists/*
+RUN python -m pip install --upgrade pip setuptools wheel
+RUN pip install --index-url https://download.pytorch.org/whl/cpu "torch==2.3.1"
+COPY backend/requirements.txt ./backend/requirements.txt
+RUN sed -i 's/^[Tt]orch[[:space:]=<>!].*/# torch pinned separately (CPU)/' backend/requirements.txt || true
+RUN pip install --only-binary=:all: blis || echo "Precompiled blis not available"
+RUN pip install -r backend/requirements.txt || pip install -r backend/requirements.txt --no-deps
+COPY backend/ ./backend/
+
+# ---------- Runtime ----------
+FROM python:3.11-slim AS runtime
+ENV PYTHONUNBUFFERED=1 PIP_NO_CACHE_DIR=1 PORT=7860
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends \
+nginx supervisor ca-certificates \
+libgomp1 libopenblas0 \
+&& rm -rf /var/lib/apt/lists/*
+COPY --from=fe /app/frontend/dist /usr/share/nginx/html
+COPY --from=be /usr/local /usr/local
+COPY --from=be /app/backend /app/backend
+RUN python -m pip install --no-cache-dir gunicorn
+
+COPY nginx.conf.template /etc/nginx/nginx.conf
+
+RUN mkdir -p /etc/supervisor/conf.d && \
+printf "[program:api]\n\
+command=gunicorn --workers 2 --threads 8 --timeout 0 --chdir /app/backend -b 0.0.0.0:5001 server:app\n\
+priority=10\nautostart=true\nautorestart=true\n\
+stdout_logfile=/dev/stdout\nstderr_logfile=/dev/stderr\n\
+stdout_logfile_maxbytes=0\nstderr_logfile_maxbytes=0\n\n\
+[program:nginx]\n\
+command=nginx -g \"daemon off;\"\n\
+priority=20\nautostart=true\nautorestart=true\n\
+stdout_logfile=/dev/stdout\nstderr_logfile=/dev/stderr\n\
+stdout_logfile_maxbytes=0\nstderr_logfile_maxbytes=0\n\n\
+[supervisord]\nlogfile=/dev/stdout\nlogfile_maxbytes=0\nnodaemon=true\nuser=root\n" \
+> /etc/supervisor/conf.d/app.conf
+
+EXPOSE 7860
+CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/app.conf"]

backend/requirements.txt

@@ -0,0 +1,164 @@
+accelerate==1.10.1
+aiohttp==3.9.1
+aiosignal==1.3.1
+alabaster>=0.7,<0.8
+annotated-types==0.6.0
+anyio==4.2.0
+arrow==1.3.0
+attrs==23.2.0
+babel==2.17.0
+beautifulsoup4==4.13.3
+bibtexparser==1.4.3
+boto3==1.36.14
+bs4==0.0.2
+catalogue==2.0.10
+certifi==2023.11.17
+charset-normalizer==3.3.2
+click==8.1.7
+cloudpathlib==0.20.0
+colorama==0.4.6
+confection==0.1.5
+contourpy==1.3.1
+cycler==0.12.1
+cymem==2.0.11
+dataclasses-json==0.6.3
+datasets==2.18.0
+defusedxml==0.7.1
+Deprecated==1.2.18
+dill==0.3.8
+distro==1.9.0
+fake-useragent==2.0.3
+fastapi==0.109.0
+filelock==3.17.0
+Flask==2.0.3
+Flask-Cors==3.0.10
+fonttools==4.56.0
+fpdf2==2.8.3
+free-proxy==1.1.3
+frozenlist==1.4.1
+fsspec==2024.2.0
+gensim==4.3.3
+h11==0.14.0
+hdbscan==0.8.40
+hf-xet==1.1.9
+httpcore==1.0.2
+httpx==0.26.0
+huggingface-hub==0.34.4
+idna==3.6
+imagesize==1.4.1
+itsdangerous==2.2.0
+Jinja2==3.0.3
+jmespath==1.0.1
+joblib==1.4.2
+jsonpatch==1.33
+jsonpointer==2.4
+kiwisolver==1.4.8
+langchain==0.1.1
+langchain-community==0.0.13
+langchain-core==0.1.13
+langchain-openai==0.0.3
+langcodes==3.5.0
+langserve==0.0.39
+langsmith==0.0.83
+language_data==1.3.0
+lxml==5.3.1
+marisa-trie==1.2.1
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+marshmallow==3.20.2
+matplotlib==3.10.0
+mdurl==0.1.2
+mpmath==1.3.0
+multidict==6.0.4
+multiprocess==0.70.16
+murmurhash==1.0.12
+mypy-extensions==1.0.0
+narwhals==1.39.0
+networkx==3.4.2
+nltk==3.8.1
+numpy==1.26.4
+openai==1.9.0
+orjson==3.9.12
+outcome==1.3.0.post0
+packaging==23.2
+pandas==2.1.4
+Pillow==9.5.0
+plotly==6.0.1
+preshed==3.0.9
+psutil==7.0.0
+pyarrow==14.0.2
+pyarrow-hotfix==0.7
+pyasn1==0.6.1
+pydantic==2.5.3
+pydantic_core==2.14.6
+Pygments==2.19.1
+pyparsing==3.2.1
+PySocks==1.7.1
+python-dateutil==2.9.0.post0
+python-dotenv==1.0.0
+pytz==2025.1
+PyYAML==6.0.1
+rank-bm25==0.2.2
+regex==2023.12.25
+requests==2.32.3
+rich==13.9.4
+roman-numerals-py==3.1.0
+rsa==4.7.2
+s3transfer==0.11.2
+safetensors==0.5.2
+SAGEDbias @ https://github.com/holistic-ai/SAGED-Bias/archive/8d5664387c58d94ffd10667c40493a5e460eaac6.zip
+scholarly==1.7.11
+scikit-learn==1.6.1
+scipy==1.13.1
+selenium==4.29.0
+sentence-transformers==3.4.1
+shellingham==1.5.4
+six==1.17.0
+smart-open==7.1.0
+sniffio==1.3.0
+snowballstemmer==2.2.0
+sortedcontainers==2.4.0
+soupsieve==2.6
+spacy==3.8.7
+spacy-legacy==3.0.12
+spacy-loggers==1.0.5
+Sphinx==7.2.6
+sphinx-rtd-theme==3.0.2
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
+sphinxcontrib-jquery==4.1
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+SQLAlchemy==2.0.25
+srsly==2.5.1
+starlette==0.35.1
+sympy==1.13.1
+tenacity==8.2.3
+thinc==8.3.4
+threadpoolctl==3.5.0
+tiktoken==0.5.2
+tokenizers==0.22.0
+tqdm==4.67.1
+transformers==4.56.1
+trio==0.29.0
+trio-websocket==0.12.2
+typer==0.15.1
+types-python-dateutil==2.9.0.20241206
+typing-inspect==0.9.0
+typing_extensions==4.12.2
+tzdata==2025.1
+urllib3==2.1.0
+uvicorn==0.26.0
+wasabi==1.1.3
+weasel==0.4.1
+websocket-client==1.8.0
+Werkzeug==2.0.3
+Wikipedia-API==0.7.3
+wrapt==1.17.2
+wsproto==1.2.0
+xgboost==3.0.0
+xxhash==3.5.0
+yarl==1.9.4
+seaborn

backend/server.py

@@ -0,0 +1,600 @@
+from flask import Flask, request, jsonify, send_file, send_from_directory
+from flask_cors import CORS
+import pandas as pd
+import torch
+import os
+from datetime import datetime
+from tqdm import tqdm
+import logging
+from functools import lru_cache
+from typing import Optional, List, Dict, Any
+from utils.utils import _ensure_plot_saved
+
+os.environ["MPLBACKEND"] = "Agg"
+os.environ["QT_QPA_PLATFORM"] = "offscreen"
+
+logging.basicConfig(level=logging.INFO)
+
+from utils.sampling import rank_sample
+try:
+    from transformers import TextDataset, DataCollatorForLanguageModeling, Trainer, TrainingArguments
+    print("✓ transformers training components imported")
+except Exception as e:
+    print(f"✗ transformers training import failed: {e}")
+    def finetune(*args, **kwargs):
+        print("Warning: Transformers training components not available, skipping fine-tuning")
+        return None
+
+# 🤗 datasets
+try:
+    from datasets import (
+        load_dataset,
+        load_dataset_builder,
+        get_dataset_config_names,
+        get_dataset_split_names,
+        Features,
+    )
+    print("✓ datasets imported")
+except Exception as e:
+    print(f"✗ datasets import failed: {e}")
+    raise
+
+from utils.utils import (
+    generate_topk_samples,
+    evaluate_generated_outputs,
+    load_model_and_tokenizer,
+    generate_counterfactual_augmentations,
+)
+print("✓ utils imported")
+
+app = Flask(__name__)
+CORS(app)
+
+_MODELS = {}
+_CURRENT_DATASET = None
+_GENERATION_RESULTS = None
+
+@app.route('/data/<path:filename>')
+def serve_data(filename):
+    import os
+    from flask import Response
+    
+    print(f"[Static] Requested file: {filename}")
+    
+    data_dir = os.path.abspath('data')
+    file_path = os.path.join(data_dir, filename)
+    
+    print(f"[Static] Full path: {file_path}")
+    print(f"[Static] File exists: {os.path.exists(file_path)}")
+    
+    if not os.path.exists(file_path):
+        return "File not found", 404
+    
+    try:
+        with open(file_path, 'rb') as f:
+            file_data = f.read()
+        
+        if filename.endswith('.png'):
+            mimetype = 'image/png'
+        elif filename.endswith('.jpg') or filename.endswith('.jpeg'):
+            mimetype = 'image/jpeg'
+        elif filename.endswith('.csv'):
+            mimetype = 'text/csv'
+        else:
+            mimetype = 'application/octet-stream'
+        
+        print(f"[Static] Serving {len(file_data)} bytes as {mimetype}")
+        
+        return Response(file_data, mimetype=mimetype)
+        
+    except Exception as e:
+        print(f"[Static] Error reading file: {e}")
+        return f"Error reading file: {str(e)}", 500
+
+@app.route('/debug/files', methods=['GET'])
+def debug_files():
+    try:
+        data_dir = os.path.abspath('data')
+        if not os.path.exists(data_dir):
+            return jsonify({"error": "Data directory not found", "path": data_dir})
+        
+        files = []
+        for f in os.listdir(data_dir):
+            file_path = os.path.join(data_dir, f)
+            files.append({
+                "name": f,
+                "path": file_path,
+                "exists": os.path.exists(file_path),
+                "size": os.path.getsize(file_path) if os.path.exists(file_path) else 0
+            })
+        
+        return jsonify({
+            "data_directory": data_dir,
+            "files": files
+        })
+    except Exception as e:
+        return jsonify({"error": str(e)})
+
+def get_model(model_name: str):
+    if model_name in _MODELS:
+        print(f"Using cached model: {model_name}")
+        return _MODELS[model_name]
+    print(f"Loading new model: {model_name}")
+    tokenizer, model, device = load_model_and_tokenizer(model_name)
+    _MODELS[model_name] = (tokenizer, model, device)
+    return tokenizer, model, device
+
+
+@app.route('/health', methods=['GET'])
+def health_check():
+    return jsonify({
+        "status": "healthy",
+        "timestamp": datetime.now().isoformat(),
+        "loaded_models": list(_MODELS.keys()),
+        "dataset_loaded": _CURRENT_DATASET is not None,
+        "generation_results_available": _GENERATION_RESULTS is not None
+    })
+
+
+def _flatten_features(feats, prefix: str = "") -> List[str]:
+    cols: List[str] = []
+    try:
+        items = feats.items() if isinstance(feats, (Features, dict)) else feats.items()
+    except Exception:
+        try:
+            return list(feats.keys())
+        except Exception:
+            return cols
+    for name, sub in items:
+        full = f"{prefix}.{name}" if prefix else name
+        try:
+            if isinstance(sub, (Features, dict)):
+                cols += _flatten_features(sub, prefix=full)
+            else:
+                cols.append(full)
+        except Exception:
+            cols.append(full)
+    return cols
+
+@lru_cache(maxsize=256)
+def _get_dataset_fields_cached(dataset_id: str, config: Optional[str], split: str) -> List[str]:
+    try:
+        builder = load_dataset_builder(dataset_id, name=config)
+        feats = builder.info.features
+        fields = _flatten_features(feats)
+        return sorted(set(fields))
+    except Exception as e_builder:
+        try:
+            ds = load_dataset(dataset_id, name=config, split=split, streaming=True)
+            first = next(iter(ds.take(1)), None)
+            if first is None:
+                return []
+            fields = list(first.keys())
+            return sorted(set(fields))
+        except Exception as e_stream:
+            raise RuntimeError(f"builder_error={e_builder}; streaming_error={e_stream}")
+
+@app.route('/dataset/fields', methods=['GET'])
+def dataset_fields():
+    dataset_id = request.args.get('id')
+    cfg = request.args.get('config')
+    split = request.args.get('split', 'train')
+    if not dataset_id:
+        return jsonify({"error": "Missing required query param 'id'"}), 400
+    try:
+        fields = _get_dataset_fields_cached(dataset_id, cfg, split)
+        return jsonify({
+            "fields": fields,
+            "datasetId": dataset_id,
+            "config": cfg,
+            "split": split,
+            "source": "huggingface-builder" if fields else "unknown"
+        })
+    except Exception as e:
+        return jsonify({
+            "error": "Failed to fetch dataset fields",
+            "datasetId": dataset_id,
+            "config": cfg,
+            "split": split,
+            "detail": str(e)
+        }), 400
+
+@app.route('/dataset/meta', methods=['GET'])
+def dataset_meta():
+    dataset_id = request.args.get('id')
+    if not dataset_id:
+        return jsonify({"error": "Missing required query param 'id'"}), 400
+    try:
+        configs = get_dataset_config_names(dataset_id)
+    except Exception as e:
+        configs = []
+        logging.warning(f"get_dataset_config_names failed for {dataset_id}: {e}")
+    splits: List[str] = []
+    try:
+        if configs:
+            try:
+                b0 = load_dataset_builder(dataset_id, name=configs[0])
+                splits = sorted(list(b0.info.splits) or [])
+            except Exception:
+                splits = get_dataset_split_names(dataset_id, configs[0])
+        else:
+            try:
+                b = load_dataset_builder(dataset_id)
+                splits = sorted(list(b.info.splits) or [])
+            except Exception:
+                splits = get_dataset_split_names(dataset_id)
+    except Exception as e:
+        logging.warning(f"get splits failed for {dataset_id}: {e}")
+        splits = []
+    return jsonify({
+        "datasetId": dataset_id,
+        "configs": configs,
+        "splits": splits
+    })
+
+@app.route('/dataset/field-stats', methods=['GET'])
+def dataset_field_stats():
+    dataset_id = request.args.get('id')
+    cfg = request.args.get('config')
+    split = request.args.get('split', 'train')
+    field = request.args.get('field')
+    subfield = request.args.get('subfield')
+    if not dataset_id or not field:
+        return jsonify({"error": "Missing required query params 'id' or 'field'"}), 400
+    try:
+        ds = load_dataset(dataset_id, name=cfg, split=split, streaming=True)
+        max_rows = 50000
+        counter: Dict[str, Any] = {}
+        print(f"[field-stats] Computing stats for '{field}'" + (f" → '{subfield}'" if subfield else ""))
+        for i, row in enumerate(ds):
+            if i >= max_rows:
+                break
+            main_val = row.get(field)
+            if main_val is None:
+                continue
+            if subfield:
+                sub_val = row.get(subfield)
+                if sub_val is None:
+                    continue
+                counter.setdefault(main_val, {})
+                counter[main_val][sub_val] = counter[main_val].get(sub_val, 0) + 1
+            else:
+                counter[main_val] = counter.get(main_val, 0) + 1
+        return jsonify({
+            "field": field,
+            "subfield": subfield,
+            "datasetId": dataset_id,
+            "config": cfg,
+            "split": split,
+            "counts": counter
+        })
+    except Exception as e:
+        return jsonify({
+            "error": f"Failed to compute field stats: {str(e)}",
+            "datasetId": dataset_id,
+            "config": cfg,
+            "split": split,
+            "field": field,
+            "subfield": subfield
+        }), 500
+    
+def _parse_selected_groups_from_config(config: dict) -> List[str]:
+    raw = config.get('selectedCfFields', []) or []
+    out: List[str] = []
+    for s in raw:
+        s = (s or "").strip()
+        if not s:
+            continue
+        if "/" in s:
+            out.append(s.split("/")[-1])
+        else:
+            out.append(s)
+    seen = set()
+    uniq = []
+    for x in out:
+        if x not in seen:
+            uniq.append(x)
+            seen.add(x)
+    return uniq
+
+def stratified_sample_by_category(df: pd.DataFrame, category_col: str, groups: List[str], total_n: Optional[int]) -> pd.DataFrame:
+    if total_n is None or total_n <= 0:
+        return df
+
+    groups_present = [g for g in groups if g in df[category_col].unique()]
+    if not groups_present:
+        return df.sample(n=min(total_n, len(df)), random_state=42)
+
+    base_each = max(1, total_n // max(1, len(groups_present)))
+    remainder = max(0, total_n - base_each * len(groups_present))
+
+    parts = []
+    for g in groups_present:
+        gdf = df[df[category_col] == g]
+        need = min(base_each, len(gdf))
+        if need > 0:
+            parts.append(gdf.sample(n=need, random_state=42))
+
+    i = 0
+    while remainder > 0 and len(df) > 0:
+        g = groups_present[i % len(groups_present)]
+        gdf = df[df[category_col] == g]
+        if len(gdf) > 0:
+            parts.append(gdf.sample(n=1, replace=(len(gdf) < 1), random_state=42 + remainder))
+            remainder -= 1
+        i += 1
+
+    out = pd.concat(parts, ignore_index=True) if parts else pd.DataFrame(columns=df.columns)
+    if len(out) < total_n and len(df) > len(out):
+        rest = min(total_n - len(out), len(df) - len(out))
+        pool = df.drop(out.index, errors="ignore")
+        if len(pool) > 0 and rest > 0:
+            out = pd.concat([out, pool.sample(n=min(rest, len(pool)), random_state=777)], ignore_index=True)
+    return out
+
+def _pairwise_max_abs_diff(means: Dict[str, float]) -> float:
+    from itertools import combinations
+    keys = list(means.keys())
+    if len(keys) < 2:
+        return 0.0
+    diffs = [abs(means[a] - means[b]) for a, b in combinations(keys, 2)]
+    return float(max(diffs)) if diffs else 0.0
+
+def _mean_by_cat(df: pd.DataFrame, cats: List[str], score_col: str = "sentiment_score") -> Dict[str, float]:
+    out: Dict[str, float] = {}
+    for c in cats:
+        sub = df[df["category"] == c]
+        if len(sub) > 0:
+            out[c] = float(sub[score_col].mean())
+    return out
+
+@app.route('/pipeline', methods=['POST'])
+def run_pipeline():
+    """Run the complete pipeline with frontend JobConfig format"""
+    data = request.get_json() or {}
+    config = data.get('config', data) or {}
+    print("[DEBUG] Received config:", config)
+
+    dataset_id = config.get('dataset') or "AmazonScience/bold"
+    model_name = config.get('languageModel', 'openai-community/gpt2')
+    top_k = int(config.get('k', 5))
+    dataset_limit_raw = config.get('datasetLimit')
+    dataset_limit = int(dataset_limit_raw) if dataset_limit_raw is not None else None
+    num_cf_per_row = int(config.get('numCounterfactuals') or 3) 
+    tau = float(config.get('tau', 0.1))
+    iterations = int(config.get('iterations', 1000))
+    metric_target = config.get('metrictarget')
+
+    try:
+        results = {}
+        global _CURRENT_DATASET, _GENERATION_RESULTS
+
+        print("Pipeline Step 1: Loading data...")
+        ds = load_dataset(dataset_id, split="train")
+        df_full = pd.DataFrame(ds)[["domain", "name", "category", "prompts", "wikipedia"]].copy()
+
+        selected_groups = _parse_selected_groups_from_config(config)
+        present_all = sorted(df_full["category"].dropna().unique().tolist())
+
+        if selected_groups:
+            selected_groups = [g for g in selected_groups if g in present_all]
+            if len(selected_groups) < 2:
+                print(f"[Filter] Requested groups not enough in dataset (have {selected_groups}); fallback to ALL categories")
+                selected_groups = []
+        else:
+            print("[Filter] No groups requested from frontend; will use categories present after generation.")
+
+        df_pool = df_full[df_full["category"].isin(selected_groups)].copy() if selected_groups else df_full.copy()
+
+        df = stratified_sample_by_category(
+            df=df_pool,
+            category_col="category",
+            groups=selected_groups if selected_groups else sorted(df_pool["category"].unique().tolist()),
+            total_n=dataset_limit
+        )
+
+        print(f"[Pool] pool_size={len(df_pool)}, sampled={len(df)}")
+        print(f"[Pool] categories in pool: {sorted(df_pool['category'].unique().tolist())}")
+        print(f"[Pool] categories in sample: {sorted(df['category'].unique().tolist())}")
+
+        _CURRENT_DATASET = df
+        results['data_loaded'] = len(df)
+        print(f"Dataset loaded: {len(df)} rows")
+
+        print("Pipeline Step 2: Loading model...")
+        tokenizer, model, device = get_model(model_name)
+        results['model_loaded'] = model_name
+
+        print(f"Pipeline Step 3: Generating samples for {len(df)} entries...")
+        generation_results = generate_topk_samples(model, _CURRENT_DATASET, tokenizer, device, top_k=top_k)
+        task = config.get('classificationTask', 'sentiment') 
+        tox_choice = config.get('toxicityModelChoice', 'detoxify')
+
+        evaluated_results = evaluate_generated_outputs(
+            generation_results, device,
+            task=task,
+            toxicity_model_choice=tox_choice
+        )
+        _GENERATION_RESULTS = evaluated_results
+
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        os.makedirs("data", exist_ok=True)
+        output_file = f"data/pipeline_generation_{timestamp}.csv"
+        evaluated_results.to_csv(output_file, index=False)
+        results['generation_file'] = output_file
+        results['generation_samples'] = len(evaluated_results)
+        print("Pipeline Step 3.5: Counterfactual augmentation...")
+        augmented_results = generate_counterfactual_augmentations(
+            evaluated_results,
+            text_col="generated",
+            name_col="name",
+            category_col="category", 
+            num_cf_per_row=num_cf_per_row
+        )
+        augmented_file = f"data/pipeline_generation_cf_augmented_{timestamp}.csv"
+        augmented_results.to_csv(augmented_file, index=False)
+        results['counterfactual_file'] = augmented_file
+        results['counterfactual_added'] = len(augmented_results) - len(evaluated_results)
+        results['counterfactual_total'] = len(augmented_results)
+
+        present_after_gen = sorted(evaluated_results["category"].dropna().unique().tolist())
+        if not selected_groups:
+            selected_groups_used = present_after_gen
+        else:
+            selected_groups_used = [g for g in selected_groups if g in present_after_gen]
+            if len(selected_groups_used) < 2:
+                print(f"[Sampling] After generation only {selected_groups_used} present; expanding to all present categories")
+                selected_groups_used = present_after_gen
+
+        print(f"[Sampling] Using groups: {selected_groups_used}")
+
+        print("Debug: Checking data before sampling...")
+        print(f"Total evaluated results: {len(evaluated_results)}")
+        print(f"Categories in data: {present_after_gen}")
+        print(f"Names in data: {evaluated_results['name'].unique()}")
+
+        for cat in selected_groups_used:
+            cat_count = int((evaluated_results["category"] == cat).sum())
+            print(f"Category '{cat}': {cat_count} samples")
+
+        print(f"Pipeline Step 4: Rank sampling on original evaluated results...(iterations={iterations}, temp={tau})")
+        try:
+            best_sent_subset = rank_sample(evaluated_results, num_samples=iterations, temp=tau, target_value=metric_target)
+        except (ValueError, IndexError) as e:
+            print(f"Sampling failed: {e}")
+            mid_point = len(evaluated_results) // 2
+            best_sent_subset = evaluated_results.iloc[:mid_point].copy()
+
+        sent_file = f"data/pipeline_sent_subset_{timestamp}.csv"
+        best_sent_subset.to_csv(sent_file, index=False)
+
+        print(f"Pipeline Step 5: Rank sampling on CF-augmented results...(iterations={iterations}, temp={tau})")
+        try:
+            cf_best_sent_subset = rank_sample(augmented_results, num_samples=iterations, temp=tau, target_value=metric_target)
+        except (ValueError, IndexError) as e:
+            print(f"CF Sampling failed: {e}")
+            mid_point = len(augmented_results) // 2
+            cf_best_sent_subset = augmented_results.iloc[:mid_point].copy()
+
+        cf_sent_file = f"data/pipeline_cf_sent_subset_{timestamp}.csv"
+        cf_best_sent_subset.to_csv(cf_sent_file, index=False)
+
+        orig_means = _mean_by_cat(best_sent_subset, selected_groups_used)
+        final_mean_diff = _pairwise_max_abs_diff(orig_means)
+
+        cf_means = _mean_by_cat(cf_best_sent_subset, selected_groups_used)
+        cf_final_mean_diff = _pairwise_max_abs_diff(cf_means)
+
+        print("Pipeline Step 6: Plotting distributions...")
+
+        def _safe(s: str) -> str:
+            import re
+            return re.sub(r"[^A-Za-z0-9_.-]+", "_", s)
+
+        orig_sent_title = _safe(f"{timestamp}_original_distribution")
+        cf_sent_title   = _safe(f"{timestamp}_cf_distribution")
+
+        score_col = None
+        for c in [
+            "sentiment_score", "regard_score", "toxicity_score",
+            "stereotype_gender_score", "stereotype_religion_score",
+            "stereotype_profession_score", "stereotype_race_score",
+            "personality_score",
+        ]:
+            if c in best_sent_subset.columns:
+                score_col = c
+                break
+        if score_col is None:
+            raise KeyError(f"No score column found. Available: {list(best_sent_subset.columns)}")
+
+        orig_path = _ensure_plot_saved(
+            best_sent_subset, score_col, orig_sent_title,
+            group_col="category", target=metric_target
+        )
+        cf_path   = _ensure_plot_saved(
+            cf_best_sent_subset, score_col, cf_sent_title,
+            group_col="category", target=metric_target
+        )
+        print("[Plot check exists]", orig_path, os.path.exists(orig_path))
+        print("[Plot check exists]", cf_path,   os.path.exists(cf_path))
+
+        results['plots'] = {
+            'original_sentiment': f"/data/{orig_sent_title}.png",
+            'counterfactual_sentiment': f"/data/{cf_sent_title}.png",
+        }
+
+        print("[Plot urls]", results['plots'])
+
+        if config.get("enableFineTuning"):
+            print("Pipeline Step 7: Fine-tuning enabled, starting training...")
+
+            ft_cfg = config.get("finetuneParams", {}) or {}
+            epochs = int(ft_cfg.get("epochs", 3))
+            batch_size = int(ft_cfg.get("batchSize", 8))
+            lr = float(ft_cfg.get("learningRate", 5e-5))
+
+            input_csv = augmented_file  
+            ft_output_dir = f"data/ft_{timestamp}"
+            os.makedirs(ft_output_dir, exist_ok=True)
+
+            try:
+                from utils.finetune import finetune_gpt2_from_csv
+                finetune_gpt2_from_csv(
+                    csv_path=input_csv,
+                    output_dir=ft_output_dir,
+                    epochs=epochs,
+                    batch_size=batch_size,
+                    lr=lr
+                )
+                print(f"[Fine-tune] Saved fine-tuned model to {ft_output_dir}")
+                results["finetuned_model_dir"] = ft_output_dir
+                zip_base = f"data/ft_{timestamp}"
+                import shutil
+                zip_path = shutil.make_archive(zip_base, 'zip', ft_output_dir) 
+                results["finetuned_model_zip"] = f"/data/{os.path.basename(zip_path)}"
+            except Exception as fe:
+                print(f"[Fine-tune] Failed: {fe}")
+                results["finetuned_model_error"] = str(fe)
+
+
+        results.update({
+            'sampling_method': 'rank_sentiment_only',
+            'used_groups': selected_groups_used,
+            'sentiment_subset_file': sent_file,
+            'cf_sentiment_subset_file': cf_sent_file,
+            'sentiment_subset_size': len(best_sent_subset),
+            'cf_sentiment_subset_size': len(cf_best_sent_subset),
+            'config_used': config,
+            'metrics': {
+                'finalMeanDiff': final_mean_diff,
+                'cfFinalMeanDiff': cf_final_mean_diff,
+                'reductionPct': (0.0 if final_mean_diff == 0 else max(0.0, (final_mean_diff - cf_final_mean_diff) / abs(final_mean_diff) * 100.0)),
+                'stableCoverage': 100.0
+            }
+        })
+
+        return jsonify({
+            "status": "success",
+            "message": "Complete pipeline executed successfully (with counterfactual augmentation)",
+            "results": results,
+            "timestamp": timestamp
+        })
+
+    except Exception as e:
+        print(f"Error in pipeline: {str(e)}")
+        return jsonify({
+            "status": "error",
+            "message": f"Pipeline failed: {str(e)}"
+        }), 500
+
+
+if __name__ == '__main__':
+    os.makedirs("data", exist_ok=True)
+    print("Starting minimal Flask server...")
+    print("Available endpoints:")
+    print("  GET  /health - Health check")
+    print("  GET  /dataset/fields?id=<hf_id>[&config=...][&split=...] - List dataset fields")
+    print("  GET  /dataset/field-stats?id=...&field=... - Get value distribution of a field")
+    print("  GET  /dataset/meta?id=<hf_id> - List configs/splits")
+    print("  POST /pipeline - Run complete pipeline")
+    app.run(host='0.0.0.0', port=5001, debug=True, threaded=True)

backend/utils/finetune.py

@@ -0,0 +1,120 @@
+import os, math, random
+import pandas as pd
+import torch
+from typing import Optional
+from transformers import (AutoTokenizer, AutoModelForCausalLM, DataCollatorForLanguageModeling,
+                          Trainer, TrainingArguments)
+
+try:
+    from peft import LoraConfig, get_peft_model, TaskType
+    PEFT_AVAILABLE = True
+except Exception:
+    PEFT_AVAILABLE = False
+
+def build_text_column(df: pd.DataFrame) -> pd.Series:
+    cols = [c.lower() for c in df.columns]
+    lower_map = {c.lower(): c for c in df.columns}
+    if 'text' in cols:
+        return df[lower_map['text']].astype(str)
+    if 'prompt' in cols and 'generated' in cols:
+        pcol = lower_map['prompt']; rcol = lower_map['generated']
+        return df.apply(lambda r: f"### Instruction:\n{r[pcol]}\n\n### Response:\n{r[rcol]}\n", axis=1)
+
+    if 'generated' in cols:
+        return df[lower_map['generated']].astype(str)
+
+    raise ValueError("CSV 缺少可用欄位：請提供 text，或 prompt+generated，或 generated。")
+
+def finetune_gpt2_from_csv(
+    csv_path: str,
+    base_model: str = "gpt2",
+    output_dir: str = "data/ft_gpt2_out",
+    train_split: float = 0.9,
+    epochs: int = 3,
+    lr: float = 5e-5,
+    batch_size: int = 2,
+    use_lora: bool = False,
+    lora_r: int = 8,
+    lora_alpha: int = 16,
+    lora_dropout: float = 0.05,
+    seed: int = 42,
+    max_length: int = 512,
+) -> dict:
+    os.makedirs(output_dir, exist_ok=True)
+    random.seed(seed); torch.manual_seed(seed)
+
+    df = pd.read_csv(csv_path)
+    texts = build_text_column(df).fillna("").tolist()
+
+    tokenizer = AutoTokenizer.from_pretrained(base_model)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    model = AutoModelForCausalLM.from_pretrained(base_model)
+
+    if use_lora:
+        if not PEFT_AVAILABLE:
+            print("PEFT 未安裝，改為全參數微調")
+        else:
+            lconf = LoraConfig(
+                r=lora_r, lora_alpha=lora_alpha, lora_dropout=lora_dropout,
+                task_type=TaskType.CAUSAL_LM, target_modules=["c_attn","c_proj","q_attn"]  # 視模型而定
+            )
+            model = get_peft_model(model, lconf)
+
+    def tokenize(example_texts):
+        return tokenizer(example_texts, truncation=True, max_length=max_length)
+
+    split_idx = int(len(texts) * train_split)
+    train_texts, val_texts = texts[:split_idx], texts[split_idx:] or texts[: max(1, len(texts)//10)]
+
+    train_enc = tokenize(train_texts)
+    val_enc   = tokenize(val_texts)
+
+    collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)
+
+    class SimpleDS(torch.utils.data.Dataset):
+        def __init__(self, enc): self.enc = enc
+        def __len__(self): return len(self.enc["input_ids"])
+        def __getitem__(self, idx):
+            return {k: torch.tensor(v[idx]) for k, v in self.enc.items()}
+
+    train_ds, val_ds = SimpleDS(train_enc), SimpleDS(val_enc)
+
+    args = TrainingArguments(
+        output_dir=output_dir,
+        per_device_train_batch_size=batch_size,
+        per_device_eval_batch_size=batch_size,
+        num_train_epochs=epochs,
+        learning_rate=lr,
+        warmup_ratio=0.03,
+        weight_decay=0.01,
+        logging_steps=20,
+        eval_strategy="steps",
+        eval_steps=100,
+        save_strategy="steps",
+        save_steps=100,
+        save_total_limit=2,
+        fp16=torch.cuda.is_available(),
+        bf16=torch.cuda.is_bf16_supported() if hasattr(torch.cuda, "is_bf16_supported") else False,
+        report_to=[],
+    )
+
+    trainer = Trainer(
+        model=model,
+        args=args,
+        train_dataset=train_ds,
+        eval_dataset=val_ds,
+        data_collator=collator,
+    )
+
+    trainer.train()
+    trainer.save_model(output_dir)
+    tokenizer.save_pretrained(output_dir)
+
+    return {
+        "output_dir": output_dir,
+        "train_size": len(train_ds),
+        "eval_size": len(val_ds),
+        "perplexity": math.exp(trainer.evaluate()["eval_loss"]) if "eval_loss" in trainer.evaluate() else None
+    }

backend/utils/sampling.py

@@ -0,0 +1,120 @@
+import numpy as np
+import pandas as pd
+from tqdm import tqdm
+from typing import List, Optional
+
+def rank_sample(
+    df: pd.DataFrame,
+    name_col: str = "name",
+    category_col: str = "category",
+    sentiment_col: str = "sentiment_score",
+    groups: Optional[List[str]] = None,
+    num_samples: int = 1000,
+    temp: float = 1.0,
+    target_value: float = 0.5,
+) -> pd.DataFrame:
+
+    df = df.copy()
+    
+    for col in [name_col, category_col, sentiment_col]:
+        if col not in df.columns:
+            raise ValueError(f"Column '{col}' not found in DataFrame")
+    
+    df = df.dropna(subset=[name_col, category_col, sentiment_col])
+
+    if groups:
+        available_groups = df[category_col].unique()
+        valid_groups = [g for g in groups if g in available_groups]
+        if len(valid_groups) < 2:
+            print(f"Warning: Only {len(valid_groups)} groups available from {groups}")
+            groups = None
+        else:
+            groups = valid_groups
+            df = df[df[category_col].isin(groups)].copy()
+    
+    final_groups = df[category_col].unique()
+    if len(final_groups) < 2:
+        print(f"Error: Only {len(final_groups)} groups in data, need at least 2")
+        return df.groupby(name_col).first().reset_index()
+    
+    print(f"Sampling with groups: {sorted(final_groups)}")
+    print(f"Target value for deviation calculation: {target_value}")
+    
+    df["sentiment_deviation"] = (df[sentiment_col] - target_value).abs()
+    df["sentiment_rank"] = df.groupby(name_col)["sentiment_deviation"].rank(method="first", ascending=True)
+
+    def softmax_weights(ranks: np.ndarray, temp: float) -> np.ndarray:
+        t = float(temp) if temp and temp > 1e-8 else 1e-8
+        x = -ranks / t
+        x = x - np.max(x) 
+        exps = np.exp(x)
+        s = exps.sum()
+        return exps / s if np.isfinite(s) and s > 0 else np.ones_like(exps) / len(exps)
+
+    def objective_max_pairwise_diff(frame: pd.DataFrame) -> float:
+        g = frame.groupby(category_col)[sentiment_col].mean().dropna()
+        if len(g) < 2:
+            return np.inf
+        vals = g.values
+        diffs = np.abs(vals[:, None] - vals[None, :])
+        return float(np.max(diffs))
+
+    best_subset = None
+    best_obj = np.inf
+    valid_samples = 0
+
+    unique_names = df[name_col].nunique()
+    print(f"Total unique names: {unique_names}")
+    
+    for i in tqdm(range(num_samples), desc="Sampling"):
+        try:
+            sampled_rows = []
+            
+            for name, group in df.groupby(name_col):
+                if len(group) == 0:
+                    continue
+                
+                ranks = group["sentiment_rank"].to_numpy(dtype=float)
+                if len(ranks) == 0:
+                    continue
+                
+                w = softmax_weights(ranks, temp=temp)
+                idx = np.random.choice(group.index, p=w)
+                sampled_rows.append(df.loc[idx])
+            
+            if len(sampled_rows) == 0:
+                continue
+                
+            subset = pd.DataFrame(sampled_rows)
+
+            subset_groups = subset[category_col].unique()
+            if len(subset_groups) < 2:
+                continue
+                
+            obj = objective_max_pairwise_diff(subset)
+            
+            if np.isfinite(obj):
+                valid_samples += 1
+                if obj < best_obj:
+                    best_obj = obj
+                    best_subset = subset.copy()
+                    
+                    if valid_samples % 100 == 0 or valid_samples <= 10:
+                        group_means = subset.groupby(category_col)[sentiment_col].mean()
+                        print(f"Sample {valid_samples}: obj={obj:.4f}, groups={dict(group_means)}")
+        
+        except Exception as e:
+            print(f"Error in sample {i}: {e}")
+            continue
+    
+    print(f"Valid samples: {valid_samples}/{num_samples}")
+    print(f"Best objective: {best_obj:.4f}")
+    
+    if best_subset is None or len(best_subset) == 0:
+        print("Warning: No valid samples found, returning fallback subset")
+        best_subset = df.groupby(name_col).first().reset_index()
+    
+    final_group_counts = best_subset[category_col].value_counts()
+    print(f"Final subset group distribution: {dict(final_group_counts)}")
+    
+    return best_subset

backend/utils/utils.py

@@ -0,0 +1,552 @@
+from transformers import TextDataset,DataCollatorForLanguageModeling,Trainer,TrainingArguments
+import torch
+import pandas as pd
+from tqdm import tqdm
+import torch.nn.functional as F
+from transformers import AutoTokenizer, AutoModelForSequenceClassification, pipeline
+import matplotlib.pyplot as plt
+import seaborn as sns
+import numpy as np
+import os
+import sys
+from transformers import (
+    AutoTokenizer,
+    AutoModelForCausalLM,
+    GPT2LMHeadModel,
+    GPT2Tokenizer,
+)
+
+def load_model_and_tokenizer(model_name: str):
+    if torch.cuda.is_available():
+        device = torch.device("cuda")
+    elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available():  # macOS Apple Silicon
+        device = torch.device("mps")
+    else:
+        device = torch.device("cpu")
+
+    gpt2_aliases = {"gpt2", "openai-community/gpt2", "holistic-ai/gpt2-EMGSD"}
+
+    try:
+        if model_name in gpt2_aliases:
+            tokenizer = GPT2Tokenizer.from_pretrained(model_name)
+            if tokenizer.pad_token is None and tokenizer.eos_token is not None:
+                tokenizer.pad_token = tokenizer.eos_token
+            model = GPT2LMHeadModel.from_pretrained(model_name)
+            if getattr(model.config, "pad_token_id", None) is None and getattr(model.config, "eos_token_id", None) is not None:
+                model.config.pad_token_id = model.config.eos_token_id
+        else:
+            tokenizer = AutoTokenizer.from_pretrained(model_name)
+            if tokenizer.pad_token is None and tokenizer.eos_token is not None:
+                tokenizer.pad_token = tokenizer.eos_token
+            model = AutoModelForCausalLM.from_pretrained(model_name)
+            if getattr(model.config, "pad_token_id", None) is None and getattr(model.config, "eos_token_id", None) is not None:
+                model.config.pad_token_id = model.config.eos_token_id
+
+        model.to(device)
+        return tokenizer, model, device
+    except Exception as e:
+        raise RuntimeError(f"Failed to load model '{model_name}': {e}")
+    
+def finetune(train_texts, tokenizer, model, num_epochs=20, output_dir='./data'):
+    train_path = f"data/train.txt"
+
+    with open(train_path, "w", encoding="utf-8") as f:
+        for text in train_texts:
+            f.write(text.strip() + "\n")
+
+    train_dataset = TextDataset(tokenizer=tokenizer, file_path=train_path, block_size=128)
+    data_collator = DataCollatorForLanguageModeling(tokenizer=tokenizer, mlm=False)
+
+    training_args = TrainingArguments(
+        output_dir=output_dir,
+        overwrite_output_dir=True,
+        per_device_train_batch_size=1,
+        num_train_epochs=num_epochs,
+        save_steps=500,
+        save_total_limit=2,
+        logging_dir='./logs',
+        logging_steps=10,
+        report_to="none"
+    )
+
+    trainer = Trainer(
+        model=model,
+        args=training_args,
+        data_collator=data_collator,
+        train_dataset=train_dataset,
+    )
+
+    trainer.train()
+
+    return model
+
+def generate_topk_samples(model, df_table, tokenizer, device, top_k=10):
+    model.eval()
+    flat_results = []
+
+    df_table["prompts"] = df_table["prompts"].apply(lambda x: x[0] if isinstance(x, list) else x)
+
+    for idx, row in tqdm(df_table.iterrows(), total=len(df_table), desc="Generating samples"):
+        prompt = row["prompts"]
+
+        inputs = tokenizer(
+            prompt,
+            return_tensors="pt",
+            truncation=True,
+            padding=True
+        ).to(device)
+
+        with torch.no_grad():
+            outputs = model.generate(
+                input_ids=inputs["input_ids"],
+                attention_mask=inputs["attention_mask"],
+                do_sample=True,
+                top_k=top_k,
+                max_new_tokens=20,
+                top_p=1.0,
+                num_return_sequences=top_k,
+                pad_token_id=tokenizer.eos_token_id
+            )
+
+        for out in outputs:
+            full_text = tokenizer.decode(out, skip_special_tokens=True).strip()
+            flat_results.append({
+                "domain": row["domain"],
+                "name": row["name"],
+                "category": row["category"],
+                "prompts": prompt,
+                "wikipedia": row["wikipedia"],
+                "generated": full_text
+            })
+
+    return pd.DataFrame(flat_results)
+
+
+def evaluate_generated_outputs(
+    table: pd.DataFrame,
+    device,
+    task: str = "sentiment",
+    toxicity_model_choice: str = "detoxify",
+    text_col: str = "generated",
+) -> pd.DataFrame:
+
+    assert text_col in table.columns, f"'{text_col}' not found in table columns"
+
+    pipe_device = 0 if (isinstance(device, torch.device) and device.type == "cuda") else -1
+
+    df = table.copy()
+    texts = df[text_col].fillna("").astype(str).tolist()
+
+    task = (task or "sentiment").lower()
+
+    if task == "sentiment":
+        print("Using default sentiment classifier: lxyuan/distilbert-base-multilingual-cased-sentiments-student")
+        tok = AutoTokenizer.from_pretrained("lxyuan/distilbert-base-multilingual-cased-sentiments-student")
+        mdl = AutoModelForSequenceClassification.from_pretrained("lxyuan/distilbert-base-multilingual-cased-sentiments-student").to(device).eval()
+
+        scores = []
+        for text in tqdm(texts, desc="Scoring (sentiment)"):
+            if not text.strip():
+                scores.append(0.5)
+                continue
+            inputs = tok(text, return_tensors="pt", truncation=True, padding=True).to(device)
+            with torch.no_grad():
+                logits = mdl(**inputs).logits
+                probs = F.softmax(logits, dim=1).squeeze(0).tolist()
+                val = (probs[2] - probs[0] + 1.0) / 2.0
+            scores.append(float(val))
+
+        df["sentiment_score"] = scores
+        return df
+
+    elif task == "regard":
+        print("Using default regard classifier: sasha/regardv3")
+        clf = pipeline("text-classification", model="sasha/regardv3", device=pipe_device, top_k=None)
+
+        def _safe_relabel(text: str):
+            try:
+                out = clf(text)
+                if isinstance(out, list):
+                    out = out[0] if out else {}
+                if isinstance(out, dict) and "label" in out and "score" in out:
+                    return {out["label"].lower(): float(out["score"])}
+                if isinstance(out, list) and out and isinstance(out[0], dict) and "label" in out[0]:
+                    d = {}
+                    for item in out:
+                        d[item["label"].lower()] = float(item["score"])
+                    return d
+            except Exception:
+                pass
+            return {"positive": 0.5, "negative": 0.5}
+
+        temp = []
+        for text in tqdm(texts, desc="Scoring (regard)"):
+            res = _safe_relabel(text)
+            pos = float(res.get("positive", 0.5))
+            neg = float(res.get("negative", 0.5))
+            temp.append(pos - neg + 1.0)
+
+        df["regard_score"] = temp
+        df["sentiment_score"] = df["regard_score"]
+        return df
+
+    elif task == "stereotype":
+        print("Using default stereotype classifier: holistic-ai/stereotype-deberta-v3-base-tasksource-nli")
+        clf = pipeline("text-classification", model="holistic-ai/stereotype-deberta-v3-base-tasksource-nli", device=pipe_device, top_k=None)
+
+        def _safe_relabel(text: str):
+            try:
+                out = clf(text)
+                if isinstance(out, list) and out and isinstance(out[0], dict) and "label" in out[0]:
+                    d = {}
+                    for item in out:
+                        d[item["label"].lower()] = float(item["score"])
+                    return d
+                if isinstance(out, dict) and "label" in out:
+                    return {out["label"].lower(): float(out.get("score", 0.0))}
+            except Exception:
+                pass
+            return {
+                "stereotype_gender": 0.0,
+                "stereotype_religion": 0.0,
+                "stereotype_profession": 0.0,
+                "stereotype_race": 0.0,
+            }
+
+        g_list, r_list, p_list, race_list = [], [], [], []
+        for text in tqdm(texts, desc="Scoring (stereotype)"):
+            d = _safe_relabel(text)
+            g_list.append(float(d.get("stereotype_gender", 0.0)))
+            r_list.append(float(d.get("stereotype_religion", 0.0)))
+            p_list.append(float(d.get("stereotype_profession", 0.0)))
+            race_list.append(float(d.get("stereotype_race", 0.0)))
+
+        df["stereotype_gender_score"] = g_list
+        df["stereotype_religion_score"] = r_list
+        df["stereotype_profession_score"] = p_list
+        df["stereotype_race_score"] = race_list
+
+        df["sentiment_score"] = df["stereotype_gender_score"]
+        return df
+
+    elif task == "personality":
+        print("Using default personality classifier: Navya1602/editpersonality_classifier")
+        clf = pipeline("text-classification", model="Navya1602/editpersonality_classifier", device=pipe_device, top_k=None)
+
+        traits = ["extraversion", "neuroticism", "agreeableness", "conscientiousness", "openness"]
+
+        def _safe_relabel(text: str):
+            try:
+                out = clf(text)
+                if isinstance(out, list) and out and isinstance(out[0], dict) and "label" in out[0]:
+                    d = {}
+                    for item in out:
+                        d[item["label"].lower()] = float(item["score"])
+                    return d
+                if isinstance(out, dict) and "label" in out:
+                    return {out["label"].lower(): float(out.get("score", 0.0))}
+            except Exception:
+                pass
+            return {t: 0.2 for t in traits}
+
+        cols = {t: [] for t in traits}
+        for text in tqdm(texts, desc="Scoring (personality)"):
+            d = _safe_relabel(text)
+            for t in traits:
+                cols[t].append(float(d.get(t, 0.2)))
+
+        for t in traits:
+            df[f"{t}_score"] = cols[t]
+
+        df["sentiment_score"] = df[[f"{t}_score" for t in traits]].mean(axis=1)
+        return df
+
+    elif task == "toxicity":
+        if toxicity_model_choice == "detoxify":
+            print("Using unitary/toxic-bert model for toxicity classification")
+            clf = pipeline("text-classification", model="unitary/toxic-bert", device=pipe_device, top_k=None)
+            def _get_toxic_prob(text: str) -> float:
+                try:
+                    out = clf(text)
+                    if isinstance(out, list) and out:
+                        d = {it["label"].lower(): float(it["score"]) for it in out}
+                        return float(d.get("toxic", d.get("toxic/overall", 0.0)))
+                    if isinstance(out, dict) and "label" in out:
+                        return float(out["score"]) if out["label"].lower() == "toxic" else 0.0
+                except Exception:
+                    pass
+                return 0.0
+        elif toxicity_model_choice == "junglelee":
+            print("Using JungleLee/bert-toxic-comment-classification for toxicity classification")
+            clf = pipeline("text-classification", model="JungleLee/bert-toxic-comment-classification", device=pipe_device)
+            def _get_toxic_prob(text: str) -> float:
+                try:
+                    out = clf(text)
+                    if isinstance(out, dict):
+                        lbl = out.get("label", "").lower()
+                        score = float(out.get("score", 0.0))
+                        return score if "toxic" in lbl else 0.0
+                    if isinstance(out, list) and out:
+                        for it in out:
+                            if "toxic" in it.get("label", "").lower():
+                                return float(it.get("score", 0.0))
+                except Exception:
+                    pass
+                return 0.0
+        else:
+            raise ValueError("Invalid toxicity_model_choice. Choose 'detoxify' or 'junglelee'.")
+
+        tox = []
+        for text in tqdm(texts, desc="Scoring (toxicity)"):
+            tox.append(_get_toxic_prob(text))
+
+        df["toxicity_score"] = tox
+        df["sentiment_score"] = df["toxicity_score"]
+        return df
+
+    else:
+        raise ValueError(f"Unknown task '{task}'. Use one of: sentiment | regard | stereotype | personality | toxicity")
+
+
+import numpy as np
+import pandas as pd
+from typing import List, Dict, Optional
+
+def _generate_cross_category_cf(base_df, text_col, name_col, category_col, num_cf_per_row):
+    categories = base_df[category_col].unique().tolist()
+    category_names = {}
+    
+    for cat in categories:
+        category_names[cat] = base_df[base_df[category_col] == cat][name_col].unique().tolist()
+    
+    print(f"Categories for CF generation: {[f'{cat}({len(names)})' for cat, names in category_names.items()]}")
+    
+    cf_rows = []
+    for idx, row in base_df.iterrows():
+        original_text = row[text_col]
+        original_name = row[name_col]
+        original_category = row[category_col]
+        original_name_clean = original_name.replace("_", " ")
+        
+        other_categories = [cat for cat in categories if cat != original_category]
+        
+        for target_category in other_categories:
+            target_names = category_names[target_category]
+            
+            if len(target_names) == 0:
+                continue
+ 
+            num_to_sample = min(num_cf_per_row // len(other_categories) + 1, len(target_names))
+            if num_to_sample == 0:
+                continue
+                
+            sampled_names = np.random.choice(target_names, size=num_to_sample, replace=False)
+            
+            for new_name in sampled_names:
+                new_name_clean = new_name.replace("_", " ")
+                
+                new_text = original_text.replace(original_name_clean, new_name_clean, 1)
+                
+                if new_text == original_text:
+                    original_parts = original_name_clean.split()
+                    for part in original_parts:
+                        if len(part) > 2: 
+                            new_text = original_text.replace(part, new_name_clean, 1)
+                            if new_text != original_text:
+                                break
+
+                if new_text == original_text:
+                    continue
+                
+                new_row = row.copy()
+                new_row[name_col] = new_name
+                new_row[text_col] = new_text
+                new_row[category_col] = target_category
+                new_row["original_category"] = original_category
+                new_row["cf_type"] = f"{original_category}->{target_category}"
+                cf_rows.append(new_row)
+    
+    counterfactual_df = pd.DataFrame(cf_rows)
+    
+    if len(counterfactual_df) > 0:
+        cf_stats = counterfactual_df["cf_type"].value_counts()
+        print(f"CF generation stats:")
+        for cf_type, count in cf_stats.items():
+            print(f"  {cf_type}: {count}")
+    
+    augmented_df = pd.concat([base_df, counterfactual_df], ignore_index=True)
+    
+    print(f"\nAugmentation Finished: Original {len(base_df)} Added {len(counterfactual_df)} ")
+    print(f"Total data len: {len(augmented_df)}")
+    
+    return augmented_df
+
+def auto_detect_cf_method(base_df, category_col="category"):
+    categories = set(base_df[category_col].unique())
+    
+    if {"American_actors", "American_actresses"}.issubset(categories):
+        return "actors_actresses"
+    else:
+        return "cross_category"
+
+class Tee:
+    def __init__(self, *streams):
+        self.streams = streams
+    def write(self, data):
+        for stream in self.streams:
+            stream.write(data)
+            stream.flush()
+    def flush(self):
+        for stream in self.streams:
+            stream.flush()
+
+def generate_counterfactual_augmentations(base_df, text_col="generated", name_col="name", category_col="category", num_cf_per_row=3):
+    categories = base_df[category_col].unique().tolist()
+    category_names = {}
+    
+    for cat in categories:
+        category_names[cat] = base_df[base_df[category_col] == cat][name_col].unique().tolist()
+    
+    print(f"Categories for CF generation: {[f'{cat}({len(names)})' for cat, names in category_names.items()]}")
+    
+    if "American_actors" in categories and "American_actresses" in categories:
+        return _generate_actors_actresses_cf(base_df, text_col, name_col, category_col, num_cf_per_row, category_names)
+    else:
+        return _generate_cross_category_cf(base_df, text_col, name_col, category_col, num_cf_per_row, category_names)
+
+def _generate_actors_actresses_cf(base_df, text_col, name_col, category_col, num_cf_per_row, category_names):
+    male_names = category_names.get("American_actors", [])
+    female_names = category_names.get("American_actresses", [])
+    
+    cf_rows = []
+    for idx, row in base_df.iterrows():
+        original_text = row[text_col]
+        original_name = row[name_col]
+        category = row[category_col]
+        original_name_clean = original_name.replace("_", " ")
+        
+        if category == "American_actors":
+            swap_pool = female_names
+            new_category = "American_actresses"
+        elif category == "American_actresses":
+            swap_pool = male_names
+            new_category = "American_actors"
+        else:
+            continue
+            
+        if len(swap_pool) == 0:
+            continue
+            
+        sampled_names = np.random.choice(swap_pool, size=min(num_cf_per_row, len(swap_pool)), replace=False)
+        
+        for new_name in sampled_names:
+            new_name_clean = new_name.replace("_", " ")
+            new_text = original_text.replace(original_name_clean, new_name_clean, 1)
+            
+            if new_text == original_text:
+                continue
+                
+            new_row = row.copy()
+            new_row[name_col] = new_name
+            new_row[text_col] = new_text
+            new_row[category_col] = new_category
+            new_row["original_category"] = category
+            cf_rows.append(new_row)
+    
+    counterfactual_df = pd.DataFrame(cf_rows)
+    augmented_df = pd.concat([base_df, counterfactual_df], ignore_index=True)
+    
+    print(f"\nAugmentation Finished: Original {len(base_df)} Added {len(counterfactual_df)} ")
+    print(f"Total data len: {len(augmented_df)}")
+    return augmented_df
+
+def _generate_cross_category_cf(base_df, text_col, name_col, category_col, num_cf_per_row, category_names):
+    categories = list(category_names.keys())
+    
+    cf_rows = []
+    for idx, row in base_df.iterrows():
+        original_text = row[text_col]
+        original_name = row[name_col]
+        original_category = row[category_col]
+        original_name_clean = original_name.replace("_", " ")
+        
+        other_categories = [cat for cat in categories if cat != original_category]
+        
+        for target_category in other_categories:
+            target_names = category_names[target_category]
+            
+            if len(target_names) == 0:
+                continue
+                
+            num_to_sample = min(max(1, num_cf_per_row // len(other_categories)), len(target_names))
+            sampled_names = np.random.choice(target_names, size=num_to_sample, replace=False)
+            
+            for new_name in sampled_names:
+                new_name_clean = new_name.replace("_", " ")
+                
+                new_text = original_text.replace(original_name_clean, new_name_clean, 1)
+                
+                if new_text == original_text:
+                    original_parts = original_name_clean.split()
+                    for part in original_parts:
+                        if len(part) > 2:
+                            new_text = original_text.replace(part, new_name_clean, 1)
+                            if new_text != original_text:
+                                break
+                
+                if new_text == original_text:
+                    continue
+                
+                new_row = row.copy()
+                new_row[name_col] = new_name
+                new_row[text_col] = new_text
+                new_row[category_col] = target_category
+                new_row["original_category"] = original_category
+                cf_rows.append(new_row)
+    
+    counterfactual_df = pd.DataFrame(cf_rows)
+    augmented_df = pd.concat([base_df, counterfactual_df], ignore_index=True)
+    
+    print(f"\nAugmentation Finished: Original {len(base_df)} Added {len(counterfactual_df)} ")
+    print(f"Total data len: {len(augmented_df)}")
+    
+    return augmented_df
+
+def _ensure_plot_saved(
+    df,
+    score_col: str,
+    basename: str,
+    group_col: str = None,
+    target: float = None,
+    bins: int = 30,
+) -> str:
+    os.makedirs("data", exist_ok=True)
+    path = os.path.join("data", f"{basename}.png")
+
+    plt.figure(figsize=(8, 5))
+    data = df[score_col].dropna().values
+
+    if group_col and group_col in df.columns:
+        for g, sub in df.groupby(group_col):
+            vals = sub[score_col].dropna().values
+            if len(vals) == 0:
+                continue
+            plt.hist(vals, bins=bins, alpha=0.4, label=f"{g} (n={len(vals)}, μ={np.mean(vals):.3f})", density=True)
+    else:
+        plt.hist(data, bins=bins, alpha=0.6, density=True, label=f"All (n={len(data)}, μ={np.mean(data):.3f})")
+
+    if len(data):
+        m = float(np.mean(data))
+        plt.axvline(m, linestyle="--", linewidth=2, label=f"mean={m:.3f}")
+
+    if target is not None:
+        plt.axvline(target, linestyle="-.", linewidth=2, label=f"target={target:.3f}")
+
+    plt.xlabel(score_col)
+    plt.ylabel("density")
+    plt.title(basename.replace("_", " "))
+    plt.legend(loc="best")
+    plt.tight_layout()
+    plt.savefig(path, dpi=160)
+    plt.close()
+    return path

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/README.md

@@ -0,0 +1,69 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      ...tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      ...tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      ...tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { globalIgnores } from 'eslint/config'
+
+export default tseslint.config([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite + React + TS</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "lucide-react": "^0.542.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "recharts": "^3.1.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.33.0",
+    "@tailwindcss/forms": "^0.5.10",
+    "@types/react": "^19.1.10",
+    "@types/react-dom": "^19.1.7",
+    "@vitejs/plugin-react": "^5.0.0",
+    "autoprefixer": "^10.4.21",
+    "eslint": "^9.33.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.3.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^3.4.17",
+    "typescript": "~5.8.3",
+    "typescript-eslint": "^8.39.1",
+    "vite": "^7.1.2"
+  }
+}

frontend/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

frontend/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

frontend/src/App.tsx

@@ -0,0 +1,78 @@
+import { useState, Suspense, lazy } from 'react';
+import { Target } from 'lucide-react';
+import type { JobConfig, Extras } from './types';
+import { JobRunnerProvider, useJobRunner } from './hooks/JobRunnerProvider';
+
+const ConfigPage  = lazy(() => import('./pages/ConfigPage'));
+const ResultsPage = lazy(() => import('./pages/ResultsPage'));
+
+type Tab = 'config'|'results'|'reports';
+
+function AppInner() {
+  const [tab, setTab] = useState<Tab>('config');
+  const { start } = useJobRunner();
+
+  const run = (cfg: JobConfig, extras: Extras) => {
+    start(cfg, extras);
+    setTab('results');
+  };
+
+  const tabBtn = (active: boolean) =>
+    `relative px-4 py-2 rounded-xl text-sm font-medium transition-all ${
+      active
+        ? 'text-white bg-gradient-to-r from-indigo-600 via-violet-600 to-fuchsia-600 shadow-lg shadow-indigo-600/20'
+        : 'text-slate-600 hover:text-slate-800 bg-white/70 backdrop-blur border border-white/30 hover:shadow-md'
+    }`;
+
+  return (
+    <div className="min-h-screen bg-[radial-gradient(1200px_800px_at_20%_-10%,#c7d2fe_0%,transparent_60%),radial-gradient(1200px_800px_at_120%_20%,#fbcfe8_0%,transparent_55%)] bg-slate-50">
+      <header className="sticky top-0 z-50">
+        <div className="backdrop-blur-xl bg-white/60 border-b border-white/40 shadow-[0_10px_30px_-12px_rgba(30,41,59,0.25)] supports-[backdrop-filter]:bg-white/40">
+          <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 h-16 flex items-center justify-between">
+            <div className="flex items-center gap-3">
+              <div className="p-2 rounded-xl bg-gradient-to-br from-indigo-600 to-fuchsia-600 shadow-md shadow-indigo-600/30">
+                <Target className="w-6 h-6 text-white" />
+              </div>
+              <div>
+                <h1 className="text-lg sm:text-xl font-bold tracking-tight text-slate-900">AAAI Demo</h1>
+                <p className="text-xs text-slate-600">Rank Sampling</p>
+              </div>
+            </div>
+
+            <div className="hidden sm:flex items-center gap-2">
+              <span className="px-3 py-1 rounded-full text-xs font-medium bg-emerald-50 text-emerald-700 border border-emerald-200">System Health</span>
+              <span className="px-3 py-1 rounded-full text-xs font-medium bg-slate-100 text-slate-700 border border-slate-200">v1.0.0</span>
+            </div>
+          </div>
+        </div>
+
+        <div className="border-b border-white/40 bg-white/30 backdrop-blur supports-[backdrop-filter]:bg-white/20">
+          <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-3 flex gap-3">
+            <button className={tabBtn(tab==='config')}  onClick={() => setTab('config')}>Config Setting</button>
+            <button className={tabBtn(tab==='results')} onClick={() => setTab('results')}>Results</button>
+          </div>
+        </div>
+      </header>
+
+      <main className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
+        <Suspense fallback={
+          <div className="p-8 rounded-2xl border border-white/30 bg-white/60 backdrop-blur text-slate-600">
+            Loading
+          </div>
+        }>
+          {/* 改成把 extras 一起傳 */}
+          {tab === 'config'  && <ConfigPage onRun={run} />}
+          {tab === 'results' && <ResultsPage />}
+        </Suspense>
+      </main>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <JobRunnerProvider>
+      <AppInner />
+    </JobRunnerProvider>
+  );
+}

frontend/src/components/MetricCard.tsx

@@ -0,0 +1,29 @@
+// src/components/MetricCard.tsx
+import React from 'react';
+import type { ReactNode } from 'react';
+import { TrendingDown, TrendingUp } from 'lucide-react';
+
+export default function MetricCard({
+  title, value, change, positive, icon, description
+}: {
+  title: string; value: string; change?: string; positive?: boolean; icon: ReactNode; description?: string;
+}) {
+  return (
+    <div className="bg-white rounded-lg shadow-sm border p-6 hover:shadow-md transition-shadow">
+      <div className="flex items-center justify-between">
+        <div className="flex-1">
+          <p className="text-sm font-medium text-gray-600">{title}</p>
+          <p className="text-2xl font-bold text-gray-900 mt-1">{value}</p>
+          {change && (
+            <div className="flex items-center mt-2">
+              {positive ? <TrendingDown className="w-4 h-4 text-green-500 mr-1" /> : <TrendingUp className="w-4 h-4 text-red-500 mr-1" />}
+              <span className={`text-sm font-medium ${positive ? 'text-green-600' : 'text-red-600'}`}>{change}</span>
+            </div>
+          )}
+          {description && <p className="text-xs text-gray-500 mt-1">{description}</p>}
+        </div>
+        <div className="p-3 bg-blue-50 rounded-full">{icon}</div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/PipelineProgress.tsx

@@ -0,0 +1,386 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { CheckCircle2, Loader2, Database, Brain, Sparkles, Rocket, LineChart } from 'lucide-react';
+import { MLBiasAPI } from '../services/api';
+import { useJobRunner } from '../hooks/JobRunnerProvider';
+
+type Health = {
+  status?: string;
+  timestamp?: string;
+  loaded_models?: string[];
+  dataset_loaded?: boolean;
+  generation_results_available?: boolean;
+  finetune_running?: boolean;
+  steps?: Record<string, boolean | 'todo' | 'doing' | 'done'>;
+};
+
+type StepKey =
+  | 'Activate Task'
+  | 'Load Dataset'
+  | 'Load Model'
+  | 'Generate and Score'
+  | 'Counterfactual'
+  | 'Sampling'
+  | 'Plot and Output'
+  | 'Finetune';
+
+type StepState = 'todo' | 'doing' | 'done';
+
+export default function PipelineProgress() {
+  const { result, resp } = useJobRunner();
+
+  const [health, setHealth] = useState<Health | null>(null);
+  const pollRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    const poll = async () => {
+      try {
+        const h = (await MLBiasAPI.checkHealth()) as Health;
+        setHealth(prev => (JSON.stringify(prev) === JSON.stringify(h) ? prev : h));
+      } catch {
+      }
+    };
+    void poll();
+    pollRef.current = window.setInterval(poll, 1000);
+    return () => {
+      if (pollRef.current) window.clearInterval(pollRef.current);
+    };
+  }, []);
+
+  const [elapsed, setElapsed] = useState<number>(0);
+  const timerRef = useRef<number | null>(null);
+  useEffect(() => {
+    const startedAt = Date.now();
+    timerRef.current = window.setInterval(() => {
+      setElapsed(Math.floor((Date.now() - startedAt) / 1000));
+    }, 1000);
+    return () => {
+      if (timerRef.current) window.clearInterval(timerRef.current);
+    };
+  }, []);
+
+  const modelName = result?.config?.languageModel || '';
+
+  const wantFT = Boolean(
+    result?.config?.enableFineTuning ?? (resp?.results as any)?.config_used?.enableFineTuning
+  );
+
+  const backendSteps = useMemo(() => {
+    const fromResp = ((resp?.results as any)?.steps || {}) as Record<string, boolean>;
+    const fromHealth = ((health?.steps || {}) as Record<string, boolean | 'todo' | 'doing' | 'done'>);
+    const merged: Record<string, boolean> = { ...fromResp };
+    Object.keys(fromHealth).forEach(k => {
+      const v = (fromHealth as any)[k];
+      merged[k] = v === true || v === 'doing' || v === 'done';
+    });
+    return merged;
+  }, [health?.steps, resp?.results]);
+
+  const resultsAny = (resp?.results ?? {}) as any;
+
+  const inferred = useMemo(() => {
+    const hasData = Boolean(health?.dataset_loaded);
+    const hasModel = Boolean(health?.loaded_models && health.loaded_models.length > 0);
+
+    const genDone = Boolean(
+      backendSteps['3_generate_and_eval'] ||
+      health?.generation_results_available ||
+      resultsAny.generation_done
+    );
+
+    const r4Flag = Boolean(
+      backendSteps['4_rank_sampling_original'] ||
+      resultsAny.rank_sampling_original_done ||
+      resultsAny.rank_sampling?.original_done
+    );
+
+    const r5Flag = Boolean(
+      backendSteps['5_rank_sampling_cf'] ||
+      resultsAny.rank_sampling_cf_done ||
+      resultsAny.rank_sampling?.cf_done
+    );
+
+    const plotsFlag = Boolean(
+      backendSteps['6_plots_and_metrics'] ||
+      resultsAny.plot_urls ||
+      resultsAny.plots_ready ||
+      (resultsAny.plots &&
+        (resultsAny.plots.original_sentiment || resultsAny.plots.counterfactual_sentiment))
+    );
+
+    const ftDoneFlag = Boolean(
+      backendSteps['7_finetune'] === true ||
+      resultsAny.finetune_done ||
+      resultsAny.finetune?.completed ||
+      resultsAny.finetune?.saved_model_path
+    );
+
+    const ftRunning = Boolean(resultsAny.finetune?.running || (health as any)?.finetune_running);
+
+    const noStepSignals =
+      Object.keys(backendSteps || {}).length === 0 &&
+      !resultsAny.rank_sampling_original_done &&
+      !resultsAny.rank_sampling_cf_done &&
+      !resultsAny.plots_ready &&
+      !resultsAny.finetune_done;
+
+    const cfByTime   = noStepSignals && genDone && elapsed > 30;
+    const rsByTime   = noStepSignals && genDone && elapsed > 45;
+    const plotsByTime= noStepSignals && genDone && elapsed > 70;
+
+    const cfDone = Boolean(
+      backendSteps['3_5_counterfactual'] ||
+      resultsAny.counterfactual_done ||
+      resultsAny.counterfactual_results ||
+      r4Flag || r5Flag || plotsFlag || ftDoneFlag ||
+      cfByTime
+    );
+
+    const r4 = r4Flag || rsByTime;
+    const r5 = r5Flag || rsByTime;
+    const plots = plotsFlag || plotsByTime;
+    const ftDone = ftDoneFlag;
+
+    return { hasData, hasModel, genDone, cfDone, r4, r5, plots, ftDone, ftRunning };
+  }, [backendSteps, health, resultsAny, elapsed]);
+
+
+  const rawSteps = useMemo<Record<StepKey, StepState>>(() => {
+    const states: Record<StepKey, StepState> = {
+      'Activate Task': 'todo',
+      'Load Dataset': 'todo',
+      'Load Model': 'todo',
+      'Generate and Score': 'todo',
+      'Counterfactual': 'todo',
+      'Sampling': 'todo',
+      'Plot and Output': 'todo',
+      'Finetune': 'todo',
+    };
+
+    if (result?.status === 'running') {
+      states['Activate Task'] = 'doing';
+    }
+    if (inferred.hasData) {
+      states['Activate Task'] = 'done';
+      states['Load Dataset'] = 'done';
+    }
+
+    if (inferred.hasModel) {
+      states['Load Model'] = 'done';
+    } else if (inferred.hasData) {
+      states['Load Model'] = 'doing';
+    }
+
+    if (inferred.genDone) {
+      states['Generate and Score'] = 'done';
+    } else if (inferred.hasModel) {
+      states['Generate and Score'] = 'doing';
+    }
+
+    if (inferred.cfDone) {
+      states['Counterfactual'] = 'done';
+    } else if (states['Generate and Score'] === 'done') {
+      states['Counterfactual'] = 'doing';
+    }
+
+    const shouldStartSampling =
+      inferred.r4 || inferred.r5 ||
+      states['Counterfactual'] === 'done' ||
+      (states['Generate and Score'] === 'done' && elapsed > 20);
+
+    if (inferred.r4 && inferred.r5) {
+      states['Sampling'] = 'done';
+    } else if (shouldStartSampling) {
+      states['Sampling'] = 'doing';
+    }
+
+    const shouldStartPlotting =
+      inferred.plots ||
+      states['Sampling'] === 'done' ||
+      (states['Sampling'] === 'doing' && elapsed > 40);
+
+    if (inferred.plots) {
+      states['Plot and Output'] = 'done';
+    } else if (shouldStartPlotting) {
+      states['Plot and Output'] = 'doing';
+    }
+
+    if (wantFT) {
+      if (inferred.ftDone) states['Finetune'] = 'done';
+      else if (inferred.ftRunning || states['Plot and Output'] === 'done')
+        states['Finetune'] = 'doing';
+      else states['Finetune'] = 'todo';
+    } else {
+      states['Finetune'] = 'todo';
+    }
+
+    return states;
+  }, [elapsed, inferred, wantFT, result?.status]);
+
+  const STUCK_TIMEOUT = 30; // 秒
+  const [enteredAt, setEnteredAt] = useState<Record<StepKey, number>>({} as any);
+  const [forcedDone, setForcedDone] = useState<Record<StepKey, boolean>>({} as any);
+
+  useEffect(() => {
+    const next: Record<StepKey, number> = { ...enteredAt } as any;
+    (Object.keys(rawSteps) as StepKey[]).forEach((k) => {
+      if (rawSteps[k] === 'doing' && !next[k]) next[k] = Date.now();
+      if (rawSteps[k] !== 'doing' && next[k]) delete next[k];
+    });
+    if (JSON.stringify(next) !== JSON.stringify(enteredAt)) setEnteredAt(next);
+  }, [rawSteps]);
+
+  useEffect(() => {
+    const now = Date.now();
+    const k: StepKey = 'Counterfactual';
+    if (rawSteps[k] === 'doing' && enteredAt[k] && now - enteredAt[k] > STUCK_TIMEOUT * 1000) {
+      if (!forcedDone[k]) setForcedDone(prev => ({ ...prev, [k]: true }));
+    }
+  }, [enteredAt, rawSteps, forcedDone]);
+
+  const steps = useMemo(() => {
+    const s = { ...rawSteps } as Record<StepKey, StepState>;
+    (Object.keys(forcedDone) as StepKey[]).forEach((k) => {
+      if (forcedDone[k]) s[k] = 'done';
+    });
+    return s;
+  }, [rawSteps, forcedDone]);
+
+  const ft = resultsAny?.finetune || {};
+  const downloadPath: string | undefined =
+    ft.download_url || ft.model_url || ft.saved_model_path || resultsAny?.finetune_model_url;
+
+  const downloadHref = downloadPath ? MLBiasAPI.resolvePath(downloadPath) : undefined;
+
+  const baseSteps = [
+    { key: 'Activate Task', icon: Rocket },
+    { key: 'Load Dataset', icon: Database },
+    { key: 'Load Model', icon: Brain },
+    { key: 'Generate and Score', icon: Sparkles },
+    { key: 'Counterfactual', icon: Sparkles },
+    { key: 'Sampling', icon: LineChart },
+    { key: 'Plot and Output', icon: LineChart },
+  ] as const;
+
+  const stepList = wantFT
+    ? [...baseSteps, { key: 'Finetune', icon: Rocket } as const]
+    : baseSteps;
+
+  const completedCount = stepList.reduce(
+    (acc, s) => acc + (steps[s.key as StepKey] === 'done' ? 1 : 0),
+    0
+  );
+  const doingCount = stepList.reduce(
+    (acc, s) => acc + (steps[s.key as StepKey] === 'doing' ? 1 : 0),
+    0
+  );
+  const percent = Math.min(
+    100,
+    Math.round(((completedCount + doingCount * 0.5) / stepList.length) * 100)
+  );
+
+  const hasStuckStep =
+    Object.values(steps).some((state) => state === 'doing') &&
+    elapsed > 60 &&
+    completedCount < stepList.length - 1;
+
+  return (
+    <div className="relative overflow-hidden rounded-2xl border border-indigo-200/50 bg-white/70 backdrop-blur">
+      <div className="absolute inset-0 -z-10 bg-[radial-gradient(800px_300px_at_20%_-20%,rgba(99,102,241,0.15),transparent_60%),radial-gradient(800px_300px_at_120%_0%,rgba(244,114,182,0.15),transparent_60%)]" />
+      <div className="p-6">
+        <div className="flex items-center justify-between mb-4">
+          <div>
+            <h3 className="text-lg font-semibold text-slate-900">Pipeline Running</h3>
+            <p className="text-sm text-slate-600">
+              Model: <span className="font-medium text-slate-800">{modelName || '（未指定）'}</span>
+            </p>
+            {hasStuckStep && (
+              <p className="text-xs text-amber-600 mt-1">⚠️ Some steps may run slowly and are automatically attempted to proceed.</p>
+            )}
+          </div>
+          <div className="flex items-center gap-2 text-slate-600">
+            <Loader2 className="w-5 h-5 animate-spin" />
+            <span className="text-sm">Executed {elapsed}s</span>
+          </div>
+        </div>
+
+        <div className="w-full h-3 rounded-full bg-slate-200 overflow-hidden">
+          <div
+            className="h-3 bg-gradient-to-r from-indigo-500 via-violet-500 to-fuchsia-500 transition-all duration-500"
+            style={{ width: `${percent}%` }}
+          />
+        </div>
+
+        <ol className="mt-6 grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-3">
+          {stepList.map(({ key, icon: Icon }) => {
+            const state = steps[key as StepKey];
+            const isDone = state === 'done';
+            const isDoing = state === 'doing';
+            const startTs = enteredAt[key as StepKey];
+            const isStuck = isDoing && startTs && (Date.now() - startTs) / 1000 > STUCK_TIMEOUT;
+
+            return (
+              <li
+                key={key}
+                className={`flex items-center gap-3 rounded-xl border p-3 transition-all duration-300 ${
+                  isDone
+                    ? 'border-emerald-200 bg-emerald-50'
+                    : isDoing
+                    ? isStuck
+                      ? 'border-amber-300 bg-amber-100'
+                      : 'border-amber-200 bg-amber-50'
+                    : 'border-slate-200 bg-white/70'
+                }`}
+              >
+                <div
+                  className={`rounded-lg p-2 transition-colors ${
+                    isDone
+                      ? 'bg-emerald-100 text-emerald-700'
+                      : isDoing
+                      ? isStuck
+                        ? 'bg-amber-200 text-amber-800'
+                        : 'bg-amber-100 text-amber-700'
+                      : 'bg-slate-100 text-slate-600'
+                  }`}
+                >
+                  {isDone ? (
+                    <CheckCircle2 className="w-5 h-5" />
+                  ) : isDoing ? (
+                    <Loader2 className="w-5 h-5 animate-spin" />
+                  ) : (
+                    <Icon className="w-5 h-5" />
+                  )}
+                </div>
+                <div className="flex-1">
+                  <div className="text-sm font-medium text-slate-900">{key}</div>
+                  <div className="text-xs text-slate-600">
+                    {isDone ? 'Finished' : isDoing ? (isStuck ? 'Running...' : 'Running…') : 'Waiting'}
+                  </div>
+                </div>
+              </li>
+            );
+          })}
+        </ol>
+
+        {/* 微調完成 → 顯示下載模型 */}
+        {wantFT && inferred.ftDone && downloadHref && (
+          <div className="mt-6">
+            <a
+              href={downloadHref}
+              className="inline-flex items-center rounded-xl border bg-white px-4 py-2 text-sm font-medium text-slate-800 hover:bg-slate-50"
+              target="_blank"
+              rel="noopener noreferrer"
+            >
+              <Rocket className="w-4 h-4 mr-2" />
+              Download Finetuned Model
+            </a>
+            {ft?.saved_model_path && (
+              <p className="mt-2 text-xs text-slate-500 break-all">
+                Model path: {String(ft.saved_model_path)}
+              </p>
+            )}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/validators/DatasetValidator.tsx

@@ -0,0 +1,78 @@
+// src/components/validators/DatasetValidator.tsx
+import { useEffect } from 'react';
+import { Loader, CheckCircle, XCircle, ExternalLink } from 'lucide-react';
+import { useHFDatasetValidator } from '../../hooks/useHFValidators';
+
+export default function DatasetValidator({ datasetId }: { datasetId: string }) {
+  const { loading, result, validate } = useHFDatasetValidator();
+
+  useEffect(() => {
+    validate(datasetId);
+  }, [datasetId, validate]);
+
+  if (!datasetId?.includes('/')) return null;
+
+  return (
+    <div className="mt-3">
+      {loading && (
+        <div className="flex items-center gap-2 p-3 bg-yellow-50 rounded-lg">
+          <Loader className="w-4 h-4 text-yellow-600 animate-spin" />
+          <span className="text-sm text-yellow-800">Validating Dataset...</span>
+        </div>
+      )}
+
+      {!!result && !loading && (
+        <div className={`p-3 rounded-lg ${result.isValid ? 'bg-green-50' : 'bg-red-50'}`}>
+          <div className="flex items-start gap-2">
+            {result.isValid ? (
+              <CheckCircle className="w-4 h-4 text-green-600 mt-0.5" />
+            ) : (
+              <XCircle className="w-4 h-4 text-red-600 mt-0.5" />
+            )}
+            <div className="flex-1">
+              {result.isValid ? (
+                <>
+                  <p className="text-sm font-medium text-green-800">✅ Dataset Verification Successful</p>
+                  <div className="mt-2 space-y-1 text-xs text-green-700">
+                    <p>
+                      <strong>Author: </strong>
+                      {result.datasetInfo.author}
+                    </p>
+                    <p>
+                      <strong>Download: </strong>
+                      {result.datasetInfo.downloads.toLocaleString()}
+                    </p>
+                    {!!result.datasetInfo.task_categories?.length && (
+                      <p>
+                        <strong>Task: </strong>
+                        {result.datasetInfo.task_categories.join(', ')}
+                      </p>
+                    )}
+                    <p>
+                      <strong>Description: </strong>
+                      {result.datasetInfo.description.slice(0, 100)}...
+                    </p>
+                  </div>
+                  <a
+                    href={`https://huggingface.co/datasets/${datasetId}`}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center gap-1 text-xs text-blue-600 hover:text-blue-800 mt-2"
+                  >
+                    <ExternalLink className="w-3 h-3" />
+                    <span>View on Hugging Face</span>
+                  </a>
+                </>
+              ) : (
+                <>
+                  <p className="text-sm font-medium text-red-800">❌ Dataset Verification Failed</p>
+                  <p className="text-xs text-red-700 mt-1">{result.error}</p>
+                </>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/validators/ModelValidator.tsx

@@ -0,0 +1,80 @@
+// src/components/validators/ModelValidator.tsx
+import { useEffect } from 'react';
+import { Loader, CheckCircle, XCircle, ExternalLink } from 'lucide-react';
+import { useHFModelValidator } from '../../hooks/useHFValidators';
+
+export default function ModelValidator({
+  modelId,
+  type,
+}: {
+  modelId: string;
+  type: 'language' | 'scorer';
+}) {
+  const { loading, result, validate } = useHFModelValidator();
+
+  useEffect(() => {
+    validate(modelId, type);
+  }, [modelId, type, validate]);
+
+  if (!modelId?.includes('/')) return null;
+
+  return (
+    <div className="mt-3">
+      {loading && (
+        <div className="flex items-center gap-2 p-3 bg-yellow-50 rounded-lg">
+          <Loader className="w-4 h-4 text-yellow-600 animate-spin" />
+          <span className="text-sm text-yellow-800">Validating Model...</span>
+        </div>
+      )}
+
+      {!!result && !loading && (
+        <div className={`p-3 rounded-lg ${result.isValid ? 'bg-green-50' : 'bg-red-50'}`}>
+          <div className="flex items-start gap-2">
+            {result.isValid ? (
+              <CheckCircle className="w-4 h-4 text-green-600 mt-0.5" />
+            ) : (
+              <XCircle className="w-4 h-4 text-red-600 mt-0.5" />
+            )}
+            <div className="flex-1">
+              {result.isValid ? (
+                <>
+                  <p className="text-sm font-medium text-green-800">✅ Model Verification Sucessful</p>
+                  <div className="mt-2 space-y-1 text-xs text-green-700">
+                    <p>
+                      <strong>Author: </strong>
+                      {result.modelInfo.author}
+                    </p>
+                    <p>
+                      <strong>Download: </strong>
+                      {result.modelInfo.downloads.toLocaleString()}
+                    </p>
+                    {!!result.modelInfo.pipeline_tag && (
+                      <p>
+                        <strong>Task: </strong>
+                        {result.modelInfo.pipeline_tag}
+                      </p>
+                    )}
+                  </div>
+                  <a
+                    href={`https://huggingface.co/${modelId}`}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="inline-flex items-center gap-1 text-xs text-blue-600 hover:text-blue-800 mt-2"
+                  >
+                    <ExternalLink className="w-3 h-3" />
+                    <span>View on Hugging Face</span>
+                  </a>
+                </>
+              ) : (
+                <>
+                  <p className="text-sm font-medium text-red-800">❌ Model Verification Failed</p>
+                  <p className="text-xs text-red-700 mt-1">{result.error}</p>
+                </>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/constants/datasets.ts

@@ -0,0 +1,10 @@
+import type { Dataset } from '../types';
+
+export const DATASETS: Dataset[] = [
+  {
+    id: 'AmazonScience/bold',
+    name: 'BOLD'
+  },
+];
+
+export default DATASETS;

frontend/src/constants/models.ts

@@ -0,0 +1,11 @@
+import type { Dataset, Model } from '../types';
+
+export const DATASETS: Dataset[] = [
+  { id: 'AmazonScience/bold', name: 'BOLD' }
+];
+
+export const LM_MODELS: Model[] = [
+  { id: 'microsoft/DialoGPT-large', name: 'DialoGPT-large', type: 'language', description: 'Microsoft 對話生成模型', provider: 'Microsoft' },
+  { id: 'openai-community/gpt2', name: 'GPT-2', type: 'language', description: 'OpenAI GPT-2 基礎模型', provider: 'OpenAI' },
+  { id: 'EleutherAI/gpt-neo-2.7B', name: 'GPT-Neo-2.7B', type: 'language', description: 'EleutherAI 開源語言模型', provider: 'EleutherAI' }
+];

frontend/src/hooks/JobRunnerProvider.tsx

@@ -0,0 +1,121 @@
+import React, { createContext, useContext, useMemo, useState } from 'react';
+import type { JobConfig, JobResult } from '../types';
+import { MLBiasAPI } from '../services/api';
+
+type PipelinePlots = {
+  original_sentiment: string;
+  counterfactual_sentiment: string;
+};
+
+type PipelineResultsDTO = {
+  generation_file: string;
+  sentiment_subset_file: string;
+  cf_sentiment_subset_file: string;
+  metrics: {
+    finalMeanDiff: number;
+    cfFinalMeanDiff: number;
+    reductionPct?: number;
+    stableCoverage?: number;
+  };
+  plots: PipelinePlots;
+  finetuned_model_zip?: string;
+  finetuned_model_dir?: string;
+  run_config_files?: {
+    json?: string;     
+    markdown?: string; 
+  };
+};
+
+type PipelineResponseDTO = {
+  status: 'success' | 'error';
+  message: string;
+  timestamp: string;
+  results: PipelineResultsDTO;
+};
+
+type Extras = {
+  datasetLimit: number
+};
+
+type Ctx = {
+  result: JobResult | null;
+  resp?: PipelineResponseDTO;
+  loading: boolean;
+  error?: string;
+  start: (cfg: JobConfig, extras: Extras) => Promise<void>;
+  url: (p?: string) => string;
+};
+
+const JobRunnerContext = createContext<Ctx | undefined>(undefined);
+
+export function JobRunnerProvider({ children }: { children: React.ReactNode }) {
+  const [result, setResult] = useState<JobResult | null>(null);
+  const [resp, setResp] = useState<PipelineResponseDTO | undefined>();
+  const [loading, setLoading] = useState(false);
+  const [error, setErr] = useState<string | undefined>();
+
+  const start: Ctx['start'] = async (cfg, extras) => {
+    setLoading(true);
+    setErr(undefined);
+    setResp(undefined);
+
+    const now = new Date().toISOString();
+    setResult({
+      id: crypto.randomUUID(),
+      status: 'running',
+      progress: 0,
+      config: cfg,
+      createdAt: now,
+      updatedAt: now,
+    });
+
+    try {
+      const cfgToSend = {
+        ...cfg,
+        datasetLimit: extras.datasetLimit
+      } as unknown as JobConfig; 
+
+      const r = await MLBiasAPI.runPipeline(cfgToSend as any); 
+
+      setResp(r);
+
+      const done = new Date().toISOString();
+      setResult((prev) => ({
+        ...(prev as JobResult),
+        status: 'completed',
+        progress: 100,
+        updatedAt: done,
+        completedAt: done,
+        metrics: {
+          finalMeanDiff: r.results.metrics.finalMeanDiff,
+          reductionPct: r.results.metrics.reductionPct ?? 0,
+          stableCoverage: r.results.metrics.stableCoverage ?? 100,
+        },
+      }));
+    } catch (e: any) {
+      setErr(e.message || String(e));
+      setResult((prev) =>
+        prev
+          ? { ...prev, status: 'failed', progress: 100, updatedAt: new Date().toISOString() }
+          : prev
+      );
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const url = MLBiasAPI.resolvePath;
+
+  const value = useMemo<Ctx>(
+    () => ({ result, resp, loading, error, start, url }),
+    [result, resp, loading, error]
+  );
+
+  return <JobRunnerContext.Provider value={value}>{children}</JobRunnerContext.Provider>;
+}
+
+export function useJobRunner() {
+  const ctx = useContext(JobRunnerContext);
+  if (!ctx) throw new Error('useJobRunner must be used within JobRunnerProvider');
+  return ctx;
+}

frontend/src/hooks/useHFValidators.ts

@@ -0,0 +1,129 @@
+// src/hooks/useHFValidators.ts
+import { useMemo, useRef, useState } from 'react';
+import { fetchHFModel, fetchHFDataset } from '../services/hf';
+
+const debounce = (fn: (...args: any[]) => void, ms = 350) => {
+  let t: any;
+  return (...args: any[]) => {
+    clearTimeout(t);
+    t = setTimeout(() => fn(...args), ms);
+  };
+};
+
+export function useHFModelValidator() {
+  const cache = useRef<Map<string, any>>(new Map());
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<any>(null);
+
+  const validate = useMemo(
+    () =>
+      debounce(async (modelId: string, expected: 'language' | 'scorer') => {
+        if (!modelId?.includes('/')) {
+          setResult(null);
+          return;
+        }
+        if (cache.current.has(modelId)) {
+          setResult(cache.current.get(modelId));
+          return;
+        }
+        setLoading(true);
+        try {
+          const info = await fetchHFModel(modelId);
+          const id: string = info.id?.toLowerCase() ?? '';
+          const tags: string[] = info.tags ?? [];
+          let actual: string | undefined = info.pipeline_tag;
+
+          if (!actual) {
+            if (id.includes('t5') || tags.includes('text2text-generation')) actual = 'text2text-generation';
+            else if (tags.includes('text-generation')) actual = 'text-generation';
+            else if (tags.includes('text-classification')) actual = 'text-classification';
+          }
+
+          const ok =
+            expected === 'language'
+              ? ['text-generation', 'text2text-generation'].includes(actual || '')
+              : actual === 'text-classification';
+
+          const payload = ok
+            ? {
+                isValid: true,
+                modelInfo: {
+                  id: info.id,
+                  downloads: info.downloads ?? 0,
+                  pipeline_tag: actual,
+                  tags,
+                  author: info.id?.split('/')?.[0] ?? 'unknown',
+                  modelName: info.id?.split('/')?.[1] ?? info.id,
+                },
+              }
+            : {
+                isValid: false,
+                error:
+                  expected === 'language'
+                    ? `Model task should be text-generation or text2text-generation, but is ${actual || 'Unknown'}」`
+                    : `Model task should be text-classification, but is${actual || 'Unknown'}」`,
+              };
+
+          cache.current.set(modelId, payload);
+          setResult(payload);
+        } catch (e: any) {
+          setResult({ isValid: false, error: e?.message || 'Error when valiating model' });
+        } finally {
+          setLoading(false);
+        }
+      }),
+    []
+  );
+
+  return { loading, result, validate };
+}
+
+export function useHFDatasetValidator() {
+  const cache = useRef<Map<string, any>>(new Map());
+  const [loading, setLoading] = useState(false);
+  const [result, setResult] = useState<any>(null);
+
+  const validate = useMemo(
+    () =>
+      debounce(async (datasetId: string) => {
+        if (!datasetId?.includes('/')) {
+          setResult(null);
+          return;
+        }
+        if (cache.current.has(datasetId)) {
+          setResult(cache.current.get(datasetId));
+          return;
+        }
+        const valid = /^[a-zA-Z0-9._-]+\/[a-zA-Z0-9._-]+$/.test(datasetId);
+        if (!valid) {
+          setResult({ isValid: false, error: 'Incorrect Dataset ID Format' });
+          return;
+        }
+        setLoading(true);
+        try {
+          const info = await fetchHFDataset(datasetId);
+          const payload = {
+            isValid: true,
+            datasetInfo: {
+              id: info.id,
+              author: info.id?.split('/')?.[0] ?? 'unknown',
+              datasetName: info.id?.split('/')?.[1] ?? info.id,
+              downloads: info.downloads ?? 0,
+              tags: info.tags ?? [],
+              description: info.description ?? 'No Description',
+              task_categories: info.task_categories ?? [],
+            },
+          };
+          cache.current.set(datasetId, payload);
+          setResult(payload);
+        } catch (e: any) {
+          setResult({ isValid: false, error: e?.message || 'An error occurred while validating the dataset' });
+        } finally {
+          setLoading(false);
+        }
+      }),
+    []
+  );
+
+  return { loading, result, validate };
+}

frontend/src/hooks/useIterationData.ts

@@ -0,0 +1,14 @@
+import { useMemo } from 'react';
+
+export function useIterationData(seed = 42, points = 50) {
+  function mulberry32(a:number){return function(){let t=(a+=0x6D2B79F5);t=Math.imul(t^(t>>>15),t|1);t^=t+Math.imul(t^(t>>>7),t|61);return ((t^(t>>>14))>>>0)/4294967296;};}
+  return useMemo(() => {
+    const rand = mulberry32(seed);
+    return Array.from({ length: points }, (_, i) => ({
+      iteration: i+1,
+      meanDifference: Math.max(0.1, 0.8 - i*0.012 + rand()*0.1),
+      groupA: 0.7 - i*0.006 + rand()*0.05,
+      groupB: 0.3 + i*0.003 + rand()*0.05,
+    }));
+  }, [seed, points]);
+}

frontend/src/hooks/useJobRunner.ts

@@ -0,0 +1,208 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { JobConfig, JobResult } from '../types';
+import type { PipelineResponseDTO } from '../services/api';
+import { MLBiasAPI } from '../services/api';
+
+type HealthLike = {
+  job_id?: string;               
+  timestamp?: string;
+  updated_at?: string;
+  dataset_loaded?: boolean;
+  loaded_models?: string[];
+  generation_results_available?: boolean;
+  finetune_running?: boolean;
+  steps?: Record<string, boolean | 'todo' | 'doing' | 'done'>;
+  completed?: boolean;
+  status?: string;
+};
+
+type UseJobRunnerReturn = {
+  result: JobResult | null;
+  resp: PipelineResponseDTO | undefined;
+  loading: boolean;
+  error?: string;
+
+  start: (config: JobConfig) => Promise<void>;
+  cancel: () => void;
+
+  jobId: string | null;
+  live: {
+    health: HealthLike | null;
+    steps: Record<string, boolean>;
+    updatedAt: string | null;
+    finetuneRunning: boolean;
+    progressPercent: number;
+  };
+
+  url: typeof MLBiasAPI.resolvePath;
+};
+
+export function useJobRunner(): UseJobRunnerReturn {
+  const [jobId, setJobId] = useState<string | null>(null);
+
+  const [result, setResult] = useState<JobResult | null>(null);
+  const [resp, setResp] = useState<PipelineResponseDTO | undefined>();
+
+  const [loading, setLoading] = useState(false);
+  const [error, setErr] = useState<string | undefined>();
+
+  const [health, setHealth] = useState<HealthLike | null>(null);
+
+  const pollRef = useRef<number | null>(null);
+  const aliveRef = useRef<boolean>(false);
+
+  const stopPolling = () => {
+    if (pollRef.current) {
+      window.clearInterval(pollRef.current);
+      pollRef.current = null;
+    }
+    aliveRef.current = false;
+  };
+
+  const cancel = () => {
+    stopPolling();
+    setLoading(false);
+  };
+
+  const progressPercent = useMemo(() => {
+    const s = (health?.steps as Record<string, boolean | string>) || {};
+    const keys = Object.keys(s);
+    if (keys.length === 0) return result?.progress ?? 0;
+    let score = 0;
+    keys.forEach((k) => {
+      const v = s[k];
+      if (v === true || v === 'done') score += 1;
+      else if (v === 'doing') score += 0.5;
+    });
+    return Math.max(0, Math.min(100, Math.round((score / keys.length) * 100)));
+  }, [health?.steps, result?.progress]);
+
+  const liveSteps: Record<string, boolean> = useMemo(() => {
+    const fromResp = ((resp?.results as any)?.steps || {}) as Record<string, boolean>;
+    const fromHealth = ((health?.steps || {}) as Record<string, boolean | string>);
+    const normalized: Record<string, boolean> = {};
+    Object.keys(fromResp).forEach((k) => (normalized[k] = !!(fromResp as any)[k]));
+    Object.keys(fromHealth).forEach((k) => {
+      const v = (fromHealth as any)[k];
+      normalized[k] = v === true || v === 'done' || v === 'doing';
+    });
+    return normalized;
+  }, [health?.steps, resp?.results]);
+
+  const pollOnce = async () => {
+    try {
+      const h = (await MLBiasAPI.checkHealth()) as HealthLike;
+      setHealth((prev) => (JSON.stringify(prev) === JSON.stringify(h) ? prev : h));
+
+      const steps = (h?.steps || {}) as Record<string, boolean | string>;
+      const plotsDone =
+        !!steps['6_plots_and_metrics'] ||
+        (resp?.results as any)?.plots_ready ||
+        ((resp?.results as any)?.plot_urls?.length ?? 0) > 0;
+
+      const r4 = !!steps['4_rank_sampling_original'];
+      const r5 = !!steps['5_rank_sampling_cf'];
+      const samplingDone = r4 && r5;
+
+      const genAvailable = !!h?.generation_results_available;
+      const ftMaybeDone =
+        !!steps['7_finetune'] ||
+        (resp?.results as any)?.finetune_done ||
+        (resp?.results as any)?.finetune?.completed;
+
+      const declaredCompleted = h?.completed === true || h?.status === 'completed';
+
+      if (declaredCompleted || plotsDone || samplingDone || (genAvailable && ftMaybeDone)) {
+        stopPolling();
+        setLoading(false);
+      }
+    } catch (e: any) {
+      setErr((e && e.message) || String(e));
+    }
+  };
+
+  const start = async (config: JobConfig) => {
+    setLoading(true);
+    setErr(undefined);
+
+    const now = new Date().toISOString();
+    const provisionalId = crypto.randomUUID();
+    setResult({
+      id: provisionalId,
+      status: 'running',
+      progress: 0,
+      config,
+      createdAt: now,
+      updatedAt: now,
+    });
+    setResp(undefined);
+    setHealth(null);
+
+    try {
+      const runResp: any = await MLBiasAPI.runPipeline(config);
+
+      const jid: string | undefined =
+        runResp?.jobId || runResp?.job_id || runResp?.results?.jobId || runResp?.results?.job_id;
+      setJobId(jid || provisionalId);
+
+      if (runResp?.results?.metrics) {
+        const final = runResp as PipelineResponseDTO;
+        const now2 = new Date().toISOString();
+
+        setResp(final);
+        setResult({
+          id: jid || provisionalId,
+          status: 'completed',
+          progress: 100,
+          config,
+          createdAt: now,
+          updatedAt: now2,
+          completedAt: now2,
+          metrics: {
+            finalMeanDiff: final.results.metrics.finalMeanDiff,
+            reductionPct: final.results.metrics.reductionPct ?? 0,
+            stableCoverage: final.results.metrics.stableCoverage ?? 100,
+          },
+        });
+        setLoading(false);
+        return;
+      }
+
+      aliveRef.current = true;
+      await pollOnce(); 
+      if (aliveRef.current) {
+        pollRef.current = window.setInterval(pollOnce, 1000);
+      }
+    } catch (e: any) {
+      setErr(e?.message || String(e));
+      setResult((prev) =>
+        prev
+          ? { ...prev, status: 'failed', progress: 100, updatedAt: new Date().toISOString() }
+          : null
+      );
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => stopPolling, []);
+
+  const url = MLBiasAPI.resolvePath;
+
+  return {
+    result,
+    resp,
+    loading,
+    error,
+    start,
+    cancel,
+    jobId,
+    live: {
+      health,
+      steps: liveSteps,
+      updatedAt: (health && (health.updated_at || health.timestamp)) || null,
+      finetuneRunning: !!(health?.finetune_running || (resp as any)?.results?.finetune?.running),
+      progressPercent,
+    },
+    url,
+  };
+}

frontend/src/index.css

@@ -0,0 +1,4 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import App from './App.tsx'
+import './index.css'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)

frontend/src/pages/ConfigPage.tsx

@@ -0,0 +1,649 @@
+import { useEffect, useState } from 'react';
+import { Database, Bot, ExternalLink, Shuffle } from 'lucide-react';
+import DatasetValidator from '../components/validators/DatasetValidator';
+import ModelValidator from '../components/validators/ModelValidator';
+import { DATASETS } from '../constants/datasets';
+import { LM_MODELS} from '../constants/models';
+import type { JobConfig } from '../types';
+
+type Extras = {
+  datasetLimit: number,
+};
+
+export default function ConfigPage({ onRun }: { onRun: (cfg: JobConfig, extras: Extras) => void }) {
+  const [cfg, setCfg] = useState<JobConfig>({
+    dataset: '',
+    languageModel: '',
+    scorerModel: '',
+    k: 5,
+    numCounterfactuals: 3,
+    metrictarget: 0.5,
+    tau: 0.1,
+    iterations: 1000,
+    seed: 42,
+    enableFineTuning: false,
+    counterfactual: false,
+  });
+
+  const [datasetLimit, setDatasetLimit] = useState<number>(10);
+  const [customDataset, setCustomDataset] = useState('');
+  const [customLM, setCustomLM] = useState('');
+  const [showCustomDatasetInput, setShowCustomDatasetInput] = useState(false);
+  const [showCustomLanguageInput, setShowCustomLanguageInput] = useState(false);
+  const [fieldStats, setFieldStats] = useState<Record<string, Record<string, number>>>({});
+  const [numCounterfactuals, setNumCounterfactuals] = useState<number>(3);
+  const [classificationTask, setClassificationTask] = useState<'sentiment' | 'regard' | 'stereotype' | 'personality' | 'toxicity'>('sentiment');
+  const [toxicityModelChoice, setToxicityModelChoice] = useState<'detoxify' | 'junglelee'>('detoxify');
+  const [selectedCfFields, setSelectedCfFields] = useState<string[]>([]);
+  const [availableFields, setAvailableFields] = useState<string[]>([]);
+  const [isLoadingFields, setIsLoadingFields] = useState(false);
+  const [fieldsError, setFieldsError] = useState<string | null>(null);
+  const [metaConfigs, setMetaConfigs] = useState<string[]>([]);
+  const [metaSplits, setMetaSplits] = useState<string[]>([]);
+  const [selectedConfig, setSelectedConfig] = useState<string | null>(null);
+  const [selectedSplit, setSelectedSplit] = useState<string>('train');
+
+  const canStart = !!(cfg.dataset && cfg.languageModel);
+  const [ftEpochs, setFtEpochs] = useState(3);
+  const [ftBatchSize, setFtBatchSize] = useState(8);
+  const [ftLR, setFtLR] = useState(5e-5);
+  const setField = <K extends keyof JobConfig>(k: K, v: JobConfig[K]) =>
+    setCfg((prev) => ({ ...prev, [k]: v }));
+
+  const card = 'group relative rounded-2xl p-8 border border-white/30 bg-white/60 backdrop-blur-xl ' +
+    'shadow-[0_15px_40px_-20px_rgba(30,41,59,0.35)] transition-all duration-300 ' +
+    'hover:shadow-[0_20px_50px_-20px_rgba(79,70,229,0.45)] hover:-translate-y-0.5';
+
+  const sectionTitle = 'text-xl font-bold tracking-tight text-slate-900';
+  const subtext = 'text-sm text-slate-600';
+  const fieldInput = 'w-full rounded-xl border-2 border-slate-200/70 bg-white/70 px-4 py-3 ' +
+    'focus:outline-none focus:border-indigo-500 focus:ring-4 focus:ring-indigo-500/20 transition-all';
+  const selectInput = 'w-full rounded-xl border-2 border-slate-200/70 bg-white/70 px-3 py-2.5 ' +
+    'focus:outline-none focus:border-indigo-500 focus:ring-4 focus:ring-indigo-500/20 transition-all';
+  const choiceRow = 'flex items-start gap-4 cursor-pointer p-4 rounded-xl border transition-colors ' +
+    'bg-white/60 hover:bg-white/80 border-slate-200/60 hover:border-indigo-300';
+
+  const currentDataset = DATASETS.find((d) => d.id === cfg.dataset);
+  const fallbackFields: string[] = (currentDataset as any)?.fields || ['text', 'label', 'group'];
+
+  const toggleCfField = (f: string) =>
+    setSelectedCfFields((prev) =>
+      (prev.includes(f) ? prev.filter((x) => x !== f) : [...prev, f])
+    );
+
+  const API_BASE = '/api';
+
+  async function fetchJSON<T>(url: string, signal?: AbortSignal): Promise<T> {
+    const fullURL = url.startsWith('http') ? url : `${API_BASE}${url}`;
+    const res = await fetch(fullURL, { signal });
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    return (await res.json()) as T;
+  }
+
+
+  function buildFieldsURL(datasetId: string, config: string | null, split: string): string {
+    const params = new URLSearchParams();
+    params.set('id', datasetId);
+    
+    if (config && config.trim() !== '') {
+      params.set('config', config);
+    }
+    
+    if (split && split.trim() !== '') {
+      params.set('split', split);
+    }
+    
+    return `/dataset/fields?${params.toString()}`;
+  }
+
+  useEffect(() => {
+    console.log('📊 Dataset changed:', cfg.dataset);
+    setSelectedCfFields([]);
+    setFieldsError(null);
+    setAvailableFields([]);
+    
+    if (!cfg.dataset || cfg.dataset === 'custom') return;
+
+    const ac = new AbortController();
+    
+    const run = async () => {
+      try {
+        console.log('🔍 Fetching dataset meta...');
+        const metaURL = `/dataset/meta?id=${encodeURIComponent(cfg.dataset)}`;
+        const meta = await fetchJSON<{
+          datasetId: string;
+          configs: string[];
+          splits: string[];
+        }>(metaURL, ac.signal);
+        
+        console.log('📋 Meta data received:', meta);
+        
+        setMetaConfigs(meta.configs || []);
+        setMetaSplits(meta.splits || []);
+        
+        const defaultConfig = meta.configs?.length ? meta.configs[0] : null;
+        const defaultSplit = meta.splits?.length ? 
+          (meta.splits.includes('train') ? 'train' : meta.splits[0]) : 
+          'train';
+        
+        setSelectedConfig(defaultConfig);
+        setSelectedSplit(defaultSplit);
+        
+        console.log('🏷️ Fetching fields with config:', defaultConfig, 'split:', defaultSplit);
+        setIsLoadingFields(true);
+        
+        const fieldsURL = buildFieldsURL(cfg.dataset, defaultConfig, defaultSplit);
+        const fieldsData = await fetchJSON<{ fields: string[] }>(fieldsURL, ac.signal);
+        
+        setAvailableFields(fieldsData.fields || []);
+        setFieldsError(null);
+        
+      } catch (err: any) {
+        console.error('❌ Error in dataset effect:', err);
+        
+        setMetaConfigs([]);
+        setMetaSplits([]);
+        setSelectedConfig(null);
+        setSelectedSplit('train');
+        
+        setAvailableFields([]);
+        const fieldsURL = buildFieldsURL(cfg.dataset, null, 'train');
+        setFieldsError(`(${fieldsURL}) → ${err?.message || '欄位讀取失敗'}`);
+      } finally {
+        setIsLoadingFields(false);
+      }
+    };
+
+    run();
+    return () => ac.abort();
+  }, [cfg.dataset]);
+
+  useEffect(() => {
+    if (!cfg.dataset || cfg.dataset === 'custom') return;
+    
+    console.log('🔄 Config/Split changed - config:', selectedConfig, 'split:', selectedSplit);
+    
+    const ac = new AbortController();
+    
+    const run = async () => {
+      try {
+        setIsLoadingFields(true);
+        
+        const fieldsURL = buildFieldsURL(cfg.dataset, selectedConfig, selectedSplit);
+        const fieldsData = await fetchJSON<{ fields: string[] }>(fieldsURL, ac.signal);
+        
+        setAvailableFields(fieldsData.fields || []);
+        setFieldsError(null);
+        setSelectedCfFields([]); 
+
+        const statsURL = `/dataset/field-stats?id=${encodeURIComponent(cfg.dataset)}&field=domain&subfield=category`;
+        const statsData = await fetchJSON<{ counts: Record<string, Record<string, number>> }>(statsURL, ac.signal);
+        setFieldStats(statsData.counts || {});
+        
+      } catch (err: any) {
+        console.error('❌ Error fetching fields after config/split change:', err);
+        const fieldsURL = buildFieldsURL(cfg.dataset, selectedConfig, selectedSplit);
+        setAvailableFields([]);
+        setFieldsError(`(${fieldsURL}) → ${err?.message || 'Field Read Failed'}`);
+      } finally {
+        setIsLoadingFields(false);
+      }
+    };
+
+    run();
+    return () => ac.abort();
+  }, [cfg.dataset, selectedConfig, selectedSplit]);
+
+  return (
+    <div className="space-y-10">
+      <div className="grid grid-cols-1 lg:grid-cols-6 gap-8">
+        {/* 數據集選擇 */}
+        <div className={`${card} lg:col-span-3`}>
+          <div className="flex items-center gap-3 mb-8">
+            <div className="p-3 rounded-xl bg-gradient-to-br from-indigo-600 to-fuchsia-600 shadow-md shadow-indigo-600/30">
+              <Database className="w-6 h-6 text-white" />
+            </div>
+            <h3 className={sectionTitle}>Dataset Selection</h3>
+          </div>
+
+          <div className="space-y-4">
+            {DATASETS.map((dataset) => (
+              <label key={dataset.id} className={choiceRow}>
+                <input
+                  type="radio"
+                  name="dataset"
+                  value={dataset.id}
+                  checked={cfg.dataset === dataset.id}
+                  onChange={(e) => {
+                    setField('dataset', e.target.value);
+                    setShowCustomDatasetInput(false);
+                    setCustomDataset('');
+                    setSelectedCfFields([]);
+                  }}
+                  className="mt-1 accent-indigo-600"
+                />
+                <div className="flex-1">
+                  <div className="font-semibold text-slate-900">{dataset.name}</div>
+                  <div className="flex items-center gap-4 text-xs text-slate-500 mt-2">
+                    {'entities' in dataset && (
+                      <span>📊 {(dataset as any).entities?.toLocaleString?.() || '-'} entities</span>
+                    )}
+                    {'groups' in dataset && <span>👥 {(dataset as any).groups || '-'} groups</span>}
+                  </div>
+                  <a
+                    href={`https://huggingface.co/datasets/${dataset.id}`}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="inline-flex items-center gap-1 text-indigo-600 hover:text-indigo-700 text-xs font-medium mt-2"
+                    onClick={(e) => e.stopPropagation()}
+                  >
+                    <ExternalLink className="w-3.5 h-3.5" />
+                    View on Hugging Face
+                  </a>
+                </div>
+              </label>
+            ))}
+
+            {/* 自訂數據集 */}
+            <label className={choiceRow}>
+              <input
+                type="radio"
+                name="dataset"
+                value="custom"
+                checked={cfg.dataset === 'custom'}
+                onChange={(e) => {
+                  setField('dataset', e.target.value);
+                  setShowCustomDatasetInput(true);
+                  setSelectedCfFields([]);
+                }}
+                className="mt-1 accent-fuchsia-600"
+              />
+              <div className="flex-1">
+                <div className="font-semibold text-slate-900">🔧 Custom Dataset Upload from Hugging Face</div>
+              </div>
+            </label>
+
+            {showCustomDatasetInput && (
+              <div className="pl-6 space-y-3 animate-in slide-in-from-top duration-300">
+                <input
+                  type="text"
+                  placeholder="Input Hugging Face Dataset ID (e.g. AmazonScience/bold)"
+                  value={customDataset}
+                  onChange={(e) => {
+                    setCustomDataset(e.target.value);
+                    setField('dataset', e.target.value);
+                  }}
+                  className={fieldInput}
+                />
+                {customDataset && customDataset.includes('/') && (
+                  <DatasetValidator datasetId={customDataset} />
+                )}
+              </div>
+            )}
+
+            {cfg.dataset === 'AmazonScience/bold' && !showCustomDatasetInput && (
+              <DatasetValidator datasetId="AmazonScience/bold" />
+            )}
+          </div>
+        </div>
+
+        {/* 反事實分析（置於中間欄） */}
+        <div className={`${card} lg:col-span-3`}>
+          <div className="flex items-center gap-3 mb-8">
+            <div className="p-3 rounded-xl bg-gradient-to-br from-pink-600 to-rose-600 shadow-md shadow-pink-600/30">
+              <Shuffle className="w-6 h-6 text-white" />
+            </div>
+            <h3 className={sectionTitle}>Counterfactual Setting</h3>
+          </div>
+
+          <div className="space-y-6">
+
+          <div className="pt-2">
+            <label className="block text-sm font-semibold text-slate-800 mb-1">
+              Number of Counterfactual
+            </label>
+            <input
+              type="number"
+              min={1}
+              max={20}
+              step={1}
+              value={numCounterfactuals}
+              onChange={(e) => {
+                const v = parseInt(e.target.value || '3', 10);
+                setNumCounterfactuals(Number.isFinite(v) ? Math.max(1, Math.min(20, v)) : 3);
+              }}
+              className={fieldInput}
+            />
+          </div>
+
+
+            {/* Dataset meta（若有 configs/splits 就顯示下拉） */}
+            {(metaConfigs.length > 0 || metaSplits.length > 0) && (
+              <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+                {metaConfigs.length > 0 && (
+                  <div>
+                    <label className="block text-sm font-semibold text-slate-800 mb-1">Dataset Config</label>
+                    <select
+                      value={selectedConfig || ''}
+                      onChange={(e) => setSelectedConfig(e.target.value || null)}
+                      className={selectInput}
+                    >
+                      {metaConfigs.map((c) => (
+                        <option key={c} value={c}>{c}</option>
+                      ))}
+                    </select>
+                  </div>
+                )}
+
+                {metaSplits.length > 0 && (
+                  <div>
+                    <label className="block text-sm font-semibold text-slate-800 mb-1">Split</label>
+                    <select
+                      value={selectedSplit}
+                      onChange={(e) => setSelectedSplit(e.target.value)}
+                      className={selectInput}
+                    >
+                      {metaSplits.map((s) => (
+                        <option key={s} value={s}>{s}</option>
+                      ))}
+                    </select>
+                  </div>
+                )}
+              </div>
+            )}
+
+            {/* 狀態列 */}
+            <div className="text-xs text-slate-500 flex items-center gap-2">
+              <span>Selected Dataset</span>
+              <span className="inline-flex items-center rounded-full bg-slate-800/90 text-white px-2.5 py-1">
+                {cfg.dataset || 'Not Selected Yet'}
+              </span>
+              {selectedConfig && <span className="ml-1">/ {selectedConfig}</span>}
+              {selectedSplit && <span className="ml-1">/ {selectedSplit}</span>}
+            </div>
+
+            {/* 欄位清單 */}
+            <div>
+              <div className="flex items-center justify-between mb-2">
+                <div className="text-sm font-semibold text-slate-800">Optional fields</div>
+                {isLoadingFields && <span className="text-xs text-slate-500">Loading</span>}
+              </div>
+
+              <div className="space-y-4 max-h-64 overflow-auto pr-1">
+                {Object.entries(fieldStats).map(([domain, categories]) => (
+                  <div key={domain} className="bg-white/50 border border-slate-200 rounded-xl p-3 shadow-sm">
+                    <div className="font-semibold text-slate-700 text-sm mb-2">{domain}</div>
+                    <div className="grid grid-cols-1 sm:grid-cols-2 gap-x-4 gap-y-2 pl-1">
+                      {Object.entries(categories).map(([category, count]) => {
+                        const fieldKey = `${domain}/${category}`;
+                        return (
+                          <label
+                            key={fieldKey}
+                            className="flex items-center gap-2 text-sm text-slate-800 hover:bg-white/60 px-2 py-1 rounded-md transition-colors"
+                          >
+                            <input
+                              type="checkbox"
+                              checked={selectedCfFields.includes(fieldKey)}
+                              onChange={() =>
+                                setSelectedCfFields((prev) =>
+                                  prev.includes(fieldKey)
+                                    ? prev.filter((x) => x !== fieldKey)
+                                    : [...prev, fieldKey]
+                                )
+                              }
+                              className="accent-fuchsia-600"
+                            />
+                            <span>{category}</span>
+                            <span className="text-xs text-slate-500">({count})</span>
+                          </label>
+                        );
+                      })}
+                    </div>
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* 模型選擇（包含 K / datasetLimit 與 metrictarget 的指定位置） */}
+        <div className={`${card} lg:col-span-3`}>
+          <div className="flex items-center gap-3 mb-8">
+            <div className="p-3 rounded-xl bg-gradient-to-br from-emerald-600 to-teal-600 shadow-md shadow-emerald-600/30">
+              <Bot className="w-6 h-6 text-white" />
+            </div>
+            <h3 className={sectionTitle}>Model Selection</h3>
+          </div>
+
+          <div className="space-y-8">
+            {/* 語言模型 */}
+            <div>
+              <label className="block text-sm font-semibold text-slate-800 mb-2">🤖 Language Generation Model</label>
+              <select
+                value={cfg.languageModel}
+                onChange={(e) => {
+                  setField('languageModel', e.target.value);
+                  setShowCustomLanguageInput(e.target.value === 'custom');
+                }}
+                className={selectInput}
+              >
+                <option value="">Select a Language Model</option>
+                {LM_MODELS.map((m) => (
+                  <option key={m.id} value={m.id}>
+                    {m.name}（{m.provider}）
+                  </option>
+                ))}
+                <option value="custom">🔧 Custom Model Upload from Hugging Face</option>
+              </select>
+
+              {showCustomLanguageInput && (
+                <input
+                  type="text"
+                  placeholder="Input Hugging Face Model ID (e.g.：microsoft/DialoGPT-medium)"
+                  value={customLM}
+                  onChange={(e) => {
+                    setCustomLM(e.target.value);
+                    setField('languageModel', e.target.value);
+                  }}
+                  className={`${fieldInput} mt-3`}
+                />
+              )}
+
+              {(customLM || cfg.languageModel) && (
+                <div className="mt-3">
+                  <ModelValidator modelId={customLM || cfg.languageModel} type="language" />
+                </div>
+              )}
+
+              {/* 語言模型下方：K 與 datasetLimit */}
+              <div className="mt-6 space-y-5">
+                <div>
+                  <label className="block text-sm font-semibold text-slate-800 mb-1">
+                    Number of Candidates
+                    <span className="ml-2 text-xs font-normal text-slate-500">The number of candidates generated for each entity</span>
+                  </label>
+                  <input
+                    type="number"
+                    min={1}
+                    max={20}
+                    value={cfg.k}
+                    onChange={(e) => setField('k', parseInt(e.target.value || '0', 10))}
+                    className={fieldInput}
+                  />
+                </div>
+
+                <div>
+                  <label className="block text-sm font-semibold text-slate-800 mb-1">
+                    Testing Data Limit
+                  </label>
+                  <input
+                    type="number"
+                    min={1}
+                    max={10000}
+                    value={datasetLimit}
+                    onChange={(e) => setDatasetLimit(parseInt(e.target.value || '0', 10))}
+                    className={fieldInput}
+                  />
+                </div>
+              </div>
+            </div>
+
+            {/* 分類任務（固定選項） */}
+            <div className="mt-6">
+              <label className="block text-sm font-semibold text-slate-800 mb-1">
+                👻 Feature Extraction Model
+              </label>
+              <select
+                value={classificationTask}
+                onChange={(e) => setClassificationTask(e.target.value as any)}
+                className={selectInput}
+              >
+              <option value="sentiment">Sentiment (0–1, Neutral ≈ 0.5)</option>
+              <option value="regard">Regard (0–2, Neutral ≈ 1.0)</option>
+              <option value="stereotype">Stereotype (0–1, Neutral ≈ 0.0)</option>
+              <option value="personality">Personality (0–1, Neutral ≈ 0.2)</option>
+              <option value="toxicity">Toxicity (0–1, Neutral ≈ 0.0)</option>
+
+              </select>
+            </div>
+
+            {/* 毒性模型選擇（只有當任務為 toxicity 時顯示） */}
+            {classificationTask === 'toxicity' && (
+              <div className="mt-4">
+                <label className="block text-sm font-semibold text-slate-800 mb-1">
+                  Toxicity Model Selection
+                </label>
+                <select
+                  value={toxicityModelChoice}
+                  onChange={(e) => setToxicityModelChoice(e.target.value as any)}
+                  className={selectInput}
+                >
+                  <option value="detoxify">unitary/toxic-bert（detoxify）</option>
+                  <option value="junglelee">JungleLee/bert-toxic-comment-classification</option>
+                </select>
+              </div>
+            )}
+
+              {/* 評分模型下方：目標指標值 */}
+              <div className="mt-6">
+                <label className="block text-sm font-semibold text-slate-800 mb-1">
+                  Metric Target Value
+                  <span className="ml-2 text-xs font-normal text-slate-500">Indicator thresholds used to determine compliance</span>
+                </label>
+                <input
+                  type="number"
+                  min={0}
+                  max={2}
+                  step={0.01}
+                  value={cfg.metrictarget}
+                  onChange={(e) => setField('metrictarget', parseFloat(e.target.value || '0'))}
+                  className={fieldInput}
+                />
+
+
+            </div>
+          </div>
+        </div>
+        {/* Fine-tuning 設定 */}
+        <div className={`${card} lg:col-span-3`}>
+          <div className="flex items-center gap-3 mb-8">
+            <div className="p-3 rounded-xl bg-gradient-to-br from-orange-500 to-yellow-500 shadow-md shadow-orange-500/30">
+              <Database className="w-6 h-6 text-white" />
+            </div>
+            <h3 className={sectionTitle}>Fine-tuning Setting</h3>
+          </div>
+
+          <div className="space-y-6">
+            <label className="flex items-center gap-2">
+              <input
+                type="checkbox"
+                checked={cfg.enableFineTuning}
+                onChange={(e) => setField('enableFineTuning', e.target.checked)}
+                className="accent-orange-500"
+              />
+              <span className="text-sm text-slate-800 font-semibold">Enable Fine-tuning</span>
+            </label>
+
+            {cfg.enableFineTuning && (
+              <div className="space-y-4 pl-4 border-l-2 border-orange-200">
+                {/* Epochs */}
+                <div>
+                  <label className="block text-sm font-semibold text-slate-800 mb-1">
+                    Training Epochs
+                  </label>
+                  <input
+                    type="number"
+                    min={1}
+                    max={100}
+                    value={ftEpochs}
+                    onChange={(e) => setFtEpochs(parseInt(e.target.value || '3', 10))}
+                    className={fieldInput}
+                  />
+                </div>
+
+                {/* Batch Size */}
+                <div>
+                  <label className="block text-sm font-semibold text-slate-800 mb-1">
+                    Batch Size
+                  </label>
+                  <input
+                    type="number"
+                    min={1}
+                    max={256}
+                    value={ftBatchSize}
+                    onChange={(e) => setFtBatchSize(parseInt(e.target.value || '8', 10))}
+                    className={fieldInput}
+                  />
+                </div>
+
+                {/* Learning Rate */}
+                <div>
+                  <label className="block text-sm font-semibold text-slate-800 mb-1">
+                    Learning Rate
+                  </label>
+                  <input
+                    type="number"
+                    step={0.00001}
+                    value={ftLR}
+                    onChange={(e) => setFtLR(parseFloat(e.target.value || '0.00005'))}
+                    className={fieldInput}
+                  />
+                </div>
+              </div>
+            )}
+          </div>
+        </div>
+
+      </div>
+
+      {/* 開始按鈕 */}
+      <div className="flex">
+        <button
+          onClick={() => {
+            const fullCfg = {
+              ...cfg,
+              selectedCfFields, 
+              numCounterfactuals,
+              classificationTask,
+              toxicityModelChoice,
+              finetuneParams: {
+              epochs: ftEpochs,
+              batchSize: ftBatchSize,
+              learningRate: ftLR,
+            },         
+            };
+            onRun(fullCfg, {
+              datasetLimit
+            });
+          }}
+          disabled={!canStart}
+          className="relative w-full group overflow-hidden rounded-2xl px-6 py-4 text-white font-semibold bg-gradient-to-r from-indigo-600 via-violet-600 to-fuchsia-600 shadow-lg shadow-indigo-600/20 enabled:hover:shadow-indigo-600/40 transition-all enabled:hover:translate-y-[-1px] enabled:active:translate-y-0 disabled:opacity-60 disabled:cursor-not-allowed"
+        >
+          <span className="relative z-10">🚀 Start</span>
+          <span className="absolute inset-0 opacity-0 group-hover:opacity-100 transition-opacity bg-[radial-gradient(1200px_200px_at_50%_-40%,rgba(255,255,255,0.35),transparent_60%)]" />
+        </button>
+      </div>
+
+    </div>
+  );
+}

frontend/src/pages/ResultsPage.tsx

@@ -0,0 +1,144 @@
+import PipelineProgress from '../components/PipelineProgress';
+import { useJobRunner } from '../hooks/JobRunnerProvider';
+
+export default function ResultsPage() {
+  const { result, resp, loading, error, url } = useJobRunner();
+
+  if (loading && !resp) {
+    return (
+      <div className="space-y-6">
+        <PipelineProgress />
+        <section className="grid grid-cols-1 md:grid-cols-2 gap-6">
+          {[0, 1].map((i) => (
+            <div key={i} className="rounded-2xl border bg-white/70 backdrop-blur p-3">
+              <div className="w-full h-64 rounded-xl bg-gradient-to-b from-slate-200 to-slate-100 animate-pulse" />
+              <div className="mt-3 h-4 w-40 rounded bg-slate-200 animate-pulse" />
+            </div>
+          ))}
+        </section>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="p-6 rounded-2xl bg-red-50 border border-red-200 text-red-700">
+        {error}
+      </div>
+    );
+  }
+
+  if (!result || !resp) {
+    return (
+      <div className="p-6 rounded-2xl bg-white/70 border border-white/40">
+        Task not executed yet
+      </div>
+    );
+  }
+
+  const m = result.metrics!;
+  const plots = resp.results.plots;
+
+  const originalSrc = url(plots.original_sentiment);
+  const cfSrc = url(plots.counterfactual_sentiment);
+
+  const r = resp.results as any;
+  const links: { label: string; href: string }[] = [];
+
+  if (r?.generation_file) {
+    links.push({ label: 'Generation CSV', href: r.generation_file });
+  }
+  if (r?.sentiment_subset_file) {
+    links.push({ label: 'Original sentiment subset CSV', href: r.sentiment_subset_file });
+  }
+  if (r?.cf_sentiment_subset_file) {
+    links.push({ label: 'CF sentiment subset CSV', href: r.cf_sentiment_subset_file });
+  }
+
+  if (r?.run_config_files?.markdown) {
+    links.push({ label: 'Run Config (Markdown)', href: r.run_config_files.markdown });
+  }
+  if (r?.run_config_files?.json) {
+    links.push({ label: 'Run Config (JSON)', href: r.run_config_files.json });
+  }
+
+  if (r?.finetuned_model_zip) {
+    links.push({ label: 'Fine-tuned Model (ZIP)', href: r.finetuned_model_zip });
+  } else if (r?.finetuned_model_dir) {
+    links.push({ label: 'Fine-tuned Model Folder', href: r.finetuned_model_dir });
+  }
+
+  return (
+    <div className="space-y-6">
+      {loading && <PipelineProgress />}
+
+      <section className="p-6 rounded-2xl border border-white/40 bg-white/70 backdrop-blur">
+        <h2 className="text-lg font-semibold mb-3">Metric</h2>
+        <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+          <div className="p-4 rounded-xl bg-slate-50 border">
+            <div className="text-slate-500 text-sm">Original Difference</div>
+            <div className="text-2xl font-bold">{m.finalMeanDiff.toFixed(4)}</div>
+          </div>
+          <div className="p-4 rounded-xl bg-slate-50 border">
+            <div className="text-slate-500 text-sm">CF Difference</div>
+            <div className="text-2xl font-bold">
+              {resp.results.metrics.cfFinalMeanDiff.toFixed(4)}
+            </div>
+          </div>
+        </div>
+      </section>
+
+      <section className="p-6 rounded-2xl border border-white/40 bg-white/70 backdrop-blur">
+        <h2 className="text-lg font-semibold mb-4">Distribution</h2>
+        <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+          <figure className="rounded-xl overflow-hidden border bg-white">
+            <img
+              src={originalSrc}
+              alt="Original distribution"
+              className="w-full h-auto"
+              loading="lazy"
+              onError={(e) => {
+                e.currentTarget.alt = 'Original image loading failed';
+              }}
+            />
+            <figcaption className="p-3 text-sm text-slate-600">Original</figcaption>
+          </figure>
+
+          <figure className="rounded-xl overflow-hidden border bg-white">
+            <img
+              src={cfSrc}
+              alt="Counterfactual distribution"
+              className="w-full h-auto"
+              loading="lazy"
+              onError={(e) => {
+                e.currentTarget.alt = 'Counterfactual image loading failed';
+              }}
+            />
+            <figcaption className="p-3 text-sm text-slate-600">Counterfactual Augmented</figcaption>
+          </figure>
+        </div>
+      </section>
+
+      {links.length > 0 && (
+        <section className="p-6 rounded-2xl border border-white/40 bg-white/70 backdrop-blur">
+          <h2 className="text-lg font-semibold mb-4">Download Report</h2>
+          <ul className="space-y-2">
+            {links.map((l) => (
+              <li key={l.label}>
+                <a
+                  className="text-indigo-600 hover:underline"
+                  href={url(l.href)}
+                  target="_blank"
+                  rel="noreferrer"
+                  download
+                >
+                  {l.label}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </div>
+  );
+}

frontend/src/services/api.ts

@@ -0,0 +1,70 @@
+// src/services/api.ts
+import type { JobConfig } from '../types';
+
+export type PipelinePlots = {
+  original_sentiment: string;
+  counterfactual_sentiment: string;
+};
+
+export type PipelineResultsDTO = {
+  data_loaded: number;
+  model_loaded: string;
+
+  generation_file: string;
+  generation_samples: number;
+
+  counterfactual_file: string;
+  counterfactual_added: number;
+  counterfactual_total: number;
+
+  sampling_method: string;
+  sentiment_subset_file: string;
+  sentiment_subset_size: number;
+
+  cf_sentiment_subset_file: string;
+  cf_sentiment_subset_size: number;
+
+  // 後端還會給 stereotype 的欄位，但前端不需要可不宣告
+  config_used: import('../types').JobConfig;
+  metrics: import('../types').JobMetrics & {
+    finalMeanDiff: number;
+    cfFinalMeanDiff: number;
+  };
+  plots: PipelinePlots;
+};
+
+export type PipelineResponseDTO = {
+  status: 'success' | 'error';
+  message: string;
+  timestamp: string;
+  results: PipelineResultsDTO;
+};
+
+const BASE = import.meta.env.VITE_API_BASE ?? '/api';
+
+async function runPipeline(config: any) {
+  const r = await fetch(`${BASE}/pipeline`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ config }),
+  });
+  if (!r.ok) {
+    const text = await r.text();
+    throw new Error(`Pipeline failed (${r.status}): ${text}`);
+  }
+  return r.json();
+}
+
+async function checkHealth() {
+  const r = await fetch(`${BASE}/health`);
+  return r.json();
+}
+
+function resolvePath(p?: string) {
+  if (!p) return '';
+  if (p.startsWith('http')) return p;
+  const path = p.startsWith('/') ? p : `/${p}`;
+  return `${BASE}${path}`;
+}
+
+export const MLBiasAPI = { runPipeline, checkHealth, resolvePath };

frontend/src/services/hf.ts

@@ -0,0 +1,12 @@
+// src/services/hf.ts
+export async function fetchHFModel(modelId: string) {
+  const r = await fetch(`https://huggingface.co/api/models/${modelId}`);
+  if (!r.ok) throw new Error('The model does not exist or cannot be accessed');
+  return r.json();
+}
+
+export async function fetchHFDataset(datasetId: string) {
+  const r = await fetch(`https://huggingface.co/api/datasets/${datasetId}`);
+  if (!r.ok) throw new Error('The dataset does not exist or cannot be accessed');
+  return r.json();
+}

frontend/src/types/index.ts

@@ -0,0 +1,60 @@
+// src/types/index.ts
+export type Dataset = {
+  id: string;
+  name: string;
+};
+
+export type Model = {
+  id: string;
+  name: string;
+  type: 'language' | 'scorer';
+  description: string;
+  provider: string;
+};
+
+export type JobConfig = {
+  dataset: string;
+  languageModel: string;
+  scorerModel: string;
+  k: number;
+  tau: number;
+  iterations: number;
+  seed: number;
+  enableFineTuning: boolean;
+  counterfactual: boolean;
+  metrictarget: number;
+  numCounterfactuals: number;
+  selectedCfFields?: string[];
+  
+};
+
+export type JobStatus = 'running' | 'completed' | 'failed';
+
+export type ChartPoint = {
+  iteration: number;
+  meanDifference: number;
+  groupA: number;
+  groupB: number;
+};
+
+export type JobMetrics = {
+  finalMeanDiff: number;
+  reductionPct: number;
+  stableCoverage: number;
+};
+
+export type JobResult = {
+  id: string;
+  status: JobStatus;
+  progress: number; // 0-100
+  config: JobConfig;
+  createdAt: string;
+  updatedAt: string;
+  completedAt?: string;
+  charts?: ChartPoint[];
+  metrics?: JobMetrics;
+};
+
+export type Extras = {
+  datasetLimit: number;
+};

frontend/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

frontend/tailwind.config.js

@@ -0,0 +1,11 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [require('@tailwindcss/forms')],
+}

frontend/tsconfig.app.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}
+

frontend/tsconfig.node.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})

nginx.conf.template

@@ -0,0 +1,40 @@
+worker_processes auto;
+events { 
+    worker_connections 1024; 
+}
+
+http {
+    include       /etc/nginx/mime.types;
+    default_type  application/octet-stream;
+    sendfile      on;
+    keepalive_timeout  65;
+    
+    server {
+        listen 7860;
+        server_name _;
+        root  /usr/share/nginx/html;
+        index index.html;
+        
+        # 前端單頁應用
+        location / {
+            try_files $uri $uri/ /index.html;
+        }
+        
+        # 後端 API 反向代理
+        location /api/ {
+            proxy_pass http://127.0.0.1:5001/;
+            proxy_http_version 1.1;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection "upgrade";
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_buffering off;
+
+            proxy_connect_timeout 3000s;
+            proxy_send_timeout 3000s;
+            proxy_read_timeout 3000s;
+            proxy_redirect off;
+
+        }
+    }
+}