Cohere V2 instrumentation: continue `scaffold + chat completions` from my previous work `opentelemetry-python-contrib#4418`

[Nik-Reddy]

Background

Continuation of Cohere instrumentation work that started in open-telemetry/opentelemetry-python-contrib:

• contrib #4418 (scaffolding) - closed unmerged on 2026-05-13, "moving to new repo"
• contrib #4421 (streaming) - closed unmerged on 2026-05-13, same reason
• Original tracking issue: contrib #3050

@lmolkova closure message: "We are moving GenAI instrumentations to the new repository... I am closing this PR here, but you are welcome to reopen it in the new repo."

Filing this issue to lay out the staged-PR roadmap and open questions before opening any PR.

Note on numbering: PR 1 / PR 2 / PR 3 / PR 4 below are the planned PRs against this repo for this work. They are written without # so GitHub does not auto-link them to unrelated existing items in this repo.

Roadmap

Step	Title	Status	Depends on	Origin
PR 1	Scaffold only --> Now PR #102	Ready to merge	-	port of contrib #4418
PR 2	Chat completions (sync + async)	Not started	PR 1	new (was deferred in contrib per reviewer guidance)
PR 3	Streaming (chat_stream sync + async)	Code ported, not adapted	PR 2, #13	port of contrib #4421
PR 4	RAG / citations attribute extraction	Blocked on semconv proposal	PR 2, semconv-genai issue (separate)	new

Each PR lands before the next is opened. Single logical change per PR, per AGENTS.md.

PR 1: Scaffold only (direct port of contrib #4418) --> Now PR #102

What's here:

• Package directory instrumentation/opentelemetry-instrumentation-genai-cohere/ mirroring the opentelemetry-instrumentation-genai-anthropic layout
• CohereInstrumentor(BaseInstrumentor) with empty _instrument / _uninstrument + TODO comment; patch.py is a placeholder
• pyproject.toml (cohere >= 5.13.0 instruments extra, Python 3.10-3.14, entry point under opentelemetry_instrumentor)
• Workspace registration in root pyproject.toml, tox.ini, uv.lock
• tests/ with smoke tests only (instantiation, dependency reporting, instrument/uninstrument lifecycle)
• examples/{manual,zero-code}/ placeholders with scaffold disclaimer
• Towncrier fragment

Not in this PR: any wrap_function_wrapper calls, semconv emission, real example traces.

Fixes part of this issue (scaffolding only).

PR 2: Chat completions (sync + async)

What's planned:

• Wrap cohere.client_v2.ClientV2.chat and cohere.client_v2.AsyncClientV2.chat via wrap_function_wrapper
• Spans + metrics through opentelemetry.util.genai.handler.TelemetryHandler and InferenceInvocation (same handler the existing provider packages use)
• All attributes sourced from opentelemetry.semconv._incubating.attributes.gen_ai_attributes (no hardcoded names): request model, max output tokens, temperature, top_p, top_k, stop sequences, frequency / presence penalty, seed, response id, response model, finish reasons, input/output tokens, operation name, provider name
• Content capture via OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (default off; span-only and event-only modes)
• Error path: re-raise unmodified, span carries error.type + exception event

Tests: VCR happy-path sync + async, error-path, multi-turn message history, exact semconv attribute-name assertions.

Not in this PR: streaming, RAG/citations, V1 client, embed/classify/rerank/tokenize.

Depends on PR 1.

PR 3: Streaming (port of contrib #4421)

What's planned:

• Wrap chat_stream (sync + async) with SSE iterator + per-chunk timing via opentelemetry.util.genai.stream
• VCR streaming happy-path sync + async, chunk-count + finish-reason assertions

Depends on PR 2 landing, and on #13 (the streaming helpers PR 3 builds on).

PR 4: RAG / citations attribute extraction

What's planned:

• Extract documents and citations from Cohere V2 chat responses into gen_ai.rag.documents.* and gen_ai.response.citations.*

Blocked on a separate semconv proposal landing in open-telemetry/semantic-conventions-genai for those attribute namespaces (no such namespace exists today). I will file that proposal separately so the convention is portable across providers.

Additional Context

Compatibility matrix

Axis	Pin
cohere	>= 5.13.0 (V2 GA)
Python	3.10, 3.11, 3.12, 3.13, 3.14
opentelemetry-api, -sdk, -instrumentation, -semantic-conventions	match other instrumentations in this repo
opentelemetry-util-genai	>= 1.0b0.dev (matches anthropic, claude-agent-sdk, etc.)

Open questions

1. Is V2-only acceptable as the initial scope, consistent with how openai-v2 (now genai-openai) is structured?
2. Anything in the migration from opentelemetry-python-contrib I should be aware of beyond the directory move and the genai- prefix rename?

Plan

Scaffold is ready locally as a direct port of contrib #4418 (adapted to the current genai- prefix and module-path conventions). Unless concerns surface, I will open PR 1 in the next few days. PR 2 -> PR 4 follow sequentially.

cc @lmolkova, @lzchen, @JWinermaSplunk, @eternalcuriouslearner

[Nik-Reddy]

@lmolkova, @lzchen @JWinermaSplunk, @eternalcuriouslearner

Update on Cohere instrumentation roadmap:

PR 1 is now open as #102 and matches the scaffold-only scope described in this issue.

Current PR 1 status:

• The Cohere package scaffold is in place: package registration, CohereInstrumentor, placeholder patch module, smoke tests, examples, changelog, and workspace/tox/uv wiring.
• No runtime SDK wrapping or telemetry emission is included yet, by design.
• The PR is approved and CI is passing after rebase, so it should be ready for maintainer merge.

I also re-checked #18 before starting the next PR. That PR added OpenAI-specific chat.completions.parse() structured-output support. It reused the existing OpenAI chat wrappers, but it did not add a provider-agnostic chat wrapper that would automatically cover Cohere.

Based on the current repo layout, I think the next correct step is still PR 2, scoped specifically to Cohere V2 non-streaming chat instrumentation:

• wrap cohere.client_v2.ClientV2.chat
• wrap cohere.client_v2.AsyncClientV2.chat
• use the shared TelemetryHandler / InferenceInvocation lifecycle
• keep Cohere-specific request/response extraction in the Cohere package
• emit provider-agnostic GenAI semantic convention attributes where available
• include sync + async tests for happy path, error path, content capture, usage, finish reasons, and request/response attributes

I am planning to keep streaming as PR 3 rather than starting it next, because chat_stream should build on the shared stream helpers and #13 is still not landed.

Proposed next sequence:

1. PR 1: scaffold - current PR Add Cohere instrumentation package scaffolding #102, ready for merge @lzchen @lmolkova
2. PR 2: Cohere V2 non-streaming chat, sync + async
3. PR 3: Cohere V2 streaming chat, sync + async, after the stream helper work lands

Please let me know if this sequencing looks right. If so, I will start PR 2 after PR #102 merges.