Metadata-Version: 2.1
Name: gk-diffuser
Version: 0.0.2
Summary: Image/video/audio generation GUI for GGUF diffusion models, powered by the gk engine
Author-Email: gguf <info@gguf.us>
License: MIT
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: Repository, https://github.com/gguf-io/gk
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# gk-diffuser

Image/video/audio generation GUI for GGUF diffusion models, packaged for
Python — the diffusion half of the unified `ggk` package. The GUI runs in your
browser against a local backend; each generation spawns the `diffusion` C/C++
CLI, compiled during `pip install` and bundled with the package as a single
binary. The engine evaluates its graphs on **gk**, an independent tensor
library — there is no ggml anywhere in the tree. Model files are referenced by
filesystem path through a built-in file browser — nothing is uploaded or
copied to temp storage.

## Install

```bash
pip install gk-diffuser
```

Building the bundled engine requires a C/C++ toolchain and CMake ≥ 3.15 (on
Windows: MSVC Build Tools). The engine source is resolved from the vendored
`vendor/diffusion` copy (see `scripts/vendor_engine.py`) or
`GK_DIFFUSER_ENGINE_DIR`. That tree is self-contained — it carries the gk
kernels and the diffusion runtime with its own tokenizers and thirdparty — so
the build compiles the CLI binary and nothing else.

The `vendor/diffusion/gk` kernels are shared verbatim with the `gk-server`
package; both are vendored from the same unified ggk engine tree, so the two
packages always compute with the same gk.

### GPU and accelerator backends

The default build is CPU-only (**on macOS, Metal is on by default** — no flag
needed). Backends are opt-in and can be requested with an environment variable
or a CMake define — the env var is usually easier to pass through `pip`:

```bash
GK_DIFFUSER_CUDA=1   pip install gk-diffuser    # NVIDIA (needs the CUDA toolkit)
GK_DIFFUSER_HIP=1    pip install gk-diffuser    # AMD (needs ROCm/HIP)
GK_DIFFUSER_VULKAN=1 pip install gk-diffuser    # cross-vendor (needs the Vulkan SDK)

CMAKE_ARGS="-DGK_DIFFUSER_CUDA=ON" pip install gk-diffuser   # equivalent
```

Available: `CUDA`, `HIP`, `VULKAN`, `METAL`. Each option maps to the gk
backend of the same name, and the finer-grained `GK_*` knobs (`GK_NATIVE`,
`GK_CUDA_ARCHITECTURES`, …) can still be passed straight through as
`-DGK_<NAME>=…`.

A CUDA build works its own architecture list out from nvcc and the installed
GPUs, and embeds PTX for the newest, so an unlisted card JITs rather than
failing. A wheel built on one machine for another should still say what it
targets, e.g. `CMAKE_ARGS="-DGK_DIFFUSER_CUDA=ON -DGK_CUDA_ARCHITECTURES=89"`.

## Run

```bash
gk-diffuser              # GUI on http://127.0.0.1:8643, opens the browser
python -m gk_diffuser    # same thing
gk-diffuser --port 0     # pick a free port; --no-browser to stay headless
```

The engine is directly scriptable from the CLI too:

```bash
gk-diffuser engine -- -m sd.gguf -p "a lighthouse at dusk" -o out.png
gk-diffuser engine -- --help
```
