api.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>GGUF Toolkit — API</title>
<meta name="description" content="The client-side GGUF API (browser JS) and the CPU suite endpoints, documented.">
<style>
  :root { --bg:#0e1117; --panel:#161b22; --line:#26303d; --fg:#e6edf3; --dim:#8b949e;
          --accent:#7c8cff; --ok:#3fb950; }
  * { box-sizing:border-box; }
  body { margin:0; background:var(--bg); color:var(--fg);
         font:15px/1.6 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif; }
  .wrap { max-width:960px; margin:0 auto; padding:26px 22px 70px; }
  h1 { margin:0 0 6px; font-size:24px; } h2 { margin:34px 0 8px; font-size:19px; }
  h3 { margin:22px 0 6px; font-size:16px; color:var(--fg); }
  p, li { color:#c9d4e0; } .dim { color:var(--dim); }
  a { color:var(--accent); }
  pre { background:#0d1117; border:1px solid var(--line); border-radius:10px; padding:14px;
        overflow:auto; font:12.5px/1.55 ui-monospace,SFMono-Regular,Consolas,monospace; }
  code { background:#0d1117; border:1px solid var(--line); border-radius:5px; padding:1px 5px;
         font:13px ui-monospace,SFMono-Regular,Consolas,monospace; }
  table { border-collapse:collapse; width:100%; margin:10px 0; font-size:14px; }
  th, td { border:1px solid var(--line); padding:7px 10px; text-align:left; vertical-align:top; }
  th { background:var(--panel); color:var(--dim); font-weight:600; }
  .pill { display:inline-block; padding:2px 9px; border-radius:999px; font-size:12px;
          border:1px solid var(--line); color:var(--ok); }
  .note { border-left:3px solid var(--accent); padding:8px 14px; color:#c9d4e0;
          background:var(--panel); border-radius:0 8px 8px 0; }
  footer { border-top:1px solid var(--line); margin-top:34px; padding-top:14px; color:var(--dim); font-size:13px; }
</style>
</head>
<body>
<div class="wrap">
  <h1>GGUF Toolkit — API</h1>
  <p class="dim">Two interfaces, chosen by where the work belongs: a <b>client-side JS API</b> on this
     static Space (no server, no quota) and <b>Gradio endpoints</b> on the CPU suites for the things
     that genuinely compute. <a href="index.html">← back to the tools</a></p>

  <h2>1. Client-side JS API <span class="pill">static · 0 CPU</span></h2>
  <p>Load <code>gguf.js</code> with a classic script tag and parse an <code>ArrayBuffer</code>. The
     file is dependency-free and exports the same logic the Python reference does
     (<code>templates/gguf_util.py</code>); the two are kept equal by
     <code>scripts/crosscheck_gguf.py</code>, which compares them on real <code>.gguf</code> files.</p>

<pre>&lt;script src="gguf.js"&gt;&lt;/script&gt;
&lt;script&gt;
  // 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");
&lt;/script&gt;</pre>

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

  <h3>Loading the API into your own page</h3>
  <p class="note"><b>Static Spaces have no API endpoints.</b> They are files, served from
     <code>https://&lt;owner&gt;-&lt;name&gt;.static.hf.space/</code> — note the <code>.static</code>
     host, which is different from a Gradio Space's <code>.hf.space</code>. So the API is the JS file
     itself; fetch and evaluate it, or copy <code>gguf.js</code> next to your page.</p>
<pre>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());</pre>
  <p>Because the module also does <code>module.exports = api</code> when it is loaded outside a
     browser, the same file runs in Node — that is how the cross-check test drives it.</p>

  <h2>2. CPU suite endpoints <span class="pill">cpu-basic · programmatic</span></h2>
  <p>Work that needs real compute stays on a <code>cpu-basic</code> suite and keeps its Gradio
     endpoints, callable with <code>gradio_client</code>:</p>

<pre>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")</pre>

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

  <h3>The <code>/relay</code> contract</h3>
  <p><code>relay(url, key, params_json, message)</code> POSTs <code>params_json</code> to
     <code>url</code> with <code>Authorization: &lt;key&gt;</code> 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
     <code>fetch</code> used <code>mode: "no-cors"</code>, so the reply was unreadable.</p>

  <h2>3. Which interface a project gets</h2>
  <table>
    <tr><th>Rule</th><th>Where it goes</th></tr>
    <tr><td>The bytes are already in the visitor's browser (they dropped a file in)</td><td>static Space, JS</td></tr>
    <tr><td>Pure arithmetic, formatting, JSON/table building</td><td>static Space, JS</td></tr>
    <tr><td>Simulation, model inference, anything with a compute stack</td><td>CPU suite, endpoints</td></tr>
    <tr><td>Needs to escape the browser sandbox (CORS, secrets held by the caller, host processes)</td><td>CPU suite, endpoints</td></tr>
  </table>
  <p class="dim">On this account a Gradio/Docker Space cannot even be created on the free tier
     (<code>POST /api/repos/create</code> → HTTP 402), and only three <code>cpu-basic</code> Spaces run
     at once — which is what makes the static route the default rather than a preference.</p>

  <footer>Part of the AEUPH studio. See the tools at <a href="index.html">index.html</a>.</footer>
</div>
</body>
</html>