Skip to content

fix: return typed precontext / vcache from chat.completions.parse() (sync + async) - #24

Draft
wokhouse wants to merge 1 commit into
mainfrom
fix/parse-typed-precontext
Draft

wokhouse wants to merge 1 commit into
mainfrom
fix/parse-typed-precontext

Conversation

@wokhouse

Copy link
Copy Markdown
Collaborator

Problem

interfaze.chat.completions.parse(...) returns a plain OpenAI ParsedChatCompletion, so the Interfaze extras come back untyped: response.precontext is a list of plain dicts, and the documented pattern
response.precontext[0].result raises AttributeError: 'dict' object has no attribute 'result' whenever precontext is present (e.g. any image/OCR request). create() is fine because it goes through to_interfaze() -> InterfazeChatCompletion.
The pattern is used in 26 docs snippets on interfaze.ai and 4 agent skills, so all of them fail on .parse( today.

Root cause

Completions.parse / AsyncCompletions.parse in src/interfaze/_chat.py just return self._client.chat.completions.parse(...). The extras are only present as untyped pydantic model_extra. The old comment above parse() documented this as intended.

Fix

  • New InterfazeParsedChatCompletion(ParsedChatCompletion[ContentType]) in _types.py with the same extras as InterfazeChatCompletion (precontext: Optional[List[Precontext]], reasoning, vcache, debug). Exported from interfaze.
  • New to_interfaze_parsed() in _chat.py (counterpart of to_interfaze). It does not use model_dump() (that would flatten message.parsed back into a dict); it re-validates from the existing field values plus model_extra, so choices[0].message.parsed is the same model instance as before. _request_id is carried over, like to_interfaze.
  • Sync and async parse() return it; comment above parse() updated; one README sentence added. No CHANGELOG exists in the repo.
  • Public signature change is only the return annotation (ParsedChatCompletion[Any] -> InterfazeParsedChatCompletion[Any], a subclass), so it is backwards compatible.

Verification

Unit tests (tests/test_compliance.py, respx mocks): sync + async parse with precontext present (typed Precontext, .result, vcache, reasoning, .parsed is the pydantic model), absent (defaults None/False, .parsed works), mixed raw tool-call precontext entries, _request_id carry-over.

$ .venv/bin/python -m pytest -q
...
src/interfaze/_chat.py          111      0     22      0   100%
src/interfaze/_types.py          22      0      0      0   100%
TOTAL                           600     22    174     10    95%
Required test coverage of 90% reached. Total coverage: 95.0%
146 passed in 0.79s        (baseline on main: 140 passed, 94.97%)

$ .venv/bin/mypy
Success: no issues found in 11 source files

$ .venv/bin/ruff format --check src tests
23 files already formatted

ruff check (ruff 0.17.5, no select in pyproject so default rules): main already has 192 findings (mostly UP006/UP035/UP045 from the repo's Optional/List/Dict style); this branch has 197, the +5 are the same classes in the new code, written to match existing style. Nothing in E/F/B/I is new.

Live check against api.interfaze.ai (branch installed editable in own venv, x-interfaze-bypass-cache: true), ID image + pydantic IDCard:

sync type: InterfazeParsedChatCompletion[Any] | vcache: False
sync precontext[0].name: ocr | .result: {'extracted_text': 'California USA DRIVER LICENSE\n[x] DL Y4067081 CLASS C ...
sync parsed: full_name='IVÁN ICHET MUÑOZ ESTRADA' date_of_birth='09/12/1987' id_number='Y4067081'
async type: InterfazeParsedChatCompletion[Any] | vcache: False
async precontext[0].name: ocr | .result: {'extracted_text': 'California USA DRIVER LICENSE ...
async parsed: full_name='IVÁN ICHET MUÑOZ ESTRADA' date_of_birth='09/12/1987' id_number='Y4067081'
LIVE CHECK OK

Risks & follow-ups

  • Return type is now a subclass of OpenAI's ParsedChatCompletion; isinstance checks and attribute access keep working. Code that relied on precontext items being dicts (pc[0]["result"]) will break — Precontext is a pydantic model; use .result / .model_dump(). This is the documented/intended access pattern.
  • Conversion copies the top-level object (choices/messages are shared by reference, not re-validated), negligible cost.
  • with_raw_response.parse(...) is still the untyped OpenAI path (out of scope).
  • No version bump / changelog included; left for the maintainers' release flow.

parse() returned a plain OpenAI ParsedChatCompletion, so Interfaze extras
(precontext, vcache, reasoning, debug) came back untyped and
response.precontext[0].result raised AttributeError. Add
InterfazeParsedChatCompletion and convert the parse() result (sync + async),
keeping message.parsed intact.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants