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

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

@@ -5,6 +5,7 @@ from __future__ import annotations
 from .base import ResponseBase
 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__ = [
@@ -15,4 +16,5 @@ __all__ = [
     "run_async",
     "run_streamed",
     "ResponseToolCall",
+    "attach_vector_store",
 ]

openai_sdk_helpers/response/base.py

@@ -129,6 +129,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 +164,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 +251,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
@@ -483,17 +487,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__}")
 
         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/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 ResponseBase
+
+
+def attach_vector_store(
+    response: ResponseBase[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/utils/__init__.py

@@ -2,11 +2,23 @@
 
 from __future__ import annotations
 
-from .core import JSONSerializable, check_filepath, customJSONEncoder, ensure_list, log
+from .core import (
+    JSONSerializable,
+    check_filepath,
+    coerce_dict,
+    coerce_optional_float,
+    coerce_optional_int,
+    customJSONEncoder,
+    ensure_list,
+    log,
+)
 
 __all__ = [
     "ensure_list",
     "check_filepath",
+    "coerce_optional_float",
+    "coerce_optional_int",
+    "coerce_dict",
     "JSONSerializable",
     "customJSONEncoder",
     "log",

openai_sdk_helpers/utils/core.py

@@ -8,7 +8,99 @@ from dataclasses import asdict, is_dataclass
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any, Dict, Iterable, List, TypeVar
+from typing import Any, Dict, Iterable, List, Mapping, Optional, TypeVar
+
+
+def coerce_optional_float(value: Any) -> Optional[float]:
+    """Return a float when the provided value can be coerced, otherwise ``None``.
+
+    Parameters
+    ----------
+    value : Any
+        Value to convert into a float. Strings must be parseable as floats.
+
+    Returns
+    -------
+    float | None
+        Converted float value or ``None`` if the input is ``None``.
+
+    Raises
+    ------
+    ValueError
+        If a non-empty string cannot be converted to a float.
+    TypeError
+        If the value is not a float-compatible type.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (float, int)):
+        return float(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return float(value)
+        except ValueError as exc:
+            raise ValueError("timeout must be a float-compatible value") from exc
+    raise TypeError("timeout must be a float, int, str, or None")
+
+
+def coerce_optional_int(value: Any) -> Optional[int]:
+    """Return an int when the provided value can be coerced, otherwise ``None``.
+
+    Parameters
+    ----------
+    value : Any
+        Value to convert into an int. Strings must be parseable as integers.
+
+    Returns
+    -------
+    int | None
+        Converted integer value or ``None`` if the input is ``None``.
+
+    Raises
+    ------
+    ValueError
+        If a non-empty string cannot be converted to an integer.
+    TypeError
+        If the value is not an int-compatible type.
+    """
+    if value is None:
+        return None
+    if isinstance(value, int) and not isinstance(value, bool):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    if isinstance(value, str) and value.strip():
+        try:
+            return int(value)
+        except ValueError as exc:
+            raise ValueError("max_retries must be an int-compatible value") from exc
+    raise TypeError("max_retries must be an int, str, or None")
+
+
+def coerce_dict(value: Any) -> Dict[str, Any]:
+    """Return a string-keyed dictionary built from ``value`` if possible.
+
+    Parameters
+    ----------
+    value : Any
+        Mapping-like value to convert. ``None`` yields an empty dictionary.
+
+    Returns
+    -------
+    dict[str, Any]
+        Dictionary representation of ``value``.
+
+    Raises
+    ------
+    TypeError
+        If the value cannot be treated as a mapping.
+    """
+    if value is None:
+        return {}
+    if isinstance(value, Mapping):
+        return dict(value)
+    raise TypeError("extra_client_kwargs must be a mapping or None")
+
 
 T = TypeVar("T")
 _configured_logging = False

openai_sdk_helpers/vector_storage/storage.py

@@ -7,7 +7,7 @@ import logging
 import mimetypes
 import os
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import List, Optional, Union
+from typing import List, Optional, Union, cast
 
 from openai import OpenAI
 from openai.pagination import SyncPage
@@ -437,6 +437,69 @@ class VectorStorage:
                 level=logging.ERROR,
             )
 
+    def download_files(self, output_dir: str) -> VectorStorageFileStats:
+        """Download every file in the vector store to a local directory.
+
+        Parameters
+        ----------
+        output_dir
+            Destination directory where the files will be written. The
+            directory is created when it does not already exist.
+
+        Returns
+        -------
+        VectorStorageFileStats
+            Aggregated statistics describing the download results.
+        """
+        os.makedirs(output_dir, exist_ok=True)
+
+        try:
+            files = self._client.vector_stores.files.list(
+                vector_store_id=self._vector_storage.id
+            )
+            store_files = list(getattr(files, "data", files))
+        except Exception as exc:
+            log(f"Failed to list files for download: {exc}", level=logging.ERROR)
+            return VectorStorageFileStats(
+                total=0,
+                fail=1,
+                errors=[
+                    VectorStorageFileInfo(
+                        name="", id="", status="error", error=str(exc)
+                    )
+                ],
+            )
+
+        stats = VectorStorageFileStats(total=len(store_files))
+
+        for file_ref in store_files:
+            file_id = getattr(file_ref, "id", "")
+            attributes = getattr(file_ref, "attributes", {}) or {}
+            file_name = attributes.get("file_name") or file_id
+            target_path = os.path.join(output_dir, file_name)
+
+            try:
+                content = self._client.files.content(file_id=file_id)
+                if isinstance(content, bytes):
+                    data = content
+                elif hasattr(content, "read"):
+                    data = cast(bytes, content.read())
+                else:
+                    raise TypeError("Unsupported content type for file download")
+                with open(target_path, "wb") as handle:
+                    handle.write(data)
+                stats.success += 1
+            except Exception as exc:
+                log(f"Failed to download {file_id}: {exc}", level=logging.ERROR)
+                stats.fail += 1
+                stats.errors.append(
+                    VectorStorageFileInfo(
+                        name=file_name, id=file_id, status="error", error=str(exc)
+                    )
+                )
+
+        return stats
+
     def search(
         self, query: str, top_k: int = 5
     ) -> Optional[SyncPage[VectorStoreSearchResponse]]:

{openai_sdk_helpers-0.0.6.dist-info → openai_sdk_helpers-0.0.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.6
+Version: 0.0.7
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -133,8 +133,11 @@ vector_search = VectorSearch(
 ```
 
 The helper reads `OPENAI_API_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`,
-`OPENAI_BASE_URL`, and `OPENAI_MODEL` by default but supports overrides for
-custom deployments.
+`OPENAI_BASE_URL`, `OPENAI_MODEL`, `OPENAI_TIMEOUT`, and `OPENAI_MAX_RETRIES` by
+default but supports overrides for custom deployments. Pass uncommon OpenAI
+client keyword arguments (such as `default_headers`, `http_client`, or
+`base_url` proxies) through `extra_client_kwargs` when instantiating
+`OpenAISettings`.
 
 ## Development
 

{openai_sdk_helpers-0.0.6.dist-info → openai_sdk_helpers-0.0.7.dist-info}/RECORD

@@ -1,5 +1,5 @@
 openai_sdk_helpers/__init__.py,sha256=aqesJ3gPruETXtksvQga-iNJYBQZG6TY2YGK7iNOY6g,1324
-openai_sdk_helpers/config.py,sha256=K5bXJKtl5AOsmB2-To9XHs7m0hjuILKtTkLEWv_wKkQ,4839
+openai_sdk_helpers/config.py,sha256=OH--g7Xp4ftucA2C4o6FCX0M9Z15KMRpkY0lpn0mmOI,6455
 openai_sdk_helpers/environment.py,sha256=t_AFP6OXjRBoIQVZdgjqZzcUWB-FDeYn4KzKn5FgrnY,693
 openai_sdk_helpers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openai_sdk_helpers/agent/__init__.py,sha256=1sRtu_TbnKR7EstzZjoi2OUOk0xJOTn4xbo5ZeoPIhk,825
@@ -20,11 +20,12 @@ openai_sdk_helpers/prompt/__init__.py,sha256=Pio9s99ej0ior5gKr8m-hSUgqkBOgFdNu1x
 openai_sdk_helpers/prompt/summarizer.jinja,sha256=jliSetWDISbql1EkWi1RB8-L_BXUg8JMkRRsPRHuzbY,309
 openai_sdk_helpers/prompt/translator.jinja,sha256=SZhW8ipEzM-9IA4wyS_r2wIMTAclWrilmk1s46njoL0,291
 openai_sdk_helpers/prompt/validator.jinja,sha256=6t8q_IdxFd3mVBGX6SFKNOert1Wo3YpTOji2SNEbbtE,547
-openai_sdk_helpers/response/__init__.py,sha256=z1Q09r6K5IeSspdBUDHZgyx_5T6Fo6xsTQo4sK-qK_A,432
-openai_sdk_helpers/response/base.py,sha256=ivE_YT39BqclZwHJF8md_11DVyG0jACXQc1O5uDdMCE,19296
+openai_sdk_helpers/response/__init__.py,sha256=LOCBPGe--iKHHCU1WVcljXV5tLFFRdv1dTJZeip7gc8,505
+openai_sdk_helpers/response/base.py,sha256=vOibHp9xQiC4Nu-kNJ8GutRCwBPAtShgybf9_T_lHWk,19593
 openai_sdk_helpers/response/messages.py,sha256=Ot432B9qbbvinGG0aO6mWYeeEUSVqmLiNlvulKbUlZQ,6487
 openai_sdk_helpers/response/runner.py,sha256=OD-lNgpuhBULKS9-fyYAicKONdx_Tk48qGOzVBmG00s,2536
 openai_sdk_helpers/response/tool_call.py,sha256=kYUfkjmkLbEJun_QByMuAvYjdixwoRAjHNy2Sk_riXA,1937
+openai_sdk_helpers/response/vector_store.py,sha256=wCPPppzCQ-PYSS4T2QHqDUHcPMYNlQFeV-Pu33KBRy8,2418
 openai_sdk_helpers/structure/__init__.py,sha256=GBD48p3M9wnOPmEO9t9t5XuiMQedmDBClKmjDLEjcUo,1129
 openai_sdk_helpers/structure/agent_blueprint.py,sha256=opL-dER3a_f_JWC3Jx9ovRdbC4XZe9X20-o1YUq9sgw,7569
 openai_sdk_helpers/structure/base.py,sha256=FJvB-HedXG02VJEEgymMd2adcJCwugdGHidj4ne7phU,22975
@@ -38,13 +39,13 @@ openai_sdk_helpers/structure/plan/__init__.py,sha256=OVTGp0MAb8RLjE7TZk5zoXjXIih
 openai_sdk_helpers/structure/plan/enum.py,sha256=EYGdUckSUSOXQCTIbD8RhSQNylgVTVvOnb7za6fv6_A,1772
 openai_sdk_helpers/structure/plan/plan.py,sha256=33qBu-yzFEpYHVsvGiGMsdZphYpOD7eT5AjNQzt5cmo,7480
 openai_sdk_helpers/structure/plan/task.py,sha256=Qn-GXV0VuOYA-EHXSC6tQlcXObKMeV3-TQhgeepl2L8,3481
-openai_sdk_helpers/utils/__init__.py,sha256=jaItJ51pCLNGHzG3C2H0sPF1cV1h2BfXYqzGRUH1bO0,294
-openai_sdk_helpers/utils/core.py,sha256=rYlfz-F9Ms_eppF2ttCJBpUKoNN8caZPX7iZRJ1uo5Q,5567
+openai_sdk_helpers/utils/__init__.py,sha256=JRmAwQz2qE0bNhshAq5HAlXjYMyE5OqLl-vOKcD6MZY,463
+openai_sdk_helpers/utils/core.py,sha256=mKCkGE1cC06ZcOip70eiA8rJ4jaRmnGm4zJfwDPLkQM,8161
 openai_sdk_helpers/vector_storage/__init__.py,sha256=BjUueFnxmF4T6YOCra2nqa8rEAzsihEYWavkYB7S_lM,384
 openai_sdk_helpers/vector_storage/cleanup.py,sha256=6e_A9MAOKhJl_9EbRgGiB0NrrN79IwN0mMnHrwp4gd8,2964
-openai_sdk_helpers/vector_storage/storage.py,sha256=l0keUiKmQPnCl5OGCbV1Fi5hN4F6P_puW3EdAFK4uKE,16927
+openai_sdk_helpers/vector_storage/storage.py,sha256=-Yk9RwzG6ABkhH1p3Y-6tv5sGu2MdxHvwkxEtB9N9_c,19295
 openai_sdk_helpers/vector_storage/types.py,sha256=9u5oBxKTDf_ljvbWhp1dWVW1zrlVwLd4OpikygvlKJI,1298
-openai_sdk_helpers-0.0.6.dist-info/METADATA,sha256=ggBFoPInIsKSCUl_nmshg9H3UzFpS3FNG3sBCrWJaaM,6338
-openai_sdk_helpers-0.0.6.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.0.6.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.0.6.dist-info/RECORD,,
+openai_sdk_helpers-0.0.7.dist-info/METADATA,sha256=zYMBq4ke7ex0StA0Q4ddjD4GAsx9cI8oEWTXpZOV1SY,6557
+openai_sdk_helpers-0.0.7.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.0.7.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.0.7.dist-info/RECORD,,