Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions src/interfaze/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@
from ._types import (
GuardCode,
InterfazeChatCompletion,
InterfazeParsedChatCompletion,
Precontext,
ReasoningEffort,
TaskName,
Expand All @@ -44,6 +45,7 @@
"AsyncInterfaze",
"InterfazeError",
"InterfazeChatCompletion",
"InterfazeParsedChatCompletion",
"InterfazeStream",
"AsyncInterfazeStream",
"strip_side_channels",
Expand Down
26 changes: 20 additions & 6 deletions src/interfaze/_chat.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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,
*,
Expand All @@ -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:
Expand Down Expand Up @@ -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:
Expand Down
16 changes: 14 additions & 2 deletions src/interfaze/_types.py
Original file line number Diff line number Diff line change
@@ -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[
Expand Down Expand Up @@ -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
105 changes: 103 additions & 2 deletions tests/test_compliance.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down Expand Up @@ -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")
Expand Down
Loading