Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions .github/workflows/cohere-java-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
name: Cohere Java compatibility

on:
pull_request:
paths:
- 'java/traceai-java-cohere/**'
- 'java/traceai-java-core/**'
- 'java/pom.xml'
- '.github/workflows/cohere-java-tests.yml'
push:
branches: [dev, main]
paths:
- 'java/traceai-java-cohere/**'
- 'java/traceai-java-core/**'
- 'java/pom.xml'
- '.github/workflows/cohere-java-tests.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
compatibility:
name: Cohere ${{ matrix.sdk }} synthetic contracts
runs-on: ubuntu-latest
timeout-minutes: 15
strategy:
fail-fast: false
matrix:
sdk: ['1.9.3', '1.12.0']
defaults:
run:
working-directory: java
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '21'
cache: maven
cache-dependency-path: 'java/**/pom.xml'
- name: Resolve dependencies and compile
run: mvn -B -ntp -pl traceai-java-cohere -am -Dcohere-java.version=${{ matrix.sdk }} -DskipTests package
- name: Run synthetic SDK and OTLP contracts
run: >-
mvn -B -ntp -pl traceai-java-cohere -am
-Dcohere-java.version=${{ matrix.sdk }}
-Dtest=CohereSurfaceTest,CohereOtlpTest,CohereRequestSafetyTest,TracedCohereTransportTest,TracedCohereStreamTest,TracedCohereClientPrivacyTest
-Dsurefire.failIfNoSpecifiedTests=false test
- uses: actions/upload-artifact@v4
if: always()
with:
name: cohere-java-${{ matrix.sdk }}-reports
path: java/traceai-java-cohere/target/surefire-reports/
30 changes: 29 additions & 1 deletion java/traceai-java-cohere/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,17 @@
<dependency>
<groupId>com.cohere</groupId>
<artifactId>cohere-java</artifactId>
<version>1.9.3</version>
<version>${cohere-java.version}</version>
<scope>provided</scope>
</dependency>

<!-- Testing -->
<dependency>
<groupId>io.opentelemetry.proto</groupId>
<artifactId>opentelemetry-proto</artifactId>
<version>1.0.0-alpha</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
Expand All @@ -56,4 +62,26 @@
<scope>test</scope>
</dependency>
</dependencies>

<profiles>
<profile>
<id>cohere-1.12-maven-transport</id>
<activation>
<property>
<name>cohere-java.version</name>
<value>1.12.0</value>
</property>
</activation>
<!-- Cohere 1.12's POM names OkHttp's multiplatform artifact. Maven
needs the JVM artifact explicitly; Gradle selects its JVM variant. -->
<dependencies>
<dependency>
<groupId>com.squareup.okhttp3</groupId>
<artifactId>okhttp-jvm</artifactId>
<version>5.2.1</version>
<scope>test</scope>
</dependency>
</dependencies>
</profile>
</profiles>
</project>
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
package ai.traceai.cohere;

import ai.traceai.FITracer;
import ai.traceai.SemanticConventions;
import com.cohere.api.core.ObjectMappers;
import com.cohere.api.resources.v2.types.V2ChatStreamResponse;
import com.cohere.api.types.ApiMeta;
import com.cohere.api.types.NonStreamedChatResponse;
import com.cohere.api.types.StreamedChatResponse;
import com.cohere.api.types.Usage;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.node.ObjectNode;
import io.opentelemetry.api.trace.Span;

import java.util.ArrayList;
import java.util.List;
import java.util.Map;

/** Shared, privacy-gated attributes for the additional SDK surfaces. */
final class CohereAttributes {
private final FITracer tracer;
private final Span span;
// Never accumulate unbounded output or retain content when capture is disabled.
private final StringBuilder text = new StringBuilder();
private boolean truncated;
private boolean failed;
private static final int MAX_TEXT = 32000;

CohereAttributes(FITracer tracer, Span span) {
this.tracer = tracer;
this.span = span;
span.setAttribute(SemanticConventions.LLM_SYSTEM, "cohere");
span.setAttribute(SemanticConventions.LLM_PROVIDER, "cohere");
}

void model(String model) {
span.setAttribute(SemanticConventions.LLM_MODEL_NAME, model);
span.setAttribute(SemanticConventions.LLM_REQUEST_MODEL, model);
}

void chatInput(Object request) {
if (tracer.getConfig().isHideInputs() || tracer.getConfig().isHideInputMessages()) return;
JsonNode json = inputJson(request);
if (json == null) return;
List<Map<String, String>> messages = new ArrayList<>();
if (json.has("messages")) {
for (JsonNode message : json.path("messages")) {
messages.add(FITracer.message(message.path("role").asText(), content(message.path("content"))));
}
} else {
if (json.hasNonNull("preamble")) messages.add(FITracer.message("system", json.get("preamble").asText()));
for (JsonNode message : json.path("chat_history")) {
String role = message.path("role").asText().toLowerCase(java.util.Locale.ROOT);
messages.add(FITracer.message("chatbot".equals(role) ? "assistant" : role,
message.path("message").asText()));
}
messages.add(FITracer.message("user", json.path("message").asText()));
}
tracer.setInputMessages(span, messages);
tracer.setInputValue(span, json.has("messages") ? json.get("messages").toString() : json.path("message").asText());
tracer.setRawInput(span, json.toString());
}

void rawInput(Object request) {
if (tracer.getConfig().isHideInputs()) return;
JsonNode json = inputJson(request);
if (json != null) tracer.setRawInput(span, json.toString());
}

void rawOutput(Object response) {
if (tracer.getConfig().isHideOutputs()) return;
JsonNode json = json(response);
if (json != null) tracer.setRawOutput(span, json.toString());
}

void chatOutput(Object response) {
if (!captureOutput()) return;
JsonNode json = json(response);
if (json == null) return;
String result = json.has("text") ? json.get("text").asText() : content(json.path("message").path("content"));
tracer.setOutputValue(span, result);
tracer.setOutputMessages(span, List.of(FITracer.message("assistant", result)));
tracer.setRawOutput(span, json.toString());
}

void usage(Usage usage) {
usage.getTokens().ifPresent(tokens -> {
tokens.getInputTokens().ifPresent(value -> span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_PROMPT, value.longValue()));
tokens.getOutputTokens().ifPresent(value -> span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_COMPLETION, value.longValue()));
if (tokens.getInputTokens().isPresent() && tokens.getOutputTokens().isPresent()) {
span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_TOTAL,
tokens.getInputTokens().get().longValue() + tokens.getOutputTokens().get().longValue());
}
});
}

void meta(ApiMeta meta) {
meta.getTokens().ifPresent(tokens -> {
tokens.getInputTokens().ifPresent(value -> span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_PROMPT, value.longValue()));
tokens.getOutputTokens().ifPresent(value -> span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_COMPLETION, value.longValue()));
if (tokens.getInputTokens().isPresent() && tokens.getOutputTokens().isPresent()) {
span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_TOTAL,
tokens.getInputTokens().get().longValue() + tokens.getOutputTokens().get().longValue());
}
});
meta.getBilledUnits().ifPresent(units -> {
units.getInputTokens().ifPresent(value -> span.setAttribute("cohere.billed_units.input_tokens", value.longValue()));
units.getSearchUnits().ifPresent(value -> span.setAttribute("cohere.rerank.search_units", value.longValue()));
});
}

void embeddingMeta(ApiMeta meta) {
meta(meta);
// Embeddings often report only billed input tokens. Keep actual usage
// when present (including zero), and never fabricate output or total counts.
if (meta.getTokens().flatMap(tokens -> tokens.getInputTokens()).isEmpty()) {
meta.getBilledUnits().flatMap(units -> units.getInputTokens()).ifPresent(value ->
span.setAttribute(SemanticConventions.LLM_TOKEN_COUNT_PROMPT, value.longValue()));
}
}

TracedCohereStream.EventState v1Event(StreamedChatResponse event) {
event.getStreamStart().ifPresent(start -> span.setAttribute(SemanticConventions.LLM_RESPONSE_ID, start.getGenerationId()));
event.getTextGeneration().ifPresent(delta -> append(delta.getText()));
if (event.getStreamEnd().isEmpty()) return TracedCohereStream.EventState.CONTINUE;
var end = event.getStreamEnd().get();
NonStreamedChatResponse response = end.getResponse();
response.getGenerationId().ifPresent(id -> span.setAttribute(SemanticConventions.LLM_RESPONSE_ID, id));
response.getMeta().ifPresent(this::meta);
if (captureOutput() && response.getText() != null) {
text.setLength(0);
truncated = false;
append(response.getText());
}
return finishReason(end.getFinishReason().toString(), null);
}

TracedCohereStream.EventState v2Event(V2ChatStreamResponse event) {
event.getMessageStart().flatMap(start -> start.getId())
.ifPresent(id -> span.setAttribute(SemanticConventions.LLM_RESPONSE_ID, id));
event.getContentDelta().flatMap(delta -> delta.getDelta()).flatMap(delta -> delta.getMessage())
.flatMap(message -> message.getContent()).flatMap(content -> content.getText()).ifPresent(this::append);
if (event.getMessageEnd().isEmpty()) return TracedCohereStream.EventState.CONTINUE;
var end = event.getMessageEnd().get();
end.getId().ifPresent(id -> span.setAttribute(SemanticConventions.LLM_RESPONSE_ID, id));
end.getDelta().flatMap(delta -> delta.getUsage()).ifPresent(this::usage);
String reason = end.getDelta().flatMap(delta -> delta.getFinishReason()).map(Object::toString).orElse("");
String error = end.getDelta().flatMap(delta -> delta.getError()).orElse(null);
return finishReason(reason, error);
}

boolean hasError() {
return failed;
}

TracedCohereStream.EventState finishReason(String reason, String error) {
if (!reason.isEmpty()) span.setAttribute(SemanticConventions.LLM_RESPONSE_FINISH_REASON, reason);
if (error != null || reason.toLowerCase(java.util.Locale.ROOT).startsWith("error")) {
failed = true;
tracer.setError(span, new IllegalStateException(error == null ? "Cohere generation failed" : error));
return TracedCohereStream.EventState.ERROR;
}
return TracedCohereStream.EventState.COMPLETE;
}

void streamOutput() {
if (!captureOutput()) return;
tracer.setOutputValue(span, text.toString());
tracer.setOutputMessages(span, List.of(FITracer.message("assistant", text.toString())));
if (truncated) span.setAttribute("cohere.stream.output_truncated", true);
}

private void append(String value) {
if (!captureOutput()) return;
int remaining = MAX_TEXT - text.length();
text.append(value, 0, Math.min(remaining, value.length()));
truncated |= value.length() > remaining;
}

private boolean captureOutput() {
return !tracer.getConfig().isHideOutputs() && !tracer.getConfig().isHideOutputMessages();
}

private static String content(JsonNode content) {
if (content.isTextual()) return content.asText();
StringBuilder result = new StringBuilder();
if (content.isArray()) for (JsonNode part : content) result.append(part.path("text").asText(""));
return result.toString();
}

private static JsonNode inputJson(Object request) {
JsonNode json = json(request);
if (json == null) return null;
// Authentication is never trace content, even with input capture enabled.
// Only edit the serialized tracing copy; the SDK still needs these tokens.
for (JsonNode connector : json.path("connectors")) {
if (connector.isObject()) ((ObjectNode) connector).remove("user_access_token");
}
return json;
}

private static JsonNode json(Object value) {
try {
// Use the SDK's Jackson mapping, which understands its unions and Optional fields.
return ObjectMappers.JSON_MAPPER.valueToTree(value);
} catch (IllegalArgumentException error) {
// Unsupported user-supplied extension data must not break the provider call.
return null;
}
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@

/**
* Instrumentation wrapper for Cohere Java client.
* Wraps the Cohere client to provide automatic tracing of all API calls.
* Traces v1 chat, embed, rerank and chat streams, plus the same operations through
* {@link #v2()}. Calls made directly on {@link #unwrap()} are not traced.
*
* <p>Usage:</p>
* <pre>
Expand Down Expand Up @@ -100,7 +101,8 @@ public NonStreamedChatResponse chat(ChatRequest request) {
span.setAttribute("cohere.preamble", preamble));
}

tracer.setRawInput(span, request);
// Use the same credential-safe tracing copy as the streaming path.
new CohereAttributes(tracer, span).rawInput(request);

// Execute request
NonStreamedChatResponse response = client.chat(request);
Expand Down Expand Up @@ -308,9 +310,53 @@ public RerankResponse rerank(RerankRequest request) {
}

/**
* Gets the underlying Cohere client.
* Returns a typed traced facade for v2 chat, embed, rerank and chat streaming.
* @return the traced v2 client
*/
public TracedCohereV2Client v2() {
return new TracedCohereV2Client(client.v2(), tracer);
}

/**
* Opens a traced v1 chat stream. Always use try-with-resources when consuming it.
* @param request the stream request
* @return the closeable stream of unchanged SDK events
*/
public TracedCohereStream<StreamedChatResponse> chatStream(ChatStreamRequest request) {
return chatStream(request, null);
}

/**
* Opens a traced v1 chat stream with SDK request options.
* @param request the stream request
* @param options the SDK request options, or null for defaults
* @return the closeable stream of unchanged SDK events
*/
public TracedCohereStream<StreamedChatResponse> chatStream(
ChatStreamRequest request, com.cohere.api.core.RequestOptions options) {
Span span = tracer.startSpan("Cohere Chat Stream", FISpanKind.LLM);
CohereAttributes attributes = new CohereAttributes(tracer, span);
try (Scope ignored = span.makeCurrent()) {
request.getModel().ifPresent(attributes::model);
request.getTemperature().ifPresent(value ->
span.setAttribute(SemanticConventions.LLM_REQUEST_TEMPERATURE, value.doubleValue()));
request.getMaxTokens().ifPresent(value ->
span.setAttribute(SemanticConventions.LLM_REQUEST_MAX_TOKENS, value.longValue()));
attributes.chatInput(request);
return new TracedCohereStream<>(client.chatStream(request, options), tracer, span,
attributes::v1Event, attributes::streamOutput);
} catch (RuntimeException | Error error) {
tracer.setError(span, error);
span.end();
throw error;
}
}

/**
* Gets the underlying, untraced Cohere client. Calls through this escape hatch
* bypass instrumentation; use {@link #v2()} for supported v2 operations.
*
* @return the wrapped Cohere client
* @return the original SDK client, without tracing
*/
public Cohere unwrap() {
return client;
Expand Down
Loading
Loading