BoKeTE

A minimal PyTorch training and experimentation helper library for my personal use. Extracted from my computer vision final year project (2024/2025) at the University of Nottingham. Named after the Bad Bunny song BoKeTe, which refers to pothole in English. Designed as a modular, reusable helper package for general PyTorch deep learning workflows:

_{"BoKeTe": Music video homage & namesake inspiration.}

• Training & Execution: Trainer loop with mixed-precision (AMP), auto cuDNN benchmarking, EarlyStopping, and model/optimizer checkpointing.
• Experimentation & Reporting: Metric tracking, loss curve rendering (Matplotlib + Chart.js HTML), grid search parameter sweeps, and GFM Markdown report compilation (single-trial + multi-trial summaries).

[!NOTE] Personal Tooling & Disclaimer: bokete is an opinionated, personal PyTorch helper library created to streamline my own research workflows. While open-sourced under the MIT License, it is provided "as is" without warranty, guarantee of support, or promises of backward compatibility. If you choose to use it, you do so entirely at your own risk.

Table of Contents

• 1. Public API Summary
• 2. Installation
• 3. Core Modules & API Reference
  • 3.1 Training & Checkpointing (bokete.training)
  • 3.2 Metric Tracking & Summaries (bokete.metrics)
  • 3.3 Loss Curve Plotting (bokete.plotting)
  • 3.4 Markdown Experiment Reporting (bokete.reporting)
  • 3.5 Hyperparameter Sweeps (bokete.experiments)
• 4. Usage Example
• 5. Project Architecture

1. Public API Summary

All core primitives are exported at the root package level (from bokete import ...):

(back to top)

2. Installation

bokete is packaged using the hatchling build backend and is fully compatible with uv workspaces.

Workspace / Local Installation (uv)

When used inside a project workspace, uv sync automatically installs bokete in editable mode:

uv sync

Or standalone via uv pip:

uv pip install -e ./bokete

Dependency Requirements

• Python: >= 3.10
• PyTorch: >= 2.0
• NumPy, Matplotlib, tqdm

(back to top)

3. Core Modules & API Reference

3.1 Training & Checkpointing (bokete.training)

Provides the core training loop wrapper (Trainer), early stopping logic (EarlyStopping), model checkpointing (Checkpoint), and hardware device detection (determine_device).

from bokete import Trainer, EarlyStopping, Checkpoint, determine_device, set_seed

# Reproducibility & Hardware setup
set_seed(42)
device = determine_device()

# Setup callbacks
early_stop = EarlyStopping(patience=10, min_delta=1e-4)
checkpoint = Checkpoint(directory="checkpoints")

# Initialise and execute training loop
trainer = Trainer(model, criterion, optimizer, device=device, amp=True)
metrics = trainer.fit(
    train_loader, 
    val_loader, 
    epochs=50, 
    early_stopping=early_stop,
    checkpoint=checkpoint
)

3.2 Metric Tracking & Summaries (bokete.metrics)

Aggregates running loss metrics per epoch and generates structured summary statistics (final losses, mean losses, best epoch).

from bokete import TrainingMetrics, training_report

# Compute summary stats from training history dictionary
summary = training_report(eval_metrics)
# Returns: {'final_train_loss': 0.12, 'final_val_loss': 0.18, 'mean_train_loss': ..., 'best_epoch': 34}

3.3 Loss Curve Plotting (bokete.plotting)

Renders publication-ready training and validation loss curves using Matplotlib with annotated best-epoch markers, alongside a companion interactive Chart.js HTML file.

from bokete import plot_loss_curves

plot_loss_curves(
    train_loss=eval_metrics['train_loss'],
    val_loss=eval_metrics['val_loss'],
    path="results/graph.png",
    best_epoch=summary['best_epoch']
)

3.4 Markdown Experiment Reporting (bokete.reporting)

Generates structured, self-contained GitHub-Flavoured Markdown (.md) reports containing trial overviews, key hyperparameter highlights, loss graph embeds, custom evaluation metrics, and multi-trial statistical summaries ($\text{Mean} \pm \text{Std}$, $\text{Min}$, $\text{Max}$).

from bokete import experiment_report, multi_trial_report

# 1. Single Trial Report
md_report = experiment_report(
    config=config_dict,
    metrics_summary=summary,
    train_loss=eval_metrics['train_loss'],
    val_loss=eval_metrics['val_loss'],
    graph_filename="graph.png",
    title="Trial 1 Report [mixed_r0.1_s0.1]",
    extra_metrics={"Convergence Speed": 0.2145}
)

with open("result.md", "w", encoding="utf-8") as f:
    f.write(md_report)

# 2. Multi-Trial Combined Summary Report
summary_md = multi_trial_report(
    config=config_dict,
    all_trial_metrics=[metrics_trial_1, metrics_trial_2, metrics_trial_3]
)

with open("summary-report.md", "w", encoding="utf-8") as f:
    f.write(summary_md)

3.5 Hyperparameter Sweeps (bokete.experiments)

Orchestrates parameter sweeps over a grid of configuration paths without bleeding state across runs.

from bokete import run_experiments

param_grid = {
    "training.lr": [0.001, 0.0001],
    "training.batch_size": [8, 16]
}

results = run_experiments(
    base_config=config,
    param_grid=param_grid,
    run_fn=train_and_eval_callback
)

(back to top)

4. Usage Example

Here is a complete, minimal example combining bokete helpers inside a standard PyTorch pipeline:

import torch
import torch.nn as nn
from torch.utils.data import DataLoader
from bokete import (
    determine_device, 
    set_seed, 
    Trainer, 
    training_report, 
    plot_loss_curves, 
    experiment_report
)

# 1. Setup Environment
set_seed(42)
device = determine_device()

# 2. Model, Loss, Optimizer
model = MyNeuralNetwork().to(device)
criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

# 3. Train using Trainer wrapper
trainer = Trainer(model, criterion, optimizer, device=device)
history = trainer.fit(train_loader, val_loader, epochs=20)

# 4. Generate Reports & Visualisations
summary = training_report(history.as_dict())
plot_loss_curves(
    train_loss=history.train_loss,
    val_loss=history.val_loss,
    path="graph.png",
    best_epoch=summary['best_epoch']
)

md = experiment_report(
    config={"lr": 1e-3, "epochs": 20},
    metrics_summary=summary,
    train_loss=history.train_loss,
    val_loss=history.val_loss,
    graph_filename="graph.png",
    title="Minimal Training Run"
)

with open("result.md", "w", encoding="utf-8") as f:
    f.write(md)

(back to top)

5. Project Architecture

bokete/
├── pyproject.toml         # Hatchling build system configuration
├── README.md              # Package documentation
└── src/
    └── bokete/
        ├── __init__.py    # Public API exports
        ├── experiments.py # Grid sweep orchestration
        ├── metrics.py     # Loss aggregation & summary statistics
        ├── plotting.py    # Matplotlib loss curve & Chart.js HTML rendering
        ├── reporting.py   # Single-trial & multi-trial Markdown report generation
        └── training.py    # Core Trainer, EarlyStopping, Checkpoint, auto-benchmarking

(back to top)