vibe.llm_providers.openai

OpenAI-compatible LLM provider implementation.

OpenAIChatConverter

Converter for OpenAI ChatCompletions API format.

Format: {"role": "user|assistant|system|tool", "content": ..., "tool_calls": [...]}

__init__ 

__init__(remove_empty_content: bool = True) -> None

Initialize the chat converter.

Parameters:
  • remove_empty_content (bool, default: True ) –

    If True, omit content field from assistant messages with tool_calls when content is empty. OpenAI prefers this. Set False for providers that require explicit content: null.

convert_system 

convert_system(msg: SystemMessage) -> dict[str, Any]

Convert system message to OpenAI system role format.

convert_user 

convert_user(msg: UserMessage) -> dict[str, Any]

Convert user message to OpenAI user role format, JSON-encoding dicts.

convert_assistant 

convert_assistant(msg: AssistantMessage) -> dict[str, Any]

Convert assistant message with optional tool_calls to OpenAI format.

convert_tool_result 

convert_tool_result(msg: ToolResult) -> dict[str, Any]

Convert tool result to OpenAI tool role format with tool_call_id.

OpenAIResponsesConverter

Converter for OpenAI Responses API format (gpt-5, o4, etc.).

Format differs from ChatCompletions: - System messages use role="developer" with content blocks - User/Assistant messages use content blocks with type="input_text"|"output_text" - Tool calls are separate items with type="function_call" - Tool results use type="function_call_output"

convert_system 

convert_system(msg: SystemMessage) -> dict[str, Any]

Convert system message to Responses API developer role with content blocks.

convert_user 

convert_user(msg: UserMessage) -> dict[str, Any]

Convert user message to Responses API format with input_text block.

convert_assistant 

convert_assistant(msg: AssistantMessage) -> object

Convert assistant message.

Note: For messages with tool_calls, this returns a list of function_call items, not a single message. The convert_all method handles flattening.

convert_tool_result 

convert_tool_result(msg: ToolResult) -> dict[str, Any]

Convert tool result to Responses API function_call_output format.

convert_all 

convert_all(messages: list[Message]) -> list[dict[str, Any]]

Convert all messages, handling multi-item assistant conversions.

ResponsesAPIError

Raised when the OpenAI Responses API sends an explicit error event.

OpenAIProvider

LLMProvider implementation for OpenAI APIs.

Supports both Responses API (new models) and ChatCompletions API (legacy/third-party).

Configuration options (common - via ProviderConfig): - api_key: API key for authentication (required) - model: Model name (default: "gpt-3.5-turbo") - base_url: Custom base URL for OpenAI-compatible providers (optional) - temperature: Controls randomness (0.0 - 2.0) - max_tokens: Maximum tokens in response (default: 32768) - timeout: Request timeout in seconds (default: 10) - tools: Enable tool calling (default: True)

Configuration options (OpenAI-specific): - use_responses_api: Explicit override to force API selection (optional) Defaults to auto-detection based on model and base_url - reasoning_effort: For gpt-5/o4 models ("none", "low", "medium", "high") - reasoning_summary: For gpt-5/o4 models ("auto", "detailed") - controls reasoning output detail - text_verbosity: For gpt-5/o4 models ("low", "medium", "high") - remove_empty_content: Whether to omit empty content from assistant messages (default: True)

API Selection Logic: - Third-party providers (custom base_url): ChatCompletions API - Official OpenAI gpt-5/gpt-4.1/o4/gpt-oss: Responses API - Other official OpenAI models: ChatCompletions API - Explicit override: use_responses_api config flag

Examples:

Third-party provider (auto-detects ChatCompletions API)

config = { "api_key": "...", "model": "llama-3-70b", "base_url": "https://api.berget.ai/v1" }

Latest OpenAI model (auto-detects Responses API)

config = { "api_key": "...", "model": "gpt-4.1" }

Force specific API

config = { "api_key": "...", "model": "gpt-4", "use_responses_api": False # Force ChatCompletions }

convert_messages_to_provider_format 

convert_messages_to_provider_format(messages: list[Message], tools: list[Tool] | None = None) -> list[dict[str, Any]]

Convert internal messages and tools to OpenAI-compatible format.

Uses MessageConverter pattern for clean separation of conversion logic.

Parameters:
  • messages (list[Message]) –

    List of typed Message objects

  • tools (list[Tool] | None, default: None ) –

    Optional list of Tool objects (uses self.tools if not provided)
Returns:
  • list[dict[str, Any]] –

    List of message dicts in OpenAI format (ChatCompletions or Responses API)

stream_generate 

stream_generate(messages: list[Message], sequence_number: int, *, session_id: str, assistant_name: str, endpoint_name: str, turn_id: str, previous_response_id: str | None = None, tool_outputs: list[ToolOutput] | None = None, unanswered_predefined_questions: list[dict[str, Any]] | None = None) -> Generator[StreamChunk, None, None]

Stream LLM responses with tool call support.

Supports both Responses API (new OpenAI models) and ChatCompletions API (legacy/third-party).

Parameters:
  • messages (list[Message]) –

    Conversation history as typed Message objects

  • sequence_number (int) –

    Turn sequence number for conversation ordering

  • session_id (str) –

    Session identifier for logging and correlation

  • assistant_name (str) –

    Assistant display name for logging

  • endpoint_name (str) –

    LLM endpoint identifier for logging and metrics

  • turn_id (str) –

    Unique turn identifier for request/response correlation

  • previous_response_id (str | None, default: None ) –

    Provider-specific response ID for Responses API continuation (optional)

  • tool_outputs (list[ToolOutput] | None, default: None ) –

    Tool execution results to submit with this request (optional)

  • unanswered_predefined_questions (list[dict[str, Any]] | None, default: None ) –

    Not used by OpenAI provider
Yields:
  • StreamChunk –

    StreamChunk objects containing text deltas or tool call invocations

get_last_response_id 

get_last_response_id() -> str | None

Return the response ID from the last Responses API call (for conversation continuation).

get_usage_stats 

get_usage_stats() -> UsageStats | None

Return usage statistics from the last API call.

get_capabilities 

get_capabilities() -> ProviderCapabilities

Return OpenAI provider capability flags used by assistant logic/tests.

get_ui_config_schema 

get_ui_config_schema() -> dict[str, ConfigOption]

Return config schema with model-specific and provider-specific options.

Handles: - Model-specific reasoning_effort levels - Third-party OpenAI-compatible providers (Berget.ai, Scaleway)

get_current_config_values 

get_current_config_values() -> dict[str, Any]

Return current config values including resolved use_responses_api.

Overrides base implementation to return the resolved (auto-detected) value of use_responses_api rather than the config default.

set_vector_store_ids 

set_vector_store_ids(vector_store_ids: list[str]) -> None

Set vector store IDs for file_search tool.

When set, file_search tool will be included in Responses API calls with these vector store IDs.

Parameters:
  • vector_store_ids (list[str]) –

    List of OpenAI vector store IDs