Coverage for src / lexigram / contracts / ai / relay / dto / common.py: 25%

1"""Shared JSON helpers for the relay wire DTO families. 

2 

3The four protocol DTO families (OpenAI Chat, OpenAI Responses, Claude, 

4and Gemini) all carry raw wire fields as JSON-ish dictionaries and 

5preserve unknown upstream fields verbatim in ``passthrough``. This 

6module owns those shared aliases and helpers so each family keeps the 

7same present/wire semantics without redefining them. 

8""" 

9 

10from __future__ import annotations 

11 

12from typing import Any, TypeAlias 

13 

14from lexigram.contracts.ai.exceptions import RelayError, RelayErrorCode 

15 

16__all__ = [ 

17 "JsonDict", 

18 "JsonValue", 

19 "require_field", 

20] 

21 

22 

23JsonValue: TypeAlias = dict[str, Any] | list[Any] | str | int | float | bool | None 

24"""A JSON-compatible value accepted by the wire DTOs.""" 

25 

26JsonDict: TypeAlias = dict[str, JsonValue] 

27"""A JSON-compatible object (wire request/response fragment).""" 

28 

29 

30def require_field(data: dict[str, Any], name: str) -> Any: 

31 """Return a required wire field or raise a typed malformed-payload error. 

32 

33 Args: 

34 data: Raw wire dict being parsed. 

35 name: Name of the required field. 

36 

37 Returns: 

38 The field value. 

39 

40 Raises: 

41 RelayError: With code ``malformed_payload`` when the field is 

42 absent or ``None``. 

43 """ 

44 if name not in data or data[name] is None: 

45 raise RelayError( 

46 f"malformed payload: missing required field '{name}'", 

47 code=RelayErrorCode.MALFORMED_PAYLOAD, 

48 ) 

49 return data[name]