Document the one-prompt, one-completion rule on every entry point

F184 and F197 refuse several prompts in one request and "n" > 1 with
InvalidRequestException, unlike upstream's server, which answers both.
Only the C header of jllama_completions/jllama_completions_oai said so,
and streamCompletionsOai named the prompts but not "n". The @throws of
handleCompletions, handleCompletionsOai and streamCompletionsOai now
name both, handleChatCompletions and handleInfill only "n" (a chat
request renders one prompt from its messages, infill builds its own);
the eight request methods of FfmLlamaModel carry the same split, and
the chat, infill and streaming functions of jllama_api.h say it too.
Phrased as an unconditional refusal, not tied to the slot count.
Documentation only; javadoc builds clean for the core and llama-ffm.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VBFFnrhtvXiUeyxjmUc4R2

Author: claude

BUGHUNT-FOUND.md

@@ -1612,6 +1612,7 @@ Repos plus eins. Geprüfte Klassen ohne Fund stehen in [`BUGHUNT-CHECKED.md`](BU
 - **Rot-Grün-Nachweis:** Der C-API-Test gegen den alten Code rot (alle vier Wege `OK` statt `INVALID_REQUEST`), mit dem Fix grün; `ctest` grün. Die beiden Java-Tests lokal mit dem Zufallsmodell grün (die zwei Infill-Tests der Klasse scheitern dort erwartungsgemäß, das Zufallsmodell hat keine FIM-Tokens); in CI mit dem echten Modell.
 - **Status:** gefixt
 - **Commit:** java-llama.cpp `7a51bbc`
+- **Nachtrag (Branch-Review 2026-10-20, Fund XJ-5):** Die Ablehnung mehrerer Prompts (F184) und von `"n"` > 1 stand im C-Header nur bei `jllama_completions`/`jllama_completions_oai` und in der Javadoc von `streamCompletionsOai` nur zur Hälfte. Jetzt nennen sie die `@throws InvalidRequestException` von `LlamaModel#handleCompletions`, `#handleCompletionsOai` und `#streamCompletionsOai` (beides), `#handleChatCompletions` und `#handleInfill` (nur `"n"`: eine Chat-Anfrage rendert genau einen Prompt aus `messages`, Infill baut ihn selbst), alle acht Anfrage-Methoden von `FfmLlamaModel` mit derselben Aufteilung, und im C-Header die Chat-, Infill- und Stream-Funktionen. Formuliert als unbedingte Ablehnung (ein Prompt und eine Completion je Anfrage), nicht über die Slot-Zahl. Nur Doku.
 
 <a id="f198"></a>
 ### F198 – java-llama.cpp: `FfmTextToSpeech.close()` gibt die Engine frei, während `synthesize()` auf einem anderen Thread in ihr läuft (FFM-Hälfte von F16)

llama-ffm/src/main/java/net/ladenthin/llama/ffm/FfmLlamaModel.java

@@ -146,6 +146,8 @@ public String meta() {
      *
      * @param requestJson the OpenAI chat body ({@code {"messages": [...], ...}})
      * @return the {@code chat.completion} object
+     * @throws InvalidRequestException if the server refuses the body, including {@code "n"} greater than 1
+     *     (one completion per request; send separate requests)
      */
     public String chatCompletions(String requestJson) {
         return stringOut(JllamaNative.CHAT_COMPLETIONS, requireNonNull(requestJson, "requestJson"));
@@ -157,6 +159,8 @@ public String chatCompletions(String requestJson) {
      *
      * @param requestJson the OpenAI chat body
      * @return the stream; close it to release the task early
+     * @throws InvalidRequestException if the server refuses the body, including {@code "n"} greater than 1
+     *     (one completion per request; send separate requests)
      */
     public FfmTaskStream chatCompletionsStream(String requestJson) {
         int task = taskOut(JllamaNative.CHAT_COMPLETIONS_STREAM_REQUEST, requireNonNull(requestJson, "requestJson"));
@@ -169,6 +173,8 @@ public FfmTaskStream chatCompletionsStream(String requestJson) {
      *
      * @param requestJson the OpenAI chat body
      * @return the stream of raw result objects
+     * @throws InvalidRequestException if the server refuses the body, including {@code "n"} greater than 1
+     *     (one completion per request; send separate requests)
      */
     public FfmTaskStream chatCompletionsRaw(String requestJson) {
         int task = taskOut(JllamaNative.CHAT_COMPLETIONS_REQUEST, requireNonNull(requestJson, "requestJson"));
@@ -180,6 +186,9 @@ public FfmTaskStream chatCompletionsRaw(String requestJson) {
      *
      * @param requestJson the request object ({@code {"prompt": ..., ...}})
      * @return the result object
+     * @throws InvalidRequestException if the server refuses the body, including several prompts in one
+     *     request or {@code "n"} greater than 1 (one prompt and one completion per request; send separate
+     *     requests)
      */
     public String completions(String requestJson) {
         return stringOut(JllamaNative.COMPLETIONS, requireNonNull(requestJson, "requestJson"));
@@ -190,6 +199,9 @@ public String completions(String requestJson) {
      *
      * @param requestJson the request object
      * @return the {@code text_completion} object
+     * @throws InvalidRequestException if the server refuses the body, including several prompts in one
+     *     request or {@code "n"} greater than 1 (one prompt and one completion per request; send separate
+     *     requests)
      */
     public String completionsOai(String requestJson) {
         return stringOut(JllamaNative.COMPLETIONS_OAI, requireNonNull(requestJson, "requestJson"));
@@ -202,6 +214,9 @@ public String completionsOai(String requestJson) {
      *
      * @param requestJson the request object, parsed as {@link #completionsOai(String)} parses it
      * @return the stream; close it to release the task early
+     * @throws InvalidRequestException if the server refuses the body, including several prompts in one
+     *     request or {@code "n"} greater than 1 (one prompt and one completion per request; send separate
+     *     requests)
      */
     public FfmTaskStream completionsOaiStream(String requestJson) {
         int task = taskOut(JllamaNative.COMPLETIONS_OAI_STREAM_REQUEST, requireNonNull(requestJson, "requestJson"));
@@ -213,6 +228,8 @@ public FfmTaskStream completionsOaiStream(String requestJson) {
      *
      * @param requestJson the request object ({@code input_prefix}, {@code input_suffix}, ...)
      * @return the result object
+     * @throws InvalidRequestException if the server refuses the body, including {@code "n"} greater than 1
+     *     (one completion per request)
      */
     public String infill(String requestJson) {
         return stringOut(JllamaNative.INFILL, requireNonNull(requestJson, "requestJson"));
@@ -223,6 +240,9 @@ public String infill(String requestJson) {
      *
      * @param requestJson the request object
      * @return the stream
+     * @throws InvalidRequestException if the server refuses the body, including several prompts in one
+     *     request or {@code "n"} greater than 1 (one prompt and one completion per request; send separate
+     *     requests)
      */
     public FfmTaskStream completionsStream(String requestJson) {
         int task = taskOut(JllamaNative.COMPLETIONS_STREAM_REQUEST, requireNonNull(requestJson, "requestJson"));

llama/src/main/cpp/jllama_api.h

@@ -123,15 +123,17 @@ JLLAMA_API void jllama_model_free(jllama_model *model);
 /**
  * An OpenAI chat completion, blocking: `request_json` is the request body
  * (`{"messages":[...], "max_tokens": ..., ...}`), *response_json the chat.completion object
- * (jllama_string_free). JLLAMA_STATUS_INVALID_REQUEST for a body the server refuses.
+ * (jllama_string_free). JLLAMA_STATUS_INVALID_REQUEST for a body the server refuses, including
+ * "n" > 1: a request takes one completion (send separate requests).
  */
 JLLAMA_API jllama_status jllama_chat_completions(jllama_model *model, const char *request_json, char **response_json);
 
 /**
  * Starts a streaming OpenAI chat completion (`"stream": true` in the body makes the server emit
  * chat.completion.chunk deltas) and returns its task id in *task_id. Receive with
  * jllama_chat_completions_stream_receive until it reports stop; a task not received to its end is
- * released with jllama_task_release.
+ * released with jllama_task_release. "n" > 1 is JLLAMA_STATUS_INVALID_REQUEST, as for
+ * jllama_chat_completions.
  */
 JLLAMA_API jllama_status jllama_chat_completions_stream_request(jllama_model *model, const char *request_json,
                                                                 int *task_id);
@@ -192,27 +194,29 @@ JLLAMA_API jllama_status jllama_completions_oai(jllama_model *model, const char
  * Starts a streaming OpenAI /v1/completions request (the body as for jllama_completions_oai) and
  * returns its task id in *task_id. Receive with jllama_chat_completions_stream_receive, whose
  * envelopes then carry text_completion chunks, the last with usage; release an unfinished task with
- * jllama_task_release.
+ * jllama_task_release. One prompt and one choice, as for jllama_completions.
  */
 JLLAMA_API jllama_status jllama_completions_oai_stream_request(jllama_model *model, const char *request_json,
                                                                int *task_id);
 
 /**
  * A fill-in-the-middle request (`input_prefix`, `input_suffix`, optional `input_extra` and
- * `prompt`), blocking. JLLAMA_STATUS_ERROR when the model has no FIM tokens.
+ * `prompt`), blocking. JLLAMA_STATUS_ERROR when the model has no FIM tokens; "n" > 1 is
+ * JLLAMA_STATUS_INVALID_REQUEST, as for jllama_completions.
  */
 JLLAMA_API jllama_status jllama_infill(jllama_model *model, const char *request_json, char **response_json);
 
 /**
  * Starts a raw streaming completion (`"stream": true`; an infill one when the body carries
  * `input_prefix`/`input_suffix`) and returns its task id; receive with
- * jllama_completions_stream_receive.
+ * jllama_completions_stream_receive. One prompt and one completion, as for jllama_completions.
  */
 JLLAMA_API jllama_status jllama_completions_stream_request(jllama_model *model, const char *request_json, int *task_id);
 
 /**
  * Starts a streaming chat completion whose results are llama.cpp's raw result objects (the chat
  * template applied, no OpenAI chunk formatting); receive with jllama_completions_stream_receive.
+ * "n" > 1 is JLLAMA_STATUS_INVALID_REQUEST, as for jllama_chat_completions.
  */
 JLLAMA_API jllama_status jllama_chat_completions_request(jllama_model *model, const char *request_json, int *task_id);
 

llama/src/main/java/net/ladenthin/llama/LlamaModel.java

@@ -800,7 +800,8 @@ public void streamChatCompletion(InferenceParameters parameters, Consumer<String
      * @param requestJson the OpenAI completion body ({@code {"prompt": ..., "max_tokens": ..., ...}})
      * @param chunkSink receiver for each {@code text_completion} chunk JSON string, in order
      * @throws net.ladenthin.llama.exception.InvalidRequestException if the request is rejected (no
-     *     {@code prompt}, a parameter upstream refuses, several prompts, a prompt over the context size)
+     *     {@code prompt}, a parameter upstream refuses, several prompts, {@code "n"} greater than 1, a prompt
+     *     over the context size; see {@link #handleCompletionsOai(String)})
      * @throws net.ladenthin.llama.exception.LlamaException if inference fails
      */
     public void streamCompletionsOai(String requestJson, Consumer<String> chunkSink) {
@@ -826,7 +827,9 @@ public void streamCompletionsOai(String requestJson, Consumer<String> chunkSink)
      * @param paramsJson JSON string with at least a "prompt" field
      * @return JSON response from the server
      * @throws net.ladenthin.llama.exception.InvalidRequestException if the request is rejected: not valid JSON, no
-     *     {@code "prompt"}, a parameter outside its limits, a prompt over the context size
+     *     {@code "prompt"}, a parameter outside its limits, a prompt over the context size, several prompts in
+     *     one request (an array of strings or of token arrays) or {@code "n"} greater than 1 -- one prompt and
+     *     one completion per request, unlike upstream's server; send separate requests
      * @throws net.ladenthin.llama.exception.LlamaException if inference fails
      */
     public native String handleCompletions(String paramsJson);
@@ -838,7 +841,9 @@ public void streamCompletionsOai(String requestJson, Consumer<String> chunkSink)
      * @param paramsJson JSON string with OAI-compatible completion parameters
      * @return JSON response in OAI format
      * @throws net.ladenthin.llama.exception.InvalidRequestException if the request is rejected: not valid JSON, no
-     *     {@code "prompt"}, a parameter outside its limits, a prompt over the context size
+     *     {@code "prompt"}, a parameter outside its limits, a prompt over the context size, several prompts in
+     *     one request (an array of strings or of token arrays) or {@code "n"} greater than 1 -- one prompt and
+     *     one completion per request, unlike upstream's server; send separate requests
      * @throws net.ladenthin.llama.exception.LlamaException if inference fails
      */
     public native String handleCompletionsOai(String paramsJson);
@@ -850,7 +855,8 @@ public void streamCompletionsOai(String requestJson, Consumer<String> chunkSink)
      * @param paramsJson JSON string with infill parameters
      * @return JSON response from the server
      * @throws net.ladenthin.llama.exception.InvalidRequestException if the request is rejected: not valid JSON, a missing
-     *     {@code "input_prefix"} or {@code "input_suffix"}, a parameter outside its limits
+     *     {@code "input_prefix"} or {@code "input_suffix"}, a parameter outside its limits, {@code "n"} greater
+     *     than 1 (one completion per request)
      * @throws net.ladenthin.llama.exception.LlamaException if the model has no fill-in-the-middle tokens or inference fails
      */
     public native String handleInfill(String paramsJson);
@@ -1180,7 +1186,8 @@ public void setLoraAdapter(int adapterId, float scale) {
      * @return JSON response in OAI chat-completion format
      * @throws net.ladenthin.llama.exception.InvalidRequestException if the request is rejected: not valid JSON, no
      *     {@code "messages"}, a message the chat template cannot take, a parameter outside its limits, a
-     *     prompt over the context size
+     *     prompt over the context size, {@code "n"} greater than 1 (one completion per request, unlike
+     *     upstream's server; send separate requests)
      * @throws net.ladenthin.llama.exception.LlamaException if the model was loaded in embedding mode or inference fails
      */
     public native String handleChatCompletions(String params);