Capture decisions: LLM Explorer tool, HF Spaces deployment

- Built tools/llm-explorer/ Gradio app (3 tabs + admin panel)
- Deployed to HuggingFace Spaces (chyams/llm-explorer) with T4 GPU
- Separate tools venv at ~/venvs/responsible-ai-course-tools
- Admin-swappable model list, seed accordion UX, slider debounce
- Session notes added to 2026-spring/CLAUDE.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+*.pyc
+.env

README.md

@@ -0,0 +1,45 @@
+---
+title: LLM Explorer
+emoji: 🔬
+colorFrom: blue
+colorTo: indigo
+sdk: gradio
+sdk_version: 6.5.1
+app_file: app.py
+pinned: false
+license: mit
+short_description: Interactive tools for next-token prediction, text generation
+suggested_hardware: t4-small
+---
+
+# LLM Explorer
+
+Interactive tools for understanding how Large Language Models work. Built for the *Responsible AI: Technology, Power, and Justice* course at Huston-Tillotson University.
+
+## Tools
+
+1. **Probability Explorer** — Enter a prompt, watch the model predict one token at a time with full probability distributions
+2. **Generator** — Generate text with adjustable temperature and top-k sampling
+3. **Tokenizer** — See how text is split into tokens
+
+## Deployment
+
+This app is designed to run on a HuggingFace Space with a dedicated T4 GPU.
+
+### Setup
+
+1. Create a new Space at huggingface.co/new-space
+2. Select Gradio SDK
+3. Push the contents of this directory to the Space repo
+4. In Space Settings, select T4 GPU hardware
+5. Set `ADMIN_PASSWORD` as a Space Secret
+
+### Local Development
+
+```bash
+cd tools/llm-explorer
+pip install -r requirements.txt
+python app.py
+```
+
+Opens at http://localhost:7860

app.py

@@ -0,0 +1,487 @@
+"""LLM Explorer — Interactive tools for understanding how LLMs work.
+
+Gradio app with three tabs:
+  1. Step-by-Step Probability Explorer
+  2. Interactive Generator
+  3. Tokenizer
+
+Plus a password-protected Admin panel for runtime configuration.
+"""
+
+import os
+
+import gradio as gr
+
+from models import AVAILABLE_MODELS, manager
+
+# ---------------------------------------------------------------------------
+# Admin password — set via env var on HF Spaces, or fall back to config/default
+# ---------------------------------------------------------------------------
+ADMIN_PASSWORD = os.environ.get("ADMIN_PASSWORD", "admin")
+
+# ---------------------------------------------------------------------------
+# HTML rendering helpers
+# ---------------------------------------------------------------------------
+
+# Alternating token chip colors
+TOKEN_COLORS = [
+    ("#e0f2fe", "#0c4a6e"),  # light blue / dark blue
+    ("#fef3c7", "#92400e"),  # light amber / dark amber
+    ("#d1fae5", "#065f46"),  # light green / dark green
+    ("#fce7f3", "#9d174d"),  # light pink / dark pink
+    ("#e0e7ff", "#3730a3"),  # light indigo / dark indigo
+    ("#fde68a", "#78350f"),  # yellow / brown
+]
+
+
+def _render_step_html(step_data: dict, prompt: str) -> str:
+    """Render one generation step as styled HTML."""
+    s = step_data
+    generated = s["text"][len(prompt):]
+
+    # Build probability bar chart
+    rows_html = ""
+    for token_str, prob, tid in s["top_tokens"]:
+        bar_width = max(1, int(prob * 300))
+        is_selected = tid == s["token_id"]
+        bg = "#2563eb" if is_selected else "#94a3b8"
+        label_style = "font-weight:700;" if is_selected else ""
+        arrow = " \u2190" if is_selected else ""
+        token_display = repr(token_str)
+        rows_html += f"""
+        <div style="display:flex;align-items:center;gap:8px;margin:2px 0;font-family:monospace;font-size:13px;">
+          <span style="width:140px;text-align:right;color:#1e293b;{label_style}">{token_display}</span>
+          <div style="width:{bar_width}px;height:16px;background:{bg};border-radius:3px;"></div>
+          <span style="color:#334155;{label_style}">{prob:.4f}{arrow}</span>
+        </div>"""
+
+    return f"""
+    <div style="border:1px solid #e2e8f0;border-radius:8px;padding:12px;margin:8px 0;background:#fff;">
+      <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:8px;">
+        <span style="font-weight:600;color:#1e293b;">Step {s['step']}</span>
+        <span style="color:#64748b;font-size:12px;">Entropy: {s['entropy']:.2f} bits</span>
+      </div>
+      <div style="font-family:monospace;font-size:14px;padding:8px;background:#f8fafc;border-radius:4px;margin-bottom:8px;word-wrap:break-word;">
+        <span style="color:#64748b;">{prompt}</span><span style="color:#1e293b;font-weight:600;">{generated}</span>
+      </div>
+      {rows_html}
+    </div>"""
+
+
+def _render_final_text_html(prompt: str, generated_text: str) -> str:
+    """Render just the final generated text."""
+    generated = generated_text[len(prompt):]
+    return f"""
+    <div style="border:1px solid #e2e8f0;border-radius:8px;padding:16px;background:#fff;">
+      <div style="font-family:monospace;font-size:16px;line-height:1.6;word-wrap:break-word;">
+        <span style="color:#94a3b8;">{prompt}</span><span style="color:#1e293b;font-weight:600;">{generated}</span>
+      </div>
+    </div>"""
+
+
+def _render_tokens_html(tokens: list[tuple[str, int]]) -> str:
+    """Render tokenized text as colored chips."""
+    chips = ""
+    for i, (token_str, tid) in enumerate(tokens):
+        bg, fg = TOKEN_COLORS[i % len(TOKEN_COLORS)]
+        # Escape HTML
+        display = token_str.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        # Show spaces explicitly
+        if display.strip() == "":
+            display = repr(token_str).strip("'")
+        chips += f"""<span title="ID: {tid}" style="
+            display:inline-block;
+            padding:4px 8px;
+            margin:2px;
+            border-radius:4px;
+            background:{bg};
+            color:{fg};
+            font-family:monospace;
+            font-size:14px;
+            cursor:default;
+        ">{display}</span>"""
+
+    return f"""
+    <div style="padding:8px;">
+      <div style="margin-bottom:12px;color:#64748b;font-size:13px;">
+        {len(tokens)} tokens &mdash; hover for token IDs
+      </div>
+      <div style="line-height:2.2;">{chips}</div>
+    </div>"""
+
+
+# ---------------------------------------------------------------------------
+# Tab 1: Step-by-Step Probability Explorer
+# ---------------------------------------------------------------------------
+
+def explore_probabilities(prompt, temperature, top_n, steps, show_steps, seed):
+    """Generate tokens step by step and return formatted HTML."""
+    if not manager.is_ready():
+        return f"<p style='color:red;'>{manager.status_message()}</p>"
+
+    seed = int(seed)
+    results = manager.generate_step_by_step(
+        prompt=prompt,
+        steps=int(steps),
+        temperature=temperature,
+        top_n=int(top_n),
+        seed=seed,
+        show_steps=show_steps,
+    )
+
+    if not results:
+        return "<p>No results generated.</p>"
+
+    if show_steps:
+        html_parts = [_render_step_html(r, prompt) for r in results]
+        return "\n".join(html_parts)
+    else:
+        final_text = results[-1]["text"]
+        return _render_final_text_html(prompt, final_text)
+
+
+def on_show_steps_change(show_steps):
+    """Adjust max steps slider when show_steps toggles."""
+    new_max = 20 if show_steps else 100
+    return gr.update(maximum=new_max)
+
+
+# ---------------------------------------------------------------------------
+# Tab 2: Interactive Generator
+# ---------------------------------------------------------------------------
+
+def generate_interactive(prompt, num_tokens, temperature, top_k, seed):
+    """Generate text and return it."""
+    if not manager.is_ready():
+        return f"*{manager.status_message()}*"
+
+    seed = int(seed)
+    text = manager.generate_text(
+        prompt=prompt,
+        num_tokens=int(num_tokens),
+        temperature=temperature,
+        top_k=int(top_k),
+        seed=seed,
+    )
+    return text
+
+
+# ---------------------------------------------------------------------------
+# Tab 3: Tokenizer
+# ---------------------------------------------------------------------------
+
+def tokenize_text(text):
+    """Tokenize input and return formatted HTML."""
+    if not manager.is_ready():
+        return f"<p style='color:red;'>{manager.status_message()}</p>"
+
+    tokens = manager.tokenize(text)
+    return _render_tokens_html(tokens)
+
+
+# ---------------------------------------------------------------------------
+# Admin panel
+# ---------------------------------------------------------------------------
+
+def admin_login(password):
+    """Check admin password and return visibility update."""
+    if password == ADMIN_PASSWORD:
+        return gr.update(visible=True), gr.update(visible=False), ""
+    return gr.update(visible=False), gr.update(visible=True), "Incorrect password."
+
+
+def admin_load_model(model_name):
+    """Load a new model from admin panel."""
+    status = manager.load_model(model_name)
+    cfg = manager.get_config()
+    return status, json.dumps(cfg, indent=2)
+
+
+def admin_save_defaults(prompt, temperature, top_n, steps, seed):
+    """Save default settings."""
+    manager.update_config(
+        default_prompt=prompt,
+        default_temperature=temperature,
+        default_top_n=int(top_n),
+        default_steps=int(steps),
+        default_seed=int(seed),
+    )
+    return "Defaults saved."
+
+
+import json
+
+
+# ---------------------------------------------------------------------------
+# Build the Gradio app
+# ---------------------------------------------------------------------------
+
+def create_app():
+    cfg = manager.get_config()
+
+    with gr.Blocks(
+        title="LLM Explorer",
+        theme=gr.themes.Soft(),
+    ) as demo:
+        gr.Markdown("# LLM Explorer\n*Interactive tools for understanding how LLMs work*")
+
+        # Status bar
+        status_display = gr.Markdown(value=f"**{manager.status_message()}**")
+
+        # ==================================================================
+        # Tab 1: Probability Explorer
+        # ==================================================================
+        with gr.Tab("Probability Explorer"):
+            gr.Markdown("### Step-by-Step Next-Token Prediction")
+            gr.Markdown(
+                "Enter a prompt and watch the model predict one token at a time. "
+                "Each step shows the probability distribution over the vocabulary."
+            )
+
+            with gr.Row():
+                with gr.Column(scale=3):
+                    t1_prompt = gr.Textbox(
+                        label="Prompt",
+                        value=cfg.get("default_prompt", "The best thing about Huston-Tillotson University is"),
+                        lines=2,
+                    )
+                with gr.Column(scale=1):
+                    t1_show_steps = gr.Checkbox(
+                        label="Show steps",
+                        value=True,
+                    )
+
+            with gr.Row():
+                t1_temperature = gr.Slider(
+                    label="Temperature",
+                    minimum=0.1, maximum=2.5, step=0.1,
+                    value=cfg.get("default_temperature", 0.8),
+                )
+                t1_top_n = gr.Slider(
+                    label="Top-N tokens",
+                    minimum=5, maximum=30, step=1,
+                    value=cfg.get("default_top_n", 10),
+                )
+                t1_steps = gr.Slider(
+                    label="Steps",
+                    minimum=1, maximum=20, step=1,
+                    value=cfg.get("default_steps", 8),
+                )
+
+            with gr.Accordion(f"Seed: {cfg.get('default_seed', 42)}", open=False):
+                t1_seed = gr.Number(
+                    label="Random seed",
+                    value=cfg.get("default_seed", 42),
+                    precision=0,
+                )
+
+            t1_generate_btn = gr.Button("Generate", variant="primary")
+            t1_output = gr.HTML(label="Output")
+
+            # Show steps toggle adjusts max steps
+            t1_show_steps.change(
+                fn=on_show_steps_change,
+                inputs=[t1_show_steps],
+                outputs=[t1_steps],
+            )
+
+            t1_generate_btn.click(
+                fn=explore_probabilities,
+                inputs=[t1_prompt, t1_temperature, t1_top_n, t1_steps, t1_show_steps, t1_seed],
+                outputs=[t1_output],
+            )
+
+        # ==================================================================
+        # Tab 2: Interactive Generator
+        # ==================================================================
+        with gr.Tab("Generator"):
+            gr.Markdown("### Interactive Text Generator")
+            gr.Markdown(
+                "Generate text from a prompt. Adjust temperature and top-k, "
+                "then release the slider to regenerate with the same seed."
+            )
+
+            t2_prompt = gr.Textbox(
+                label="Prompt",
+                value=cfg.get("default_prompt", "The best thing about Huston-Tillotson University is"),
+                lines=2,
+            )
+
+            with gr.Row():
+                t2_num_tokens = gr.Slider(
+                    label="Tokens to generate",
+                    minimum=5, maximum=100, step=1,
+                    value=30,
+                )
+                t2_temperature = gr.Slider(
+                    label="Temperature",
+                    minimum=0.1, maximum=2.5, step=0.1,
+                    value=cfg.get("default_temperature", 0.8),
+                )
+                t2_top_k = gr.Slider(
+                    label="Top-K",
+                    minimum=1, maximum=100, step=1,
+                    value=40,
+                )
+
+            with gr.Accordion(f"Seed: {cfg.get('default_seed', 42)}", open=False):
+                t2_seed = gr.Number(
+                    label="Random seed",
+                    value=cfg.get("default_seed", 42),
+                    precision=0,
+                )
+
+            t2_generate_btn = gr.Button("Generate", variant="primary")
+            t2_output = gr.Textbox(
+                label="Generated text",
+                lines=8,
+                interactive=False,
+            )
+
+            gen_inputs = [t2_prompt, t2_num_tokens, t2_temperature, t2_top_k, t2_seed]
+
+            t2_generate_btn.click(
+                fn=generate_interactive,
+                inputs=gen_inputs,
+                outputs=[t2_output],
+            )
+
+            # Slider release events trigger regeneration
+            t2_temperature.release(
+                fn=generate_interactive,
+                inputs=gen_inputs,
+                outputs=[t2_output],
+            )
+            t2_top_k.release(
+                fn=generate_interactive,
+                inputs=gen_inputs,
+                outputs=[t2_output],
+            )
+
+        # ==================================================================
+        # Tab 3: Tokenizer
+        # ==================================================================
+        with gr.Tab("Tokenizer"):
+            gr.Markdown("### Token Visualization")
+            gr.Markdown(
+                "Enter any text to see how the model's tokenizer splits it into tokens. "
+                "Hover over each token to see its numeric ID."
+            )
+
+            t3_input = gr.Textbox(
+                label="Text",
+                value="Huston-Tillotson University is an HBCU in Austin, Texas",
+                lines=3,
+            )
+            t3_btn = gr.Button("Tokenize", variant="primary")
+            t3_output = gr.HTML(label="Tokens")
+
+            t3_btn.click(
+                fn=tokenize_text,
+                inputs=[t3_input],
+                outputs=[t3_output],
+            )
+
+        # ==================================================================
+        # Admin Panel
+        # ==================================================================
+        with gr.Tab("Admin"):
+            gr.Markdown("### Admin Panel")
+
+            # Login gate
+            with gr.Group() as admin_login_group:
+                admin_pw = gr.Textbox(
+                    label="Password",
+                    type="password",
+                    placeholder="Enter admin password",
+                )
+                admin_login_btn = gr.Button("Login")
+                admin_login_msg = gr.Markdown("")
+
+            # Admin controls (hidden until login)
+            with gr.Group(visible=False) as admin_controls:
+                gr.Markdown("#### Model")
+                with gr.Row():
+                    admin_model_dropdown = gr.Dropdown(
+                        choices=list(AVAILABLE_MODELS.keys()),
+                        value=manager.current_model_name or cfg.get("model", "Qwen2.5-3B"),
+                        label="Select model",
+                    )
+                    admin_load_btn = gr.Button("Load Model", variant="primary")
+                admin_model_status = gr.Markdown("")
+
+                gr.Markdown("---")
+                gr.Markdown("#### Default Settings")
+                admin_prompt = gr.Textbox(
+                    label="Default prompt",
+                    value=cfg.get("default_prompt", ""),
+                )
+                with gr.Row():
+                    admin_temp = gr.Number(
+                        label="Default temperature",
+                        value=cfg.get("default_temperature", 0.8),
+                    )
+                    admin_top_n = gr.Number(
+                        label="Default top-n",
+                        value=cfg.get("default_top_n", 10),
+                        precision=0,
+                    )
+                    admin_steps = gr.Number(
+                        label="Default steps",
+                        value=cfg.get("default_steps", 8),
+                        precision=0,
+                    )
+                    admin_seed = gr.Number(
+                        label="Default seed",
+                        value=cfg.get("default_seed", 42),
+                        precision=0,
+                    )
+                admin_save_btn = gr.Button("Save Defaults")
+                admin_save_msg = gr.Markdown("")
+
+                gr.Markdown("---")
+                gr.Markdown("#### Current Config")
+                admin_config_display = gr.Code(
+                    value=json.dumps(cfg, indent=2),
+                    language="json",
+                    interactive=False,
+                )
+
+            # Login wiring
+            admin_login_btn.click(
+                fn=admin_login,
+                inputs=[admin_pw],
+                outputs=[admin_controls, admin_login_group, admin_login_msg],
+            )
+
+            # Model loading
+            admin_load_btn.click(
+                fn=admin_load_model,
+                inputs=[admin_model_dropdown],
+                outputs=[admin_model_status, admin_config_display],
+            )
+
+            # Save defaults
+            admin_save_btn.click(
+                fn=admin_save_defaults,
+                inputs=[admin_prompt, admin_temp, admin_top_n, admin_steps, admin_seed],
+                outputs=[admin_save_msg],
+            )
+
+    return demo
+
+
+# ---------------------------------------------------------------------------
+# Startup
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    # Load default model on startup
+    cfg = manager.get_config()
+    model_to_load = cfg.get("model", "Qwen2.5-3B")
+    print(f"Loading default model: {model_to_load}")
+    status = manager.load_model(model_to_load)
+    print(status)
+
+    app = create_app()
+    app.launch(server_name="0.0.0.0", server_port=7860)

config.json

@@ -0,0 +1,8 @@
+{
+  "model": "GPT-OSS-20B",
+  "default_prompt": "The best thing about Huston-Tillotson University is",
+  "default_temperature": 0.8,
+  "default_top_n": 10,
+  "default_steps": 8,
+  "default_seed": 42
+}

models.py

@@ -0,0 +1,343 @@
+"""Model management for LLM Explorer.
+
+Handles loading, unloading, and swapping models at runtime.
+Provides inference methods for next-token probabilities and step-by-step generation.
+"""
+
+import gc
+import json
+import math
+import os
+import threading
+from pathlib import Path
+
+import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+# ---------------------------------------------------------------------------
+# Available models — add entries here to make them selectable in admin panel.
+# To use a new model, just add it here and redeploy (or restart).
+# ---------------------------------------------------------------------------
+AVAILABLE_MODELS = {
+    "Qwen2.5-3B": {
+        "id": "Qwen/Qwen2.5-3B",
+        "dtype": "float16",
+        "description": "Fast, good quality (default)",
+    },
+    "Qwen2.5-7B (4-bit)": {
+        "id": "Qwen/Qwen2.5-7B",
+        "quantize": "4bit",
+        "description": "Higher quality, quantized to fit T4",
+    },
+    "Llama-3.2-3B": {
+        "id": "meta-llama/Llama-3.2-3B",
+        "dtype": "float16",
+        "description": "Meta's latest 3B",
+    },
+    "Mistral-7B-v0.3 (4-bit)": {
+        "id": "mistralai/Mistral-7B-v0.3",
+        "quantize": "4bit",
+        "description": "Best quality, quantized",
+    },
+    "GPT-OSS-20B": {
+        "id": "openai/gpt-oss-20b",
+        "dtype": "auto",
+        "description": "OpenAI 20B, full precision (local/large GPU only)",
+    },
+    "GPT-OSS-20B (4-bit)": {
+        "id": "openai/gpt-oss-20b",
+        "quantize": "4bit",
+        "description": "OpenAI 20B, quantized to fit T4 (~10-12GB)",
+    },
+}
+
+DEFAULT_MODEL = "Qwen2.5-3B"
+
+CONFIG_PATH = Path(__file__).parent / "config.json"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _detect_device() -> str:
+    """Pick the best available device."""
+    if torch.cuda.is_available():
+        return "cuda"
+    if hasattr(torch.backends, "mps") and torch.backends.mps.is_available():
+        return "mps"
+    return "cpu"
+
+
+def _load_config() -> dict:
+    """Load persisted config or return defaults."""
+    defaults = {
+        "model": DEFAULT_MODEL,
+        "default_prompt": "The best thing about Huston-Tillotson University is",
+        "default_temperature": 0.8,
+        "default_top_n": 10,
+        "default_steps": 8,
+        "default_seed": 42,
+    }
+    if CONFIG_PATH.exists():
+        try:
+            with open(CONFIG_PATH) as f:
+                saved = json.load(f)
+            defaults.update(saved)
+        except (json.JSONDecodeError, OSError):
+            pass
+    return defaults
+
+
+def _save_config(cfg: dict) -> None:
+    """Persist config to disk."""
+    with open(CONFIG_PATH, "w") as f:
+        json.dump(cfg, f, indent=2)
+
+
+# ---------------------------------------------------------------------------
+# ModelManager — singleton that owns the active model
+# ---------------------------------------------------------------------------
+
+class ModelManager:
+    """Manages a single active model with hot-swap capability."""
+
+    def __init__(self):
+        self.model = None
+        self.tokenizer = None
+        self.current_model_name: str | None = None
+        self.device: str = _detect_device()
+        self.loading = False
+        self._lock = threading.Lock()
+        self.config = _load_config()
+
+    # ------------------------------------------------------------------
+    # Model lifecycle
+    # ------------------------------------------------------------------
+
+    def load_model(self, model_name: str) -> str:
+        """Load a model by its display name. Returns status message."""
+        if model_name not in AVAILABLE_MODELS:
+            return f"Unknown model: {model_name}"
+
+        if self.loading:
+            return "A model is already being loaded. Please wait."
+
+        spec = AVAILABLE_MODELS[model_name]
+
+        with self._lock:
+            self.loading = True
+            try:
+                # Unload current model
+                self._unload()
+
+                # Determine load kwargs
+                model_id = spec["id"]
+                load_kwargs: dict = {"device_map": "auto"}
+
+                if spec.get("quantize") == "4bit":
+                    from transformers import BitsAndBytesConfig
+                    load_kwargs["quantization_config"] = BitsAndBytesConfig(
+                        load_in_4bit=True,
+                        bnb_4bit_compute_dtype=torch.float16,
+                    )
+                elif spec.get("quantize") == "8bit":
+                    from transformers import BitsAndBytesConfig
+                    load_kwargs["quantization_config"] = BitsAndBytesConfig(
+                        load_in_8bit=True,
+                    )
+                else:
+                    dtype_str = spec.get("dtype", "float16")
+                    if dtype_str == "auto":
+                        load_kwargs["torch_dtype"] = "auto"
+                    else:
+                        load_kwargs["torch_dtype"] = getattr(torch, dtype_str)
+
+                # Load tokenizer + model
+                self.tokenizer = AutoTokenizer.from_pretrained(model_id)
+                self.model = AutoModelForCausalLM.from_pretrained(
+                    model_id, **load_kwargs
+                )
+                self.model.eval()
+                self.current_model_name = model_name
+
+                # Persist choice
+                self.config["model"] = model_name
+                _save_config(self.config)
+
+                return f"Loaded {model_name} ({model_id})"
+
+            except Exception as e:
+                self._unload()
+                return f"Failed to load {model_name}: {e}"
+            finally:
+                self.loading = False
+
+    def _unload(self) -> None:
+        """Release current model and free memory."""
+        if self.model is not None:
+            del self.model
+            self.model = None
+        if self.tokenizer is not None:
+            del self.tokenizer
+            self.tokenizer = None
+        self.current_model_name = None
+        gc.collect()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+
+    def is_ready(self) -> bool:
+        return self.model is not None and not self.loading
+
+    def status_message(self) -> str:
+        if self.loading:
+            return "Loading model..."
+        if self.model is None:
+            return "No model loaded"
+        return f"Model: {self.current_model_name}"
+
+    # ------------------------------------------------------------------
+    # Inference helpers
+    # ------------------------------------------------------------------
+
+    def _get_logits(self, text: str) -> torch.Tensor:
+        """Run a forward pass and return logits for the last token position."""
+        inputs = self.tokenizer(text, return_tensors="pt")
+        inputs = {k: v.to(self.model.device) for k, v in inputs.items()}
+        with torch.no_grad():
+            out = self.model(**inputs)
+        return out.logits[0, -1, :]  # (vocab_size,)
+
+    @staticmethod
+    def apply_temperature(logits: torch.Tensor, temperature: float) -> torch.Tensor:
+        """Apply temperature scaling to logits and return probabilities."""
+        if temperature <= 0:
+            temperature = 1e-6
+        scaled = logits / temperature
+        return torch.softmax(scaled, dim=-1)
+
+    @staticmethod
+    def entropy_bits(probs: torch.Tensor) -> float:
+        """Shannon entropy in bits."""
+        eps = 1e-20
+        p = probs + eps
+        return float(-torch.sum(p * torch.log2(p)))
+
+    def top_k_table(
+        self, probs: torch.Tensor, k: int = 10
+    ) -> list[tuple[str, float, int]]:
+        """Return list of (token_str, probability, token_id) for top-k tokens."""
+        topk = torch.topk(probs, k=min(k, probs.shape[0]))
+        rows = []
+        for prob, idx in zip(topk.values.tolist(), topk.indices.tolist()):
+            token_str = self.tokenizer.decode([idx])
+            rows.append((token_str, float(prob), int(idx)))
+        return rows
+
+    # ------------------------------------------------------------------
+    # High-level generation
+    # ------------------------------------------------------------------
+
+    def generate_step_by_step(
+        self,
+        prompt: str,
+        steps: int = 8,
+        temperature: float = 0.8,
+        top_n: int = 10,
+        seed: int = 42,
+        show_steps: bool = True,
+    ) -> list[dict]:
+        """Generate tokens one at a time, returning per-step data.
+
+        Each step dict contains:
+            - step: int (1-based)
+            - text: accumulated text so far
+            - token: the sampled token string
+            - token_id: int
+            - entropy: float (bits)
+            - top_tokens: list of (token_str, prob, token_id)
+        """
+        if not self.is_ready():
+            return []
+
+        text = prompt
+        results = []
+        rng = torch.Generator()
+
+        for i in range(steps):
+            logits = self._get_logits(text)
+            probs = self.apply_temperature(logits, temperature)
+            entropy = self.entropy_bits(probs)
+            top_tokens = self.top_k_table(probs, k=top_n) if show_steps else []
+
+            # Sample with deterministic seed per step
+            rng.manual_seed(seed + i)
+            idx = torch.multinomial(probs.cpu(), num_samples=1, generator=rng).item()
+            token_str = self.tokenizer.decode([idx])
+            text += token_str
+
+            results.append({
+                "step": i + 1,
+                "text": text,
+                "token": token_str,
+                "token_id": int(idx),
+                "entropy": entropy,
+                "top_tokens": top_tokens,
+            })
+
+        return results
+
+    def generate_text(
+        self,
+        prompt: str,
+        num_tokens: int = 30,
+        temperature: float = 0.8,
+        top_k: int = 40,
+        seed: int = 42,
+    ) -> str:
+        """Generate text with top-k sampling. Returns prompt + generated text."""
+        if not self.is_ready():
+            return prompt
+
+        text = prompt
+        rng = torch.Generator()
+
+        for i in range(num_tokens):
+            logits = self._get_logits(text)
+
+            # Apply top-k filtering
+            if top_k > 0:
+                top_k_vals, top_k_idxs = torch.topk(logits, k=min(top_k, logits.shape[0]))
+                mask = torch.full_like(logits, float("-inf"))
+                mask.scatter_(0, top_k_idxs, top_k_vals)
+                logits = mask
+
+            probs = self.apply_temperature(logits, temperature)
+
+            rng.manual_seed(seed + i)
+            idx = torch.multinomial(probs.cpu(), num_samples=1, generator=rng).item()
+            token_str = self.tokenizer.decode([idx])
+            text += token_str
+
+        return text
+
+    def tokenize(self, text: str) -> list[tuple[str, int]]:
+        """Tokenize text and return list of (token_str, token_id)."""
+        if self.tokenizer is None:
+            return []
+        ids = self.tokenizer.encode(text)
+        return [(self.tokenizer.decode([tid]), tid) for tid in ids]
+
+    # ------------------------------------------------------------------
+    # Config helpers
+    # ------------------------------------------------------------------
+
+    def get_config(self) -> dict:
+        return dict(self.config)
+
+    def update_config(self, **kwargs) -> None:
+        self.config.update(kwargs)
+        _save_config(self.config)
+
+
+# Module-level singleton
+manager = ModelManager()

requirements.txt

@@ -0,0 +1,7 @@
+torch>=2.1.0
+transformers>=4.40.0
+accelerate>=0.27.0
+bitsandbytes>=0.43.0
+gradio>=4.20.0
+sentencepiece>=0.2.0
+protobuf>=4.25.0