The Chat Completions Protocol and Streaming in Java

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import java.util.List;

public class RequestJson {
    record Message(String role, String content) {}
    record StreamOptions(boolean includeUsage) {}

    @JsonInclude(JsonInclude.Include.NON_NULL)
    record ChatRequest(String model, List<Message> messages, Double temperature, Integer maxTokens,
                       Boolean stream, StreamOptions streamOptions) {}

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper()
                .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
        List<Message> messages = List.of(
                new Message("system", "You are a coding assistant."),
                new Message("user", "Write a Java loop."));

        ChatRequest plain = new ChatRequest("tiny-coder", messages, 0.0, 6, null, null);
        System.out.println(json.writeValueAsString(plain));

        ChatRequest streaming = new ChatRequest("tiny-coder", messages.subList(1, 2), null, 6,
                true, new StreamOptions(true));
        System.out.println(json.writerWithDefaultPrettyPrinter().writeValueAsString(streaming));
    }
}

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import java.util.List;

public class ParseResponse {
    // Captured from llama-server (random weights, ASCII-only grammar)
    static final String BODY = """
        {"choices":[{"finish_reason":"length","index":0,"message":{"role":"assistant",
        "content":" Inventweights publishers publishers publishers publishers"}}],"created":1791032728,
        "model":"tiny-coder","system_fingerprint":"b1-0c1e570","object":"chat.completion",
        "usage":{"completion_tokens":6,"prompt_tokens":23,"total_tokens":29,"prompt_tokens_details":{"cached_tokens":22}},
        "id":"chatcmpl-tYRxeTsElLIer6kMouE6EQXEJyBeoV0y",
        "timings":{"cache_n":22,"prompt_n":1,"prompt_ms":44.203,"predicted_n":6,"predicted_ms":177.678}}
        """;

    record Message(String role, String content) {}
    record Choice(int index, Message message, String finishReason) {}
    record PromptTokensDetails(Integer cachedTokens) {}
    record Usage(int promptTokens, int completionTokens, int totalTokens, PromptTokensDetails promptTokensDetails) {}
    record ChatResponse(String id, String object, long created, String model, List<Choice> choices, Usage usage) {}

    public static void main(String[] args) throws Exception {
        ObjectMapper strict = new ObjectMapper().setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
        try {
            strict.readValue(BODY, ChatResponse.class);
        } catch (Exception e) {
            System.out.println("strict mapper: " + e.getClass().getSimpleName());
            String msg = e.getMessage();
            System.out.println("  " + msg.substring(0, msg.indexOf(" (class")));
        }

        ObjectMapper lenient = strict.copy().configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        ChatResponse r = lenient.readValue(BODY, ChatResponse.class);
        Choice c = r.choices().get(0);
        System.out.println("id            = " + r.id());
        System.out.println("object        = " + r.object() + ", model = " + r.model());
        System.out.println("role          = " + c.message().role());
        System.out.println("content       = [" + c.message().content() + "]");
        System.out.println("finish_reason = " + c.finishReason());
        System.out.println("usage         = " + r.usage());
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetAddress;
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.charset.StandardCharsets;
import java.time.Duration;

public class SyncCall {
    // Captured from llama-server (random weights, ASCII-only grammar)
    static final String REPLY = """
        {"choices":[{"finish_reason":"length","index":0,"message":{"role":"assistant","content":" Inventweights publishers publishers publishers publishers"}}],"created":1791032728,"model":"tiny-coder","system_fingerprint":"b1-0c1e570","object":"chat.completion","usage":{"completion_tokens":6,"prompt_tokens":23,"total_tokens":29,"prompt_tokens_details":{"cached_tokens":22}},"id":"chatcmpl-tYRxeTsElLIer6kMouE6EQXEJyBeoV0y"}
        """;

    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
        server.createContext("/v1/chat/completions", exchange -> {
            String body = new String(exchange.getRequestBody().readAllBytes(), StandardCharsets.UTF_8);
            System.out.println("server got " + exchange.getRequestMethod() + " " + exchange.getRequestURI()
                    + ", auth=" + exchange.getRequestHeaders().getFirst("Authorization"));
            System.out.println("server got body " + body);
            byte[] bytes = REPLY.getBytes(StandardCharsets.UTF_8);
            exchange.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8");
            exchange.sendResponseHeaders(200, bytes.length);
            try (OutputStream out = exchange.getResponseBody()) { out.write(bytes); }
        });
        server.start();
        String baseUrl = "http://127.0.0.1:" + server.getAddress().getPort() + "/v1";

        try (HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1)
                .connectTimeout(Duration.ofSeconds(2)).build()) {
            String request = """
                {"model":"tiny-coder","messages":[{"role":"user","content":"Write a Java loop."}],"max_tokens":6}""";
            HttpRequest httpRequest = HttpRequest.newBuilder(URI.create(baseUrl + "/chat/completions"))
                    .header("Content-Type", "application/json")
                    .header("Authorization", "Bearer no-key")
                    .timeout(Duration.ofSeconds(30))
                    .POST(HttpRequest.BodyPublishers.ofString(request))
                    .build();
            HttpResponse<String> response = http.send(httpRequest, HttpResponse.BodyHandlers.ofString());
            JsonNode root = new ObjectMapper().readTree(response.body());
            JsonNode choice = root.at("/choices/0");
            System.out.println("client status " + response.statusCode()
                    + ", content type " + response.headers().firstValue("Content-Type").orElse("?"));
            System.out.println("client content [" + choice.at("/message/content").asText() + "]");
            System.out.println("client finish " + choice.get("finish_reason").asText()
                    + ", tokens " + root.at("/usage/prompt_tokens").asInt() + "+" + root.at("/usage/completion_tokens").asInt());
        } finally {
            server.stop(0);
        }
    }
}

import java.io.BufferedReader;
import java.io.IOException;
import java.io.StringReader;
import java.util.ArrayList;
import java.util.List;

public class SseParse {
    record Event(String name, String data) {}

    // One SSE parser: collects "event:" and "data:" fields until a blank line ends the event.
    static final class SseParser {
        private String name = "message";
        private final StringBuilder data = new StringBuilder();
        private boolean hasData;

        /** Feeds one line (without its line ending); returns an event when a blank line completes one. */
        Event feed(String line) {
            if (line.isEmpty()) {
                if (!hasData) { name = "message"; return null; }
                Event e = new Event(name, data.toString());
                name = "message"; data.setLength(0); hasData = false;
                return e;
            }
            if (line.startsWith(":")) return null;                      // comment, e.g. keep-alive ping
            int colon = line.indexOf(':');
            String field = colon < 0 ? line : line.substring(0, colon);
            String value = colon < 0 ? "" : line.substring(colon + 1);
            if (value.startsWith(" ")) value = value.substring(1);       // one optional space after the colon
            switch (field) {
                case "data" -> { if (hasData) data.append('\n'); data.append(value); hasData = true; }
                case "event" -> name = value;
                default -> { }                                          // id, retry, unknown fields
            }
            return null;
        }
    }

    public static void main(String[] args) throws IOException {
        String wire = """
            data: {"choices":[{"index":0,"delta":{"role":"assistant","content":null}}]}

            :

            data: {"choices":[{"index":0,"delta":{"content":" Invent"}}]}

            data:{"choices":[{"index":0,
            data: "delta":{"content":"weights"}}]}

            event: response.output_text.delta
            data: {"type":"response.output_text.delta","delta":"x"}

            data: [DONE]

            """;
        SseParser parser = new SseParser();
        List<Event> events = new ArrayList<>();
        BufferedReader reader = new BufferedReader(new StringReader(wire));
        for (String line; (line = reader.readLine()) != null; ) {
            Event e = parser.feed(line);
            if (e != null) events.add(e);
        }
        for (int i = 0; i < events.size(); i++) {
            Event e = events.get(i);
            String kind = e.data().equals("[DONE]") ? "end of stream" : "json";
            System.out.printf("event %d name=%s kind=%s data=%s%n", i, e.name(), kind, e.data().replace("\n", "\\n"));
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetAddress;
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.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import java.util.stream.Stream;

public class StreamLines {
    // Captured from llama-server; envelope fields (id, created, model, ...) removed for length
    static final List<String> EVENTS = List.of(
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\" Invent\"}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\"weights\"}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\" publishers\"}}]}",
        "{\"choices\":[{\"finish_reason\":\"length\",\"index\":0,\"delta\":{}}]}",
        "[DONE]");

    public static void main(String[] args) throws Exception {
        CountDownLatch clientSawTwoDeltas = new CountDownLatch(1);
        HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
        server.createContext("/v1/chat/completions", exchange -> {
            exchange.getRequestBody().readAllBytes();
            exchange.getResponseHeaders().set("Content-Type", "text/event-stream");
            exchange.sendResponseHeaders(200, 0);                       // 0 = chunked, length unknown
            try (OutputStream out = exchange.getResponseBody()) {
                for (int i = 0; i < EVENTS.size(); i++) {
                    out.write(("data: " + EVENTS.get(i) + "\n\n").getBytes(StandardCharsets.UTF_8));
                    out.flush();
                    if (i == 2) {
                        boolean seen = clientSawTwoDeltas.await(5, TimeUnit.SECONDS);
                        System.out.println("  server: stream still open, client already printed 2 deltas: " + seen);
                    }
                }
            } catch (InterruptedException e) { Thread.currentThread().interrupt(); }
        });
        server.start();

        try (HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {
            HttpRequest request = HttpRequest.newBuilder(
                    URI.create("http://127.0.0.1:" + server.getAddress().getPort() + "/v1/chat/completions"))
                .header("Content-Type", "application/json")
                .header("Accept", "text/event-stream")
                .POST(HttpRequest.BodyPublishers.ofString("{\"messages\":[],\"stream\":true}"))
                .build();
            HttpResponse<Stream<String>> response = http.send(request, HttpResponse.BodyHandlers.ofLines());
            System.out.println("status " + response.statusCode() + ", " + response.headers().firstValue("Content-Type").orElse(""));
            ObjectMapper json = new ObjectMapper();
            int deltas = 0;
            try (Stream<String> lines = response.body()) {
                for (String line : (Iterable<String>) lines::iterator) {
                    if (!line.startsWith("data: ")) continue;
                    String data = line.substring(6);
                    if (data.equals("[DONE]")) { System.out.println("[DONE]"); break; }
                    JsonNode delta = json.readTree(data).at("/choices/0/delta");
                    if (delta.hasNonNull("content")) {
                        deltas++;
                        System.out.println("delta " + deltas + ": [" + delta.get("content").asText() + "]");
                        if (deltas == 2) clientSawTwoDeltas.countDown();
                    }
                }
            }
        } finally {
            server.stop(0);
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Accumulate {
    // Captured from llama-server with stream_options.include_usage; id/created/model fields removed except on the last chunk
    static final String WIRE = """
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"role":"assistant","content":null}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":" Invent"}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":"weights"}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":" publishers"}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":" publishers"}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":" publishers"}}]}

        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"content":" publishers"}}]}

        data: {"choices":[{"finish_reason":"length","index":0,"delta":{}}]}

        data: {"choices":[],"id":"chatcmpl-CyVpWRHnMjGe3Gi6jlt8pDtXxEPG7nzw","object":"chat.completion.chunk","usage":{"completion_tokens":6,"prompt_tokens":23,"total_tokens":29,"prompt_tokens_details":{"cached_tokens":22}}}

        data: [DONE]

        """;

    static final class MessageBuilder {
        String role;
        final StringBuilder content = new StringBuilder();
        String finishReason;
        JsonNode usage;
        int chunks;

        void accept(JsonNode chunk) {
            chunks++;
            if (chunk.hasNonNull("usage")) usage = chunk.get("usage");
            for (JsonNode choice : chunk.get("choices")) {            // empty in the usage-only chunk
                JsonNode delta = choice.get("delta");
                if (delta.hasNonNull("role")) role = delta.get("role").asText();
                if (delta.hasNonNull("content")) content.append(delta.get("content").asText());
                if (choice.hasNonNull("finish_reason")) finishReason = choice.get("finish_reason").asText();
            }
        }
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper();
        MessageBuilder message = new MessageBuilder();
        for (String line : WIRE.split("\n")) {
            if (!line.startsWith("data: ")) continue;
            String data = line.substring(6);
            if (data.equals("[DONE]")) break;
            message.accept(json.readTree(data));
        }
        System.out.println("chunks parsed  = " + message.chunks);
        System.out.println("role           = " + message.role);
        System.out.println("content        = [" + message.content + "]");
        System.out.println("finish_reason  = " + message.finishReason);
        System.out.println("usage          = " + message.usage);
        System.out.println("cached prompt  = " + message.usage.at("/prompt_tokens_details/cached_tokens").asInt()
                + " of " + message.usage.get("prompt_tokens").asInt());
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.TreeMap;

public class ToolDeltas {
    // Captured from llama-server (Qwen2.5 template, tool_choice required); envelope fields removed
    static final String WIRE = """
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"role":"assistant","content":null}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"id":"5ztHnIb8odTda96BAIowHvag0ZjNWH7b","type":"function","function":{"name":"read_file","arguments":"{"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\n  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t\\""}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"path"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\":\\""}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"sr"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"c"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"/M"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"ai"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"n"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":".java"}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\""}}]}}]}
        data: {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":" }"}}]}}]}
        data: {"choices":[{"finish_reason":"tool_calls","index":0,"delta":{}}]}
        data: [DONE]
        """;

    static final class CallBuilder {
        String id, type, name;
        final StringBuilder arguments = new StringBuilder();
        int pieces;
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper();
        Map<Integer, CallBuilder> calls = new TreeMap<>();
        String finish = null;
        for (String line : WIRE.split("\n")) {
            String data = line.substring("data: ".length());
            if (data.equals("[DONE]")) break;
            JsonNode choice = json.readTree(data).at("/choices/0");
            if (choice.hasNonNull("finish_reason")) finish = choice.get("finish_reason").asText();
            for (JsonNode d : choice.at("/delta/tool_calls")) {
                CallBuilder call = calls.computeIfAbsent(d.get("index").asInt(), i -> new CallBuilder());
                if (d.hasNonNull("id")) call.id = d.get("id").asText();
                if (d.hasNonNull("type")) call.type = d.get("type").asText();
                JsonNode f = d.path("function");
                if (f.hasNonNull("name")) call.name = f.get("name").asText();
                if (f.hasNonNull("arguments")) { call.arguments.append(f.get("arguments").asText()); call.pieces++; }
            }
        }
        System.out.println("finish_reason = " + finish);
        for (var e : calls.entrySet()) {
            CallBuilder c = e.getValue();
            System.out.println("call " + e.getKey() + ": id=" + c.id + " type=" + c.type + " name=" + c.name
                    + " pieces=" + c.pieces);
            System.out.println("  raw arguments: " + c.arguments.toString().replace("\n", "\\n").replace("\t", "\\t"));
            JsonNode parsed = json.readTree(c.arguments.toString());
            System.out.println("  parsed: " + parsed + " -> path=" + parsed.get("path").asText());
        }
    }
}

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.TreeMap;

public class ToolDeltasTwo {
    // Captured from llama-server (parallel tool calls allowed, max_tokens 100); envelope fields removed
    static final String WIRE = """
        {"choices":[{"finish_reason":null,"index":0,"delta":{"role":"assistant","content":null}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"id":"GbpMe8NnqSqLz6tof3Wj7oIK61dgnBde","type":"function","function":{"name":"read_file","arguments":"{"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\n  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t\\""}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"path"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\":\\""}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"sr"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"c"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"/M"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"ai"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"n"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":".java"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":"\\""}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":0,"function":{"arguments":" }"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"id":"8dP5VcT1eTIV1UIbbnp9jFhil954Drwp","type":"function","function":{"name":"read_file","arguments":"{"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"\\n  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t  \\t\\t\\t\\""}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"path"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"\\":\\""}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"sr"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"c"}}]}}]}
        {"choices":[{"finish_reason":null,"index":0,"delta":{"tool_calls":[{"index":1,"function":{"arguments":"/M"}}]}}]}
        {"choices":[{"finish_reason":"length","index":0,"delta":{}}]}
        """;

    record Call(String id, String name, StringBuilder arguments) {}

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper();
        Map<Integer, Call> calls = new TreeMap<>();
        String finish = null;
        for (String data : WIRE.split("\n")) {
            JsonNode choice = json.readTree(data).at("/choices/0");
            if (choice.hasNonNull("finish_reason")) finish = choice.get("finish_reason").asText();
            for (JsonNode d : choice.at("/delta/tool_calls")) {
                Call call = calls.computeIfAbsent(d.get("index").asInt(),
                        i -> new Call(d.path("id").asText(), d.at("/function/name").asText(), new StringBuilder()));
                call.arguments().append(d.at("/function/arguments").asText());
            }
        }
        System.out.println("finish_reason = " + finish + ", calls = " + calls.size());
        for (var e : calls.entrySet()) {
            Call c = e.getValue();
            try {
                JsonNode parsed = json.readTree(c.arguments().toString());
                System.out.println("call " + e.getKey() + " " + c.name() + " id=" + c.id().substring(0, 8) + "... complete: " + parsed);
            } catch (JsonProcessingException ex) {
                String tail = c.arguments().substring(c.arguments().lastIndexOf("\""));
                System.out.println("call " + e.getKey() + " " + c.name() + " id=" + c.id().substring(0, 8)
                        + "... incomplete, arguments end with " + tail + " -> " + ex.getClass().getSimpleName());
            }
        }
        boolean runTools = "tool_calls".equals(finish);
        System.out.println("run the tools: " + runTools);
    }
}

import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetAddress;
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.charset.StandardCharsets;
import java.util.Iterator;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import java.util.stream.Stream;

public class CancelStream {
    static final int PLANNED = 2000;

    public static void main(String[] args) throws Exception {
        CompletableFuture<Integer> serverResult = new CompletableFuture<>();
        HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
        server.createContext("/v1/chat/completions", exchange -> {
            exchange.getRequestBody().readAllBytes();
            exchange.getResponseHeaders().set("Content-Type", "text/event-stream");
            exchange.sendResponseHeaders(200, 0);
            int written = 0;
            try (OutputStream out = exchange.getResponseBody()) {
                for (; written < PLANNED; written++) {
                    String chunk = "{\"choices\":[{\"index\":0,\"delta\":{\"content\":\" publishers\"}}]}";
                    out.write(("data: " + chunk + "\n\n").getBytes(StandardCharsets.UTF_8));
                    out.flush();
                    Thread.sleep(2);                                     // a slow model
                }
                out.write("data: [DONE]\n\n".getBytes(StandardCharsets.UTF_8));
            } catch (IOException | InterruptedException e) {
                // the client went away: a real server cancels the generation here
            } finally {
                serverResult.complete(written);
            }
        });
        server.start();

        try (HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {
            HttpRequest request = HttpRequest.newBuilder(
                    URI.create("http://127.0.0.1:" + server.getAddress().getPort() + "/v1/chat/completions"))
                .POST(HttpRequest.BodyPublishers.ofString("{\"stream\":true}")).build();
            HttpResponse<Stream<String>> response = http.send(request, HttpResponse.BodyHandlers.ofLines());
            ObjectMapper json = new ObjectMapper();
            int received = 0;
            try (Stream<String> lines = response.body()) {                // close() cancels the body
                Iterator<String> it = lines.iterator();
                while (it.hasNext() && received < 3) {
                    String line = it.next();
                    if (!line.startsWith("data: ")) continue;
                    received++;
                    String text = json.readTree(line.substring(6)).at("/choices/0/delta/content").asText();
                    System.out.println("client delta " + received + ": [" + text + "]");
                }
                System.out.println("client: stop requested, closing the stream");
            }
            int written = serverResult.get(10, TimeUnit.SECONDS);
            System.out.println("server: stopped before the planned " + PLANNED + " events: " + (written < PLANNED));
        } finally {
            server.stop(0);
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetAddress;
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.net.http.HttpTimeoutException;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.util.concurrent.Executors;
import java.util.concurrent.atomic.AtomicInteger;

public class ErrorsTimeouts {
    static final class ApiException extends IOException {
        final int status; final String type;
        ApiException(int status, String type, String message) {
            super(status + " " + type + ": " + message);
            this.status = status; this.type = type;
        }
    }

    static void reply(HttpExchange ex, int status, String body) throws IOException {
        ex.getRequestBody().readAllBytes();
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        ex.getResponseHeaders().set("Content-Type", "application/json");
        ex.sendResponseHeaders(status, bytes.length);
        try (OutputStream out = ex.getResponseBody()) { out.write(bytes); }
    }

    static String post(HttpClient http, String url, Duration timeout) throws IOException, InterruptedException {
        HttpRequest req = HttpRequest.newBuilder(URI.create(url)).timeout(timeout)
                .POST(HttpRequest.BodyPublishers.ofString("{}")).build();
        HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
        if (res.statusCode() >= 400) {
            JsonNode err = new ObjectMapper().readTree(res.body()).path("error");
            throw new ApiException(res.statusCode(), err.path("type").asText("unknown"), err.path("message").asText());
        }
        return res.body();
    }

    public static void main(String[] args) throws Exception {
        AtomicInteger loadingCalls = new AtomicInteger();
        HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor()); // daemon threads
        // bodies captured from llama-server
        server.createContext("/ctx", ex -> reply(ex, 400, "{\"error\":{\"code\":400,\"message\":\"request (2118 tokens) exceeds the available context size (2048 tokens), try increasing it\",\"type\":\"exceed_context_size_error\",\"n_prompt_tokens\":2118,\"n_ctx\":2048}}"));
        server.createContext("/loading", ex -> {
            if (loadingCalls.incrementAndGet() <= 2) reply(ex, 503, "{\"error\":{\"message\":\"Loading model\",\"type\":\"unavailable_error\",\"code\":503}}");
            else reply(ex, 200, "{\"status\":\"ok\"}");
        });
        server.createContext("/slow", ex -> {
            try { Thread.sleep(2000); } catch (InterruptedException ignored) { }
            reply(ex, 200, "{}");
        });
        server.start();
        String base = "http://127.0.0.1:" + server.getAddress().getPort();

        try (HttpClient http = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build()) {
            try {
                post(http, base + "/ctx", Duration.ofSeconds(5));
            } catch (ApiException e) {
                System.out.println("400 case: " + e.getMessage());
                System.out.println("  retry? " + (e.status == 503) + ", type=" + e.type);
            }

            long delayMs = 50;
            for (int attempt = 1; ; attempt++) {
                try {
                    System.out.println("attempt " + attempt + ": " + post(http, base + "/loading", Duration.ofSeconds(5)));
                    break;
                } catch (ApiException e) {
                    System.out.println("attempt " + attempt + ": " + e.getMessage() + ", waiting " + delayMs + " ms");
                    if (e.status != 503 || attempt == 5) throw e;
                    Thread.sleep(delayMs);
                    delayMs *= 2;
                }
            }

            try {
                post(http, base + "/slow", Duration.ofMillis(300));
            } catch (HttpTimeoutException e) {
                System.out.println("timeout case: " + e.getClass().getSimpleName() + ": " + e.getMessage());
            }
        } finally {
            server.stop(0);
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.node.ObjectNode;

public class ServerDialects {
    enum Server { LLAMA_SERVER, VLLM, OLLAMA_OPENAI }

    static final ObjectMapper JSON = new ObjectMapper();

    /** Standard fields first; non-standard sampling fields only where the server's request type has them. */
    static ObjectNode request(Server server, double temperature, int topK, double minP) {
        ObjectNode r = JSON.createObjectNode();
        r.put("model", "coder");
        r.putArray("messages").addObject().put("role", "user").put("content", "Write a Java loop.");
        r.put("temperature", temperature);
        r.put("max_tokens", 256);
        switch (server) {
            case LLAMA_SERVER, VLLM -> { r.put("top_k", topK); r.put("min_p", minP); }
            case OLLAMA_OPENAI -> { }  // ChatCompletionRequest in openai/openai.go has no top_k or min_p
        }
        return r;
    }

    /** llama-server returns reasoning_content; vLLM and Ollama return reasoning. */
    static String reasoning(JsonNode message) {
        if (message.hasNonNull("reasoning_content")) return message.get("reasoning_content").asText();
        if (message.hasNonNull("reasoning")) return message.get("reasoning").asText();
        return "";
    }

    public static void main(String[] args) throws Exception {
        for (Server s : Server.values()) {
            System.out.printf("%-13s %s%n", s, JSON.writeValueAsString(request(s, 0.2, 20, 0.05)));
        }
        String[] messages = {
            "{\"role\":\"assistant\",\"content\":\"7 is prime.\",\"reasoning_content\":\"check 2, 3\"}",
            "{\"role\":\"assistant\",\"content\":\"7 is prime.\",\"reasoning\":\"check 2, 3\"}",
            "{\"role\":\"assistant\",\"content\":\"7 is prime.\"}"
        };
        for (String m : messages) {
            JsonNode message = JSON.readTree(m);
            System.out.println("reasoning=[" + reasoning(message) + "] content=[" + message.get("content").asText() + "]");
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Locale;

public class Logprobs {
    // Captured from llama-server: logprobs=true, top_logprobs=2, ASCII-only grammar, random weights
    static final String BODY = """
        {"choices":[{"finish_reason":"length","index":0,"message":{"role":"assistant","content":" Inventweights publishers"},
        "logprobs":{"content":[
         {"id":92158,"token":" Invent","bytes":[32,73,110,118,101,110,116],"logprob":-10.670243263244629,
          "top_logprobs":[{"id":119530,"token":"瓤","bytes":[231,147,164],"logprob":-10.596213340759277},
                          {"id":97494,"token":"(\\"(%","bytes":[40,34,40,37],"logprob":-10.60909366607666}]},
         {"id":13327,"token":"weights","bytes":[119,101,105,103,104,116,115],"logprob":-10.7026948928833,
          "top_logprobs":[{"id":123014,"token":"崶","bytes":[229,180,182],"logprob":-10.638603210449219},
                          {"id":97494,"token":"(\\"(%","bytes":[40,34,40,37],"logprob":-10.65953540802002}]},
         {"id":35617,"token":" publishers","bytes":[32,112,117,98,108,105,115,104,101,114,115],"logprob":-10.583504676818848,
          "top_logprobs":[{"id":35617,"token":" publishers","bytes":[32,112,117,98,108,105,115,104,101,114,115],"logprob":-10.583504676818848},
                          {"id":97494,"token":"(\\"(%","bytes":[40,34,40,37],"logprob":-10.606264114379883}]}]}}]}
        """;

    public static void main(String[] args) throws Exception {
        JsonNode content = new ObjectMapper().readTree(BODY).at("/choices/0/logprobs/content");
        double sum = 0;
        for (JsonNode t : content) {
            double lp = t.get("logprob").asDouble();
            sum += lp;
            System.out.printf(Locale.ROOT, "chosen %-13s id=%-6d logprob=%.4f p=%.2e bytes=%d%n",
                    "[" + t.get("token").asText() + "]", t.get("id").asInt(), lp, Math.exp(lp), t.get("bytes").size());
            for (JsonNode alt : t.get("top_logprobs")) {
                System.out.printf(Locale.ROOT, "   top %-13s id=%-6d logprob=%.4f%n",
                        "[" + alt.get("token").asText() + "]", alt.get("id").asInt(), alt.get("logprob").asDouble());
            }
        }
        System.out.printf(Locale.ROOT, "sequence logprob = %.4f, mean = %.4f%n", sum, sum / content.size());
        System.out.printf(Locale.ROOT, "uniform over 151936 tokens = %.4f%n", Math.log(1.0 / 151936));
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Locale;

public class OllamaNdjson {
    // Shape of POST /api/chat with "stream": true (field names from Ollama v0.35.1 api/types.go; values illustrative)
    static final String NDJSON = """
        {"model":"qwen2.5-coder:7b","created_at":"2026-10-03T12:00:00.100Z","message":{"role":"assistant","content":"Reading"},"done":false}
        {"model":"qwen2.5-coder:7b","created_at":"2026-10-03T12:00:00.120Z","message":{"role":"assistant","content":" the file."},"done":false}
        {"model":"qwen2.5-coder:7b","created_at":"2026-10-03T12:00:00.180Z","message":{"role":"assistant","content":"","tool_calls":[{"id":"call_k2v9","function":{"index":0,"name":"read_file","arguments":{"path":"pom.xml"}}}]},"done":false}
        {"model":"qwen2.5-coder:7b","created_at":"2026-10-03T12:00:00.200Z","message":{"role":"assistant","content":""},"done":true,"done_reason":"stop","total_duration":2150000000,"load_duration":1500000000,"prompt_eval_count":120,"prompt_eval_duration":400000000,"eval_count":25,"eval_duration":250000000}
        """;

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper();
        StringBuilder content = new StringBuilder();
        for (String line : NDJSON.split("\n")) {                    // one JSON object per line, no "data: " prefix
            JsonNode r = json.readTree(line);
            if (r.has("error")) throw new IllegalStateException(r.get("error").asText());  // {"error": "text"}
            JsonNode msg = r.get("message");
            content.append(msg.path("content").asText());
            for (JsonNode call : msg.path("tool_calls")) {
                JsonNode f = call.get("function");
                System.out.println("tool call " + f.get("name").asText() + " arguments object " + f.get("arguments")
                        + " (isObject=" + f.get("arguments").isObject() + ")");
            }
            if (r.get("done").asBoolean()) {
                double evalSeconds = r.get("eval_duration").asLong() / 1e9;  // durations are nanoseconds
                double promptSeconds = r.get("prompt_eval_duration").asLong() / 1e9;
                System.out.println("content     = [" + content + "]");
                System.out.println("done_reason = " + r.get("done_reason").asText());
                System.out.printf(Locale.ROOT, "prompt: %d tokens in %.3f s = %.1f tok/s%n",
                        r.get("prompt_eval_count").asInt(), promptSeconds, r.get("prompt_eval_count").asInt() / promptSeconds);
                System.out.printf(Locale.ROOT, "output: %d tokens in %.3f s = %.1f tok/s%n",
                        r.get("eval_count").asInt(), evalSeconds, r.get("eval_count").asInt() / evalSeconds);
                System.out.printf(Locale.ROOT, "load: %.3f s of %.3f s total%n",
                        r.get("load_duration").asLong() / 1e9, r.get("total_duration").asLong() / 1e9);
            }
        }
    }
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class ResponsesEvents {
    // Captured from llama-server POST /v1/responses with "stream": true (random weights)
    static final String WIRE = """
        event: response.created
        data: {"type":"response.created","response":{"id":"resp_1ozZJzNQRW59aeykjm40KXDpCt54Bd2n","object":"response","status":"in_progress"}}

        event: response.in_progress
        data: {"type":"response.in_progress","response":{"id":"resp_1ozZJzNQRW59aeykjm40KXDpCt54Bd2n","object":"response","status":"in_progress"}}

        event: response.output_item.added
        data: {"type":"response.output_item.added","item":{"content":[],"id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","role":"assistant","status":"in_progress","type":"message"}}

        event: response.content_part.added
        data: {"type":"response.content_part.added","item_id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","part":{"type":"output_text","text":""}}

        event: response.output_text.delta
        data: {"type":"response.output_text.delta","item_id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","delta":"🇷"}

        event: response.output_text.delta
        data: {"type":"response.output_text.delta","item_id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","delta":"🇷"}

        event: response.output_text.done
        data: {"type":"response.output_text.done","item_id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","text":"🇷🇷"}

        event: response.content_part.done
        data: {"type":"response.content_part.done","item_id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","part":{"type":"output_text","annotations":[],"logprobs":[],"text":"🇷🇷"}}

        event: response.output_item.done
        data: {"type":"response.output_item.done","item":{"type":"message","status":"completed","id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"🇷🇷"}],"role":"assistant"}}

        event: response.completed
        data: {"type":"response.completed","response":{"id":"resp_1ozZJzNQRW59aeykjm40KXDpCt54Bd2n","object":"response","created_at":1791032700,"status":"completed","model":"tiny-coder","output":[{"type":"message","status":"completed","id":"msg_1xwJuyYl5xm2xXEoVDBph00zkN5gw7jM","content":[{"type":"output_text","annotations":[],"logprobs":[],"text":"🇷🇷"}],"role":"assistant"}],"usage":{"input_tokens":21,"output_tokens":2,"total_tokens":23,"input_tokens_details":{"cached_tokens":20}}},"timings":{"cache_n":20,"prompt_n":1,"prompt_ms":7.737,"prompt_per_token_ms":7.737,"prompt_per_second":129.24906294429366,"predicted_n":2,"predicted_ms":7.296,"predicted_per_token_ms":7.296,"predicted_per_second":137.06140350877192}}

        """;

    public static void main(String[] args) throws Exception {
        ObjectMapper json = new ObjectMapper();
        StringBuilder text = new StringBuilder();
        String eventName = null;
        for (String line : WIRE.split("\n")) {
            if (line.startsWith("event: ")) { eventName = line.substring(7); continue; }
            if (!line.startsWith("data: ")) continue;
            JsonNode data = json.readTree(line.substring(6));
            System.out.println(eventName + (eventName.equals(data.get("type").asText()) ? "" : " (type differs)"));
            switch (eventName) {
                case "response.output_text.delta" -> text.append(data.get("delta").asText());
                case "response.output_text.done" -> System.out.println("  done text equals deltas: " + data.get("text").asText().contentEquals(text));
                case "response.completed" -> {
                    JsonNode r = data.get("response");
                    System.out.println("  status=" + r.get("status").asText() + " output[0].type=" + r.at("/output/0/type").asText()
                            + " text=" + r.at("/output/0/content/0/text").asText());
                    System.out.println("  usage input=" + r.at("/usage/input_tokens").asInt() + " output=" + r.at("/usage/output_tokens").asInt()
                            + " cached=" + r.at("/usage/input_tokens_details/cached_tokens").asInt());
                }
                default -> { }
            }
        }
    }
}

import com.fasterxml.jackson.annotation.JsonInclude;
import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.io.OutputStream;
import java.net.InetAddress;
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.charset.StandardCharsets;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Iterator;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.concurrent.Executors;
import java.util.stream.Stream;

public class ChatClientDemo {
    // ---------------- Project 11: the ChatClient library ----------------
    @JsonInclude(JsonInclude.Include.NON_NULL)
    record Message(String role, String content, List<ToolCall> toolCalls, String toolCallId) {
        static Message system(String text) { return new Message("system", text, null, null); }
        static Message user(String text) { return new Message("user", text, null, null); }
        static Message assistant(String text, List<ToolCall> calls) { return new Message("assistant", text, calls, null); }
        static Message tool(String callId, String result) { return new Message("tool", result, null, callId); }
    }
    record ToolCall(String id, String type, FunctionCall function) {}
    record FunctionCall(String name, String arguments) {}
    @JsonInclude(JsonInclude.Include.NON_NULL)
    record FunctionDef(String name, String description, JsonNode parameters) {}
    record Tool(String type, FunctionDef function) {
        static Tool function(String name, String description, JsonNode parameters) {
            return new Tool("function", new FunctionDef(name, description, parameters));
        }
    }
    @JsonInclude(JsonInclude.Include.NON_NULL)
    record Request(String model, List<Message> messages, Double temperature, Integer maxTokens, List<Tool> tools) {}
    record Usage(int promptTokens, int completionTokens, int totalTokens) {}
    record Result(String content, String reasoning, List<ToolCall> toolCalls, String finishReason, Usage usage) {}

    interface Listener {
        void onContent(String text);
        default void onReasoning(String text) { }
    }

    static final class Cancel {
        private volatile boolean cancelled;
        void cancel() { cancelled = true; }
        boolean isCancelled() { return cancelled; }
    }

    static final class ApiException extends IOException {
        final int status;
        final String type;
        ApiException(int status, String type, String message) {
            super(status + " " + type + ": " + message);
            this.status = status;
            this.type = type;
        }
    }

    static final class ChatClient implements AutoCloseable {
        private final HttpClient http = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_1_1).connectTimeout(Duration.ofSeconds(5)).build();
        private final ObjectMapper json = new ObjectMapper()
                .setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
                .configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
        private final URI endpoint;
        private final String apiKey;

        /** baseUrl ends in /v1, for example http://127.0.0.1:8080/v1; apiKey may be null. */
        ChatClient(String baseUrl, String apiKey) {
            this.endpoint = URI.create(baseUrl + "/chat/completions");
            this.apiKey = apiKey;
        }

        /** One request, one complete response. */
        Result chat(Request request) throws IOException, InterruptedException {
            ObjectNode body = json.valueToTree(request);
            body.put("stream", false);
            HttpResponse<String> res = http.send(build(body, Duration.ofMinutes(10)), HttpResponse.BodyHandlers.ofString());
            if (res.statusCode() >= 400) throw error(res.statusCode(), json.readTree(res.body()));
            JsonNode root = json.readTree(res.body());
            JsonNode choice = root.at("/choices/0");
            JsonNode message = choice.get("message");
            List<ToolCall> calls = new ArrayList<>();
            for (JsonNode c : message.path("tool_calls")) calls.add(json.treeToValue(c, ToolCall.class));
            return new Result(message.path("content").asText(""), reasoningOf(message), calls,
                    choice.path("finish_reason").asText(null), usageOf(root));
        }

        /** Streams one request; deltas go to the listener; returns the accumulated result. */
        Result stream(Request request, Listener listener, Cancel cancel) throws IOException, InterruptedException {
            ObjectNode body = json.valueToTree(request);
            body.put("stream", true);
            body.putObject("stream_options").put("include_usage", true);
            HttpResponse<Stream<String>> res = http.send(build(body, Duration.ofMinutes(10)), HttpResponse.BodyHandlers.ofLines());
            if (res.statusCode() >= 400) {
                String text = String.join("\n", res.body().toList());
                throw error(res.statusCode(), json.readTree(text));
            }
            StringBuilder content = new StringBuilder(), reasoning = new StringBuilder();
            Map<Integer, String[]> calls = new TreeMap<>();               // index -> {id, name, arguments}
            String finish = null;
            Usage usage = null;
            try (Stream<String> lines = res.body()) {                      // closing cancels the HTTP exchange
                Iterator<String> it = lines.iterator();
                while (it.hasNext()) {
                    if (cancel.isCancelled()) { finish = "cancelled"; break; }
                    String line = it.next();
                    if (!line.startsWith("data:")) continue;               // blank lines, ":" pings, event names
                    String data = line.substring(5).trim();
                    if (data.equals("[DONE]")) break;
                    JsonNode chunk = json.readTree(data);
                    if (chunk.has("error")) throw error(res.statusCode(), chunk);
                    if (chunk.hasNonNull("usage")) usage = usageOf(chunk);
                    for (JsonNode choice : chunk.path("choices")) {
                        JsonNode delta = choice.path("delta");
                        String text = delta.path("content").asText("");
                        if (!text.isEmpty()) { content.append(text); listener.onContent(text); }
                        String thought = reasoningOf(delta);
                        if (!thought.isEmpty()) { reasoning.append(thought); listener.onReasoning(thought); }
                        for (JsonNode d : delta.path("tool_calls")) {
                            String[] call = calls.computeIfAbsent(d.path("index").asInt(), i -> new String[] {null, null, ""});
                            if (d.hasNonNull("id")) call[0] = d.get("id").asText();
                            if (d.at("/function/name").isTextual()) call[1] = d.at("/function/name").asText();
                            call[2] += d.at("/function/arguments").asText("");
                        }
                        if (choice.hasNonNull("finish_reason")) finish = choice.get("finish_reason").asText();
                    }
                }
            }
            List<ToolCall> toolCalls = new ArrayList<>();
            for (String[] c : calls.values()) toolCalls.add(new ToolCall(c[0], "function", new FunctionCall(c[1], c[2])));
            return new Result(content.toString(), reasoning.toString(), toolCalls, finish, usage);
        }

        private HttpRequest build(JsonNode body, Duration timeout) throws IOException {
            HttpRequest.Builder b = HttpRequest.newBuilder(endpoint).timeout(timeout)
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(json.writeValueAsString(body)));
            if (apiKey != null) b.header("Authorization", "Bearer " + apiKey);
            return b.build();
        }

        private static String reasoningOf(JsonNode node) {   // llama-server: reasoning_content; vLLM, Ollama: reasoning
            if (node.hasNonNull("reasoning_content")) return node.get("reasoning_content").asText();
            return node.path("reasoning").asText("");
        }

        private static Usage usageOf(JsonNode root) {
            JsonNode u = root.path("usage");
            return u.isMissingNode() || u.isNull() ? null : new Usage(u.path("prompt_tokens").asInt(),
                    u.path("completion_tokens").asInt(), u.path("total_tokens").asInt());
        }

        private static ApiException error(int status, JsonNode root) {
            JsonNode e = root.path("error");
            if (e.isTextual()) return new ApiException(status, "error", e.asText());   // Ollama native shape
            return new ApiException(status, e.path("type").asText("unknown"), e.path("message").asText(""));
        }

        @Override public void close() { http.close(); }
    }
    // ---------------- end of the library ----------------

    // Fake llama-server replaying captured responses (envelope fields removed from the SSE chunks)
    static final String SYNC = "{\"choices\":[{\"finish_reason\":\"length\",\"index\":0,\"message\":{\"role\":\"assistant\",\"content\":\" Inventweights publishers publishers publishers publishers\"}}],\"object\":\"chat.completion\",\"usage\":{\"completion_tokens\":6,\"prompt_tokens\":23,\"total_tokens\":29}}";
    static final List<String> TEXT_SSE = List.of(
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\" Invent\"}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\"weights\"}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"content\":\" publishers\"}}]}",
        "{\"choices\":[{\"finish_reason\":\"length\",\"index\":0,\"delta\":{}}]}",
        "{\"choices\":[],\"usage\":{\"completion_tokens\":3,\"prompt_tokens\":23,\"total_tokens\":26}}",
        "[DONE]");
    static final List<String> TOOL_SSE = List.of(
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"role\":\"assistant\",\"content\":null}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"id\":\"5ztHnIb8odTda96BAIowHvag0ZjNWH7b\",\"type\":\"function\",\"function\":{\"name\":\"read_file\",\"arguments\":\"{\"}}]}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"\\\"path\\\":\\\"\"}}]}}]}",
        "{\"choices\":[{\"finish_reason\":null,\"index\":0,\"delta\":{\"tool_calls\":[{\"index\":0,\"function\":{\"arguments\":\"src/Main.java\\\" }\"}}]}}]}",
        "{\"choices\":[{\"finish_reason\":\"tool_calls\",\"index\":0,\"delta\":{}}]}",
        "[DONE]");
    static final String CTX_ERROR = "{\"error\":{\"code\":400,\"message\":\"request (2118 tokens) exceeds the available context size (2048 tokens), try increasing it\",\"type\":\"exceed_context_size_error\",\"n_prompt_tokens\":2118,\"n_ctx\":2048}}";

    static HttpServer fakeServer() throws IOException {
        ObjectMapper json = new ObjectMapper();
        HttpServer server = HttpServer.create(new InetSocketAddress(InetAddress.getLoopbackAddress(), 0), 0);
        server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
        server.createContext("/v1/chat/completions", ex -> {
            JsonNode req = json.readTree(ex.getRequestBody().readAllBytes());
            String last = req.at("/messages/" + (req.get("messages").size() - 1) + "/content").asText();
            boolean stream = req.path("stream").asBoolean();
            try (OutputStream out = ex.getResponseBody()) {
                if (last.equals("too long")) {
                    byte[] b = CTX_ERROR.getBytes(StandardCharsets.UTF_8);
                    ex.sendResponseHeaders(400, b.length);
                    out.write(b);
                } else if (!stream) {
                    byte[] b = SYNC.getBytes(StandardCharsets.UTF_8);
                    ex.sendResponseHeaders(200, b.length);
                    out.write(b);
                } else {
                    ex.getResponseHeaders().set("Content-Type", "text/event-stream");
                    ex.sendResponseHeaders(200, 0);
                    List<String> events = req.has("tools") ? TOOL_SSE : TEXT_SSE;
                    int repeat = last.equals("long") ? 1000 : 1;
                    for (int r = 0; r < repeat; r++) {
                        for (String e : events) {
                            if (repeat > 1 && (e.equals("[DONE]") || e.contains("finish_reason\":\"") || e.contains("usage"))) continue;
                            out.write(("data: " + e + "\n\n").getBytes(StandardCharsets.UTF_8));
                            out.flush();
                            if (repeat > 1) Thread.sleep(2);
                        }
                    }
                }
            } catch (IOException | InterruptedException ignored) {
                // client closed the connection
            }
        });
        server.start();
        return server;
    }

    public static void main(String[] args) throws Exception {
        HttpServer server = fakeServer();
        String base = "http://127.0.0.1:" + server.getAddress().getPort() + "/v1";
        try (ChatClient client = new ChatClient(base, "no-key")) {
            List<Message> history = new ArrayList<>(List.of(Message.system("You are a coding assistant."), Message.user("Write a Java loop.")));

            Result sync = client.chat(new Request("tiny-coder", history, 0.0, 6, null));
            System.out.println("1 chat:   [" + sync.content() + "] finish=" + sync.finishReason() + " " + sync.usage());

            StringBuilder shown = new StringBuilder();
            Result streamed = client.stream(new Request("tiny-coder", history, 0.0, 3, null), t -> shown.append('|').append(t), new Cancel());
            System.out.println("2 stream: listener saw " + shown + "| finish=" + streamed.finishReason() + " " + streamed.usage());

            JsonNode schema = new ObjectMapper().readTree("{\"type\":\"object\",\"properties\":{\"path\":{\"type\":\"string\"}},\"required\":[\"path\"]}");
            List<Tool> tools = List.of(Tool.function("read_file", "Read a file from the workspace", schema));
            Result call = client.stream(new Request("tiny-coder", List.of(Message.user("Show me pom.xml")), 0.0, 100, tools), t -> { }, new Cancel());
            ToolCall tc = call.toolCalls().get(0);
            System.out.println("3 tools:  finish=" + call.finishReason() + " " + tc.function().name() + " " + tc.function().arguments());
            history.add(Message.assistant("", call.toolCalls()));
            history.add(Message.tool(tc.id(), "<project>...</project>"));
            ObjectMapper snake = new ObjectMapper().setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);
            System.out.println("          next request ends with " + snake.writeValueAsString(history.subList(2, 4)));

            Cancel cancel = new Cancel();
            int[] count = {0};
            Result stopped = client.stream(new Request("tiny-coder", List.of(Message.user("long")), 0.0, null, null),
                    t -> { if (++count[0] == 4) cancel.cancel(); }, cancel);
            System.out.println("4 cancel: finish=" + stopped.finishReason() + " content=[" + stopped.content() + "]");

            try {
                client.chat(new Request("tiny-coder", List.of(Message.user("too long")), null, null, null));
            } catch (ApiException e) {
                System.out.println("5 error:  " + e.status + " " + e.type);
            }
        } finally {
            server.stop(0);
        }
    }
}