aliasgate 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,359 @@
1
+ """OpenAI Chat Completions, `POST /v1/chat/completions`, non-streaming (architecture §6).
2
+
3
+ Request shapes checked on 2026-11-17 against the types of openai-python 3.52.0.
4
+
5
+ Slot order, which placeholder numbering follows:
6
+
7
+ 1. each message in order: `content` (a string, or its `text` and `refusal` parts in order),
8
+ then the assistant's `refusal`, then each of its `tool_calls`, then the legacy
9
+ `function_call`;
10
+ 2. `prediction.content`;
11
+ 3. if the policy says so, every `description` string inside `tools`, then inside the legacy
12
+ `functions`.
13
+
14
+ Where the dialect expects a shape and finds another, it raises MalformedRequestError naming the
15
+ position (for example `messages[2].content`), never the content. It validates nothing else;
16
+ the provider does that.
17
+ """
18
+
19
+ import json
20
+ from collections.abc import Callable
21
+ from functools import partial
22
+ from typing import Any, Final
23
+
24
+ from aliasgate.dialects.base import (
25
+ MalformedRequestError,
26
+ Policy,
27
+ PreparedRequest,
28
+ Slot,
29
+ StreamTransformer,
30
+ UnsupportedContentError,
31
+ key_slot,
32
+ restore_all_strings,
33
+ slots_for_json_strings,
34
+ slots_for_key_strings,
35
+ )
36
+ from aliasgate.dialects.sse import SSEEvent
37
+ from aliasgate.engine import restore
38
+ from aliasgate.mapping import Mapping
39
+ from aliasgate.stream import StreamRestorer
40
+
41
+ _USER_IDENTIFIERS: Final = ("user", "safety_identifier")
42
+ _TEXT_PARTS: Final = frozenset({"text", "refusal"}) # the part type is also the text's key
43
+ _TOOL_DEFINITIONS: Final = ("tools", "functions")
44
+
45
+
46
+ def _object(value: object, where: str) -> dict[str, Any]:
47
+ if not isinstance(value, dict):
48
+ raise MalformedRequestError(f"{where}: expected an object")
49
+ return value
50
+
51
+
52
+ def _write_json(obj: dict[str, Any], key: str, value: dict[str, Any] | list[Any]) -> None:
53
+ obj[key] = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
54
+
55
+
56
+ class _Collector:
57
+ """Accumulates the slots and finalizers of one request while walking it."""
58
+
59
+ __slots__ = ("finalizers", "policy", "slots")
60
+
61
+ def __init__(self, policy: Policy) -> None:
62
+ self.policy = policy
63
+ self.slots: list[Slot] = []
64
+ self.finalizers: list[Callable[[], None]] = []
65
+
66
+ def message(self, value: object, where: str) -> None:
67
+ message = _object(value, where)
68
+ self.content(message, where)
69
+ self.optional_string(message, "refusal", where)
70
+ self.tool_calls(message.get("tool_calls"), f"{where}.tool_calls")
71
+ function_call = message.get("function_call")
72
+ if function_call is not None:
73
+ where = f"{where}.function_call"
74
+ self.arguments(_object(function_call, where), where)
75
+
76
+ def content(self, holder: dict[str, Any], where: str) -> None:
77
+ value = holder.get("content")
78
+ where = f"{where}.content"
79
+ if value is None:
80
+ return
81
+ if isinstance(value, str):
82
+ self.slots.append(key_slot(holder, "content"))
83
+ return
84
+ if not isinstance(value, list):
85
+ raise MalformedRequestError(f"{where}: expected a string, a list or null")
86
+ for index, part in enumerate(value):
87
+ self.part(part, f"{where}[{index}]")
88
+
89
+ def part(self, value: object, where: str) -> None:
90
+ part = _object(value, where)
91
+ kind = part.get("type")
92
+ if not isinstance(kind, str):
93
+ raise MalformedRequestError(f"{where}.type: expected a string")
94
+ if kind in _TEXT_PARTS:
95
+ self.required_string(part, kind, where)
96
+ else:
97
+ self.unsupported(kind)
98
+
99
+ def tool_calls(self, value: object, where: str) -> None:
100
+ if value is None:
101
+ return
102
+ if not isinstance(value, list):
103
+ raise MalformedRequestError(f"{where}: expected a list or null")
104
+ for index, item in enumerate(value):
105
+ at = f"{where}[{index}]"
106
+ call = _object(item, at)
107
+ kind = call.get("type")
108
+ if kind == "function":
109
+ self.arguments(_object(call.get("function"), f"{at}.function"), f"{at}.function")
110
+ elif kind == "custom":
111
+ custom = _object(call.get("custom"), f"{at}.custom")
112
+ self.required_string(custom, "input", f"{at}.custom")
113
+ elif isinstance(kind, str):
114
+ self.unsupported(kind)
115
+ else:
116
+ raise MalformedRequestError(f"{at}.type: expected a string")
117
+
118
+ def arguments(self, function: dict[str, Any], where: str) -> None:
119
+ """JSON object or array arguments: a slot per string value, re-serialised afterwards.
120
+ Anything else (a bare JSON scalar, invalid JSON): one slot on the raw string."""
121
+ raw = function.get("arguments")
122
+ if not isinstance(raw, str):
123
+ raise MalformedRequestError(f"{where}.arguments: expected a string")
124
+ try:
125
+ parsed = json.loads(raw)
126
+ except (ValueError, RecursionError):
127
+ parsed = None
128
+ if isinstance(parsed, dict | list):
129
+ self.slots.extend(slots_for_json_strings(parsed))
130
+ self.finalizers.append(partial(_write_json, function, "arguments", parsed))
131
+ else:
132
+ self.slots.append(key_slot(function, "arguments"))
133
+
134
+ def required_string(self, holder: dict[str, Any], key: str, where: str) -> None:
135
+ if not isinstance(holder.get(key), str):
136
+ raise MalformedRequestError(f"{where}.{key}: expected a string")
137
+ self.slots.append(key_slot(holder, key))
138
+
139
+ def optional_string(self, holder: dict[str, Any], key: str, where: str) -> None:
140
+ if holder.get(key) is not None:
141
+ self.required_string(holder, key, where)
142
+
143
+ def unsupported(self, kind: str) -> None:
144
+ if self.policy.unsupported_content == "block":
145
+ raise UnsupportedContentError(kind)
146
+
147
+ def tool_definitions(self, body: dict[str, Any]) -> None:
148
+ for key in _TOOL_DEFINITIONS:
149
+ definitions = body.get(key)
150
+ if definitions is None:
151
+ continue
152
+ if not isinstance(definitions, list):
153
+ raise MalformedRequestError(f"{key}: expected a list")
154
+ self.slots.extend(slots_for_key_strings(definitions, "description"))
155
+
156
+
157
+ def _restore_key(obj: object, key: str, mapping: Mapping, *, json_escape: bool = False) -> None:
158
+ if isinstance(obj, dict) and isinstance(value := obj.get(key), str):
159
+ obj[key] = restore(value, mapping, json_escape=json_escape)
160
+
161
+
162
+ def _restore_message(message: dict[str, Any], mapping: Mapping) -> None:
163
+ _restore_key(message, "content", mapping)
164
+ _restore_key(message, "refusal", mapping)
165
+ tool_calls = message.get("tool_calls")
166
+ if isinstance(tool_calls, list):
167
+ for call in tool_calls:
168
+ if isinstance(call, dict):
169
+ _restore_key(call.get("function"), "arguments", mapping, json_escape=True)
170
+ _restore_key(call.get("custom"), "input", mapping)
171
+ _restore_key(message.get("function_call"), "arguments", mapping, json_escape=True)
172
+ _restore_key(message.get("audio"), "transcript", mapping)
173
+
174
+
175
+ class OpenAIChatDialect:
176
+ """OpenAI Chat Completions payloads: slots in a fixed order, restoration of responses."""
177
+
178
+ name = "openai_chat"
179
+
180
+ def prepare_request(self, body: dict[str, Any], policy: Policy) -> PreparedRequest:
181
+ """Collect the slots of `body` in the documented order and strip end-user identifiers.
182
+
183
+ Raises UnsupportedContentError for uninspectable content under policy `block`, and
184
+ MalformedRequestError when a walked field has the wrong shape. Changes `body` only
185
+ through the returned slots and finalizers, and by removing identifiers.
186
+ """
187
+ if not isinstance(body, dict):
188
+ raise MalformedRequestError("body: expected an object")
189
+ messages = body.get("messages")
190
+ if not isinstance(messages, list):
191
+ raise MalformedRequestError("messages: expected a list")
192
+ collector = _Collector(policy)
193
+ for index, message in enumerate(messages):
194
+ collector.message(message, f"messages[{index}]")
195
+ prediction = body.get("prediction")
196
+ if prediction is not None:
197
+ collector.content(_object(prediction, "prediction"), "prediction")
198
+ if policy.tool_definitions:
199
+ collector.tool_definitions(body)
200
+ if policy.strip_user_identifiers:
201
+ for key in _USER_IDENTIFIERS:
202
+ body.pop(key, None)
203
+ return PreparedRequest(collector.slots, collector.finalizers)
204
+
205
+ def restore_response(self, body: dict[str, Any], mapping: Mapping) -> None:
206
+ """Restore, in place, the model text of every choice: content, refusal, tool-call
207
+ arguments and inputs, legacy function-call arguments and the audio transcript.
208
+
209
+ Everything else (annotations, logprobs, usage, ids) is left untouched, and so is a body
210
+ without `choices`; use `restore_all_strings` for error bodies.
211
+ """
212
+ choices = body.get("choices")
213
+ if not isinstance(choices, list):
214
+ return
215
+ for choice in choices:
216
+ if isinstance(choice, dict) and isinstance(message := choice.get("message"), dict):
217
+ _restore_message(message, mapping)
218
+
219
+ def stream_transformer(self, mapping: Mapping) -> StreamTransformer:
220
+ """A transformer that restores one streamed completion with `mapping`."""
221
+ return OpenAIChatStreamTransformer(mapping)
222
+
223
+ def error_body(self, status: int, code: str, message: str) -> dict[str, Any]:
224
+ """A gateway error in the OpenAI error shape."""
225
+ return {
226
+ "error": {"message": message, "type": "aliasgate_error", "param": None, "code": code}
227
+ }
228
+
229
+
230
+ # A restorer per (choice index, channel). The channel names the delta field the text belongs
231
+ # to: "content", "refusal", "function_call", "audio", or ("tool" | "custom", tool call index).
232
+ type _Channel = str | tuple[str, int]
233
+ _ENVELOPE: Final = ("id", "object", "created", "model", "system_fingerprint")
234
+ _JSON_CHANNELS: Final = frozenset({"function_call"})
235
+
236
+
237
+ def _dumps(value: object) -> str:
238
+ return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
239
+
240
+
241
+ def _channel_delta(channel: _Channel, text: str) -> dict[str, Any]:
242
+ """A delta that carries `text` in the field `channel` stands for."""
243
+ if isinstance(channel, tuple):
244
+ kind, tool = channel
245
+ call = {"function": {"arguments": text}} if kind == "tool" else {"custom": {"input": text}}
246
+ return {"tool_calls": [{"index": tool, **call}]}
247
+ if channel == "function_call":
248
+ return {"function_call": {"arguments": text}}
249
+ if channel == "audio":
250
+ return {"audio": {"transcript": text}}
251
+ return {channel: text}
252
+
253
+
254
+ class OpenAIChatStreamTransformer:
255
+ """Restores the placeholders of one streamed chat completion, chunk by chunk.
256
+
257
+ Each text field of each choice has its own `StreamRestorer`, so placeholders split across
258
+ chunks are restored and choices or tool calls never mix. Text still held when a choice
259
+ finishes, at `[DONE]` or at `end()` is sent in a synthetic chunk before it; nothing held
260
+ is emitted any other way.
261
+ """
262
+
263
+ def __init__(self, mapping: Mapping) -> None:
264
+ self._mapping = mapping
265
+ self._restorers: dict[tuple[int, _Channel], StreamRestorer] = {}
266
+ self._envelope: dict[str, Any] = {}
267
+ self._event_name: str | None = None
268
+ self.unresolved = 0
269
+
270
+ def feed(self, event: SSEEvent) -> list[SSEEvent]:
271
+ """The events to send in place of `event`: synthetic flushes first, then the chunk."""
272
+ self._event_name = event.event
273
+ if event.data == "[DONE]":
274
+ return [*self._flush(None), event]
275
+ try:
276
+ chunk = json.loads(event.data)
277
+ except (ValueError, RecursionError):
278
+ return [event]
279
+ if not isinstance(chunk, dict):
280
+ return [event]
281
+ choices = chunk.get("choices")
282
+ if not isinstance(choices, list):
283
+ if "error" not in chunk:
284
+ return [event]
285
+ # A provider error sent in the stream; it may echo placeholders back.
286
+ return [SSEEvent(event.event, _dumps(restore_all_strings(chunk, self._mapping)))]
287
+ self._envelope = {key: chunk[key] for key in _ENVELOPE if key in chunk}
288
+ changed = False
289
+ flushed: list[SSEEvent] = []
290
+ for choice in choices:
291
+ if not isinstance(choice, dict) or not isinstance(index := choice.get("index"), int):
292
+ continue
293
+ delta = choice.get("delta")
294
+ if isinstance(delta, dict):
295
+ changed |= self._restore_delta(index, delta)
296
+ if choice.get("finish_reason") is not None:
297
+ flushed += self._flush(index)
298
+ self._count()
299
+ if not changed and not flushed:
300
+ return [event]
301
+ return [*flushed, SSEEvent(event.event, _dumps(chunk), event.raw_fields)]
302
+
303
+ def end(self) -> list[SSEEvent]:
304
+ """Synthetic chunks for any text still held; called when the stream ends without [DONE]."""
305
+ return self._flush(None)
306
+
307
+ def _restore_delta(self, index: int, delta: dict[str, Any]) -> bool:
308
+ changed = self._feed(delta, "content", (index, "content"))
309
+ changed |= self._feed(delta, "refusal", (index, "refusal"))
310
+ tool_calls = delta.get("tool_calls")
311
+ if isinstance(tool_calls, list):
312
+ for call in tool_calls:
313
+ if not isinstance(call, dict) or not isinstance(tool := call.get("index"), int):
314
+ continue
315
+ if isinstance(function := call.get("function"), dict):
316
+ changed |= self._feed(function, "arguments", (index, ("tool", tool)))
317
+ if isinstance(custom := call.get("custom"), dict):
318
+ changed |= self._feed(custom, "input", (index, ("custom", tool)))
319
+ if isinstance(function_call := delta.get("function_call"), dict):
320
+ changed |= self._feed(function_call, "arguments", (index, "function_call"))
321
+ if isinstance(audio := delta.get("audio"), dict):
322
+ changed |= self._feed(audio, "transcript", (index, "audio"))
323
+ return changed
324
+
325
+ def _feed(self, holder: dict[str, Any], key: str, where: tuple[int, _Channel]) -> bool:
326
+ value = holder.get(key)
327
+ if not isinstance(value, str):
328
+ return False
329
+ restorer = self._restorers.get(where)
330
+ if restorer is None:
331
+ channel = where[1]
332
+ json_escape = channel in _JSON_CHANNELS or (
333
+ isinstance(channel, tuple) and channel[0] == "tool"
334
+ )
335
+ restorer = StreamRestorer(self._mapping, json_escape=json_escape)
336
+ self._restorers[where] = restorer
337
+ restored = restorer.feed(value)
338
+ holder[key] = restored
339
+ return restored != value
340
+
341
+ def _flush(self, index: int | None) -> list[SSEEvent]:
342
+ """Synthetic chunks with the held text of one choice, or of every choice for None."""
343
+ events = []
344
+ for (choice, channel), restorer in self._restorers.items():
345
+ if index is not None and choice != index:
346
+ continue
347
+ text = restorer.flush()
348
+ if text:
349
+ delta = _channel_delta(channel, text)
350
+ chunk = {
351
+ **self._envelope,
352
+ "choices": [{"index": choice, "delta": delta, "finish_reason": None}],
353
+ }
354
+ events.append(SSEEvent(self._event_name, _dumps(chunk)))
355
+ self._count()
356
+ return events
357
+
358
+ def _count(self) -> None:
359
+ self.unresolved = sum(restorer.unresolved for restorer in self._restorers.values())
@@ -0,0 +1,108 @@
1
+ """Server-sent events: parse a byte stream into events and encode events back.
2
+
3
+ Follows the event-stream format of the HTML Living Standard (section 9.2.5): `\\n`, `\\r\\n` and
4
+ `\\r` end lines, an empty line ends an event, lines starting with `:` are comments.
5
+ """
6
+
7
+ import codecs
8
+ import re
9
+ from dataclasses import dataclass
10
+ from typing import Final
11
+
12
+ _LINE_END: Final = re.compile(r"\r\n|\r|\n")
13
+ _BOM: Final = "\ufeff"
14
+
15
+
16
+ @dataclass(frozen=True, slots=True)
17
+ class SSEEvent:
18
+ """One event: its `event` field, its `data` lines joined with "\\n", and any other fields
19
+ (id, retry, ...) in order."""
20
+
21
+ event: str | None
22
+ data: str
23
+ raw_fields: tuple[tuple[str, str], ...] = ()
24
+
25
+ def encode(self) -> bytes:
26
+ """The event in wire format: event, other fields, one `data:` line per line of data."""
27
+ lines = [] if self.event is None else [f"event: {self.event}"]
28
+ lines += [f"{name}: {value}" for name, value in self.raw_fields]
29
+ lines += [f"data: {line}" for line in self.data.split("\n")]
30
+ return ("\n".join(lines) + "\n\n").encode("utf-8")
31
+
32
+
33
+ class SSEParser:
34
+ """Incremental parser: bytes in any chunking, events out as soon as they are complete.
35
+
36
+ UTF-8 is decoded strictly and incrementally, so a character split across chunks is fine and
37
+ invalid UTF-8 raises UnicodeDecodeError. Events with neither data nor an event name are not
38
+ emitted. One instance per stream.
39
+ """
40
+
41
+ __slots__ = ("_after_cr", "_data", "_decoder", "_event", "_fields", "_pending", "_started")
42
+
43
+ def __init__(self) -> None:
44
+ self._decoder = codecs.getincrementaldecoder("utf-8")(errors="strict")
45
+ self._pending = "" # the current, incomplete line
46
+ self._after_cr = False # the last line ended with "\r": a leading "\n" belongs to it
47
+ self._started = False
48
+ self._event: str | None = None
49
+ self._data: list[str] | None = None
50
+ self._fields: list[tuple[str, str]] = []
51
+
52
+ def feed(self, chunk: bytes) -> list[SSEEvent]:
53
+ """Parse `chunk`; return the events it completes."""
54
+ return self._text(self._decoder.decode(chunk))
55
+
56
+ def end(self) -> list[SSEEvent]:
57
+ """Return a final event if the stream ended without a blank line; else []."""
58
+ events = self._text(self._decoder.decode(b"", final=True))
59
+ if self._pending:
60
+ line, self._pending = self._pending, ""
61
+ self._line(line)
62
+ event = self._dispatch()
63
+ return events if event is None else [*events, event]
64
+
65
+ def _text(self, text: str) -> list[SSEEvent]:
66
+ if not self._started and text:
67
+ self._started = True
68
+ text = text.removeprefix(_BOM)
69
+ if self._after_cr and text:
70
+ self._after_cr = False
71
+ text = text.removeprefix("\n")
72
+ buffer = self._pending + text
73
+ events: list[SSEEvent] = []
74
+ start = 0
75
+ for match in _LINE_END.finditer(buffer):
76
+ if match.group() == "\r" and match.end() == len(buffer):
77
+ self._after_cr = True
78
+ event = self._line(buffer[start : match.start()])
79
+ if event is not None:
80
+ events.append(event)
81
+ start = match.end()
82
+ self._pending = buffer[start:]
83
+ return events
84
+
85
+ def _line(self, line: str) -> SSEEvent | None:
86
+ if not line:
87
+ return self._dispatch()
88
+ if line.startswith(":"):
89
+ return None
90
+ name, colon, value = line.partition(":")
91
+ if colon:
92
+ value = value.removeprefix(" ")
93
+ if name == "data":
94
+ if self._data is None:
95
+ self._data = []
96
+ self._data.append(value)
97
+ elif name == "event":
98
+ self._event = value
99
+ else:
100
+ self._fields.append((name, value))
101
+ return None
102
+
103
+ def _dispatch(self) -> SSEEvent | None:
104
+ event = None
105
+ if self._data is not None or self._event is not None:
106
+ event = SSEEvent(self._event, "\n".join(self._data or []), tuple(self._fields))
107
+ self._event, self._data, self._fields = None, None, []
108
+ return event