BasicAIClient: A Lightweight Java Client Library for AI APIs

Mario Nenno, 2025-01-26

Introduction

The integration of multiple AI API providers into applications has become increasingly essential for developers seeking to streamline their workflows. As the demand for interoperability among diverse services grows, there is a pressing need for lightweight Java client libraries that support minimal JDK requirements and reduce dependency on third-party libraries. Such libraries simplify API calls while ensuring compatibility with older Java runtimes like JDK 8, enabling broader adoption of modern AI capabilities without requiring costly upgrades.

While Python boasts numerous client libraries and a cross-provider solution called aisuite, the landscape for Java clients is less mature. Many existing Java libraries, such as the official OpenAI Java library and OpenAiService (TheoKanning/openai-java), have been discontinued. Current alternatives like LangChain4j and Spring AI require JDK 11 or higher, along with several third-party dependencies.

Lightweight libraries are designed to provide efficient access to various AI services, including OpenAI and other emerging platforms, while maintaining a minimal footprint. By focusing on simplicity and ease of use, they enable developers to integrate advanced functionalities into their applications without the overhead of complex frameworks. This flexibility is particularly valuable for projects requiring quick deployment and low maintenance.

In this article, we explore BasicAIClient, a new lightweight Java client library that supports multiple API providers supporting common text-to-text generation features.

Features

The BasicAIClient is designed with user-friendliness and versatility at its core, making it an excellent choice for those looking to delve into the basics of text-to-text generative AI. It features a learning-friendly design that requires minimal setup and resources, perfect for beginners seeking an easy entry point. The library supports older versions starting from JDK 8 while keeping external dependencies to a minimum, ensuring broad compatibility across various environments without needing extensive configurations.

Additionally, the library offers seamless integration with popular local inference servers such as Ollama and LM Studio, providing users with flexible options for testing and development in their own environments. It also supports several remote API providers that adhere to OpenAI standards, including Groq, OpenRouter, OpenAI, and Anthropic, thus ensuring comprehensive platform support.

The feature set covers simple setting of temperature as well as more advanced settings like streaming response, JSON mode, function/tool calling, and structured output. A detailed logging option via the logDetails variable further aids in debugging and monitoring processes. The library simplifies interactions with multiple providers through a unified API interface, making cross-provider testing and comparison efficient.

Finally, an optional configuration manager allows users to define various API providers within a JSON resource file, facilitating easy switching between different providers programmatically. This flexibility enhances the library's utility in managing connections across diverse platforms, providing both convenience and adaptability for its users.

Requirements

As a runtime environment, JDK version 8 or later is required. For efficient handling of JSON data, the FasterXML Jackson JSON library at version 2.8.8 or newer is utilized. Logging is managed using SLF4J with log4j 2.20.0, although an alternative bridge to log4j 1.x can be employed if desired.

Installation

To integrate the BasicAIClient Java library into your project, begin by defining necessary dependencies in your pom.xml file. Then, download the latest version of the BasicAIClient.jar from its GitHub repository release section. Ensure a log4j2.xml logging configuration file is present in your project directory to handle log generation aiding debugging and monitoring. Finally, add the dependencies from your pom.xml and the downloaded BasicAIClient.jar to your project's classpath to enable the Java compiler and runtime to locate these files during execution.

Usage

To get started with a local inference server like Ollama or LM Studio, simply follow the installation steps outlined in their documentation. Once installed, you’ll be ready to use them without needing to worry about API keys.

When it comes to API keys, they’re only required if you’re working with remote APIs. To obtain one, check the provider’s documentation, which will guide you through the process. Some providers, such as Groq and OpenRouter, even offer free access to specific open-source or open-weight models, though this may come with rate limits. On the other hand, proprietary LLM providers like OpenAI and Anthropic provide access exclusively through paid plans.

Once you have your API key, you can set it up in one of two ways: either by configuring it as an environment variable based on your operating system or by saving it directly in the API configuration file (see below).

Examples

For more detailed guidance on how to make use of the various features examples are provided in the src/test/java/examples directory of the GitHub project page. These examples cover several key functionalities:

• JSON mode
• response streaming
• tool/function calling
• structured output
• use of other remote API providers (OpenRouter, OpenAI and Anthropic)

By referring to these comprehensive examples, you can better understand how to effectively use the client library according to your specific needs.

API configuration file

To centralize your API configurations, create a file named 'aiapis.json' like the example you find in the src/test/resources directory of the project page and put it in the 'resources' directory. This JSON file enables you to define API keys for each provider, either as a literal value ("key") or by referencing an environment variable ("env_key"), along with a list of model names that can be accessed using a custom shortname as the key.

License

The BasicAIClient project is licensed under the Apache License, Version 2.0.

References

Project on Github Download the library as Jar file