From 62d987b58c4e595eb94847f86a8c896f32cd4d09 Mon Sep 17 00:00:00 2001 From: Nikhil Pareek <8347993+nik13@users.noreply.github.com> Date: Sat, 31 Oct 2026 09:44:14 -0700 Subject: [PATCH] fix(ollama-java): document released legacy SDK setup Pin the provided Ollama4j SDK, use working released chat, and state current SDK and tracing boundaries. Co-Authored-By: Claude Code --- scripts/integrations.test.mjs | 1 + scripts/ollama-java.test.mjs | 34 +++++++++ .../traceai/java/llm-providers.mdx | 69 ++++++++++++------- 3 files changed, 78 insertions(+), 26 deletions(-) create mode 100644 scripts/ollama-java.test.mjs diff --git a/scripts/integrations.test.mjs b/scripts/integrations.test.mjs index 0a8e2c289..33275222a 100644 --- a/scripts/integrations.test.mjs +++ b/scripts/integrations.test.mjs @@ -1,3 +1,4 @@ +import './ollama-java.test.mjs'; import test from 'node:test'; import assert from 'node:assert/strict'; import fs from 'node:fs'; diff --git a/scripts/ollama-java.test.mjs b/scripts/ollama-java.test.mjs new file mode 100644 index 000000000..876ade6fd --- /dev/null +++ b/scripts/ollama-java.test.mjs @@ -0,0 +1,34 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; + +const page = readFileSync(new URL('../src/pages/docs/integrations/traceai/java/llm-providers.mdx', import.meta.url), 'utf8'); +const section = page.split('## Ollama\n')[1]?.split('\n## IBM Watsonx')[0]; + +test('Ollama Java installs the released wrapper and its explicit legacy SDK dependency', () => { + assert.ok(section); + assert.match(section, /com\.futureagi<\/groupId>\s*traceai-java-ollama<\/artifactId>\s*1\.0\.0<\/version>/); + assert.match(section, /io\.github\.ollama4j<\/groupId>\s*ollama4j<\/artifactId>\s*1\.0\.79<\/version>/); + assert.match(section, /com\.futureagi:traceai-java-ollama:1\.0\.0/); + assert.match(section, /io\.github\.ollama4j:ollama4j:1\.0\.79/); + assert.doesNotMatch(section, /main-SNAPSHOT|com\.github\.future-agi/); +}); + +test('Ollama Java states the SDK boundary and uses working released chat with shutdown', () => { + assert.match(section, /1\.1\.7/); + assert.match(section, /not compatible/); + assert.match(section, /provided/); + assert.match(section, /traced\.chat\(/); + assert.match(section, /finally\s*\{\s*TraceAI\.shutdown\(\)/); + assert.doesNotMatch(section, /traced\.generate\(/); + assert.match(section, /`generate\(\)`.*1\.0\.0/); +}); + +test('Ollama Java does not promise unsupported streaming, tools or usage', () => { + assert.match(section, /[Ss]treaming callbacks/); + assert.match(section, /tool-call attributes/); + assert.match(section, /token usage/); + assert.match(section, /unwrap\(\)/); + assert.match(section, /client-side/); + assert.doesNotMatch(section, /server's own timing/); +}); diff --git a/src/pages/docs/integrations/traceai/java/llm-providers.mdx b/src/pages/docs/integrations/traceai/java/llm-providers.mdx index f332e76d9..406c7b57a 100644 --- a/src/pages/docs/integrations/traceai/java/llm-providers.mdx +++ b/src/pages/docs/integrations/traceai/java/llm-providers.mdx @@ -161,24 +161,40 @@ Azure OpenAI captures tool call attributes when the model invokes tools, and han ## Ollama -Wraps `io.github.ollama4j.OllamaAPI` for local Ollama models. +Trace local Ollama chat and embedding requests with `TracedOllamaAPI`, the wrapper for the legacy `io.github.ollama4j.OllamaAPI` client. + +Use **Ollama4j 1.0.79** with this wrapper. Ollama4j 1.1.7 uses `io.github.ollama4j.Ollama` instead and is not compatible. The SDK is a `provided` dependency, so add both packages explicitly from Maven Central; no JitPack repository is needed. ```xml Maven - com.github.future-agi.traceAI + com.futureagi traceai-java-ollama - main-SNAPSHOT + 1.0.0 + + + io.github.ollama4j + ollama4j + 1.0.79 ``` ```groovy Gradle -implementation 'com.github.future-agi.traceAI:traceai-java-ollama:main-SNAPSHOT' +repositories { + mavenCentral() +} + +dependencies { + implementation 'com.futureagi:traceai-java-ollama:1.0.0' + implementation 'io.github.ollama4j:ollama4j:1.0.79' +} ``` +Start your Ollama server at `http://localhost:11434` and make sure the `llama3` model is installed, or replace the model name below with one you already have. Configure the `FI_*` variables from the [Java SDK setup](/docs/integrations/traceai/java) before running this example. Local model inference stays on your Ollama server; captured trace content is sent to Future AGI. + ```java import ai.traceai.TraceAI; import ai.traceai.ollama.TracedOllamaAPI; @@ -188,33 +204,34 @@ import io.github.ollama4j.models.chat.OllamaChatMessageRole; import java.util.List; TraceAI.initFromEnvironment(); +try { + OllamaAPI api = new OllamaAPI("http://localhost:11434"); + TracedOllamaAPI traced = new TracedOllamaAPI(api); + + var response = traced.chat("llama3", List.of( + new OllamaChatMessage(OllamaChatMessageRole.USER, + "What is the capital of France?") + )); + System.out.println(response.getResponse()); +} finally { + TraceAI.shutdown(); +} +``` -OllamaAPI api = new OllamaAPI("http://localhost:11434"); -TracedOllamaAPI traced = new TracedOllamaAPI(api); - -// Generate -var result = traced.generate("llama3", "What is the capital of France?"); -System.out.println(result.getResponse()); - -// Chat -var chatResult = traced.chat("llama3", List.of( - new OllamaChatMessage(OllamaChatMessageRole.USER, "Hello!") -)); +For a long-running application, initialize once at startup and call `TraceAI.shutdown()` when the application exits. Open your project in Future AGI to inspect the **Ollama Chat** span. -// Embeddings -var embedding = traced.embed("llama3", "Hello world"); +### Supported operations -// List models -var models = traced.listModels(); -``` +| Wrapper method | Span | +| --- | --- | +| `chat(model, messages)` | Ollama Chat (LLM) | +| `embed(model, text)` | Ollama Embed (EMBEDDING) | +| `embedBatch(model, texts)` | Ollama Embed Batch (EMBEDDING) | +| `listModels()` | Ollama List Models (LLM) | -**Spans created:** -- `generate()` - "Ollama Generate" (LLM) -- `chat()` - "Ollama Chat" (LLM) -- `embed()` - "Ollama Embed" (EMBEDDING) -- `listModels()` - "Ollama List Models" (LLM) +Use `chat()` for text generation: `generate()` in traceAI 1.0.0 throws before sending the request. Choose an embedding-capable model when using `embed()` or `embedBatch()`. -Ollama spans include `ollama.response_time_ms` from the Ollama server's own timing. +Only calls through the wrapper are traced. Streaming callbacks, structured tool-call attributes and token usage are not supported; calls through `unwrap()` bypass tracing. `ollama.response_time_ms` records the SDK's client-side elapsed time for chat, not the server's model-evaluation duration. ---