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

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

Start by reviewing PR #102, AGENTS.md, and the scaffold at instrumentation/opentelemetry-instrumentation-genai-cohere/. Then inspect the existing provider packages and the planned ClientV2.chat and AsyncClientV2.chat entry points. Done means the staged chat-completion scope is implemented with the listed VCR, error-path, history, and semantic-convention tests passing; streaming and RAG remain separate.