providers.deepseek.client Namespace Reference

Classes
class	DeepSeekClient

Functions
bool	_is_retryable (Exception exc)
dict	_deep_usage_dict (usage)
	_ensure_plain (value)

Variables
tuple	_RETRY_DELAYS = (1, 2, 4)
dict	_RETRYABLE_STATUS = {429, 500, 502, 503, 524}

Detailed Description

DeepSeek API client with streaming chat and automatic retry logic.

Purpose
-------
Provides :class:`DeepSeekClient` which wraps the OpenAI-compatible
SDK, handles streaming of reasoning content, text, tool calls, and
token usage, and retries transient errors with exponential backoff.

Moved from ``oc_chat/core/client.py`` in Phase C.2b. The old path
remains as a compat re-export shim until C.3f.

Responsibilities
----------------
- :class:`DeepSeekClient` — concrete :class:`BaseClient` for DeepSeek;
  exposes ``stream_chat``, ``one_shot``, ``list_models``.
- :func:`_is_retryable` — decide whether an SDK exception is worth
  retrying (auth errors no, transient HTTP yes).
- :func:`_deep_usage_dict` — defensively normalise pydantic
  ``CompletionUsage`` objects into plain nested dicts so consumers
  can rely on ``isinstance(field, dict)``.
- Streaming chunk shaping: yield ``("reasoning", str)``,
  ``("content", str)``, ``("tool_call", dict)``, ``("usage", dict)``
  in API arrival order, then a terminal ``("finish_reason", str)``.

Diagnostics
-----------
Domain: OC_CHAT.CLIENT
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Up to 3 attempts on transient errors with delays of 1/2/4 seconds.
- Authentication failures fail fast — never retried.
- ``stream_chat`` is a generator; iteration completes when the SDK's
  stream ends.
- Usage objects are always converted to plain dicts before being
  yielded (no pydantic models leak past this client).

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- openai (API client for chat completions and streaming)
- option_c_agent_contracts (lazy; SupportsCancellation type of the stream_chat cancellation token)
- httpx (lazy; HTTP client with trust_env off, handed to the OpenAI SDK)

See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §5 Streaming chunk tuples — concrete impl
of the stream_chat tuple contract.

Function Documentation

_deep_usage_dict()

dict providers.deepseek.client._deep_usage_dict ( usage )

protected

Convert a pydantic ``CompletionUsage`` (or any object) to a
plain nested dict, recursively ensuring pydantic model fields
(``prompt_tokens_details``, ``completion_tokens_details``, etc.)
become plain dicts rather than remaining as pydantic model objects.

This prevents silent ``isinstance(field, dict)`` failures in consumers.

Definition at line 85 of file client.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_ensure_plain()

providers.deepseek.client._ensure_plain ( value )

protected

Recursively convert pydantic / non-primitive objects to plain dicts/lists.

Definition at line 104 of file client.py.

Here is the call graph for this function:

Here is the caller graph for this function:

_is_retryable()

bool providers.deepseek.client._is_retryable ( Exception exc )

protected

Return True if *exc* is a transient error worth retrying.

Definition at line 76 of file client.py.

Here is the caller graph for this function:

Variable Documentation

_RETRY_DELAYS

tuple providers.deepseek.client._RETRY_DELAYS = (1, 2, 4)

protected

Definition at line 72 of file client.py.

_RETRYABLE_STATUS

dict providers.deepseek.client._RETRYABLE_STATUS = {429, 500, 502, 503, 524}

protected

Definition at line 73 of file client.py.