KohakuBlueleaf / KohakuGBC

# KohakuGBC
Graph-Based Captioning (GBC) as one
KIR program on the
Togeari dataflow machine, with the engines that run
it: a VLM over any OpenAI-compatible or Anthropic API, vLLM in-process or a specialised Qwen3.5
engine; OWLv2 or SAM 3 for detection; EmbeddingGemma for names; on one GPU, many GPUs or other
nodes.
Producing one GBC graph is a branching process: ask the VLM, detect what it named, describe each
region, detect its parts, merge regions that are the same object, ask relational questions. Its
control flow differs per image and cannot be batched across images by hand. KohakuGBC writes
that process once, as a sequential KIR program; Togeari runs many images at once, overlaps every
call the sequential run cannot tell apart, and turns their model calls into batched engine calls.
**Contents:** Highlights · Install · Quick start ·
How it works · Configuration · Output ·
Faithful to GBC · Measured ·
Repository layout · Documentation · Checks
## Highlights
- **GBC at scale, with the models you choose.** Thousands to millions of images through a hosted
 API, your own vLLM or SGLang servers, or everything in one process on your GPU; engines on
 other nodes join the same lanes.
- **Exactly the sequential procedure.** Every job can be recorded and replayed through KIR's
 reference interpreter. On recorded runs of GBC's proof of concept, every graph equals the
 PoC's to the digest.
- **The procedure as data.** The root (an image query, existing captions, tags), the node budget,
 the fan-out and the relational questions are per-image `controls`; the detector is one setting.
- **One engine contract.** Every engine, from an HTTP server to the qwen35 engine written for this
 workload, sits behind Togeari's contract and is checked against it.
## Install
 [code] 
Wheels carry the Rust extension `kohakugbc._rs` (graph resolution). From a clone, with a Rust
toolchain:
 [code] 
`gbc doctor` prints versions, devices with their free memory, every entry per slot and, given
configuration layers, their placement plan and whether it fits.
## Quick start
**On one GPU**, the VLM, the detector and the embedder in this process (`configs/machine/
qwen35_local.py`: Qwen3.5-4B on the qwen35 engine, OWLv2, EmbeddingGemma on the CPU; 24 GiB):
 [code] 
One graph per image lands in `runs/machine/qwen35_local/graphs.jsonl`; the teaser above is the
graph of its image (29 vertices, the figure shows 20; 51 edges, 48 captions), drawn by
`scripts/docs/teaser.py`:
 [code] 
**Over an API**, the VLM on a server (vLLM, SGLang, llama.cpp, OpenAI, OpenRouter, Anthropic),
the vision models here:
 [code] 
 [code] 
**Without models**, the recorded PoC runs replayed: the program and the machine on pseudo
engines, every graph equal to the PoC's.
 [code] 
**From Python**:
 [code] 
| Command | Does |
|---|---|
| `gbc run CONFIG [CONFIG ...]` | builds the machine from configuration layers and runs its source into its sink |
| `gbc check CONFIG ...` | builds and checks the machine without star