Spaces:
Running
Running
| <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><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></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://<owner>-<name>.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: <key></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> | |