11"""Native OpenAI Responses API transport for Responses-only models.
22
3- Some gateways serve certain models exclusively on the ``/v1/responses``
4- endpoint and answer ``/v1/chat/completions`` with ``503 Endpoint is
5- unavailable``. OpenKB talks to LLMs through LiteLLM Chat Completions, so
6- those models are unreachable — unless the KB opts in here by prefixing
7- the model id::
3+ Some gateways serve certain models exclusively on ``/v1/responses`` and
4+ answer ``/v1/chat/completions`` with ``503 Endpoint is unavailable``.
5+ Prefix the model id to opt in::
86
97 model: openai-responses/muse-spark-1.3-contributor
108
11- The prefix is an OpenKB-only convention (LiteLLM never sees it). It is
12- recognized at the two places a model string is consumed:
13-
14- - :func:`openkb.agent.compiler._llm_call` / ``_llm_call_async`` — routed
15- to :func:`litellm.responses` / :func:`litellm.aresponses`, with the
16- result adapted back to the Chat Completions shape the compiler reads.
17- - :func:`openkb.agent.query.build_run_config_from_bundle` — builds an
18- agents-SDK ``OpenAIResponsesModel`` over a custom ``AsyncOpenAI``
19- client (per-KB ``api_key`` / ``base_url`` / ``extra_headers``), so
20- query/chat/lint/skills — including ``run_streamed`` — work unchanged.
21-
22- Only ``openai-responses/`` (OpenAI-compatible bases) is supported.
23- Long-PDF PageIndex indexing still requires a Chat Completions model
24- (see :mod:`openkb.indexer` guard); short documents, query, chat, lint,
25- skills, and decks all work.
9+ The prefix is OpenKB-only (stripped before anything reaches LiteLLM).
10+ Responses are adapted back to the Chat Completions shape, so existing
11+ call sites — compile, query/chat/lint/skills agents, usage reporting —
12+ work unchanged. Limitation: long-PDF PageIndex indexing still needs a
13+ Chat Completions model (see :mod:`openkb.indexer` guard).
2614"""
2715
2816from __future__ import annotations
@@ -76,14 +64,7 @@ def split_responses_model(model: str) -> tuple[str, str]:
7664
7765
7866def messages_to_responses_input (messages : list [dict ]) -> list [dict ]:
79- """Translate Chat Completions ``messages`` to Responses ``input`` items.
80-
81- Plain user/assistant/system/developer messages pass through. Assistant
82- messages carrying ``tool_calls`` become ``function_call`` items (plus a
83- message item when they also have text); ``tool`` messages become
84- ``function_call_output`` items. Content blocks (``type: text`` /
85- ``image_url``) are preserved as-is.
86- """
67+ """Translate Chat Completions ``messages`` to Responses ``input`` items."""
8768 items : list [dict ] = []
8869 for msg in messages :
8970 role = msg .get ("role" )
@@ -96,9 +77,11 @@ def messages_to_responses_input(messages: list[dict]) -> list[dict]:
9677 }
9778 )
9879 continue
99- if role == "assistant" and msg .get ("tool_calls" ):
100- if msg .get ("content" ):
101- items .append ({"role" : "assistant" , "content" : msg ["content" ]})
80+ is_assistant = role == "assistant"
81+ if is_assistant and msg .get ("tool_calls" ):
82+ content = _translate_content (msg .get ("content" ), for_assistant = True )
83+ if content :
84+ items .append ({"role" : "assistant" , "content" : content })
10285 for tc in msg ["tool_calls" ]:
10386 fn = tc .get ("function" , {})
10487 items .append (
@@ -110,25 +93,26 @@ def messages_to_responses_input(messages: list[dict]) -> list[dict]:
11093 }
11194 )
11295 continue
113- content = msg .get ("content" )
96+ content = _translate_content ( msg .get ("content" ), for_assistant = is_assistant )
11497 if content is None :
11598 continue # e.g. reasoning-only placeholder, nothing to send
116- if isinstance (content , list ):
117- content = [
118- _translate_content_block (b , for_assistant = (role == "assistant" )) for b in content
119- ]
12099 items .append ({"role" : role , "content" : content })
121100 return items
122101
123102
103+ def _translate_content (content : Any , * , for_assistant : bool = False ) -> Any :
104+ """Translate message content to Responses input shape (blocks mapped)."""
105+ if isinstance (content , list ):
106+ return [_translate_content_block (b , for_assistant = for_assistant ) for b in content ]
107+ return content
108+
109+
124110def _translate_content_block (block : Any , * , for_assistant : bool = False ) -> Any :
125- """Map one Chat Completions content block to Responses input shape.
111+ """Map one content block to Responses input shape.
126112
127- ``text`` -> ``input_text`` (or ``output_text`` inside ``assistant``
128- messages — the endpoint rejects ``input_text`` there), ``image_url``
129- -> ``input_image`` (lifting ``url``/``detail``); any residual provider
130- markers such as ``cache_control`` are stripped. Unknown block types
131- pass through untouched rather than being silently dropped.
113+ ``output_text`` (not ``input_text``) is required inside ``assistant``
114+ messages; ``cache_control`` leftovers are stripped; unknown types
115+ pass through.
132116 """
133117 if not isinstance (block , dict ):
134118 return block
@@ -211,20 +195,16 @@ def _to_dict(obj: Any) -> dict:
211195 fn = getattr (obj , attr , None )
212196 if callable (fn ):
213197 try :
214- return fn ()
215- except Exception : # noqa: BLE001
216- pass
198+ result = fn ()
199+ except Exception : # noqa: BLE001 -- try the next coercion
200+ continue
201+ if isinstance (result , dict ):
202+ return result
217203 return getattr (obj , "__dict__" , {})
218204
219205
220206def adapt_response (response : Any ) -> SimpleNamespace :
221- """Adapt a Responses API object to the Chat Completions shape.
222-
223- The compiler reads ``response.choices[0].message.content``,
224- ``response.choices[0].finish_reason``, and
225- ``response.usage.{prompt_tokens,completion_tokens}`` — this adapter
226- provides exactly that surface so call sites need no further changes.
227- """
207+ """Adapt a Responses object to the Chat Completions shape call sites read."""
228208 text , incomplete = extract_output_text (response )
229209 usage = getattr (response , "usage" , None ) or SimpleNamespace ()
230210 adapted_usage = SimpleNamespace (
@@ -245,13 +225,7 @@ def adapt_response(response: Any) -> SimpleNamespace:
245225
246226
247227def build_responses_params (model : str , messages : list [dict ], ** kwargs : Any ) -> tuple [str , dict ]:
248- """Build ``(litellm_model, params)`` for :func:`litellm.aresponses`.
249-
250- ``max_tokens``/``max_completion_tokens`` become ``max_output_tokens``,
251- ``response_format`` becomes ``text``, unsupported params are dropped
252- with a debug log. ``api_key``/``base_url``/``extra_headers``/``timeout``
253- pass straight through to LiteLLM.
254- """
228+ """Build ``(litellm_model, params)`` for :func:`litellm.aresponses`."""
255229 litellm_model , _ = split_responses_model (model )
256230 params : dict [str , Any ] = {"input" : messages_to_responses_input (messages )}
257231 for key , value in kwargs .items ():
0 commit comments