Workshop: loop pull, list, show, rm, and fit

import java.util.List;
import java.util.Locale;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class ModelRefs {
    /** repo[:quant][@revision], from lesson 26 (Example 12), plus URL prefixes and local names. */
    record ModelRef(String repo, String quant, String revision) {
        static final Pattern FORMAT = Pattern.compile("([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)(?::([A-Za-z0-9_]+))?(?:@([A-Za-z0-9_./-]+))?");
        static final List<String> PREFIXES = List.of("https://huggingface.co/", "huggingface.co/", "hf.co/");

        static ModelRef parse(String text) {
            String t = text.strip();
            for (String p : PREFIXES) if (t.startsWith(p)) { t = t.substring(p.length()); break; }
            Matcher m = FORMAT.matcher(t);
            if (!m.matches() || m.group(1).contains(".."))
                throw new IllegalArgumentException("'" + text + "' is not a model reference of the form org/name[:QUANT][@REVISION]");
            String quant = m.group(2) == null ? null : m.group(2).toUpperCase(Locale.ROOT);
            return new ModelRef(m.group(1), quant, m.group(3) == null ? "main" : m.group(3));
        }

        /** The name shown by loop list once the quant is known, for example org/repo:Q4_K_M. */
        String displayName(String chosenQuant) { return repo + ":" + chosenQuant + (revision.equals("main") ? "" : "@" + revision); }

        /** A directory name without '/' or ':', unique per repo, quant, and revision. */
        String directoryName(String chosenQuant) {
            String rev = revision.equals("main") ? "" : "--" + revision.replace('/', '_');
            return repo.replace("/", "--") + "--" + chosenQuant + rev;
        }
    }

    public static void main(String[] args) {
        String[] inputs = {"example-org/Coder-7B-Instruct-GGUF", "example-org/Coder-7B-Instruct-GGUF:q4_k_m",
                "hf.co/example-org/Coder-7B-Instruct-GGUF:Q8_0", "https://huggingface.co/example-org/Coder-7B-Instruct-GGUF@refs/pr/3",
                "example-org/Coder-7B-Instruct-GGUF:Q5_K_M@0123456789abcdef0123456789abcdef01234567", "Coder-7B", "org/../x"};
        for (String in : inputs) {
            try {
                ModelRef r = ModelRef.parse(in);
                String q = r.quant() == null ? "Q4_K_M" : r.quant();          // pretend the chooser picked Q4_K_M
                System.out.println(in);
                System.out.println("  " + r + "\n  name " + r.displayName(q) + "\n  dir  " + r.directoryName(q));
            } catch (IllegalArgumentException e) {
                System.out.println(in + "\n  error: " + e.getMessage());
            }
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.ArrayList;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TreeMap;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class ListRepoFiles {
    record RepoFile(String path, long size, String sha256) {}            // sha256 is null for files stored in git

    /** The read-only part of the HubClient from lesson 23, Example 15. */
    static final class HubClient {
        private final HttpClient http = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build();
        private final ObjectMapper json = new ObjectMapper();
        private final String endpoint;

        HubClient(String endpoint) { this.endpoint = endpoint; }

        JsonNode getJson(String path) throws Exception {
            HttpResponse<String> r = http.send(HttpRequest.newBuilder(URI.create(endpoint + path)).build(), HttpResponse.BodyHandlers.ofString());
            if (r.statusCode() != 200) throw new IllegalStateException("GET " + path + " -> " + r.statusCode());
            return json.readTree(r.body());
        }

        String commit(String repo, String revision) throws Exception {
            if (revision.matches("[0-9a-f]{40}")) return revision;
            for (JsonNode b : getJson("/api/models/" + repo + "/refs").get("branches"))
                if (b.get("name").asText().equals(revision)) return b.get("targetCommit").asText();
            throw new IllegalArgumentException("no branch " + revision + " in " + repo);
        }

        List<RepoFile> files(String repo, String commit) throws Exception {
            List<RepoFile> out = new ArrayList<>();
            for (JsonNode e : getJson("/api/models/" + repo + "/tree/" + commit + "?recursive=true"))
                if (e.get("type").asText().equals("file"))
                    out.add(new RepoFile(e.get("path").asText(), e.get("size").asLong(), e.has("lfs") ? e.get("lfs").get("oid").asText() : null));
            return out;
        }
    }

    static final Pattern QUANT = Pattern.compile("(?i)[-_.](IQ\\d_[A-Z]+|Q\\d_K(?:_[SML])?|Q\\d_\\d|BF16|F16|F32)(?=[-.])");

    static String quantOf(String path) {
        Matcher m = QUANT.matcher(path.substring(path.lastIndexOf('/') + 1));
        return m.find() ? m.group(1).toUpperCase(Locale.ROOT) : null;
    }

    static final String COMMIT = "4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c";
    static final String TREE = """
        [{"type":"file","path":"README.md","size":2210,"oid":"6f2b"},
         {"type":"file","path":"config.json","size":663,"oid":"8a1c"},
         {"type":"file","path":"Coder-7B-Instruct-Q4_K_M.gguf","size":4683071008,"oid":"3d1f","lfs":{"oid":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","size":4683071008}},
         {"type":"file","path":"Coder-7B-Instruct-Q6_K.gguf","size":6254199584,"oid":"7c2e","lfs":{"oid":"1b4f0e9800d5d1f0b8a6c3e4f7a2b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6","size":6254199584}},
         {"type":"file","path":"Coder-7B-Instruct-Q8_0-00001-of-00002.gguf","size":4049262608,"oid":"5e4d","lfs":{"oid":"2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae","size":4049262608}},
         {"type":"file","path":"Coder-7B-Instruct-Q8_0-00002-of-00002.gguf","size":4049262608,"oid":"5e4e","lfs":{"oid":"fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9","size":4049262608}},
         {"type":"file","path":"mmproj-Coder-7B-F16.gguf","size":1354163456,"oid":"9a8b","lfs":{"oid":"baa5a0964d3320fbc0c6a922140453c8513ea24ab8fd0577034804a967248096","size":1354163456}}]
        """;

    public static void main(String[] args) throws Exception {
        HttpServer hub = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        hub.createContext("/api/models/", ex -> {                        // a fake Hub: refs and tree listing only
            String p = ex.getRequestURI().getPath();
            String body = p.endsWith("/refs") ? "{\"branches\":[{\"name\":\"main\",\"targetCommit\":\"" + COMMIT + "\"}],\"tags\":[]}"
                        : p.contains("/tree/" + COMMIT) ? TREE : null;
            byte[] b = body == null ? "{\"error\":\"not found\"}".getBytes() : body.getBytes();
            ex.sendResponseHeaders(body == null ? 404 : 200, b.length);
            try (var out = ex.getResponseBody()) { out.write(b); }
        });
        hub.start();
        HubClient client = new HubClient("http://127.0.0.1:" + hub.getAddress().getPort());
        String repo = "example-org/Coder-7B-Instruct-GGUF";
        String commit = client.commit(repo, "main");
        List<RepoFile> files = client.files(repo, commit);
        System.out.println("main -> " + commit + ", " + files.size() + " files");

        Map<String, long[]> byQuant = new TreeMap<>();                   // quant -> {files, bytes}
        for (RepoFile f : files) {
            String q = quantOf(f.path());
            boolean model = f.path().endsWith(".gguf") && !f.path().contains("mmproj") && !f.path().contains("imatrix");
            System.out.printf(Locale.ROOT, "  %-44s %,15d  %s%n", f.path(), f.size(), !model ? "(not a model file)" : q);
            if (model && q != null) { long[] g = byQuant.computeIfAbsent(q, k -> new long[2]); g[0]++; g[1] += f.size(); }
        }
        byQuant.forEach((q, g) -> System.out.printf(Locale.ROOT, "%-7s %d file(s) %6.2f GiB%n", q, g[0], g[1] / 1073741824.0));
        hub.stop(0);
    }
}

import java.util.Comparator;
import java.util.LinkedHashMap;
import java.util.Locale;
import java.util.Map;
import java.util.Optional;

public class ChooseQuant {
    /** The parts of Project 4's ModelConfig (lesson 16) that the KV cache and compute estimate need. */
    record ModelConfig(long layers, long kvHeads, long headDim, long ffn, long vocab) {
        long kvBytes(long ctx, int bytesPerValue) { return 2 * layers * kvHeads * headDim * bytesPerValue * ctx; }
        long computeBytes() { return (vocab + 2 * ffn) * 512 * 4; }        // Project 4 estimate at -ub 512
    }

    static final double GIB = 1L << 30;

    /** The largest quant whose weights + KV cache + compute fit the budget. */
    static Optional<String> choose(Map<String, Long> quantBytes, ModelConfig cfg, long ctx, long budget) {
        long overhead = cfg.kvBytes(ctx, 2) + cfg.computeBytes();
        return quantBytes.entrySet().stream()
                .filter(e -> e.getValue() + overhead <= budget)
                .max(Comparator.comparingLong(Map.Entry::getValue))
                .map(Map.Entry::getKey);
    }

    public static void main(String[] args) {
        Map<String, Long> sizes = new LinkedHashMap<>();                  // summed per quant, as in Example 2
        sizes.put("Q3_K_M", 3_808_391_200L);
        sizes.put("IQ4_XS", 4_250_000_000L);
        sizes.put("Q4_K_M", 4_683_071_008L);
        sizes.put("Q5_K_M", 5_444_831_264L);
        sizes.put("Q6_K", 6_254_199_584L);
        sizes.put("Q8_0", 8_098_525_216L);
        ModelConfig cfg = new ModelConfig(28, 4, 128, 18_944, 152_064);   // a 7B shape with 4 KV heads

        System.out.printf(Locale.ROOT, "KV cache: %.0f MiB at 8K, %.0f MiB at 32K; compute %.0f MiB%n",
                cfg.kvBytes(8192, 2) / 1048576.0, cfg.kvBytes(32768, 2) / 1048576.0, cfg.computeBytes() / 1048576.0);
        sizes.forEach((q, b) -> System.out.printf(Locale.ROOT, "  %-7s file %5.2f GiB, total at 8K %5.2f GiB, at 32K %5.2f GiB%n", q, b / GIB,
                (b + cfg.kvBytes(8192, 2) + cfg.computeBytes()) / GIB, (b + cfg.kvBytes(32768, 2) + cfg.computeBytes()) / GIB));

        long[][] cases = {{4, 8192}, {6, 8192}, {8, 8192}, {8, 32768}, {12, 32768}};
        for (long[] c : cases) {
            Optional<String> pick = choose(sizes, cfg, c[1], c[0] << 30);
            System.out.printf("budget %2d GiB, ctx %5d -> %s%n", c[0], c[1], pick.orElse("nothing fits; use a smaller context or a smaller model"));
        }
    }
}

import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.TreeSet;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

public class SplitFiles {
    /** prefix-00002-of-00004.gguf, the naming rule of llama.cpp (llama_split_path and common/download.cpp). */
    static final Pattern SPLIT = Pattern.compile("(?i)^(.+)-(\\d{5})-of-(\\d{5})\\.gguf$");

    record Part(String path, int index, int count) {}
    record ModelFiles(String prefix, int count, List<String> paths) {
        boolean complete() { return paths.size() == count; }
        String first() { return paths.get(0); }                           // llama.cpp must be given the first part
    }

    static List<ModelFiles> group(List<String> paths) {
        Map<String, TreeMap<Integer, Part>> groups = new TreeMap<>();
        Map<String, Integer> counts = new TreeMap<>();
        for (String p : paths) {
            if (!p.endsWith(".gguf")) continue;
            Matcher m = SPLIT.matcher(p);
            Part part = m.matches() ? new Part(p, Integer.parseInt(m.group(2)), Integer.parseInt(m.group(3))) : new Part(p, 1, 1);
            String prefix = m.matches() ? m.group(1) : p.substring(0, p.length() - 5);
            String key = prefix + "#" + part.count();                     // same prefix and same count, as llama.cpp checks
            groups.computeIfAbsent(key, k -> new TreeMap<>()).put(part.index(), part);
            counts.put(key, part.count());
        }
        List<ModelFiles> out = new ArrayList<>();
        groups.forEach((key, parts) -> out.add(new ModelFiles(key.substring(0, key.indexOf('#')), counts.get(key),
                parts.values().stream().map(Part::path).toList())));
        return out;
    }

    public static void main(String[] args) {
        List<String> listing = List.of(
                "README.md",
                "Coder-32B-Q4_K_M.gguf",
                "Q8_0/Coder-32B-Q8_0-00002-of-00003.gguf",                   // listed out of order on purpose
                "Q8_0/Coder-32B-Q8_0-00001-of-00003.gguf",
                "Q8_0/Coder-32B-Q8_0-00003-of-00003.gguf",
                "BF16/Coder-32B-BF16-00001-of-00002.gguf");                 // part 2 missing
        for (ModelFiles mf : group(listing)) {
            System.out.println(mf.prefix() + ": " + mf.paths().size() + " of " + mf.count() + " part(s)"
                    + (mf.complete() ? ", load with " + mf.first() : ", INCOMPLETE, missing " + missing(mf)));
        }
    }

    static TreeSet<Integer> missing(ModelFiles mf) {
        TreeSet<Integer> all = new TreeSet<>();
        for (int i = 1; i <= mf.count(); i++) all.add(i);
        for (String p : mf.paths()) { Matcher m = SPLIT.matcher(p); if (m.matches()) all.remove(Integer.parseInt(m.group(2))); }
        return all;
    }
}

import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.security.DigestInputStream;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.Random;
import java.util.concurrent.atomic.AtomicInteger;
import static java.nio.file.StandardOpenOption.*;

public class PullFiles {
    interface Progress { void update(long done, long total); }

    /** A shorter form of lesson 28's Downloader (Example 15): resume with If-Range, retries, SHA-256, atomic rename. */
    static final class Downloader {
        private final HttpClient http = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build();

        void download(URI uri, Path target, long size, String sha256, Progress progress) throws Exception {
            if (Files.exists(target)) return;
            Path part = Path.of(target + ".part"), etag = Path.of(target + ".etag");
            for (int attempt = 1; ; attempt++) {
                try { fetch(uri, part, etag, size, progress); break; }
                catch (IOException e) {
                    if (attempt == 5) throw e;
                    System.out.println("    attempt " + attempt + " failed: " + e.getMessage() + "; resuming");
                }                                                      // a real client waits with backoff here
            }
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            try (InputStream in = new DigestInputStream(Files.newInputStream(part), md)) { in.transferTo(OutputStream.nullOutputStream()); }
            if (!HexFormat.of().formatHex(md.digest()).equals(sha256)) { Files.delete(part); throw new IllegalStateException("SHA-256 mismatch"); }
            Files.move(part, target, StandardCopyOption.ATOMIC_MOVE);
            Files.deleteIfExists(etag);
        }

        private void fetch(URI uri, Path part, Path etag, long size, Progress progress) throws Exception {
            long have = Files.exists(part) ? Files.size(part) : 0;
            HttpRequest.Builder b = HttpRequest.newBuilder(uri);
            if (have > 0) b.header("Range", "bytes=" + have + "-");
            if (have > 0 && Files.exists(etag)) b.header("If-Range", Files.readString(etag));
            HttpResponse<InputStream> r = http.send(b.build(), HttpResponse.BodyHandlers.ofInputStream());
            if (r.statusCode() >= 500 || r.statusCode() == 429) { r.body().close(); throw new IOException("status " + r.statusCode()); }
            if (r.statusCode() != 200 && r.statusCode() != 206) throw new IllegalStateException("status " + r.statusCode());
            if (r.statusCode() == 200) have = 0;
            if (r.headers().firstValue("etag").isPresent()) Files.writeString(etag, r.headers().firstValue("etag").get());
            try (InputStream in = r.body(); OutputStream out = Files.newOutputStream(part, CREATE, WRITE, have > 0 ? APPEND : TRUNCATE_EXISTING)) {
                byte[] buf = new byte[64 * 1024];
                for (int n; (n = in.read(buf)) >= 0; ) { out.write(buf, 0, n); have += n; progress.update(have, size); }
            }
            if (have != size) throw new IOException("incomplete");
        }
    }

    static String sha256(byte[] b) throws Exception { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(b)); }

    public static void main(String[] args) throws Exception {
        Map<String, byte[]> blobs = new LinkedHashMap<>();                 // sha256 -> content, as the CDN stores it
        Map<String, String> paths = new LinkedHashMap<>();                 // file path in the repo -> sha256
        for (int i = 1; i <= 2; i++) {
            byte[] data = new byte[300_000];
            new Random(i).nextBytes(data);
            String sha = sha256(data);
            blobs.put(sha, data);
            paths.put("Coder-7B-Instruct-Q8_0-0000" + i + "-of-00002.gguf", sha);
        }
        AtomicInteger cdnRequests = new AtomicInteger();
        HttpServer hub = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        hub.createContext("/", ex -> {
            String p = ex.getRequestURI().getPath();
            if (p.contains("/resolve/")) {                                 // the Hub redirects to the CDN, named by hash
                ex.getResponseHeaders().add("Location", "/cdn/" + paths.get(p.substring(p.lastIndexOf('/') + 1)));
                ex.sendResponseHeaders(302, -1);
                ex.close();
                return;
            }
            int n = cdnRequests.incrementAndGet();
            String sha = p.substring(5);
            byte[] data = blobs.get(sha);
            String range = ex.getRequestHeaders().getFirst("Range"), ifRange = ex.getRequestHeaders().getFirst("If-Range");
            int start = range != null && ("\"" + sha + "\"").equals(ifRange) ? Integer.parseInt(range.substring(6, range.length() - 1)) : 0;
            ex.getResponseHeaders().add("ETag", "\"" + sha + "\"");
            if (start > 0) ex.getResponseHeaders().add("Content-Range", "bytes " + start + "-" + (data.length - 1) + "/" + data.length);
            ex.sendResponseHeaders(start > 0 ? 206 : 200, data.length - start);
            OutputStream out = ex.getResponseBody();
            if (n == 2) { out.write(data, 0, 120_000); out.flush(); throw new RuntimeException("drop"); }  // second file: drop at 40%
            out.write(data, start, data.length - start);
            out.close();
        });
        hub.start();
        String base = "http://127.0.0.1:" + hub.getAddress().getPort() + "/example-org/Coder-7B-Instruct-GGUF/resolve/4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c/";
        Path blobDir = Files.createDirectories(Files.createTempDirectory("loop-home").resolve("blobs"));
        Downloader downloader = new Downloader();
        for (var e : paths.entrySet()) {
            System.out.println("pulling " + e.getKey());
            int[] last = {0};
            downloader.download(URI.create(base + e.getKey()), blobDir.resolve("sha256-" + e.getValue()), 300_000, e.getValue(), (done, total) -> {
                int q = (int) (done * 4 / total);
                if (q > last[0]) { last[0] = q; System.out.println("    " + q * 25 + "%"); }
            });
        }
        try (var s = Files.list(blobDir)) { s.map(p -> p.getFileName().toString().substring(0, 23) + "...").sorted().forEach(System.out::println); }
        System.out.println("CDN requests: " + cdnRequests.get());
        hub.stop(0);
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.SerializationFeature;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.util.List;
import java.util.stream.Stream;

public class Registry {
    record FileEntry(String path, long size, String sha256) {}
    record Manifest(String name, String repo, String revision, String commit, String quant, List<FileEntry> files, String pulledAt) {}

    static final ObjectMapper JSON = new ObjectMapper().enable(SerializationFeature.INDENT_OUTPUT);

    /** home/blobs/sha256-<hex> holds content; home/models/<dir>/ holds manifest.json and one link per file. */
    static Path register(Path home, String dir, Manifest m) throws Exception {
        Path modelDir = Files.createDirectories(home.resolve("models").resolve(dir));
        for (FileEntry f : m.files()) {
            Path blob = home.resolve("blobs").resolve("sha256-" + f.sha256());
            if (!Files.exists(blob)) throw new IllegalStateException("missing blob for " + f.path());
            Path link = modelDir.resolve(Path.of(f.path()).getFileName().toString());   // original name: llama.cpp finds the other parts
            Files.deleteIfExists(link);
            Files.createSymbolicLink(link, modelDir.relativize(blob));
        }
        Path tmp = modelDir.resolve("manifest.json.tmp");
        JSON.writeValue(tmp.toFile(), m);
        Files.move(tmp, modelDir.resolve("manifest.json"), java.nio.file.StandardCopyOption.ATOMIC_MOVE);
        return modelDir;
    }

    static void tree(Path home) throws Exception {
        try (Stream<Path> s = Files.walk(home)) {
            for (Path p : s.sorted().toList()) {
                if (p.equals(home)) continue;
                String rel = home.relativize(p).toString().replaceAll("[0-9a-f]{56}", "...");
                String extra = Files.isSymbolicLink(p) ? " -> " + Files.readSymbolicLink(p).toString().replaceAll("[0-9a-f]{56}", "...")
                             : Files.isRegularFile(p) ? " (" + Files.size(p) + " bytes)" : "/";
                System.out.println("  " + rel + extra);
            }
        }
    }

    public static void main(String[] args) throws Exception {
        Path home = Files.createTempDirectory("loop-home");
        Files.createDirectories(home.resolve("blobs"));
        List<FileEntry> files = new java.util.ArrayList<>();
        for (int i = 1; i <= 2; i++) {                                      // the two blobs Example 5 downloaded
            byte[] data = ("part " + i).getBytes();
            String sha = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(data));
            Files.write(home.resolve("blobs/sha256-" + sha), data);
            files.add(new FileEntry("Coder-7B-Instruct-Q8_0-0000" + i + "-of-00002.gguf", data.length, sha));
        }
        String commit = "4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c";
        register(home, "example-org--Coder-7B-Instruct-GGUF--Q8_0", new Manifest("example-org/Coder-7B-Instruct-GGUF:Q8_0",
                "example-org/Coder-7B-Instruct-GGUF", "main", commit, "Q8_0", files, "2026-10-03T12:00:00Z"));
        register(home, "example-org--Coder-7B-Instruct-GGUF--Q8_0--v1.0", new Manifest("example-org/Coder-7B-Instruct-GGUF:Q8_0@v1.0",
                "example-org/Coder-7B-Instruct-GGUF", "v1.0", commit, "Q8_0", files, "2026-10-03T12:05:00Z"));
        tree(home);
        System.out.println(Files.readString(home.resolve("models/example-org--Coder-7B-Instruct-GGUF--Q8_0/manifest.json")));
        Path first = home.resolve("models/example-org--Coder-7B-Instruct-GGUF--Q8_0/Coder-7B-Instruct-Q8_0-00001-of-00002.gguf");
        System.out.println("read through the link: " + Files.readString(first) + ", same file as the blob: "
                + Files.isSameFile(first, home.resolve("blobs/sha256-" + files.get(0).sha256())));
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.security.DigestInputStream;
import java.security.MessageDigest;
import java.util.*;
import java.util.concurrent.Callable;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Stream;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import picocli.CommandLine.ParentCommand;
import picocli.CommandLine.ScopeType;
import static java.nio.file.StandardOpenOption.*;

/** Project 9: loop pull against a fake Hub. */
@Command(name = "loop", mixinStandardHelpOptions = true, version = "loop 0.1.0",
        subcommands = {LoopPull.Pull.class})
public class LoopPull {
    @Option(names = "--home", scope = ScopeType.INHERIT, defaultValue = "${sys:loop.home:-${sys:user.home}/.loop}") Path home;
    @Option(names = "--hub", scope = ScopeType.INHERIT, defaultValue = "${HF_ENDPOINT:-https://huggingface.co}") String hubUrl;

    // ---- model references (Example 1) and the registry (Example 6) ----
    record ModelRef(String repo, String quant, String revision) {
        static final Pattern FORMAT = Pattern.compile("(?:https://huggingface\\.co/|hf\\.co/)?([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)(?::([A-Za-z0-9_]+))?(?:@([A-Za-z0-9_./-]+))?");
        static ModelRef parse(String text) {
            Matcher m = FORMAT.matcher(text.strip());
            if (!m.matches() || m.group(1).contains("..")) throw new IllegalArgumentException("not a model reference: " + text);
            return new ModelRef(m.group(1), m.group(2) == null ? null : m.group(2).toUpperCase(Locale.ROOT), m.group(3) == null ? "main" : m.group(3));
        }
        String name(String q) { return repo + ":" + q + (revision.equals("main") ? "" : "@" + revision); }
        String dir(String q) { return repo.replace("/", "--") + "--" + q + (revision.equals("main") ? "" : "--" + revision.replace('/', '_')); }
    }
    record FileEntry(String path, long size, String sha256) {}
    record Manifest(String name, String repo, String revision, String commit, String quant, List<FileEntry> files, String pulledAt) {
        long size() { return files.stream().mapToLong(FileEntry::size).sum(); }
    }
    static final ObjectMapper JSON = new ObjectMapper();

    // ---- the Hub client (lesson 23) and the downloader (lesson 28) ----
    record RepoFile(String path, long size, String sha256) {}
    static final class Hub {
        final HttpClient http = HttpClient.newBuilder().followRedirects(HttpClient.Redirect.NORMAL).build();
        final String endpoint;
        Hub(String endpoint) { this.endpoint = endpoint; }
        String get(String path) throws Exception {
            HttpResponse<String> r = http.send(HttpRequest.newBuilder(URI.create(endpoint + path)).build(), HttpResponse.BodyHandlers.ofString());
            if (r.statusCode() != 200) throw new IllegalStateException("GET " + path + " -> " + r.statusCode());
            return r.body();
        }
        String commit(String repo, String rev) throws Exception {
            if (rev.matches("[0-9a-f]{40}")) return rev;
            JsonNode refs = JSON.readTree(get("/api/models/" + repo + "/refs"));
            for (String kind : List.of("branches", "tags"))
                for (JsonNode b : refs.path(kind)) if (b.get("name").asText().equals(rev)) return b.get("targetCommit").asText();
            throw new IllegalArgumentException("no branch or tag " + rev);
        }
        List<RepoFile> files(String repo, String commit) throws Exception {
            List<RepoFile> out = new ArrayList<>();
            for (JsonNode e : JSON.readTree(get("/api/models/" + repo + "/tree/" + commit + "?recursive=true")))
                if (e.get("type").asText().equals("file"))
                    out.add(new RepoFile(e.get("path").asText(), e.get("size").asLong(), e.has("lfs") ? e.get("lfs").get("oid").asText() : null));
            return out;
        }
        URI resolve(String repo, String commit, String path) { return URI.create(endpoint + "/" + repo + "/resolve/" + commit + "/" + path); }

        void download(URI uri, Path target, long size, String sha256) throws Exception {
            Path part = Path.of(target + ".part"), etag = Path.of(target + ".etag");
            for (int attempt = 1; ; attempt++) {
                try { fetch(uri, part, etag, size); break; }
                catch (IOException e) { if (attempt == 5) throw e; Thread.sleep(Math.min(8000, 500L << attempt) / 100); }
            }
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            try (InputStream in = new DigestInputStream(Files.newInputStream(part), md)) { in.transferTo(OutputStream.nullOutputStream()); }
            if (!HexFormat.of().formatHex(md.digest()).equals(sha256)) { Files.delete(part); throw new IllegalStateException("SHA-256 mismatch: " + target.getFileName()); }
            Files.move(part, target, StandardCopyOption.ATOMIC_MOVE);
            Files.deleteIfExists(etag);
        }
        void fetch(URI uri, Path part, Path etag, long size) throws Exception {
            long have = Files.exists(part) ? Files.size(part) : 0;
            HttpRequest.Builder b = HttpRequest.newBuilder(uri);
            if (have > 0) b.header("Range", "bytes=" + have + "-");
            if (have > 0 && Files.exists(etag)) b.header("If-Range", Files.readString(etag));
            HttpResponse<InputStream> r = http.send(b.build(), HttpResponse.BodyHandlers.ofInputStream());
            if (r.statusCode() >= 500 || r.statusCode() == 429) { r.body().close(); throw new IOException("status " + r.statusCode()); }
            if (r.statusCode() != 200 && r.statusCode() != 206) throw new IllegalStateException("status " + r.statusCode());
            if (r.statusCode() == 200) have = 0;
            if (r.headers().firstValue("etag").isPresent()) Files.writeString(etag, r.headers().firstValue("etag").get());
            try (InputStream in = r.body(); OutputStream out = Files.newOutputStream(part, CREATE, WRITE, have > 0 ? APPEND : TRUNCATE_EXISTING)) {
                have += in.transferTo(out);
            }
            if (have != size) throw new IOException("incomplete");
        }
    }

    // ---- memory math (Project 4) ----
    static long kvBytes(long layers, long kvHeads, long headDim, long ctx) { return 2 * layers * kvHeads * headDim * 2 * ctx; }
    static long computeBytes(long vocab, long ffn) { return (vocab + 2 * ffn) * 512 * 4; }
    static final Pattern QUANT = Pattern.compile("(?i)[-_.](IQ\\d_[A-Z]+|Q\\d_K(?:_[SML])?|Q\\d_\\d|BF16|F16|F32)(?=[-.])");
    static String mib(long bytes) { return String.format(Locale.ROOT, "%.2f MiB", bytes / 1048576.0); }
    static final Pattern SPLIT = Pattern.compile("-(\\d{5})-of-(\\d{5})\\.gguf$");

    /** The size converter of lesson 26 (Example 11), shortened: 512MiB, 3.5MiB, 8GiB, 8GB. */
    static class ByteSize implements CommandLine.ITypeConverter<Long> {
        public Long convert(String v) {
            Matcher m = Pattern.compile("(?i)(\\d+(?:\\.\\d+)?)\\s*([KMGT])?(i)?B?").matcher(v.strip());
            if (!m.matches()) throw new CommandLine.TypeConversionException("'" + v + "' is not a size such as 8GiB");
            int exp = m.group(2) == null ? 0 : "KMGT".indexOf(Character.toUpperCase(m.group(2).charAt(0))) + 1;
            double unit = Math.pow(m.group(3) == null && exp > 0 ? 1000 : 1024, exp);
            return (long) (Double.parseDouble(m.group(1)) * unit);
        }
    }

    // ---- commands ----
    @Command(name = "pull", description = "Download a GGUF model from Hugging Face.")
    static class Pull implements Callable<Integer> {
        @ParentCommand LoopPull loop;
        @Parameters(paramLabel = "MODEL", description = "repo[:quant][@revision]") String model;
        @Option(names = "--mem", converter = ByteSize.class, description = "Memory budget; picks the largest quant that fits") Long mem;
        @Option(names = {"-c", "--ctx-size"}, defaultValue = "4096") long ctx;

        public Integer call() throws Exception {
            ModelRef ref = ModelRef.parse(model);
            Hub hub = new Hub(loop.hubUrl);
            String commit = hub.commit(ref.repo(), ref.revision());
            List<RepoFile> files = hub.files(ref.repo(), commit);
            Map<String, List<RepoFile>> byQuant = new TreeMap<>();
            for (RepoFile f : files) {
                Matcher m = QUANT.matcher(f.path().substring(f.path().lastIndexOf('/') + 1));
                if (f.path().endsWith(".gguf") && !f.path().contains("mmproj") && f.sha256() != null && m.find())
                    byQuant.computeIfAbsent(m.group(1).toUpperCase(Locale.ROOT), k -> new ArrayList<>()).add(f);
            }
            byQuant.values().forEach(l -> l.sort(Comparator.comparing(RepoFile::path)));     // split parts in order
            String quant = ref.quant();
            if (quant == null) {
                long overhead = 0;
                if (files.stream().anyMatch(f -> f.path().equals("config.json"))) {
                    JsonNode c = JSON.readTree(hub.get("/" + ref.repo() + "/resolve/" + commit + "/config.json"));
                    long heads = c.get("num_attention_heads").asLong();
                    overhead = kvBytes(c.get("num_hidden_layers").asLong(), c.get("num_key_value_heads").asLong(), c.get("hidden_size").asLong() / heads, ctx)
                            + computeBytes(c.get("vocab_size").asLong(), c.get("intermediate_size").asLong());
                }
                long need = overhead, budget = mem == null ? Long.MAX_VALUE : mem;   // no budget: the largest quant
                Map.Entry<String, Long> best = byQuant.entrySet().stream()
                        .map(e -> Map.entry(e.getKey(), e.getValue().stream().mapToLong(RepoFile::size).sum() + need))
                        .filter(e -> e.getValue() <= budget).max(Map.Entry.comparingByValue())
                        .orElseThrow(() -> new IllegalStateException("no quant fits in " + mib(budget) + " at -c " + ctx));
                quant = best.getKey();
                System.out.println("chose " + quant + ": needs " + mib(best.getValue()) + " (KV cache and compute " + mib(overhead) + ")");
            }
            List<RepoFile> parts = byQuant.get(quant);
            if (parts == null) throw new IllegalArgumentException("no " + quant + " files; available: " + byQuant.keySet());
            Matcher sp = SPLIT.matcher(parts.get(0).path());
            if (sp.find() && Integer.parseInt(sp.group(2)) != parts.size())
                throw new IllegalStateException(quant + " has " + parts.size() + " of " + Integer.parseInt(sp.group(2)) + " parts");
            Path dir = loop.home.resolve("models").resolve(ref.dir(quant));
            if (Files.exists(dir.resolve("manifest.json"))) { System.out.println(ref.name(quant) + " is already pulled"); return 0; }
            Path blobs = Files.createDirectories(loop.home.resolve("blobs"));
            List<FileEntry> entries = new ArrayList<>();
            for (RepoFile f : parts) {
                Path blob = blobs.resolve("sha256-" + f.sha256());
                boolean have = Files.exists(blob);
                if (!have) hub.download(hub.resolve(ref.repo(), commit, f.path()), blob, f.size(), f.sha256());
                System.out.println((have ? "  have     " : "  pulled   ") + f.path() + " (" + mib(f.size()) + ")");
                entries.add(new FileEntry(f.path(), f.size(), f.sha256()));
            }
            Files.createDirectories(dir);
            for (FileEntry e : entries) {
                Path link = dir.resolve(Path.of(e.path()).getFileName().toString());
                if (!Files.exists(link, java.nio.file.LinkOption.NOFOLLOW_LINKS)) Files.createSymbolicLink(link, dir.relativize(blobs.resolve("sha256-" + e.sha256())));
            }
            Manifest m = new Manifest(ref.name(quant), ref.repo(), ref.revision(), commit, quant, entries, "2026-10-03T12:00:00Z");
            JSON.writeValue(dir.resolve("manifest.json.tmp").toFile(), m);
            Files.move(dir.resolve("manifest.json.tmp"), dir.resolve("manifest.json"), StandardCopyOption.ATOMIC_MOVE);
            System.out.println("pulled " + m.name());
            return 0;
        }
    }

    // ---- demo: a fake Hub with a tiny model in three quants (random bytes stand in for GGUF files) ----
    static HttpServer fakeHub(String repo, String commit) throws Exception {
        Map<String, byte[]> files = new LinkedHashMap<>();
        files.put("config.json", "{\"num_hidden_layers\":2,\"hidden_size\":128,\"num_attention_heads\":4,\"num_key_value_heads\":2,\"intermediate_size\":256,\"vocab_size\":64}".getBytes());
        Random random = new Random(9);
        for (String[] f : new String[][] {{"Tiny-Coder-F16.gguf", "608064"}, {"Tiny-Coder-Q4_0.gguf", "171840"},
                {"Tiny-Coder-Q8_0-00001-of-00002.gguf", "168160"}, {"Tiny-Coder-Q8_0-00002-of-00002.gguf", "155744"}}) {
            byte[] b = new byte[Integer.parseInt(f[1])];
            random.nextBytes(b);
            files.put(f[0], b);
        }
        StringJoiner tree = new StringJoiner(",", "[", "]");
        Map<String, byte[]> cdn = new HashMap<>();
        Map<String, String> shaOf = new HashMap<>();
        for (var e : files.entrySet()) {
            String sha = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(e.getValue()));
            boolean lfs = e.getKey().endsWith(".gguf");
            if (lfs) { cdn.put(sha, e.getValue()); shaOf.put(e.getKey(), sha); }
            tree.add("{\"type\":\"file\",\"path\":\"" + e.getKey() + "\",\"size\":" + e.getValue().length
                    + (lfs ? ",\"lfs\":{\"oid\":\"" + sha + "\",\"size\":" + e.getValue().length + "}" : "") + "}");
        }
        HttpServer s = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        s.createContext("/", ex -> {
            String p = ex.getRequestURI().getPath();
            byte[] body;
            if (p.equals("/api/models/" + repo + "/refs")) body = ("{\"branches\":[{\"name\":\"main\",\"targetCommit\":\"" + commit + "\"}],"
                    + "\"tags\":[{\"name\":\"v1.0\",\"targetCommit\":\"" + commit + "\"}]}").getBytes();
            else if (p.equals("/api/models/" + repo + "/tree/" + commit)) body = tree.toString().getBytes();
            else if (p.startsWith("/" + repo + "/resolve/" + commit + "/")) {
                String name = p.substring(p.lastIndexOf('/') + 1);
                if (shaOf.containsKey(name)) {                                  // LFS files: redirect to the CDN
                    ex.getResponseHeaders().add("Location", "/cdn/" + shaOf.get(name)); ex.sendResponseHeaders(302, -1); ex.close(); return;
                }
                body = files.get(name);
            } else body = p.startsWith("/cdn/") ? cdn.get(p.substring(5)) : null;
            if (body == null) { ex.sendResponseHeaders(404, -1); ex.close(); return; }
            ex.sendResponseHeaders(200, body.length);
            try (var out = ex.getResponseBody()) { out.write(body); }
        });
        s.start();
        return s;
    }

    public static void main(String[] args) throws Exception {
        if (args.length > 0) { System.exit(new CommandLine(new LoopPull()).execute(args)); }
        HttpServer hub = fakeHub("example-org/Tiny-Coder-GGUF", "4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c");
        String[] common = {"--home", Files.createTempDirectory("loop-home").toString(), "--hub", "http://127.0.0.1:" + hub.getAddress().getPort()};
        String[][] demo = {{"pull", "example-org/Tiny-Coder-GGUF", "--mem", "3.5MiB"}, {"pull", "example-org/Tiny-Coder-GGUF", "--mem", "3MiB"},
                {"pull", "example-org/Tiny-Coder-GGUF:Q8_0"}, {"pull", "example-org/Tiny-Coder-GGUF:Q8_0@v1.0"},
                {"pull", "hf.co/example-org/Tiny-Coder-GGUF:q4_0"}, {"pull", "example-org/Tiny-Coder-GGUF:Q5_K_M"}};
        for (String[] d : demo) {
            CommandLine cl = new CommandLine(new LoopPull());
            cl.setErr(new java.io.PrintWriter(System.out, true));
            cl.setExecutionExceptionHandler((ex, c, r) -> { System.out.println("loop " + c.getCommandName() + ": " + ex.getMessage()); return 1; });
            System.out.println("$ loop " + String.join(" ", d));
            int code = cl.execute(Stream.concat(Arrays.stream(d), Arrays.stream(common)).toArray(String[]::new));
            if (code != 0) System.out.println("(exit code " + code + ")");
        }
        try (Stream<Path> files = Files.walk(Path.of(common[1]))) {
            files.map(p -> Path.of(common[1]).relativize(p).toString().replaceAll("[0-9a-f]{56}", "...")).filter(p -> !p.isEmpty()).sorted().forEach(System.out::println);
        }
        hub.stop(0);
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Comparator;
import java.util.List;
import java.util.Locale;
import java.util.stream.Stream;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;

@Command(name = "list", aliases = "ls", description = "List downloaded models.")
public class ListModels implements Runnable {
    record FileEntry(String path, long size, String sha256) {}
    record Manifest(String name, String repo, String revision, String commit, String quant, List<FileEntry> files, String pulledAt) {
        long size() { return files.stream().mapToLong(FileEntry::size).sum(); }
    }

    record Row(String name, String quant, long sizeBytes, int files, String pulledAt) {}    // the --json shape

    static final ObjectMapper JSON = new ObjectMapper();

    static List<Manifest> manifests(Path home) throws Exception {
        List<Manifest> out = new ArrayList<>();
        Path models = home.resolve("models");
        if (!Files.isDirectory(models)) return out;
        try (Stream<Path> dirs = Files.list(models)) {
            for (Path d : dirs.toList()) {
                Path f = d.resolve("manifest.json");
                if (Files.exists(f)) out.add(JSON.readValue(f.toFile(), Manifest.class));   // a dir without manifest is an unfinished pull
            }
        }
        out.sort(Comparator.comparing(Manifest::name));
        return out;
    }

    static String human(long bytes) {
        return bytes >= 1L << 30 ? String.format(Locale.ROOT, "%.2f GiB", bytes / (double) (1L << 30))
                                  : String.format(Locale.ROOT, "%.1f MiB", bytes / (double) (1L << 20));
    }

    @Option(names = "--home", required = true) Path home;
    @Option(names = "--json", description = "Print JSON for scripts") boolean json;

    @Override
    public void run() {
        try {
            List<Manifest> all = manifests(home);
            if (json) {
                for (Manifest m : all)                                        // one JSON object per line
                    System.out.println(JSON.writeValueAsString(new Row(m.name(), m.quant(), m.size(), m.files().size(), m.pulledAt())));
                return;
            }
            int width = Math.max(4, all.stream().mapToInt(m -> m.name().length()).max().orElse(0));
            String format = "%-" + width + "s  %-7s %10s  %5s  %s%n";
            System.out.printf(format, "NAME", "QUANT", "SIZE", "FILES", "PULLED");
            for (Manifest m : all)
                System.out.printf(format, m.name(), m.quant(), human(m.size()), m.files().size(), m.pulledAt().substring(0, 10));
        } catch (Exception e) {
            throw new IllegalStateException(e);
        }
    }

    public static void main(String[] args) throws Exception {
        Path home = Files.createTempDirectory("loop-home");
        String c = "4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c";
        Manifest[] ms = {
            new Manifest("example-org/Coder-7B-Instruct-GGUF:Q8_0", "example-org/Coder-7B-Instruct-GGUF", "main", c, "Q8_0",
                    List.of(new FileEntry("Coder-7B-Instruct-Q8_0-00001-of-00002.gguf", 4_049_262_608L, "2c26"),
                            new FileEntry("Coder-7B-Instruct-Q8_0-00002-of-00002.gguf", 4_049_262_608L, "fcde")), "2026-10-02T09:30:00Z"),
            new Manifest("example-org/Coder-7B-Instruct-GGUF:Q4_K_M", "example-org/Coder-7B-Instruct-GGUF", "main", c, "Q4_K_M",
                    List.of(new FileEntry("Coder-7B-Instruct-Q4_K_M.gguf", 4_683_071_008L, "9f86")), "2026-10-03T12:00:00Z"),
            new Manifest("example-org/Tiny-Coder-GGUF:Q8_0", "example-org/Tiny-Coder-GGUF", "main", c, "Q8_0",
                    List.of(new FileEntry("Tiny-Coder-Q8_0.gguf", 115_200, "77aa")), "2026-10-03T12:05:00Z")};
        for (Manifest m : ms) {
            Path d = Files.createDirectories(home.resolve("models").resolve(m.name().replace("/", "--").replace(":", "--")));
            JSON.writeValue(d.resolve("manifest.json").toFile(), m);
        }
        Files.createDirectories(home.resolve("models/example-org--Unfinished-GGUF--Q4_0"));   // a pull that was interrupted

        new CommandLine(new ListModels()).execute("--home", home.toString());
        new CommandLine(new ListModels()).execute("--home", home.toString(), "--json");
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.ByteBuffer;
import java.nio.ByteOrder;
import java.nio.channels.FileChannel;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HexFormat;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TreeMap;

public class ShowModel {
    record FileEntry(String path, long size, String sha256) {}
    record Manifest(String name, String repo, String revision, String commit, String quant, List<FileEntry> files, String pulledAt) {}
    record TensorInfo(String name, long[] dims, int type, long offset) {}
    record Gguf(int version, Map<String, Object> kv, List<TensorInfo> tensors) {}

    // ggml type id -> {name, block size, type size}, from GGML_QUANT_SIZES in gguf-py (lesson 25)
    static final Map<Integer, Object[]> TYPES = Map.of(0, new Object[] {"F32", 1, 4}, 1, new Object[] {"F16", 1, 2},
            2, new Object[] {"Q4_0", 32, 18}, 8, new Object[] {"Q8_0", 32, 34}, 12, new Object[] {"Q4_K", 256, 144}, 14, new Object[] {"Q6_K", 256, 210});

    static long bytes(TensorInfo t) { long n = Arrays.stream(t.dims()).reduce(1, (a, b) -> a * b); Object[] ty = TYPES.get(t.type()); return n / (Integer) ty[1] * (Integer) ty[2]; }

    /** Writes a GGUF v3 file: metadata (UINT32, FLOAT32, STRING, string arrays), tensor infos, and zero-filled data. */
    static byte[] writeGguf(Map<String, Object> kv, List<TensorInfo> tensors) {
        ByteBuffer b = ByteBuffer.allocate(1 << 20).order(ByteOrder.LITTLE_ENDIAN);
        b.put("GGUF".getBytes(StandardCharsets.US_ASCII)).putInt(3).putLong(tensors.size()).putLong(kv.size());
        for (var e : kv.entrySet()) {
            str(b, e.getKey());
            switch (e.getValue()) {
                case Integer i -> b.putInt(4).putInt(i);
                case Float f -> b.putInt(6).putFloat(f);
                case String s -> { b.putInt(8); str(b, s); }
                case List<?> l -> { b.putInt(9).putInt(8).putLong(l.size()); l.forEach(x -> str(b, (String) x)); }
                default -> throw new IllegalArgumentException(e.getKey());
            }
        }
        long offset = 0;
        for (TensorInfo t : tensors) {
            str(b, t.name()); b.putInt(t.dims().length);
            for (long d : t.dims()) b.putLong(d);
            b.putInt(t.type()).putLong(offset);
            offset += (bytes(t) + 31) / 32 * 32;
        }
        while (b.position() % 32 != 0) b.put((byte) 0);
        byte[] out = Arrays.copyOf(b.array(), b.position() + (int) offset);   // data section: zeros
        return out;
    }

    static void str(ByteBuffer b, String s) { byte[] u = s.getBytes(StandardCharsets.UTF_8); b.putLong(u.length).put(u); }
    static String str(ByteBuffer b) { byte[] s = new byte[Math.toIntExact(b.getLong())]; b.get(s); return new String(s, StandardCharsets.UTF_8); }

    static Object value(ByteBuffer b, int type) {                       // the reader of Project 7 (lesson 25)
        return switch (type) {
            case 0, 1, 7 -> b.get(); case 2, 3 -> b.getShort(); case 4 -> Integer.toUnsignedLong(b.getInt()); case 5 -> b.getInt();
            case 6 -> b.getFloat(); case 8 -> str(b); case 10, 11 -> b.getLong(); case 12 -> b.getDouble();
            case 9 -> { int et = b.getInt(); long n = b.getLong(); List<Object> l = new ArrayList<>();
                        for (long i = 0; i < n; i++) l.add(value(b, et)); yield l; }
            default -> throw new IllegalArgumentException("bad value type " + type);
        };
    }

    static Gguf readGguf(Path file) throws Exception {
        try (FileChannel ch = FileChannel.open(file)) {
            ByteBuffer b = ch.map(FileChannel.MapMode.READ_ONLY, 0, Math.min(ch.size(), Integer.MAX_VALUE)).order(ByteOrder.LITTLE_ENDIAN);
            if (b.getInt() != 0x46554747) throw new IllegalArgumentException("not a GGUF file: " + file.getFileName());
            int version = b.getInt();
            long nTensors = b.getLong(), nKv = b.getLong();
            Map<String, Object> kv = new LinkedHashMap<>();
            for (long i = 0; i < nKv; i++) { String k = str(b); kv.put(k, value(b, b.getInt())); }
            List<TensorInfo> tensors = new ArrayList<>();
            for (long i = 0; i < nTensors; i++) {
                String name = str(b); long[] dims = new long[b.getInt()];
                for (int j = 0; j < dims.length; j++) dims[j] = b.getLong();
                tensors.add(new TensorInfo(name, dims, b.getInt(), b.getLong()));
            }
            return new Gguf(version, kv, tensors);
        }
    }

    static void show(Path home, String dir) throws Exception {
        Path modelDir = home.resolve("models").resolve(dir);
        Manifest m = new ObjectMapper().readValue(modelDir.resolve("manifest.json").toFile(), Manifest.class);
        Gguf g = readGguf(modelDir.resolve(m.files().get(0).path()));
        String arch = (String) g.kv().get("general.architecture");
        System.out.println(m.name() + "  (commit " + m.commit().substring(0, 7) + ", pulled " + m.pulledAt() + ")");
        System.out.println("  file      " + m.files().get(0).path() + ", GGUF v" + g.version());
        System.out.println("  arch      " + arch + ", name " + g.kv().get("general.name"));
        for (String k : List.of("context_length", "embedding_length", "block_count", "feed_forward_length", "attention.head_count", "attention.head_count_kv"))
            System.out.printf("  %-24s %s%n", k, g.kv().get(arch + "." + k));
        System.out.println("  vocabulary " + ((List<?>) g.kv().get("tokenizer.ggml.tokens")).size() + " tokens");
        Map<String, long[]> mix = new TreeMap<>();
        long params = 0;
        for (TensorInfo t : g.tensors()) {
            long n = Arrays.stream(t.dims()).reduce(1, (a, b) -> a * b);
            long[] x = mix.computeIfAbsent((String) TYPES.get(t.type())[0], k -> new long[3]);
            x[0]++; x[1] += n; x[2] += bytes(t); params += n;
        }
        System.out.printf(Locale.ROOT, "  parameters %,d%n", params);
        mix.forEach((ty, x) -> System.out.printf(Locale.ROOT, "  %-5s %d tensors, %,d params, %,d bytes%n", ty, x[0], x[1], x[2]));
    }

    public static void main(String[] args) throws Exception {
        Map<String, Object> kv = new LinkedHashMap<>();                  // a tiny Llama-architecture model
        kv.put("general.architecture", "llama"); kv.put("general.name", "Tiny-Coder"); kv.put("general.file_type", 7);
        kv.put("llama.context_length", 2048); kv.put("llama.embedding_length", 128); kv.put("llama.block_count", 2);
        kv.put("llama.feed_forward_length", 256); kv.put("llama.attention.head_count", 4); kv.put("llama.attention.head_count_kv", 2);
        List<String> tokens = new ArrayList<>();
        for (int i = 0; i < 64; i++) tokens.add("t" + i);
        kv.put("tokenizer.ggml.tokens", tokens);
        List<TensorInfo> tensors = new ArrayList<>(List.of(new TensorInfo("token_embd.weight", new long[] {128, 64}, 8, 0)));
        for (int l = 0; l < 2; l++)
            for (String n : List.of("attn_q", "attn_k", "attn_v", "attn_output"))
                tensors.add(new TensorInfo("blk." + l + "." + n + ".weight", new long[] {128, n.equals("attn_k") || n.equals("attn_v") ? 64 : 128}, 8, 0));
        tensors.add(new TensorInfo("output_norm.weight", new long[] {128}, 0, 0));
        byte[] file = writeGguf(kv, tensors);

        Path home = Files.createTempDirectory("loop-home");                // register it as Example 6 does
        String sha = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(file));
        Path blob = Files.write(Files.createDirectories(home.resolve("blobs")).resolve("sha256-" + sha), file);
        Path dir = Files.createDirectories(home.resolve("models/example-org--Tiny-Coder-GGUF--Q8_0"));
        Files.createSymbolicLink(dir.resolve("Tiny-Coder-Q8_0.gguf"), dir.relativize(blob));
        new ObjectMapper().writeValue(dir.resolve("manifest.json").toFile(), new Manifest("example-org/Tiny-Coder-GGUF:Q8_0",
                "example-org/Tiny-Coder-GGUF", "main", "4b1c7d2e9f0a8b6c5d3e2f1a0b9c8d7e6f5a4b3c", "Q8_0",
                List.of(new FileEntry("Tiny-Coder-Q8_0.gguf", file.length, sha)), "2026-10-03T12:00:00Z"));
        show(home, "example-org--Tiny-Coder-GGUF--Q8_0");
    }
}