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 Spec
• 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

Or

Installation

Check the releases here.

For Maven

1. In your Maven project, add this dependency:

<dependency>
    <groupId>io.github.amithkoujalgi</groupId>
    <artifactId>ollama4j</artifactId>
  <version>1.0.74</version>
</dependency>

2. Add repository to your project's pom.xml:

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

3. 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>

For Gradle

In your Gradle project, add the dependency using the Kotlin DSL or the Groovy DSL:

dependencies {

    val ollama4jVersion = "1.0.74"

    implementation("io.github.amithkoujalgi:ollama4j:$ollama4jVersion")
}

dependencies {
    implementation("io.github.amithkoujalgi:ollama4j:1.0.74")
}

API Spec

Find the full API specifications on the website.

Development

Build:

make build

Run unit tests:

make ut

Run integration tests:

make it

Releases

Releases (newer artifact versions) are done automatically on pushing the code to the main branch through GitHub Actions CI workflow.

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

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?