openai-sdk-helpers 0.0.6__py3-none-any.whl → 0.0.8__py3-none-any.whl

openai_sdk_helpers/__init__.py

@@ -2,10 +2,23 @@
 
 from __future__ import annotations
 
-from .structure import *
+from .structure import (
+    BaseStructure,
+    SchemaOptions,
+    PlanStructure,
+    TaskStructure,
+    WebSearchStructure,
+    VectorSearchStructure,
+    PromptStructure,
+    spec_field,
+    SummaryStructure,
+    ExtendedSummaryStructure,
+    ValidationResultStructure,
+    AgentBlueprint,
+)
 from .prompt import PromptRenderer
 from .config import OpenAISettings
-from .vector_storage import *
+from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
     AgentBase,
     AgentConfig,
@@ -18,10 +31,11 @@ from .agent import (
     WebAgentSearch,
 )
 from .response import (
-    ResponseBase,
+    BaseResponse,
     ResponseMessage,
     ResponseMessages,
     ResponseToolCall,
+    attach_vector_store,
 )
 
 __all__ = [
@@ -33,10 +47,6 @@ __all__ = [
     "VectorStorage",
     "VectorStorageFileInfo",
     "VectorStorageFileStats",
-    "assistant_tool_definition",
-    "assistant_format",
-    "response_tool_definition",
-    "response_format",
     "SummaryStructure",
     "PromptStructure",
     "AgentBlueprint",
@@ -55,8 +65,9 @@ __all__ = [
     "WebSearchStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
-    "ResponseBase",
+    "BaseResponse",
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",
+    "attach_vector_store",
 ]

openai_sdk_helpers/agent/base.py

@@ -207,7 +207,7 @@ class AgentBase:
         """
         agent_config: Dict[str, Any] = {
             "name": self.agent_name,
-            "instructions": self._build_prompt_from_jinja(),
+            "instructions": self._build_prompt_from_jinja() or ".",
             "model": self.model,
         }
         if self._output_type:

openai_sdk_helpers/agent/web_search.py

@@ -311,7 +311,7 @@ class WebAgentSearch(AgentBase):
         )
         self._prompt_dir = prompt_dir
 
-    async def run_agent(self, search_query: str) -> WebSearchStructure:
+    async def run_agent_async(self, search_query: str) -> WebSearchStructure:
         """Execute the entire research workflow for ``search_query``.
 
         Parameters
@@ -358,10 +358,9 @@ class WebAgentSearch(AgentBase):
         WebSearchStructure
             Completed research output.
         """
-        return run_coroutine_agent_sync(self.run_agent(search_query))
+        return run_coroutine_agent_sync(self.run_agent_async(search_query))
 
-    @staticmethod
-    async def run_web_agent(search_query: str) -> WebSearchStructure:
+    async def run_web_agent_async(self, search_query: str) -> WebSearchStructure:
         """Return a research report for the given query using ``WebAgentSearch``.
 
         Parameters
@@ -374,7 +373,7 @@ class WebAgentSearch(AgentBase):
         WebSearchStructure
             Completed research output.
         """
-        return await WebAgentSearch().run_agent(search_query=search_query)
+        return await self.run_agent_async(search_query=search_query)
 
     @staticmethod
     def run_web_agent_sync(search_query: str) -> WebSearchStructure:
@@ -391,7 +390,7 @@ class WebAgentSearch(AgentBase):
             Completed research output.
         """
         return run_coroutine_agent_sync(
-            WebAgentSearch.run_web_agent(search_query=search_query)
+            WebAgentSearch().run_web_agent_async(search_query=search_query)
         )
 
 

openai_sdk_helpers/config.py

@@ -10,6 +10,12 @@ from dotenv import dotenv_values
 from openai import OpenAI
 from pydantic import BaseModel, ConfigDict, Field
 
+from openai_sdk_helpers.utils import (
+    coerce_dict,
+    coerce_optional_float,
+    coerce_optional_int,
+)
+
 
 class OpenAISettings(BaseModel):
     """Configuration helpers for constructing OpenAI clients.
@@ -61,6 +67,28 @@ class OpenAISettings(BaseModel):
             " provided. Defaults to ``OPENAI_MODEL``."
         ),
     )
+    timeout: Optional[float] = Field(
+        default=None,
+        description=(
+            "Request timeout in seconds applied to all OpenAI client calls."
+            " Defaults to ``OPENAI_TIMEOUT``."
+        ),
+    )
+    max_retries: Optional[int] = Field(
+        default=None,
+        description=(
+            "Maximum number of automatic retries for transient failures."
+            " Defaults to ``OPENAI_MAX_RETRIES``."
+        ),
+    )
+    extra_client_kwargs: Dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Additional keyword arguments forwarded to ``openai.OpenAI``. Use"
+            " this for less common options like ``default_headers`` or"
+            " ``http_client``."
+        ),
+    )
 
     @classmethod
     def from_env(
@@ -87,7 +115,18 @@ class OpenAISettings(BaseModel):
         else:
             env_file_values = dotenv_values()
 
-        values: Dict[str, Optional[str]] = {
+        timeout_raw = (
+            overrides.get("timeout")
+            or env_file_values.get("OPENAI_TIMEOUT")
+            or os.getenv("OPENAI_TIMEOUT")
+        )
+        max_retries_raw = (
+            overrides.get("max_retries")
+            or env_file_values.get("OPENAI_MAX_RETRIES")
+            or os.getenv("OPENAI_MAX_RETRIES")
+        )
+
+        values: Dict[str, Any] = {
             "api_key": overrides.get("api_key")
             or env_file_values.get("OPENAI_API_KEY")
             or os.getenv("OPENAI_API_KEY"),
@@ -103,6 +142,9 @@ class OpenAISettings(BaseModel):
             "default_model": overrides.get("default_model")
             or env_file_values.get("OPENAI_MODEL")
             or os.getenv("OPENAI_MODEL"),
+            "timeout": coerce_optional_float(timeout_raw),
+            "max_retries": coerce_optional_int(max_retries_raw),
+            "extra_client_kwargs": coerce_dict(overrides.get("extra_client_kwargs")),
         }
 
         settings = cls(**values)
@@ -128,7 +170,7 @@ class OpenAISettings(BaseModel):
         Keyword arguments populated with available authentication and routing
         values.
         """
-        kwargs: Dict[str, Any] = {}
+        kwargs: Dict[str, Any] = dict(self.extra_client_kwargs)
         if self.api_key:
             kwargs["api_key"] = self.api_key
         if self.org_id:
@@ -137,6 +179,10 @@ class OpenAISettings(BaseModel):
             kwargs["project"] = self.project_id
         if self.base_url:
             kwargs["base_url"] = self.base_url
+        if self.timeout is not None:
+            kwargs["timeout"] = self.timeout
+        if self.max_retries is not None:
+            kwargs["max_retries"] = self.max_retries
         return kwargs
 
     def create_client(self) -> OpenAI:

openai_sdk_helpers/response/__init__.py

@@ -2,17 +2,19 @@
 
 from __future__ import annotations
 
-from .base import ResponseBase
+from .base import BaseResponse
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_sync, run_async, run_streamed
+from .vector_store import attach_vector_store
 from .tool_call import ResponseToolCall
 
 __all__ = [
-    "ResponseBase",
+    "BaseResponse",
     "ResponseMessage",
     "ResponseMessages",
     "run_sync",
     "run_async",
     "run_streamed",
     "ResponseToolCall",
+    "attach_vector_store",
 ]

openai_sdk_helpers/response/base.py

@@ -10,11 +10,13 @@ import threading
 import uuid
 from pathlib import Path
 from typing import (
+    TYPE_CHECKING,
     Any,
     Callable,
     Generic,
     List,
     Optional,
+    Sequence,
     Tuple,
     Type,
     TypeVar,
@@ -32,16 +34,22 @@ from openai.types.responses.response_input_param import ResponseInputItemParam
 from openai.types.responses.response_input_text_param import ResponseInputTextParam
 from openai.types.responses.response_output_message import ResponseOutputMessage
 
-from .messages import ResponseMessages
+from .messages import ResponseMessage, ResponseMessages
 from ..structure import BaseStructure
 from ..utils import ensure_list, log
 
+if TYPE_CHECKING:
+    from openai_sdk_helpers.streamlit_app.configuration import StreamlitAppConfig
+
 T = TypeVar("T", bound=BaseStructure)
 ToolHandler = Callable[[ResponseFunctionToolCall], Union[str, Any]]
 ProcessContent = Callable[[str], Tuple[str, List[str]]]
 
 
-class ResponseBase(Generic[T]):
+RB = TypeVar("RB", bound="BaseResponse[BaseStructure]")
+
+
+class BaseResponse(Generic[T]):
     """Manage OpenAI interactions for structured responses.
 
     This base class handles input construction, OpenAI requests, tool calls,
@@ -55,6 +63,8 @@ class ResponseBase(Generic[T]):
         Synchronous wrapper around ``run_async``.
     run_streamed(content, attachments)
         Await ``run_async`` to mirror the agent API.
+    build_streamlit_config(...)
+        Construct a :class:`StreamlitAppConfig` using this class as the builder.
     save(filepath)
         Serialize the message history to disk.
     close()
@@ -129,6 +139,8 @@ class ResponseBase(Generic[T]):
         self._tools = tools if tools is not None else []
         self._schema = schema
         self._output_structure = output_structure
+        self._cleanup_user_vector_storage = False
+        self._cleanup_system_vector_storage = False
 
         if client is None:
             if api_key is None:
@@ -162,6 +174,7 @@ class ResponseBase(Generic[T]):
             self._system_vector_storage = self._vector_storage_cls(
                 store_name=storage_name, client=self._client, model=self._model
             )
+            self._cleanup_system_vector_storage = True
             system_vector_storage = cast(Any, self._system_vector_storage)
             for file_path, tool_type in attachments:
                 uploaded_file = system_vector_storage.upload_file(file_path=file_path)
@@ -248,6 +261,7 @@ class ResponseBase(Generic[T]):
                         client=self._client,
                         model=self._model,
                     )
+                    self._cleanup_user_vector_storage = True
                     user_vector_storage = cast(Any, self._user_vector_storage)
                     if not any(
                         tool.get("type") == "file_search" for tool in self._tools
@@ -441,6 +455,81 @@ class ResponseBase(Generic[T]):
         """
         return asyncio.run(self.run_async(content=content, attachments=attachments))
 
+    def get_last_tool_message(self) -> ResponseMessage | None:
+        """Return the most recent tool message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest tool message or ``None`` when absent.
+        """
+        return self.messages.get_last_tool_message()
+
+    def get_last_user_message(self) -> ResponseMessage | None:
+        """Return the most recent user message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest user message or ``None`` when absent.
+        """
+        return self.messages.get_last_user_message()
+
+    def get_last_assistant_message(self) -> ResponseMessage | None:
+        """Return the most recent assistant message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest assistant message or ``None`` when absent.
+        """
+        return self.messages.get_last_assistant_message()
+
+    @classmethod
+    def build_streamlit_config(
+        cls: type[RB],
+        *,
+        display_title: str = "Example copilot",
+        description: str | None = None,
+        system_vector_store: Sequence[str] | str | None = None,
+        preserve_vector_stores: bool = False,
+        model: str | None = None,
+    ) -> "StreamlitAppConfig":
+        """Construct a :class:`StreamlitAppConfig` using ``cls`` as the builder.
+
+        Parameters
+        ----------
+        display_title : str, default="Example copilot"
+            Title displayed at the top of the Streamlit page.
+        description : str or None, default=None
+            Optional short description shown beneath the title.
+        system_vector_store : Sequence[str] | str | None, default=None
+            Optional vector store names to attach as system context.
+        preserve_vector_stores : bool, default=False
+            When ``True``, skip automatic vector store cleanup on close.
+        model : str or None, default=None
+            Optional model hint for display alongside the chat interface.
+
+        Returns
+        -------
+        StreamlitAppConfig
+            Validated configuration bound to ``cls`` as the response builder.
+        """
+        from openai_sdk_helpers.streamlit_app.configuration import StreamlitAppConfig
+
+        normalized_stores = None
+        if system_vector_store is not None:
+            normalized_stores = ensure_list(system_vector_store)
+
+        return StreamlitAppConfig(
+            response=cls,
+            display_title=display_title,
+            description=description,
+            system_vector_store=normalized_stores,
+            preserve_vector_stores=preserve_vector_stores,
+            model=model,
+        )
+
     def save(self, filepath: Optional[str | Path] = None) -> None:
         """Serialize the message history to a JSON file."""
         if filepath is not None:
@@ -474,7 +563,7 @@ class ResponseBase(Generic[T]):
             f"messages={len(self.messages.messages)}, data_path={data_path}>"
         )
 
-    def __enter__(self) -> "ResponseBase[T]":
+    def __enter__(self) -> "BaseResponse[T]":
         """Enter the context manager for this response session."""
         return self
 
@@ -483,17 +572,17 @@ class ResponseBase(Generic[T]):
         self.close()
 
     def close(self) -> None:
-        """Delete remote vector stores and clean up the session."""
+        """Delete managed vector stores and clean up the session."""
         log(f"Closing session {self.uuid} for {self.__class__.__name__}")
-
+        self.save()
         try:
-            if self._user_vector_storage:
+            if self._user_vector_storage and self._cleanup_user_vector_storage:
                 self._user_vector_storage.delete()
                 log("User vector store deleted.")
         except Exception as exc:
             log(f"Error deleting user vector store: {exc}", level=logging.WARNING)
         try:
-            if self._system_vector_storage:
+            if self._system_vector_storage and self._cleanup_system_vector_storage:
                 self._system_vector_storage.delete()
                 log("System vector store deleted.")
         except Exception as exc:

openai_sdk_helpers/response/messages.py

@@ -209,3 +209,51 @@ class ResponseMessages(JSONSerializable):
         return [
             msg.to_openai_format() for msg in self.messages if msg.role != "assistant"
         ]
+
+    def _get_last_message(self, role: str) -> ResponseMessage | None:
+        """Return the most recent message for the given role.
+
+        Parameters
+        ----------
+        role : str
+            Role name to filter messages by.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest message matching ``role`` or ``None`` when absent.
+        """
+        for message in reversed(self.messages):
+            if message.role == role:
+                return message
+        return None
+
+    def get_last_assistant_message(self) -> ResponseMessage | None:
+        """Return the most recent assistant message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest assistant message or ``None`` when absent.
+        """
+        return self._get_last_message(role="assistant")
+
+    def get_last_tool_message(self) -> ResponseMessage | None:
+        """Return the most recent tool message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest tool message or ``None`` when absent.
+        """
+        return self._get_last_message(role="tool")
+
+    def get_last_user_message(self) -> ResponseMessage | None:
+        """Return the most recent user message.
+
+        Returns
+        -------
+        ResponseMessage or None
+            Latest user message or ``None`` when absent.
+        """
+        return self._get_last_message(role="user")

openai_sdk_helpers/response/runner.py

@@ -6,10 +6,10 @@ import asyncio
 
 from typing import Any, Optional, Type, TypeVar
 
-from .base import ResponseBase
+from .base import BaseResponse
 
 
-R = TypeVar("R", bound=ResponseBase[Any])
+R = TypeVar("R", bound=BaseResponse[Any])
 
 
 def run_sync(
@@ -32,7 +32,7 @@ def run_sync(
     Returns
     -------
     Any
-        Parsed response from :meth:`ResponseBase.run_response`.
+        Parsed response from :meth:`BaseResponse.run_response`.
     """
     response = response_cls(**(response_kwargs or {}))
     try:
@@ -61,7 +61,7 @@ async def run_async(
     Returns
     -------
     Any
-        Parsed response from :meth:`ResponseBase.run_response_async`.
+        Parsed response from :meth:`BaseResponse.run_response_async`.
     """
     response = response_cls(**(response_kwargs or {}))
     try:
@@ -79,7 +79,7 @@ def run_streamed(
     """Run a response workflow and return the asynchronous result.
 
     This mirrors the agent API for discoverability. Streaming responses are not
-    currently supported by :class:`ResponseBase`, so this returns the same value
+    currently supported by :class:`BaseResponse`, so this returns the same value
     as :func:`run_async`.
 
     Parameters

openai_sdk_helpers/response/tool_call.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from typing import Tuple
+import json
+import ast
 
 from openai.types.responses.response_function_tool_call_param import (
     ResponseFunctionToolCallParam,
@@ -68,3 +70,40 @@ class ResponseToolCall:
             },
         )
         return function_call, function_call_output
+
+
+def parse_tool_arguments(arguments: str) -> dict:
+    """Parse tool call arguments which may not be valid JSON.
+
+    The OpenAI API is expected to return well-formed JSON for tool arguments,
+    but minor formatting issues (such as the use of single quotes) can occur.
+    This helper first tries ``json.loads`` and falls back to
+    ``ast.literal_eval`` for simple cases.
+
+    Parameters
+    ----------
+    arguments
+        Raw argument string from the tool call.
+
+    Returns
+    -------
+    dict
+        Parsed dictionary of arguments.
+
+    Raises
+    ------
+    ValueError
+        If the arguments cannot be parsed as JSON.
+
+    Examples
+    --------
+    >>> parse_tool_arguments('{"key": "value"}')["key"]
+    'value'
+    """
+    try:
+        return json.loads(arguments)
+    except json.JSONDecodeError:
+        try:
+            return ast.literal_eval(arguments)
+        except Exception as exc:  # noqa: BLE001
+            raise ValueError(f"Invalid JSON arguments: {arguments}") from exc

openai_sdk_helpers/response/vector_store.py

@@ -0,0 +1,84 @@
+"""Helpers for attaching vector stores to responses."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence
+
+from openai import OpenAI
+
+from ..utils import ensure_list
+from .base import BaseResponse
+
+
+def attach_vector_store(
+    response: BaseResponse[Any],
+    vector_stores: str | Sequence[str],
+    api_key: Optional[str] = None,
+) -> list[str]:
+    """Attach vector stores to a response ``file_search`` tool.
+
+    Parameters
+    ----------
+    response
+        Response instance whose tool configuration is updated.
+    vector_stores
+        Single vector store name or a sequence of names to attach.
+    api_key : str, optional
+        API key used when the response does not already have a client. Default
+        ``None``.
+
+    Returns
+    -------
+    list[str]
+        Ordered list of vector store IDs applied to the ``file_search`` tool.
+
+    Raises
+    ------
+    ValueError
+        If a vector store cannot be resolved or no API key is available when
+        required.
+    """
+    requested_stores = ensure_list(vector_stores)
+
+    client = getattr(response, "_client", None)
+    if client is None:
+        if api_key is None:
+            raise ValueError(
+                "OpenAI API key is required to resolve vector store names."
+            )
+        client = OpenAI(api_key=api_key)
+
+    available_stores = client.vector_stores.list().data
+    resolved_ids: list[str] = []
+
+    for store in requested_stores:
+        match = next(
+            (vs.id for vs in available_stores if vs.name == store),
+            None,
+        )
+        if match is None:
+            raise ValueError(f"Vector store '{store}' not found.")
+        if match not in resolved_ids:
+            resolved_ids.append(match)
+
+    file_search_tool = next(
+        (tool for tool in response._tools if tool.get("type") == "file_search"),
+        None,
+    )
+
+    if file_search_tool is None:
+        response._tools.append(
+            {"type": "file_search", "vector_store_ids": resolved_ids}
+        )
+        return resolved_ids
+
+    existing_ids = ensure_list(file_search_tool.get("vector_store_ids", []))
+    combined_ids = existing_ids.copy()
+    for vector_store_id in resolved_ids:
+        if vector_store_id not in combined_ids:
+            combined_ids.append(vector_store_id)
+    file_search_tool["vector_store_ids"] = combined_ids
+    return combined_ids
+
+
+__all__ = ["attach_vector_store"]

openai_sdk_helpers/streamlit_app/__init__.py

@@ -0,0 +1,13 @@
+"""Streamlit app utilities for the config-driven chat interface."""
+
+from .configuration import (
+    StreamlitAppConfig,
+    _load_configuration,
+    load_app_config,
+)
+
+__all__ = [
+    "StreamlitAppConfig",
+    "_load_configuration",
+    "load_app_config",
+]