refactor: rename folders to fix N999, INP001, S311 linting rules

- Rename PYTHON/ to python_pkg/ (fix N999 uppercase folder)
- Rename camelCase folders to snake_case:
  - randomJPG -> random_jpg
  - tagDivider -> tag_divider
  - downloadCats -> download_cats
  - keyboardCoop -> keyboard_coop
  - extractLinks -> extract_links
  - scapeWebsite -> scrape_website
- Rename camelCase files:
  - generateJpeg.py -> generate_jpeg.py
  - tagDivider.py -> tag_divider.py
- Rename poker-modifier-app to poker_modifier_app (fix INP001)
- Add __init__.py to poker_modifier_app
- Replace random module with secrets.SystemRandom (fix S311)
- Fix S110 try-except-pass with contextlib.suppress
- Update all imports and config references

python_pkg/download_cats/__init__.py

@@ -0,0 +1 @@
+"""Cat image generator package."""

python_pkg/download_cats/generate_cats.py

@@ -0,0 +1,46 @@
+"""Download cat images from TheCatAPI.
+
+Fetches cat images in batches and saves them to a local directory.
+"""
+
+import json
+import logging
+import os
+from pathlib import Path
+
+import requests
+
+logging.basicConfig(level=logging.INFO)
+
+MAX_REQUESTS = 90
+REQUEST_TIMEOUT = 30  # seconds
+
+requests_send = 0
+while requests_send < MAX_REQUESTS:
+    res = requests.get(
+        "https://api.thecatapi.com/v1/images/search?limit=100&api_key=",
+        timeout=REQUEST_TIMEOUT,
+    )
+    requests_send += 1
+    response = json.loads(res.text)
+    urls = [cat.get("url") for cat in response]
+
+    Path("./CATS2").mkdir(parents=True, exist_ok=True)
+    for url in urls:
+        try:
+            # Get the image content
+            response = requests.get(url, timeout=REQUEST_TIMEOUT)
+            response.raise_for_status()  # Raise an exception for HTTP errors
+
+            # Extract the image name from the URL
+            image_name = os.path.basename(url)
+            image_path = os.path.join("./CATS2/", image_name)
+
+            # Save the image to the directory
+            with open(image_path, "wb") as file:
+                file.write(response.content)
+
+            logging.info(f"Saved {url} as {image_path}")
+
+        except requests.exceptions.RequestException:
+            logging.exception(f"Failed to download {url}")

python_pkg/download_cats/requirements.txt

@@ -0,0 +1,4 @@
+json
+os
+pathlib
+requests

python_pkg/extract_links/main.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Extract hosts from href attributes in an HTML file and write them as *host* per line.
+
+Usage:
+  python main.py INPUT_HTML [OUTPUT_TXT]
+
+If OUTPUT_TXT is not provided, the script writes to <INPUT_BASENAME>_links.txt
+alongside the input file.
+"""
+
+from __future__ import annotations
+
+import argparse
+from html.parser import HTMLParser
+import logging
+import os
+from urllib.parse import urlparse
+
+logging.basicConfig(level=logging.INFO)
+
+
+class _HrefParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__()
+        self.hrefs: list[str] = []
+
+    def handle_starttag(  # type: ignore[override]
+        self, _tag: str, attrs: list[tuple[str, str | None]]
+    ) -> None:
+        """Collect href attributes from start tags."""
+        for k, v in attrs:
+            if k.lower() == "href" and v is not None:
+                self.hrefs.append(v)
+
+
+def extract_hosts_from_html(html_text: str) -> list[str]:
+    """Parse HTML text, extract href values, and return a list of hostnames.
+
+    Rules:
+    - Only http/https URLs are considered.
+    - Output is the network location (host[:port]) without scheme or path.
+    - Duplicates are removed, preserving first-seen order.
+    """
+    parser = _HrefParser()
+    parser.feed(html_text)
+
+    seen: set[str] = set()
+    hosts: list[str] = []
+    for href in parser.hrefs:
+        parsed = urlparse(href)
+        if parsed.scheme in {"http", "https"} and parsed.netloc:
+            host = parsed.netloc
+            if host not in seen:
+                seen.add(host)
+                hosts.append(host)
+    return hosts
+
+
+def main() -> int:
+    """Parse command-line arguments and extract hosts from an HTML file."""
+    ap = argparse.ArgumentParser(
+        description="Extract hosts from hrefs in an HTML file."
+    )
+    ap.add_argument("input_html", help="Path to input HTML file")
+    ap.add_argument(
+        "output_txt",
+        nargs="?",
+        help=(
+            "Path to output text file "
+            "(defaults to <input_basename>_links.txt in the same directory)"
+        ),
+    )
+    args = ap.parse_args()
+
+    input_path = args.input_html
+    if not os.path.isfile(input_path):
+        msg = f"Input file not found: {input_path}"
+        raise SystemExit(msg)
+
+    out_path = args.output_txt
+    if not out_path:
+        base = os.path.splitext(os.path.basename(input_path))[0]
+        out_path = os.path.join(os.path.dirname(input_path), f"{base}_links.txt")
+
+    with open(input_path, encoding="utf-8", errors="ignore") as f:
+        html_text = f.read()
+
+    hosts = extract_hosts_from_html(html_text)
+
+    with open(out_path, "w", encoding="utf-8") as f:
+        f.writelines(f"*{host}*\n" for host in hosts)
+
+    logging.info(f"Wrote {len(hosts)} host(s) to {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

python_pkg/extract_links/pytest.ini

@@ -0,0 +1,2 @@
+[pytest]
+addopts = -q

python_pkg/extract_links/run.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Wrapper to run the extractor. Usage:
+#   ./run.sh path/to/input.html [output.txt]
+
+SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" &>/dev/null && pwd)
+
+if [[ $# -lt 1 || $# -gt 2 ]]; then
+  echo "Usage: $0 <input.html> [output.txt]" >&2
+  exit 1
+fi
+
+python3 "$SCRIPT_DIR/main.py" "$@"

python_pkg/extract_links/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for link extraction module."""

python_pkg/extract_links/tests/sample2.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+  <head>
+    <title>Sample 2</title>
+  </head>
+  <body>
+    <p>Links:</p>
+    <ul>
+      <li><a href="https://sub.domain.co.uk/path?x=1#y">Subdomain</a></li>
+      <li><a href="http://example.com:8080/with-port">Port</a></li>
+      <li><a href="//no-scheme.com/should-be-ignored">Protocol-relative (ignored)</a></li>
+      <li><a href="ftp://not-supported.com/ignore">FTP (ignored)</a></li>
+    </ul>
+  </body>
+</html>

python_pkg/extract_links/tests/test_main.py

@@ -0,0 +1,73 @@
+"""Unit tests for link extraction functionality."""
+
+from pathlib import Path
+import subprocess
+import sys
+
+# Allow importing from project root when running pytest from this folder
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+SCRIPT = ROOT / "main.py"
+
+
+def read_lines(p: Path) -> list[str]:
+    """Read lines from a file, stripping newlines."""
+    return [line.rstrip("\n") for line in p.read_text(encoding="utf-8").splitlines()]
+
+
+def test_extract_hosts_function() -> None:
+    """Test extract_hosts_from_html extracts unique hosts in order."""
+    from main import extract_hosts_from_html
+
+    html = (
+        '<a href="https://wiby.me/">A</a>'
+        '<a href="http://example.com/page">B</a>'
+        '<a href="#local">C</a>'
+        '<a href="mailto:foo@bar.com">D</a>'
+        '<a href="https://wiby.me/about">E</a>'
+    )
+    hosts = extract_hosts_from_html(html)
+    assert hosts == ["wiby.me", "example.com"], hosts
+
+
+def test_cli_writes_expected_output(tmp_path: Path) -> None:
+    """Test CLI writes correctly formatted output file."""
+    # copy sample1.html to tmpdir and run the script
+    sample = ROOT / "tests" / "sample1.html"
+    html_copy = tmp_path / "sample1.html"
+    html_copy.write_text(sample.read_text(encoding="utf-8"), encoding="utf-8")
+
+    # Run CLI
+    out_file = tmp_path / "out.txt"
+    subprocess.run(
+        [sys.executable, str(SCRIPT), str(html_copy), str(out_file)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert out_file.exists()
+
+    lines = read_lines(out_file)
+    # Expected order: first time we see wiby.me, then example.com
+    assert lines == ["*wiby.me*", "*example.com*"], lines
+
+
+def test_cli_default_output_name(tmp_path: Path) -> None:
+    """Test CLI generates default output filename from input."""
+    sample = ROOT / "tests" / "sample2.html"
+    html_copy = tmp_path / "sample2.html"
+    html_copy.write_text(sample.read_text(encoding="utf-8"), encoding="utf-8")
+
+    subprocess.run(
+        [sys.executable, str(SCRIPT), str(html_copy)],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+    default_out = tmp_path / "sample2_links.txt"
+    assert default_out.exists()
+
+    lines = read_lines(default_out)
+    assert lines == ["*sub.domain.co.uk*", "*example.com:8080*"], lines

python_pkg/keyboard_coop/README.md

@@ -0,0 +1,68 @@
+# Keyboard Coop Game
+
+A fun 2-player cooperative word game where players take turns selecting adjacent letters on a QWERTY keyboard to form valid words.
+
+## How to Play
+
+1. **Setup**: Two players take turns at the same computer
+2. **Turn System**: Player 1 starts by clicking any letter on the keyboard
+3. **Adjacent Rule**: The next player must click a letter that is adjacent to the previously selected letter
+4. **Word Formation**: Continue taking turns until you want to submit a word
+5. **Scoring**: Press ENTER to submit the word. Valid words score points exponentially based on length:
+   - 3 letters: 2 points
+   - 4 letters: 4 points
+   - 5 letters: 8 points
+   - 6 letters: 16 points
+   - And so on...
+
+## Game Rules
+
+- **Minimum Length**: Words must be at least 3 letters long
+- **Adjacency**: Letters must be adjacent on a standard QWERTY keyboard
+- **Valid Words**: Only dictionary words are accepted
+- **Cooperative**: Both players share the same score - work together!
+
+## Keyboard Adjacency
+
+Each key is adjacent to its neighbors (including diagonals). For example:
+
+- 'S' is adjacent to: Q, W, E, A, D, Z, X, C
+- 'F' is adjacent to: E, R, T, D, G, C, V, B
+
+## Controls
+
+- **Mouse Click**: Select letters and buttons
+- **ENTER Key**: Submit current word
+- **R Key**: Reset the game
+- **ENTER Button**: Submit current word (mouse)
+- **RESET Button**: Reset the game (mouse)
+
+## Installation
+
+1. Make sure you have Python 3.6+ installed
+2. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Run the game:
+   ```bash
+   python main.py
+   ```
+
+## Features
+
+- Visual QWERTY keyboard layout
+- Real-time adjacency highlighting
+- Turn-based gameplay with player indicators
+- Exponential scoring system
+- Built-in dictionary validation
+- Reset and restart functionality
+
+## Strategy Tips
+
+- Look for common word patterns and endings
+- Try to set up your partner for success
+- Longer words give exponentially more points
+- Remember that some letters have more adjacent options than others
+
+Enjoy playing together!

python_pkg/keyboard_coop/__init__.py

@@ -0,0 +1 @@
+"""Keyboard cooperation utilities package."""

python_pkg/keyboard_coop/main.py

@@ -0,0 +1,506 @@
+"""Keyboard cooperative word game using Pygame.
+
+Players take turns selecting adjacent keys to form valid English words.
+"""
+
+import json
+import logging
+import os
+import secrets
+import sys
+
+import pygame
+
+logging.basicConfig(level=logging.INFO)
+
+# Use cryptographically secure random number generator
+_rng = secrets.SystemRandom()
+
+# Initialize Pygame
+pygame.init()
+
+# Constants
+SCREEN_WIDTH = 1366
+SCREEN_HEIGHT = 768
+BACKGROUND_COLOR = (30, 30, 40)
+KEYBOARD_COLOR = (60, 60, 70)
+KEY_COLOR = (80, 80, 90)
+KEY_HOVER_COLOR = (100, 100, 110)
+KEY_SELECTED_COLOR = (150, 150, 200)
+KEY_AVAILABLE_COLOR = (100, 150, 100)
+TEXT_COLOR = (255, 255, 255)
+PLAYER_COLORS = [(255, 100, 100), (100, 100, 255)]
+MIN_WORD_LENGTH = 3
+
+# Keyboard layout
+KEYBOARD_LAYOUT = [
+    ["q", "w", "e", "r", "t", "y", "u", "i", "o", "p"],
+    ["a", "s", "d", "f", "g", "h", "j", "k", "l"],
+    ["z", "x", "c", "v", "b", "n", "m"],
+]
+
+# Key adjacency mapping
+KEY_ADJACENCY = {
+    "q": ["w", "a", "s"],
+    "w": ["q", "e", "a", "s", "d"],
+    "e": ["w", "r", "s", "d", "f"],
+    "r": ["e", "t", "d", "f", "g"],
+    "t": ["r", "y", "f", "g", "h"],
+    "y": ["t", "u", "g", "h", "j"],
+    "u": ["y", "i", "h", "j", "k"],
+    "i": ["u", "o", "j", "k", "l"],
+    "o": ["i", "p", "k", "l"],
+    "p": ["o", "l"],
+    "a": ["q", "w", "s", "z", "x"],
+    "s": ["q", "w", "e", "a", "d", "z", "x", "c"],
+    "d": ["w", "e", "r", "s", "f", "x", "c", "v"],
+    "f": ["e", "r", "t", "d", "g", "c", "v", "b"],
+    "g": ["r", "t", "y", "f", "h", "v", "b", "n"],
+    "h": ["t", "y", "u", "g", "j", "b", "n", "m"],
+    "j": ["y", "u", "i", "h", "k", "n", "m"],
+    "k": ["u", "i", "o", "j", "l", "m"],
+    "l": ["i", "o", "p", "k"],
+    "z": ["a", "s", "x"],
+    "x": ["a", "s", "d", "z", "c"],
+    "c": ["s", "d", "f", "x", "v"],
+    "v": ["d", "f", "g", "c", "b"],
+    "b": ["f", "g", "h", "v", "n"],
+    "n": ["g", "h", "j", "b", "m"],
+    "m": ["h", "j", "k", "n"],
+}
+
+
+class KeyboardCoopGame:
+    """Main game class for the keyboard cooperative word game."""
+
+    def __init__(self) -> None:
+        """Initialize the game window, fonts, and game state."""
+        self.screen = pygame.display.set_mode((SCREEN_WIDTH, SCREEN_HEIGHT))
+        pygame.display.set_caption("Keyboard Coop Game")
+        self.clock = pygame.time.Clock()
+        self.font = pygame.font.Font(None, 24)
+        self.large_font = pygame.font.Font(None, 32)
+        self.small_font = pygame.font.Font(None, 20)
+
+        # Load dictionary
+        self.dictionary = self.load_dictionary()
+
+        # Initialize game state
+        self.current_player = 0
+        self.current_word = ""
+        self.selected_letters = []
+        self.score = 0
+        self.game_over = False
+        self.message = "Player 1: Choose any letter to start!"
+
+        # Generate random keyboard layout and adjacency
+        self.generate_random_keyboard()
+
+        # Key positions
+        self.key_positions = self.calculate_key_positions()
+
+    def load_dictionary(self) -> set[str]:
+        """Load dictionary from words_dictionary.json file."""
+        try:
+            dictionary_path = os.path.join(
+                os.path.dirname(__file__), "words_dictionary.json"
+            )
+            with open(dictionary_path, encoding="utf-8") as f:
+                dictionary_data = json.load(f)
+            # Convert to set for faster lookup (we only need the keys)
+            return set(dictionary_data.keys())
+        except FileNotFoundError:
+            logging.warning(
+                "words_dictionary.json not found, using fallback dictionary"
+            )
+            # Fallback to a smaller dictionary if file not found
+            return {
+                "cat",
+                "dog",
+                "car",
+                "bat",
+                "rat",
+                "hat",
+                "mat",
+                "sat",
+                "fat",
+                "pat",
+                "the",
+                "and",
+                "for",
+                "are",
+                "but",
+                "not",
+                "you",
+                "all",
+                "can",
+                "had",
+                "her",
+                "was",
+                "one",
+                "our",
+                "out",
+                "day",
+                "get",
+                "has",
+                "him",
+                "his",
+                "how",
+                "man",
+                "new",
+                "now",
+                "old",
+                "see",
+                "two",
+                "way",
+                "who",
+                "boy",
+                "work",
+                "know",
+                "place",
+                "year",
+                "live",
+                "me",
+                "back",
+                "give",
+                "good",
+            }
+        except json.JSONDecodeError:
+            logging.warning(
+                "Error reading words_dictionary.json, using fallback dictionary"
+            )
+            return {
+                "cat",
+                "dog",
+                "car",
+                "bat",
+                "rat",
+                "hat",
+                "mat",
+                "sat",
+                "fat",
+                "pat",
+                "the",
+                "and",
+                "for",
+                "are",
+                "but",
+                "not",
+                "you",
+                "all",
+                "can",
+                "had",
+                "work",
+                "know",
+                "place",
+                "year",
+                "live",
+                "me",
+                "back",
+                "give",
+                "good",
+            }
+
+    def generate_random_keyboard(self) -> None:
+        """Generate a random keyboard layout and calculate adjacencies."""
+        # All 26 letters
+        all_letters = list("abcdefghijklmnopqrstuvwxyz")
+        _rng.shuffle(all_letters)
+
+        # Create random layout with same structure as QWERTY (10-9-7)
+        self.keyboard_layout = [
+            all_letters[0:10],  # Top row: 10 keys
+            all_letters[10:19],  # Middle row: 9 keys
+            all_letters[19:26],  # Bottom row: 7 keys
+        ]
+
+        # Update available letters
+        self.available_letters = set(all_letters)
+
+        # Calculate adjacencies based on new layout
+        self.calculate_adjacencies()
+
+    def calculate_adjacencies(self) -> None:
+        """Calculate adjacencies based on current keyboard layout."""
+        self.key_adjacency = {}
+
+        for row_idx, row in enumerate(self.keyboard_layout):
+            for col_idx, letter in enumerate(row):
+                adjacents = []
+
+                # Check all 8 directions (including diagonals)
+                directions = [
+                    (-1, -1),
+                    (-1, 0),
+                    (-1, 1),  # Above
+                    (0, -1),
+                    (0, 1),  # Same row
+                    (1, -1),
+                    (1, 0),
+                    (1, 1),  # Below
+                ]
+
+                for dr, dc in directions:
+                    new_row = row_idx + dr
+                    new_col = col_idx + dc
+
+                    # Check bounds
+                    if 0 <= new_row < len(self.keyboard_layout) and 0 <= new_col < len(
+                        self.keyboard_layout[new_row]
+                    ):
+                        adjacents.append(self.keyboard_layout[new_row][new_col])
+
+                self.key_adjacency[letter] = adjacents
+
+    def calculate_key_positions(self) -> dict[str, pygame.Rect]:
+        """Calculate the position of each key on screen."""
+        positions: dict[str, pygame.Rect] = {}
+        key_width = 60
+        key_height = 60
+        key_spacing = 8
+        start_x = 50
+        start_y = 320
+
+        for row_idx, row in enumerate(self.keyboard_layout):
+            row_offset = row_idx * 30  # Offset for layout
+            for col_idx, key in enumerate(row):
+                x = start_x + col_idx * (key_width + key_spacing) + row_offset
+                y = start_y + row_idx * (key_height + key_spacing)
+                positions[key] = pygame.Rect(x, y, key_width, key_height)
+
+        return positions
+
+    def get_key_at_position(self, pos: tuple[int, int]) -> str | None:
+        """Get the key at the given mouse position."""
+        for key, rect in self.key_positions.items():
+            if rect.collidepoint(pos):
+                return key
+        return None
+
+    def is_valid_move(self, letter: str) -> bool:
+        """Check if the letter is a valid move."""
+        if not self.selected_letters:
+            return True  # First move can be any letter
+
+        last_letter = self.selected_letters[-1]
+        return letter in self.key_adjacency[last_letter]
+
+    def is_valid_word(self, word: str) -> bool:
+        """Check if the word is in the dictionary."""
+        return word.lower() in self.dictionary
+
+    def calculate_score(self, word_length: int) -> int:
+        """Calculate score exponentially based on word length."""
+        if word_length < MIN_WORD_LENGTH:
+            return 0
+        return 2 ** (word_length - 2)
+
+    def handle_letter_click(self, letter: str) -> None:
+        """Handle clicking on a letter."""
+        if letter in self.available_letters and self.is_valid_move(letter):
+            self.selected_letters.append(letter)
+            self.current_word += letter
+
+            # Update available letters to include adjacent letters AND the same letter
+            adjacent_letters = (
+                set(self.key_adjacency[letter])
+                if letter in self.key_adjacency
+                else set()
+            )
+            adjacent_letters.add(letter)  # Allow selecting the same letter again
+            self.available_letters = adjacent_letters
+
+            # Switch player
+            self.current_player = 1 - self.current_player
+            self.message = (
+                f"Player {self.current_player + 1}: Choose an adjacent letter!"
+            )
+
+            # If no valid moves available, force word submission
+            if not self.available_letters:
+                self.submit_word()
+
+    def submit_word(self) -> None:
+        """Submit the current word and check if it's valid."""
+        if len(self.current_word) >= MIN_WORD_LENGTH and self.is_valid_word(
+            self.current_word
+        ):
+            points = self.calculate_score(len(self.current_word))
+            self.score += points
+            self.message = (
+                f"'{self.current_word}' is valid! +{points} points "
+                f"(Total: {self.score}) - New keyboard!"
+            )
+
+            # Randomize keyboard layout after scoring
+            self.generate_random_keyboard()
+            self.key_positions = self.calculate_key_positions()
+
+        elif len(self.current_word) < MIN_WORD_LENGTH:
+            self.message = (
+                f"'{self.current_word}' is too short! "
+                f"(minimum {MIN_WORD_LENGTH} letters)"
+            )
+        else:
+            self.message = f"'{self.current_word}' is not a valid word!"
+
+        # Reset for next word
+        self.current_word = ""
+        self.selected_letters = []
+        self.current_player = 0
+
+    def reset_game(self) -> None:
+        """Reset the game to initial state."""
+        self.current_player = 0
+        self.current_word = ""
+        self.selected_letters = []
+        self.score = 0
+        self.game_over = False
+        self.message = "Player 1: Choose any letter to start!"
+
+        # Generate new random keyboard layout
+        self.generate_random_keyboard()
+        self.key_positions = self.calculate_key_positions()
+
+    def draw_keyboard(self) -> None:
+        """Draw the virtual keyboard."""
+        mouse_pos = pygame.mouse.get_pos()
+
+        for letter, rect in self.key_positions.items():
+            # Determine key color
+            if letter in self.selected_letters:
+                color = KEY_SELECTED_COLOR
+            elif letter in self.available_letters:
+                color = KEY_AVAILABLE_COLOR
+            elif rect.collidepoint(mouse_pos) and letter in self.available_letters:
+                color = KEY_HOVER_COLOR
+            else:
+                color = KEY_COLOR
+
+            # Draw key
+            pygame.draw.rect(self.screen, color, rect)
+            pygame.draw.rect(self.screen, TEXT_COLOR, rect, 2)
+
+            # Draw letter
+            text = self.small_font.render(letter.upper(), True, TEXT_COLOR)
+            text_rect = text.get_rect(center=rect.center)
+            self.screen.blit(text, text_rect)
+
+    def draw_ui(self) -> tuple[pygame.Rect, pygame.Rect]:
+        """Draw the user interface."""
+        # Title
+        title = self.large_font.render("Keyboard Coop Game", True, TEXT_COLOR)
+        self.screen.blit(title, (30, 20))
+
+        # Current word
+        word_text = self.font.render(
+            f"Current Word: {self.current_word.upper()}", True, TEXT_COLOR
+        )
+        self.screen.blit(word_text, (30, 50))
+
+        # Score
+        score_text = self.font.render(f"Score: {self.score}", True, TEXT_COLOR)
+        self.screen.blit(score_text, (30, 75))
+
+        # Current player
+        player_color = PLAYER_COLORS[self.current_player]
+        player_text = self.font.render(
+            f"Current Player: {self.current_player + 1}", True, player_color
+        )
+        self.screen.blit(player_text, (30, 100))
+
+        # Message
+        message_text = self.font.render(self.message, True, TEXT_COLOR)
+        self.screen.blit(message_text, (30, 125))
+
+        # Instructions - Move to right side and make more compact
+        instructions = [
+            "Instructions:",
+            "• Take turns selecting adjacent letters",
+            "• Click letters or use keyboard to select",
+            "• Same letter can be selected consecutively",
+            "• Press ENTER to submit word (min 3 letters)",
+            "• Press R to reset game",
+            "• Score increases exponentially",
+            "• Keyboard randomizes after each valid word!",
+        ]
+
+        start_x = 750
+        for i, instruction in enumerate(instructions):
+            inst_text = self.small_font.render(instruction, True, TEXT_COLOR)
+            self.screen.blit(inst_text, (start_x, 20 + i * 22))
+
+        # Enter button - smaller and repositioned
+        enter_rect = pygame.Rect(750, 190, 120, 40)
+        pygame.draw.rect(self.screen, KEY_COLOR, enter_rect)
+        pygame.draw.rect(self.screen, TEXT_COLOR, enter_rect, 2)
+        enter_text = self.small_font.render("ENTER", True, TEXT_COLOR)
+        enter_text_rect = enter_text.get_rect(center=enter_rect.center)
+        self.screen.blit(enter_text, enter_text_rect)
+
+        # Reset button - smaller and repositioned
+        reset_rect = pygame.Rect(880, 190, 120, 40)
+        pygame.draw.rect(self.screen, KEY_COLOR, reset_rect)
+        pygame.draw.rect(self.screen, TEXT_COLOR, reset_rect, 2)
+        reset_text = self.small_font.render("RESET", True, TEXT_COLOR)
+        reset_text_rect = reset_text.get_rect(center=reset_rect.center)
+        self.screen.blit(reset_text, reset_text_rect)
+
+        return enter_rect, reset_rect
+
+    def handle_click(self, pos: tuple[int, int]) -> None:
+        """Handle mouse clicks."""
+        # Check if clicked on a key
+        key = self.get_key_at_position(pos)
+        if key:
+            self.handle_letter_click(key)
+
+        # Check UI buttons
+        enter_rect = pygame.Rect(750, 190, 120, 40)
+        reset_rect = pygame.Rect(880, 190, 120, 40)
+
+        if enter_rect.collidepoint(pos):
+            self.submit_word()
+        elif reset_rect.collidepoint(pos):
+            self.reset_game()
+
+    def run(self) -> None:
+        """Main game loop."""
+        running = True
+
+        while running:
+            for event in pygame.event.get():
+                if event.type == pygame.QUIT:
+                    running = False
+                elif event.type == pygame.MOUSEBUTTONDOWN:
+                    if event.button == 1:  # Left click
+                        self.handle_click(event.pos)
+                elif event.type == pygame.KEYDOWN:
+                    if event.key == pygame.K_RETURN:
+                        self.submit_word()
+                    elif event.key == pygame.K_r:
+                        self.reset_game()
+                    else:
+                        # Handle letter key presses
+                        key_name = pygame.key.name(event.key)
+                        if len(key_name) == 1 and key_name.isalpha():
+                            self.handle_letter_click(key_name.lower())
+
+            # Clear screen
+            self.screen.fill(BACKGROUND_COLOR)
+
+            # Draw everything
+            self.draw_keyboard()
+            self.draw_ui()
+
+            # Update display
+            pygame.display.flip()
+            self.clock.tick(60)
+
+        pygame.quit()
+        sys.exit()
+
+
+if __name__ == "__main__":
+    game = KeyboardCoopGame()
+    game.run()

python_pkg/keyboard_coop/requirements.txt

@@ -0,0 +1 @@
+pygame==2.1.3

python_pkg/keyboard_coop/run_game.sh

@@ -0,0 +1,3 @@
+#!/bin/bash
+cd "$(dirname "$0")" || exit 1
+python main.py

python_pkg/lichess_bot/.bot_version

@@ -0,0 +1 @@
+43

python_pkg/lichess_bot/README.md

@@ -0,0 +1,74 @@
+# Lichess Bot (minimal)
+
+A small Lichess BOT that accepts standard challenges and plays quick random legal moves using python-chess. It demonstrates the Lichess Board API basics with a simple, readable implementation.
+
+## Features
+
+- Connects to Lichess Board API via streaming NDJSON
+- Accepts only standard chess challenges (bullet/blitz/rapid/classical)
+- Spawns a thread per active game
+- Plays random legal moves (swap in a stronger engine later)
+- Simple logging and basic retries on transient network errors
+
+## Requirements
+
+- Python 3.9+
+- A Lichess account that is activated as a BOT
+- A Lichess API access token with at least the scopes:
+  - bot:play
+  - challenge:read
+  - challenge:write
+
+Install dependencies:
+
+```bash
+pip install -r PYTHON/lichess_bot/requirements.txt
+```
+
+## Activate BOT and get a token
+
+1. Create or use an existing Lichess account for your bot.
+2. Activate it as a BOT (one-time): https://lichess.org/api#tag/Bot
+   - If not already BOT, you need to convert the account; follow Lichess docs.
+3. Create a personal API token: https://lichess.org/account/oauth/token/create
+   - Grant scopes: bot:play, challenge:read, challenge:write
+
+Export the token in your shell (recommended):
+
+```bash
+export LICHESS_TOKEN="your_bot_token_here"
+```
+
+## Run
+
+From the repo root:
+
+```bash
+python -m PYTHON.lichess_bot.main
+```
+
+Optional flags:
+
+- `--log-level INFO|DEBUG|WARNING|ERROR` (default: INFO)
+- `--decline-correspondence` (declines correspondence challenges)
+
+You can also use the helper script:
+
+```bash
+bash PYTHON/lichess_bot/run.sh
+```
+
+## Notes
+
+- The engine is intentionally weak (random moves). Swap it with a UCI engine or implement a better search in `engine.py`.
+- Network calls hit real Lichess endpoints. Keep the bot polite; respect rate limits.
+
+## Development
+
+- Small unit tests are in `tests/` and only cover local helpers (no network). Run:
+
+```bash
+python -m pytest PYTHON/lichess_bot/tests -q
+```
+
+If you add tests requiring third-party packages, install them in your environment first.

python_pkg/lichess_bot/__init__.py

@@ -0,0 +1,3 @@
+"""Package marker for lichess_bot."""
+
+__all__ = []

python_pkg/lichess_bot/engine.py

@@ -0,0 +1,165 @@
+"""Chess engine wrapper for the C-based random/scoring engine."""
+
+import contextlib
+import json
+import logging
+import os
+import subprocess
+
+import chess
+
+
+class RandomEngine:
+    """Thin wrapper around the C engine in C/lichess_random_engine/random_engine.
+
+    Contract:
+    - Given a chess.Board, call the C binary with all legal moves encoded as
+      UCI (with optional annotations in the future). The binary prints the
+      chosen move's UCI on stdout (or JSON when --explain, which we don't need).
+    - We do not compute or rank anything in Python; we just pass through moves
+      and play exactly what the engine returns.
+    - If the binary is missing or returns an invalid/illegal move, raise.
+    """
+
+    def __init__(
+        self,
+        *,
+        engine_path: str | None = None,
+        max_time_sec: float = 2.0,
+        depth: int | None = None,
+    ) -> None:
+        """Initialize the engine wrapper with path and time settings."""
+        self.max_time_sec = max_time_sec
+        # depth is accepted for compatibility with existing callers but is unused;
+        # the C engine handles its own scoring/selection.
+        self.depth = depth
+        # Default relative path inside this repo
+        default_path = os.path.abspath(
+            os.path.join(
+                os.path.dirname(__file__),
+                "..",
+                "..",
+                "C",
+                "lichess_random_engine",
+                "random_engine",
+            )
+        )
+        self.engine_path = engine_path or default_path
+        if not os.path.isfile(self.engine_path) or not os.access(
+            self.engine_path, os.X_OK
+        ):
+            msg = (
+                f"C engine not found or not executable at '{self.engine_path}'. "
+                "Build it first (make -C C/lichess_random_engine)."
+            )
+            raise FileNotFoundError(msg)
+
+    def _call_engine(self, args: list[str], *, timeout: float) -> str:
+        try:
+            proc = subprocess.run(
+                [self.engine_path, *args],
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=True,
+            )
+        except subprocess.CalledProcessError as e:
+            stderr = (e.stderr or "").strip()
+            msg = f"C engine failed: {stderr or e}"
+            raise RuntimeError(msg) from e
+        except subprocess.TimeoutExpired as e:
+            msg = "C engine timed out"
+            raise TimeoutError(msg) from e
+        return (proc.stdout or "").strip()
+
+    def choose_move(self, board: chess.Board) -> chess.Move:
+        """Choose a move for the given board position."""
+        mv, _ = self.choose_move_with_explanation(
+            board, time_budget_sec=self.max_time_sec
+        )
+        return mv
+
+    def choose_move_with_explanation(
+        self, board: chess.Board, *, time_budget_sec: float
+    ) -> tuple[chess.Move | None, str]:
+        """Choose a move and return explanation for the decision."""
+        # Collect legal moves and send to engine as plain UCI tokens.
+        legal = list(board.legal_moves)
+        if not legal:
+            return None, "no_legal_moves"
+
+        args = ["--fen", board.fen()] + [m.uci() for m in legal]
+        # Optionally pass a seed for reproducibility when desired;
+        # keep default behavior otherwise.
+        # We deliberately avoid adding annotations here per request.
+
+        output = self._call_engine(args, timeout=max(0.1, time_budget_sec))
+
+        # The engine, without --explain, should print the chosen UCI.
+        chosen_uci = output.splitlines()[-1].strip() if output else ""
+        try:
+            move = chess.Move.from_uci(chosen_uci)
+        except Exception:
+            msg = f"Engine returned invalid move: '{chosen_uci}' (output: {output!r})"
+            raise RuntimeError(msg) from None
+
+        if move not in board.legal_moves:
+            msg = f"Engine returned illegal move for position: {chosen_uci}"
+            raise RuntimeError(msg)
+
+        return move, "from_c_engine"
+
+    def evaluate_proposed_move_with_suggestion(
+        self,
+        board: chess.Board,
+        proposed_move_uci: str,
+        *,
+        time_budget_sec: float,
+    ) -> tuple[float, str, chess.Move | None, str]:
+        """Ask the C engine to explain and analyze a specific candidate.
+
+        Returns (candidate_score, candidate_expl, best_move, best_expl)
+        where explanations are concise JSON snippets from the engine. All logic is
+        delegated to the C binary; no scoring is done in Python.
+        """
+        legal = list(board.legal_moves)
+        if not legal:
+            return 0.0, "no_legal_moves", None, "no_best_move"
+
+        args = ["--fen", board.fen(), "--explain", "--analyze", proposed_move_uci] + [
+            m.uci() for m in legal
+        ]
+        out = self._call_engine(args, timeout=max(0.1, time_budget_sec))
+
+        # Try to parse the engine's JSON explanation
+        cand_score = 0.0
+        best_move: chess.Move | None = None
+        cand_expl = out
+        best_expl = out
+        try:
+            data = json.loads(out)
+            # candidate score if provided
+            analyze = data.get("analyze") or {}
+            cs = analyze.get("candidate_score")
+            if isinstance(cs, int | float):
+                cand_score = float(cs)
+            # best move
+            chosen = data.get("chosen_move")
+            if isinstance(chosen, str):
+                with contextlib.suppress(Exception):
+                    bm = chess.Move.from_uci(chosen)
+                    if bm in board.legal_moves:
+                        best_move = bm
+            # Store compact explanations for debugging
+            cand_expl = json.dumps(analyze, ensure_ascii=False)
+            best_expl = json.dumps(
+                {
+                    "chosen_index": data.get("chosen_index"),
+                    "chosen_move": data.get("chosen_move"),
+                },
+                ensure_ascii=False,
+            )
+        except Exception:
+            logging.debug("Failed to parse engine JSON output")
+
+        return cand_score, cand_expl, best_move, best_expl

python_pkg/lichess_bot/lichess_api.py

@@ -0,0 +1,189 @@
+"""Lichess API client for bot interactions."""
+
+from collections.abc import Generator
+import contextlib
+from http import HTTPStatus
+import json
+import logging
+import time
+
+import chess
+import requests
+
+LICHESS_API = "https://lichess.org"
+
+
+class LichessAPI:
+    """Client for interacting with the Lichess Bot API."""
+
+    def __init__(self, token: str, session: requests.Session | None = None) -> None:
+        """Initialize the API client with authentication token."""
+        self.token = token
+        self.session = session or requests.Session()
+        self.session.headers.update(
+            {
+                "Authorization": f"Bearer {self.token}",
+                "Accept": "application/json",
+                "User-Agent": "minimal-lichess-bot/0.1 (+https://lichess.org)",
+            }
+        )
+
+    def _request(
+        self,
+        method: str,
+        url: str,
+        *,
+        raise_for_status: bool = False,
+        **kwargs: object,
+    ) -> requests.Response:
+        """Wrapper around session.request that logs every request/response.
+
+        - Logs start (method+URL) and end (status, elapsed).
+        - On 4xx/5xx, logs a warning with a small snippet of the response body.
+        - Optionally raises for status.
+        """
+        t0 = time.monotonic()
+        logging.info(f"HTTP {method} {url} -> sending")
+        try:
+            r = self.session.request(method, url, **kwargs)  # type: ignore[arg-type]
+        except Exception:
+            logging.exception(f"HTTP {method} {url} -> exception")
+            raise
+        elapsed = time.monotonic() - t0
+        status = r.status_code
+        if status >= HTTPStatus.BAD_REQUEST:
+            # Log a brief error body snippet if available
+            snippet = None
+            try:
+                text = r.text or ""
+                snippet = text[:200].replace("\n", " ")
+            except Exception:
+                snippet = None
+            if snippet:
+                logging.warning(
+                    f"HTTP {method} {url} -> {status} "
+                    f"in {elapsed:.2f}s body='{snippet}'"
+                )
+            else:
+                logging.warning(f"HTTP {method} {url} -> {status} in {elapsed:.2f}s")
+        else:
+            logging.info(f"HTTP {method} {url} -> {status} in {elapsed:.2f}s")
+        if raise_for_status:
+            r.raise_for_status()
+        return r
+
+    def stream_events(self) -> Generator[dict, None, None]:
+        """Stream incoming events (challenges, game starts, etc.)."""
+        url = f"{LICHESS_API}/api/stream/event"
+        backoff = 0.5
+        while True:
+            try:
+                # Use NDJSON Accept and no timeout for long-lived stream
+                headers = {"Accept": "application/x-ndjson"}
+                with self._request(
+                    "GET", url, headers=headers, stream=True, timeout=None
+                ) as r:
+                    r.raise_for_status()
+                    backoff = 0.5  # reset on success
+                    for line in r.iter_lines(decode_unicode=True):
+                        if not line:
+                            continue
+                        try:
+                            yield json.loads(line)
+                        except json.JSONDecodeError:
+                            logging.debug(f"Skipping non-JSON line: {line}")
+            except requests.HTTPError as e:
+                status = getattr(e.response, "status_code", None)
+                if status == HTTPStatus.TOO_MANY_REQUESTS:
+                    logging.warning("Event stream hit 429; backing off")
+                    time.sleep(backoff)
+                    backoff = min(8.0, backoff * 2)
+                    continue
+                raise
+
+    def accept_challenge(self, challenge_id: str) -> None:
+        """Accept a challenge by its ID."""
+        url = f"{LICHESS_API}/api/challenge/{challenge_id}/accept"
+        self._request("POST", url, timeout=30, raise_for_status=True)
+
+    def decline_challenge(self, challenge_id: str, reason: str = "generic") -> None:
+        """Decline a challenge with an optional reason."""
+        url = f"{LICHESS_API}/api/challenge/{challenge_id}/decline"
+        data = {"reason": reason}
+        self._request("POST", url, data=data, timeout=30, raise_for_status=True)
+
+    def join_game_stream(
+        self, game_id: str, my_color: str | None
+    ) -> tuple[chess.Board, str]:
+        """Deprecated: use stream_game_events and parse initial state there."""
+        # Fallback to initial behavior for compatibility
+        url = f"{LICHESS_API}/api/board/game/stream/{game_id}"
+        board = chess.Board()
+        color = my_color or "white"
+        headers = {"Accept": "application/x-ndjson"}
+        with self._request("GET", url, headers=headers, stream=True, timeout=None) as r:
+            r.raise_for_status()
+            for line in r.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                try:
+                    event = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+                t = event.get("type")
+                if t == "gameFull":
+                    white_id = event["white"].get("id")
+                    black_id = event["black"].get("id")
+                    me = self.get_my_user_id()
+                    if me == white_id:
+                        color = "white"
+                    elif me == black_id:
+                        color = "black"
+                    state = event.get("state", {})
+                    moves = state.get("moves", "")
+                    if moves:
+                        for m in moves.split():
+                            with contextlib.suppress(Exception):
+                                board.push_uci(m)
+                    break
+        return board, color
+
+    def stream_game_events(self, game_id: str) -> Generator[dict, None, None]:
+        """Stream game state events for a specific game."""
+        url = f"{LICHESS_API}/api/board/game/stream/{game_id}"
+        headers = {"Accept": "application/x-ndjson"}
+        with self._request("GET", url, headers=headers, stream=True, timeout=None) as r:
+            r.raise_for_status()
+            for line in r.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError:
+                    logging.debug(f"Skipping non-JSON line in game {game_id}: {line}")
+
+    def make_move(self, game_id: str, move: chess.Move) -> None:
+        """Submit a move to an active game."""
+        url = f"{LICHESS_API}/api/board/game/{game_id}/move/{move.uci()}"
+        r = self._request("POST", url, timeout=30)
+        if r.status_code in (HTTPStatus.BAD_REQUEST, HTTPStatus.CONFLICT):
+            # Likely not our turn or move already played; do not retry to avoid spam
+            r.raise_for_status()
+            return
+        if r.status_code == HTTPStatus.TOO_MANY_REQUESTS:
+            logging.warning(f"HTTP POST {url} -> 429; retrying once after 0.5s")
+            time.sleep(0.5)
+            r = self._request("POST", url, timeout=30)
+        r.raise_for_status()
+
+    def get_game_state(self, _game_id: str) -> dict | None:
+        """Deprecated: use stream_game_events in a persistent loop."""
+        return None
+
+    def get_my_user_id(self) -> str | None:
+        """Fetch the authenticated user's ID."""
+        url = f"{LICHESS_API}/api/account"
+        r = self._request("GET", url, timeout=30)
+        if r.status_code == HTTPStatus.OK:
+            return r.json().get("id")
+        return None

python_pkg/lichess_bot/main.py

@@ -0,0 +1,465 @@
+"""Main entry point for the Lichess bot."""
+
+import argparse
+import contextlib
+import datetime
+import json
+import logging
+import os
+import subprocess
+import sys
+import threading
+
+import chess
+import chess.pgn
+
+from python_pkg.lichess_bot.engine import RandomEngine
+from python_pkg.lichess_bot.lichess_api import LichessAPI
+from python_pkg.lichess_bot.utils import backoff_sleep, get_and_increment_version
+
+
+def run_bot(log_level: str = "INFO", *, decline_correspondence: bool = False) -> None:
+    """Start the bot and listen for incoming events."""
+    logging.basicConfig(
+        level=getattr(logging, log_level.upper(), logging.INFO),
+        format="[%(asctime)s] %(levelname)s %(threadName)s: %(message)s",
+    )
+
+    token = os.getenv("LICHESS_TOKEN")
+    if not token:
+        msg = "LICHESS_TOKEN environment variable is required"
+        raise RuntimeError(msg)
+
+    logging.info("Token present. Initializing client and engine...")
+    # Self-incrementing bot version (persisted on disk)
+    bot_version = get_and_increment_version()
+    logging.info(f"Bot version: v{bot_version}")
+    api = LichessAPI(token)
+    engine = RandomEngine()
+
+    game_threads = {}
+
+    def handle_game(game_id: str, my_color: str | None = None) -> None:
+        logging.info(f"Starting game thread for {game_id} [bot v{bot_version}]")
+        board = chess.Board()
+        color: str | None = my_color
+        # Track how many moves we have already processed;
+        # start at -1 so we act on the first state (0 moves)
+        last_handled_len = -1
+        # Prepare a per-game log file
+        game_log_path = os.path.join(os.getcwd(), f"lichess_bot_game_{game_id}.log")
+        try:
+            with open(game_log_path, "w") as lf:
+                lf.write(f"game {game_id} started\n")
+                lf.write(f"bot_version v{bot_version}\n")
+        except Exception:
+            game_log_path = None
+        # Simple time manager state
+        my_ms = None
+        opp_ms = None
+        inc_ms = 0
+        # Meta info for logging/PGN
+        game_date_iso: str | None = None
+        white_name: str | None = None
+        black_name: str | None = None
+        site_url: str | None = None
+        try:
+            # Only send moves on authoritative gameState events to avoid race
+            # conditions right after gameFull arrives.
+            for event in api.stream_game_events(game_id):
+                et = event.get("type")
+                if et in ("gameFull", "gameState"):
+                    # Determine moves list and optional status
+                    if et == "gameFull":
+                        state = event.get("state", {})
+                        moves = state.get("moves", "")
+                        status = state.get("status")
+                        # clocks are in milliseconds if present
+                        my_ms = (
+                            state.get("wtime")
+                            if color == "white"
+                            else state.get("btime")
+                        )
+                        opp_ms = (
+                            state.get("btime")
+                            if color == "white"
+                            else state.get("wtime")
+                        )
+                        inc_ms = state.get("winc") or state.get("binc") or 0
+                        # Discover my color from gameFull
+                        white_id = event["white"].get("id")
+                        black_id = event["black"].get("id")
+                        white_name = event["white"].get("name") or white_id or "?"
+                        black_name = event["black"].get("name") or black_id or "?"
+                        # Set site and date if available
+                        with contextlib.suppress(Exception):
+                            # Lichess event may include 'createdAt' ms epoch
+                            created_ms = event.get("createdAt") or event.get(
+                                "createdAtDate"
+                            )
+                            if created_ms:
+                                game_date_iso = datetime.datetime.fromtimestamp(
+                                    int(created_ms) / 1000, tz=datetime.timezone.utc
+                                ).strftime("%Y.%m.%d")
+                        site_url = f"https://lichess.org/{game_id}"
+                        me = api.get_my_user_id()
+                        if me == white_id:
+                            color = "white"
+                        elif me == black_id:
+                            color = "black"
+                        logging.info(f"Game {game_id}: joined as {color} (gameFull)")
+                    else:
+                        moves = event.get("moves", "")
+                        status = event.get("status")
+                        # update clocks from gameState if present
+                        if color == "white":
+                            my_ms = event.get("wtime", my_ms)
+                            opp_ms = event.get("btime", opp_ms)
+                            inc_ms = event.get("winc", inc_ms)
+                        elif color == "black":
+                            my_ms = event.get("btime", my_ms)
+                            opp_ms = event.get("wtime", opp_ms)
+                            inc_ms = event.get("binc", inc_ms)
+
+                    moves_list = moves.split() if moves else []
+                    new_len = len(moves_list)
+                    logging.info(
+                        f"Game {game_id}: event={et}, moves={new_len}, color={color}"
+                    )
+                    if new_len == last_handled_len:
+                        logging.debug(
+                            f"Game {game_id}: position unchanged "
+                            f"(len={new_len}), skipping"
+                        )
+                        continue
+
+                    # Rebuild board from moves
+                    board = chess.Board()
+                    for m in moves_list:
+                        try:
+                            board.push_uci(m)
+                        except Exception:
+                            logging.debug(f"Game {game_id}: could not apply move {m}")
+
+                    if color is None:
+                        logging.info(
+                            f"Game {game_id}: color unknown yet; waiting for gameFull"
+                        )
+                        # Do not mark this position handled on gameFull;
+                        # wait for authoritative gameState
+                        if et == "gameState":
+                            last_handled_len = new_len
+                        continue
+
+                    is_white_turn = board.turn
+                    my_turn = (is_white_turn and color == "white") or (
+                        (not is_white_turn) and color == "black"
+                    )
+                    logging.info(
+                        f"Game {game_id}: "
+                        f"turn={'white' if is_white_turn else 'black'}, "
+                        f"my_turn={my_turn}"
+                    )
+                    # Move policy:
+                    # - Always move on 'gameState' (authoritative)
+                    # - Also allow moving on the initial 'gameFull' when there are
+                    #   zero moves and it's our turn. This avoids stalling at game
+                    #   start when Lichess doesn't immediately send a 'gameState'
+                    #   for 0 moves.
+                    allow_move = (et == "gameState") or (
+                        et == "gameFull" and new_len == 0
+                    )
+                    if my_turn and allow_move:
+                        # Compute a per-move time budget (seconds) based on
+                        # remaining time.
+                        # Heuristic: use min( max_time_sec,
+                        #   max(0.05, 0.6 * my_time_left/remaining_moves + inc) )
+                        # Estimate remaining moves as 30 - ply/2 bounded to [10, 60]
+                        est_moves_left = max(
+                            10, min(60, 30 - board.fullmove_number // 2)
+                        )
+                        time_left_sec = (my_ms or 0) / 1000.0
+                        inc_sec = (inc_ms or 0) / 1000.0
+                        budget = (
+                            0.6 * (time_left_sec / max(1, est_moves_left))
+                            + 0.5 * inc_sec
+                        )
+                        # Spend more time per move (requested): double the budget
+                        budget *= 2.0
+                        # Keep within reasonable bounds
+                        budget = max(0.05, min(engine.max_time_sec, budget))
+                        move, reason = engine.choose_move_with_explanation(
+                            board, time_budget_sec=budget
+                        )
+                        if move is None:
+                            logging.info(
+                                f"Game {game_id}: no legal moves (game likely over)"
+                            )
+                            break
+                        try:
+                            # Double-check legality just before sending
+                            # to avoid 400s when state changed.
+                            if move not in board.legal_moves:
+                                logging.info(
+                                    f"Game {game_id}: selected move "
+                                    "no longer legal; skipping send"
+                                )
+                            else:
+                                logging.info(
+                                    f"Game {game_id}: playing {move.uci()} "
+                                    f"(budget={budget:.2f}s, "
+                                    f"my_time_left={time_left_sec:.1f}s, "
+                                    f"inc={inc_sec:.2f}s)"
+                                )
+                                if game_log_path:
+                                    with open(game_log_path, "a") as lf:
+                                        lf.write(
+                                            f"ply {last_handled_len + 1}: "
+                                            f"{move.uci()}\n{reason}\n\n"
+                                        )
+                                api.make_move(game_id, move)
+                        except Exception as e:
+                            logging.warning(
+                                f"Game {game_id}: move {move.uci()} failed: {e}"
+                            )
+                    # Mark this position as handled on authoritative
+                    # gameState, or after we've actually attempted a move
+                    # (including the first move on gameFull len=0).
+                    if et == "gameState" or (my_turn and allow_move):
+                        last_handled_len = new_len
+                    if status in {"mate", "resign", "stalemate", "timeout", "draw"}:
+                        logging.info(f"Game {game_id} finished: {status}")
+                        break
+                elif et in {"chatLine", "opponentGone"}:
+                    continue
+        except Exception:
+            logging.exception(f"Game {game_id} thread error")
+        finally:
+            # On game end, write full PGN to the log file
+            try:
+                if game_log_path:
+                    game = chess.pgn.Game.from_board(board)
+                    # Record the bot version in the PGN headers
+                    with contextlib.suppress(Exception):
+                        game.headers["BotVersion"] = f"v{bot_version}"
+                        if site_url:
+                            game.headers["Site"] = site_url
+                        if game_date_iso:
+                            game.headers["Date"] = game_date_iso
+                        if white_name:
+                            game.headers["White"] = white_name
+                        if black_name:
+                            game.headers["Black"] = black_name
+                    with open(game_log_path, "a") as lf:
+                        lf.write("\nPGN:\n")
+                        exporter = chess.pgn.StringExporter(
+                            headers=True, variations=False, comments=False
+                        )
+                        lf.write(game.accept(exporter))
+                        lf.write("\n")
+                # After PGN is written, run analysis and save it
+                # to the same file (inserted before PGN)
+                if game_log_path:
+                    analysis_text: str | None = None
+                    try:
+                        analyze_script = os.path.join(
+                            os.path.dirname(os.path.dirname(__file__)),
+                            "stockfish_analysis",
+                            "analyze_chess_game.py",
+                        )
+                        if os.path.isfile(analyze_script):
+                            # Estimate total plies from the final board
+                            try:
+                                total_plies = len(board.move_stack)
+                            except Exception:
+                                total_plies = 0
+
+                            logging.info(
+                                f"Game {game_id}: starting post-game "
+                                f"analysis ({total_plies} plies)"
+                            )
+                            # Run analyzer unbuffered and stream output for progress
+                            proc = subprocess.Popen(
+                                [sys.executable, "-u", analyze_script, game_log_path],
+                                stdout=subprocess.PIPE,
+                                stderr=subprocess.PIPE,
+                                text=True,
+                                bufsize=1,
+                            )
+                            analyzed = 0
+                            lines: list[str] = []
+                            ply_line_re = __import__("re").compile(r"^\s*(\d+)\s")
+                            # Read stdout line by line
+                            # stdout/stderr are guaranteed non-None with PIPE
+                            assert proc.stdout is not None  # noqa: S101
+                            assert proc.stderr is not None  # noqa: S101
+                            for line in proc.stdout:
+                                lines.append(line)
+                                m = ply_line_re.match(line)
+                                if m:
+                                    # Count as one analyzed ply
+                                    analyzed += 1
+                                    left = (
+                                        max(0, (total_plies or 0) - analyzed)
+                                        if total_plies
+                                        else "?"
+                                    )
+                                    if total_plies:
+                                        pct = analyzed / total_plies * 100.0
+                                        logging.info(
+                                            f"Game {game_id}: analysis progress "
+                                            f"{analyzed}/{total_plies} "
+                                            f"({pct:.0f}%), left {left}"
+                                        )
+                                    else:
+                                        logging.info(
+                                            f"Game {game_id}: analysis progress "
+                                            f"{analyzed} plies (total unknown)"
+                                        )
+
+                            # Capture any remaining stderr and ensure process ends
+                            stderr_text = proc.stderr.read() or ""
+                            ret = proc.wait()
+                            analysis_text = "".join(lines)
+                            if ret != 0:
+                                logging.warning(
+                                    f"Game {game_id}: analysis script "
+                                    f"exited with code {ret}"
+                                )
+                                if stderr_text:
+                                    analysis_text += "\n[stderr]\n" + stderr_text
+                            logging.info(f"Game {game_id}: analysis complete")
+                        else:
+                            logging.info(
+                                f"Game {game_id}: analysis script not found "
+                                f"at {analyze_script}; skipping analysis"
+                            )
+                    except Exception as e:
+                        logging.debug(f"Game {game_id}: analysis run failed: {e}")
+
+                    # Insert analysis before the PGN section so future runs
+                    # can still parse PGN cleanly
+                    if analysis_text:
+                        try:
+                            with open(
+                                game_log_path, encoding="utf-8", errors="replace"
+                            ) as f:
+                                content = f.read()
+
+                            # Find the start of the 'PGN:' line
+                            insert_idx = 0
+                            p = content.find("\nPGN:\n")
+                            if p != -1:
+                                insert_idx = (
+                                    p + 1
+                                )  # start of the line after the preceding newline
+                            elif content.startswith("PGN:\n"):
+                                insert_idx = 0
+                            else:
+                                # If PGN marker not found (unexpected), append at end
+                                insert_idx = len(content)
+
+                            # Prepend meta information block for easier parsing later
+                            meta_lines = []
+                            if game_date_iso:
+                                meta_lines.append(f"Date: {game_date_iso}")
+                            if white_name or black_name:
+                                meta_lines.append(
+                                    f"Players: {white_name or '?'} "
+                                    f"vs {black_name or '?'}"
+                                )
+                            if meta_lines:
+                                meta_block = "\n".join(meta_lines) + "\n"
+                            else:
+                                meta_block = ""
+
+                            analysis_block = (
+                                (meta_block if meta_block else "")
+                                + "ANALYSIS:\n"
+                                + analysis_text.rstrip()
+                                + "\n\n"
+                            )
+                            new_content = (
+                                content[:insert_idx]
+                                + analysis_block
+                                + content[insert_idx:]
+                            )
+                            with open(game_log_path, "w", encoding="utf-8") as f:
+                                f.write(new_content)
+                        except Exception as e:
+                            logging.debug(
+                                f"Game {game_id}: could not write analysis to log: {e}"
+                            )
+            except Exception as e:
+                logging.debug(f"Game {game_id}: could not write PGN: {e}")
+            logging.info(f"Ending game thread for {game_id}")
+
+    # Main event stream: challenge and game start events
+    logging.info("Connecting to Lichess event stream. Waiting for challenges...")
+    backoff = 0
+    while True:
+        try:
+            for event in api.stream_events():
+                if event.get("type") == "challenge":
+                    challenge = event["challenge"]
+                    ch_id = challenge["id"]
+                    variant = challenge.get("variant", {}).get("key", "standard")
+                    speed = challenge.get("speed")
+                    perf_ok = speed in {"bullet", "blitz", "rapid", "classical"}
+                    not_corr = (
+                        challenge.get("speed") != "correspondence"
+                        or not decline_correspondence
+                    )
+                    if variant == "standard" and perf_ok and not_corr:
+                        logging.info(f"Accepting challenge {ch_id} ({speed})")
+                        api.accept_challenge(ch_id)
+                    else:
+                        logging.info(
+                            f"Declining challenge {ch_id} "
+                            f"(variant={variant}, speed={speed})"
+                        )
+                        api.decline_challenge(ch_id)
+
+                elif event.get("type") == "gameStart":
+                    game_id = event["game"]["id"]
+                    # Spin up a game thread
+                    if (
+                        game_id not in game_threads
+                        or not game_threads[game_id].is_alive()
+                    ):
+                        t = threading.Thread(
+                            target=handle_game, args=(game_id,), name=f"game-{game_id}"
+                        )
+                        t.daemon = True
+                        game_threads[game_id] = t
+                        t.start()
+
+                elif event.get("type") == "gameFinish":
+                    game_id = event["game"]["id"]
+                    logging.info(f"Game finished event: {game_id}")
+                else:
+                    logging.debug(f"Unhandled event: {json.dumps(event)}")
+            # If stream ends normally, reset backoff
+            backoff = 0
+        except Exception as e:
+            logging.warning(f"Event stream error: {e}")
+            backoff = backoff_sleep(backoff)
+
+
+def main() -> None:
+    """Parse arguments and run the Lichess bot."""
+    parser = argparse.ArgumentParser(description="Run a minimal Lichess bot")
+    parser.add_argument(
+        "--log-level", default="INFO", help="Logging level (default: INFO)"
+    )
+    parser.add_argument(
+        "--decline-correspondence",
+        action="store_true",
+        help="Decline correspondence challenges",
+    )
+    args = parser.parse_args()
+    run_bot(args.log_level, decline_correspondence=args.decline_correspondence)
+
+
+if __name__ == "__main__":
+    main()

python_pkg/lichess_bot/requirements.txt

@@ -0,0 +1,6 @@
+certifi>=2024.2.2
+chardet>=5.2.0
+idna>=3.7
+python-chess==1.999
+requests==2.32.3
+urllib3==2.2.3

python_pkg/lichess_bot/run.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve script directory and repo root
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/../.." && pwd)"
+
+# Load a local .env if present
+if [[ -f "$SCRIPT_DIR/.env" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$SCRIPT_DIR/.env"
+  set +a
+fi
+
+# Helper to persist the token to .env
+save_token() {
+  local env_file="$SCRIPT_DIR/.env"
+  # Keep other lines, remove existing LICHESS_TOKEN, then append new one
+  if [[ -f "$env_file" ]]; then
+    grep -v '^LICHESS_TOKEN=' "$env_file" > "$env_file.tmp" || true
+    printf 'LICHESS_TOKEN=%s\n' "$LICHESS_TOKEN" >> "$env_file.tmp"
+    mv "$env_file.tmp" "$env_file"
+  else
+    printf 'LICHESS_TOKEN=%s\n' "$LICHESS_TOKEN" > "$env_file"
+  fi
+  chmod 600 "$env_file" 2>/dev/null || true
+  echo "Saved token to $env_file"
+}
+
+# Optional: --token <TOKEN> to set for this run
+if [[ "${1:-}" == "--token" || "${1:-}" == "-t" ]]; then
+  if [[ "${2:-}" == "" ]]; then
+    echo "--token requires a value"
+    exit 2
+  fi
+  export LICHESS_TOKEN="$2"
+  shift 2
+fi
+
+# Ask for token if not set and export it for this run
+if [[ -z "${LICHESS_TOKEN:-}" ]]; then
+  printf "Paste your Lichess API token and press Enter: "
+  read -r token
+  export LICHESS_TOKEN="$token"
+  if [[ -z "$LICHESS_TOKEN" ]]; then
+    echo "No token provided. Aborting."
+    exit 1
+  fi
+  echo "Token received."
+  save_token
+else
+  # If token came from CLI or env, still persist so next run won't prompt
+  save_token
+fi
+
+# Choose python: prefer local venv
+PY="$SCRIPT_DIR/.venv/bin/python"
+if [[ ! -x "$PY" ]]; then
+  PY="python"
+fi
+
+cd "$REPO_ROOT"
+echo "Using Python: $PY"
+echo "Repository root: $REPO_ROOT"
+echo "Starting Lichess bot..."
+echo "Tip: Open another terminal to watch logs; press Ctrl+C here to stop."
+
+trap 'echo; echo "Stopping bot (Ctrl+C)."' INT
+"$PY" -m PYTHON.lichess_bot.main "$@"

python_pkg/lichess_bot/run_tests.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Directory of this script (lichess_bot module root)
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$ROOT_DIR"
+
+# Try to detect repo root (two levels up from PYTHON/lichess_bot)
+REPO_ROOT="$(cd "$ROOT_DIR/../.." 2>/dev/null && pwd)"
+
+# Prefer Python 3 if available
+if command -v python3 >/dev/null 2>&1; then
+  PY=python3
+else
+  PY=python
+fi
+
+echo "[run_tests] Base Python: $($PY -c 'import sys; print(sys.executable)')"
+
+# Create/use local virtual environment to avoid system-managed pip restrictions (PEP 668)
+VENV_DIR="$ROOT_DIR/.venv"
+if [[ ! -d "$VENV_DIR" ]]; then
+  echo "[run_tests] Creating virtual environment at $VENV_DIR"
+  $PY -m venv "$VENV_DIR"
+fi
+
+VENV_PY="$VENV_DIR/bin/python"
+echo "[run_tests] Venv Python: $($VENV_PY -c 'import sys; print(sys.executable)')"
+
+echo "[run_tests] Upgrading pip/setuptools/wheel"
+"$VENV_PY" -m pip install --upgrade pip setuptools wheel >/dev/null
+
+# Choose requirements file: prefer repo root, fallback to local
+REQ_FILE=""
+if [[ -f "$REPO_ROOT/requirements.txt" ]]; then
+  REQ_FILE="$REPO_ROOT/requirements.txt"
+elif [[ -f "$ROOT_DIR/requirements.txt" ]]; then
+  REQ_FILE="$ROOT_DIR/requirements.txt"
+fi
+
+if [[ -n "$REQ_FILE" ]]; then
+  echo "[run_tests] Installing requirements from $REQ_FILE"
+  "$VENV_PY" -m pip install -r "$REQ_FILE"
+else
+  echo "[run_tests] No requirements.txt found; proceeding without dependency install"
+fi
+
+# Ensure pytest is available in venv
+if ! "$VENV_PY" -c "import pytest" >/dev/null 2>&1; then
+  echo "[run_tests] Installing pytest"
+  "$VENV_PY" -m pip install pytest
+fi
+
+# Make project importable (module root and repo root)
+export PYTHONPATH="$ROOT_DIR:${REPO_ROOT:-$ROOT_DIR}:${PYTHONPATH:-}"
+
+TEST_PATH_REL="PYTHON/lichess_bot/tests"
+TEST_PATH_ABS="$REPO_ROOT/$TEST_PATH_REL"
+if [[ ! -d "$TEST_PATH_ABS" ]]; then
+  # Fallback if script moved and relative layout differs
+  if [[ -d "$ROOT_DIR/tests" ]]; then
+    TEST_PATH_ABS="$ROOT_DIR/tests"
+  else
+    echo "[run_tests] Test directory not found (tried: $TEST_PATH_ABS and $ROOT_DIR/tests)." >&2
+    exit 1
+  fi
+fi
+
+echo "[run_tests] Running pytest for $TEST_PATH_ABS"
+"$VENV_PY" -m pytest -q "$TEST_PATH_ABS" "$@"

python_pkg/lichess_bot/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for Lichess bot module."""

python_pkg/lichess_bot/tests/conftest.py

@@ -0,0 +1,22 @@
+import os
+from pathlib import Path
+import sys
+
+import pytest
+
+# Add repository root to sys.path so 'import python_pkg.*' works when running
+# pytest with a subdirectory as rootdir.
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../.."))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+
+
+def pytest_ignore_collect(collection_path: Path, _config: pytest.Config) -> bool | None:
+    """Ignore per-game blunder test files; keep only the unified one.
+
+    This lets us keep historical files in the repo without collecting them.
+    """
+    basename = collection_path.name
+    return bool(
+        basename.startswith("test_blunders_") and basename != "test_blunders_all.py"
+    )

python_pkg/lichess_bot/tests/test_puzzles.py

@@ -0,0 +1,75 @@
+"""Test the engine against Lichess puzzles."""
+
+import csv
+import os
+
+import chess
+import pytest
+
+from python_pkg.lichess_bot.engine import RandomEngine
+
+
+def _load_top_puzzles(csv_path: str, limit: int = 8) -> list[tuple[str, str]]:
+    """Return a list of (FEN, solution_moves_str) for the first `limit` rows in the CSV.
+
+    CSV columns: PuzzleId,FEN,Moves,...
+    """
+    puzzles: list[tuple[str, str]] = []
+    with open(csv_path, newline="", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            fen = row["FEN"].strip()
+            moves = row["Moves"].strip()
+            if fen and moves:
+                puzzles.append((fen, moves))
+            if len(puzzles) >= limit:
+                break
+    return puzzles
+
+
+@pytest.mark.parametrize(
+    ("fen", "moves_str"),
+    _load_top_puzzles(
+        os.path.join(os.path.dirname(__file__), "lichess_db_puzzle.csv"), limit=8
+    ),
+)
+def test_puzzle_engine_follow_solution(fen: str, moves_str: str) -> None:
+    """Verify the engine follows puzzle solutions correctly."""
+    board = chess.Board(fen)
+    eng = RandomEngine(max_time_sec=1.0)
+
+    # Moves are space-separated UCIs alternating sides
+    # starting from side-to-move in the FEN
+    solution_moves = moves_str.split()
+    for step, uci in enumerate(solution_moves, start=1):
+        # Engine move on this ply
+        mv, expl = eng.choose_move_with_explanation(board, time_budget_sec=0.5)
+        assert mv is not None, f"No move returned at step {step}.\nExplanation: {expl}"
+
+        # If engine move differs from solution, fail immediately
+        # but provide analysis of the correct move
+        if mv.uci() != uci:
+            # Ask the engine to analyze the correct move for debug
+            score_cp, proposed_expl, best_mv, best_expl = (
+                eng.evaluate_proposed_move_with_suggestion(
+                    board, uci, time_budget_sec=0.5
+                )
+            )
+            details = [
+                f"Puzzle failed at step {step}.",
+                f"FEN: {fen}",
+                f"Expected: {uci}",
+                f"Engine played: {mv.uci()}",
+                "--- engine explanation ---",
+                expl,
+                "--- analysis of expected move ---",
+                f"score_cp: {score_cp}",
+                proposed_expl,
+            ]
+            if best_mv is not None:
+                details.append("--- engine best move analysis ---")
+                details.append(best_expl)
+            pytest.fail("\n".join(details))
+
+        # Apply the move and continue
+        board.push(mv)

python_pkg/lichess_bot/tests/test_utils.py

@@ -0,0 +1,26 @@
+"""Tests for utility functions."""
+
+import pytest
+
+from python_pkg.lichess_bot.utils import backoff_sleep
+
+
+def test_backoff_sleep_increments_and_caps(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that backoff sleep increments and respects the cap."""
+    slept: list[float] = []
+
+    def fake_sleep(sec: float) -> None:
+        slept.append(sec)
+
+    monkeypatch.setattr("time.sleep", fake_sleep)
+
+    b = 0
+    b = backoff_sleep(b, base=0.1, cap=0.3)
+    b = backoff_sleep(b, base=0.1, cap=0.3)
+    b = backoff_sleep(b, base=0.1, cap=0.3)
+    assert b >= 1
+    assert len(slept) == 3
+    # Expected sleep values: first=0.1, second=0.2, third=0.3 (capped)
+    assert slept[0] == 0.1
+    assert slept[1] == 0.2
+    assert slept[2] == 0.3

python_pkg/lichess_bot/tests/test_versioning.py

@@ -0,0 +1,25 @@
+"""Tests for bot version management."""
+
+from pathlib import Path
+
+import pytest
+
+from python_pkg.lichess_bot.utils import get_and_increment_version
+
+
+def test_version_file_increments_and_persists(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """Test that version increments and persists to file."""
+    version_file = tmp_path / "version.txt"
+    monkeypatch.setenv("LICHESS_BOT_VERSION_FILE", str(version_file))
+
+    v1 = get_and_increment_version()
+    v2 = get_and_increment_version()
+
+    assert v1 == 1
+    assert v2 == 2
+
+    # Ensure it persisted
+    with open(version_file) as f:
+        assert f.read().strip() == "2"

python_pkg/lichess_bot/tools/generate_blunder_tests.py

@@ -0,0 +1,469 @@
+#!/usr/bin/env python3
+"""Generate pytest cases from one or more lichess analysis logs.
+
+Input: log files that contain a "Columns:" section and a "PGN:" section.
+We'll extract each row where class==Blunder, reconstruct the FEN of the
+position before the blunder, and the blunder move in UCI. Then we'll write
+parametrized pytest files that assert the engine does not pick that same
+blunder move from those positions.
+
+Where logs are loaded from:
+    - By default (no arguments), all logs in the "past_games" folder located
+        next to this script will be processed (files matching lichess_bot_game_*.log).
+    - If a single argument is provided and it's a file path, that file is used.
+    - If a single argument looks like a game id (e.g. OVmR29MI), the script will
+        look for past_games/lichess_bot_game_<gameid>.log next to this script.
+
+Usage examples:
+    # Process all logs in tools/past_games
+    python python_pkg/lichess_bot/tools/generate_blunder_tests.py
+
+    # Process a specific game by id from tools/past_games
+    python python_pkg/lichess_bot/tools/generate_blunder_tests.py OVmR29MI
+
+    # Process an explicit file path
+    python python_pkg/lichess_bot/tools/generate_blunder_tests.py \
+        /path/to/lichess_bot_game_xxxxx.log
+
+It will create files like:
+    python_pkg/lichess_bot/tests/test_blunders_<gameid>.py
+
+Dependencies: python-chess, pytest (already in requirements.txt)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import io
+import logging
+import os
+import re
+import sys
+
+import chess
+import chess.pgn
+
+logging.basicConfig(level=logging.INFO)
+
+# Expected columns in the log file:
+# ply, side, move, played_eval, best_eval, loss, class, best_suggestion
+EXPECTED_COLUMNS = 8
+
+
+@dataclass
+class Blunder:
+    """Data class representing a blunder move from analysis."""
+
+    ply: int
+    side: str  # 'W' or 'B'
+    san: str  # SAN of the played blunder
+    best_suggestion_san: str  # SAN of the best suggestion from log (mandatory)
+
+
+def parse_columns_for_blunders(text: str) -> list[Blunder]:
+    """Parse the Columns section of a log file to extract blunders."""
+    lines = text.splitlines()
+    # Find start of "Columns:" block
+    try:
+        idx = next(i for i, ln in enumerate(lines) if ln.strip().startswith("Columns:"))
+    except StopIteration:
+        return []
+
+    blunders: list[Blunder] = []
+    # Lines after header until a blank line or "PGN:" marker
+    for ln in lines[idx + 1 :]:
+        if not ln.strip():
+            break
+        if ln.strip().startswith("PGN:"):
+            break
+        # Expect lines starting with a move number
+        if not re.match(r"^\s*\d+\s+", ln):
+            continue
+        # Split by 2+ spaces to get columns
+        parts = re.split(r"\s{2,}", ln.strip())
+        # Expected columns:
+        # ply, side, move, played_eval, best_eval, loss, class, best_suggestion
+        if len(parts) < EXPECTED_COLUMNS:
+            continue
+        try:
+            ply = int(parts[0])
+        except ValueError:
+            continue
+        side = parts[1]
+        move_san = parts[2]
+        clazz = parts[6]
+        best_suggestion_san = parts[7].strip() if parts[7] else ""
+        if clazz == "Blunder":
+            # Require best suggestion to be provided; if it's missing, raise
+            if not best_suggestion_san:
+                msg = (
+                    f"Missing best_suggestion in Columns "
+                    f"for blunder row: ply={ply} side={side} "
+                    f"move={move_san}.\nRaw line: '{ln.strip()}'"
+                )
+                raise ValueError(msg)
+            blunders.append(
+                Blunder(
+                    ply=ply,
+                    side=side,
+                    san=move_san,
+                    best_suggestion_san=best_suggestion_san,
+                )
+            )
+    return blunders
+
+
+def extract_pgn(text: str) -> str | None:
+    """Extract the PGN block from a log file."""
+    # Extract the PGN block after a line that is exactly 'PGN:' or starts with it
+    m = re.search(r"^PGN:\s*$", text, flags=re.MULTILINE)
+    if not m:
+        return None
+    start = m.end()
+    pgn = text[start:].strip()
+    return pgn if pgn else None
+
+
+def san_list_from_game(game: chess.pgn.Game) -> list[str]:
+    """Extract the list of SAN moves from a PGN game."""
+    san_moves: list[str] = []
+    node = game
+    while node.variations:
+        node = node.variation(0)
+        san_moves.append(node.san())
+    return san_moves
+
+
+def fen_and_uci_for_blunders(
+    pgn_text: str, blunders: list[Blunder]
+) -> list[tuple[str, str, str, Blunder]]:
+    """Convert blunders to (FEN, UCI, best_UCI, Blunder) tuples."""
+    game = chess.pgn.read_game(io.StringIO(pgn_text))
+    if game is None:
+        msg = "Failed to parse PGN from log"
+        raise RuntimeError(msg)
+
+    main_sans = san_list_from_game(game)
+    results: list[tuple[str, str, str, Blunder]] = []
+    for bl in blunders:
+        # Reconstruct the board before this ply
+        board = game.board()
+        # plies are 1-based; apply moves up to ply-1
+        upto = max(0, bl.ply - 1)
+        for i in range(min(upto, len(main_sans))):
+            board.push_san(main_sans[i])
+        fen_before = board.fen()
+        # Parse the SAN blunder at this position to get UCI. If parse fails, skip.
+        try:
+            move = board.parse_san(bl.san)
+        except ValueError:
+            # Try to fall back to using the game's move at that ply if available
+            if bl.ply - 1 < len(main_sans):
+                try:
+                    move = board.parse_san(main_sans[bl.ply - 1])
+                except Exception:
+                    logging.debug("Skipping blunder: failed to parse fallback move")
+                    continue
+            else:
+                continue
+        # Parse best suggestion SAN to UCI in the same position;
+        # if it fails, skip this blunder
+        try:
+            best_move = board.parse_san(bl.best_suggestion_san)
+            best_uci = best_move.uci()
+        except Exception as e:
+            msg = (
+                f"Failed to parse best_suggestion SAN "
+                f"'{bl.best_suggestion_san}' at ply {bl.ply} "
+                f"side {bl.side} in position FEN: {fen_before}. "
+                f"Error: {e}"
+            )
+            raise ValueError(msg) from e
+        results.append((fen_before, move.uci(), best_uci, bl))
+    return results
+
+
+def ensure_unified_test_file(target_path: str) -> None:
+    """Create the unified test file skeleton if it doesn't exist."""
+    os.makedirs(os.path.dirname(target_path), exist_ok=True)
+    if os.path.exists(target_path):
+        return
+    # Create skeleton unified test file
+    with open(target_path, "w", encoding="utf-8") as f:
+        f.write(
+            """import os
+import sys
+import chess
+import pytest
+
+# Ensure repo root is importable when running pytest directly
+REPO_ROOT = os.path.dirname(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+)
+if REPO_ROOT not in sys.path:
+    sys.path.insert(0, REPO_ROOT)
+
+from python_pkg.lichess_bot.engine import RandomEngine  # noqa: E402
+
+BLUNDER_CASES = [
+]
+
+
+@pytest.mark.parametrize(
+    'fen,blunder_uci,label',
+    BLUNDER_CASES,
+    ids=[c[2] for c in BLUNDER_CASES],
+)
+def test_engine_avoids_logged_blunder(fen, blunder_uci, label):
+    board = chess.Board(fen)
+    eng = RandomEngine(depth=4, max_time_sec=1.2)
+    # Prefer explanation variant if available for better failure messages
+    move = None
+    explanation = ''
+    if hasattr(eng, 'choose_move_with_explanation'):
+        try:
+            mv, expl = eng.choose_move_with_explanation(board, time_budget_sec=1.2)
+            move, explanation = mv, expl or ''
+        except Exception:
+            move = eng.choose_move(board)
+    else:
+        move = eng.choose_move(board)
+    assert move is not None, 'Engine returned no move'
+    assert move in board.legal_moves, 'Engine move is illegal'
+    assert move.uci() != blunder_uci, (
+        f'Engine repeated blunder {blunder_uci} at {label}. '
+        f'Explanation: {explanation}'
+    )
+"""
+        )
+
+
+def append_cases_to_unified_test(
+    unified_path: str, cases: list[tuple[str, str, str, Blunder]]
+) -> int:
+    """Append new cases to BLUNDER_CASES in the unified test file, skipping duplicates.
+
+    Returns the number of cases actually appended.
+    """
+    ensure_unified_test_file(unified_path)
+    with open(unified_path, encoding="utf-8") as f:
+        content = f.read()
+
+    # Extract current cases as a set of (fen, uci) to de-duplicate
+    existing = set(
+        re.findall(
+            r"\(\"(.*?)\",\s*\"(.*?)\",\s*\"ply\d+_[WB]_[^\"]+\"\)\,?",
+            content,
+            flags=re.DOTALL,
+        )
+    )
+
+    lines = []
+    updated_existing = 0
+    for fen, uci, best_uci, bl in cases:
+        key = (fen, uci)
+        if key in existing:
+            # If a best move UCI is available, try to backfill
+            # or update it into the label
+            if best_uci:
+                side = "W" if bl.side == "W" else "B"
+                fen_re = re.escape(fen)
+                uci_re = re.escape(uci)
+                base_label = f"ply{bl.ply}_{side}_{uci}"
+                # Pattern A: no best suffix yet
+                pattern_no_best = (
+                    rf"\(\"{fen_re}\",\s*\"{uci_re}\","
+                    rf"\s*\"({re.escape(base_label)})\"\)"
+                )
+                # Pattern B: existing best suffix (whatever it is)
+                # replace it with the new best_uci
+                pattern_with_best = (
+                    rf"\(\"{fen_re}\",\s*\"{uci_re}\","
+                    rf"\s*\"({re.escape(base_label)}_best_[^\"]+)\"\)"
+                )
+                if re.search(pattern_no_best, content):
+                    content = re.sub(
+                        pattern_no_best,
+                        lambda m, lbl=base_label, bst=best_uci: m.group(0).replace(
+                            m.group(1), f"{lbl}_best_{bst}"
+                        ),
+                        content,
+                        count=1,
+                    )
+                    updated_existing += 1
+                elif re.search(pattern_with_best, content):
+                    content = re.sub(
+                        pattern_with_best,
+                        lambda m, lbl=base_label, bst=best_uci: m.group(0).replace(
+                            m.group(1), f"{lbl}_best_{bst}"
+                        ),
+                        content,
+                        count=1,
+                    )
+                    updated_existing += 1
+            continue
+        label = f"ply{bl.ply}_{'W' if bl.side == 'W' else 'B'}_{uci}"
+        # Encode the best move UCI in the label so tests can
+        # extract it without changing tuple shape
+        label += f"_best_{best_uci}"
+        lines.append(f'    ("{fen}", "{uci}", "{label}"),\n')
+
+    if not lines:
+        return 0
+
+    # Insert before closing bracket of BLUNDER_CASES into the possibly updated 'content'
+    new_content = re.sub(
+        r"BLUNDER_CASES\s*=\s*\[\n",
+        lambda m: m.group(0) + "".join(lines),
+        content,
+        count=1,
+    )
+
+    # Apply the changes (either updates to existing labels and/or appended lines)
+    with open(unified_path, "w", encoding="utf-8") as f:
+        f.write(new_content)
+    return len(lines) + updated_existing
+
+
+def _process_single_log(log_path: str) -> int:
+    """Process a single log file. Returns 0 on success, non-zero otherwise."""
+    base = os.path.basename(log_path)
+    result = _parse_and_extract_blunders(log_path, base)
+    if isinstance(result, int):
+        return result  # Error code
+
+    cases, game_id = result
+    # Always append to the unified test file
+    unified = os.path.join(
+        os.path.dirname(__file__), "..", "tests", "test_blunders_all.py"
+    )
+    unified = os.path.abspath(unified)
+    added = append_cases_to_unified_test(unified, cases)
+    logging.info(
+        f"Appended {added} new blunder checks to "
+        f"{os.path.relpath(unified)} (game {game_id})."
+    )
+    return 0
+
+
+def _parse_and_extract_blunders(
+    log_path: str, base: str
+) -> int | tuple[list[tuple[str, str, str, Blunder]], str]:
+    """Parse log file and extract blunder cases.
+
+    Returns error code or (cases, game_id).
+    """
+    text, err = _read_log_file(log_path)
+    if err is not None or text is None:
+        return err if err is not None else 2
+
+    blunders, err = _parse_blunders(text, base)
+    if err is not None or blunders is None:
+        return err if err is not None else 2
+
+    cases, err = _extract_cases(text, blunders, base)
+    if err is not None or cases is None:
+        return err if err is not None else 2
+
+    m = re.search(r"game_([A-Za-z0-9]+)\.log$", base)
+    game_id = m.group(1) if m else os.path.splitext(base)[0]
+    return cases, game_id
+
+
+def _read_log_file(log_path: str) -> tuple[str | None, int | None]:
+    """Read log file contents. Returns (text, None) or (None, error_code)."""
+    try:
+        with open(log_path, encoding="utf-8") as fh:
+            return fh.read(), None
+    except FileNotFoundError:
+        logging.exception(f"Log file not found: {log_path}")
+        return None, 2
+
+
+def _parse_blunders(text: str, base: str) -> tuple[list[Blunder] | None, int | None]:
+    """Parse blunders from text. Returns (blunders, None) or (None, error_code)."""
+    try:
+        blunders = parse_columns_for_blunders(text)
+    except Exception:
+        logging.exception(f"Error parsing Columns in {base}")
+        return None, 2
+    if not blunders:
+        logging.warning(f"No blunders found in Columns section: {base}")
+        return None, 1
+    return blunders, None
+
+
+def _extract_cases(
+    text: str, blunders: list[Blunder], base: str
+) -> tuple[list[tuple[str, str, str, Blunder]] | None, int | None]:
+    """Extract FEN/UCI cases from PGN. Returns (cases, None) or (None, error_code)."""
+    pgn_text = extract_pgn(text)
+    if not pgn_text:
+        logging.warning(f"No PGN section found: {base}")
+        return None, 1
+
+    try:
+        cases = fen_and_uci_for_blunders(pgn_text, blunders)
+    except Exception:
+        logging.exception(f"Error converting SAN to UCI in {base}")
+        return None, 2
+    if not cases:
+        logging.warning(f"Failed to reconstruct any blunder positions from PGN: {base}")
+        return None, 1
+    return cases, None
+
+
+def main(argv: list[str]) -> int:
+    """Process log files and generate blunder test cases."""
+    script_dir = os.path.dirname(__file__)
+    past_dir = os.path.abspath(os.path.join(script_dir, "past_games"))
+
+    # No argument: process all logs in past_games
+    if len(argv) == 1:
+        if not os.path.isdir(past_dir):
+            logging.error(f"No past_games directory found at {past_dir}")
+            return 2
+        logs = [
+            os.path.join(past_dir, name)
+            for name in os.listdir(past_dir)
+            if re.match(r"lichess_bot_game_[A-Za-z0-9]+\.log$", name)
+        ]
+        if not logs:
+            logging.warning(f"No logs found in {past_dir}")
+            return 1
+        # Sort by mtime ascending for determinism
+        logs.sort(key=lambda p: os.path.getmtime(p))
+        ok = 0
+        for lp in logs:
+            rc = _process_single_log(lp)
+            if rc == 0:
+                ok += 1
+        logging.info(
+            f"Processed {len(logs)} logs from {past_dir}, "
+            f"succeeded: {ok}, failed: {len(logs) - ok}"
+        )
+        return 0 if ok > 0 else 1
+
+    # One argument: game id or file path
+    arg = argv[1]
+    candidate_path = None
+    if os.path.isfile(arg):
+        candidate_path = arg
+    # Treat as game id, resolve within past_games
+    elif re.fullmatch(r"[A-Za-z0-9]+", arg):
+        candidate_path = os.path.join(past_dir, f"lichess_bot_game_{arg}.log")
+    else:
+        # Fallback: if it's a bare filename, try inside past_games
+        maybe = os.path.join(past_dir, arg)
+        if os.path.isfile(maybe):
+            candidate_path = maybe
+
+    if not candidate_path:
+        logging.info("Usage: generate_blunder_tests.py [<game_id>|</path/to/log>]")
+        return 2
+
+    return _process_single_log(candidate_path)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

python_pkg/lichess_bot/utils.py

@@ -0,0 +1,62 @@
+"""Utility functions for the Lichess bot."""
+
+import logging
+import os
+import time
+
+
+def _version_file_path() -> str:
+    """Return the path to the persistent bot version file.
+
+    Stored alongside this module as a simple text file containing an integer.
+    """
+    override = os.getenv("LICHESS_BOT_VERSION_FILE")
+    if override:
+        return override
+    return os.path.join(os.path.dirname(__file__), ".bot_version")
+
+
+def get_and_increment_version() -> int:
+    """Read the current bot version, increment it, persist, and return the new version.
+
+    If the version file doesn't exist or is invalid, starts from 0, then sets to 1.
+    """
+    path = _version_file_path()
+    current = 0
+    try:
+        with open(path) as f:
+            raw = f.read().strip()
+            if raw:
+                current = int(raw)
+    except Exception:
+        # Missing or unreadable file -> treat as version 0
+        current = 0
+
+    new_version = current + 1
+    try:
+        tmp_path = path + ".tmp"
+        with open(tmp_path, "w") as f:
+            f.write(str(new_version))
+        os.replace(tmp_path, path)
+    except Exception:
+        # As a fallback, try a direct write; failure is non-fatal to bot operation
+        try:
+            with open(path, "w") as f:
+                f.write(str(new_version))
+        except Exception:
+            logging.debug("Could not persist bot version to %s", path)
+
+    return new_version
+
+
+def backoff_sleep(current_backoff: int, base: float = 0.5, cap: float = 8.0) -> int:
+    """Sleep with exponential backoff. Returns the next backoff step.
+
+    - current_backoff: number of consecutive failures
+    - base: base delay in seconds
+    - cap: maximum delay in seconds
+    """
+    delay = min(cap, base * (2**current_backoff))
+    logging.info(f"Backing off for {delay:.1f}s")
+    time.sleep(delay)
+    return min(current_backoff + 1, 10)

python_pkg/mock_server/README.md

@@ -0,0 +1,54 @@
+# Simulate Connection Failure
+
+(it takes ≈ 1hr to get it working)
+
+Install: https://mitmproxy.org/ (install it the way they recommend for your OS, for Ubuntu specifically apt version is 4 main versions behind newest version)
+
+Run it using `mitmproxy`
+
+Run your webbrowser using `127.0.0.1:8080` as proxy
+on chromium-based browser it should be enough to do:
+`google-chrome --proxy-server=127.0.0.1:8080`
+
+Run `mitmweb`
+
+open 127.0.0.1:808**1**
+
+Click `File` in upper left corner and then `Install Certificates`
+
+You should get a list of Windows/Linux/macOS/Firefox with certificates and how to install them
+
+Install certificates using those instructions
+
+**important!** Go to your browser certificate settings and ensure that:
+
+1. mitmproxy certificate is imported
+2. **it is set to trusted**
+
+Now all of your network communication should go through mitmproxy, you can verify it by going to 127.0.0.1:808**1** and seeing constant flow of requests
+
+## What can we do with it?
+
+1. Install mitmproxy python library using pip
+
+`pip install mitmproxy`
+
+2. Copy and paste this “hello world”:
+
+```
+from mitmproxy import http
+
+def request(flow: http.HTTPFlow) -> None:
+    # Only intercept traffic to example.com
+    if "example.com" in flow.request.host:
+        flow.response = http.Response.make(
+            502,  # Bad Gateway status code
+            b"Simulated connection failure",
+            {"Content-Type": "text/plain"}
+        )
+
+```
+
+3. Run it: `mitmdump -s mitm_world.py`
+4. Go to [example.com](http://example.com)
+5. You should see “simulated connection failure” in plain text

python_pkg/mock_server/__init__.py

@@ -0,0 +1 @@
+"""Mock server package."""

python_pkg/mock_server/mock_server.py

@@ -0,0 +1,14 @@
+"""Mitmproxy addon to simulate connection failures."""
+
+from mitmproxy import http
+
+
+def request(flow: http.HTTPFlow) -> None:
+    """Intercept requests and simulate failures for specific hosts."""
+    # Only intercept traffic to example.com
+    if "example.com" in flow.request.host:
+        flow.response = http.Response.make(
+            502,  # Bad Gateway status code
+            b"Simulated connection failure",
+            {"Content-Type": "text/plain"},
+        )

python_pkg/mock_server/requirements.txt

@@ -0,0 +1,3 @@
+flask
+flask-cors
+mitmproxy

python_pkg/mock_server/run.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+mitmdump -s mock_server.py

python_pkg/randomize_numbers/__init__.py

@@ -0,0 +1 @@
+"""Random number utilities package."""

python_pkg/randomize_numbers/random_digits.py

@@ -0,0 +1,95 @@
+"""Randomize numbers by applying a random percentage variation."""
+
+import contextlib
+import logging
+import re
+import secrets
+import sys
+
+logging.basicConfig(level=logging.INFO)
+
+# Use cryptographically secure random number generator
+_rng = secrets.SystemRandom()
+
+DEFAULT_MIN_PERCENTAGE = 1
+DEFAULT_MAX_PERCENTAGE = 20
+
+
+def randomize_numbers(
+    numbers: list[float],
+    min_percentage: float = DEFAULT_MIN_PERCENTAGE,
+    max_percentage: float = DEFAULT_MAX_PERCENTAGE,
+) -> list[float]:
+    """Apply random percentage variation to a list of numbers."""
+    randomized_numbers = []
+    for number in numbers:
+        percentage = _rng.uniform(min_percentage, max_percentage) / 100
+        if _rng.choice([True, False]):
+            new_number = number + (number * percentage)
+        else:
+            new_number = number - (number * percentage)
+        randomized_numbers.append(new_number)
+    return randomized_numbers
+
+
+def parse_input(input_string: str) -> tuple[list[float], list[int]]:
+    """Parse a string of numbers and return floats with decimal counts."""
+    # Replace commas with dots and remove non-numeric characters
+    # except dots, commas, and digits
+    cleaned_input = re.sub(r"[^\d.,\s]", "", input_string).replace(",", ".")
+    # Split the cleaned input into individual numbers
+    number_strings = cleaned_input.split()
+    # Convert the number strings to floats
+    numbers: list[float] = []
+    decimal_counts: list[int] = []
+    for num in number_strings:
+        try:
+            float_num = float(num)
+            digits_count = len(num.split(".")[-1]) if "." in num else 0
+            numbers.append(float_num)
+            decimal_counts.append(digits_count)
+        except ValueError:
+            continue
+    return numbers, decimal_counts
+
+
+MIN_ARGS = 2
+
+if __name__ == "__main__":
+    if len(sys.argv) < MIN_ARGS:
+        logging.info(
+            "Usage: python random_digits.py <number1> <number2> ... "
+            "[min_percentage max_percentage]"
+        )
+        sys.exit(1)
+
+    input_string = " ".join(sys.argv[1:])
+    numbers, decimal_counts = parse_input(input_string)
+
+    if len(numbers) == 0:
+        logging.error("No valid numbers provided.")
+        sys.exit(1)
+
+    min_percentage = DEFAULT_MIN_PERCENTAGE
+    max_percentage = DEFAULT_MAX_PERCENTAGE
+
+    try:
+        if len(sys.argv) > len(numbers) + 1:
+            with contextlib.suppress(ValueError):
+                min_percentage = float(sys.argv[len(numbers) + 1])
+        if len(sys.argv) > len(numbers) + 2:
+            with contextlib.suppress(ValueError):
+                max_percentage = float(sys.argv[len(numbers) + 2])
+
+        randomized_numbers = randomize_numbers(numbers, min_percentage, max_percentage)
+        formatted_numbers = []
+        for i, num in enumerate(randomized_numbers):
+            format_str = f".{decimal_counts[i]}f"
+            formatted_numbers.append(float(format(num, format_str)))
+
+        logging.info(f"Original numbers: {numbers}")
+        logging.info(f"Randomized numbers: {formatted_numbers}")
+    except ValueError:
+        logging.exception("Error processing numbers")
+        logging.exception("Please provide valid numbers and percentages.")
+        sys.exit(1)

python_pkg/scrape_website/.gitignore

@@ -0,0 +1,63 @@
+# JPEG
+*.jpg
+*.jpeg
+*.jpe
+*.jif
+*.jfif
+*.jfi
+
+# JPEG 2000
+*.jp2
+*.j2k
+*.jpf
+*.jpx
+*.jpm
+*.mj2
+
+# JPEG XR
+*.jxr
+*.hdp
+*.wdp
+
+# Graphics Interchange Format
+*.gif
+
+# RAW
+*.raw
+
+# Web P
+*.webp
+
+# Portable Network Graphics
+*.png
+
+# Animated Portable Network Graphics
+*.apng
+
+# Multiple-image Network Graphics
+*.mng
+
+# Tagged Image File Format
+*.tiff
+*.tif
+
+# Scalable Vector Graphics
+*.svg
+*.svgz
+
+# Portable Document Format
+*.pdf
+
+# X BitMap
+*.xbm
+
+# BMP
+*.bmp
+*.dib
+
+# ICO
+*.ico
+
+# 3D Images
+*.3dm
+*.max

python_pkg/scrape_website/__init__.py

@@ -0,0 +1 @@
+"""Web scraping package."""

python_pkg/scrape_website/requirements.txt

@@ -0,0 +1,2 @@
+requests
+selenium

python_pkg/scrape_website/scrape_comics.py

@@ -0,0 +1,83 @@
+"""Download comic images from a website using Selenium."""
+
+import argparse
+import logging
+import os
+from urllib.parse import urlparse
+
+import requests
+from selenium import webdriver
+from selenium.webdriver.common.by import By
+
+logging.basicConfig(level=logging.INFO)
+
+REQUEST_TIMEOUT = 30  # seconds
+
+# Initialize argument parser to accept the website URL as an argument
+parser = argparse.ArgumentParser(description="Download images from a comic website.")
+parser.add_argument(
+    "url", type=str, help="The URL of the website to start downloading images from"
+)
+args = parser.parse_args()
+
+# Initialize WebDriver (Use the appropriate driver for your browser)
+driver = webdriver.Chrome()
+
+# Open the website from the passed argument
+url = args.url
+logging.info(f"Opening the website: {url}")
+driver.get(url)
+
+
+# A function to download images by URL
+def download_image(url: str) -> bool:
+    """Download an image from a URL and save it locally."""
+    # Extract image name from URL
+    image_name = os.path.basename(urlparse(url).path)
+
+    # Check if the image already exists
+    if os.path.exists(image_name):
+        logging.info(f"Image {image_name} already exists, skipping download.")
+        return False
+    logging.info(f"Downloading image from URL: {url}")
+    img_data = requests.get(url, timeout=REQUEST_TIMEOUT).content
+    with open(image_name, "wb") as handler:
+        handler.write(img_data)
+    logging.info(f"Image {image_name} downloaded successfully")
+    return True
+
+
+# No need to define a specific number of images now
+count = 1
+
+while True:
+    logging.info(f"Processing image {count}...")
+
+    # Find the image element by its ID
+    image_element = driver.find_element(By.ID, "cc-comic")
+
+    # Get the image URL from the 'src' attribute
+    image_url = image_element.get_attribute("src")
+    logging.info(f"Found image URL: {image_url}")
+
+    # Download the image if it doesn't already exist
+    if download_image(image_url):
+        count += 1  # Increment count only if the image was downloaded
+
+    # Try to find the 'Next' button by its class
+    try:
+        logging.info("Clicking the 'Next' button to load the next image...")
+        next_button = driver.find_element(By.CSS_SELECTOR, "a.cc-next")
+
+        # Navigate to the URL in the 'href' of the next button
+        next_button_url = next_button.get_attribute("href")
+        driver.get(next_button_url)
+
+    except Exception:
+        # If the 'Next' button is not found, it means we've reached the last image
+        logging.info("No 'Next' button found. Reached the end of images.")
+        break
+
+# Close the browser
+logging.info("All images processed, closing the browser.")
+driver.quit()

python_pkg/stockfish_analysis/README.md

@@ -0,0 +1,31 @@
+# Chess move analysis with Stockfish
+
+This utility parses a PGN (or a log that contains a PGN section) and evaluates each move with a local Stockfish engine, printing a per-move quality rating.
+
+## Install
+
+Install python dependencies:
+
+```
+pip install -r PYTHON/stockfish_analysis/requirements.txt
+```
+
+Ensure Stockfish is installed and available in your PATH (or provide the path via `--engine`). On Linux, you can typically install with your package manager or download a binary.
+
+## Run
+
+From the repo root:
+
+```
+python3 PYTHON/analyze_chess_game.py lichess_bot_game_8GSdY3Ci.log
+```
+
+Options:
+
+- `--engine /path/to/stockfish` to specify a custom engine path
+- `--time 0.2` seconds per evaluation (default)
+- `--depth 12` fixed depth instead of time
+
+The script prints a table with, for each ply:
+
+- side to move, SAN move, eval before/after from mover's POV, delta, classification, and Stockfish best move suggestion.

python_pkg/stockfish_analysis/analyze_chess_game.py

@@ -0,0 +1,637 @@
+#!/usr/bin/env python3
+"""Analyze a chess game's moves using a local Stockfish engine and rate each move.
+
+Usage:
+    python3 python_pkg/analyze_chess_game.py <path-to-file>
+        [--engine stockfish]
+        [--time 0.5 | --depth 20]
+        [--threads auto|N]
+        [--hash-mb auto|MB]
+        [--multipv N]
+        [--last-move-only]
+
+Notes:
+    - Requires python-chess. Install from python_pkg/stockfish_analysis/requirements.txt
+    - The input file can be a pure PGN or a log file containing a PGN section.
+    - The script tries to locate the PGN by looking for a 'PGN:' marker,
+      PGN tags '[...]', or a move list starting with '1.'.
+    - Stockfish is CPU-based; it doesn't use GPU VRAM. "Full power" here means
+      using many CPU threads and a large transposition table (Hash).
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import logging
+import multiprocessing
+import os
+import re
+import sys
+
+try:
+    import psutil  # type: ignore[import-untyped]
+except Exception:  # pragma: no cover - optional dependency; we fall back if unavailable
+    psutil = None  # type: ignore[assignment]
+
+try:
+    import chess
+    import chess.engine
+    import chess.pgn
+except Exception:  # pragma: no cover
+    logging.exception("Missing dependency. Please install python-chess:")
+    logging.exception("  pip install -r python_pkg/stockfish_analysis/requirements.txt")
+    raise
+
+# Memory configuration constants
+MEMINFO_PARTS_MIN = 2
+HIGH_THREAD_COUNT = 16
+
+
+def extract_pgn_text(raw: str) -> str | None:
+    """Try to extract a PGN block from a possibly noisy file.
+
+    Strategies tried in order:
+      1) Everything after a line that equals or starts with 'PGN:'
+      2) From the first PGN tag line '[' to the end
+      3) From the first line starting with an integer and a dot (e.g., '1.') to the end
+    """
+    lines = raw.splitlines()
+
+    # 1) After 'PGN:' marker
+    for i, line in enumerate(lines):
+        if line.strip().startswith("PGN:"):
+            # everything after this line
+            pgn = "\n".join(lines[i + 1 :]).strip()
+            if pgn:
+                return pgn
+
+    # 2) From first tag line
+    for i, line in enumerate(lines):
+        if line.strip().startswith("[") and "]" in line:
+            pgn = "\n".join(lines[i:]).strip()
+            if pgn:
+                return pgn
+
+    # 3) From first move number
+    move_start_re = re.compile(r"^\s*\d+\.")
+    for i, line in enumerate(lines):
+        if move_start_re.match(line):
+            pgn = "\n".join(lines[i:]).strip()
+            if pgn:
+                return pgn
+
+    return None
+
+
+def score_to_cp(
+    score: chess.engine.PovScore, *, pov_white: bool
+) -> tuple[int | None, int | None]:
+    """Return tuple (cp, mate_in) from a PovScore for the given POV color.
+
+    If it's a mate score, cp will be None and mate_in will be +/-N
+    (positive means mate for POV side). If it's a cp score, mate_in will be None.
+    """
+    pov = chess.WHITE if pov_white else chess.BLACK
+    s = score.pov(pov)
+    if s.is_mate():
+        mi = s.mate()
+        return None, mi
+    return s.score(mate_score=None), None
+
+
+# Centipawn loss thresholds for move quality classification (Lichess-like bands)
+CP_LOSS_BEST = 10
+CP_LOSS_EXCELLENT = 20
+CP_LOSS_GOOD = 50
+CP_LOSS_INACCURACY = 99
+CP_LOSS_MISTAKE = 299
+
+
+# Centipawn loss thresholds for move classification
+_CP_LOSS_BANDS = [
+    (CP_LOSS_BEST, "Best"),
+    (CP_LOSS_EXCELLENT, "Excellent"),
+    (CP_LOSS_GOOD, "Good"),
+    (CP_LOSS_INACCURACY, "Inaccuracy"),
+    (CP_LOSS_MISTAKE, "Mistake"),
+]
+
+
+def classify_cp_loss(cp_loss: int | None) -> str:
+    """Classify move quality using Lichess-like centipawn loss bands.
+
+    Loss is best_eval(cp) - played_eval(cp), from the mover's POV (positive is worse).
+    Bands (approx, widely cited):
+      - Best:    0..10 cp
+      - Excellent: 11..20 cp
+      - Good:    21..50 cp
+      - Inaccuracy: 51..99 cp
+      - Mistake: 100..299 cp
+      - Blunder: >=300 cp
+    """
+    if cp_loss is None:
+        return "Unknown"
+    for threshold, classification in _CP_LOSS_BANDS:
+        if cp_loss <= threshold:
+            return classification
+    return "Blunder"
+
+
+def fmt_eval(cp: int | None, mate_in: int | None) -> str:
+    """Format evaluation score as human-readable string."""
+    if mate_in is not None:
+        sign = "+" if mate_in > 0 else ""
+        return f"M{sign}{mate_in}"
+    if cp is None:
+        return "?"
+    # Convert cp to pawns with sign and 2 decimals
+    return f"{cp / 100.0:+.2f}"
+
+
+def _parse_threads(value: str) -> int | None:
+    v = value.strip().lower()
+    if v in ("auto", "max", ""):  # auto-detect
+        return None
+    try:
+        n = int(v)
+        return max(1, n)
+    except ValueError:
+        msg = "--threads must be an integer or 'auto'"
+        raise argparse.ArgumentTypeError(msg) from None
+
+
+def _parse_hash_mb(value: str) -> int | None:
+    v = value.strip().lower()
+    if v in ("auto", "max", ""):  # auto-detect
+        return None
+    try:
+        mb = int(v)
+        return max(16, mb)
+    except ValueError:
+        msg = "--hash-mb must be an integer (MB) or 'auto'"
+        raise argparse.ArgumentTypeError(msg) from None
+
+
+def _detect_total_mem_mb() -> int | None:
+    # Prefer psutil if available
+    if psutil is not None:
+        with contextlib.suppress(Exception):
+            return int(psutil.virtual_memory().total // (1024 * 1024))
+    # Fallback approach for Linux systems using proc meminfo.
+    with (
+        contextlib.suppress(Exception),
+        open("/proc/meminfo", encoding="utf-8", errors="ignore") as f,
+    ):
+        for line in f:
+            if line.startswith("MemTotal:"):
+                parts = line.split()
+                if len(parts) >= MEMINFO_PARTS_MIN and parts[1].isdigit():
+                    # Value is in kB
+                    kb = int(parts[1])
+                    return kb // 1024
+    return None
+
+
+def _auto_hash_mb(threads_wanted: int, engine_options: dict[str, object]) -> int:
+    total_mb = _detect_total_mem_mb() or 2048
+    # Heuristic: cap at 4 GiB by default; keep at most half of RAM; ensure >= 64MB
+    half_ram = max(64, total_mb // 2)
+    target = half_ram
+    # Respect engine "Hash" max if exposed
+    opt = engine_options.get("Hash")
+    max_allowed = None
+    try:
+        max_allowed = opt.max if opt is not None else None  # type: ignore[attr-defined]
+    except Exception:
+        max_allowed = None
+    if isinstance(max_allowed, int):
+        target = min(target, max_allowed)
+    # Some rough scaling: if very many threads, give a bit more (but not huge)
+    if threads_wanted >= HIGH_THREAD_COUNT:
+        target = min(target + 1024, (total_mb * 3) // 4)
+    return max(64, int(target))
+
+
+def main() -> None:
+    """Parse arguments and run chess game analysis."""
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    ap = argparse.ArgumentParser(
+        description="Analyze a chess game's moves with Stockfish and rate each move."
+    )
+    ap.add_argument("file", help="Path to a PGN file or a log containing a PGN section")
+    ap.add_argument(
+        "--engine",
+        default="stockfish",
+        help="Path to stockfish executable (default: stockfish)",
+    )
+    # Exactly one of time or depth may be provided; default to time
+    ap.add_argument(
+        "--time",
+        type=float,
+        default=0.5,
+        help="Analysis time per evaluation in seconds (default: 0.5)",
+    )
+    ap.add_argument(
+        "--depth",
+        type=int,
+        default=None,
+        help="Fixed depth per evaluation (overrides --time)",
+    )
+    # Performance knobs
+    ap.add_argument(
+        "--threads",
+        type=_parse_threads,
+        default=None,
+        metavar="auto|N",
+        help="Engine threads to use (default: auto = all logical cores)",
+    )
+    ap.add_argument(
+        "--hash-mb",
+        type=_parse_hash_mb,
+        default=None,
+        metavar="auto|MB",
+        help="Hash table size in MB (default: auto = up to half RAM, capped)",
+    )
+    ap.add_argument(
+        "--multipv",
+        type=int,
+        default=2,
+        help="Number of principal variations to compute (default: 1)",
+    )
+    ap.add_argument(
+        "--last-move-only",
+        action="store_true",
+        help=(
+            "Analyze only the last move of the main line "
+            "(reports its eval and the best move)"
+        ),
+    )
+    args = ap.parse_args()
+
+    if not os.path.isfile(args.file):
+        logging.error(f"Input not found: {args.file}")
+        sys.exit(1)
+
+    with open(args.file, encoding="utf-8", errors="replace") as f:
+        raw = f.read()
+
+    pgn_text = extract_pgn_text(raw)
+    if not pgn_text:
+        logging.error("Could not locate PGN text in the file.")
+        sys.exit(2)
+
+    game = chess.pgn.read_game(io.StringIO(pgn_text))
+    if game is None:
+        logging.error("Failed to parse PGN.")
+        sys.exit(3)
+
+    # Prepare engine
+    try:
+        engine = chess.engine.SimpleEngine.popen_uci([args.engine])
+    except FileNotFoundError:
+        logging.exception(f"Could not launch engine at: {args.engine}")
+        logging.exception(
+            "Ensure Stockfish is installed and in PATH, or specify with --engine."
+        )
+        sys.exit(4)
+
+    # Configure engine performance options if available
+    try:
+        options = engine.options  # type: ignore[attr-defined]
+    except Exception:
+        options = {}
+
+    # Threads
+    wanted_threads = (
+        args.threads if args.threads is not None else (multiprocessing.cpu_count() or 1)
+    )
+    # Respect engine bounds if present
+    if "Threads" in options:
+        try:
+            max_thr = getattr(options["Threads"], "max", None)
+            min_thr = getattr(options["Threads"], "min", 1)
+            if isinstance(max_thr, int):
+                wanted_threads = min(wanted_threads, max_thr)
+            if isinstance(min_thr, int):
+                wanted_threads = max(wanted_threads, min_thr)
+            engine.configure({"Threads": int(wanted_threads)})
+        except Exception:
+            logging.debug("Failed to configure Threads option")
+
+    # Configure hash table size in MB.
+    if "Hash" in options:
+        try:
+            if args.hash_mb is not None:
+                target_hash = int(args.hash_mb)
+            else:
+                target_hash = _auto_hash_mb(int(wanted_threads), options)
+            # Respect bounds
+            max_hash = getattr(options["Hash"], "max", None)
+            min_hash = getattr(options["Hash"], "min", 16)
+            if isinstance(max_hash, int):
+                target_hash = min(target_hash, max_hash)
+            if isinstance(min_hash, int):
+                target_hash = max(target_hash, min_hash)
+            engine.configure({"Hash": int(target_hash)})
+        except Exception:
+            logging.debug("Failed to configure Hash option")
+
+    # MultiPV
+    effective_mpv = max(1, int(args.multipv))
+    if "MultiPV" in options:
+        try:
+            max_mpv = getattr(options["MultiPV"], "max", None)
+            if isinstance(max_mpv, int):
+                effective_mpv = min(effective_mpv, max_mpv)
+            engine.configure({"MultiPV": int(effective_mpv)})
+        except Exception:
+            logging.debug("Failed to configure MultiPV option")
+
+    # Enable NNUE if the option exists
+    for nnue_key in ("Use NNUE", "UseNNUE"):
+        if nnue_key in options:
+            with contextlib.suppress(Exception):
+                engine.configure({nnue_key: True})
+
+    limit: chess.engine.Limit
+    if args.depth is not None:
+        limit = chess.engine.Limit(depth=args.depth)
+    else:
+        limit = chess.engine.Limit(time=max(0.05, args.time))
+
+    board = game.board()
+    logging.info("Game:")
+    white = game.headers.get("White", "White")
+    black = game.headers.get("Black", "Black")
+    result = game.headers.get("Result", "*")
+    logging.info(f"  {white} vs {black}  Result: {result}")
+    logging.info("")
+    logging.info(
+        "Columns: ply  side  move  played_eval  best_eval  loss  class  best_suggestion"
+    )
+    # Brief performance summary (best-effort)
+    try:
+        thr_show = int(wanted_threads)
+    except Exception:
+        thr_show = 1
+    try:
+        hash_show = (
+            int(engine.options.get("Hash").value)
+            if hasattr(engine, "options") and engine.options.get("Hash")
+            else None
+        )
+    except Exception:
+        hash_show = None
+    if hash_show is not None:
+        logging.info(
+            f"Using engine options: Threads={thr_show}, "
+            f"Hash={hash_show} MB, MultiPV={effective_mpv}"
+        )
+    else:
+        logging.info(
+            f"Using engine options: Threads={thr_show}, MultiPV={effective_mpv}"
+        )
+
+    ply = 1
+    try:
+        node = game
+
+        if args.last_move_only:
+            # Walk to the last move in the main line and analyze only that ply.
+            if not node.variations:
+                logging.warning("No moves found in the game.")
+            else:
+                while node.variations:
+                    move_node = node.variations[0]
+                    move = move_node.move
+                    mover_white = board.turn
+
+                    # If this is the final move in the mainline, analyze it and stop.
+                    if not move_node.variations:
+                        # Analyse current position to get engine best move suggestion
+                        info_root_raw = engine.analyse(
+                            board, limit=limit, multipv=effective_mpv
+                        )
+                        info_root = (
+                            info_root_raw[0]
+                            if isinstance(info_root_raw, list)
+                            else info_root_raw
+                        )
+                        best_move = None
+                        if (
+                            info_root is not None
+                            and "pv" in info_root
+                            and info_root["pv"]
+                        ):
+                            best_move = info_root["pv"][0]
+                        if best_move is None:
+                            res = engine.play(board, limit)
+                            best_move = res.move
+
+                        san = board.san(move)
+
+                        # Evaluate played move
+                        board_played = board.copy()
+                        board_played.push(move)
+                        info_played_raw = engine.analyse(
+                            board_played, limit=limit, multipv=effective_mpv
+                        )
+                        info_played = (
+                            info_played_raw[0]
+                            if isinstance(info_played_raw, list)
+                            else info_played_raw
+                        )
+                        if info_played is None or "score" not in info_played:
+                            played_cp, played_mate = None, None
+                        else:
+                            played_cp, played_mate = score_to_cp(
+                                info_played["score"], pov_white=mover_white
+                            )
+
+                        # Evaluate best move position (for mover POV)
+                        best_san = (
+                            board.san(best_move) if best_move is not None else "?"
+                        )
+                        if best_move is not None:
+                            board_best = board.copy()
+                            board_best.push(best_move)
+                            info_best_raw = engine.analyse(
+                                board_best, limit=limit, multipv=effective_mpv
+                            )
+                            info_best = (
+                                info_best_raw[0]
+                                if isinstance(info_best_raw, list)
+                                else info_best_raw
+                            )
+                            if info_best is None or "score" not in info_best:
+                                best_cp, best_mate = None, None
+                            else:
+                                best_cp, best_mate = score_to_cp(
+                                    info_best["score"], pov_white=mover_white
+                                )
+                        else:
+                            best_cp, best_mate = None, None
+
+                        # Compute loss/classification
+                        cp_loss: int | None = None
+                        classification = "Unknown"
+                        if best_mate is not None or played_mate is not None:
+                            if best_mate is not None and played_mate is not None:
+                                if (best_mate > 0) and (played_mate > 0):
+                                    if abs(played_mate) == abs(best_mate):
+                                        classification = "Best"
+                                    elif abs(played_mate) > abs(best_mate):
+                                        classification = "Inaccuracy"
+                                    else:
+                                        classification = "Best"
+                                elif (best_mate < 0) and (played_mate < 0):
+                                    if abs(played_mate) == abs(best_mate):
+                                        classification = "Best"
+                                    elif abs(played_mate) < abs(best_mate):
+                                        classification = "Blunder"
+                                    else:
+                                        classification = "Good"
+                                else:
+                                    classification = "Blunder"
+                            else:
+                                classification = "Blunder"
+                        elif best_cp is not None and played_cp is not None:
+                            cp_loss = max(0, best_cp - played_cp)
+                            classification = classify_cp_loss(cp_loss)
+
+                        side = "W" if mover_white else "B"
+                        logging.info(
+                            f"{ply:>3}  {side}   {san:<8}  "
+                            f"{fmt_eval(played_cp, played_mate):>10}  "
+                            f"{fmt_eval(best_cp, best_mate):>9}  "
+                            f"{(str(cp_loss) if cp_loss is not None else '—'):>5}  "
+                            f"{classification:<12}  {best_san}"
+                        )
+                        break
+
+                    # Advance to keep searching for the last move
+                    board.push(move)
+                    node = move_node
+                    ply += 1
+        else:
+            # Default behavior: analyze all moves
+            while node.variations:
+                move_node = node.variations[0]
+                move = move_node.move
+                mover_white = board.turn
+
+                # Analyse position to get engine best move suggestion
+                info_root_raw = engine.analyse(
+                    board, limit=limit, multipv=effective_mpv
+                )
+                info_root = (
+                    info_root_raw[0]
+                    if isinstance(info_root_raw, list)
+                    else info_root_raw
+                )
+                best_move = None
+                if info_root is not None and "pv" in info_root and info_root["pv"]:
+                    best_move = info_root["pv"][0]
+                # Fallback to engine.play if PV missing
+                if best_move is None:
+                    res = engine.play(board, limit)
+                    best_move = res.move
+
+                # Evaluate played move position (for mover POV) using a temp board
+                san = board.san(move)
+                board_played = board.copy()
+                board_played.push(move)
+                info_played_raw = engine.analyse(
+                    board_played, limit=limit, multipv=effective_mpv
+                )
+                info_played = (
+                    info_played_raw[0]
+                    if isinstance(info_played_raw, list)
+                    else info_played_raw
+                )
+                if info_played is None or "score" not in info_played:
+                    played_cp, played_mate = None, None
+                else:
+                    played_cp, played_mate = score_to_cp(
+                        info_played["score"], pov_white=mover_white
+                    )
+
+                # Evaluate best move position (for mover POV)
+                best_san = board.san(best_move) if best_move is not None else "?"
+                if best_move is not None:
+                    board_best = board.copy()
+                    board_best.push(best_move)
+                    info_best_raw = engine.analyse(
+                        board_best, limit=limit, multipv=effective_mpv
+                    )
+                    info_best = (
+                        info_best_raw[0]
+                        if isinstance(info_best_raw, list)
+                        else info_best_raw
+                    )
+                    if info_best is None or "score" not in info_best:
+                        best_cp, best_mate = None, None
+                    else:
+                        best_cp, best_mate = score_to_cp(
+                            info_best["score"], pov_white=mover_white
+                        )
+                else:
+                    best_cp, best_mate = None, None
+
+                # Compute centipawn loss bands
+                cp_loss: int | None = None
+                classification = "Unknown"
+                # Handle mate cases first
+                if best_mate is not None or played_mate is not None:
+                    if best_mate is not None and played_mate is not None:
+                        # Same sign -> compare speed
+                        if (best_mate > 0) and (played_mate > 0):
+                            # Keeping a mate: equal speed Best;
+                            # slower -> Inaccuracy; faster -> Best
+                            if abs(played_mate) == abs(best_mate):
+                                classification = "Best"
+                            elif abs(played_mate) > abs(best_mate):
+                                classification = "Inaccuracy"
+                            else:
+                                classification = "Best"
+                        elif (best_mate < 0) and (played_mate < 0):
+                            # Defending: equal delay Best;
+                            # sooner mate -> Blunder;
+                            # if played delays more -> Good
+                            if abs(played_mate) == abs(best_mate):
+                                classification = "Best"
+                            elif abs(played_mate) < abs(best_mate):
+                                classification = "Blunder"
+                            else:
+                                classification = "Good"
+                        else:
+                            # Sign flip across who mates -> Blunder
+                            classification = "Blunder"
+                    else:
+                        # Losing a forced mate or missing one
+                        classification = "Blunder"
+                elif best_cp is not None and played_cp is not None:
+                    cp_loss = max(0, best_cp - played_cp)
+                    classification = classify_cp_loss(cp_loss)
+
+                side = "W" if mover_white else "B"
+                logging.info(
+                    f"{ply:>3}  {side}   {san:<8}  "
+                    f"{fmt_eval(played_cp, played_mate):>10}  "
+                    f"{fmt_eval(best_cp, best_mate):>9}  "
+                    f"{(str(cp_loss) if cp_loss is not None else '—'):>5}  "
+                    f"{classification:<12}  {best_san}"
+                )
+
+                node = move_node
+                ply += 1
+                # Advance the live board for the next ply
+                board.push(move)
+    finally:
+        engine.quit()
+
+
+if __name__ == "__main__":
+    main()

python_pkg/stockfish_analysis/requirements.txt

@@ -0,0 +1,2 @@
+psutil>=5.9
+python-chess>=1.999

python_pkg/stockfish_analysis/run.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Resolve paths
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+VENV_DIR="$REPO_ROOT/.venv"
+
+# Find analyzer script (prefer local copy in this folder, fallback to PYTHON/analyze_chess_game.py)
+ANALYZER="$SCRIPT_DIR/analyze_chess_game.py"
+if [[ ! -f "$ANALYZER" ]]; then
+  if [[ -f "$REPO_ROOT/PYTHON/analyze_chess_game.py" ]]; then
+    ANALYZER="$REPO_ROOT/PYTHON/analyze_chess_game.py"
+  else
+    echo "Could not find analyze_chess_game.py" >&2
+    exit 1
+  fi
+fi
+
+# Ensure virtual environment exists and is active
+if [[ ! -d "$VENV_DIR" ]]; then
+  python3 -m venv "$VENV_DIR"
+fi
+# shellcheck disable=SC1090
+source "$VENV_DIR/bin/activate"
+
+# Install dependencies quietly
+pip install -r "$SCRIPT_DIR/requirements.txt" >/dev/null
+
+# Default engine (can override with STOCKFISH env var)
+ENGINE_BIN="${STOCKFISH:-stockfish}"
+
+# Require input file or auto-pick a lichess log if not provided
+if [[ $# -eq 0 ]]; then
+  GAME_FILE="$(ls -1 "$REPO_ROOT"/lichess_bot_game_*.log 2>/dev/null | head -n1 || true)"
+  if [[ -z "${GAME_FILE:-}" ]]; then
+    echo "Usage: $0 <pgn-or-log-file> [--time sec | --depth N] [--engine path] [extra args]" >&2
+    exit 2
+  fi
+  set -- "$GAME_FILE"
+fi
+
+# Pass through args, but add --engine if user didn't include one
+if printf '%s\n' "$@" | grep -q -- "--engine"; then
+  ENGINE_ARGS=()
+else
+  ENGINE_ARGS=(--engine "$ENGINE_BIN")
+fi
+
+python "$ANALYZER" "$@" "${ENGINE_ARGS[@]}"

python_pkg/tag_divider/LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

python_pkg/tag_divider/README.md

@@ -0,0 +1,15 @@
+# tagDivider
+
+Python script creating two directories, showing images in the script directory and putting those images into one of those directories depending on user input
+
+How to use:
+
+1. Install opencv for python3
+   a) Linux: sudo apt-get install python3-opencv
+2. Put the script into whatever folder you have images in
+3. Run the script
+   python3 tagDivider.py
+4. Enter folders names in terminal
+5. Click "a" or "d" accordingly to folder you want image to be in
+
+If you want to change default buttons just modify script

python_pkg/tag_divider/__init__.py

@@ -0,0 +1 @@
+"""Image tag divider package."""

python_pkg/tag_divider/tag_divider.py

@@ -0,0 +1,78 @@
+"""Sort images into folders using keyboard input."""
+
+import logging
+import os  # for: os.getcwd; os.mkdir; os.listdir;
+from os import path  # for: os.path.abspath
+import shutil  # for: shutil.move
+
+# for: cv2.imread; cv2.namedWindow; cv2.imshow;
+# cv2.waitKey; cv2.destroyAllWindows; cv2.IMREAD_COLOR
+import cv2
+
+logging.basicConfig(level=logging.INFO)
+
+IMAGE_EXTENSION = (
+    ".bmp",
+    ".dib",
+    ".jpeg",
+    ".jpg",
+    ".jpe",
+    ".jp2",
+    ".png",
+    ".pbm",
+    ".pgm",
+    ".ppm",
+    ".pxm",
+    ".pnm",
+    ".pfm",
+    ".sr",
+    ".ras",
+    ".tiff",
+    ".tif",
+    ".exr",
+    ".hdr",
+    ".pic",
+)  # From: https://docs.opencv.org/4.5.2/d4/da8/group__imgcodecs.html
+# Note: .webp excluded because animated images don't work
+LEFT_FOLDER_CODE = 100  # Default 100 - 'd'
+RIGHT_FOLDER_CODE = 97  # Default 97 - 'a'
+# Change by checking: https://www.ascii-code.com/
+
+first_folder_name = input("Enter first folder name: [a] ")
+second_folder_name = input("Enter second folder name: [d] ")
+
+current_path = os.path.abspath(
+    os.getcwd()
+)  # Stolen from: https://stackoverflow.com/q/3430372
+os.chdir(current_path)  # Change working directory to the path where the python file is
+
+if (
+    path.isdir(first_folder_name) != 1
+):  # Check if folder already exists, if it does not make it
+    os.mkdir(first_folder_name)
+if path.isdir(second_folder_name) != 1:
+    os.mkdir(second_folder_name)
+
+for filename in os.listdir(
+    os.getcwd()
+):  # Go through every file in the working directory
+    if (filename.lower()).endswith(
+        IMAGE_EXTENSION
+    ):  # If the file name ends with image extension
+        logging.info(filename)
+        image = cv2.imread(filename, cv2.IMREAD_COLOR)
+        window_name = filename.split(".")[0]
+        cv2.namedWindow(window_name)  # Window name is the same as image file name
+        cv2.imshow(window_name, image)
+        key = cv2.waitKey()
+        if key == RIGHT_FOLDER_CODE:
+            shutil.move(
+                current_path + "/" + filename,
+                current_path + "/" + first_folder_name + "/" + filename,
+            )
+        elif key == LEFT_FOLDER_CODE:
+            shutil.move(
+                current_path + "/" + filename,
+                current_path + "/" + second_folder_name + "/" + filename,
+            )
+        cv2.destroyAllWindows()