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

openai_sdk_helpers/streamlit_app/app.py

@@ -0,0 +1,270 @@
+"""Streamlit chat application driven by a developer configuration."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List
+
+import streamlit as st
+from dotenv import load_dotenv
+
+load_dotenv()
+
+from openai_sdk_helpers.response import BaseResponse, attach_vector_store
+from openai_sdk_helpers.streamlit_app import (
+    StreamlitAppConfig,
+    _load_configuration,
+)
+from openai_sdk_helpers.structure.base import BaseStructure
+from openai_sdk_helpers.utils import ensure_list, coerce_jsonable, log
+
+
+def _extract_assistant_text(response: BaseResponse[Any]) -> str:
+    """Return the latest assistant message as a friendly string.
+
+    Parameters
+    ----------
+    response : BaseResponse[Any]
+        Active response session containing message history.
+
+    Returns
+    -------
+    str
+        Concatenated assistant text, or an empty string when unavailable.
+    """
+    message = response.get_last_assistant_message() or response.get_last_tool_message()
+    if message is None:
+        return ""
+
+    content = getattr(message.content, "content", None)
+    if content is None:
+        return ""
+
+    text_parts: List[str] = []
+    for part in ensure_list(content):
+        text_value = getattr(getattr(part, "text", None), "value", None)
+        if text_value:
+            text_parts.append(text_value)
+    if text_parts:
+        return "\n\n".join(text_parts)
+    return ""
+
+
+def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
+    """Generate the assistant-facing summary shown in the transcript.
+
+    Parameters
+    ----------
+    result : Any
+        Parsed result returned from ``BaseResponse.run_sync``.
+    response : BaseResponse[Any]
+        Response instance containing the latest assistant message.
+
+    Returns
+    -------
+    str
+        Display-ready summary text for the chat transcript.
+    """
+    if isinstance(result, BaseStructure):
+        return result.print()
+    if isinstance(result, dict):
+        return json.dumps(result, indent=2)
+    if result:
+        return str(result)
+
+    fallback_text = _extract_assistant_text(response)
+    if fallback_text:
+        return fallback_text
+    return "No response returned."
+
+
+def _build_raw_output(result: Any, response: BaseResponse[Any]) -> Dict[str, Any]:
+    """Assemble the raw payload shown under the expandable transcript section.
+
+    Parameters
+    ----------
+    result : Any
+        Parsed result returned from the response instance.
+    response : BaseResponse[Any]
+        Response session containing message history.
+
+    Returns
+    -------
+    dict[str, Any]
+        Mapping that includes parsed data and raw conversation messages.
+    """
+    return {
+        "parsed": coerce_jsonable(result),
+        "conversation": response.messages.to_json(),
+    }
+
+
+def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
+    """Instantiate and cache the configured :class:`BaseResponse`.
+
+    Parameters
+    ----------
+    config : StreamlitAppConfig
+        Loaded configuration containing the response definition.
+
+    Returns
+    -------
+    BaseResponse[Any]
+        Active response instance for the current session.
+
+    Raises
+    ------
+    TypeError
+        If the configured ``response`` cannot produce ``BaseResponse``.
+    """
+    if "response_instance" in st.session_state:
+        cached = st.session_state["response_instance"]
+        if isinstance(cached, BaseResponse):
+            return cached
+
+    response = config.create_response()
+
+    if config.preserve_vector_stores:
+        setattr(response, "_cleanup_system_vector_storage", False)
+        setattr(response, "_cleanup_user_vector_storage", False)
+
+    vector_stores = config.normalized_vector_stores()
+    if vector_stores:
+        attach_vector_store(response=response, vector_stores=vector_stores)
+
+    st.session_state["response_instance"] = response
+    return response
+
+
+def _reset_chat(close_response: bool = True) -> None:
+    """Clear the conversation and optionally close the response session.
+
+    Parameters
+    ----------
+    close_response : bool, default=True
+        Whether to call ``close`` on the cached response instance.
+
+    Returns
+    -------
+    None
+        This function mutates ``st.session_state`` in-place.
+    """
+    response = st.session_state.get("response_instance")
+    if close_response and isinstance(response, BaseResponse):
+        filepath = f"./data/{response.name}.{response.uuid}.json"
+        response.save(filepath)
+        response.close()
+    st.session_state["chat_history"] = []
+    st.session_state.pop("response_instance", None)
+
+
+def _init_session_state() -> None:
+    """Prepare Streamlit session state containers.
+
+    Returns
+    -------
+    None
+        This function initializes chat-related session keys when absent.
+    """
+    if "chat_history" not in st.session_state:
+        st.session_state["chat_history"] = []
+
+
+def _render_chat_history() -> None:
+    """Display the conversation transcript from session state.
+
+    Returns
+    -------
+    None
+        Renders chat messages in the current Streamlit session.
+    """
+    for message in st.session_state.get("chat_history", []):
+        role = message.get("role", "assistant")
+        with st.chat_message(role):
+            if role == "assistant":
+                st.markdown(message.get("summary", ""))
+                raw_output = message.get("raw")
+                if raw_output is not None:
+                    with st.expander("Raw output", expanded=False):
+                        st.json(raw_output)
+            else:
+                st.markdown(message.get("content", ""))
+
+
+def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
+    """Append a user prompt and stream the assistant reply into the transcript.
+
+    Parameters
+    ----------
+    prompt : str
+        User-entered text to send to the assistant.
+    config : StreamlitAppConfig
+        Loaded configuration containing the response definition.
+    """
+    st.session_state["chat_history"].append({"role": "user", "content": prompt})
+    try:
+        response = _get_response_instance(config)
+    except Exception as exc:  # pragma: no cover - surfaced in UI
+        st.error(f"Failed to start response session: {exc}")
+        return
+
+    try:
+        with st.spinner("Thinking..."):
+            result = response.run_sync(content=prompt)
+        summary = _render_summary(result, response)
+        raw_output = _build_raw_output(result, response)
+        st.session_state["chat_history"].append(
+            {"role": "assistant", "summary": summary, "raw": raw_output}
+        )
+        st.rerun()
+    except Exception as exc:  # pragma: no cover - surfaced in UI
+        st.session_state["chat_history"].append(
+            {
+                "role": "assistant",
+                "summary": f"Encountered an error: {exc}",
+                "raw": {"error": str(exc)},
+            }
+        )
+        st.error("Something went wrong, but your chat history is still here.")
+
+
+def main(config_path: Path) -> None:
+    """Run the config-driven Streamlit chat app.
+
+    Parameters
+    ----------
+    config_path : Path
+        Filesystem location of the configuration module.
+    """
+    config = _load_configuration(config_path)
+    st.set_page_config(page_title=config.display_title, layout="wide")
+    _init_session_state()
+
+    st.title(config.display_title)
+    if config.description:
+        st.caption(config.description)
+    if config.model:
+        st.caption(f"Model: {config.model}")
+
+    close_col, _ = st.columns([1, 5])
+    with close_col:
+        if st.button("Close chat", type="secondary"):
+            _reset_chat()
+            st.toast("Chat closed.")
+
+    _render_chat_history()
+
+    prompt = st.chat_input("Message the assistant")
+    if prompt:
+        _handle_user_message(prompt, config)
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) != 2:
+        print("Usage: python app.py <config_path>")
+        sys.exit(1)
+    config_path = Path(sys.argv[1])
+    main(config_path)

openai_sdk_helpers/streamlit_app/configuration.py

@@ -0,0 +1,324 @@
+"""Configuration loading for the example Streamlit chat app."""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+from typing import Callable, Sequence, cast
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from openai_sdk_helpers.response.base import BaseResponse
+from openai_sdk_helpers.structure.base import BaseStructure
+from openai_sdk_helpers.utils import ensure_list
+
+
+class StreamlitAppConfig(BaseModel):
+    """Validated configuration for the config-driven Streamlit application.
+
+    Methods
+    -------
+    normalized_vector_stores()
+        Return configured system vector stores as a list of names.
+    create_response()
+        Instantiate the configured ``BaseResponse``.
+    load_app_config(config_path)
+        Load, validate, and return the Streamlit application configuration.
+    """
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    response: BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None = (
+        Field(
+            default=None,
+            description=(
+                "Configured ``BaseResponse`` subclass, instance, or callable that returns"
+                " a response instance."
+            ),
+        )
+    )
+    display_title: str = Field(
+        default="Example copilot",
+        description="Title displayed at the top of the Streamlit page.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional short description shown beneath the title.",
+    )
+    system_vector_store: list[str] | None = Field(
+        default=None,
+        description=(
+            "Optional vector store names to attach as system context for "
+            "file search tools."
+        ),
+    )
+    preserve_vector_stores: bool = Field(
+        default=False,
+        description="When ``True``, skip automatic vector store cleanup on close.",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Optional model hint for display alongside the chat interface.",
+    )
+
+    @field_validator("system_vector_store", mode="before")
+    @classmethod
+    def validate_vector_store(
+        cls, value: Sequence[str] | str | None
+    ) -> list[str] | None:
+        """Normalize configured vector stores to a list of names.
+
+        Parameters
+        ----------
+        value : Sequence[str] | str | None
+            Raw value provided by the configuration module.
+
+        Returns
+        -------
+        list[str] | None
+            Normalized list of vector store names.
+
+        Raises
+        ------
+        TypeError
+            If any entry cannot be coerced to ``str``.
+        """
+        if value is None:
+            return None
+        stores = ensure_list(value)
+        if not all(isinstance(store, str) for store in stores):
+            raise ValueError("system_vector_store values must be strings.")
+        return list(stores)
+
+    @field_validator("response")
+    @classmethod
+    def validate_response(
+        cls, value: BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None
+    ) -> BaseResponse[BaseStructure] | type[BaseResponse] | Callable | None:
+        """Ensure the configuration provides a valid response source."""
+        if value is None:
+            return None
+        if isinstance(value, BaseResponse):
+            return value
+        if isinstance(value, type) and issubclass(value, BaseResponse):
+            return value
+        if callable(value):
+            return value
+        raise TypeError("response must be a BaseResponse, subclass, or callable")
+
+    def normalized_vector_stores(self) -> list[str]:
+        """Return configured system vector stores as a list.
+
+        Returns
+        -------
+        list[str]
+            Vector store names or an empty list when none are configured.
+        """
+        return list(self.system_vector_store or [])
+
+    @model_validator(mode="after")
+    def ensure_response(self) -> "StreamlitAppConfig":
+        """Validate that a response source is provided."""
+        if self.response is None:
+            raise ValueError("response must be provided.")
+        return self
+
+    def create_response(self) -> BaseResponse[BaseStructure]:
+        """Instantiate and return the configured response instance.
+
+        Returns
+        -------
+        BaseResponse[BaseStructure]
+            Active response instance.
+
+        Raises
+        ------
+        TypeError
+            If the configured ``response`` cannot produce a ``BaseResponse``.
+        """
+        return _instantiate_response(self.response)
+
+    @staticmethod
+    def load_app_config(
+        config_path: Path,
+    ) -> "StreamlitAppConfig":
+        """Load, validate, and return the Streamlit application configuration.
+
+        Parameters
+        ----------
+        config_path : Path
+            Filesystem path to the configuration module.
+
+        Returns
+        -------
+        StreamlitAppConfig
+            Validated configuration derived from ``config_path``.
+        """
+        module = _import_config_module(config_path)
+        return _extract_config(module)
+
+
+def _import_config_module(config_path: Path) -> ModuleType:
+    """Import the configuration module from ``config_path``.
+
+    Parameters
+    ----------
+    config_path : Path
+        Filesystem path pointing to the configuration module.
+
+    Returns
+    -------
+    ModuleType
+        Loaded Python module containing application configuration.
+
+    Raises
+    ------
+    FileNotFoundError
+        If ``config_path`` does not exist.
+    ImportError
+        If the module cannot be imported.
+    """
+    if not config_path.exists():
+        raise FileNotFoundError(f"Configuration file not found at '{config_path}'.")
+
+    spec = importlib.util.spec_from_file_location(config_path.stem, config_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Unable to load configuration module at '{config_path}'.")
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _extract_config(module: ModuleType) -> StreamlitAppConfig:
+    """Extract a validated :class:`StreamlitAppConfig` from ``module``.
+
+    Parameters
+    ----------
+    module : ModuleType
+        Module loaded from the configuration path.
+
+    Returns
+    -------
+    StreamlitAppConfig
+        Parsed and validated configuration instance.
+
+    Raises
+    ------
+    ValueError
+        If ``APP_CONFIG`` is missing from the module.
+    TypeError
+        If ``APP_CONFIG`` is neither a mapping nor ``StreamlitAppConfig`` instance.
+    """
+    if not hasattr(module, "APP_CONFIG"):
+        raise ValueError("APP_CONFIG must be defined in the configuration module.")
+
+    raw_config = getattr(module, "APP_CONFIG")
+    if isinstance(raw_config, StreamlitAppConfig):
+        return raw_config
+    if isinstance(raw_config, dict):
+        return _config_from_mapping(raw_config)
+    if isinstance(raw_config, BaseResponse):
+        return StreamlitAppConfig(response=raw_config)
+    if isinstance(raw_config, type) and issubclass(raw_config, BaseResponse):
+        return StreamlitAppConfig(response=raw_config)
+    if callable(raw_config):
+        return StreamlitAppConfig(response=raw_config)
+
+    raise TypeError(
+        "APP_CONFIG must be a dict, callable, BaseResponse, or StreamlitAppConfig."
+    )
+
+
+def _instantiate_response(candidate: object) -> BaseResponse[BaseStructure]:
+    """Instantiate a :class:`BaseResponse` from the provided candidate.
+
+    Parameters
+    ----------
+    candidate : object
+        Configured response source.
+
+    Returns
+    -------
+    BaseResponse[BaseStructure]
+        Active response instance.
+
+    Raises
+    ------
+    TypeError
+        If the candidate cannot produce a ``BaseResponse`` instance.
+    """
+    if isinstance(candidate, BaseResponse):
+        return candidate
+    if isinstance(candidate, type) and issubclass(candidate, BaseResponse):
+        response_cls = cast(type[BaseResponse[BaseStructure]], candidate)
+        return response_cls()  # type: ignore[call-arg]
+    if callable(candidate):
+        response_callable = cast(Callable[[], BaseResponse[BaseStructure]], candidate)
+        response = response_callable()
+        if isinstance(response, BaseResponse):
+            return response
+    raise TypeError("response must be a BaseResponse, subclass, or callable")
+
+
+def _config_from_mapping(raw_config: dict) -> StreamlitAppConfig:
+    """Build :class:`StreamlitAppConfig` from a mapping with aliases.
+
+    The mapping may provide ``build_response`` directly or a ``response`` key
+    containing a :class:`BaseResponse` instance, subclass, or callable.
+
+    Parameters
+    ----------
+    raw_config : dict
+        Developer-supplied mapping from the configuration module.
+
+    Returns
+    -------
+    StreamlitAppConfig
+        Validated configuration derived from ``raw_config``.
+    """
+    config_kwargs = dict(raw_config)
+    response_candidate = config_kwargs.pop("response", None)
+    if response_candidate is None:
+        response_candidate = config_kwargs.pop("build_response", None)
+    if response_candidate is not None:
+        config_kwargs["response"] = response_candidate
+
+    return StreamlitAppConfig(**config_kwargs)
+
+
+def load_app_config(
+    config_path: Path,
+) -> StreamlitAppConfig:
+    """Proxy to :meth:`StreamlitAppConfig.load_app_config` for compatibility."""
+    return StreamlitAppConfig.load_app_config(config_path=config_path)
+
+
+def _load_configuration(config_path: Path) -> StreamlitAppConfig:
+    """Load the Streamlit configuration and present user-friendly errors.
+
+    Parameters
+    ----------
+    config_path : Path
+        Filesystem location of the developer-authored configuration module.
+
+    Returns
+    -------
+    StreamlitAppConfig
+        Validated configuration object.
+    """
+    try:
+        return StreamlitAppConfig.load_app_config(config_path=config_path)
+    except Exception as exc:  # pragma: no cover - surfaced in UI
+        import streamlit as st  # type: ignore[import-not-found]
+
+        st.error(f"Configuration error: {exc}")
+        st.stop()
+        raise RuntimeError("Configuration loading halted.") from exc
+
+
+__all__ = [
+    "StreamlitAppConfig",
+    "load_app_config",
+    "_load_configuration",
+]

openai_sdk_helpers/streamlit_app/streamlit_web_search.py

@@ -0,0 +1,69 @@
+"""Developer configuration for the example Streamlit chat app."""
+
+import json
+from openai_sdk_helpers.agent.web_search import WebAgentSearch
+from openai_sdk_helpers.config import OpenAISettings
+from openai_sdk_helpers.response.base import BaseResponse
+from openai_sdk_helpers.structure.web_search import WebSearchStructure
+from openai_sdk_helpers.structure.prompt import PromptStructure
+from openai_sdk_helpers.utils.core import customJSONEncoder
+
+DEFAULT_MODEL = "gpt-4o-mini"
+
+
+class StreamlitWebSearch(BaseResponse[WebSearchStructure]):
+    """Response tuned for a generic chat experience with structured output.
+
+    Methods
+    -------
+    __init__()
+        Configure a general-purpose response session using OpenAI settings.
+    """
+
+    def __init__(self) -> None:
+        settings = OpenAISettings.from_env()
+        super().__init__(
+            instructions="Perform web searches and generate reports.",
+            tools=[
+                PromptStructure.response_tool_definition(
+                    tool_name="perform_search",
+                    tool_description="Tool to perform web searches and generate reports.",
+                )
+            ],
+            schema=WebSearchStructure.response_format(),
+            output_structure=WebSearchStructure,
+            tool_handlers={"perform_search": perform_search},
+            client=settings.create_client(),
+            model=settings.default_model or DEFAULT_MODEL,
+        )
+
+
+async def perform_search(tool) -> str:
+    """Perform a web search and return structured results."""
+    structured_data = PromptStructure.from_tool_arguments(tool.arguments)
+    web_result = await WebAgentSearch(default_model=DEFAULT_MODEL).run_web_agent_async(
+        structured_data.prompt
+    )
+    return json.dumps(web_result.to_json(), cls=customJSONEncoder)
+
+
+APP_CONFIG = {
+    "response": StreamlitWebSearch,
+    "display_title": "Web Search Assistant",
+    "description": "Config-driven chat experience for performing web searches.",
+}
+
+if __name__ == "__main__":
+    web_search_instance = StreamlitWebSearch()
+    import asyncio
+
+    result = asyncio.run(
+        web_search_instance.run_async("What are the 2026 advancements in AI?")
+    )
+    if result:
+        print(web_search_instance.get_last_tool_message())
+    else:
+        print("No result returned.")
+    filepath = f"./data/{web_search_instance.name}.{web_search_instance.uuid}.json"
+    web_search_instance.save(filepath)
+    web_search_instance.close()