feat: Deploy Hangman AI Demo to Hugging Face Spaces

- Create Gradio app for interactive hangman demo
- Add requirements.txt with necessary dependencies
- Include README with proper metadata for HF Spaces
- Fix short_description to meet 60 character limit

.gitignore

@@ -0,0 +1,96 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Hugging Face specific
+*.bin
+*.safetensors
+*.h5
+*.ckpt
+*.pth
+*.pt
+*.pkl
+*.pickle
+
+# Model checkpoints and data
+checkpoints/
+models/
+data/
+logs/
+runs/
+wandb/
+
+# Temporary files
+*.tmp
+*.temp
+*.log

hangman/rl/eval.py

@@ -1,178 +0,0 @@
-import os
-import time
-import csv
-from argparse import Namespace
-
-import torch
-
-from .envs import BatchEnv
-from .priors import (
-    CandCache,
-    ig_exact_pick,
-    candidate_letter_probs,
-    pos_present_probs,
-)
-
-
-@torch.no_grad()
-def greedy_rollout(win_env: BatchEnv, model, device, N=1000, priors=None, log_stride: int = 256, use_cand_priors: bool = False):
-    wins = 0
-    total = 0
-    B = min(win_env.batch, 256)
-    env = BatchEnv(win_env.buckets, win_env.tries_init, B, win_env.len_choices.copy(), win_env.max_len)
-    env.reset()
-    model.eval()
-    if hasattr(model, "remove_noise"):
-        model.remove_noise()
-    start = time.perf_counter()
-    local_cache = CandCache(1024) if use_cand_priors else None
-    while total < N:
-        pat_idx, tried, lens, tries = env.observe()
-        B_now = pat_idx.size(0)
-        lp = torch.zeros((B_now, 26), dtype=torch.float32)
-        for i, patt in enumerate(env.patterns):
-            L = min(len(patt), model.max_len if hasattr(model, "max_len") else win_env.max_len)
-            lp[i, :] = torch.tensor(priors.get(L, [0.0] * 26))
-        if use_cand_priors and local_cache is not None:
-            cp = torch.zeros((B_now, 26), dtype=torch.float32)
-            for i in range(B_now):
-                L = min(len(env.patterns[i]), win_env.max_len)
-                tried_bits = int(env.tried_mask_bits[i])
-                cp[i, :] = candidate_letter_probs(L, env.patterns[i], tried_bits, win_env.buckets, local_cache)
-        else:
-            cp = None
-        tn = (tries.float() / win_env.tries_init).unsqueeze(1)
-        out = model(
-            pat_idx.to(device),
-            tried.to(device),
-            lens.to(device),
-            lp.to(device),
-            tn.to(device),
-            cand_priors=(cp.to(device) if cp is not None else None),
-        )
-        if isinstance(out, tuple):
-            logits, _v = out
-            actions = logits.argmax(dim=1).cpu()
-        else:
-            q = out
-            actions = q.argmax(dim=1).cpu()
-        env.step(actions)
-        finished = env.done.clone()
-        if finished.any():
-            batch_wins = int(env.won.sum().item())
-            batch_finished = int(finished.sum().item())
-            wins += batch_wins
-            total += batch_finished
-            if (total % max(1, log_stride) == 0) or (total >= N):
-                wr = wins / max(1, total)
-                elapsed = (time.perf_counter() - start) / 60.0
-                print(f"[eval] episodes={total}/{N} win-rate={wr:.3f} | {elapsed:.1f} min")
-            env.force_reset_done()
-    model.train()
-    if hasattr(model, "resample_noise"):
-        model.resample_noise()
-    return wins / max(1, total)
-
-
-@torch.no_grad()
-def run_solver(args, buckets, priors, pos_priors):
-    lens = sorted(buckets.keys())
-    env = BatchEnv(buckets, args.tries, args.batch_env, lens.copy(), args.max_len)
-    env.reset()
-    total = 0
-    wins = 0
-    start = time.perf_counter()
-    csv_fp = None
-    csv_writer = None
-    if getattr(args, "csv_log", False):
-        os.makedirs(args.out_dir, exist_ok=True)
-        csv_path = os.path.join(args.out_dir, "metrics.csv")
-        new_file = not os.path.exists(csv_path)
-        csv_fp = open(csv_path, "a", newline="")
-        csv_writer = csv.writer(csv_fp)
-        if new_file:
-            csv_writer.writerow(["mode", "episodes", "wins", "win_rate", "minutes"])
-    while total < args.solver_eval_N:
-        B = env.batch
-        actions = torch.zeros(B, dtype=torch.long)
-        for i in range(B):
-            patt = env.patterns[i]
-            L = len(patt)
-            tried_bits = int(env.tried_mask_bits[i])
-            if args.solver_mode == "igx":
-                a = ig_exact_pick(tried_bits, L, patt, buckets)
-            elif args.solver_mode == "ig":
-                vec = candidate_letter_probs(L, patt, tried_bits, buckets, CandCache(1))
-                score = vec.clamp(0, 1) * (1 - vec.clamp(0, 1))
-                for j in range(26):
-                    if (tried_bits >> j) & 1:
-                        score[j] = -1.0
-                a = int(score.argmax().item())
-            elif args.solver_mode == "pos":
-                vec = pos_present_probs(L, patt, pos_priors)
-                for j in range(26):
-                    if (tried_bits >> j) & 1:
-                        vec[j] = -1.0
-                a = int(vec.argmax().item())
-            elif args.solver_mode == "len":
-                vec = torch.tensor(priors.get(L, [0.0]*26), dtype=torch.float32)
-                for j in range(26):
-                    if (tried_bits >> j) & 1:
-                        vec[j] = -1.0
-                a = int(vec.argmax().item())
-            else:  # cand
-                vec = candidate_letter_probs(L, patt, tried_bits, buckets, CandCache(1))
-                for j in range(26):
-                    if (tried_bits >> j) & 1:
-                        vec[j] = -1.0
-                a = int(vec.argmax().item())
-            actions[i] = a
-        env.step(actions)
-        finished = env.done.clone()
-        if finished.any():
-            wins += int(env.won.sum().item())
-            total += int(finished.sum().item())
-            env.force_reset_done()
-            if total % 512 == 0 or total >= args.solver_eval_N:
-                wr = wins / max(1, total)
-                elapsed = (time.perf_counter() - start) / 60.0
-                print(f"[solver {args.solver_mode}] episodes={total}/{args.solver_eval_N} win-rate={wr:.3f} | {elapsed:.1f} min")
-                if csv_writer:
-                    csv_writer.writerow([args.solver_mode, total, wins, f"{wr:.6f}", f"{elapsed:.3f}"])
-                    csv_fp.flush()
-    final_wr = wins / max(1, total)
-    print(f"[done][SOLVER:{args.solver_mode}] win-rate={final_wr:.3f} over {total} episodes")
-    if csv_fp:
-        csv_fp.close()
-    return final_wr
-
-
-def run_solver_sweep(args, buckets, priors, pos_priors):
-    modes = [m.strip() for m in str(args.sweep_modes).split(",") if m.strip()]
-    results = {m: [] for m in modes}
-    for r in range(int(args.sweep_repeats)):
-        for m in modes:
-            a = Namespace(**vars(args))
-            a.solver_mode = m
-            wr = run_solver(a, buckets, priors, pos_priors)
-            results[m].append(float(wr))
-    summary_rows = []
-    print("\n[solver sweep] summary:")
-    for m in modes:
-        vals = results[m]
-        mean_wr = sum(vals) / max(1, len(vals))
-        best_wr = max(vals) if vals else 0.0
-        print(f"  - {m:>4}: mean={mean_wr:.3f} best={best_wr:.3f} over {len(vals)} run(s)")
-        summary_rows.append((m, len(vals), mean_wr, best_wr))
-    if getattr(args, "csv_log", False):
-        os.makedirs(args.out_dir, exist_ok=True)
-        path = os.path.join(args.out_dir, "solver_sweep.csv")
-        new_file = not os.path.exists(path)
-        with open(path, "a", newline="") as fp:
-            w = csv.writer(fp)
-            if new_file:
-                w.writerow(["mode", "repeats", "mean_win_rate", "best_win_rate"])
-            for m, rpt, mean_wr, best_wr in summary_rows:
-                w.writerow([m, rpt, f"{mean_wr:.6f}", f"{best_wr:.6f}"])
-        print(f"[solver sweep] written summary to {path}")
-

hangman/rl/ppo.py

@@ -1,21 +0,0 @@
-import torch
-
-
-def compute_gae(rewards, values, dones, gamma, lam):
-    """
-    rewards, values, dones: tensors [T, B]
-    returns advantages [T, B] and returns [T, B]
-    """
-    T, B = rewards.size(0), rewards.size(1)
-    adv = torch.zeros_like(rewards)
-    lastgaelam = torch.zeros(B, device=rewards.device)
-    next_value = values[-1]
-    for t in reversed(range(T)):
-        mask = 1.0 - dones[t].float()
-        delta = rewards[t] + gamma * next_value * mask - values[t]
-        lastgaelam = delta + gamma * lam * mask * lastgaelam
-        adv[t] = lastgaelam
-        next_value = values[t]
-    returns = adv + values[:-1]
-    return adv, returns
-

hangman/rl/replay.py

@@ -1,86 +0,0 @@
-from typing import Tuple
-
-import torch
-
-from .utils import enc_pattern
-from .priors import cand_priors_batch
-
-
-class Replay:
-    def __init__(self, cap: int):
-        self.cap = cap
-        self.buf = []
-        self.pos = 0
-
-    def push(self, s, a, r, sp, done, word, won: bool):
-        item = (s, a, r, sp, done, word, won)
-        if len(self.buf) < self.cap:
-            self.buf.append(item)
-        else:
-            self.buf[self.pos] = item
-        self.pos = (self.pos + 1) % self.cap
-
-    def sample(self, n):
-        import random
-        return random.sample(self.buf, n)
-
-    def __len__(self):
-        return len(self.buf)
-
-
-class SuccessReplay(Replay):
-    pass
-
-
-def tensorize_batch(batch, device, max_len, priors_dict, buckets, cand_cache, cand_frac: float = 1.0):
-    s, a, r, sp, done, _w, _won = zip(*batch)
-    B = len(batch)
-    # s
-    pat_idx0 = torch.tensor([enc_pattern(si[0], max_len) for si in s], dtype=torch.long, device=device)
-    tried0 = torch.zeros((B, 26), dtype=torch.float32, device=device)
-    lens0 = torch.tensor([min(len(si[0]), max_len) for si in s], dtype=torch.long, device=device)
-    pri0 = torch.zeros((B, 26), dtype=torch.float32, device=device)
-    tries0 = torch.tensor([si[2] for si in s], dtype=torch.float32, device=device)  # raw count
-    for i, si in enumerate(s):
-        m = si[1]
-        for j in range(26):
-            tried0[i, j] = 1.0 if ((m >> j) & 1) else 0.0
-        L = min(len(si[0]), max_len)
-        pri0[i, :] = torch.tensor(priors_dict.get(L, [0.0] * 26), dtype=torch.float32, device=device)
-    cand0 = cand_priors_batch(s, buckets, cand_cache, max_len, device) if cand_frac >= 1.0 else None
-
-    # sp
-    pat_idx1 = torch.tensor([enc_pattern(si[0], max_len) for si in sp], dtype=torch.long, device=device)
-    tried1 = torch.zeros((B, 26), dtype=torch.float32, device=device)
-    lens1 = torch.tensor([min(len(si[0]), max_len) for si in sp], dtype=torch.long, device=device)
-    pri1 = torch.zeros((B, 26), dtype=torch.float32, device=device)
-    tries1 = torch.tensor([si[2] for si in sp], dtype=torch.float32, device=device)
-    for i, si in enumerate(sp):
-        m = si[1]
-        for j in range(26):
-            tried1[i, j] = 1.0 if ((m >> j) & 1) else 0.0
-        L = min(len(si[0]), max_len)
-        pri1[i, :] = torch.tensor(priors_dict.get(L, [0.0] * 26), dtype=torch.float32, device=device)
-    cand1 = cand_priors_batch(sp, buckets, cand_cache, max_len, device) if cand_frac >= 1.0 else None
-
-    a = torch.tensor(a, dtype=torch.long, device=device)
-    r = torch.tensor(r, dtype=torch.float32, device=device)
-    done = torch.tensor(done, dtype=torch.bool, device=device)
-    return (
-        pat_idx0,
-        tried0,
-        lens0,
-        pri0,
-        cand0,
-        tries0,
-        pat_idx1,
-        tried1,
-        lens1,
-        pri1,
-        cand1,
-        tries1,
-        a,
-        r,
-        done,
-    )
-

hangman/rl/seed_bc.py

@@ -1,144 +0,0 @@
-import random
-from typing import List
-
-import torch
-import torch.nn.functional as F
-
-try:
-    from tqdm import tqdm
-except Exception:  # pragma: no cover - fallback in limited envs
-    def tqdm(x, **k):
-        return x
-
-from .envs import BatchEnv
-from .priors import (
-    candidate_letter_probs,
-    teacher_actions_batch,
-)
-from .utils import enc_pattern, atomic_save
-
-
-def seed_expert(replay, success_replay, buckets, tries, episodes,
-                priors, pos_priors, cand_cache, teacher_mode: str, max_len: int):
-    env = BatchEnv(buckets, tries, 1, sorted(buckets.keys()), max_len)
-    env.reset()
-    pushed = 0
-    won_count = 0
-    for _ in tqdm(range(episodes), desc="[seed] heuristic"):
-        env.words[0] = random.choice(buckets[random.choice(env.len_choices)])
-        L = len(env.words[0])
-        env.patterns[0] = "_" * L
-        env.tried_mask_bits[0] = 0
-        env.tries_left[0] = tries
-        env.done[0] = False
-        env.won[0] = False
-
-        while not env.done[0]:
-            tried_bits = env.tried_mask_bits[0]
-            a = teacher_actions_batch([(env.patterns[0], tried_bits, int(env.tries_left[0].item()), L)],
-                                      buckets, teacher_mode, priors, pos_priors, cand_cache)[0]
-            s = (env.patterns[0], tried_bits, int(env.tries_left[0].item()), L)
-            r = env.step(torch.tensor([a]))[0].item()
-            sp = (env.patterns[0], int(env.tried_mask_bits[0]), int(env.tries_left[0].item()), L)
-            done = bool(env.done[0].item())
-            won = bool(env.won[0].item())
-            replay.push(s, a, float(r), sp, done, env.words[0], won)
-            if done and won:
-                success_replay.push(s, a, float(r), sp, done, env.words[0], won)
-                won_count += 1
-            pushed += 1
-        env.force_reset_done()
-    print(f"[seed] added transitions={pushed}, winning_episodes={won_count}")
-
-
-def behavior_cloning(model, replay, success_replay, priors, device, max_len, tries_init: int,
-                     steps=3000, bs=512, success_frac=0.5, lr=5e-4, wd=1e-4,
-                     bc_ckpt_path: str = "", save_every: int = 250):
-    if steps <= 0 or len(replay) == 0:
-        return
-    opt = torch.optim.AdamW(model.parameters(), lr=lr, weight_decay=wd)
-    model.train()
-    pbar = tqdm(range(steps), desc="[bc] pretrain", leave=False)
-    try:
-        for t in pbar:
-            n_succ = min(int(success_frac * bs), len(success_replay))
-            n_base = max(1, bs - n_succ)
-            base_batch = replay.sample(min(n_base, len(replay)))
-            batch = base_batch
-            if n_succ > 0:
-                batch += success_replay.sample(n_succ)
-
-            s, a, _r, _sp, _done, _w, _won = zip(*batch)
-            B = len(batch)
-            pat_idx = torch.tensor([enc_pattern(si[0], max_len) for si in s], dtype=torch.long, device=device)
-            tried = torch.zeros((B, 26), dtype=torch.float32, device=device)
-            lens = torch.tensor([min(len(si[0]), max_len) for si in s], dtype=torch.long, device=device)
-            pri = torch.zeros((B, 26), dtype=torch.float32, device=device)
-            for i, si in enumerate(s):
-                m = si[1]
-                for j in range(26):
-                    tried[i, j] = 1.0 if ((m >> j) & 1) else 0.0
-                L = min(len(si[0]), max_len)
-                pri[i, :] = torch.tensor(priors.get(L, [0.0] * 26), device=device)
-            tries_norm = torch.tensor([si[2] for si in s], dtype=torch.float32, device=device) / float(tries_init)
-            tries_norm = tries_norm.unsqueeze(1)
-            a = torch.tensor(a, dtype=torch.long, device=device)
-
-            logits = model(pat_idx, tried, lens, pri, tries_norm)
-            loss = F.cross_entropy(logits, a)
-
-            opt.zero_grad(set_to_none=True)
-            loss.backward()
-            torch.nn.utils.clip_grad_norm_(model.parameters(), 1.0)
-            opt.step()
-
-            if bc_ckpt_path and ((t + 1) % max(1, save_every) == 0):
-                atomic_save({"model": model.state_dict()}, bc_ckpt_path)
-    finally:
-        if bc_ckpt_path:
-            atomic_save({"model": model.state_dict()}, bc_ckpt_path)
-            print(f"[bc] checkpoint saved to {bc_ckpt_path}")
-
-
-def actor_bc_pretrain(ac, optimizer, buckets, tries, priors, pos_priors, cand_cache,
-                      max_len, steps: int, B: int, device, teacher_mode: str = "igx", cand_frac: float = 0.25):
-    if steps <= 0:
-        return
-    env_bc = BatchEnv(buckets, tries, B, sorted(buckets.keys()), max_len)
-    env_bc.reset()
-    pbar = tqdm(range(steps), desc="[ppo-bc] pretrain", leave=False)
-    for t in pbar:
-        pat_idx, tried, lens_t, tries_t = env_bc.observe()
-        B_now = pat_idx.size(0)
-        lp = torch.zeros((B_now, 26), dtype=torch.float32)
-        for i, patt in enumerate(env_bc.patterns):
-            L = min(len(patt), max_len)
-            lp[i, :] = torch.tensor(priors.get(L, [0.0] * 26))
-        cp = torch.zeros((B_now, 26), dtype=torch.float32)
-        if cand_frac > 0.0:
-            import random as _rnd
-            k = max(1, int(B_now * min(1.0, max(0.0, cand_frac))))
-            idxs = _rnd.sample(range(B_now), k)
-            for i in idxs:
-                L = min(len(env_bc.patterns[i]), max_len)
-                tried_bits = int(env_bc.tried_mask_bits[i])
-                cp[i, :] = candidate_letter_probs(L, env_bc.patterns[i], tried_bits, buckets, cand_cache)
-        tries_norm = (tries_t.float() / float(tries)).unsqueeze(1)
-        states_list = []
-        for i in range(B_now):
-            patt = env_bc.patterns[i]
-            tried_bits = int(env_bc.tried_mask_bits[i])
-            L_here = len(patt)
-            states_list.append((patt, tried_bits, int(tries_t[i].item()), L_here))
-        ta = teacher_actions_batch(states_list, buckets, teacher_mode, priors, pos_priors, cand_cache)
-        ta_t = torch.tensor(ta, dtype=torch.long, device=device)
-        logits, _ = ac(pat_idx.to(device), tried.to(device), lens_t.to(device),
-                       lp.to(device), tries_norm.to(device), cand_priors=cp.to(device))
-        loss = F.cross_entropy(logits, ta_t)
-        optimizer.zero_grad(set_to_none=True)
-        loss.backward()
-        torch.nn.utils.clip_grad_norm_(ac.parameters(), 1.0)
-        optimizer.step()
-        env_bc.step(ta_t.cpu())
-        env_bc.force_reset_done()
-

hangman/rl/train_bc.py

@@ -1,139 +0,0 @@
-import argparse
-import os
-import time
-
-import torch
-
-from .models import DuelingQNet
-from .replay import Replay, SuccessReplay
-from .seed_bc import seed_expert, behavior_cloning
-from .eval import greedy_rollout
-from .priors import build_length_priors, build_positional_priors, CandCache
-from .utils import load_dict, by_len, set_seed
-
-
-def parse_args():
-    p = argparse.ArgumentParser("Behavior Cloning pretraining for Hangman")
-    # data
-    p.add_argument("--dict_path", type=str, default="data/words_250000_train.txt", help="Path to word list")
-    p.add_argument("--len_lo", type=int, default=4, help="Min word length")
-    p.add_argument("--len_hi", type=int, default=12, help="Max word length")
-    p.add_argument("--max_len", type=int, default=35, help="Model max sequence length")
-    p.add_argument("--tries", type=int, default=6, help="Initial tries for env")
-    # seeding and BC
-    p.add_argument("--seed_episodes", type=int, default=5000, help="How many heuristic episodes to seed replay")
-    p.add_argument("--teacher_mode", type=str, default="igx", choices=["igx", "ig", "cand", "pos", "len"], help="Heuristic teacher policy")
-    p.add_argument("--replay_cap", type=int, default=200_000, help="Replay buffer capacity")
-    p.add_argument("--success_cap", type=int, default=50_000, help="Success replay capacity")
-    p.add_argument("--bc_steps", type=int, default=5000, help="Behavior cloning optimization steps")
-    p.add_argument("--bc_bs", type=int, default=512, help="Behavior cloning batch size")
-    p.add_argument("--bc_lr", type=float, default=5e-4, help="Learning rate for BC")
-    p.add_argument("--bc_wd", type=float, default=1e-4, help="Weight decay for BC")
-    p.add_argument("--success_frac", type=float, default=0.5, help="Fraction of success samples in BC batches")
-    p.add_argument("--save_every", type=int, default=500, help="Checkpoint frequency (steps)")
-    p.add_argument("--out_dir", type=str, default="runs/bc", help="Output directory for checkpoints and logs")
-    # model
-    p.add_argument("--d_model", type=int, default=128)
-    p.add_argument("--nhead", type=int, default=4)
-    p.add_argument("--nlayers", type=int, default=2)
-    p.add_argument("--ff_mult", type=int, default=4)
-    p.add_argument("--dropout", type=float, default=0.1)
-    p.add_argument("--noisy", action="store_true", help="Use NoisyNet layers in dueling head")
-    p.add_argument("--device", type=str, default="cuda" if torch.cuda.is_available() else "cpu")
-    # eval
-    p.add_argument("--eval_N", type=int, default=2000, help="Episodes for quick greedy eval")
-    p.add_argument("--eval_stride", type=int, default=256, help="Logging stride for eval")
-    p.add_argument("--eval_use_cand_priors", action="store_true", help="Fuse candidate priors during eval")
-    # misc
-    p.add_argument("--seed", type=int, default=42)
-    return p.parse_args()
-
-
-def main():
-    args = parse_args()
-    set_seed(int(args.seed))
-
-    assert os.path.exists(args.dict_path), f"Dictionary file not found: {args.dict_path}"
-    words = load_dict(args.dict_path)
-    buckets = by_len(words, args.len_lo, args.len_hi)
-    priors = build_length_priors(buckets)
-    pos_priors = build_positional_priors(buckets, args.max_len)
-    cand_cache = CandCache(100_000)
-
-    device = torch.device(args.device)
-
-    # replay buffers
-    replay = Replay(cap=int(args.replay_cap))
-    success_replay = SuccessReplay(cap=int(args.success_cap))
-
-    # expert seeding
-    print(f"[setup] Seeding replay with heuristic='{args.teacher_mode}', episodes={args.seed_episodes}…")
-    seed_expert(
-        replay,
-        success_replay,
-        buckets,
-        tries=int(args.tries),
-        episodes=int(args.seed_episodes),
-        priors=priors,
-        pos_priors=pos_priors,
-        cand_cache=cand_cache,
-        teacher_mode=str(args.teacher_mode),
-        max_len=int(args.max_len),
-    )
-
-    # model
-    model = DuelingQNet(
-        d_model=int(args.d_model),
-        nhead=int(args.nhead),
-        nlayers=int(args.nlayers),
-        ff_mult=int(args.ff_mult),
-        max_len=int(args.max_len),
-        dropout=float(args.dropout),
-        use_noisy=bool(args.noisy),
-    ).to(device)
-
-    os.makedirs(args.out_dir, exist_ok=True)
-    ckpt_path = os.path.join(args.out_dir, "bc_dueling_qnet.pt")
-
-    # behavior cloning
-    print(f"[train] Starting BC: steps={args.bc_steps}, bs={args.bc_bs}, success_frac={args.success_frac}")
-    t0 = time.perf_counter()
-    behavior_cloning(
-        model,
-        replay,
-        success_replay,
-        priors,
-        device,
-        max_len=int(args.max_len),
-        tries_init=int(args.tries),
-        steps=int(args.bc_steps),
-        bs=int(args.bc_bs),
-        success_frac=float(args.success_frac),
-        lr=float(args.bc_lr),
-        wd=float(args.bc_wd),
-        bc_ckpt_path=ckpt_path,
-        save_every=int(args.save_every),
-    )
-    dt_min = (time.perf_counter() - t0) / 60.0
-    print(f"[train] BC finished in {dt_min:.2f} min. Checkpoint saved to {ckpt_path}")
-
-    # quick greedy rollout eval
-    print("[eval] Running greedy rollout eval…")
-    from .envs import BatchEnv
-    env = BatchEnv(buckets, int(args.tries), batch=64, len_choices=sorted(buckets.keys()), max_len=int(args.max_len))
-    env.reset()
-    wr = greedy_rollout(
-        env,
-        model,
-        device=device,
-        N=int(args.eval_N),
-        priors=priors,
-        log_stride=int(args.eval_stride),
-        use_cand_priors=bool(args.eval_use_cand_priors),
-    )
-    print(f"[done] Greedy eval win-rate={wr:.3f} over N={args.eval_N}")
-
-
-if __name__ == "__main__":
-    main()
-

hangman/utils.py

@@ -1,129 +0,0 @@
-import re
-import random
-import string
-import pandas as pd
-import torch
-
-RNG = random.Random(0)  # reproducible sampling
-
-def get_char_mapping():
-    # include PAD=0, a..z=1..26, _=27
-    return {'PAD': 0, **{c: i+1 for i, c in enumerate(string.ascii_lowercase)}, '_': 27}
-
-def read_data():
-    with open("words_250000_train.txt", "r") as f:
-        words = [w.strip().lower() for w in f if w.strip()]
-    # keep pure alphabetic words only
-    words = [w for w in words if re.fullmatch(r"[a-z]+", w)]
-    return words
-
-def create_intermediate_data(words):
-    x = pd.DataFrame({0: words})
-    x[1] = x[0].str.len()
-    x['vowels_present'] = x[0].apply(lambda p: set(p) & {'a','e','i','o','u'})
-    x['vowels_count'] = x['vowels_present'].str.len()
-    x['unique_char_count'] = x[0].apply(lambda p: len(set(p)))
-    # filter: length>3, ≥3 unique chars, has a vowel
-    x_ = x[~((x['unique_char_count'].isin([0,1,2])) | (x[1] <= 3)) & (x['vowels_count'] != 0)]
-    return x_
-
-def loop_for_permutation(unique_letters, word, all_perm, k):
-    # choose k+1 letters to hide
-    letters_to_hide = RNG.sample(unique_letters, k+1)
-    masked = word
-    for L in letters_to_hide:
-        masked = masked.replace(L, "_")
-    all_perm.append(masked)
-
-def permute_all(word, vowel_permutation_loop=False):
-    # random subset sampling of letters to hide; keep at least 1 char shown
-    uniq = list(set(word))
-    all_perm = []
-    hi = (len(uniq)-1) if vowel_permutation_loop else (len(uniq)-2)
-    for k in range(max(0, hi)):
-        loop_for_permutation(uniq, word, all_perm, k)
-    return list(set(all_perm))
-
-def permute_consonents(word):
-    # keep some vowels only; hide all consonants
-    vowel_positions = [i for i,ch in enumerate(word) if ch in "aeiou"]
-    vowels = "".join(word[i] for i in vowel_positions)     # only the vowels
-    perm_vowel_only = permute_all(vowels, vowel_permutation_loop=True)
-    out = []
-    for pv in perm_vowel_only:
-        a = ["_"] * len(word)
-        for j, ch in enumerate(pv):
-            a[vowel_positions[j]] = ch
-        out.append("".join(a))
-    return out
-
-def create_masked_dictionary(df_aug):
-    masked_dictionary = {}
-    for i, word in df_aug[0].items():
-        pats = permute_all(word) + permute_consonents(word)
-        masked_dictionary[word] = list(set(pats))
-        if i % 10000 == 0:
-            print(f"Iteration {i} completed")
-    return masked_dictionary
-
-def get_vowel_prob(df_vowel, vowel):
-    if len(df_vowel)==0: return 0.0
-    return df_vowel[0].str.contains(vowel).mean()
-
-def get_vowel_prior(df_aug):
-    prior = {}
-    max_len = int(df_aug[1].max())
-    for L in range(1, max_len+1):
-        df_v = df_aug[df_aug[1] == L]
-        probs = [get_vowel_prob(df_v, v) for v in "aeiou"]
-        prior[L] = pd.DataFrame({"vowel": list("aeiou"), "p": probs}).sort_values("p", ascending=False)
-    return prior
-
-def save_vowel_prior(vowel_prior, path="prior_probabilities.pkl"):
-    import pickle
-    with open(path, "wb") as f:
-        pickle.dump(vowel_prior, f)
-
-# ---------- ENCODING (align target to Hangman) ----------
-
-CMAP = get_char_mapping()
-
-def idx(c):  # a..z
-    return CMAP[c]-1
-
-def encode_input(pattern, max_len=35):
-    vec = [0]*max_len
-    start = max_len - len(pattern)
-    for i,ch in enumerate(pattern):
-        vec[start+i] = CMAP[ch]  # 0 is PAD, '_'=27, letters 1..26
-    return vec
-
-def encode_output_for_pattern(word, pattern):
-    """Label only letters that are STILL HIDDEN by this pattern."""
-    y = [0]*26
-    for i,ch in enumerate(word):
-        if pattern[i] == '_':
-            y[idx(ch)] = 1
-    return y
-
-def encode_words(masked_dictionary):
-    X, Y = [], []
-    for word, patterns in masked_dictionary.items():
-        for pat in patterns:
-            X.append(encode_input(pat))
-            Y.append(encode_output_for_pattern(word, pat))
-    return X, Y
-
-def convert_to_tensor(X, Y):
-    X = torch.tensor(X, dtype=torch.long)
-    Y = torch.tensor(Y, dtype=torch.float32)  # for BCEWithLogitsLoss
-    return X, Y
-
-def get_datasets():
-    words = read_data()
-    df_aug = create_intermediate_data(words)
-    masked_dictionary = create_masked_dictionary(df_aug)
-    vowel_prior = get_vowel_prior(df_aug)
-    save_vowel_prior(vowel_prior)
-    X, Y = encode_words(masked_dictionary)
-    return convert_to_tensor(X, Y)