Create app.py

app.py

@@ -0,0 +1,833 @@
+# app.py
+# Hugging Face Space (Gradio) for a deterministic "Black-Box Translator" demo (Chess + Shogi).
+# No engines. No learning. Pure rule-based, reproducible heuristics + structured logs.
+
+from __future__ import annotations
+
+import math
+import os
+import platform
+import re
+import sys
+import traceback
+from dataclasses import dataclass, asdict
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+import matplotlib.pyplot as plt
+import gradio as gr
+
+try:
+    from importlib import metadata as importlib_metadata  # py3.8+
+except Exception:  # pragma: no cover
+    import importlib_metadata  # type: ignore
+
+
+# ---------------------------
+# Repro snapshot
+# ---------------------------
+
+def _pkg_version(name: str) -> str:
+    try:
+        return importlib_metadata.version(name)
+    except Exception:
+        return "unknown"
+
+def repro_snapshot() -> Dict[str, Any]:
+    return {
+        "utc_now": datetime.now(timezone.utc).isoformat(),
+        "python": sys.version.replace("\n", " "),
+        "platform": platform.platform(),
+        "packages": {
+            "gradio": _pkg_version("gradio"),
+            "pandas": _pkg_version("pandas"),
+            "matplotlib": _pkg_version("matplotlib"),
+            "chess": _pkg_version("chess"),
+            "python-shogi": _pkg_version("python-shogi"),
+        },
+    }
+
+
+# ---------------------------
+# Generic scoring/logging
+# ---------------------------
+
+AXES_ORDER = [
+    "material",
+    "king_safety",
+    "development",
+    "center_control",
+    "mobility",
+    "tactical_pressure",
+]
+
+DEFAULT_WEIGHTS = {
+    "material": 1.8,
+    "king_safety": 1.4,
+    "development": 1.0,
+    "center_control": 1.0,
+    "mobility": 0.8,
+    "tactical_pressure": 1.2,
+}
+
+def clamp(x: float, lo: float = -1.0, hi: float = 1.0) -> float:
+    return max(lo, min(hi, x))
+
+def weighted_score(axes: Dict[str, float], weights: Dict[str, float]) -> float:
+    s = 0.0
+    for k, w in weights.items():
+        if k in axes and axes[k] is not None:
+            s += w * float(axes[k])
+    return float(s)
+
+def axes_df(before: Dict[str, float], after: Dict[str, float], weights: Dict[str, float]) -> pd.DataFrame:
+    rows = []
+    for k in AXES_ORDER:
+        b = float(before.get(k, 0.0))
+        a = float(after.get(k, 0.0))
+        d = a - b
+        rows.append({
+            "axis": k,
+            "before": round(b, 4),
+            "after": round(a, 4),
+            "delta": round(d, 4),
+            "weight": float(weights.get(k, 0.0)),
+            "weighted_delta": round(d * float(weights.get(k, 0.0)), 4),
+        })
+    return pd.DataFrame(rows)
+
+def build_comment(axis_table: pd.DataFrame, chosen_move: str) -> str:
+    df = axis_table.copy()
+    df["abs_wd"] = df["weighted_delta"].abs()
+    df = df.sort_values("abs_wd", ascending=False)
+    top = df.head(2).to_dict("records")
+    parts = []
+    for r in top:
+        sign = "↑" if r["weighted_delta"] >= 0 else "↓"
+        parts.append(f"- {r['axis']}: {sign} (Δ={r['delta']}, wΔ={r['weighted_delta']})")
+    core = "\n".join(parts) if parts else "- (no decisive axis change detected)"
+    return f"**Move:** `{chosen_move}`\n\n**Why (deterministic heuristic):**\n{core}"
+
+def build_hds_log(axis_table: pd.DataFrame, score_before: float, score_after: float) -> str:
+    df = axis_table.copy()
+    df = df.sort_values("weighted_delta", ascending=False)
+    top_pos = df.head(2).to_dict("records")
+    top_neg = df.tail(2).to_dict("records")
+
+    def _fmt(rs):
+        out = []
+        for r in rs:
+            sign = "+" if r["weighted_delta"] >= 0 else ""
+            out.append(f"  - {r['axis']}: Δ={r['delta']} / wΔ={sign}{r['weighted_delta']}")
+        return "\n".join(out) if out else "  - (none)"
+
+    lines = []
+    lines.append("### HDS Log (deterministic)\n")
+    lines.append("**Layer 1 — Validity**")
+    lines.append("- Input parsed and move legality checked inside the rules library.")
+    lines.append("")
+    lines.append("**Layer 2 — Axis deltas (what changed)**")
+    lines.append(_fmt(top_pos))
+    lines.append(_fmt(top_neg))
+    lines.append("")
+    lines.append("**Layer 3 — Causal chain (why those deltas happen)**")
+    lines.append("- This demo uses only board-state features (no search, no evaluation engine).")
+    lines.append("- Axis deltas come from measurable state transitions (piece locations, legal-move counts, checks, center occupancy).")
+    lines.append("")
+    lines.append("**Layer 4 — Counterfactual hint**")
+    lines.append("- Compare with the 'Top alternatives' table below (same heuristic score, same weights).")
+    lines.append("")
+    lines.append("**Layer 5 — Reproducibility**")
+    lines.append(f"- score_before={round(score_before, 4)} / score_after={round(score_after, 4)} / Δ={round(score_after-score_before, 4)}")
+    lines.append("- No randomness. Same input => same output (given identical library versions).")
+    return "\n".join(lines)
+
+def plot_axis_deltas(axis_table: pd.DataFrame) -> Any:
+    df = axis_table.copy()
+    plt.figure()
+    plt.bar(df["axis"], df["weighted_delta"])
+    plt.xticks(rotation=30, ha="right")
+    plt.title("Weighted delta by axis")
+    plt.tight_layout()
+    return plt.gcf()
+
+
+# ---------------------------
+# Chess (python-chess) logic
+# ---------------------------
+
+def _import_chess():
+    import chess  # type: ignore
+    return chess
+
+PIECE_VALUE_CHESS = {
+    "P": 1.0,
+    "N": 3.1,
+    "B": 3.3,
+    "R": 5.1,
+    "Q": 9.5,
+    "K": 0.0,
+}
+
+CENTER_SQUARES_CHESS = ["d4", "e4", "d5", "e5"]
+
+def chess_color_from_perspective(board, perspective: str):
+    chess = _import_chess()
+    if perspective == "side_to_move":
+        return board.turn
+    if perspective == "white":
+        return chess.WHITE
+    return chess.BLACK
+
+def _chess_material(board, me_color) -> float:
+    chess = _import_chess()
+    score = 0.0
+    for piece_type, v in [
+        (chess.PAWN, PIECE_VALUE_CHESS["P"]),
+        (chess.KNIGHT, PIECE_VALUE_CHESS["N"]),
+        (chess.BISHOP, PIECE_VALUE_CHESS["B"]),
+        (chess.ROOK, PIECE_VALUE_CHESS["R"]),
+        (chess.QUEEN, PIECE_VALUE_CHESS["Q"]),
+    ]:
+        my = len(board.pieces(piece_type, me_color))
+        op = len(board.pieces(piece_type, not me_color))
+        score += v * (my - op)
+    return clamp(score / 39.0)
+
+def _chess_king_safety(board, me_color) -> float:
+    chess = _import_chess()
+    king_sq = board.king(me_color)
+    if king_sq is None:
+        return 0.0
+    ring = []
+    kf = chess.square_file(king_sq)
+    kr = chess.square_rank(king_sq)
+    for df in (-1, 0, 1):
+        for dr in (-1, 0, 1):
+            if df == 0 and dr == 0:
+                continue
+            f = kf + df
+            r = kr + dr
+            if 0 <= f <= 7 and 0 <= r <= 7:
+                ring.append(chess.square(f, r))
+    defenders = 0
+    attackers = 0
+    for sq in ring:
+        p = board.piece_at(sq)
+        if p is not None and p.color == me_color:
+            defenders += 1
+        if board.is_attacked_by(not me_color, sq):
+            attackers += 1
+    raw = (defenders - attackers) / 8.0
+    return clamp(raw)
+
+def _chess_development(board, me_color) -> float:
+    chess = _import_chess()
+    dev = 0
+    total = 0
+    start = {
+        chess.WHITE: {
+            chess.KNIGHT: [chess.B1, chess.G1],
+            chess.BISHOP: [chess.C1, chess.F1],
+        },
+        chess.BLACK: {
+            chess.KNIGHT: [chess.B8, chess.G8],
+            chess.BISHOP: [chess.C8, chess.F8],
+        },
+    }
+    for pt in (chess.KNIGHT, chess.BISHOP):
+        total += 2
+        squares = list(board.pieces(pt, me_color))
+        for s in squares:
+            if s not in start[me_color][pt]:
+                dev += 1
+    return clamp((dev - 1.0) / 1.0)
+
+def _chess_center_control(board, me_color) -> float:
+    chess = _import_chess()
+    score = 0.0
+    for name in CENTER_SQUARES_CHESS:
+        sq = chess.parse_square(name)
+        p = board.piece_at(sq)
+        if p is not None:
+            score += (1.0 if p.color == me_color else -1.0) * 0.5
+        if board.is_attacked_by(me_color, sq):
+            score += 0.25
+        if board.is_attacked_by(not me_color, sq):
+            score -= 0.25
+    return clamp(score / 2.0)
+
+def _chess_mobility(board, me_color) -> float:
+    b = board.copy(stack=False)
+    b.turn = me_color
+    m = b.legal_moves.count()
+    return clamp((min(m, 60) - 30) / 30)
+
+def _chess_tactical_pressure(board, me_color) -> float:
+    chess = _import_chess()
+    b = board.copy(stack=False)
+    b.turn = me_color
+    total = 0
+    checks = 0
+    captures = 0
+    for mv in b.legal_moves:
+        total += 1
+        if b.is_capture(mv):
+            captures += 1
+        b2 = b.copy(stack=False)
+        b2.push(mv)
+        if b2.is_check():
+            checks += 1
+    if total == 0:
+        return 0.0
+    raw = 0.6 * (checks / total) + 0.4 * (captures / total)
+    return clamp((raw - 0.15) / 0.35)
+
+def evaluate_axes_chess(board, perspective: str) -> Dict[str, float]:
+    me_color = chess_color_from_perspective(board, perspective)
+    axes = {
+        "material": _chess_material(board, me_color),
+        "king_safety": _chess_king_safety(board, me_color),
+        "development": _chess_development(board, me_color),
+        "center_control": _chess_center_control(board, me_color),
+        "mobility": _chess_mobility(board, me_color),
+        "tactical_pressure": _chess_tactical_pressure(board, me_color),
+    }
+    return {k: float(v) for k, v in axes.items()}
+
+def explain_chess_move_en(fen: str, move_uci: str, perspective: str = "side_to_move",
+                         weights: Dict[str, float] = DEFAULT_WEIGHTS, topk: int = 8):
+    chess = _import_chess()
+    board = chess.Board(fen)
+
+    mv = chess.Move.from_uci(move_uci)
+    if mv not in board.legal_moves:
+        raise ValueError("Illegal move for the given FEN (UCI).")
+
+    axes_before = evaluate_axes_chess(board, perspective)
+    score_before = weighted_score(axes_before, weights)
+
+    board_after = board.copy(stack=False)
+    board_after.push(mv)
+
+    axes_after = evaluate_axes_chess(board_after, perspective)
+    score_after = weighted_score(axes_after, weights)
+
+    df_axes = axes_df(axes_before, axes_after, weights)
+    comment = build_comment(df_axes, move_uci)
+    hds_log = build_hds_log(df_axes, score_before, score_after)
+
+    alt_rows = []
+    for cand in board.legal_moves:
+        if cand == mv:
+            continue
+        b2 = board.copy(stack=False)
+        b2.push(cand)
+        a2 = evaluate_axes_chess(b2, perspective)
+        s2 = weighted_score(a2, weights)
+        alt_rows.append({
+            "move": cand.uci(),
+            "score_after": round(s2, 4),
+            "delta_vs_chosen": round(s2 - score_after, 4),
+            "gives_check": b2.is_check(),
+        })
+    alt_df = pd.DataFrame(alt_rows)
+    if len(alt_df) > 0:
+        alt_df = alt_df.sort_values("score_after", ascending=False).head(topk)
+
+    fig = plot_axis_deltas(df_axes)
+
+    return {
+        "game": "chess",
+        "input": {"fen": fen, "move_uci": move_uci, "perspective": perspective},
+        "scores": {"before": score_before, "after": score_after, "delta": score_after - score_before},
+        "axes_table": df_axes,
+        "alternatives": alt_df,
+        "comment_md": comment,
+        "hds_md": hds_log,
+        "plot_fig": fig,
+        "repro": repro_snapshot(),
+    }
+
+
+# ---------------------------
+# Shogi (python-shogi) logic
+# ---------------------------
+
+def _try_import_shogi():
+    import shogi  # type: ignore
+    return shogi
+
+PIECE_VALUE_SHOGI = {
+    "P": 1.0,
+    "L": 3.0,
+    "N": 3.0,
+    "S": 4.0,
+    "G": 5.0,
+    "B": 8.0,
+    "R": 10.0,
+    "K": 0.0,
+    "+P": 5.0,
+    "+L": 5.0,
+    "+N": 5.0,
+    "+S": 5.0,
+    "+B": 9.0,
+    "+R": 11.0,
+}
+
+def _shogi_square_maps(shogi_mod):
+    names = getattr(shogi_mod, "SQUARE_NAMES", None)
+    if names is None:
+        files = list(range(9, 0, -1))
+        ranks = list("abcdefghi")
+        names = []
+        for r in ranks:
+            for f in files:
+                names.append(f"{f}{r}")
+    name_to_sq = {n: i for i, n in enumerate(names)}
+    return names, name_to_sq
+
+def _shogi_piece_key(piece):
+    sym = None
+    if hasattr(piece, "symbol"):
+        try:
+            sym = piece.symbol()
+        except Exception:
+            sym = None
+    if sym is None:
+        sym = str(piece)
+
+    is_black = True
+    if len(sym) >= 1 and sym[-1].isalpha():
+        is_black = sym[-1].isupper()
+
+    promo = sym.startswith("+")
+    base = sym[-1].upper() if sym[-1].isalpha() else sym[-1]
+    key = f"+{base}" if promo else base
+    return key, is_black
+
+def _shogi_material(board, shogi_mod, me_black: bool) -> float:
+    names, _ = _shogi_square_maps(shogi_mod)
+    total = 0.0
+    squares = getattr(shogi_mod, "SQUARES", list(range(len(names))))
+    for sq in squares:
+        try:
+            p = board.piece_at(sq)
+        except Exception:
+            p = None
+        if p is None:
+            continue
+        key, is_black = _shogi_piece_key(p)
+        v = PIECE_VALUE_SHOGI.get(key, 0.0)
+        total += v * (1.0 if (is_black == me_black) else -1.0)
+
+    try:
+        hands = board.pieces_in_hand  # type: ignore
+        my_hand = hands[shogi_mod.BLACK if me_black else shogi_mod.WHITE]
+        op_hand = hands[shogi_mod.WHITE if me_black else shogi_mod.BLACK]
+        symtab = getattr(shogi_mod, "PIECE_SYMBOLS", None)
+
+        def hand_value(hand_obj, sign: float):
+            nonlocal total
+            if isinstance(hand_obj, dict):
+                it = hand_obj.items()
+            else:
+                it = enumerate(hand_obj)
+            for k, cnt in it:
+                if cnt is None:
+                    continue
+                if symtab is not None and isinstance(k, int) and 0 <= k < len(symtab):
+                    sym = symtab[k]
+                else:
+                    sym = str(k)
+                sym = sym.upper()
+                v = PIECE_VALUE_SHOGI.get(sym, PIECE_VALUE_SHOGI.get(sym[-1], 0.0))
+                total += sign * v * float(cnt)
+
+        hand_value(my_hand, +1.0)
+        hand_value(op_hand, -1.0)
+    except Exception:
+        pass
+
+    return clamp(total / 60.0)
+
+def _shogi_find_king_square(board, shogi_mod, me_black: bool) -> Optional[int]:
+    names, _ = _shogi_square_maps(shogi_mod)
+    squares = getattr(shogi_mod, "SQUARES", list(range(len(names))))
+    for sq in squares:
+        p = board.piece_at(sq)
+        if p is None:
+            continue
+        key, is_black = _shogi_piece_key(p)
+        if key == "K" and (is_black == me_black):
+            return sq
+    return None
+
+def _shogi_neighbors(sq_name: str, names_set: set) -> List[str]:
+    m = re.fullmatch(r"([1-9])([a-i])", sq_name)
+    if not m:
+        return []
+    f = int(m.group(1))
+    r = m.group(2)
+    ranks = "abcdefghi"
+    ri = ranks.index(r)
+    out = []
+    for df in (-1, 0, 1):
+        for dr in (-1, 0, 1):
+            if df == 0 and dr == 0:
+                continue
+            nf = f + df
+            nri = ri + dr
+            if 1 <= nf <= 9 and 0 <= nri <= 8:
+                cand = f"{nf}{ranks[nri]}"
+                if cand in names_set:
+                    out.append(cand)
+    return out
+
+def _shogi_king_safety(board, shogi_mod, me_black: bool) -> float:
+    names, name_to_sq = _shogi_square_maps(shogi_mod)
+    king_sq = _shogi_find_king_square(board, shogi_mod, me_black)
+    if king_sq is None:
+        return 0.0
+    king_name = names[king_sq]
+    names_set = set(names)
+    ring = _shogi_neighbors(king_name, names_set)
+
+    defenders = 0
+    enemies_near = 0
+    for n in ring:
+        sq = name_to_sq.get(n)
+        if sq is None:
+            continue
+        p = board.piece_at(sq)
+        if p is None:
+            continue
+        _, is_black = _shogi_piece_key(p)
+        if is_black == me_black:
+            defenders += 1
+        else:
+            enemies_near += 1
+
+    raw = (defenders - enemies_near) / 8.0
+    return clamp(raw)
+
+def _shogi_development(board, shogi_mod, me_black: bool) -> float:
+    names, _ = _shogi_square_maps(shogi_mod)
+    squares = getattr(shogi_mod, "SQUARES", list(range(len(names))))
+    ranks = "abcdefghi"
+    adv = []
+    for sq in squares:
+        p = board.piece_at(sq)
+        if p is None:
+            continue
+        key, is_black = _shogi_piece_key(p)
+        if is_black != me_black:
+            continue
+        base = key[-1]
+        if base in ("K", "P"):
+            continue
+        sqn = names[sq]
+        m = re.fullmatch(r"([1-9])([a-i])", sqn)
+        if not m:
+            continue
+        ri = ranks.index(m.group(2))
+        a = (8 - ri) if me_black else ri
+        adv.append(a / 8.0)
+    if not adv:
+        return 0.0
+    return clamp((sum(adv) / len(adv) - 0.35) / 0.35)
+
+def _shogi_center_control(board, shogi_mod, me_black: bool) -> float:
+    names, _ = _shogi_square_maps(shogi_mod)
+    squares = getattr(shogi_mod, "SQUARES", list(range(len(names))))
+    score = 0.0
+    for sq in squares:
+        p = board.piece_at(sq)
+        if p is None:
+            continue
+        _, is_black = _shogi_piece_key(p)
+        sqn = names[sq]
+        m = re.fullmatch(r"([1-9])([a-i])", sqn)
+        if not m:
+            continue
+        f = int(m.group(1))
+        r = m.group(2)
+        if 4 <= f <= 6 and r in ("d", "e", "f"):
+            score += 1.0 if (is_black == me_black) else -1.0
+    return clamp(score / 6.0)
+
+def _shogi_mobility(board, shogi_mod, me_black: bool) -> float:
+    b = shogi_mod.Board(board.sfen()) if hasattr(board, "sfen") else board
+    try:
+        b.turn = shogi_mod.BLACK if me_black else shogi_mod.WHITE
+    except Exception:
+        pass
+    try:
+        m = len(list(b.legal_moves))
+    except Exception:
+        m = 0
+    return clamp((min(m, 250) - 80) / 80)
+
+def _shogi_tactical_pressure(board, shogi_mod, me_black: bool) -> float:
+    names, name_to_sq = _shogi_square_maps(shogi_mod)
+    b = shogi_mod.Board(board.sfen()) if hasattr(board, "sfen") else board
+    try:
+        b.turn = shogi_mod.BLACK if me_black else shogi_mod.WHITE
+    except Exception:
+        pass
+
+    def move_to_name(move_str: str) -> Optional[str]:
+        m = re.fullmatch(r"([1-9][a-i])([1-9][a-i])(\+)?", move_str)
+        if m:
+            return m.group(2)
+        m = re.fullmatch(r"[PLNSGBRK]\*([1-9][a-i])", move_str)
+        if m:
+            return m.group(1)
+        return None
+
+    total = 0
+    checks = 0
+    captureish = 0
+
+    try:
+        legal = list(b.legal_moves)
+    except Exception:
+        legal = []
+
+    for mv in legal:
+        total += 1
+        mv_usi = mv.usi() if hasattr(mv, "usi") else str(mv)
+
+        dest = move_to_name(mv_usi)
+        if dest is not None:
+            sq = name_to_sq.get(dest)
+            if sq is not None:
+                p = b.piece_at(sq)
+                if p is not None:
+                    _, is_black = _shogi_piece_key(p)
+                    if is_black != me_black:
+                        captureish += 1
+
+        try:
+            b2 = shogi_mod.Board(b.sfen())
+            b2.push_usi(mv_usi)
+            if hasattr(b2, "is_check") and b2.is_check():
+                checks += 1
+        except Exception:
+            pass
+
+    if total == 0:
+        return 0.0
+    raw = 0.6 * (checks / total) + 0.4 * (captureish / total)
+    return clamp((raw - 0.10) / 0.30)
+
+def evaluate_axes_shogi(board, shogi_mod, perspective: str) -> Dict[str, float]:
+    if perspective == "side_to_move":
+        me_black = (board.turn == shogi_mod.BLACK)
+    elif perspective == "black":
+        me_black = True
+    else:
+        me_black = False
+
+    axes = {
+        "material": _shogi_material(board, shogi_mod, me_black),
+        "king_safety": _shogi_king_safety(board, shogi_mod, me_black),
+        "development": _shogi_development(board, shogi_mod, me_black),
+        "center_control": _shogi_center_control(board, shogi_mod, me_black),
+        "mobility": _shogi_mobility(board, shogi_mod, me_black),
+        "tactical_pressure": _shogi_tactical_pressure(board, shogi_mod, me_black),
+    }
+    return {k: float(v) for k, v in axes.items()}
+
+def explain_shogi_move_en(sfen: str, move_usi: str, perspective: str = "side_to_move",
+                         weights: Dict[str, float] = DEFAULT_WEIGHTS, topk: int = 8):
+    shogi_mod = _try_import_shogi()
+    board = shogi_mod.Board(sfen)
+
+    legal = list(board.legal_moves)
+    legal_usi = [(m.usi() if hasattr(m, "usi") else str(m)) for m in legal]
+    if move_usi not in legal_usi:
+        raise ValueError("Illegal move for the given SFEN (USI).")
+
+    axes_before = evaluate_axes_shogi(board, shogi_mod, perspective)
+    score_before = weighted_score(axes_before, weights)
+
+    board_after = shogi_mod.Board(board.sfen())
+    board_after.push_usi(move_usi)
+
+    axes_after = evaluate_axes_shogi(board_after, shogi_mod, perspective)
+    score_after = weighted_score(axes_after, weights)
+
+    df_axes = axes_df(axes_before, axes_after, weights)
+    comment = build_comment(df_axes, move_usi)
+    hds_log = build_hds_log(df_axes, score_before, score_after)
+
+    alt_rows = []
+    for cand in legal_usi:
+        if cand == move_usi:
+            continue
+        try:
+            b2 = shogi_mod.Board(board.sfen())
+            b2.push_usi(cand)
+            a2 = evaluate_axes_shogi(b2, shogi_mod, perspective)
+            s2 = weighted_score(a2, weights)
+            gives_check = (b2.is_check() if hasattr(b2, "is_check") else False)
+            alt_rows.append({
+                "move": cand,
+                "score_after": round(s2, 4),
+                "delta_vs_chosen": round(s2 - score_after, 4),
+                "gives_check": gives_check,
+            })
+        except Exception:
+            continue
+    alt_df = pd.DataFrame(alt_rows)
+    if len(alt_df) > 0:
+        alt_df = alt_df.sort_values("score_after", ascending=False).head(topk)
+
+    fig = plot_axis_deltas(df_axes)
+
+    return {
+        "game": "shogi",
+        "input": {"sfen": sfen, "move_usi": move_usi, "perspective": perspective},
+        "scores": {"before": score_before, "after": score_after, "delta": score_after - score_before},
+        "axes_table": df_axes,
+        "alternatives": alt_df,
+        "comment_md": comment,
+        "hds_md": hds_log,
+        "plot_fig": fig,
+        "repro": repro_snapshot(),
+    }
+
+
+# ---------------------------
+# Gradio UI
+# ---------------------------
+
+def _format_repro_md(repro: Dict[str, Any]) -> str:
+    p = repro.get("packages", {})
+    lines = []
+    lines.append("### Repro snapshot")
+    lines.append(f"- utc_now: `{repro.get('utc_now')}`")
+    lines.append(f"- python: `{repro.get('python')}`")
+    lines.append(f"- platform: `{repro.get('platform')}`")
+    lines.append("- packages:")
+    for k, v in p.items():
+        lines.append(f"  - {k}: `{v}`")
+    return "\n".join(lines)
+
+def run_shogi(sfen: str, move_usi: str, perspective: str):
+    try:
+        report = explain_shogi_move_en(sfen.strip(), move_usi.strip(), perspective=perspective)
+        return (
+            report["comment_md"],
+            report["hds_md"],
+            report["axes_table"],
+            report["alternatives"],
+            report["plot_fig"],
+            _format_repro_md(report["repro"]),
+        )
+    except Exception as e:
+        tb = traceback.format_exc(limit=2)
+        return (
+            f"**Error:** {e}\n\n```\n{tb}\n```",
+            "",
+            pd.DataFrame(),
+            pd.DataFrame(),
+            None,
+            _format_repro_md(repro_snapshot()),
+        )
+
+def run_chess(fen: str, move_uci: str, perspective: str):
+    try:
+        report = explain_chess_move_en(fen.strip(), move_uci.strip(), perspective=perspective)
+        return (
+            report["comment_md"],
+            report["hds_md"],
+            report["axes_table"],
+            report["alternatives"],
+            report["plot_fig"],
+            _format_repro_md(report["repro"]),
+        )
+    except Exception as e:
+        tb = traceback.format_exc(limit=2)
+        return (
+            f"**Error:** {e}\n\n```\n{tb}\n```",
+            "",
+            pd.DataFrame(),
+            pd.DataFrame(),
+            None,
+            _format_repro_md(repro_snapshot()),
+        )
+
+ABOUT_MD = r"""
+## Black-Box Translator (Deterministic Demo)
+
+- **No engine / no search / no learning.** Only deterministic heuristics + structured logs.
+- **Goal:** Make a 3rd party able to reproduce the same explanation from the same input.
+
+**Inputs**
+- Chess: `FEN` + `UCI move`
+- Shogi: `SFEN` + `USI move`
+
+**Output**
+- One **human-readable comment**
+- A **structured log** (HDS-style layers)
+- Axis table + top alternatives + a small chart
+
+**Important prohibition**
+- This demo must NOT be used for: emotion total-formalization, self/ego design, or any use that directly enables ranking/scoring humans.
+"""
+
+def build_ui():
+    with gr.Blocks(title="HDS Black-Box Translator (Demo)") as demo:
+        gr.Markdown(ABOUT_MD)
+
+        with gr.Tabs():
+            with gr.Tab("Shogi"):
+                with gr.Row():
+                    sfen = gr.Textbox(
+                        label="SFEN",
+                        lines=2,
+                        value="lnsgkgsnl/1r5b1/p1ppppppp/9/9/9/P1PPPPPPP/1B5R1/LNSGKGSNL b - 1",
+                    )
+                with gr.Row():
+                    move = gr.Textbox(label="USI move", value="7g7f")
+                    persp = gr.Dropdown(label="Perspective", choices=["side_to_move", "black", "white"], value="side_to_move")
+                    btn = gr.Button("Explain (Shogi)")
+                comment = gr.Markdown()
+                hds = gr.Markdown()
+                axes = gr.Dataframe(label="Axes", interactive=False)
+                alts = gr.Dataframe(label="Top alternatives", interactive=False)
+                fig = gr.Plot(label="Axis deltas")
+                repro = gr.Markdown()
+                btn.click(run_shogi, inputs=[sfen, move, persp], outputs=[comment, hds, axes, alts, fig, repro])
+
+            with gr.Tab("Chess"):
+                with gr.Row():
+                    fen = gr.Textbox(
+                        label="FEN",
+                        lines=2,
+                        value="r1bqkbnr/pppp1ppp/2n5/4p3/2B1P3/5N2/PPPP1PPP/RNBQK2R w KQkq - 2 3",
+                    )
+                with gr.Row():
+                    move = gr.Textbox(label="UCI move", value="f3g5")
+                    persp = gr.Dropdown(label="Perspective", choices=["side_to_move", "white", "black"], value="side_to_move")
+                    btn = gr.Button("Explain (Chess)")
+                comment = gr.Markdown()
+                hds = gr.Markdown()
+                axes = gr.Dataframe(label="Axes", interactive=False)
+                alts = gr.Dataframe(label="Top alternatives", interactive=False)
+                fig = gr.Plot(label="Axis deltas")
+                repro = gr.Markdown()
+                btn.click(run_chess, inputs=[fen, move, persp], outputs=[comment, hds, axes, alts, fig, repro])
+
+        with gr.Accordion("Repro snapshot (now)", open=False):
+            gr.Markdown(_format_repro_md(repro_snapshot()))
+
+    return demo
+
+
+if __name__ == "__main__":
+    ui = build_ui()
+    ui.launch()