backshot-solver 0.1.0__tar.gz

backshot_solver-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.3
+Name: backshot-solver
+Version: 0.1.0
+Summary: A buckshot roulette magazine predictor
+Author: takingurstuff
+Author-email: takingurstuff <130810510+takingurstuff@users.noreply.github.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Buckshot Roulette Solver Overlay
+
+A minimal, low-latency, mathematical state-space tracker and HUD overlay for _Buckshot Roulette_ (and its Roblox port _Buckshot_). Tracks exact shell inventory, computes real-time Bayesian chamber probabilities, and incorporates oracle item observations (Magnifying Glass and Burner Phone) using vim-style keybinds. Partially inspired by [BackshotRoulette](https://github.com/redstone59/BackshotRoulette) (redstone59)
+
+---
+
+## Installation
+
+### Via `pipx` or `uv`
+
+```bash
+# uv:
+uvx backshot-solver
+
+# or pipx:
+pipx install backshot-solver
+```
+
+### Editable
+
+```bash
+git clone https://github.com/takingurstuff/backshot-solver
+pip install -e .
+```
+
+### Development Install (`uv` recommended)
+
+```bash
+git clone https://github.com/takingurstuff/backshot-solver
+uv sync
+```
+
+---
+
+## How to Use
+
+1. Launch **Buckshot Roulette** in **Borderless Windowed** or **Windowed** mode.
+2. Launch the solver:
+
+```bash
+backshot-solver
+```
+
+_Do note that the overlay pins itself to top for easy accessing_.
+
+3. Enter the initial **Live** and **Blank** shell counts announced by the dealer at the start of the loadout.
+4. Click **Initialize**.
+
+---
+
+## Keybinds & Controls
+
+All inputs use modal, vim-style chords. You do not need to click or hold modifier keys:
+
+| Command          | Action                                | Example                            |
+| ---------------- | ------------------------------------- | ---------------------------------- |
+| `L`              | Register Live shell fired/ejected     | Dealer shoots Live                 |
+| `B`              | Register Blank shell fired/ejected    | Dealer shoots Blank or drinks Beer |
+| `ML` / `MB`      | **Magnifying Glass** (Top shell type) | `ML` = Top shell is Live           |
+| `P<Slot><Type>`  | **Burner Phone** (Forward indexing)   | `P3L` = 3rd shell from top is Live |
+| `P-<Slot><Type>` | **Burner Phone** (Backward indexing)  | `P-1B` = Last shell is Blank       |
+
+_Note: If an invalid key or partial chord is abandoned, the input buffer clears automatically after 1.2 seconds._
+
+---
+
+## Compositor Setup (Hyprland)
+
+For Hyprland users, add these rules to `~/.config/hypr/hyprland.conf` to enable opacity and floating:
+
+```ini
+windowrulev2 = float, title:^(Buckshot Roulette Solver Overlay)$
+windowrulev2 = opacity 0.7 0.7, title:^(Buckshot Roulette Solver Overlay)$
+windowrulev2 = noblur, title:^(Buckshot Roulette Solver Overlay)$
+
+```
+
+OR post luafication hyprland:
+
+```lua
+hl.window_rule({
+    match = {
+        title = "^(Buckshot Roulette Solver Overlay)$",
+    },
+    float = true,
+    pin = true,
+    opacity = "0.7 0.7",
+    no_blur = true,
+})
+```
+
+---
+
+## Disclaimers
+
+> **Use at Your Own Risk:** This is an external mathematical calculator. While it does not hook into, inject code, or read game process memory, using third-party trackers in online multiplayer mode may be considered unsportsmanlike or breach community guidelines.
+
+> **RNG & Variance:** This tool provides strictly optimal mathematical probabilities based on known information. An $80\%$ chance of a blank is not a $100\%$ guarantee—variance and bad rolls can and will still happen.

backshot_solver-0.1.0/README.md

@@ -0,0 +1,98 @@
+# Buckshot Roulette Solver Overlay
+
+A minimal, low-latency, mathematical state-space tracker and HUD overlay for _Buckshot Roulette_ (and its Roblox port _Buckshot_). Tracks exact shell inventory, computes real-time Bayesian chamber probabilities, and incorporates oracle item observations (Magnifying Glass and Burner Phone) using vim-style keybinds. Partially inspired by [BackshotRoulette](https://github.com/redstone59/BackshotRoulette) (redstone59)
+
+---
+
+## Installation
+
+### Via `pipx` or `uv`
+
+```bash
+# uv:
+uvx backshot-solver
+
+# or pipx:
+pipx install backshot-solver
+```
+
+### Editable
+
+```bash
+git clone https://github.com/takingurstuff/backshot-solver
+pip install -e .
+```
+
+### Development Install (`uv` recommended)
+
+```bash
+git clone https://github.com/takingurstuff/backshot-solver
+uv sync
+```
+
+---
+
+## How to Use
+
+1. Launch **Buckshot Roulette** in **Borderless Windowed** or **Windowed** mode.
+2. Launch the solver:
+
+```bash
+backshot-solver
+```
+
+_Do note that the overlay pins itself to top for easy accessing_.
+
+3. Enter the initial **Live** and **Blank** shell counts announced by the dealer at the start of the loadout.
+4. Click **Initialize**.
+
+---
+
+## Keybinds & Controls
+
+All inputs use modal, vim-style chords. You do not need to click or hold modifier keys:
+
+| Command          | Action                                | Example                            |
+| ---------------- | ------------------------------------- | ---------------------------------- |
+| `L`              | Register Live shell fired/ejected     | Dealer shoots Live                 |
+| `B`              | Register Blank shell fired/ejected    | Dealer shoots Blank or drinks Beer |
+| `ML` / `MB`      | **Magnifying Glass** (Top shell type) | `ML` = Top shell is Live           |
+| `P<Slot><Type>`  | **Burner Phone** (Forward indexing)   | `P3L` = 3rd shell from top is Live |
+| `P-<Slot><Type>` | **Burner Phone** (Backward indexing)  | `P-1B` = Last shell is Blank       |
+
+_Note: If an invalid key or partial chord is abandoned, the input buffer clears automatically after 1.2 seconds._
+
+---
+
+## Compositor Setup (Hyprland)
+
+For Hyprland users, add these rules to `~/.config/hypr/hyprland.conf` to enable opacity and floating:
+
+```ini
+windowrulev2 = float, title:^(Buckshot Roulette Solver Overlay)$
+windowrulev2 = opacity 0.7 0.7, title:^(Buckshot Roulette Solver Overlay)$
+windowrulev2 = noblur, title:^(Buckshot Roulette Solver Overlay)$
+
+```
+
+OR post luafication hyprland:
+
+```lua
+hl.window_rule({
+    match = {
+        title = "^(Buckshot Roulette Solver Overlay)$",
+    },
+    float = true,
+    pin = true,
+    opacity = "0.7 0.7",
+    no_blur = true,
+})
+```
+
+---
+
+## Disclaimers
+
+> **Use at Your Own Risk:** This is an external mathematical calculator. While it does not hook into, inject code, or read game process memory, using third-party trackers in online multiplayer mode may be considered unsportsmanlike or breach community guidelines.
+
+> **RNG & Variance:** This tool provides strictly optimal mathematical probabilities based on known information. An $80\%$ chance of a blank is not a $100\%$ guarantee—variance and bad rolls can and will still happen.

backshot_solver-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "backshot-solver"
+version = "0.1.0"
+description = "A buckshot roulette magazine predictor"
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[[project.authors]]
+name = "takingurstuff"
+email = "130810510+takingurstuff@users.noreply.github.com"
+
+[project.gui-scripts]
+backshot-solver = "backshot_solver.app:main"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

backshot_solver-0.1.0/pyproject.toml.orig

@@ -0,0 +1,17 @@
+[project]
+name = "backshot-solver"
+version = "0.1.0"
+description = "A buckshot roulette magazine predictor"
+readme = "README.md"
+authors = [
+    { name = "takingurstuff", email = "130810510+takingurstuff@users.noreply.github.com" },
+]
+requires-python = ">=3.13"
+dependencies = []
+
+[project.gui-scripts]
+backshot-solver = "backshot_solver.app:main"
+
+[build-system]
+requires = ["uv_build>=0.12.1,<0.13.0"]
+build-backend = "uv_build"

backshot_solver-0.1.0/src/backshot_solver/__init__.py

@@ -0,0 +1,2 @@
+def main() -> None:
+    print("Hello from backshot-solver!")

backshot_solver-0.1.0/src/backshot_solver/app.py

@@ -0,0 +1,664 @@
+import re
+import sys
+import tkinter as tk
+from tkinter import ttk
+from typing import List, Literal, Union, Dict
+from .predictor import BuckshotMagazinePredictor
+
+ShellType = Literal["L", "B", "U"]
+
+
+class App(tk.Tk):
+
+    def __init__(self):
+        super().__init__()
+
+        # --- Window & Title Bar Configuration ---
+        self.title("Buckshot Roulette Solver Overlay")
+        self.geometry("520x720")
+        self.minsize(460, 680)
+
+        # --- Chroma Key Transparency Settings ---
+        # Any widget or background painted with CHROMA_KEY becomes completely transparent/pass-through
+        self.CHROMA_KEY = "#010101"
+        self.configure(bg=self.CHROMA_KEY)
+
+        # Apply OS-level chroma transparency (Windows / X11)
+        if sys.platform.startswith("win"):
+            self.wm_attributes("-transparentcolor", self.CHROMA_KEY)
+        self.attributes("-topmost", True)
+
+        # --- Solid Dark UI Theme Palette ---
+        self.COLOR_PANEL_BG = "#161616"  # Opaque panel backing
+        self.COLOR_PANEL_BORDER = "#2B2B2B"  # Subdued outer borders
+        self.COLOR_CANVAS_BG = "#0D0D0D"  # High-contrast widget display
+        self.COLOR_TEXT_PRIMARY = "#EEEEEE"  # Crisp bright labels
+        self.COLOR_TEXT_MUTED = "#888888"  # Subdued instructional text
+
+        self.PALETTE = {
+            "L": {"bg": "#9E1C1C", "border": "#FF4D4D", "text": "LIVE"},
+            "B": {"bg": "#14487A", "border": "#4DA3FF", "text": "BLANK"},
+            "U": {"bg": "#2A2A2A", "border": "#555555", "text": "?"},
+        }
+
+        # State & Buffer Tracking
+        self.magazine = None
+        self.key_buffer = ""
+        self.reset_timer_id = None
+
+        self._configure_ttk_styles()
+        self._create_widgets()
+
+        # Listen for keypress events across the window
+        self.bind("<Key>", self._handle_keypress)
+
+    def _configure_ttk_styles(self):
+        """Configure dark, solid TTK styles to ensure no background bleed."""
+        style = ttk.Style(self)
+        style.theme_use("clam")
+
+        # Base Frame & LabelFrames
+        style.configure("Dark.TFrame", background=self.COLOR_PANEL_BG)
+        style.configure(
+            "Dark.TLabelframe",
+            background=self.COLOR_PANEL_BG,
+            bordercolor=self.COLOR_PANEL_BORDER,
+            darkcolor=self.COLOR_PANEL_BORDER,
+            lightcolor=self.COLOR_PANEL_BORDER,
+        )
+        style.configure(
+            "Dark.TLabelframe.Label",
+            background=self.COLOR_PANEL_BG,
+            foreground="#CCCCCC",
+            font=("Consolas", 9, "bold"),
+        )
+
+        # Labels
+        style.configure(
+            "Dark.TLabel",
+            background=self.COLOR_PANEL_BG,
+            foreground=self.COLOR_TEXT_PRIMARY,
+        )
+        style.configure(
+            "Muted.TLabel",
+            background=self.COLOR_PANEL_BG,
+            foreground=self.COLOR_TEXT_MUTED,
+            font=("Arial", 8),
+        )
+
+        # Buttons
+        style.configure(
+            "Dark.TButton",
+            background="#262626",
+            foreground="#FFFFFF",
+            bordercolor="#444444",
+            focuscolor="none",
+            font=("Consolas", 9, "bold"),
+        )
+        style.map(
+            "Dark.TButton",
+            background=[("active", "#383838"), ("pressed", "#181818")],
+            bordercolor=[("active", "#666666")],
+        )
+
+        # Spinbox
+        style.configure(
+            "Dark.TSpinbox",
+            fieldbackground="#0D0D0D",
+            background="#262626",
+            foreground="#FFFFFF",
+            arrowcolor="#CCCCCC",
+            bordercolor="#333333",
+            insertcolor="#FFFFFF",
+        )
+
+    def _create_widgets(self):
+        # Main solid HUD container
+        main_frame = ttk.Frame(self, padding="14", style="Dark.TFrame")
+        main_frame.pack(fill="both", expand=True, padx=4, pady=4)
+        main_frame.columnconfigure(0, weight=1)
+
+        # 1. Instructions Block
+        instructions_text = (
+            "• [ L ] / [ B ] = Register Live / Blank shot or ejection\n"
+            "• [ ML ] / [ MB ] = Magnifying Glass (e.g., ML = top is live)\n"
+            "• [ P + Slot + Type ] = Burner Phone (e.g., P3L = 3rd shell is live)"
+        )
+        self.label_instructions = ttk.Label(
+            main_frame,
+            text=instructions_text,
+            justify="left",
+            anchor="nw",
+            style="Muted.TLabel",
+        )
+        self.label_instructions.grid(row=0, column=0, sticky="ew", pady=(0, 6))
+
+        # 2. Input Fields Container
+        inputs_frame = ttk.Frame(main_frame, style="Dark.TFrame")
+        inputs_frame.grid(row=1, column=0, sticky="ew", pady=(0, 6))
+        inputs_frame.columnconfigure(0, weight=1)
+        inputs_frame.columnconfigure(1, weight=1)
+
+        vcmd = (self.register(self._validate_spinbox), "%P")
+
+        ttk.Label(inputs_frame, text="Live Shells:", style="Dark.TLabel").grid(
+            row=0, column=0, sticky="w", padx=(0, 6), pady=(0, 2)
+        )
+        self.live_shells = ttk.Spinbox(
+            inputs_frame,
+            from_=0,
+            to=9,
+            increment=1,
+            validate="key",
+            validatecommand=vcmd,
+            style="Dark.TSpinbox",
+        )
+        self.live_shells.set("0")
+        self.live_shells.grid(row=1, column=0, sticky="ew", padx=(0, 6))
+
+        ttk.Label(inputs_frame, text="Blank Shells:", style="Dark.TLabel").grid(
+            row=0, column=1, sticky="w", padx=(6, 0), pady=(0, 2)
+        )
+        self.blank_shells = ttk.Spinbox(
+            inputs_frame,
+            from_=0,
+            to=9,
+            increment=1,
+            validate="key",
+            validatecommand=vcmd,
+            style="Dark.TSpinbox",
+        )
+        self.blank_shells.set("0")
+        self.blank_shells.grid(row=1, column=1, sticky="ew", padx=(6, 0))
+
+        # 3. Action Buttons
+        button_frame = ttk.Frame(main_frame, style="Dark.TFrame")
+        button_frame.grid(row=2, column=0, sticky="ew", pady=(2, 6))
+        button_frame.columnconfigure(0, weight=1)
+        button_frame.columnconfigure(1, weight=1)
+
+        self.btn_initialize = ttk.Button(
+            button_frame,
+            text="Initialize",
+            command=self.on_initialize,
+            style="Dark.TButton",
+        )
+        self.btn_initialize.grid(row=0, column=0, sticky="ew", padx=(0, 6), ipady=2)
+
+        self.btn_reset = ttk.Button(
+            button_frame,
+            text="Reset",
+            command=self.on_reset,
+            style="Dark.TButton",
+        )
+        self.btn_reset.grid(row=0, column=1, sticky="ew", padx=(6, 0), ipady=2)
+
+        # 4. Status Bar
+        status_frame = ttk.LabelFrame(
+            main_frame, text="Status", padding="6", style="Dark.TLabelframe"
+        )
+        status_frame.grid(row=3, column=0, sticky="ew", pady=(2, 6))
+        status_frame.columnconfigure(0, weight=1)
+
+        self.label_status = ttk.Label(
+            status_frame,
+            text="Ready. Enter counts and click 'Initialize'.",
+            font=("Consolas", 9),
+            justify="left",
+            anchor="w",
+            style="Dark.TLabel",
+        )
+        self.label_status.grid(row=0, column=0, sticky="ew")
+
+        # 5. Shell Pool (Tallies & Counts)
+        tally_frame = ttk.LabelFrame(
+            main_frame,
+            text="Remaining Shell Pool",
+            padding="6",
+            style="Dark.TLabelframe",
+        )
+        tally_frame.grid(row=4, column=0, sticky="ew", pady=(2, 6))
+        tally_frame.columnconfigure(0, weight=1)
+
+        self.tally_canvas = tk.Canvas(
+            tally_frame,
+            height=48,
+            bg=self.COLOR_CANVAS_BG,
+            highlightthickness=1,
+            highlightbackground="#222222",
+        )
+        self.tally_canvas.grid(row=0, column=0, sticky="ew")
+        self.tally_canvas.bind("<Configure>", lambda e: self.update_tally_display())
+
+        # 6. Top Shell Confidence Box
+        confidence_frame = ttk.LabelFrame(
+            main_frame,
+            text="Next Shell Confidence",
+            padding="6",
+            style="Dark.TLabelframe",
+        )
+        confidence_frame.grid(row=5, column=0, sticky="ew", pady=(2, 6))
+        confidence_frame.columnconfigure(0, weight=1)
+
+        self.confidence_canvas = tk.Canvas(
+            confidence_frame,
+            height=22,
+            bg=self.COLOR_CANVAS_BG,
+            highlightthickness=1,
+            highlightbackground="#222222",
+        )
+        self.confidence_canvas.grid(row=0, column=0, sticky="ew", pady=(0, 4))
+        self.confidence_canvas.bind(
+            "<Configure>", lambda e: self.update_confidence_bar()
+        )
+
+        self.label_confidence = ttk.Label(
+            confidence_frame,
+            text="No data",
+            font=("Consolas", 9, "bold"),
+            anchor="center",
+            style="Dark.TLabel",
+        )
+        self.label_confidence.grid(row=1, column=0, sticky="ew")
+
+        # 7. Magazine Visualizer Box (Chamber Sequence)
+        magazine_frame = ttk.LabelFrame(
+            main_frame,
+            text="Chamber Sequence Prediction",
+            padding="6",
+            style="Dark.TLabelframe",
+        )
+        magazine_frame.grid(row=6, column=0, sticky="nsew", pady=(2, 0))
+        magazine_frame.columnconfigure(0, weight=1)
+        main_frame.rowconfigure(6, weight=1)
+
+        self.mag_canvas = tk.Canvas(
+            magazine_frame,
+            height=86,
+            bg=self.COLOR_CANVAS_BG,
+            highlightthickness=1,
+            highlightbackground="#222222",
+        )
+        self.mag_canvas.grid(row=0, column=0, sticky="nsew")
+        self.mag_canvas.bind("<Configure>", lambda e: self.update_magazine_display())
+
+    # --- Drawing Helpers ---
+    def _draw_tally_group(
+        self,
+        canvas: tk.Canvas,
+        start_x: int,
+        start_y: int,
+        count: int,
+        color: str,
+    ) -> int:
+        stroke_h = 22
+        stroke_spacing = 6
+        group_gap = 14
+        line_w = 3
+
+        cur_x = start_x
+        full_groups = count // 5
+        remainder = count % 5
+
+        for _ in range(full_groups):
+            for i in range(4):
+                canvas.create_line(
+                    cur_x + (i * stroke_spacing),
+                    start_y,
+                    cur_x + (i * stroke_spacing),
+                    start_y + stroke_h,
+                    fill=color,
+                    width=line_w,
+                    capstyle="round",
+                )
+            canvas.create_line(
+                cur_x - 3,
+                start_y + stroke_h - 2,
+                cur_x + (3 * stroke_spacing) + 3,
+                start_y + 2,
+                fill=color,
+                width=line_w,
+                capstyle="round",
+            )
+            cur_x += (3 * stroke_spacing) + group_gap
+
+        for i in range(remainder):
+            canvas.create_line(
+                cur_x + (i * stroke_spacing),
+                start_y,
+                cur_x + (i * stroke_spacing),
+                start_y + stroke_h,
+                fill=color,
+                width=line_w,
+                capstyle="round",
+            )
+        if remainder > 0:
+            cur_x += (remainder - 1) * stroke_spacing
+
+        return cur_x
+
+    # --- UI Synchronization ---
+    def refresh_all_displays(self):
+        self.update_tally_display()
+        self.update_confidence_bar()
+        self.update_magazine_display()
+
+    def update_tally_display(self):
+        self.tally_canvas.delete("all")
+        w = self.tally_canvas.winfo_width()
+        h = self.tally_canvas.winfo_height()
+
+        if w <= 1:
+            return
+
+        if not self.magazine or self.magazine.depth == 0:
+            self.tally_canvas.create_text(
+                w // 2,
+                h // 2,
+                text="CHAMBER EMPTY",
+                fill="#555555",
+                font=("Consolas", 9, "bold"),
+            )
+            return
+
+        lives = self.magazine.n_lives
+        blanks = self.magazine.n_blanks
+        half_w = w // 2
+        y_pos = (h - 22) // 2
+
+        # Left Half: LIVE
+        self.tally_canvas.create_text(
+            16,
+            h // 2,
+            text=f"LIVE [{lives}]",
+            fill=self.PALETTE["L"]["border"],
+            font=("Consolas", 10, "bold"),
+            anchor="w",
+        )
+        if lives > 0:
+            self._draw_tally_group(
+                self.tally_canvas,
+                start_x=95,
+                start_y=y_pos,
+                count=lives,
+                color=self.PALETTE["L"]["border"],
+            )
+
+        # Center Line
+        self.tally_canvas.create_line(half_w, 6, half_w, h - 6, fill="#222222", width=1)
+
+        # Right Half: BLANK
+        self.tally_canvas.create_text(
+            half_w + 16,
+            h // 2,
+            text=f"BLANK [{blanks}]",
+            fill=self.PALETTE["B"]["border"],
+            font=("Consolas", 10, "bold"),
+            anchor="w",
+        )
+        if blanks > 0:
+            self._draw_tally_group(
+                self.tally_canvas,
+                start_x=half_w + 105,
+                start_y=y_pos,
+                count=blanks,
+                color=self.PALETTE["B"]["border"],
+            )
+
+    def update_confidence_bar(self):
+        self.confidence_canvas.delete("all")
+        width = self.confidence_canvas.winfo_width()
+        height = self.confidence_canvas.winfo_height()
+
+        if width <= 1:
+            return
+
+        if not self.magazine or self.magazine.depth == 0:
+            self.label_confidence.configure(
+                text="No Shells Remaining", foreground=self.COLOR_TEXT_MUTED
+            )
+            return
+
+        top_pred = self.magazine.predict_slot(0)
+
+        if top_pred == "L":
+            p_val = 1.0
+            shell_type = "L"
+            text_desc = "100.0% LIVE"
+        elif top_pred == "B":
+            p_val = 1.0
+            shell_type = "B"
+            text_desc = "100.0% BLANK"
+        elif isinstance(top_pred, dict):
+            p_live = top_pred.get("L", 0.0)
+            p_blank = top_pred.get("B", 0.0)
+            if p_live >= p_blank:
+                p_val = p_live
+                shell_type = "L"
+            else:
+                p_val = p_blank
+                shell_type = "B"
+            text_desc = f"Live: {p_live*100:.1f}% | Blank: {p_blank*100:.1f}%"
+        else:
+            self.label_confidence.configure(
+                text="Unknown", foreground=self.COLOR_TEXT_MUTED
+            )
+            return
+
+        self.label_confidence.configure(
+            text=text_desc, foreground=self.COLOR_TEXT_PRIMARY
+        )
+
+        fill_width = int(width * p_val)
+        bar_color = self.PALETTE[shell_type]["bg"]
+
+        self.confidence_canvas.create_rectangle(
+            0, 0, fill_width, height, fill=bar_color, width=0
+        )
+
+    def update_magazine_display(self):
+        self.mag_canvas.delete("all")
+        canvas_width = self.mag_canvas.winfo_width()
+        canvas_height = self.mag_canvas.winfo_height()
+
+        if canvas_width <= 1 or not self.magazine or self.magazine.depth == 0:
+            return
+
+        predictions: List[ShellType] = self.magazine.predict_all()
+        n = len(predictions)
+        if n == 0:
+            return
+
+        card_w, card_h = 36, 48
+        spacing = 8
+        total_w = (n * card_w) + ((n - 1) * spacing)
+        start_x = max(10, (canvas_width - total_w) // 2)
+        start_y = max(10, (canvas_height - card_h) // 2)
+
+        for i, shell_type in enumerate(predictions):
+            x = start_x + i * (card_w + spacing)
+            y = start_y
+            cfg = self.PALETTE[shell_type]
+            is_top = i == 0
+
+            # Card Rectangle
+            self.mag_canvas.create_rectangle(
+                x,
+                y,
+                x + card_w,
+                y + card_h,
+                fill=cfg["bg"],
+                outline="#FFD700" if is_top else cfg["border"],
+                width=2 if is_top else 1,
+            )
+
+            # Card Text Label
+            self.mag_canvas.create_text(
+                x + card_w // 2,
+                y + card_h // 2,
+                text=cfg["text"],
+                fill="#FFFFFF",
+                font=("Consolas", 8, "bold"),
+            )
+
+            # Slot Number
+            self.mag_canvas.create_text(
+                x + card_w // 2,
+                y - 7,
+                text=f"#{i+1}",
+                fill="#FFD700" if is_top else "#777777",
+                font=("Consolas", 7, "bold" if is_top else "normal"),
+            )
+
+    # --- Status Management Helpers ---
+    def set_status(self, message: str, is_warning: bool = False):
+        color = "#FF5555" if is_warning else self.COLOR_TEXT_PRIMARY
+        self.label_status.configure(text=message, foreground=color)
+
+    # --- Validation & Value Fetching ---
+    def _validate_spinbox(self, proposed_val: str) -> bool:
+        if proposed_val == "":
+            return True
+        return proposed_val.isdigit() and len(proposed_val) == 1
+
+    def _get_spinbox_value(self, spinbox: ttk.Spinbox) -> int:
+        raw_val = spinbox.get().strip()
+        if not raw_val or not raw_val.isdigit():
+            spinbox.set("0")
+            return 0
+        return int(raw_val)
+
+    # --- Key Event Handling & Buffer Management ---
+    def _handle_keypress(self, event):
+        if event.widget in (self.live_shells, self.blank_shells):
+            return
+
+        char = event.char.lower()
+        if not char:
+            return
+
+        self.key_buffer += char
+
+        if self.reset_timer_id:
+            self.after_cancel(self.reset_timer_id)
+
+        if self._evaluate_buffer():
+            self.key_buffer = ""
+        else:
+            self.reset_timer_id = self.after(1200, self._clear_buffer_on_timeout)
+
+    def _evaluate_buffer(self) -> bool:
+        buf = self.key_buffer
+
+        # 1. Single shot: [B] or [L]
+        if buf in ("b", "l"):
+            if not self._check_magazine_initialized():
+                return True
+            self.on_shot_registered(is_live=(buf == "l"))
+            return True
+
+        # 2. Magnifier: [MB] or [ML]
+        match_mag = re.match(r"^m([bl])$", buf)
+        if match_mag:
+            if not self._check_magazine_initialized():
+                return True
+            self.on_magnifier_used(is_live=(match_mag.group(1) == "l"))
+            return True
+
+        # 3. Burner Phone (Forward & Backward): [P + optional minus + digit + B/L]
+        # Examples: p3l (3rd from top), p-1b (last shell from bottom)
+        match_phone = re.match(r"^p(-?[1-9])([bl])$", buf)
+        if match_phone:
+            if not self._check_magazine_initialized():
+                return True
+            slot_offset = int(match_phone.group(1))
+            self.on_phone_used(slot=slot_offset, is_live=(match_phone.group(2) == "l"))
+            return True
+
+        if not (buf.startswith("m") or buf.startswith("p")):
+            return True
+
+        return False
+
+    def _check_magazine_initialized(self) -> bool:
+        if self.magazine is None or self.magazine.depth == 0:
+            self.set_status("⚠️ Magazine is empty or not initialized!", is_warning=True)
+            return False
+        return True
+
+    def _clear_buffer_on_timeout(self):
+        self.key_buffer = ""
+
+    # --- Action Callbacks ---
+    def on_shot_registered(self, is_live: bool):
+        if self._check_magazine_initialized():
+            self.magazine.observe_extraction("L" if is_live else "B")
+            self.set_status(f"{'Live' if is_live else 'Blank'} shell ejected.")
+            self.refresh_all_displays()
+
+    def on_magnifier_used(self, is_live: bool):
+        if self._check_magazine_initialized():
+            self.magazine.observe_peek(0, "L" if is_live else "B")
+            self.set_status(
+                f"Magnifier: Top shell is {'Live' if is_live else 'Blank'}."
+            )
+            self.refresh_all_displays()
+
+    def on_phone_used(self, slot: int, is_live: bool):
+        if self._check_magazine_initialized():
+            depth = self.magazine.depth
+
+            if slot > 0:
+                # 1-based forward index -> 0-based index
+                zero_indexed = slot - 1
+            else:
+                # Negative backward index (e.g., -1 is last shell, depth - 1)
+                zero_indexed = slot
+
+            if not (0 <= abs(zero_indexed) < depth):
+                self.set_status(
+                    f"⚠️ Slot #{slot} is out of bounds (depth={depth}).",
+                    is_warning=True,
+                )
+                return
+
+            self.magazine.observe_peek(zero_indexed, "L" if is_live else "B")
+            self.set_status(
+                f"Burner Phone: Shell #{slot if slot > 0 else zero_indexed + 1} is {'Live' if is_live else 'Blank'}."
+            )
+            self.refresh_all_displays()
+
+    # --- Lifecycle Callbacks ---
+    def on_initialize(self):
+        lives = self._get_spinbox_value(self.live_shells)
+        blanks = self._get_spinbox_value(self.blank_shells)
+        total = lives + blanks
+
+        if total == 0:
+            self.set_status(
+                "⚠️ Cannot initialize with 0 total shells.", is_warning=True
+            )
+            return
+
+        self.magazine = BuckshotMagazinePredictor(lives, blanks)
+        self.set_status(
+            f"Initialized: {lives} Live, {blanks} Blank ({total} total chambered)."
+        )
+        self.refresh_all_displays()
+
+    def on_reset(self):
+        self.live_shells.set("0")
+        self.blank_shells.set("0")
+        self.magazine = None
+        self.key_buffer = ""
+        self.set_status("App reset. Enter shell counts and click 'Initialize'.")
+        self.refresh_all_displays()
+
+
+def main():
+    app = App()
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    main()

backshot_solver-0.1.0/src/backshot_solver/predictor.py

@@ -0,0 +1,78 @@
+import itertools
+from typing import List, Dict, Optional, Literal, Union
+
+ShellType = Literal["L", "B", "U"]
+
+
+class BuckshotMagazinePredictor:
+    def __init__(self, n_lives: int, n_blanks: int):
+        """Initializes with total known counts of Live ('L') and Blank ('B') shells."""
+        self.candidates: List[tuple[Literal["L", "B"], ...]] = list(
+            set(itertools.permutations(["L"] * n_lives + ["B"] * n_blanks))
+        )
+        self.depth = n_lives + n_blanks
+        self.n_lives = n_lives
+        self.n_blanks = n_blanks
+
+    def observe_peek(self, depth_from_top: int, shell_type: Literal["L", "B"]) -> int:
+        """
+        Filters candidate sequences by an oracle query (e.g. Magnifying Glass / Phone) at a given depth.
+        depth_from_top: 0-indexed (0 is current top shell). supports negative indexes.
+        """
+        self.candidates = [
+            cand for cand in self.candidates if cand[depth_from_top] == shell_type
+        ]
+        return len(self.candidates)
+
+    def observe_extraction(self, shell_type: Literal["L", "B"]) -> int:
+        """
+        Filters candidates matching fired/ejected top shell, then shifts the magazine up.
+        """
+        self.candidates = [
+            cand[1:] for cand in self.candidates if cand[0] == shell_type
+        ]
+        self.depth -= 1
+        if shell_type == "B":
+            self.n_blanks -= 1
+        elif shell_type == "L":
+            self.n_lives -= 1
+        return len(self.candidates)
+
+    def predict_slot(
+        self, depth_from_top: int = 0
+    ) -> Union[Literal["L", "B"], Dict[Literal["L", "B"], float], None]:
+        """
+        Returns:
+        - "L" or "B" if deterministic (100% certain).
+        - A dict with probabilities `{"L": P(Live), "B": P(Blank)}` if unknown.
+        - None if magazine is empty or index is out of bounds.
+        """
+        if not self.candidates or depth_from_top >= self.depth:
+            return None
+
+        total = len(self.candidates)
+        count_live = sum(1 for cand in self.candidates if cand[depth_from_top] == "L")
+
+        p_live = count_live / total
+        p_blank = 1.0 - p_live
+
+        if p_live == 1.0:
+            return "L"
+        if p_blank == 1.0:
+            return "B"
+
+        return {"L": round(p_live, 4), "B": round(p_blank, 4)}
+
+    def predict_all(self) -> List[ShellType]:
+        """
+        Returns a list of ShellType for all remaining slots from top to bottom.
+        Each element is 'L' (Live), 'B' (Blank), or 'U' (Unknown/Probabilistic).
+        """
+        result: List[ShellType] = []
+        for i in range(self.depth):
+            slot_prediction = self.predict_slot(i)
+            if slot_prediction in ("L", "B"):
+                result.append(slot_prediction)
+            else:
+                result.append("U")
+        return result