[OPIK-5664] [SDK] feat: global client management API with context-wise propagation and batching warning

[alexkuzmik]

Details

Global Client Management API

Introduces get_global_client(), set_global_client(), reset_global_client(), and get_current_client_raw() to replace the lru_cache-based get_client_cached() singleton. The new API supports context-local client overrides via contextvars, fixing OPIK-5664 where EvaluationSuite.run() ignored the parent Opik client.

Resolution order for get_global_client():

1. Context-local client (set via set_global_client(client, context_wise=True))
2. Global singleton (set via set_global_client(client))
3. Auto-created default client

Key changes:

• EvaluationSuite stores and propagates the parent Opik client through evaluate_suite()
• StreamingExecutor sets the client in each worker thread via set_global_client(context_wise=True)
• All integrations resolve the client lazily at runtime via @property (no more storing at init)
• ADK patchers no longer require an opik_client argument
• get_client_cached() kept as a thin delegate for backwards compatibility

Batching Warning

Adds a public batching: bool = True parameter to Opik.__init__ (enabled by default). When update operations (Span.end()/update(), Trace.end()/update(), Opik.update_span()/update_trace()) are called on a client with batching enabled, a warning is emitted — updates can be silently dropped by the server if they arrive before the batched create request is flushed, resulting in data loss.

• Streamer.use_batching property to check batching state
• _use_batching deprecated in favor of public batching
• All internal callsites migrated to batching=True

Test Improvements

• Unit test teardown uses reset_global_client(end_client=False) — avoids network calls, cut test time from ~44s to ~22s
• New tests for client propagation through evaluate_suite() and worker threads

Change checklist

• User facing
• Documentation update

Issues

• OPIK-5664

Testing

• 2769 unit tests pass
• New tests verify:
  • Explicit client used for experiment creation
  • EvaluationSuite.run() forwards stored client to evaluate_suite()
  • Worker threads see the same client via get_global_client()

Documentation

N/A — no user-facing documentation changes required. The new batching parameter and get_global_client()/set_global_client() APIs are documented via docstrings.

[github-actions]

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Documentation section.

[github-actions]

📋 PR Linter Failed

❌ Missing Section. The description is missing the ## Documentation section.

[alexkuzmik]

Addressing baz-reviewer comments

Fixed

Comment	File	Fix
batching or _use_batching ignores batching=False	opik_client.py:111,147	Fixed in 76c2a5a — _use_batching default changed to False so Opik(batching=False) works correctly
Single-worker branch missing set_global_client	evaluation_tasks_executor.py:212	Fixed in d86baf2 — workers==1 path now calls set_global_client(client, context_wise=True) before running tasks inline
OpikTracer arg order changed	haystack/opik_tracer.py	Fixed in 572cadb — opik_client kept as first positional param for backwards compatibility

Skipping (by design)

Comment	File	Rationale
patch_adk dropped opik_client param — callers will crash	patchers.py:26	All callers updated in the same PR. patch_adk is internal API, no external consumers.
Duplicated batching warning — extract helper	trace_client.py:71, span_client.py:94,95	4 lines per site, a helper adds indirection for no gain. Each callsite passes a different method name.
Warning fires on every call — use log_once	opik_client.py:711	Intentional — we want users to see the warning every time to push them to fix the issue.
Race on _global_singleton in get_global_client()	opik_client.py:2759	Same race profile as the lru_cache approach it replaced. GIL protects the assignment in CPython. Adding a lock is over-engineering for the same risk.
OpikTracer accepts opik_client but ignores it	haystack/opik_tracer.py:34	Intentional — deprecated param kept for backwards compatibility. Client resolves lazily via @property.
_temporary_client_context leaks context-local into global	smoke_test.py:127	It uses set_global_client (global, not context-local) and properly restores the previous client in finally. No leak.
Import style (from vs module import)	configure.py:13	Style nit, not a bug.
Default batching=True conflicts with _use_batching docs	opik_client.py:110	Already fixed — _use_batching now defaults to False and is documented as deprecated.

[baz-reviewer]

Thanks for the detailed follow-up and rationale on each point. I appreciate the clarifications, but I can currently only save feedback to memory when it’s attached to specific code review findings, not broader PR-level or general comments like this.