diff --git a/README.md b/README.md index 0eee36c..b09d8c3 100644 --- a/README.md +++ b/README.md @@ -140,7 +140,7 @@ res = interfaze.chat.completions.create( receipt = json.loads(res.choices[0].message.content or "{}") # {"merchant": ..., "total": ..., "items": [...]} ``` -`message.content` comes back as a JSON string, so parse it - and keep the root an `object`, since a non-object root is wrapped under a `result` key. Prefer Pydantic? Use `interfaze.chat.completions.parse(response_format=YourModel, …)` and read `choices[0].message.parsed`. +`message.content` comes back as a JSON string, so parse it - and keep the root an `object`, since a non-object root is wrapped under a `result` key. Prefer Pydantic? Use `interfaze.chat.completions.parse(response_format=YourModel, …)` and read `choices[0].message.parsed`. The result is an `InterfazeParsedChatCompletion`, so `precontext` (a list of `Precontext`, e.g. `res.precontext[0].result`) and `vcache` are typed just like on `create()`. ### Tools and function calling diff --git a/src/interfaze/__init__.py b/src/interfaze/__init__.py index fc67409..bc26d55 100644 --- a/src/interfaze/__init__.py +++ b/src/interfaze/__init__.py @@ -32,6 +32,7 @@ from ._types import ( GuardCode, InterfazeChatCompletion, + InterfazeParsedChatCompletion, Precontext, ReasoningEffort, TaskName, @@ -44,6 +45,7 @@ "AsyncInterfaze", "InterfazeError", "InterfazeChatCompletion", + "InterfazeParsedChatCompletion", "InterfazeStream", "AsyncInterfazeStream", "strip_side_channels", diff --git a/src/interfaze/_chat.py b/src/interfaze/_chat.py index 0df6544..e4cd43d 100644 --- a/src/interfaze/_chat.py +++ b/src/interfaze/_chat.py @@ -10,7 +10,7 @@ from ._guard import guard_tag from ._schema import empty_task_schema from ._stream import AsyncInterfazeStream, InterfazeStream, strip_json_fence -from ._types import GuardCode, InterfazeChatCompletion, TaskName +from ._types import GuardCode, InterfazeChatCompletion, InterfazeParsedChatCompletion, TaskName def _is_non_empty_schema(rf: Any) -> bool: @@ -70,6 +70,18 @@ def to_interfaze(raw: ChatCompletion, strip_fence: bool) -> InterfazeChatComplet return result +def to_interfaze_parsed(raw: ParsedChatCompletion[Any]) -> InterfazeParsedChatCompletion[Any]: + # Not model_dump(): that would flatten `message.parsed` back into a dict. Keep the parsed + # field values as-is and promote the untyped extras (`precontext`, `vcache`, ...) to typed fields. + data: Dict[str, Any] = {name: getattr(raw, name) for name in type(raw).model_fields} + data.update(raw.model_extra or {}) + result = InterfazeParsedChatCompletion[Any].model_validate(data) + request_id = getattr(raw, "_request_id", None) + if request_id is not None: + result._request_id = request_id + return result + + class _CompletionsBase: def _kwargs( self, @@ -150,7 +162,7 @@ def stream( kw, strip = self._kwargs(messages, model, task, guard, response_format, kwargs) return InterfazeStream(self._client, kw, strip) - # Structured output via a Pydantic model, extras (``vcache``/``precontext``) are present but untyped here; use ``create`` for the typed extended completion. (same for async) + # Structured output via a Pydantic model; returns the Interfaze-extended parsed completion with typed ``precontext``/``vcache`` (same for async). def parse( self, *, @@ -159,11 +171,12 @@ def parse( model: str = INTERFAZE_MODEL, guard: Optional[List[GuardCode]] = None, **kwargs: Any, - ) -> "ParsedChatCompletion[Any]": + ) -> "InterfazeParsedChatCompletion[Any]": msgs = prepare(messages, model, None, guard, None)[0] - return self._client.chat.completions.parse( + raw = self._client.chat.completions.parse( model=model, messages=msgs, response_format=response_format, **kwargs ) + return to_interfaze_parsed(raw) @property def with_raw_response(self) -> Any: @@ -244,11 +257,12 @@ async def parse( model: str = INTERFAZE_MODEL, guard: Optional[List[GuardCode]] = None, **kwargs: Any, - ) -> "ParsedChatCompletion[Any]": + ) -> "InterfazeParsedChatCompletion[Any]": msgs = prepare(messages, model, None, guard, None)[0] - return await self._client.chat.completions.parse( + raw = await self._client.chat.completions.parse( model=model, messages=msgs, response_format=response_format, **kwargs ) + return to_interfaze_parsed(raw) @property def with_raw_response(self) -> Any: diff --git a/src/interfaze/_types.py b/src/interfaze/_types.py index 7ded1dd..5d98ebc 100644 --- a/src/interfaze/_types.py +++ b/src/interfaze/_types.py @@ -1,8 +1,8 @@ from __future__ import annotations -from typing import Any, List, Literal, Optional +from typing import Any, Generic, List, Literal, Optional, TypeVar -from openai.types.chat import ChatCompletion +from openai.types.chat import ChatCompletion, ParsedChatCompletion from pydantic import BaseModel, ConfigDict TaskName = Literal[ @@ -51,3 +51,15 @@ class InterfazeChatCompletion(ChatCompletion): reasoning: Optional[str] = None vcache: bool = False debug: Optional[Any] = None + + +ContentType = TypeVar("ContentType") + + +class InterfazeParsedChatCompletion(ParsedChatCompletion[ContentType], Generic[ContentType]): + """Result of `chat.completions.parse()`: OpenAI's parsed completion plus the Interfaze extras.""" + + precontext: Optional[List[Precontext]] = None + reasoning: Optional[str] = None + vcache: bool = False + debug: Optional[Any] = None diff --git a/tests/test_compliance.py b/tests/test_compliance.py index 78419f0..ed787ed 100644 --- a/tests/test_compliance.py +++ b/tests/test_compliance.py @@ -4,10 +4,10 @@ import httpx import respx -from conftest import BASIC, CHAT_URL, _chunk, completion, mock_json, mock_sse +from conftest import BASIC, CHAT_URL, MIXED_PRECONTEXT, _chunk, completion, mock_json, mock_sse from pydantic import BaseModel -from interfaze import AsyncInterfaze, Interfaze +from interfaze import AsyncInterfaze, Interfaze, InterfazeParsedChatCompletion, Precontext USAGE_CHUNK = { "id": "req-test", @@ -76,6 +76,107 @@ def test_parse_returns_parsed_object(): assert isinstance(parsed, _Weather) and parsed.city == "Tokyo" and parsed.temp_c == 21 +_WEATHER_JSON = '{"city": "Tokyo", "temp_c": 21}' +_MSGS = [{"role": "user", "content": "Weather in Tokyo?"}] + + +@respx.mock +def test_parse_exposes_typed_precontext_and_vcache(): + mock_json( + completion( + _WEATHER_JSON, + precontext=[{"name": "ocr", "result": {"extracted_text": "x"}}], + vcache=True, + reasoning="because", + ) + ) + res = Interfaze(api_key="t").chat.completions.parse(messages=_MSGS, response_format=_Weather) + assert isinstance(res, InterfazeParsedChatCompletion) + assert res.precontext is not None + assert isinstance(res.precontext[0], Precontext) + assert res.precontext[0].name == "ocr" + assert res.precontext[0].result == {"extracted_text": "x"} + assert res.vcache is True + assert res.reasoning == "because" + parsed = res.choices[0].message.parsed + assert isinstance(parsed, _Weather) and parsed.city == "Tokyo" + assert res.usage is not None and res.usage.total_tokens == 8 + + +@respx.mock +def test_parse_without_precontext_defaults(): + mock_json({k: v for k, v in completion(_WEATHER_JSON).items() if k != "vcache"}) + res = Interfaze(api_key="t").chat.completions.parse(messages=_MSGS, response_format=_Weather) + assert isinstance(res, InterfazeParsedChatCompletion) + assert res.precontext is None + assert res.vcache is False + parsed = res.choices[0].message.parsed + assert isinstance(parsed, _Weather) and parsed.temp_c == 21 + + +@respx.mock +def test_parse_keeps_raw_tool_call_precontext_entries(): + mock_json({**MIXED_PRECONTEXT, "choices": completion(_WEATHER_JSON)["choices"]}) + res = Interfaze(api_key="t").chat.completions.parse(messages=_MSGS, response_format=_Weather) + assert res.precontext is not None and len(res.precontext) == 2 + assert res.precontext[0].result == {"extracted_text": "x"} + assert res.precontext[1].name is None and res.precontext[1].result is None + assert res.precontext[1].model_extra == { + "toolCallId": "call_1", + "toolName": "run_code", + "input": {"code": "print(1)"}, + } + + +@respx.mock +def test_parse_carries_request_id(): + respx.post(CHAT_URL).mock( + return_value=httpx.Response( + 200, json=completion(_WEATHER_JSON), headers={"x-request-id": "req-parse1"} + ) + ) + res = Interfaze(api_key="t").chat.completions.parse(messages=_MSGS, response_format=_Weather) + assert res._request_id == "req-parse1" + + +@respx.mock +def test_async_parse_exposes_typed_precontext_and_vcache(): + mock_json( + completion( + _WEATHER_JSON, precontext=[{"name": "ocr", "result": {"extracted_text": "x"}}], vcache=True + ) + ) + + async def go(): + return await AsyncInterfaze(api_key="t").chat.completions.parse( + messages=_MSGS, response_format=_Weather + ) + + res = asyncio.run(go()) + assert isinstance(res, InterfazeParsedChatCompletion) + assert res.precontext is not None and isinstance(res.precontext[0], Precontext) + assert res.precontext[0].result == {"extracted_text": "x"} + assert res.vcache is True + parsed = res.choices[0].message.parsed + assert isinstance(parsed, _Weather) and parsed.city == "Tokyo" + + +@respx.mock +def test_async_parse_without_precontext(): + mock_json(completion(_WEATHER_JSON)) + + async def go(): + return await AsyncInterfaze(api_key="t").chat.completions.parse( + messages=_MSGS, response_format=_Weather + ) + + res = asyncio.run(go()) + assert isinstance(res, InterfazeParsedChatCompletion) + assert res.precontext is None and res.vcache is False + parsed = res.choices[0].message.parsed + assert isinstance(parsed, _Weather) and parsed.temp_c == 21 + + def test_escape_hatch_surface_present(): for comp in (Interfaze(api_key="t").chat.completions, AsyncInterfaze(api_key="t").chat.completions): assert hasattr(comp, "parse")