deep-mkv-gen-notebooks

deep-mkv-gen-notebooks is the experiment and notebook sibling for deep-mkv-gen. This repo owns the interactive workflows, notebook-only helper code, vendored ALAE runtime, and local artifact directories that should not be part of the reusable library package.

The notebooks in this repo have been exercised locally against the current deep-mkv-gen public API.

Repo Boundary

Keep reusable runtime code in deep-mkv-gen. Keep exploratory workflows and local experiment state here.

This repo owns:

• Jupyter notebooks
• notebook-side helper code in notebooks/
• vendored ALAE code under notebooks/vendor_alae/
• downloaded public assets under data/
• generated outputs, previews, and caches under notebook_runs/

This repo does not own:

• the packaged deep_mkv_gen library
• the training runtime implementation
• provider implementations
• the library test suite

Those live in the sibling repo ../deep-mkv-gen.

Expected Local Layout

scenarios/
├── deep-mkv-gen/
└── deep-mkv-gen-notebooks/

The notebooks assume the library repo is available at ../deep-mkv-gen.

Setup

Recommended local setup:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

That requirements file installs the sibling library repo in editable mode with its geomloss extra, because the W2 and hybrid notebooks depend on the GeomLoss-backed provider path.

Start Jupyter from this repo root so relative paths resolve consistently:

jupyter lab

Public API Shape

The notebooks follow the current public API from deep-mkv-gen:

• build a DeepMKVGen model
• build a provider spec such as KLProviderSpec, W2ProviderSpec, or HybridProviderSpec
• call fit(..., provider_spec=provider_spec, ...) with either source/target samples or explicit SourceSampler / TargetSampler objects
• use sample(...) for unconditional draws from the fitted source distribution
• use transport(...) or transport_with_snapshots(...) for explicit-input transport

The concrete provider classes are intentionally not used directly here anymore. fit(...) resolves the provider implementation and wires the target sampler internally from the provider spec and the target input you pass in.

Notebook Guide

Main workflow:

• notebooks/ffhq_alae_women_smile_transport.ipynb End-to-end FFHQ / ALAE smile-transport workflow in the 512D latent space.

Supporting helper:

• notebooks/ffhq_alae_smile_dataset.py Downloads public FFHQ/ALAE latent assets, filters the latent table, computes CLIP-derived smile scores, and manages cached notebook artifacts.

Smaller synthetic examples:

• notebooks/n8g_deep_mkv_gen_kl_ratio.ipynb Minimal KL-ratio example using KLProviderSpec.
• notebooks/n8g_deep_mkv_gen_w.ipynb Minimal Wasserstein example using W2ProviderSpec.
• notebooks/n8g_deep_mkv_gen_hybrid.ipynb Minimal hybrid KL + W2 example using HybridProviderSpec.

Repo Layout

deep-mkv-gen-notebooks/
├── README.md
├── requirements.txt
├── data/
├── notebook_runs/
└── notebooks/
    ├── __init__.py
    ├── utils.py
    ├── n8g_deep_mkv_gen_kl_ratio.ipynb
    ├── n8g_deep_mkv_gen_w.ipynb
    ├── n8g_deep_mkv_gen_hybrid.ipynb
    ├── ffhq_alae_smile_dataset.py
    ├── ffhq_alae_women_smile_transport.ipynb
    └── vendor_alae/

data/ and notebook_runs/ are local working directories and are ignored by git.

Vendored ALAE Runtime

notebooks/vendor_alae/ contains the trimmed vendored runtime needed by the FFHQ / ALAE workflow. Keep downloaded checkpoints, cached arrays, and generated outputs out of that vendored source tree.

The third-party notice file is:

• notebooks/vendor_alae/THIRD_PARTY_NOTICES.md