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

openai_sdk_helpers/response/tool_call.py

@@ -1,11 +1,15 @@
-"""Tool call representation for shared responses."""
+"""Tool call representation and argument parsing.
+
+This module provides data structures and utilities for managing tool calls
+in OpenAI response conversations, including conversion to OpenAI API formats
+and robust argument parsing.
+"""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Tuple
-import json
 import ast
+import json
+from dataclasses import dataclass
 
 from openai.types.responses.response_function_tool_call_param import (
     ResponseFunctionToolCallParam,
@@ -15,23 +19,27 @@ from openai.types.responses.response_input_param import FunctionCallOutput
 
 @dataclass
 class ResponseToolCall:
-    """Container for tool call data used in a conversation.
+    """Container for tool call data in a conversation.
+
+    Stores the complete information about a tool invocation including
+    the call identifier, tool name, input arguments, and execution output.
+    Can convert to OpenAI API format for use in subsequent requests.
 
     Attributes
     ----------
     call_id : str
-        Identifier of the tool call.
+        Unique identifier for this tool call.
     name : str
-        Name of the tool invoked.
+        Name of the tool that was invoked.
     arguments : str
-        JSON string with the arguments passed to the tool.
+        JSON string containing the arguments passed to the tool.
     output : str
-        JSON string representing the result produced by the tool.
+        JSON string representing the result produced by the tool handler.
 
     Methods
     -------
     to_response_input_item_param()
-        Convert stored data into OpenAI tool call objects.
+        Convert to OpenAI API tool call format.
     """
 
     call_id: str
@@ -41,14 +49,28 @@ class ResponseToolCall:
 
     def to_response_input_item_param(
         self,
-    ) -> Tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
-        """Convert stored data into OpenAI tool call objects.
+    ) -> tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
+        """Convert stored data into OpenAI API tool call objects.
+
+        Creates the function call parameter and corresponding output object
+        required by the OpenAI API for tool interaction.
 
         Returns
         -------
         tuple[ResponseFunctionToolCallParam, FunctionCallOutput]
-            The function call object and the corresponding output object
-            suitable for inclusion in an OpenAI request.
+            A two-element tuple containing:
+            - ResponseFunctionToolCallParam: The function call representation
+            - FunctionCallOutput: The function output representation
+
+        Examples
+        --------
+        >>> tool_call = ResponseToolCall(
+        ...     call_id="call_123",
+        ...     name="search",
+        ...     arguments='{"query": "test"}',
+        ...     output='{"results": []}'
+        ... )
+        >>> func_call, func_output = tool_call.to_response_input_item_param()
         """
         from typing import cast
 
@@ -72,33 +94,39 @@ 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.
+def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
+    """Parse tool call arguments with fallback for malformed 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.
+    Attempts to parse arguments as JSON first, then falls back to
+    ast.literal_eval for cases where the OpenAI API returns minor
+    formatting issues like single quotes instead of double quotes.
+    Provides clear error context including tool name and raw payload.
 
     Parameters
     ----------
-    arguments
-        Raw argument string from the tool call.
+    arguments : str
+        Raw argument string from a tool call, expected to be JSON.
+    tool_name : str
+        Tool name for improved error context (required).
 
     Returns
     -------
     dict
-        Parsed dictionary of arguments.
+        Parsed dictionary of tool arguments.
 
     Raises
     ------
     ValueError
-        If the arguments cannot be parsed as JSON.
+        If the arguments cannot be parsed as valid JSON or Python literal.
+        Error message includes tool name and payload excerpt for debugging.
 
     Examples
     --------
-    >>> parse_tool_arguments('{"key": "value"}')["key"]
-    'value'
+    >>> parse_tool_arguments('{"key": "value"}', tool_name="search")
+    {'key': 'value'}
+
+    >>> parse_tool_arguments("{'key': 'value'}", tool_name="search")
+    {'key': 'value'}
     """
     try:
         return json.loads(arguments)
@@ -106,4 +134,11 @@ def parse_tool_arguments(arguments: str) -> dict:
         try:
             return ast.literal_eval(arguments)
         except Exception as exc:  # noqa: BLE001
-            raise ValueError(f"Invalid JSON arguments: {arguments}") from exc
+            # Build informative error message with context
+            payload_preview = (
+                arguments[:100] + "..." if len(arguments) > 100 else arguments
+            )
+            raise ValueError(
+                f"Failed to parse tool arguments for tool '{tool_name}'. "
+                f"Raw payload: {payload_preview}"
+            ) from exc

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,