[nik13]

Summary

Keep the Cohere Java integration and repair its missing SDK surfaces rather than delete a useful package. The existing wrapper traced only synchronous v1 chat/embed/rerank; its unwrap() escape hatch did not trace v2 or streams, despite the all-API-calls Javadoc.

• Add the typed traced.v2() facade for chat, embed, rerank and chat streaming, including SDK RequestOptions overloads.
• Add closeable v1/v2 chat streams. Preserve SDK events, close the underlying transport, restore caller context, and end exactly one span on completion, early close, exhaustion or failure. A stream without its terminal event is incomplete rather than successful.
• Capture model, response ID, finish reason and usage, with privacy-gated content and bounded streaming text. Preserve SDK exceptions on the new surfaces and distinguish provider error finish reasons.
• Keep all existing v1 methods and unwrap() behavior intact; explicitly document that the escape hatch bypasses tracing.
• Add a floor/current SDK CI matrix. Do not change package versions or changelogs.

Evidence and compatibility

The upstream 1.9.3 sources and 1.12.0 sources expose these typed v2 and streaming methods. No native OpenTelemetry path was found in those SDK sources; this change does not claim a dedicated competitor Java integration was established.

Cohere 1.12.0's Maven POM references the multiplatform okhttp:5.2.1 artifact. The current-version test profile explicitly supplies okhttp-jvm:5.2.1. Maven applications selecting that SDK version need the JVM artifact too. The default SDK floor remains 1.9.3.

Streams return tool/citation/reasoning events unchanged, but reconstruct text output only. Async clients, raw-response clients and other endpoints remain outside this facade. Both tested SDKs swallow malformed SSE payloads; a resulting EOF is recorded as incomplete, not falsely marked successful.

Verification

• Before implementation, both CohereSurfaceTest cases failed with NoSuchMethodException for v2() and chatStream(ChatStreamRequest).
• After implementation, clean compilation and 93 tests passed at each SDK version: 56 Cohere tests plus 37 core tests; zero failures, errors or skips.
• Runs used Maven offline under the existing macOS sandbox denying outbound traffic except localhost. IPv4 stack selection kept local Java OTLP sockets inside the sandbox's localhost rule. No vendor/model API calls or real credentials were used.
• Real SDK request serialization and response/stream decoding run against an OkHttp fake transport. Coverage includes request options, v1 compatibility/privacy, completion, early close, EOF, parse errors, provider/transport errors, iterator and close failures, exception identity, context restoration and bounded output.
• OTLP/HTTP tests decode actual protobuf requests received by a localhost collector, checking one span per operation, token counts, status and absence of hidden content/error details.
• The staged documentation examples compile at both SDK versions.

Re-run from java/ with either 1.9.3 or 1.12.0:

mvn -B -pl traceai-java-cohere -am -Dcohere-java.version=1.9.3 \
  -Dtest=CohereSurfaceTest,CohereOtlpTest,TracedCohereTransportTest,TracedCohereStreamTest,TracedCohereClientPrivacyTest,FITracerTest,FITracerPrivacyTest,TraceAIVersionTest \
  -Dsurefire.failIfNoSpecifiedTests=false clean test

Release and docs

Release this Java package before updating the customer guide to use the new facade. A corrected src/pages/docs/integrations/traceai/java/cohere.mdx draft is staged for that follow-up; no docs PR advertises these APIs before registry availability. No merge, tag or package publication is performed by this PR.

Self-review

No blocking findings after the compatibility and privacy checks. No Python, migrations or frontend changes: those mechanical gates are not applicable. This repository has no product e2e/ coverage harness; provider transport and OTLP wire contracts cover this SDK change.

E2E: exempt (SDK-only synthetic transport and OTLP contracts; no product e2e harness)

Generated with Claude Code