Ollama4j

A Java library (wrapper/binding) for Ollama server.

Find more details on the website.

Table of Contents

• How does it work?
• Requirements
• Installation
• API Spec
• Javadoc
• Development
• Contributions
• References

How does it work?

  flowchart LR
    o4j[Ollama4j]
    o[Ollama Server]
    o4j -->|Communicates with| o;
    m[Models]
    subgraph Ollama Deployment
        direction TB
        o -->|Manages| m
    end

Requirements

macOS https://ollama.com/download/Ollama-darwin.zip Linux curl -fsSL https://ollama.com/install.sh \| sh Windows https://ollama.com/download/OllamaSetup.exe	CPU only docker run -d -p 11434:11434 \ -v ollama:/root/.ollama \ --name ollama \ ollama/ollama NVIDIA GPU docker run -d -p 11434:11434 \ --gpus=all \ -v ollama:/root/.ollama \ --name ollama \ ollama/ollama

Installation

Note

We are now publishing the artifacts to both Maven Central and GitHub package repositories.

Track the releases here and update the dependency version according to your requirements.

For Maven

Using Maven Central

In your Maven project, add this dependency:

<dependency>
    <groupId>io.github.ollama4j</groupId>
    <artifactId>ollama4j</artifactId>
    <version>1.0.78</version>
</dependency>

Using GitHub's Maven Package Repository

1. Add GitHub Maven Packages repository to your project's pom.xml or your settings.xml:

<repositories>
    <repository>
        <id>github</id>
        <name>GitHub Apache Maven Packages</name>
        <url>https://maven.pkg.github.com/ollama4j/ollama4j</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

2. Add GitHub server to settings.xml. (Usually available at ~/.m2/settings.xml)

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <servers>
        <server>
            <id>github</id>
            <username>YOUR-USERNAME</username>
            <password>YOUR-TOKEN</password>
        </server>
    </servers>
</settings>

3. In your Maven project, add this dependency:

<dependency>
    <groupId>io.github.ollama4j</groupId>
    <artifactId>ollama4j</artifactId>
    <version>1.0.78</version>
</dependency>

For Gradle

1. Add the dependency

dependencies {
  implementation 'com.github.ollama4j:ollama4j:1.0.78'
}

API Spec

Tip

Find the full API specifications on the website.

Development

Build:

make build

Run unit tests:

make unit-tests

Run integration tests:

make integration-tests

Releases

Newer artifacts are published via GitHub Actions CI workflow when a new release is created from main branch.

Who's using Ollama4j?

• Datafaker: a library to generate fake data
  • https://github.com/datafaker-net/datafaker-experimental/tree/main/ollama-api
• Vaadin Web UI: UI-Tester for Interactions with Ollama via ollama4j
  • https://github.com/TEAMPB/ollama4j-vaadin-ui
• ollama-translator: Minecraft 1.20.6 spigot plugin allows to easily break language barriers by using ollama on the server to translate all messages into a specfic target language.
  • https://github.com/liebki/ollama-translator
• Ollama4j UI: A web UI for Ollama written in Java using Spring Boot and Vaadin framework and Ollama4j. https://github.com/ollama4j/ollama4j-web-ui

Traction

Areas of improvement

• Use Java-naming conventions for attributes in the request/response models instead of the snake-case conventions. ( possibly with Jackson-mapper's @JsonProperty)
• Fix deprecated HTTP client code
• Setup logging
• Use lombok
• Update request body creation with Java objects
• Async APIs for images
• Support for function calling with models like Mistral
  • generate in sync mode
  • generate in async mode
• Add custom headers to requests
• Add additional params for ask APIs such as:
  • options: additional model parameters for the Modelfile such as temperature - Supported params.
  • system: system prompt to (overrides what is defined in the Modelfile)
  • template: the full prompt or prompt template (overrides what is defined in the Modelfile)
  • context: the context parameter returned from a previous request, which can be used to keep a short conversational memory
  • stream: Add support for streaming responses from the model
• Add test cases
• Handle exceptions better (maybe throw more appropriate exceptions)

Get Involved

Contributions are most welcome! Whether it's reporting a bug, proposing an enhancement, or helping with code - any sort of contribution is much appreciated.

References

• Ollama REST APIs

Credits

The nomenclature and the icon have been adopted from the incredible Ollama project.

Thanks to the amazing contributors

Appreciate my work?