GGUF Toolkit — API

Two interfaces, chosen by where the work belongs: a client-side JS API on this static Space (no server, no quota) and Gradio endpoints on the CPU suites for the things that genuinely compute. ← back to the tools

1. Client-side JS API static · 0 CPU

Load gguf.js with a classic script tag and parse an ArrayBuffer. The file is dependency-free and exports the same logic the Python reference does (templates/gguf_util.py); the two are kept equal by scripts/crosscheck_gguf.py, which compares them on real .gguf files.

<script src="gguf.js"></script>
<script>
  // read only the header: the reader stops at the tensor index
  const head = file.slice(0, 64 * 1024 * 1024);
  const h = GGUF.parse(await head.arrayBuffer());
  h.sizeBytes = file.size;               // the slice is a prefix of the file

  console.log(GGUF.inspect(h));          // metadata KVs + quantisation mix
  console.log(GGUF.validate(h).verdict); // "SELF-DESCRIBING: complete" | ...
  console.log(GGUF.inventory(h, "attn", "params"));
  const json = GGUF.buildWorkflow("sdxl", "sdxl-unet-q8.gguf", "a photo", "blurry");
</script>

Function	Returns
`GGUF.parse(arrayBuffer)`	`{version, nTensors, nKv, kv[], tensors[], sizeBytes}`; throws `GGUF.GgufError` on a bad magic/version
`GGUF.inspect(h)`	text: every KV and the quantisation histogram
`GGUF.validate(h)`	`{report, verdict}` — checks the self-describing schemas (`sdxl`, `jinxos`, `lora`, `shader`, `jinxai`)
`GGUF.compareFromFile(h)` / `GGUF.compareFromParams(n)`	text: size in every quantisation from the ggml bit-width table
`GGUF.inventory(h, filter, sortBy)`	`{table, hist}`, 400 rows max
`GGUF.buildWorkflow(family, unet, pos, neg)`	ComfyUI-GGUF workflow JSON (`sdxl`, `flux`)
`GGUF.quantHistogram(tensors)`, `GGUF.fmtBytes(n)`, `GGUF.estimateSizes(n)`, `GGUF.GGML_TYPES`, `GGUF.BITS`, `GGUF.SCHEMAS`	the tables and helpers the tools are built from

Loading the API into your own page

Static Spaces have no API endpoints. They are files, served from https://<owner>-<name>.static.hf.space/ — note the .static host, which is different from a Gradio Space's .hf.space. So the API is the JS file itself; fetch and evaluate it, or copy gguf.js next to your page.

const src = await (await fetch(
  "https://aeuph-gguf-toolkit.static.hf.space/gguf.js")).text();
new Function(src)();                       // defines GGUF on window
const h = GGUF.parse(await file.arrayBuffer());

Because the module also does module.exports = api when it is loaded outside a browser, the same file runs in Node — that is how the cross-check test drives it.

2. CPU suite endpoints cpu-basic · programmatic

Work that needs real compute stays on a cpu-basic suite and keeps its Gradio endpoints, callable with gradio_client:

from gradio_client import Client

# Hyper-dimensional computing: bind / bundle / permute / lexicon / aetheric VM
h = Client("AEUPH/hdc-suite")
h.predict("aether", "cosmos", 3, api_name="/algebra")

# Quantum: statevector circuit simulation, Grover, CHSH, superposition
q = Client("AEUPH/quantum-suite")
q.predict("H 0\nCX 0 1", 2, api_name="/circuit_sim")
q.predict(5, 16, api_name="/grover")

# BRUTE-AI: same-origin relay (this is the endpoint a static page cannot offer)
b = Client("AEUPH/brute-suite")
b.predict(url, key, params_json, message, api_name="/relay")
b.predict(model_reply, api_name="/protocol_runner")

Suite	Endpoints	Why it needs CPU
`hdc-suite`	`/algebra`, `/lexicon`, `/aetheric_vm`	1024-dimensional hypervector arithmetic — server-side computation
`quantum-suite`	`/circuit_sim`, `/superposition`, `/grover`, `/entanglement_lab`	numpy statevector simulation
`brute-suite`	`/relay`, `/protocol_runner`	same-origin relay: the browser cannot read a cross-origin model reply, so the request must leave from the host

The `/relay` contract

relay(url, key, params_json, message) POSTs params_json to url with Authorization: <key> and returns the model text, the HTTP status and the elapsed time. The key is used once and never stored, logged or echoed back — the caller supplies their own. This is the piece BRUTE-AI could not do itself: its own fetch used mode: "no-cors", so the reply was unreadable.

3. Which interface a project gets

Rule	Where it goes
The bytes are already in the visitor's browser (they dropped a file in)	static Space, JS
Pure arithmetic, formatting, JSON/table building	static Space, JS
Simulation, model inference, anything with a compute stack	CPU suite, endpoints
Needs to escape the browser sandbox (CORS, secrets held by the caller, host processes)	CPU suite, endpoints