Coverage for src / lexigram / contracts / ai / thinking.py: 0%

1"""Thinking/reasoning value types shared across AI packages. 

2 

3These types are provider-agnostic. Every LLM client that supports extended 

4thinking or chain-of-thought reasoning normalises its output into 

5:class:`ThinkingResult` and accepts configuration via :class:`ThinkingConfig`. 

6""" 

7 

8from __future__ import annotations 

9 

10from dataclasses import dataclass 

11 

12__all__ = [ 

13 "ThinkingConfig", 

14 "ThinkingResult", 

15] 

16 

17 

18@dataclass(frozen=True) 

19class ThinkingConfig: 

20 """Provider-agnostic thinking/reasoning configuration. 

21 

22 Pass as ``LLMConfig.thinking`` to enable extended thinking on any 

23 supporting provider. ``None`` means thinking is disabled. 

24 

25 Attributes: 

26 suppress: When True, actively suppresses thinking tokens by injecting 

27 ``enable_thinking: false`` (and ``chat_template_kwargs.enable_thinking: false``) 

28 into the request payload. Use this for models that generate thinking 

29 by default (Qwen3, Gemma-4 via LM Studio / vLLM / SGLang) when you 

30 do not want the latency cost. Mutually exclusive with ``effort``, 

31 ``budget_tokens``, and ``level`` — if ``suppress`` is True the other 

32 fields are ignored. 

33 budget_tokens: Maximum tokens the model may spend on internal 

34 reasoning. Applies to Anthropic (``budget_tokens``), Gemini 2.5 

35 (``thinkingBudget``), and AWS Bedrock Claude (``budget_tokens``). 

36 Ignored when ``level`` is set (Gemini 3 uses ``level`` instead). 

37 level: Gemini 3 thinking level. One of ``"minimal"``, ``"low"``, 

38 ``"medium"``, ``"high"``. When set, takes precedence over 

39 ``budget_tokens`` for Gemini 3 models. 

40 effort: OpenAI o-series reasoning effort. One of ``"low"``, 

41 ``"medium"``, ``"high"``. Mutually exclusive with ``budget_tokens`` 

42 and ``level`` (different API surface). 

43 """ 

44 

45 suppress: bool = False 

46 budget_tokens: int = 10_000 

47 level: str | None = None 

48 effort: str | None = None 

49 

50 

51@dataclass(frozen=True) 

52class ThinkingResult: 

53 """Normalised thinking/reasoning output — consistent shape regardless of provider. 

54 

55 Attributes: 

56 content: The full thinking/reasoning text produced by the model. 

57 signature: Anthropic-specific encrypted signature required to 

58 re-inject thinking blocks into subsequent assistant turns during 

59 multi-turn tool-use conversations. ``None`` for all other 

60 providers. 

61 tokens: Number of tokens consumed by internal reasoning. Populated 

62 from Gemini ``thoughtsTokenCount`` and OpenAI 

63 ``completion_tokens_details.reasoning_tokens``. ``None`` when 

64 the provider does not report this value. 

65 """ 

66 

67 content: str 

68 signature: str | None = None 

69 tokens: int | None = None