JLlmClient

org.llm4s.javaapi.JLlmClient
final class JLlmClient extends AutoCloseable

Java-friendly wrapper around LLMClient.

The underlying Scala client returns Result[Completion]; this wrapper surfaces it as LlmResult so Java callers never import any Scala types. complete returns the reply's text alone; completion returns the whole reply as a JCompletion - the text, the model that answered, its tool calls, its token usage and estimated cost.

Every complete and completion blocks the calling thread and never throws: a failure comes back inside the LlmResult. Interrupting the thread blocked in a call returns a failed result whose error is a CancelledError, with the thread's interrupt flag still set; InterruptedException is never thrown. The methods therefore declare no checked exception, and javac rejects a catch (InterruptedException e) around them as "never thrown in body of corresponding try statement" - test the result instead:

LlmResult<String> result = client.complete("Long question");
if (result.isFailure() && result.getError().getKind() == LlmErrorKind.CANCELLED) {
   // interrupted while blocked; Thread.currentThread().isInterrupted() is still true
}

Each blocking call has an *Async variant - completeAsync, completionAsync - that returns a CompletableFuture at once and makes the call on another thread: by default a virtual thread of this client's own virtual-thread-per-task executor, which close() shuts down; withAsyncExecutor names another executor. The future completes with the value, or exceptionally with the LlmException the blocking call's result would hold. cancel(true) - and any other completion from outside, such as orTimeout - interrupts the call:

CompletableFuture<String> a = client.completeAsync("Summarise the first report");
CompletableFuture<String> b = client.completeAsync("Summarise the second report");
CompletableFuture.allOf(a, b).join();

Obtain instances via Llm4s.createDefaultClient or Llm4s.createClient, or wrap a Scala LLMClient you built yourself with Llm4s.wrapClient; the constructor is the package's own (#1666).

LlmResult<String> r = client.complete("What is 2+2?");
r.ifSuccess(System.out::println).ifFailure(e -> System.err.println(e.getMessage()));

Attributes

Source
JLlmClient.scala
Graph
Supertypes
class Object
trait Matchable
class Any

Members list

Value members

Concrete methods

override def close(): Unit

Closes the provider client and shuts down this client's own async executor, interrupting any *Async call still running; a supplied executor (withAsyncExecutor) is left alone.

Closes the provider client and shuts down this client's own async executor, interrupting any *Async call still running; a supplied executor (withAsyncExecutor) is left alone.

Attributes

Definition Classes
Source
JLlmClient.scala

Sends a single user query and returns the assistant's text response. A null query yields a failed LlmResult, never an exception.

Sends a single user query and returns the assistant's text response. A null query yields a failed LlmResult, never an exception.

Blocks the calling thread. If that thread is interrupted while it waits, the result is a failure whose error is a CancelledError and the thread's interrupt flag is left set; InterruptedException is never thrown, and the method declares none.

Attributes

Source
JLlmClient.scala
def complete(conversation: Conversation): LlmResult[String]

Sends a pre-built conversation and returns the assistant's text response. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

Sends a pre-built conversation and returns the assistant's text response. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

Attributes

Source
JLlmClient.scala
def complete(conversation: Conversation, options: JCompletionOptions): LlmResult[String]

Sends a conversation with the options a JCompletionOptions builder made - temperature, token limit, reasoning - and returns the assistant's text response. A null argument yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

Sends a conversation with the options a JCompletionOptions builder made - temperature, token limit, reasoning - and returns the assistant's text response. A null argument yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

JCompletionOptions options = JCompletionOptions.builder().temperature(0.2).maxTokens(512).build();
LlmResult<String> answer = client.complete(conversation, options);

Attributes

Source
JLlmClient.scala
def complete(conversation: Conversation, options: CompletionOptions): LlmResult[String]

Full access: send a conversation with core's Scala CompletionOptions, returning the raw text content; from Java, JCompletionOptions builds the same options without Scala types. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

Full access: send a conversation with core's Scala CompletionOptions, returning the raw text content; from Java, JCompletionOptions builds the same options without Scala types. Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

Attributes

Source
JLlmClient.scala
def complete[T](query: String, `type`: Class[T]): LlmResult[T]

Sends a single user query and returns the answer as an instance of the Java record type: the record's JSON Schema is derived from its components, sent as the structured-output format, and the reply is read back into the record. complete(String) returns the text instead.

Sends a single user query and returns the answer as an instance of the Java record type: the record's JSON Schema is derived from its components, sent as the structured-output format, and the reply is read back into the record. complete(String) returns the text instead.

A component may be a String, an integer type, a double or float, a boolean, an enum, another record, a java.util.List of these, or an Optional of these (the one way to let the model answer null). A type outside that list, or a reply that does not fit the record - a missing or null field that is not an Optional, the wrong JSON type, an unknown enum name - is a failed result whose message names the field. How firmly the schema binds the model depends on the provider: OpenAI-style providers send it as a native JSON Schema, Anthropic as a prompt instruction. Blocks and reports an interrupt as complete(String) does.

record City(String name, String country, int population) {}
City city = client.complete("The largest city in Japan", City.class).get();

Attributes

Source
JLlmClient.scala
def complete[T](conversation: Conversation, `type`: Class[T]): LlmResult[T]

Sends a conversation and returns the answer as an instance of the record type, as complete(String, Class).

Sends a conversation and returns the answer as an instance of the record type, as complete(String, Class).

Attributes

Source
JLlmClient.scala
def complete[T](conversation: Conversation, options: JCompletionOptions, `type`: Class[T]): LlmResult[T]

Sends a conversation with the options a JCompletionOptions builder made and returns the answer as an instance of the record type, as complete(String, Class). The options' response format is replaced by the record's schema.

Sends a conversation with the options a JCompletionOptions builder made and returns the answer as an instance of the record type, as complete(String, Class). The options' response format is replaced by the record's schema.

Attributes

Source
JLlmClient.scala

complete(String) on another thread: returns at once with a future of the text. The future completes exceptionally with the LlmException the blocking call's failed result would hold - of the same LlmErrorKind - and never with another exception, except the CancellationException of a future cancelled yourself. cancel(true) interrupts the call, which the provider answers by stopping; cancel(false) lets it run and discards its answer. Completing the future yourself - orTimeout, completeOnTimeout, complete - also interrupts the call. Cancel this future, not one derived from it with thenApply: a derived future's cancellation does not reach the call.

complete(String) on another thread: returns at once with a future of the text. The future completes exceptionally with the LlmException the blocking call's failed result would hold - of the same LlmErrorKind - and never with another exception, except the CancellationException of a future cancelled yourself. cancel(true) interrupts the call, which the provider answers by stopping; cancel(false) lets it run and discards its answer. Completing the future yourself - orTimeout, completeOnTimeout, complete - also interrupts the call. Cancel this future, not one derived from it with thenApply: a derived future's cancellation does not reach the call.

The call runs on this client's executor: by default a new virtual thread for each call, from an executor that close() shuts down - a call still running then is interrupted, and a call made after it fails with kind OTHER; see withAsyncExecutor.

Attributes

Source
JLlmClient.scala

complete(Conversation) on another thread, as completeAsync(String).

complete(Conversation) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala

complete(Conversation, JCompletionOptions) on another thread, as completeAsync(String).

complete(Conversation, JCompletionOptions) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala
def completeAsync[T](query: String, `type`: Class[T]): CompletableFuture[T]

Structured output, complete(String, Class), on another thread, as completeAsync(String): a future of the record.

Structured output, complete(String, Class), on another thread, as completeAsync(String): a future of the record.

CompletableFuture<City> city = client.completeAsync("The largest city in Japan", City.class);

Attributes

Source
JLlmClient.scala
def completeAsync[T](conversation: Conversation, `type`: Class[T]): CompletableFuture[T]

complete(Conversation, Class) on another thread, as completeAsync(String).

complete(Conversation, Class) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala
def completeAsync[T](conversation: Conversation, options: JCompletionOptions, `type`: Class[T]): CompletableFuture[T]

complete(Conversation, JCompletionOptions, Class) on another thread, as completeAsync(String).

complete(Conversation, JCompletionOptions, Class) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala
def completion(query: String): LlmResult[JCompletion]

Sends a single user query and returns the whole reply: its text, the model that answered, the tool calls it asked for, the tokens it used and its estimated cost. complete(String) returns the text alone. A null query yields a failed LlmResult, never an exception.

Sends a single user query and returns the whole reply: its text, the model that answered, the tool calls it asked for, the tokens it used and its estimated cost. complete(String) returns the text alone. A null query yields a failed LlmResult, never an exception.

Blocks and reports an interrupt as complete(String) does: a CancelledError result, the interrupt flag left set, never an InterruptedException.

JCompletion reply = client.completion("What is 2+2?").get();
System.out.println(reply.model() + ": " + reply.content());

Attributes

Source
JLlmClient.scala
def completion(conversation: Conversation): LlmResult[JCompletion]

Sends a pre-built conversation and returns the whole reply, as completion(String) does. A null conversation yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does.

Sends a pre-built conversation and returns the whole reply, as completion(String) does. A null conversation yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does.

Attributes

Source
JLlmClient.scala
def completion(conversation: Conversation, options: JCompletionOptions): LlmResult[JCompletion]

Sends a conversation with the options a JCompletionOptions builder made and returns the whole reply, as completion(String) does. A null argument yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does.

Sends a conversation with the options a JCompletionOptions builder made and returns the whole reply, as completion(String) does. A null argument yields a failed LlmResult. Blocks and reports an interrupt as complete(String) does.

There is no overload taking core's Scala CompletionOptions, so completion(conversation, null) compiles and returns a failed result, where complete(conversation, null) needs a cast to pick an overload.

JCompletionOptions options = JCompletionOptions.builder().maxTokens(512).build();
JCompletion reply = client.completion(conversation, options).get();

Attributes

Source
JLlmClient.scala
def completionAsync(query: String): CompletableFuture[JCompletion]

completion(String) on another thread - the whole reply - as completeAsync(String).

completion(String) on another thread - the whole reply - as completeAsync(String).

Attributes

Source
JLlmClient.scala
def completionAsync(conversation: Conversation): CompletableFuture[JCompletion]

completion(Conversation) on another thread, as completeAsync(String).

completion(Conversation) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala
def completionAsync(conversation: Conversation, options: JCompletionOptions): CompletableFuture[JCompletion]

completion(Conversation, JCompletionOptions) on another thread, as completeAsync(String).

completion(Conversation, JCompletionOptions) on another thread, as completeAsync(String).

Attributes

Source
JLlmClient.scala

Sends a single user query and streams the reply to listener: each piece of its text as it arrives, then the whole reply or the error (see CompletionStreamListener). Returns at once with the running CompletionStream, which cancels the call (close() or cancel()) and awaits its reply (await()). A null argument is a failed result, and listener hears nothing.

Sends a single user query and streams the reply to listener: each piece of its text as it arrives, then the whole reply or the error (see CompletionStreamListener). Returns at once with the running CompletionStream, which cancels the call (close() or cancel()) and awaits its reply (await()). A null argument is a failed result, and listener hears nothing.

CompletionStream stream = client.stream("Tell me a story", System.out::print).get();
JCompletion reply = stream.await().get();

Attributes

Source
JLlmClient.scala

Sends a conversation and streams the reply to listener, as stream(String, listener) does.

Sends a conversation and streams the reply to listener, as stream(String, listener) does.

Attributes

Source
JLlmClient.scala

Sends a conversation with the options a JCompletionOptions builder made and streams the reply to listener, as stream(String, listener) does.

Sends a conversation with the options a JCompletionOptions builder made and streams the reply to listener, as stream(String, listener) does.

Attributes

Source
JLlmClient.scala

The reply to a single user query as a java.util.concurrent.Flow.Publisher of its text: in the JDK, so it adapts to Reactor, RxJava or Mutiny with their own Flow adapters and adds no dependency. It is cold: each subscription makes its own provider call, on a thread of its own. A subscriber slower than the provider holds the provider's thread rather than losing text (up to 64 pieces wait for it); cancelling the subscription interrupts the call. The publisher completes after the last piece, or fails with an LlmException

The reply to a single user query as a java.util.concurrent.Flow.Publisher of its text: in the JDK, so it adapts to Reactor, RxJava or Mutiny with their own Flow adapters and adds no dependency. It is cold: each subscription makes its own provider call, on a thread of its own. A subscriber slower than the provider holds the provider's thread rather than losing text (up to 64 pieces wait for it); cancelling the subscription interrupts the call. The publisher completes after the last piece, or fails with an LlmException

  • at once, on subscription, for a null argument.

Attributes

Source
JLlmClient.scala

A conversation's reply as a Flow.Publisher of its text, as streamAsPublisher(String).

A conversation's reply as a Flow.Publisher of its text, as streamAsPublisher(String).

Attributes

Source
JLlmClient.scala

A conversation's reply, with the options of a JCompletionOptions builder, as streamAsPublisher(String).

A conversation's reply, with the options of a JCompletionOptions builder, as streamAsPublisher(String).

Attributes

Source
JLlmClient.scala

This client with its *Async calls run on executor - a Spring TaskExecutor, a bounded pool, a Quarkus or Micronaut managed executor - rather than a virtual thread of the client's own. It is a view: it shares this client's provider connection, so closing either closes it, and it never shuts executor down. Any Executor works, a ForkJoinPool too: cancelling a future interrupts the thread running its call, whatever the executor. An executor that refuses a call - shut down, its queue full - fails that call's future at once with kind OTHER, the executor's exception as its cause.

This client with its *Async calls run on executor - a Spring TaskExecutor, a bounded pool, a Quarkus or Micronaut managed executor - rather than a virtual thread of the client's own. It is a view: it shares this client's provider connection, so closing either closes it, and it never shuts executor down. Any Executor works, a ForkJoinPool too: cancelling a future interrupts the thread running its call, whatever the executor. An executor that refuses a call - shut down, its queue full - fails that call's future at once with kind OTHER, the executor's exception as its cause.

Attributes

Throws
NullPointerException

when executor is null

Source
JLlmClient.scala