Reduce external implementation types exposed by the GPULlama3 integration API

[orionpapadakis]

Description

The langchain4j-gpu-llama3 module currently exposes classes from external dependencies through its public methods.

Some exposure is required by LangChain4j’s model contracts:

public ChatResponse doChat(ChatRequest request)

public void doChat(
ChatRequest request,
StreamingChatResponseHandler handler
)

These types come from langchain4j-core:

• ChatRequest
• ChatResponse
• StreamingChatResponseHandler

This exposure is intentional and cannot be removed without departing from the LangChain4j model interfaces.

The integration also exposes GPULlama implementation types:

public Model getModel()

public Sampler getSampler()

These types come from the gpu-llama3 dependency:

• org.beehive.gpullama3.model.Model
• org.beehive.gpullama3.inference.sampler.Sampler

Revapi reports all these classes as:

java.class.externalClassExposedInAPI

The current version handles this with targeted exceptions in langchain4j-gpu-llama3/revapi.json. This is appropriate for a non-breaking update, but it highlights that applications can depend directly on
GPULlama implementation classes through the LangChain4j integration.

Why this matters

Exposing Model and Sampler couples the integration’s public API to GPULlama’s internal API.

For example:

GPULlama3ChatModel chatModel = ...;

Model model = chatModel.getModel();
Sampler sampler = chatModel.getSampler();

If GPULlama later moves, renames, or changes either class, the LangChain4j integration may be forced to introduce a breaking API change even when its own behavior remains unchanged.

The LangChain4j request and response types do not have the same problem: they are part of the framework contract that the integration is expected to implement.

Proposed solution for a future major release

Review whether getModel() and getSampler() need to remain public.

If they are only used internally, reduce their visibility:

Model getModel()

Sampler getSampler()

or:

protected Model getModel()

protected Sampler getSampler()

This would remove the GPULlama types from the integration’s public API.

Because reducing visibility is a breaking change, this should be considered only for a release where API changes are allowed.

Alternatives

1. Introduce integration-owned abstractions

Return stable types owned by langchain4j-gpu-llama3:

public GPULlamaModelHandle modelHandle()

The handle could expose only operations that applications genuinely need without publishing the complete GPULlama implementation API.

This provides better isolation but requires designing and maintaining another abstraction.

2. Keep the current API

Continue exposing Model and Sampler and retain the targeted Revapi exceptions.

This preserves compatibility and gives advanced users direct access to GPULlama, but intentionally couples the integration API to GPULlama.

3. Deprecate before removal

Deprecate the getters first:

@deprecated(forRemoval = true)
public Model getModel()

@deprecated(forRemoval = true)
public Sampler getSampler()

Document the replacement, then remove them in a later major release. This offers the clearest migration path if consumers currently use these methods.

4. Enable Revapi dependency checking

Configure:

true

This is not currently recommended. It would make the module responsible for analysing dependency API changes and could produce unrelated compatibility reports.

Suggested next steps

• Determine whether external users rely on getModel() or getSampler().
• Decide whether direct access to GPULlama internals is an intentional supported feature.
• If not, deprecate both methods and introduce a replacement where necessary.
• Keep the LangChain4j contract types exposed.
• Retain the targeted Revapi exceptions until a breaking release can implement the chosen API change.