openai-sdk-helpers 0.0.7__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/response/__init__.py

@@ -2,14 +2,14 @@
 
 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",

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()
@@ -445,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:
@@ -478,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
 
@@ -489,7 +574,7 @@ class ResponseBase(Generic[T]):
     def close(self) -> None:
         """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 and self._cleanup_user_vector_storage:
                 self._user_vector_storage.delete()

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

@@ -7,11 +7,11 @@ from typing import Any, Optional, Sequence
 from openai import OpenAI
 
 from ..utils import ensure_list
-from .base import ResponseBase
+from .base import BaseResponse
 
 
 def attach_vector_store(
-    response: ResponseBase[Any],
+    response: BaseResponse[Any],
     vector_stores: str | Sequence[str],
     api_key: Optional[str] = None,
 ) -> list[str]:

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",
+]