+ * This class provides methods for model management, chat, embeddings, tool registration, and more. + */ @SuppressWarnings({"DuplicatedCode", "resource", "SpellCheckingInspection"}) public class OllamaAPI { @@ -62,31 +66,33 @@ public class OllamaAPI { /** * The request timeout in seconds for API calls. - * - *
Default is 10 seconds. This value determines how long the client will wait for a response + *
+ * Default is 10 seconds. This value determines how long the client will wait for a response * from the Ollama server before timing out. */ @Setter private long requestTimeoutSeconds = 10; + /** The read timeout in seconds for image URLs. */ @Setter private int imageURLReadTimeoutSeconds = 10; + /** The connect timeout in seconds for image URLs. */ @Setter private int imageURLConnectTimeoutSeconds = 10; /** * The maximum number of retries for tool calls during chat interactions. - * - *
This value controls how many times the API will attempt to call a tool in the event of a + *
+ * This value controls how many times the API will attempt to call a tool in the event of a * failure. Default is 3. */ @Setter private int maxChatToolCallRetries = 3; /** * The number of retries to attempt when pulling a model from the Ollama server. - * - *
If set to 0, no retries will be performed. If greater than 0, the API will retry pulling + *
+ * If set to 0, no retries will be performed. If greater than 0, the API will retry pulling * the model up to the specified number of times in case of failure. - * - *
Default is 0 (no retries). + *
+ * Default is 0 (no retries). */ @Setter @SuppressWarnings({"FieldMayBeFinal", "FieldCanBeLocal"}) @@ -94,15 +100,14 @@ public class OllamaAPI { /** * Enable or disable Prometheus metrics collection. - * - *
When enabled, the API will collect and expose metrics for request counts, durations, model + *
+ * When enabled, the API will collect and expose metrics for request counts, durations, model
* usage, and other operational statistics. Default is false.
*/
@Setter private boolean metricsEnabled = false;
/**
- * Instantiates the Ollama API with default Ollama host: http://localhost:11434
+ * Instantiates the Ollama API with the default Ollama host: {@code http://localhost:11434}
*/
public OllamaAPI() {
this.host = "http://localhost:11434";
@@ -110,9 +115,9 @@ public class OllamaAPI {
}
/**
- * Instantiates the Ollama API with specified Ollama host address.
+ * Instantiates the Ollama API with a specified Ollama host address.
*
- * @param host the host address of Ollama server
+ * @param host the host address of the Ollama server
*/
public OllamaAPI(String host) {
if (host.endsWith("/")) {
@@ -125,7 +130,7 @@ public class OllamaAPI {
}
/**
- * Set basic authentication for accessing Ollama server that's behind a reverse-proxy/gateway.
+ * Set basic authentication for accessing an Ollama server that's behind a reverse-proxy/gateway.
*
* @param username the username
* @param password the password
@@ -135,7 +140,7 @@ public class OllamaAPI {
}
/**
- * Set Bearer authentication for accessing Ollama server that's behind a reverse-proxy/gateway.
+ * Set Bearer authentication for accessing an Ollama server that's behind a reverse-proxy/gateway.
*
* @param bearerToken the Bearer authentication token to provide
*/
@@ -144,13 +149,14 @@ public class OllamaAPI {
}
/**
- * API to check the reachability of Ollama server.
+ * Checks the reachability of the Ollama server.
*
- * @return true if the server is reachable, false otherwise.
+ * @return true if the server is reachable, false otherwise
+ * @throws OllamaBaseException if the ping fails
*/
public boolean ping() throws OllamaBaseException {
long startTime = System.currentTimeMillis();
- String url = this.host + "/api/tags";
+ String url = "/api/tags";
int statusCode = 0;
Object out = null;
try {
@@ -158,7 +164,7 @@ public class OllamaAPI {
HttpRequest httpRequest;
HttpResponse
+ * If an empty prompt is provided and the keep_alive parameter is set to 0, a model will be unloaded from memory.
+ *
+ * @param modelName the name of the model to unload
+ * @throws OllamaBaseException if the response indicates an error status
*/
public void unloadModel(String modelName) throws OllamaBaseException {
long startTime = System.currentTimeMillis();
- String url = this.host + "/api/generate";
+ String url = "/api/generate";
int statusCode = 0;
Object out = null;
try {
@@ -630,7 +648,7 @@ public class OllamaAPI {
jsonMap.put("keep_alive", 0);
String jsonData = objectMapper.writeValueAsString(jsonMap);
HttpRequest request =
- getRequestBuilderDefault(new URI(url))
+ getRequestBuilderDefault(new URI(this.host + url))
.method(
"POST",
HttpRequest.BodyPublishers.ofString(
@@ -669,20 +687,18 @@ public class OllamaAPI {
* @param modelRequest request for '/api/embed' endpoint
* @return embeddings
* @throws OllamaBaseException if the response indicates an error status
- * @throws IOException if an I/O error occurs during the HTTP request
- * @throws InterruptedException if the operation is interrupted
*/
public OllamaEmbedResponseModel embed(OllamaEmbedRequestModel modelRequest)
throws OllamaBaseException {
long startTime = System.currentTimeMillis();
- String url = this.host + "/api/embed";
+ String url = "/api/embed";
int statusCode = 0;
Object out = null;
try {
String jsonData = Utils.getObjectMapper().writeValueAsString(modelRequest);
HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request =
- HttpRequest.newBuilder(new URI(url))
+ HttpRequest.newBuilder(new URI(this.host + url))
.header(
Constants.HttpConstants.HEADER_KEY_ACCEPT,
Constants.HttpConstants.APPLICATION_JSON)
@@ -706,6 +722,18 @@ public class OllamaAPI {
}
}
+ /**
+ * Generates a response from a model using the specified parameters and stream observer.
+ *
+ * @param model the model name
+ * @param prompt the prompt to send
+ * @param raw whether to return the raw response
+ * @param think whether to stream "thinking" tokens
+ * @param options additional options
+ * @param streamObserver the stream observer for handling streamed responses
+ * @return the OllamaResult containing the response
+ * @throws OllamaBaseException if the request fails
+ */
public OllamaResult generate(
String model,
String prompt,
@@ -741,22 +769,20 @@ public class OllamaAPI {
/**
* Generates structured output from the specified AI model and prompt.
+ *
+ * Note: When formatting is specified, the 'think' parameter is not allowed.
*
- * Note: When formatting is specified, the 'think' parameter is not allowed.
- *
- * @param model The name or identifier of the AI model to use for generating the response.
+ * @param model The name or identifier of the AI model to use for generating the response.
* @param prompt The input text or prompt to provide to the AI model.
* @param format A map containing the format specification for the structured output.
* @return An instance of {@link OllamaResult} containing the structured response.
* @throws OllamaBaseException if the response indicates an error status.
- * @throws IOException if an I/O error occurs during the HTTP request.
- * @throws InterruptedException if the operation is interrupted.
*/
@SuppressWarnings("LoggingSimilarMessage")
public OllamaResult generateWithFormat(String model, String prompt, Map This method operates in blocking mode. It first augments the prompt with all registered
+ *
+ * This method operates in blocking mode. It first augments the prompt with all registered
* tool specifications (unless the prompt already begins with {@code [AVAILABLE_TOOLS]}), sends
* the prompt to the model, and parses the model's response for tool call instructions. If tool
* calls are found, each is invoked using the registered tool implementations, and their results
- * are collected. Typical usage:
- *
+ * are collected.
+ *
+ * Typical usage:
* This method returns an {@link OllamaAsyncResultStreamer} handle that can be used to poll
+ *
+ * This method returns an {@link OllamaAsyncResultStreamer} handle that can be used to poll
* for status and retrieve streamed "thinking" and response tokens from the model. The call is
* non-blocking.
- *
- * Example usage:
- *
+ *
+ * Example usage:
* This method allows you to provide images (as {@link File}, {@code byte[]}, or image URL
+ * Generates a response from a model running on the Ollama server using one or more images as input.
+ *
+ * This method allows you to provide images (as {@link File}, {@code byte[]}, or image URL
* {@link String}) along with a prompt to the specified model. The images are automatically
* encoded as base64 before being sent. Additional model options can be specified via the {@link
* Options} parameter.
- *
- * If a {@code streamHandler} is provided, the response will be streamed and the handler will
+ *
+ * If a {@code streamHandler} is provided, the response will be streamed and the handler will
* be called for each streamed response chunk. If {@code streamHandler} is {@code null},
* streaming is disabled and the full response is returned synchronously.
*
- * @param model the name of the Ollama model to use for generating the response
- * @param prompt the prompt or question text to send to the model
- * @param images a list of images to use for the question; each element must be a {@link File},
- * {@code byte[]}, or a URL {@link String}
- * @param options the {@link Options} object containing model parameters; see Ollama
- * model options documentation
+ * @param model the name of the Ollama model to use for generating the response
+ * @param prompt the prompt or question text to send to the model
+ * @param images a list of images to use for the question; each element must be a {@link File},
+ * {@code byte[]}, or a URL {@link String}
+ * @param options the {@link Options} object containing model parameters; see
+ * Ollama model options documentation
+ * @param format a map specifying the output format, or null for default
* @param streamHandler an optional callback that is invoked for each streamed response chunk;
- * if {@code null}, disables streaming and returns the full response synchronously
+ * if {@code null}, disables streaming and returns the full response synchronously
* @return an {@link OllamaResult} containing the response text and time taken for the response
- * @throws OllamaBaseException if the response indicates an error status or an invalid image
- * type is provided
- * @throws IOException if an I/O error occurs during the HTTP request
- * @throws InterruptedException if the operation is interrupted
- * @throws URISyntaxException if an image URL is malformed
+ * @throws OllamaBaseException if the response indicates an error status or an invalid image type is provided
*/
public OllamaResult generateWithImages(
String model,
@@ -1056,19 +1074,14 @@ public class OllamaAPI {
/**
* Ask a question to a model using an {@link OllamaChatRequest} and set up streaming response.
* This can be constructed using an {@link OllamaChatRequestBuilder}.
+ *
+ * Hint: the OllamaChatRequestModel#getStream() property is not implemented.
*
- * Hint: the OllamaChatRequestModel#getStream() property is not implemented.
- *
- * @param request request object to be sent to the server
+ * @param request request object to be sent to the server
* @param tokenHandler callback handler to handle the last token from stream (caution: the
- * previous tokens from stream will not be concatenated)
+ * previous tokens from stream will not be concatenated)
* @return {@link OllamaChatResult}
- * @throws OllamaBaseException any response code than 200 has been returned
- * @throws IOException in case the responseStream can not be read
- * @throws InterruptedException in case the server is not reachable or network issues happen
* @throws OllamaBaseException if the response indicates an error status
- * @throws IOException if an I/O error occurs during the HTTP request
- * @throws InterruptedException if the operation is interrupted
*/
public OllamaChatResult chat(OllamaChatRequest request, OllamaChatTokenHandler tokenHandler)
throws OllamaBaseException {
@@ -1143,7 +1156,7 @@ public class OllamaAPI {
* Registers a single tool in the tool registry using the provided tool specification.
*
* @param toolSpecification the specification of the tool to register. It contains the tool's
- * function name and other relevant information.
+ * function name and other relevant information.
*/
public void registerTool(Tools.ToolSpecification toolSpecification) {
toolRegistry.addTool(toolSpecification.getFunctionName(), toolSpecification);
@@ -1151,11 +1164,11 @@ public class OllamaAPI {
}
/**
- * Registers multiple tools in the tool registry using a list of tool specifications. Iterates
- * over the list and adds each tool specification to the registry.
+ * Registers multiple tools in the tool registry using a list of tool specifications.
+ * Iterates over the list and adds each tool specification to the registry.
*
* @param toolSpecifications a list of tool specifications to register. Each specification
- * contains information about a tool, such as its function name.
+ * contains information about a tool, such as its function name.
*/
public void registerTools(List{@code
* OllamaToolsResult result = ollamaAPI.generateWithTools(
* "my-model",
@@ -850,17 +877,14 @@ public class OllamaAPI {
* Map
*
- * @param model the name or identifier of the AI model to use for generating the response
- * @param prompt the input text or prompt to provide to the AI model
- * @param options additional options or configurations to use when generating the response
+ * @param model the name or identifier of the AI model to use for generating the response
+ * @param prompt the input text or prompt to provide to the AI model
+ * @param options additional options or configurations to use when generating the response
* @param streamHandler handler for streaming responses; if {@code null}, streaming is disabled
* @return an {@link OllamaToolsResult} containing the model's response and the results of any
* invoked tools. If the model does not request any tool calls, the tool results map will be
* empty.
* @throws OllamaBaseException if the Ollama API returns an error status
- * @throws IOException if an I/O error occurs during the HTTP request
- * @throws InterruptedException if the operation is interrupted
- * @throws ToolInvocationException if a tool call fails to execute
*/
public OllamaToolsResult generateWithTools(
String model, String prompt, Options options, OllamaGenerateTokenHandler streamHandler)
@@ -927,13 +951,12 @@ public class OllamaAPI {
/**
* Asynchronously generates a response for a prompt using a model running on the Ollama server.
- *
- * {@code
* OllamaAsyncResultStreamer resultStreamer = ollamaAPI.generate("gpt-oss:20b", "Who are you", false, true);
* int pollIntervalMilliseconds = 1000;
@@ -950,24 +973,24 @@ public class OllamaAPI {
* System.out.println("Complete response: " + resultStreamer.getCompleteResponse());
* }
*
- * @param model the Ollama model to use for generating the response
+ * @param model the Ollama model to use for generating the response
* @param prompt the prompt or question text to send to the model
- * @param raw if {@code true}, returns the raw response from the model
- * @param think if {@code true}, streams "thinking" tokens as well as response tokens
- * @return an {@link OllamaAsyncResultStreamer} handle for polling and retrieving streamed
- * results
+ * @param raw if {@code true}, returns the raw response from the model
+ * @param think if {@code true}, streams "thinking" tokens as well as response tokens
+ * @return an {@link OllamaAsyncResultStreamer} handle for polling and retrieving streamed results
+ * @throws OllamaBaseException if the request fails
*/
public OllamaAsyncResultStreamer generate(
String model, String prompt, boolean raw, boolean think) throws OllamaBaseException {
long startTime = System.currentTimeMillis();
- String url = this.host + "/api/generate";
+ String url = "/api/generate";
try {
OllamaGenerateRequest ollamaRequestModel = new OllamaGenerateRequest(model, prompt);
ollamaRequestModel.setRaw(raw);
ollamaRequestModel.setThink(think);
OllamaAsyncResultStreamer ollamaAsyncResultStreamer =
new OllamaAsyncResultStreamer(
- getRequestBuilderDefault(new URI(url)),
+ getRequestBuilderDefault(new URI(this.host + url)),
ollamaRequestModel,
requestTimeoutSeconds);
ollamaAsyncResultStreamer.start();
@@ -980,33 +1003,28 @@ public class OllamaAPI {
}
/**
- * Generates a response from a model running on the Ollama server using one or more images as
- * input.
- *
- *