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

1"""Wire transport contracts for the relay gateway. 

2 

3Defines the upstream request/response/chunk value types and the upstream 

4client protocol used by the relay gateway to talk to model providers. 

5""" 

6 

7from __future__ import annotations 

8 

9from collections.abc import AsyncIterator, Mapping 

10from dataclasses import dataclass 

11from typing import Protocol, runtime_checkable 

12 

13from lexigram.contracts.ai.relay.types import JsonValue 

14 

15 

16@dataclass(frozen=True, slots=True) 

17class UpstreamRequest: 

18 """A fully-resolved request to an upstream model provider. 

19 

20 Attributes: 

21 request_id: Identifier of the originating gateway request. 

22 method: HTTP method used for the upstream call. 

23 url: Fully-resolved upstream endpoint URL. 

24 headers: Headers to send with the upstream call. 

25 payload: JSON payload to send with the upstream call. 

26 timeout_seconds: Timeout budget for the upstream call. 

27 channel_name: Name of the relay channel that selected this call. Empty 

28 when the caller does not use channel identity. 

29 """ 

30 

31 request_id: str 

32 method: str 

33 url: str 

34 headers: Mapping[str, str] 

35 payload: Mapping[str, JsonValue] 

36 timeout_seconds: float 

37 channel_name: str = "" 

38 

39 

40@dataclass(frozen=True, slots=True) 

41class UpstreamResponse: 

42 """A non-streaming response from an upstream model provider.""" 

43 

44 status_code: int 

45 headers: Mapping[str, str] 

46 payload: Mapping[str, JsonValue] | None 

47 

48 

49@dataclass(frozen=True, slots=True) 

50class UpstreamChunk: 

51 """A single streaming chunk from an upstream model provider.""" 

52 

53 event: str | None 

54 data: str 

55 terminal: bool = False 

56 

57 

58@dataclass(frozen=True, slots=True) 

59class RelayWireEvent: 

60 """A normalized streaming event emitted by the relay gateway.""" 

61 

62 event: str | None 

63 data: Mapping[str, JsonValue] | None 

64 terminal: bool = False 

65 

66 

67@runtime_checkable 

68class RelayUpstreamProtocol(Protocol): 

69 """Client protocol for invoking upstream model providers.""" 

70 

71 async def request(self, request: UpstreamRequest) -> UpstreamResponse: ... 

72 async def stream( 

73 self, request: UpstreamRequest 

74 ) -> AsyncIterator[UpstreamChunk]: ... 

75 async def cancel(self, request_id: str) -> None: ...