Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
"""OpenAI native provider using the official `openai` Python SDK.
Handles GPT-5.x, GPT-4.x, and o-series reasoning models.
Also used as base for OpenRouter (same API shape, different base_url).
"""
from __future__ import annotations
import json
from typing import Any, Dict, List, Mapping, Optional
from core.logging import get_logger
from services.llm.observation import observe_response, observe_sdk_request, observe_stage
from services.llm.protocol import (
ContentBlock,
LLMError,
LLMErrorCategory,
LLMResponse,
Message,
StreamEvent,
StreamSink,
ThinkingConfig,
ToolCall,
ToolDef,
Usage,
)
#: Responses API stream events that carry the finished response.
_RESPONSES_TERMINAL_EVENTS = frozenset({"response.completed", "response.incomplete", "response.failed"})
# Responses generation errors arrive inside HTTP 2xx bodies/events. Give
# known codes the same retry semantics as their HTTP error counterparts.
_RESPONSE_ERROR_STATUS = {
"server_error": 500, "overloaded_error": 529,
"rate_limit_exceeded": 429, "insufficient_quota": 429,
"billing_hard_limit_reached": 429, "insufficient_credits": 429,
"vector_store_timeout": 408,
"invalid_prompt": 400, "data_residency_mismatch": 400, "bio_policy": 400,
"invalid_image": 400, "invalid_image_format": 400, "invalid_base64_image": 400,
"invalid_image_url": 400, "image_too_large": 400, "image_too_small": 400,
"image_parse_error": 400, "image_content_policy_violation": 400,
"invalid_image_mode": 400, "image_file_too_large": 400,
"unsupported_image_media_type": 400, "empty_image_file": 400,
"failed_to_download_image": 400, "image_file_not_found": 400,
}
class _ResponseGenerationFailure(Exception):
"""SDK-shaped metadata for a failed generation, not a transport error."""
def __init__(self, code: Optional[str], message: str, request_id: Optional[str]):
super().__init__(message)
self.body = {"code": code, "message": message}
self.code = code
self.status_code = _RESPONSE_ERROR_STATUS.get(code)
self.request_id = request_id
logger = get_logger(__name__)
def _image_sources(m: Message) -> List[Dict[str, Any]]:
"""The message's hydrated images (``source`` dicts with ``data_b64``)."""
return [
block.source
for block in m.blocks or []
if block.type == "image"
and isinstance(block.source, dict)
and block.source.get("kind") == "bytes"
]
def _data_url(source: Dict[str, Any]) -> str:
return f"data:{source['media_type']};base64,{source['data_b64']}"
def _detail(source: Dict[str, Any]) -> str:
detail = str(source.get("detail") or "auto")
return detail if detail in ("low", "high", "auto") else "auto"
class OpenAIProvider:
provider_name = "openai"
#: Prepended to the model name on the wire only. The LLM gateway
#: (LiteLLM) routes OpenAI-format calls by provider prefix
#: (``groq/llama-...``); everything else here keeps the bare id.
_model_prefix: str = ""
def __init__(
self,
api_key: str,
*,
proxy_url: Optional[str] = None,
base_url: Optional[str] = None,
provider_name: Optional[str] = None,
max_retries: int = 2,
model_prefix: str = "",
):
import openai
from services.llm.config import attempt_timeout_seconds
self.provider_name = provider_name or type(self).provider_name
self._model_prefix = model_prefix
kwargs: Dict[str, Any] = {
"api_key": api_key,
"max_retries": max(0, int(max_retries)),
}
# The user's stored URL (resolved when it was saved) wins over the
# vendor-declared one. Neither is ever rewritten here (RFC-0003 D1).
url = proxy_url or base_url
if url:
kwargs["base_url"] = url
# A provider whose server sends nothing until the whole answer is
# done declares a longer attempt than the SDK's default read timeout.
attempt = attempt_timeout_seconds(self.provider_name)
if attempt is not None:
kwargs["timeout"] = openai.Timeout(attempt, connect=openai.DEFAULT_TIMEOUT.connect)
#: Which setting produced the URL, for failure logs (RFC-0003 D10).
self.url_source = "proxy" if proxy_url else ("llm_defaults" if base_url else "sdk_default")
self._client = openai.AsyncOpenAI(**kwargs)
@property
def endpoint_url(self) -> str:
"""The base URL requests actually go to."""
return str(self._client.base_url)
def _wire_model(self, model: str) -> str:
"""The model name a request carries (see ``_model_prefix``)."""
return f"{self._model_prefix}{model}" if self._model_prefix else model
def _bare_model(self, model: str) -> str:
"""A model name the server echoed, without the wire prefix."""
prefix = self._model_prefix
return model[len(prefix):] if prefix and model.startswith(prefix) else model
@staticmethod
def _add_request_extras(
params: Dict[str, Any],
extra_headers: Optional[Mapping[str, str]],
extra_body: Optional[Mapping[str, Any]],
) -> None:
"""Per-request headers and body fields (the LLM gateway's
attribution and replay cache), merged with any ``extra_body``
the request already carries."""
if extra_headers:
params["extra_headers"] = dict(extra_headers)
if extra_body:
params.setdefault("extra_body", {}).update(extra_body)
def _raise_if_error_body(self, resp: Any) -> None:
"""Turn a 2xx that carried an error body into a ``PROTOCOL`` failure.
The SDK raises only on 4xx/5xx. A server asked for a route it does
not serve can answer HTTP 200 with an ``{"error": ...}`` body (LM
Studio does), which the SDK parses into a completion with no
choices. Left alone that surfaces as "AI generated empty response",
with nothing pointing at the base URL (RFC-0003 §2.1, D9).
"""
extra = getattr(resp, "model_extra", None)
error = extra.get("error") if isinstance(extra, dict) else None
if error is None:
candidate = getattr(resp, "error", None)
if isinstance(candidate, (str, dict)):
error = candidate
if not error:
return
from services.llm.endpoints import redact_url
from services.llm.protocol import LLMError, LLMErrorCategory
url = redact_url(self.endpoint_url)
raise LLMError(
message=f"HTTP 2xx without choices from {url}: {str(error)[:300]}",
provider=self.provider_name,
category=LLMErrorCategory.PROTOCOL,
public_message=(
f"The server at {url} answered without a completion. "
"Check the base URL configured for this provider."
),
)
# ------------------------------------------------------------------
# chat
# ------------------------------------------------------------------
async def chat(
self,
messages: List[Message],
*,
model: str,
temperature: float = 0.7,
max_tokens: int = 4096,
thinking: Optional[ThinkingConfig] = None,
tools: Optional[List[ToolDef]] = None,
context_management: Optional[Dict[str, Any]] = None,
on_event: Optional[StreamSink] = None,
effort: Optional[str] = None,
extra_headers: Optional[Mapping[str, str]] = None,
extra_body: Optional[Mapping[str, Any]] = None,
) -> LLMResponse:
observe_stage("request_encoding")
model = self._clean_model(model)
policy = self._model_policy(model, thinking)
if policy["use_responses"] and (
tools
or self._has_responses_state(messages)
or context_management
):
return await self._chat_responses(
messages=messages,
model=model,
max_tokens=max_tokens,
thinking=thinking,
tools=tools,
context_management=context_management,
on_event=on_event,
effort=effort,
extra_headers=extra_headers,
extra_body=extra_body,
)
params: Dict[str, Any] = {
"model": self._wire_model(model),
"messages": [self._to_api_message(m) for m in messages],
}
# OpenAI reasoning models use max_completion_tokens. Compatible
# endpoints continue to receive their documented max_tokens field.
if policy["max_completion_tokens"]:
params["max_completion_tokens"] = max_tokens
else:
params["max_tokens"] = max_tokens
if policy["temperature_allowed"]:
params["temperature"] = (
policy["fixed_temperature"]
if policy["fixed_temperature"] is not None
else temperature
)
if thinking and thinking.enabled:
thinking_type = policy["thinking_type"]
if thinking_type == "effort":
params["reasoning_effort"] = thinking.effort or "medium"
elif thinking_type == "format":
params.setdefault("extra_body", {})["reasoning_format"] = (
thinking.format
if thinking.format in {"parsed", "hidden"}
else "parsed"
)
elif thinking_type == "budget":
params.setdefault("extra_body", {})["thinking_budget"] = max(
0, int(thinking.budget)
)
elif policy["thinking_default_on"]:
params.setdefault("extra_body", {})["thinking"] = {
"type": "disabled"
}
if effort:
# The owner's chat choice (Quick / Thorough), over the agent's own
# reasoning effort. Only the effort_models receive one (ChatUnifier).
params["reasoning_effort"] = effort
# Tools
if tools:
params["tools"] = [self._to_api_tool(t) for t in tools]
self._add_request_extras(params, extra_headers, extra_body)
if on_event is not None:
resp = await self._stream_completion(params, on_event)
observe_response(resp)
return self._normalize(resp, model)
observe_sdk_request(self)
resp = await self._client.chat.completions.create(**params)
observe_response(resp)
return self._normalize(resp, model)
async def _stream_completion(self, params: Dict[str, Any], on_event: StreamSink) -> Any:
"""The completion ``create(**params)`` would return, streamed.
Chunks fold into the SDK's own snapshot (the state its ``stream()``
helper keeps). That helper is not used: it refuses tools that are not
``strict``, and its final parse raises on a ``length`` finish that a
plain ``create`` returns normally.
"""
from openai.lib.streaming.chat._completions import ChatCompletionStreamState
state = ChatCompletionStreamState()
observe_sdk_request(self)
stream = await self._client.chat.completions.create(
**params, stream=True, stream_options={"include_usage": True}
)
async for chunk in stream:
state.handle_chunk(chunk)
for choice in chunk.choices or ():
delta = choice.delta
text = getattr(delta, "content", None)
if isinstance(text, str) and text:
await on_event(StreamEvent("text", text))
reasoning = getattr(delta, "reasoning_content", None) or getattr(delta, "reasoning", None)
if isinstance(reasoning, str) and reasoning:
await on_event(StreamEvent("reasoning", reasoning))
return state.current_completion_snapshot
async def _chat_responses(
self,
*,
messages: List[Message],
model: str,
max_tokens: int,
thinking: Optional[ThinkingConfig],
tools: Optional[List[ToolDef]],
context_management: Optional[Dict[str, Any]],
on_event: Optional[StreamSink] = None,
effort: Optional[str] = None,
extra_headers: Optional[Mapping[str, str]] = None,
extra_body: Optional[Mapping[str, Any]] = None,
) -> LLMResponse:
"""Run a self-contained Responses API turn for reasoning tool use."""
params: Dict[str, Any] = {
"model": self._wire_model(model),
"input": self._to_responses_input(messages),
"max_output_tokens": max_tokens,
# Durable encrypted reasoning state is recorded in our message;
# do not depend on OpenAI retaining a prior response.
"store": False,
"include": ["reasoning.encrypted_content"],
}
if thinking and thinking.enabled:
params["reasoning"] = {
"effort": thinking.effort or "medium",
}
if effort:
# The owner's chat choice, over the agent's own effort.
params["reasoning"] = {**params.get("reasoning", {}), "effort": effort}
if tools:
params["tools"] = [
self._to_responses_tool(tool) for tool in tools
]
if (
isinstance(context_management, dict)
and context_management.get("type") == "compaction"
):
threshold = int(
context_management.get("compact_threshold") or 0
)
if threshold > 0:
params["context_management"] = [
{
"type": "compaction",
"compact_threshold": threshold,
}
]
self._add_request_extras(params, extra_headers, extra_body)
if on_event is not None:
response = await self._stream_response(params, on_event)
observe_response(response)
return self._normalize_responses(response, model)
observe_sdk_request(self)
response = await self._client.responses.create(**params)
observe_response(response)
return self._normalize_responses(response, model)
async def _stream_response(self, params: Dict[str, Any], on_event: StreamSink) -> Any:
"""The response ``responses.create(**params)`` would return, streamed:
the one the terminal event carries. Not the SDK's ``stream()``
helper, whose final read raises for an incomplete or failed response
that a plain ``create`` returns."""
final: Any = None
observe_sdk_request(self)
stream = await self._client.responses.create(**params, stream=True)
async for event in stream:
kind = getattr(event, "type", "")
if kind == "response.output_text.delta":
delta = getattr(event, "delta", "") or ""
if delta:
await on_event(StreamEvent("text", delta))
elif kind == "response.reasoning_summary_text.delta":
delta = getattr(event, "delta", "") or ""
if delta:
await on_event(StreamEvent("reasoning", delta))
elif kind in _RESPONSES_TERMINAL_EVENTS:
final = getattr(event, "response", None)
if kind == "response.failed":
self._raise_if_failed_response(final, failed=True)
if final is None:
raise LLMError(
message="The response stream ended before the response was complete.",
provider=self.provider_name,
category=LLMErrorCategory.CONNECTION,
retryable=True,
)
return final
# ------------------------------------------------------------------
# fetch_models
# ------------------------------------------------------------------
async def fetch_models(self, api_key: str) -> List[str]:
"""Fetch models using the client's configured base_url.
Providers that declare ``supports_model_listing: false`` in
llm_defaults.json expose no model-list route at all (Sarvam).
Calling ``models.list()`` there 404s, and that 404 arrives as an
``openai.OpenAIError`` which ``ChatUnifier.fetch_models``
translates into ``NodeUserError`` and ``AIService.fetch_models``
re-raises *before* reaching its curated fallback — breaking both
credential validation and the model dropdown for a perfectly
valid key. For those providers, serve the JSON-curated list and
validate the key with the cheapest real call the OpenAI wire
format offers: a one-token completion. An invalid key still
raises the typed SDK error the unifier already knows how to
translate, so the probe stays a real credential check.
The flag is read per provider from config rather than branched on
a provider name, so any future no-listing endpoint is a JSON edit.
"""
from services.llm.config import curated_models, supports_model_listing
if supports_model_listing(self.provider_name):
models = await self._client.models.list()
return sorted([m.id for m in models.data])
curated = curated_models(self.provider_name)
if not curated:
raise ValueError(
f"llm_defaults.json providers.{self.provider_name} sets "
"supports_model_listing=false but declares no models "
"(popular_models and max_output_tokens are both empty)"
)
await self._client.chat.completions.create(
model=curated[0],
messages=[{"role": "user", "content": "hi"}],
max_tokens=1,
)
return curated
# ------------------------------------------------------------------
# internals
# ------------------------------------------------------------------
def _to_api_message(self, m: Message) -> Dict[str, Any]:
if m.role == "tool":
return {
"role": "tool",
"tool_call_id": m.tool_call_id or "",
"content": m.content,
}
if m.role == "assistant":
result: Dict[str, Any] = {
"role": "assistant",
"content": m.content or None,
}
if m.tool_calls:
result["tool_calls"] = [
{
"id": tc.id,
"type": "function",
"function": {
"name": tc.name,
"arguments": (
tc.raw_arguments
if tc.raw_arguments is not None
else json.dumps(tc.args)
),
},
}
for tc in m.tool_calls
]
state = m.provider_state
if state.get("provider") == self.provider_name:
payload = state.get("payload")
if isinstance(payload, dict):
# These are the only continuation fields currently
# accepted by OpenAI-compatible chat endpoints. Never
# forward arbitrary provider state into an API request.
for key in (
"reasoning",
"reasoning_content",
"reasoning_details",
"refusal",
):
if payload.get(key) is not None:
result[key] = payload[key]
return result
images = _image_sources(m) if m.role == "user" else []
if images:
# Images the owner attached: Chat Completions takes them as
# image_url parts (a data URL) beside the text.
parts: List[Dict[str, Any]] = [{"type": "text", "text": m.content}] if m.content else []
parts.extend(
{"type": "image_url", "image_url": {"url": _data_url(source), "detail": _detail(source)}}
for source in images
)
return {"role": "user", "content": parts}
return {"role": m.role, "content": m.content}
def _to_api_tool(self, tool: ToolDef) -> Dict[str, Any]:
from services.llm.schema import compile_tool_schema
return {
"type": "function",
"function": {
"name": tool.name,
"description": tool.description,
"parameters": compile_tool_schema(
tool.parameters, provider=self.provider_name
),
},
}
def _to_responses_tool(self, tool: ToolDef) -> Dict[str, Any]:
from services.llm.schema import compile_tool_schema
return {
"type": "function",
"name": tool.name,
"description": tool.description,
"parameters": compile_tool_schema(
tool.parameters, provider=self.provider_name
),
"strict": False,
}
def _to_responses_input(
self, messages: List[Message]
) -> List[Dict[str, Any]]:
items: List[Dict[str, Any]] = []
for message in messages:
if message.role == "tool":
items.append(
{
"type": "function_call_output",
"call_id": message.tool_call_id or "",
"output": message.content,
}
)
continue
if message.role == "assistant":
state = message.provider_state
payload = state.get("payload")
if (
state.get("provider") == self.provider_name
and isinstance(payload, dict)
and payload.get("api") == "responses"
and isinstance(payload.get("output"), list)
):
items.extend(
dict(item)
for item in payload["output"]
if isinstance(item, dict)
)
continue
if message.content:
items.append(
{
"role": "assistant",
"content": message.content,
}
)
items.extend(
{
"type": "function_call",
"call_id": call.id,
"name": call.name,
"arguments": (
call.raw_arguments
if call.raw_arguments is not None
else json.dumps(call.args)
),
}
for call in message.tool_calls
)
continue
images = _image_sources(message) if message.role == "user" else []
if images:
# Images the owner attached: Responses takes them as
# input_image parts beside input_text.
content: List[Dict[str, Any]] = (
[{"type": "input_text", "text": message.content}] if message.content else []
)
content.extend(
{"type": "input_image", "image_url": _data_url(source), "detail": _detail(source)}
for source in images
)
items.append({"role": "user", "content": content})
continue
items.append(
{"role": message.role, "content": message.content}
)
return items
def _normalize(self, resp: Any, model: str) -> LLMResponse:
choices = getattr(resp, "choices", None)
choice = choices[0] if choices else None
if not choice:
self._raise_if_error_body(resp)
return LLMResponse(model=model)
msg = choice.message
content = msg.content or ""
thinking = None
tool_calls = []
blocks: List[ContentBlock] = []
# OpenAI-compatible providers expose reasoning under several fields:
# DeepSeek/xAI commonly use reasoning_content, Groq uses reasoning,
# and OpenRouter needs the lossless reasoning_details array replayed
# on the next tool turn.
reasoning_content = getattr(msg, "reasoning_content", None)
reasoning = getattr(msg, "reasoning", None)
if isinstance(reasoning_content, str) and reasoning_content:
thinking = reasoning_content
elif isinstance(reasoning, str) and reasoning:
thinking = reasoning
if thinking:
blocks.append(ContentBlock(type="reasoning", text=thinking))
refusal = getattr(msg, "refusal", None)
if not content and isinstance(refusal, str) and refusal:
content = refusal
if content:
blocks.append(
ContentBlock(
type="text",
text=content,
metadata=(
{"refusal": True}
if isinstance(refusal, str) and refusal
else {}
),
)
)
# Tool calls
if msg.tool_calls:
for tc in msg.tool_calls:
args = tc.function.arguments
call = ToolCall.from_raw(
id=tc.id,
name=tc.function.name,
arguments=args,
)
tool_calls.append(call)
blocks.append(ContentBlock(type="tool_call", tool_call=call))
u = resp.usage
usage = Usage(
input_tokens=getattr(u, "prompt_tokens", 0) if u else 0,
output_tokens=getattr(u, "completion_tokens", 0) if u else 0,
total_tokens=getattr(u, "total_tokens", 0) if u else 0,
cache_read_tokens=self._cache_read_tokens(u),
reasoning_tokens=getattr(getattr(u, "completion_tokens_details", None), "reasoning_tokens", 0) if u else 0,
)
payload: Dict[str, Any] = {}
if isinstance(reasoning, str) and reasoning:
payload["reasoning"] = reasoning
if isinstance(reasoning_content, str) and reasoning_content:
payload["reasoning_content"] = reasoning_content
reasoning_details = getattr(msg, "reasoning_details", None)
if isinstance(reasoning_details, (list, tuple)):
encoded_details = [
self._dump_response_item(detail)
for detail in reasoning_details
]
encoded_details = [detail for detail in encoded_details if detail]
if encoded_details:
payload["reasoning_details"] = encoded_details
if isinstance(refusal, str) and refusal:
payload["refusal"] = refusal
assistant_message = Message(
role="assistant",
content=content,
tool_calls=tool_calls,
blocks=blocks,
provider_state=(
{"provider": self.provider_name, "payload": payload}
if payload
else {}
),
)
return LLMResponse(
content=content,
thinking=thinking,
tool_calls=tool_calls,
usage=usage,
model=model,
finish_reason=choice.finish_reason or "stop",
raw=resp,
assistant_message=assistant_message,
)
def _raise_if_failed_response(self, resp: Any, *, failed: bool = False) -> None:
error = getattr(resp, "error", None)
code = error.get("code") if isinstance(error, dict) else getattr(error, "code", None)
message = error.get("message") if isinstance(error, dict) else getattr(error, "message", None)
if failed or getattr(resp, "status", None) == "failed" or isinstance(code, str) or isinstance(message, str):
# Do not record partial tool calls or publish partial text as a
# completed turn when the provider says generation failed.
failure = _ResponseGenerationFailure(
code if isinstance(code, str) else None,
message if isinstance(message, str) else "Response generation failed.",
getattr(resp, "_request_id", None),
)
raise LLMError.from_exception(self.provider_name, failure) from None
def _normalize_responses(self, resp: Any, model: str) -> LLMResponse:
self._raise_if_failed_response(resp)
text_parts: List[str] = []
thinking_parts: List[str] = []
tool_calls: List[ToolCall] = []
blocks: List[ContentBlock] = []
output_state: List[Dict[str, Any]] = []
for item in getattr(resp, "output", ()) or ():
dumped = self._dump_response_item(item)
if dumped:
output_state.append(dumped)
item_type = getattr(item, "type", None)
if item_type == "reasoning":
for summary in getattr(item, "summary", ()) or ():
text = getattr(summary, "text", None)
if isinstance(text, str) and text:
thinking_parts.append(text)
blocks.append(
ContentBlock(type="reasoning", text=text)
)
elif item_type == "message":
for part in getattr(item, "content", ()) or ():
part_type = getattr(part, "type", None)
text = getattr(part, "text", None)
if part_type == "output_text" and isinstance(text, str):
text_parts.append(text)
blocks.append(ContentBlock(type="text", text=text))
elif part_type == "refusal":
refusal = getattr(part, "refusal", None)
if not isinstance(refusal, str):
continue
text_parts.append(refusal)
blocks.append(
ContentBlock(
type="text",
text=refusal,
metadata={"refusal": True},
)
)
elif item_type == "function_call":
call = ToolCall.from_raw(
id=str(
getattr(item, "call_id", None)
or getattr(item, "id", "")
),
name=str(getattr(item, "name", "")),
arguments=getattr(item, "arguments", "{}"),
)
tool_calls.append(call)
blocks.append(ContentBlock(type="tool_call", tool_call=call))
usage_obj = getattr(resp, "usage", None)
input_details = getattr(usage_obj, "input_tokens_details", None)
output_details = getattr(usage_obj, "output_tokens_details", None)
usage = Usage(
input_tokens=(
getattr(usage_obj, "input_tokens", 0) if usage_obj else 0
),
output_tokens=(
getattr(usage_obj, "output_tokens", 0) if usage_obj else 0
),
total_tokens=(
getattr(usage_obj, "total_tokens", 0) if usage_obj else 0
),
cache_read_tokens=(
getattr(input_details, "cached_tokens", 0)
if input_details
else 0
),
reasoning_tokens=(
getattr(output_details, "reasoning_tokens", 0)
if output_details
else 0
),
)
content = "\n".join(text_parts)
thinking_text = (
"\n\n".join(thinking_parts) if thinking_parts else None
)
assistant_message = Message(
role="assistant",
content=content,
tool_calls=tool_calls,
blocks=blocks,
provider_state={
"provider": self.provider_name,
"payload": {
"api": "responses",
"response_id": str(getattr(resp, "id", "") or ""),
"output": output_state,
},
},
)
return LLMResponse(
content=content,
thinking=thinking_text,
tool_calls=tool_calls,
usage=usage,
model=self._bare_model(str(getattr(resp, "model", "") or model)),
finish_reason=str(
getattr(resp, "status", "") or "stop"
).lower(),
raw=resp,
assistant_message=assistant_message,
)
@staticmethod
def _dump_response_item(item: Any) -> Dict[str, Any]:
dump = getattr(item, "model_dump", None)
if dump is not None:
value = dump(mode="json", exclude_none=True)
return dict(value) if isinstance(value, dict) else {}
if isinstance(item, dict):
return dict(item)
# Lightweight fallback for SDK-compatible proxy objects and tests.
item_type = getattr(item, "type", None)
if not isinstance(item_type, str):
return {}
result: Dict[str, Any] = {"type": item_type}
for key in (
"id",
"status",
"role",
"call_id",
"name",
"arguments",
"encrypted_content",
):
value = getattr(item, key, None)
if isinstance(value, (str, int, float, bool)):
result[key] = value
for key in ("content", "summary"):
values = getattr(item, key, None)
if not values:
continue
encoded: List[Dict[str, Any]] = []
for value in values:
value_dump = getattr(value, "model_dump", None)
if value_dump is not None:
dumped = value_dump(mode="json", exclude_none=True)
if isinstance(dumped, dict):
encoded.append(dumped)
else:
entry = {
"type": getattr(value, "type", None),
"text": getattr(value, "text", None),
}
encoded.append(
{
item_key: item_value
for item_key, item_value in entry.items()
if item_value is not None
}
)
result[key] = encoded
return result
def _clean_model(self, model: str) -> str:
# Provider model IDs are opaque. Groq requires owner-qualified IDs
# such as ``openai/gpt-oss-120b`` and ``qwen/qwen3-32b``; local
# OpenAI-compatible endpoints may use namespaces too. Only remove the
# UI-only OpenRouter free-tier decoration.
return model.removeprefix("[FREE] ")
def _model_policy(
self, model: str, thinking: Optional[ThinkingConfig]
) -> Dict[str, Any]:
"""Resolve JSON-driven provider quirks in one native layer."""
from services.llm.config import LLM_DEFAULTS
config = LLM_DEFAULTS.get("providers", {}).get(self.provider_name, {})
reasoning_models = tuple(config.get("reasoning_models", ()))
is_reasoning = any(model.startswith(prefix) for prefix in reasoning_models)
if self.provider_name == "openai":
is_reasoning = is_reasoning or model.startswith(("o1", "o3", "o4"))
thinking_models = tuple(config.get("thinking_models", ()))
is_configured_thinking_model = any(
model.startswith(prefix) or prefix in model
for prefix in thinking_models
)
openai_reasoning_capable = (
self.provider_name == "openai"
and (is_reasoning or is_configured_thinking_model)
)
fixed_temperature = None
for prefix, value in config.get("fixed_temperature", {}).items():
if model.startswith(prefix):
fixed_temperature = float(value)
break
supported = set(config.get("supported_params", ()))
temperature_allowed = not is_reasoning and not openai_reasoning_capable
if supported and "temperature" not in supported:
temperature_allowed = False
default_on = any(
model.startswith(prefix)
for prefix in config.get("thinking_default_on", ())
)
thinking_type = config.get("thinking_type", "none")
supports_configured_thinking = (
not thinking_models
or is_configured_thinking_model
or is_reasoning
)
if not supports_configured_thinking:
thinking_type = "none"
# GPT-5 and o-series models use reasoning effort. Groq's GPT-OSS
# models also use reasoning_effort; reasoning_format is explicitly
# unsupported for those models and is reserved for Qwen.
if self.provider_name == "openai" and (
model.startswith("gpt-5") or is_reasoning
):
thinking_type = "effort"
elif self.provider_name == "groq" and (
model.startswith("openai/gpt-oss-")
or model.startswith("gpt-oss-")
):
thinking_type = "effort"
return {
"max_completion_tokens": (
openai_reasoning_capable
),
"use_responses": (
openai_reasoning_capable
),
"temperature_allowed": temperature_allowed
and not (
self.provider_name == "openai"
and thinking is not None
and thinking.enabled
and thinking_type == "effort"
),
"fixed_temperature": fixed_temperature,
"thinking_default_on": default_on,
"thinking_type": thinking_type,
}
def _has_responses_state(self, messages: List[Message]) -> bool:
return any(
message.provider_state.get("provider") == self.provider_name
and isinstance(message.provider_state.get("payload"), dict)
and message.provider_state["payload"].get("api") == "responses"
for message in messages
)
@staticmethod
def _cache_read_tokens(usage: Any) -> int:
if not usage:
return 0
details = getattr(usage, "prompt_tokens_details", None)
return getattr(details, "cached_tokens", 0) if details else 0
async def aclose(self) -> None:
close = getattr(self._client, "close", None)
if close is not None:
result = close()
if hasattr(result, "__await__"):
await result
# ---------------------------------------------------------------------------
# Plugin self-registration
# ---------------------------------------------------------------------------
# Registers ``openai`` into the global registry. The typed
# ``OpenAIError`` class is declared as a lazy "module:Class" ref so
# registration never imports the SDK at boot.
#
# OpenAI-compatible providers (xai / deepseek / kimi / mistral / ollama /
# lmstudio) register separately in ``_compat.py`` — they reuse
# ``OpenAIProvider`` as their factory but pin ``base_url`` via
# ``ProviderSpec.client_kwargs`` rather than per-provider Python.
from services.llm.registry import ProviderSpec, register_provider
register_provider(
ProviderSpec(
name="openai",
factory=OpenAIProvider,
sdk_exception_refs=("openai:OpenAIError",),
)
)