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

openai_sdk_helpers/response/vector_store.py

@@ -1,8 +1,12 @@
-"""Helpers for attaching vector stores to responses."""
+"""Vector store attachment utilities for responses.
+
+This module provides functions for attaching named vector stores to response
+instances, enabling file search capabilities through the OpenAI API.
+"""
 
 from __future__ import annotations
 
-from typing import Any, Optional, Sequence
+from typing import Any, Sequence
 
 from openai import OpenAI
 
@@ -13,30 +17,39 @@ from .base import BaseResponse
 def attach_vector_store(
     response: BaseResponse[Any],
     vector_stores: str | Sequence[str],
-    api_key: Optional[str] = None,
+    api_key: str | None = None,
 ) -> list[str]:
-    """Attach vector stores to a response ``file_search`` tool.
+    """Attach named vector stores to a response's file_search tool.
+
+    Resolves vector store names to IDs via the OpenAI API and configures
+    the response's file_search tool to use them. Creates the file_search
+    tool if it doesn't exist, or updates it to include additional stores.
 
     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``.
+    response : BaseResponse[Any]
+        Response instance whose tool configuration will be updated.
+    vector_stores : str or Sequence[str]
+        Single vector store name or sequence of names to attach.
+    api_key : str or None, default None
+        API key for OpenAI client. If None, uses the response's client.
 
     Returns
     -------
     list[str]
-        Ordered list of vector store IDs applied to the ``file_search`` tool.
+        Ordered list of vector store IDs attached to the file_search tool.
 
     Raises
     ------
     ValueError
-        If a vector store cannot be resolved or no API key is available when
-        required.
+        If a vector store name cannot be resolved to an ID.
+        If no API key is available and the response has no client.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.response import attach_vector_store
+    >>> ids = attach_vector_store(response, "knowledge_base")
+    >>> ids = attach_vector_store(response, ["docs", "kb"], api_key="sk-...")
     """
     requested_stores = ensure_list(vector_stores)
 

openai_sdk_helpers/retry.py

@@ -0,0 +1,175 @@
+"""Retry decorators with exponential backoff for API operations.
+
+Provides decorators for retrying async and sync functions with
+exponential backoff and jitter when rate limiting or transient
+errors occur.
+"""
+
+import asyncio
+import logging
+import random
+import time
+from functools import wraps
+from typing import Any, Callable, ParamSpec, TypeVar
+
+from openai import APIError, RateLimitError
+
+from openai_sdk_helpers.errors import AsyncExecutionError
+from openai_sdk_helpers.utils.core import log
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+# Default retry configuration constants
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BASE_DELAY = 1.0
+DEFAULT_MAX_DELAY = 60.0
+
+# HTTP status codes for transient errors
+TRANSIENT_HTTP_STATUS_CODES = frozenset({408, 429, 500, 502, 503})
+
+
+def with_exponential_backoff(
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    base_delay: float = DEFAULT_BASE_DELAY,
+    max_delay: float = DEFAULT_MAX_DELAY,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorate functions with exponential backoff on transient errors.
+
+    Retries on RateLimitError or transient API errors (5xx, 408, 429).
+    Uses exponential backoff with jitter to avoid thundering herd.
+
+    Parameters
+    ----------
+    max_retries : int
+        Maximum number of retry attempts (total attempts = max_retries + 1).
+        Default is 3.
+    base_delay : float
+        Initial delay in seconds before first retry. Default is 1.0.
+    max_delay : float
+        Maximum delay in seconds between retries. Default is 60.0.
+
+    Returns
+    -------
+    Callable
+        Decorator function.
+
+    Examples
+    --------
+    >>> @with_exponential_backoff(max_retries=3, base_delay=1.0)
+    ... def call_api(query: str) -> str:
+    ...     # API call that may fail with rate limiting
+    ...     return client.call(query)
+    """
+
+    def decorator(func: Callable[P, T]) -> Callable[P, T]:
+        """Apply retry logic to function."""
+        if asyncio.iscoroutinefunction(func):
+
+            @wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+                """Async wrapper with retry logic."""
+                last_exc: Exception | None = None
+                for attempt in range(max_retries + 1):
+                    try:
+                        return await func(*args, **kwargs)
+                    except RateLimitError as exc:
+                        last_exc = exc
+                        if attempt >= max_retries:
+                            raise
+                        delay = min(
+                            base_delay * (2**attempt) + random.uniform(0, 1),
+                            max_delay,
+                        )
+                        log(
+                            f"Rate limited on {func.__name__}, retrying in "
+                            f"{delay:.2f}s (attempt {attempt + 1}/{max_retries + 1})",
+                            level=logging.WARNING,
+                        )
+                        await asyncio.sleep(delay)
+                    except APIError as exc:
+                        last_exc = exc
+                        status_code: int | None = getattr(exc, "status_code", None)
+                        # Only retry on transient errors
+                        if (
+                            not status_code
+                            or status_code not in TRANSIENT_HTTP_STATUS_CODES
+                        ):
+                            raise
+                        if attempt >= max_retries:
+                            raise
+                        delay = min(
+                            base_delay * (2**attempt),
+                            max_delay,
+                        )
+                        log(
+                            f"Transient API error on {func.__name__}: "
+                            f"{status_code}, retrying in {delay:.2f}s "
+                            f"(attempt {attempt + 1}/{max_retries + 1})",
+                            level=logging.WARNING,
+                        )
+                        await asyncio.sleep(delay)
+
+                # Should never reach here, but handle edge case
+                if last_exc:
+                    raise last_exc
+                raise AsyncExecutionError(
+                    f"Unexpected state in {func.__name__} after retries"
+                )
+
+            return async_wrapper  # type: ignore
+
+        @wraps(func)
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            """Sync wrapper with retry logic."""
+            last_exc: Exception | None = None
+            for attempt in range(max_retries + 1):
+                try:
+                    return func(*args, **kwargs)
+                except RateLimitError as exc:
+                    last_exc = exc
+                    if attempt >= max_retries:
+                        raise
+                    delay = min(
+                        base_delay * (2**attempt) + random.uniform(0, 1),
+                        max_delay,
+                    )
+                    log(
+                        f"Rate limited on {func.__name__}, retrying in "
+                        f"{delay:.2f}s (attempt {attempt + 1}/{max_retries + 1})",
+                        level=logging.WARNING,
+                    )
+                    time.sleep(delay)
+                except APIError as exc:
+                    last_exc = exc
+                    status_code: int | None = getattr(exc, "status_code", None)
+                    # Only retry on transient errors
+                    if (
+                        not status_code
+                        or status_code not in TRANSIENT_HTTP_STATUS_CODES
+                    ):
+                        raise
+                    if attempt >= max_retries:
+                        raise
+                    delay = min(
+                        base_delay * (2**attempt),
+                        max_delay,
+                    )
+                    log(
+                        f"Transient API error on {func.__name__}: "
+                        f"{status_code}, retrying in {delay:.2f}s "
+                        f"(attempt {attempt + 1}/{max_retries + 1})",
+                        level=logging.WARNING,
+                    )
+                    time.sleep(delay)
+
+            # Should never reach here, but handle edge case
+            if last_exc:
+                raise last_exc
+            raise AsyncExecutionError(
+                f"Unexpected state in {func.__name__} after retries"
+            )
+
+        return sync_wrapper  # type: ignore
+
+    return decorator

openai_sdk_helpers/streamlit_app/__init__.py

@@ -1,6 +1,23 @@
-"""Streamlit app utilities for the config-driven chat interface."""
+"""Streamlit application utilities for configuration-driven chat interfaces.
 
-from .configuration import (
+This module provides configuration management and loading utilities for building
+Streamlit-based chat applications powered by OpenAI response handlers. It enables
+rapid deployment of conversational AI interfaces with minimal boilerplate.
+
+Classes
+-------
+StreamlitAppConfig
+    Validated configuration for Streamlit chat applications.
+
+Functions
+---------
+load_app_config
+    Load and validate configuration from a Python module.
+_load_configuration
+    Load configuration with user-friendly error handling for Streamlit UI.
+"""
+
+from .config import (
     StreamlitAppConfig,
     _load_configuration,
     load_app_config,

openai_sdk_helpers/streamlit_app/app.py

@@ -1,10 +1,15 @@
-"""Streamlit chat application driven by a developer configuration."""
+"""Configuration-driven Streamlit chat application.
+
+This module implements a complete Streamlit chat interface that loads its
+configuration from a Python module. It handles conversation state, message
+rendering, response execution, and resource cleanup.
+"""
 
 from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any
 
 import streamlit as st
 from dotenv import load_dotenv
@@ -17,21 +22,29 @@ from openai_sdk_helpers.streamlit_app import (
     _load_configuration,
 )
 from openai_sdk_helpers.structure.base import BaseStructure
-from openai_sdk_helpers.utils import ensure_list, coerce_jsonable, log
+from openai_sdk_helpers.utils import coerce_jsonable, ensure_list, log
 
 
 def _extract_assistant_text(response: BaseResponse[Any]) -> str:
-    """Return the latest assistant message as a friendly string.
+    """Extract the latest assistant message as readable text.
+
+    Searches the response's message history for the most recent assistant
+    or tool message and extracts displayable text content.
 
     Parameters
     ----------
     response : BaseResponse[Any]
-        Active response session containing message history.
+        Active response session with message history.
 
     Returns
     -------
     str
-        Concatenated assistant text, or an empty string when unavailable.
+        Concatenated assistant text, or empty string if unavailable.
+
+    Examples
+    --------
+    >>> text = _extract_assistant_text(response)
+    >>> print(text)
     """
     message = response.get_last_assistant_message() or response.get_last_tool_message()
     if message is None:
@@ -41,7 +54,7 @@ def _extract_assistant_text(response: BaseResponse[Any]) -> str:
     if content is None:
         return ""
 
-    text_parts: List[str] = []
+    text_parts: list[str] = []
     for part in ensure_list(content):
         text_value = getattr(getattr(part, "text", None), "value", None)
         if text_value:
@@ -52,19 +65,28 @@ def _extract_assistant_text(response: BaseResponse[Any]) -> str:
 
 
 def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
-    """Generate the assistant-facing summary shown in the transcript.
+    """Generate display text for the chat transcript.
+
+    Converts the response result into a human-readable format suitable
+    for display in the Streamlit chat interface. Handles structured
+    outputs, dictionaries, and raw text.
 
     Parameters
     ----------
     result : Any
-        Parsed result returned from ``BaseResponse.run_sync``.
+        Parsed result from BaseResponse.run_sync.
     response : BaseResponse[Any]
-        Response instance containing the latest assistant message.
+        Response instance containing message history.
 
     Returns
     -------
     str
         Display-ready summary text for the chat transcript.
+
+    Notes
+    -----
+    Falls back to extracting assistant text from message history if
+    the result cannot be formatted directly.
     """
     if isinstance(result, BaseStructure):
         return result.print()
@@ -79,20 +101,29 @@ def _render_summary(result: Any, response: BaseResponse[Any]) -> str:
     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.
+def _build_raw_output(result: Any, response: BaseResponse[Any]) -> dict[str, Any]:
+    """Assemble raw JSON payload for the expandable transcript section.
+
+    Creates a structured dictionary containing both the parsed result
+    and the complete conversation history for debugging and inspection.
 
     Parameters
     ----------
     result : Any
-        Parsed result returned from the response instance.
+        Parsed result from the response execution.
     response : BaseResponse[Any]
-        Response session containing message history.
+        Response session with complete message history.
 
     Returns
     -------
     dict[str, Any]
-        Mapping that includes parsed data and raw conversation messages.
+        Mapping with 'parsed' data and 'conversation' messages.
+
+    Examples
+    --------
+    >>> raw = _build_raw_output(result, response)
+    >>> raw.keys()
+    dict_keys(['parsed', 'conversation'])
     """
     return {
         "parsed": coerce_jsonable(result),
@@ -101,22 +132,31 @@ def _build_raw_output(result: Any, response: BaseResponse[Any]) -> Dict[str, Any
 
 
 def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
-    """Instantiate and cache the configured :class:`BaseResponse`.
+    """Instantiate and cache the configured BaseResponse.
+
+    Creates a new response instance from the configuration if not already
+    cached in session state. Applies vector store attachments and cleanup
+    settings based on configuration.
 
     Parameters
     ----------
     config : StreamlitAppConfig
-        Loaded configuration containing the response definition.
+        Loaded configuration with response handler definition.
 
     Returns
     -------
     BaseResponse[Any]
-        Active response instance for the current session.
+        Active response instance for the current Streamlit session.
 
     Raises
     ------
     TypeError
-        If the configured ``response`` cannot produce ``BaseResponse``.
+        If the configured response cannot produce a BaseResponse.
+
+    Notes
+    -----
+    The response instance is cached in st.session_state['response_instance']
+    to maintain conversation state across Streamlit reruns.
     """
     if "response_instance" in st.session_state:
         cached = st.session_state["response_instance"]
@@ -138,17 +178,21 @@ def _get_response_instance(config: StreamlitAppConfig) -> BaseResponse[Any]:
 
 
 def _reset_chat(close_response: bool = True) -> None:
-    """Clear the conversation and optionally close the response session.
+    """Clear conversation and optionally close the response session.
+
+    Saves the current conversation to disk, closes the response to clean
+    up resources, and clears the chat history from session state.
 
     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.
+    close_response : bool, default True
+        Whether to call close() on the cached response instance,
+        triggering resource cleanup.
+
+    Notes
+    -----
+    This function mutates st.session_state in-place, clearing the
+    chat_history and response_instance keys.
     """
     response = st.session_state.get("response_instance")
     if close_response and isinstance(response, BaseResponse):
@@ -160,12 +204,15 @@ def _reset_chat(close_response: bool = True) -> None:
 
 
 def _init_session_state() -> None:
-    """Prepare Streamlit session state containers.
+    """Initialize Streamlit session state for chat functionality.
 
-    Returns
-    -------
-    None
-        This function initializes chat-related session keys when absent.
+    Creates the chat_history list in session state if it doesn't exist,
+    enabling conversation persistence across Streamlit reruns.
+
+    Notes
+    -----
+    This function should be called early in the app lifecycle to ensure
+    session state is properly initialized before rendering chat UI.
     """
     if "chat_history" not in st.session_state:
         st.session_state["chat_history"] = []
@@ -174,10 +221,14 @@ def _init_session_state() -> None:
 def _render_chat_history() -> None:
     """Display the conversation transcript from session state.
 
-    Returns
-    -------
-    None
-        Renders chat messages in the current Streamlit session.
+    Iterates through chat_history in session state and renders each
+    message with appropriate formatting. Assistant messages include
+    an expandable raw output section.
+
+    Notes
+    -----
+    Uses Streamlit's chat_message context manager for role-based
+    message styling.
     """
     for message in st.session_state.get("chat_history", []):
         role = message.get("role", "assistant")
@@ -193,14 +244,24 @@ def _render_chat_history() -> None:
 
 
 def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
-    """Append a user prompt and stream the assistant reply into the transcript.
+    """Process user input and generate assistant response.
+
+    Appends the user message to chat history, executes the response
+    handler, and adds the assistant's reply to the conversation.
+    Handles errors gracefully by displaying them in the UI.
 
     Parameters
     ----------
     prompt : str
         User-entered text to send to the assistant.
     config : StreamlitAppConfig
-        Loaded configuration containing the response definition.
+        Loaded configuration with response handler definition.
+
+    Notes
+    -----
+    Errors during response execution are caught and displayed in the
+    chat transcript rather than crashing the application. The function
+    triggers a Streamlit rerun after successful response generation.
     """
     st.session_state["chat_history"].append({"role": "user", "content": prompt})
     try:
@@ -230,12 +291,26 @@ def _handle_user_message(prompt: str, config: StreamlitAppConfig) -> None:
 
 
 def main(config_path: Path) -> None:
-    """Run the config-driven Streamlit chat app.
+    """Run the configuration-driven Streamlit chat application.
+
+    Entry point for the Streamlit app that loads configuration, sets up
+    the UI, manages session state, and handles user interactions.
 
     Parameters
     ----------
     config_path : Path
         Filesystem location of the configuration module.
+
+    Notes
+    -----
+    This function should be called as the entry point for the Streamlit
+    application. It handles the complete application lifecycle including
+    configuration loading, UI rendering, and chat interactions.
+
+    Examples
+    --------
+    >>> from pathlib import Path
+    >>> main(Path("./my_config.py"))
     """
     config = _load_configuration(config_path)
     st.set_page_config(page_title=config.display_title, layout="wide")