Skip to content

Commit 7cabcb0

Browse files
committed
Add native OpenAI Responses API transport (openai-responses/ model prefix)
Some gateways serve models exclusively on /v1/responses and 503 /v1/chat/completions. A KB can now opt in with e.g. model: openai-responses/muse-spark-1.3-contributor. - New openkb/responses.py: message/tool/response_format translation, Chat-Completions-shaped adapter, Agents-SDK OpenAIResponsesModel builder - compiler: route _llm_call/_llm_call_async through litellm.responses - query/chat/lint/skills/decks: Agent constructors + run-config builder use the Responses model (creds from bundle, else env) - indexer: clear error for long-PDF PageIndex path (needs completions) - Docs + 12 unit tests
1 parent ff54396 commit 7cabcb0

10 files changed

Lines changed: 632 additions & 9 deletions

File tree

‎config.yaml.example‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
model: gpt-5.4 # LLM model (any LiteLLM-supported provider)
2+
# Responses-only models (served exclusively on the provider's /v1/responses
3+
# endpoint, e.g. some managed gateways): prefix with `openai-responses/`.
4+
# OpenKB then talks the Responses API for compile/query/chat/lint/skills.
5+
# Long-PDF PageIndex indexing still needs a Chat Completions model.
6+
# model: openai-responses/muse-spark-1.3-contributor
27
language: en # Wiki output language
38
pageindex_threshold: 20 # PDF pages threshold for PageIndex
49

‎examples/configuration/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,27 @@ litellm:
141141
timeout: 1200 # raise further (e.g. 3600) for large local models
142142
```
143143
144+
#### Responses-only models (Responses API transport)
145+
146+
Some gateways serve certain models exclusively on the `/v1/responses`
147+
endpoint and answer `/v1/chat/completions` with `503 Endpoint is
148+
unavailable`. Prefix the model with `openai-responses/` and OpenKB talks
149+
the Responses API for every agent call (compile, query, chat, lint,
150+
skills, decks) — including tool calls and `run_streamed` sessions:
151+
152+
```yaml
153+
model: openai-responses/muse-spark-1.3-contributor
154+
language: en
155+
```
156+
157+
The prefix is OpenKB-only (LiteLLM never sees it). Credentials work as
158+
usual: `LLM_API_KEY` + `OPENAI_API_BASE` from `<kb>/.env`, plus any
159+
`litellm.extra_headers` your gateway needs (e.g. a session-routing
160+
header). Two limitations: long-PDF PageIndex indexing still requires a
161+
Chat Completions model (`openkb add` fails fast with a clear error
162+
otherwise — convert the PDF to Markdown first), and streaming is
163+
supported through the Agents SDK path only.
164+
144165
#### GitHub Copilot / ChatGPT-subscription providers
145166

146167
These need extra headers and use OAuth (no API key):

‎openkb/agent/compiler.py‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
)
3939
from openkb.lint import list_existing_wiki_targets, strip_ghost_wikilinks
4040
from openkb.locks import atomic_write_text
41+
from openkb.responses import aresponses_completion, is_responses_model, responses_completion
4142
from openkb.schema import INDEX_SEED, get_agents_md
4243

4344
logger = logging.getLogger(__name__)
@@ -425,7 +426,10 @@ def _llm_call(
425426
spinner.start()
426427
t0 = time.time()
427428

428-
response = litellm.completion(model=model, messages=messages, **kwargs)
429+
if is_responses_model(model):
430+
response = responses_completion(model=model, messages=messages, **kwargs)
431+
else:
432+
response = litellm.completion(model=model, messages=messages, **kwargs)
429433
content = response.choices[0].message.content or ""
430434
truncated = _warn_if_truncated(response, step_name, kwargs.get("max_tokens"))
431435

@@ -466,7 +470,10 @@ async def _llm_call_async(
466470

467471
t0 = time.time()
468472

469-
response = await litellm.acompletion(model=model, messages=messages, **kwargs)
473+
if is_responses_model(model):
474+
response = await aresponses_completion(model=model, messages=messages, **kwargs)
475+
else:
476+
response = await litellm.acompletion(model=model, messages=messages, **kwargs)
470477
content = response.choices[0].message.content or ""
471478
truncated = _warn_if_truncated(response, step_name, kwargs.get("max_tokens"))
472479

‎openkb/agent/linter.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99

1010
from openkb.agent.tools import list_wiki_files, read_wiki_file
1111
from openkb.config import LlmCredentialBundle, resolve_model_settings
12+
from openkb.responses import responses_agent_model
1213
from openkb.schema import get_agents_md
1314

1415
MAX_TURNS = 50
@@ -97,7 +98,7 @@ def read_file(path: str) -> str:
9798
name="wiki-linter",
9899
instructions=instructions,
99100
tools=[list_files, read_file],
100-
model=f"litellm/{model}",
101+
model=(responses_agent_model(model, bundle) or f"litellm/{model}"),
101102
model_settings=ModelSettings(**model_settings),
102103
)
103104

‎openkb/agent/query.py‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
write_kb_file,
1616
)
1717
from openkb.config import LlmCredentialBundle, resolve_model_settings
18+
from openkb.responses import responses_agent_model
1819
from openkb.schema import get_agents_md
1920

2021
MAX_TURNS = 50
@@ -118,7 +119,7 @@ def get_image(image_path: str) -> ToolOutputImage | ToolOutputText:
118119
name="wiki-query",
119120
instructions=instructions,
120121
tools=[read_file, get_page_content, get_image],
121-
model=f"litellm/{model}",
122+
model=(responses_agent_model(model, bundle) or f"litellm/{model}"),
122123
model_settings=ModelSettings(**model_settings),
123124
)
124125

@@ -506,9 +507,20 @@ def build_run_config_from_bundle(model: str, bundle: "LlmCredentialBundle | None
506507
must NOT be added here -- doing so yields ``litellm/openai/...`` which
507508
litellm rejects as an unknown provider.
508509
"""
510+
from agents import RunConfig
511+
509512
if bundle is None:
513+
instance = responses_agent_model(model, None)
514+
if instance is not None:
515+
# Legacy CLI path for Responses models: credentials fall back
516+
# to LLM_API_KEY / OPENAI_API_BASE env (loaded from the KB
517+
# .env by _setup_llm_key before this is called).
518+
return RunConfig(model=instance)
510519
return None
511-
from agents import RunConfig
520+
521+
instance = responses_agent_model(model, bundle)
522+
if instance is not None:
523+
return RunConfig(model=instance)
512524
from agents.extensions.models.litellm_model import LitellmModel
513525

514526
litellm_model = LitellmModel(

‎openkb/indexer.py‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
from pageindex import IndexConfig, PageIndexClient
1313

1414
from openkb.config import resolve_concurrency, resolve_effective_config
15+
from openkb.responses import is_responses_model
1516
from openkb.tree_renderer import render_summary_md
1617

1718
logger = logging.getLogger(__name__)
@@ -191,6 +192,12 @@ def index_long_document(pdf_path: Path, kb_dir: Path, doc_name: str | None = Non
191192
config = resolve_effective_config(kb_dir)[0]
192193

193194
model: str = config.get("model", "gpt-5.4")
195+
if is_responses_model(model):
196+
raise ValueError(
197+
f"Long-PDF PageIndex indexing requires a Chat Completions model, "
198+
f"but the KB is configured with Responses-only {model!r}. "
199+
f"Convert the PDF to Markdown first, or switch the KB model."
200+
)
194201
pageindex_api_key = os.environ.get("PAGEINDEX_API_KEY", "")
195202

196203
index_config = _build_index_config(config)

0 commit comments

Comments
 (0)