Skip to content

fix(mistralai): adapt native telemetry for current Python SDK - #458

Merged
nik13 merged 16 commits into
devfrom
fix/mistralai-python-sdk-compat
Nov 2, 2026
Merged

nik13 merged 16 commits into
devfrom
fix/mistralai-python-sdk-compat

Conversation

@nik13

@nik13 nik13 commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Support the current Mistral Python SDK without duplicating its native OpenTelemetry spans, while preserving the legacy MistralAIInstrumentor entry point.

Mistral 3.6 provides native request hooks and a per-client tracer provider. This change routes those native spans through FITracer instead of creating a second span in completion wrappers. Lightweight method observers keep the existing native span open through SDK response decoding. It adds Future AGI span kinds and privacy handling, corrects native HTTP/stream error status, and captures conversation SSE output and final usage on the existing span. Existing clients, suppression, repeated registration, and restoring a previous native provider are covered.

Native JSON messages apply TraceConfig's existing field policies to text, reasoning, tool-result payloads, and input image parts, including SDK-created child spans and creation/batch attributes. Tool results from chat messages and conversation function results honor hide_input_text, including chunked text payloads, without dropping tool-call identifiers. Structured tool results also apply hide_input_images and the base64 size limit to both string and object image_url chunks, preserving permitted text, URL detail metadata, and tool-call IDs without changing the model request. Whole-direction controls still take precedence. Malformed message attributes are dropped rather than forwarded without privacy checks. Conversation streams reuse the SDK's OTel content formatter and use tool_call_id, not the conversation entry ID, to identify function calls. Interleaved function-call argument deltas are accumulated per output/call identity. Native HTTP URL attributes remove proxy userinfo independently of content-hiding flags.

Async cancellation before a response arrives now ends the SDK-owned request span with ERROR and re-raises the original cancellation. The adapter preserves the SDK's send/context handling, does not create another span, and only finishes adapted native spans. It weakly tracks client wrappers for cleanup, restores the previous send function on uninstrumentation, and respects later customer replacements. Telemetry cleanup failures cannot replace application cancellation or log private exception text.

For SDK 1.x, retain the completion wrappers, add embeddings, support generator and EventStream lifecycles, and restore streaming usage/tool-call accumulation. Request transport options and credentials are not copied into content attributes. Embedding vectors are not captured. Legacy embedding text is recorded only in embedding-specific attributes and honors all three input privacy controls, including with published core 1.2.2. Cancelled legacy async requests end their existing spans and preserve the original cancellation. Legacy chat and agent completion payloads are exported only through policy-aware semantic attributes; redundant raw input/output copies are removed, including streaming output. This closes selective text/message privacy leaks without modifying application requests or responses. Native per-parameter attributes honor invocation-parameter privacy while retaining model identity and usage.

SDK stream iteration is observed without creating additional spans: decoding failures, including a buffered final event at EOF, mark the existing native span ERROR before export. Streamed agent completions use the same LLM classification as nonstreaming agent completions. Uninstrumentation restores SDK iterator and observed request methods. Nonstreaming response validation failures also mark that same span ERROR before export, including malformed JSON and unexpected content types. Per-call context isolates concurrent requests, and cancellation/decoder exceptions reach the application unchanged. Conversation SSE parsing uses CR/LF boundaries only, preserving Unicode text separators inside JSON.

Compatibility

  • Supported SDK ranges: >=1.1,<2 and >=3.6,<4, on Python 3.10–3.13.
  • The former 1.0.2 floor cannot resolve with the core's Pydantic requirement; 1.1.0 is the first compatible floor. SDK 2.x and 3.0–3.5 are not advertised as supported.
  • Current SDK examples use from mistralai.client import Mistral; legacy applications keep their top-level import.
  • The native adapter deliberately selects the provider passed to the instrumentor. Uninstrument only after finishing requests and closing streams; original per-client provider selection is restored.
  • No version or changelog release sections were hand-edited. The docs-site update is held until this package change is released.

This is separate from #248's multi-message input aggregation change and #412's TypeScript repair. The older supporting <2 dependency cap in #248 must not overwrite this compatibility range.

Validation

Real SDK HTTP/SSE contracts cover sync/async chat, agents, embeddings, conversation start/append/restart and streams, errors, early closure, privacy, parent context, concurrent requests, and telemetry failure isolation. Cancellation regressions cover explicit cancellation and application timeouts during chat, embeddings, conversation and streaming setup, including a concurrent successful request on the same client. Loopback tests inspect OTLP JSON and protobuf with plain/gzip transport, including selective tool-result privacy, cancellation error status, native child spans, structured conversation parts, and distinct entry/tool-call identifiers, and execute the README quickstart. Distribution tests use clean wheel/sdist installations and the published core package. Dedicated CI runs SDK 1.1.0, 1.12.4, 3.6.0 and 3.7.0 with outbound networking disabled during tests. The repaired wheel/sdist matrix passes 272 tests per legacy SDK and 642 per native SDK; version-specific cases are skipped. Regression coverage also checks request immutability, percent-encoded/IPv6 URL credentials, selective embedding privacy in sync/async calls, cancellation identity, interleaved tool calls, decoder errors without a context manager, and iterator restoration. Additional coverage exercises selective legacy chat/agent privacy for sync/async and streaming calls with explicit/environment configuration, native invocation-parameter controls, malformed response decoding across chat/agents/embeddings/FIM/conversations, decoder cancellation identity, concurrent decoding, and Unicode separators with LF/CRLF/CR event boundaries.

No live model or Cloud request is required for these contracts. Internal-standards self-review covers the SDK boundaries, native-span ownership, privacy, failure paths, and release scope. No product API, database migration, frontend, or OSS/EE boundary changes; no task-specific ticket was supplied.

E2E coverage

not applicable (no e2e/ harness) · flows hit: n/a · marker: n/a · verdict: not applicable

Latest follow-up repairs

  • Legacy SDK message and typed text/image chunk extraction retains policy-aware semantic content without mutating the caller's messages; base64 image URLs now use the image.url leaf so TraceConfig enforces size limits.
  • Legacy streaming text-chunk deltas are accumulated into semantic output attributes, honoring output-text privacy.
  • Structured chat.parse/parse_async keep the existing completion span open through schema decoding (legacy and native SDKs); parse errors mark that single span ERROR without altering the application exception. SDK 1.1, which has no parse API, remains supported.
  • Failing-first independent reviewer regressions and the registration assertions are committed. Rebuilt wheel/sdist and ran isolated wheel tests with outbound network denied: SDK 1.1.0/Python 3.10: 312 passed; SDK 1.12.4/Python 3.12: 324 passed; SDK 3.6.0/Python 3.10: 690 passed; SDK 3.7.0/Python 3.13: 690 passed. Applicable version-specific tests skipped. Current dev merged normally; release plan check passes.

🤖 Generated with Claude Code

nik13 and others added 16 commits October 31, 2026 16:27
Preserve legacy completions and add embedding coverage, repair stream lifecycle and usage extraction, and exercise both SDK generations through real offline transports.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Apply existing field policies to native JSON messages at every FITracer boundary, reuse SDK content conversion for conversation streams, and preserve tool invocation IDs. Cover the regressions with real SDK and loopback OTLP contracts.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Honor input-text privacy for native tool response payloads and close the SDK-owned span when an async send is cancelled, preserving cancellation and native context handling.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Python 3.10 discards Task.cancel messages at the awaiter even without instrumentation. Assert task cancellation by type while keeping direct-await message checks and span cleanup assertions on all versions.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Mask native tool response image chunks with the existing TraceConfig policy, including base64 size limits, while preserving permitted text and call identifiers.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Keep the legacy and native floors in the offline distribution matrix and exercise Mistral 3.7.0 on Python 3.13.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Redact HTTP URL userinfo, isolate legacy embedding text behind selective privacy, and finish cancelled legacy async requests. Reassemble conversation tool deltas, observe SDK decoder failures on the existing native span, and classify streamed agent completions consistently.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Remove unmasked legacy chat payload copies; apply invocation privacy to
native parameter keys. Keep existing native spans open through SDK decoding
and parse conversation SSE only at CR/LF boundaries. Cover sync/async,
streaming, cancellation, concurrency and SDK floor/latest contracts.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit cb2e4c6 into dev Nov 2, 2026
25 checks passed
@nik13
nik13 deleted the fix/mistralai-python-sdk-compat branch November 2, 2026 22:17
@nik13 nik13 mentioned this pull request Nov 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant