Initial Commit

Author: V3D4NTH

.github/ISSUE_TEMPLATE/ask-a-question.md

@@ -0,0 +1,10 @@
+---
+name: Ask a Question
+about: Ask questions related to the book
+title: ''
+labels: [question]
+assignees: rasbt
+
+---
+
+If you have a question that is not a bug, please consider asking it in this GitHub repository's [discussion forum](https://github.com/rasbt/LLMs-from-scratch/discussions).

.github/ISSUE_TEMPLATE/bug-report.yaml

@@ -0,0 +1,85 @@
+name: Bug Report
+description: Report errors related to the book content or code
+title: "Description"
+labels: [bug]
+assignees: rasbt
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to report an issue. Please fill out the details below to help resolve it.
+
+  - type: textarea
+    id: bug_description
+    attributes:
+      label: Bug description
+      description: A description of the issue.
+      placeholder: |
+        Please provide a description of what the bug or issue is.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: operating_system
+    attributes:
+      label: What operating system are you using?
+      description: If applicable, please select the operating system where you experienced this issue.
+      options:
+        - "Unknown"
+        - "macOS"
+        - "Linux"
+        - "Windows"
+    validations:
+      required: False
+
+  - type: dropdown
+    id: compute_environment
+    attributes:
+      label: Where do you run your code?
+      description: Please select the computing environment where you ran this code.
+      options:
+        - "Local (laptop, desktop)"
+        - "Lightning AI Studio"
+        - "Google Colab"
+        - "Other cloud environment (AWS, Azure, GCP)"
+    validations:
+      required: False
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: |
+        Please provide details about your Python environment via the environment collection script or notebook located at
+        https://github.com/rasbt/LLMs-from-scratch/tree/main/setup/02_installing-python-libraries.
+        For your convenience, you can download and run the script from your terminal as follows:
+
+        ```bash
+        curl --ssl-no-revoke -O https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/main/setup/02_installing-python-libraries/python_environment_check.py  \
+        -O https://raw.githubusercontent.com/rasbt/LLMs-from-scratch/main/requirements.txt
+
+        python python_environment_check.py
+        ```
+
+        The script will print your Python environment information in the following format
+        ```console
+        [OK] Your Python version is 3.11.4
+        [OK] torch 2.3.1
+        [OK] jupyterlab 4.2.2
+        [OK] tiktoken 0.7.0
+        [OK] matplotlib 3.9.0
+        [OK] numpy 1.26.4
+        [OK] tensorflow 2.16.1
+        [OK] tqdm 4.66.4
+        [OK] pandas 2.2.2
+        [OK] psutil 5.9.8
+        ```
+        You can simply copy and paste the outputs of this script below.
+      value: |
+        ```
+
+
+
+        ```
+    validations:
+      required: false

.github/scripts/check_double_quotes.py

@@ -0,0 +1,158 @@
+# Copyright (c) Sebastian Raschka under Apache License 2.0 (see LICENSE.txt)
+# Source for "Build a Reasoning Model (From Scratch)": https://mng.bz/lZ5B
+# Code repository: https://github.com/rasbt/reasoning-from-scratch
+
+# Verify that Python source files (and optionally notebooks) use double quotes for strings.
+
+import argparse
+import ast
+import io
+import json
+import sys
+import tokenize
+from pathlib import Path
+
+EXCLUDED_DIRS = {
+    ".git",
+    ".hg",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+}
+
+PREFIX_CHARS = {"r", "u", "f", "b"}
+SINGLE_QUOTE = "'"
+DOUBLE_QUOTE = "\""
+TRIPLE_SINGLE = SINGLE_QUOTE * 3
+TRIPLE_DOUBLE = DOUBLE_QUOTE * 3
+
+
+def should_skip(path):
+    parts = set(path.parts)
+    return bool(EXCLUDED_DIRS & parts)
+
+
+def collect_fstring_expr_string_positions(source):
+    """
+    Return set of (lineno, col_offset) for string literals that appear inside
+    formatted expressions of f-strings. These should be exempt from the double
+    quote check, since enforcing double quotes there is unnecessarily strict.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set()
+
+    positions = set()
+
+    class Collector(ast.NodeVisitor):
+        def visit_JoinedStr(self, node):
+            for value in node.values:
+                if isinstance(value, ast.FormattedValue):
+                    self._collect_from_expr(value.value)
+            # Continue walking to catch nested f-strings within expressions
+            self.generic_visit(node)
+
+        def _collect_from_expr(self, node):
+            if isinstance(node, ast.Constant) and isinstance(node.value, str):
+                positions.add((node.lineno, node.col_offset))
+            elif isinstance(node, ast.Str):  # Python <3.8 compatibility
+                positions.add((node.lineno, node.col_offset))
+            else:
+                for child in ast.iter_child_nodes(node):
+                    self._collect_from_expr(child)
+
+    Collector().visit(tree)
+    return positions
+
+
+def check_quotes_in_source(source, path):
+    violations = []
+    ignored_positions = collect_fstring_expr_string_positions(source)
+    tokens = tokenize.generate_tokens(io.StringIO(source).readline)
+    for tok_type, tok_str, start, _, _ in tokens:
+        if tok_type == tokenize.STRING:
+            if start in ignored_positions:
+                continue
+            lowered = tok_str.lower()
+            # ignore triple-quoted strings
+            if lowered.startswith((TRIPLE_DOUBLE, TRIPLE_SINGLE)):
+                continue
+
+            # find the prefix and quote type
+            # prefix = ""
+            for c in PREFIX_CHARS:
+                if lowered.startswith(c):
+                    # prefix = c
+                    lowered = lowered[1:]
+                    break
+
+            # report if not using double quotes
+            if lowered.startswith(SINGLE_QUOTE):
+                line, col = start
+                violations.append(f"{path}:{line}:{col}: uses single quotes")
+    return violations
+
+
+def check_file(path):
+    try:
+        if path.suffix == ".ipynb":
+            return check_notebook(path)
+        else:
+            text = path.read_text(encoding="utf-8")
+            return check_quotes_in_source(text, path)
+    except Exception as e:
+        return [f"{path}: failed to check ({e})"]
+
+
+def check_notebook(path):
+    violations = []
+    with open(path, encoding="utf-8") as f:
+        nb = json.load(f)
+    for cell in nb.get("cells", []):
+        if cell.get("cell_type") == "code":
+            src = "".join(cell.get("source", []))
+            violations.extend(check_quotes_in_source(src, path))
+    return violations
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="Verify double-quoted string literals.")
+    parser.add_argument(
+        "--include-notebooks",
+        action="store_true",
+        help="Also scan Jupyter notebooks (.ipynb files) for single-quoted strings.",
+    )
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+    project_root = Path(".").resolve()
+    py_files = sorted(project_root.rglob("*.py"))
+    notebook_files = sorted(project_root.rglob("*.ipynb")) if args.include_notebooks else []
+
+    violations = []
+    for path in py_files + notebook_files:
+        if should_skip(path):
+            continue
+        violations.extend(check_file(path))
+
+    if violations:
+        print("\n".join(violations))
+        print(f"\n{len(violations)} violations found.")
+        return 1
+
+    print("All files use double quotes correctly.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/basic-tests-latest-python.yml

@@ -0,0 +1,51 @@
+name: Test latest PyTorch-compatible Python version
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - '**/*.py'    # Run workflow for changes in Python files
+      - '**/*.ipynb'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.sh'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '**/*.py'
+      - '**/*.ipynb'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.sh'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+
+    - name: Install dependencies
+      run: |
+        curl -LsSf https://astral.sh/uv/install.sh | sh
+        uv sync --dev --python=3.13
+        uv add pytest-ruff nbval
+
+    - name: Test Selected Python Scripts
+      run: |
+        source .venv/bin/activate
+        pytest setup/02_installing-python-libraries/tests.py
+        pytest ch04/01_main-chapter-code/tests.py
+        pytest ch05/01_main-chapter-code/tests.py
+        pytest ch06/01_main-chapter-code/tests.py
+
+    - name: Validate Selected Jupyter Notebooks
+      run: |
+        source .venv/bin/activate
+        pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
+        pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
+        pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb

.github/workflows/basic-tests-linux-uv.yml

@@ -0,0 +1,82 @@
+name: Code tests Linux
+
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - '**/*.py'
+      - '**/*.ipynb'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.sh'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '**/*.py'
+      - '**/*.ipynb'
+      - '**/*.yaml'
+      - '**/*.yml'
+      - '**/*.sh'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  uv-tests:
+    name: Code tests (Linux)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python (uv)
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install uv and dependencies
+        shell: bash
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          uv sync --dev  # tests for backwards compatibility
+          uv pip install -r ch05/07_gpt_to_llama/tests/test-requirements-extra.txt
+          uv add pytest-ruff nbval
+
+      - name: Test Selected Python Scripts (uv)
+        shell: bash
+        run: |
+          source .venv/bin/activate
+          pytest setup/02_installing-python-libraries/tests.py
+          pytest ch03/02_bonus_efficient-multihead-attention/tests/test_mha_implementations.py
+          pytest ch04/01_main-chapter-code/tests.py
+          pytest ch04/03_kv-cache/tests.py
+          pytest ch05/01_main-chapter-code/tests.py
+          pytest ch05/07_gpt_to_llama/tests/tests_rope_and_parts.py
+          pytest ch05/07_gpt_to_llama/tests/test_llama32_nb.py
+          pytest ch05/11_qwen3/tests/test_qwen3_nb.py
+          pytest ch05/12_gemma3/tests/test_gemma3_nb.py
+          pytest ch05/12_gemma3/tests/test_gemma3_kv_nb.py
+          pytest ch05/13_olmo3/tests/test_olmo3_nb.py
+          pytest ch05/13_olmo3/tests/test_olmo3_kvcache_nb.py
+          pytest ch06/01_main-chapter-code/tests.py
+
+      - name: Validate Selected Jupyter Notebooks (uv)
+        shell: bash
+        run: |
+          source .venv/bin/activate
+          pytest --nbval ch02/01_main-chapter-code/dataloader.ipynb
+          pytest --nbval ch03/01_main-chapter-code/multihead-attention.ipynb
+          pytest --nbval ch02/04_bonus_dataloader-intuition/dataloader-intuition.ipynb
+
+      - name: Test Selected Bonus Materials
+        shell: bash
+        run: |
+          source .venv/bin/activate
+          pytest ch02/05_bpe-from-scratch/tests.py
+
+      - name: Test Selected Bonus Materials
+        shell: bash
+        run: |
+          source .venv/bin/activate
+          pytest pkg/llms_from_scratch/tests/