ollama4j/ollama4j

Ollama4j – Java client for the Ollama LLM server

What it is – A pure‑Java library that talks to an Ollama server (the open‑source, locally‑run LLM runtime). It lets Java applications generate text, run chat sessions, call tools, work with embeddings, and even handle images when the underlying model supports vision.

Key capabilities

• Text generation – single‑turn generate calls, optional streaming, and a type‑safe options builder.
• Chat – multi‑turn conversations with role handling and a “thinking” mode for chain‑of‑thought style output.
• Tool/function calling – annotate Java methods to expose them as LLM‑callable tools; also supports the MCP protocol for external tools.
• Multimodal – send images as inputs to vision‑capable models.
• Embeddings – obtain vector embeddings for arbitrary text.
• Async fire‑and‑forget generation – start a request without waiting for the full response.
• Model management – list, pull, create, delete, and inspect models on the Ollama server.
• Server utilities – ping the server, query process status.
• Authentication – basic auth or bearer token.
• Timeouts & logging – configurable network time‑outs and request/response hooks.
• Metrics – optional Prometheus exporter for request counts, latency, and model usage (beta).

How it works – The library is a thin HTTP wrapper around Ollama’s REST API. Your Java code adds the ollama4j dependency (via Maven Central, GitHub Packages, or Gradle), creates an Ollama client pointing at the local server (e.g., http://localhost:11434), and then calls the high‑level methods provided by the library. All communication is over standard HTTP, so any Ollama server version 0.11.10+ works.

Getting started

<!-- Maven example -->
<dependency>
  <groupId>io.github.ollama4j</groupId>
  <artifactId>ollama4j</artifactId>
  <version>/* latest release */</version>
</dependency>

// Gradle example
implementation 'io.github.ollama4j:ollama4j:/* latest release */'

Ollama ollama = new Ollama("http://localhost:11434");
GenerateResponse resp = ollama.generate("phi", "Explain quantum tunnelling.");
System.out.println(resp.getResponse());

The README links to a separate ollama4j‑examples repo for complete snippets.

Who’s using it – Datafaker, a Vaadin UI tester, Minecraft plugins/mods, a Spring‑Boot web UI, Jenkins CLI tool, and several other open‑source projects.

Development & contribution – The project uses make shortcuts for dev setup, builds, and tests (unit tests run locally; integration tests spin up an Ollama Docker container via Testcontainers). CI runs unit/integration tests, code‑coverage, and Sonar quality gates. Contributions are welcomed via GitHub issues, PRs, and discussions.

Where to learn more – Full API docs, usage guides, and versioned releases are on the project website (https://ollama4j.github.io/ollama4j/) and the GitHub repo.