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

openai_sdk_helpers/structure/base.py

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 # Standard library imports
+import ast
 import inspect
 import json
 import logging
-from abc import ABC, abstractmethod
 from enum import Enum
 from pathlib import Path
 from collections.abc import Mapping, Sequence
@@ -570,6 +570,45 @@ class BaseStructure(BaseModel):
 
         return cls(**clean_data)
 
+    @classmethod
+    def from_tool_arguments(cls: Type[T], arguments: str) -> T:
+        """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:
+            structured_data = json.loads(arguments)
+
+        except json.JSONDecodeError:
+            try:
+                structured_data = ast.literal_eval(arguments)
+            except Exception as exc:  # noqa: BLE001
+                raise ValueError(f"Invalid JSON arguments: {arguments}") from exc
+        return cls.from_raw_input(structured_data)
+
     @staticmethod
     def format_output(label: str, value: Any) -> str:
         """

openai_sdk_helpers/structure/web_search.py

@@ -44,3 +44,7 @@ class WebSearchStructure(BaseStructure):
         "web_search_results"
     )
     web_search_report: WebSearchReportStructure = spec_field("web_search_report")
+
+    def print(self) -> str:
+        """Return the markdown report."""
+        return self.web_search_report.markdown_report

openai_sdk_helpers/utils/__init__.py

@@ -2,11 +2,25 @@
 
 from __future__ import annotations
 
-from .core import JSONSerializable, check_filepath, customJSONEncoder, ensure_list, log
+from .core import (
+    JSONSerializable,
+    check_filepath,
+    coerce_jsonable,
+    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",
+    "coerce_jsonable",
     "JSONSerializable",
     "customJSONEncoder",
     "log",

openai_sdk_helpers/utils/core.py

@@ -4,11 +4,104 @@ from __future__ import annotations
 
 import json
 import logging
+import ast
 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
@@ -103,6 +196,38 @@ def _to_jsonable(value: Any) -> Any:
     return value
 
 
+def coerce_jsonable(value: Any) -> Any:
+    """Convert ``value`` into a JSON-serializable representation.
+
+    Parameters
+    ----------
+    value : Any
+        Object to convert into a JSON-friendly structure.
+
+    Returns
+    -------
+    Any
+        JSON-serializable representation of ``value``.
+    """
+    from openai_sdk_helpers.response.base import BaseResponse
+    from openai_sdk_helpers.structure.base import BaseStructure
+
+    if value is None:
+        return None
+    if isinstance(value, BaseStructure):
+        return value.model_dump()
+    if isinstance(value, BaseResponse):
+        return coerce_jsonable(value.messages.to_json())
+    if is_dataclass(value) and not isinstance(value, type):
+        return {key: coerce_jsonable(item) for key, item in asdict(value).items()}
+    coerced = _to_jsonable(value)
+    try:
+        json.dumps(coerced)
+        return coerced
+    except TypeError:
+        return str(coerced)
+
+
 class customJSONEncoder(json.JSONEncoder):
     """Encode common helper types like enums and paths.
 
@@ -202,6 +327,7 @@ def log(message: str, level: int = logging.INFO) -> None:
 __all__ = [
     "ensure_list",
     "check_filepath",
+    "coerce_jsonable",
     "JSONSerializable",
     "customJSONEncoder",
     "log",

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
@@ -199,20 +199,19 @@ class VectorStorage:
 
         Parameters
         ----------
-        file_path
+        file_path : str
             Local path to the file to upload.
-        purpose
-            Purpose of the file (for example ``"assistants"``). Default
-            ``"assistants"``.
-        attributes
+        purpose : str, default "assistants"
+            Purpose of the file (for example ``"assistants"``).
+        attributes : dict or None, default None
             Custom attributes to associate with the file. The ``file_name``
-            attribute is added automatically. Default ``None``.
-        overwrite
+            attribute is added automatically.
+        overwrite : bool, default False
             When ``True``, re-upload even if a file with the same name already
-            exists. Default ``False``.
-        refresh_cache
+            exists.
+        refresh_cache : bool, default False
             When ``True``, refresh the local cache of existing files before
-            checking for duplicates. Default ``False``.
+            checking for duplicates.
 
         Returns
         -------
@@ -284,16 +283,16 @@ class VectorStorage:
 
         Parameters
         ----------
-        file_patterns
+        file_patterns : str or list of str
             Glob pattern or list of patterns (for example
             ``'/path/to/files/**/*.txt'``).
-        purpose
-            Purpose assigned to uploaded files. Default ``"assistants"``.
-        attributes
-            Custom attributes to associate with each file. Default ``None``.
-        overwrite
+        purpose : str, default "assistants"
+            Purpose assigned to uploaded files.
+        attributes : dict or None, default None
+            Custom attributes to associate with each file.
+        overwrite : bool, default False
             When ``True``, re-upload files even if files with the same name
-            already exist. Default ``False``.
+            already exist.
 
         Returns
         -------
@@ -437,6 +436,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.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.6
+Version: 0.0.8
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -11,6 +11,7 @@ Requires-Dist: openai
 Requires-Dist: openai-agents
 Requires-Dist: pydantic<3,>=2.7
 Requires-Dist: python-dotenv
+Requires-Dist: streamlit
 Requires-Dist: typing-extensions<5,>=4.15.0
 Description-Content-Type: text/markdown
 
@@ -133,8 +134,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.8.dist-info}/RECORD

@@ -1,9 +1,9 @@
-openai_sdk_helpers/__init__.py,sha256=aqesJ3gPruETXtksvQga-iNJYBQZG6TY2YGK7iNOY6g,1324
-openai_sdk_helpers/config.py,sha256=K5bXJKtl5AOsmB2-To9XHs7m0hjuILKtTkLEWv_wKkQ,4839
+openai_sdk_helpers/__init__.py,sha256=510VjcPPtGcjEQuhkAswEi7guNFhBHBpaPuuFzAO3RA,1592
+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
-openai_sdk_helpers/agent/base.py,sha256=JHJnI7nW6e6l_FrEVoyHjFd_agE5CAM_E8rUPMrlZsk,10053
+openai_sdk_helpers/agent/base.py,sha256=P6FYmXssJduFvLaupde0H6lXIe0IJyDZGfEPOHAlMxA,10060
 openai_sdk_helpers/agent/config.py,sha256=IZDF83f_QT-1-3GdTVrn9cQCoaaH4KNcrO-ocfc-LwY,1925
 openai_sdk_helpers/agent/project_manager.py,sha256=uYCZyAG8_Snxef4mv5ax-nI_XVvRPUh43I0pY_AdiiU,16249
 openai_sdk_helpers/agent/prompt_utils.py,sha256=8uCm08YuJ94rKgBuIkio2O4EpbwDmTXNfgeddbih8JA,228
@@ -13,38 +13,43 @@ openai_sdk_helpers/agent/translator.py,sha256=Cj3eJ2IakX2UqSeDotgqpbmM89FekpYt3G
 openai_sdk_helpers/agent/utils.py,sha256=DTD5foCqGYfXf13F2bZMYIQROl7SbDSy5GDPGi0Zl-0,1089
 openai_sdk_helpers/agent/validation.py,sha256=omKfbClYdPQxxn9WKlw33s42AkudeFw54DmgGSe2UhQ,3216
 openai_sdk_helpers/agent/vector_search.py,sha256=pf_kIFl_TK4ZXvTcZzNqXxZuyq4QfF4ncDluAp4nj0c,15529
-openai_sdk_helpers/agent/web_search.py,sha256=VCsMN75XlwrifqOVMSDYxkrLJ2oJl-yInMdMtx6Puqo,12147
+openai_sdk_helpers/agent/web_search.py,sha256=mAtUoXSULn5p1Et6XrGptdZHBlBPNMXnSaTx8pSRsfs,12155
 openai_sdk_helpers/enums/__init__.py,sha256=HhzM9YVDqPijpnKzA-qnzbX62104FrGDcnN-cEYMD_w,149
 openai_sdk_helpers/enums/base.py,sha256=dBrzbIA3Ft2Jy-1PhMImEQeDwH0FXIMGHdg68DsG7WE,697
 openai_sdk_helpers/prompt/__init__.py,sha256=Pio9s99ej0ior5gKr8m-hSUgqkBOgFdNu1xofvjPEf8,2275
 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/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/__init__.py,sha256=TSTewIzMyAkR7kcxZlZ7-v3KXpDD2JBC6xG3eYa67zQ,505
+openai_sdk_helpers/response/base.py,sha256=tCWRcBhNIRUz77HWxHRdCPFuywbUKCYa7ac-TvxNWiI,22593
+openai_sdk_helpers/response/messages.py,sha256=O6c2E8Q6cm1nE4McPevvqcxa4kUFd5pL2MuUHtOVqsY,7917
+openai_sdk_helpers/response/runner.py,sha256=xCiZ1-1kGLmVuDzX31zrx7snNrbQfn7OS-BYN-XG0es,2536
+openai_sdk_helpers/response/tool_call.py,sha256=5ZZLyblNe35kRZ3_0JgGASS92nlT2xAxvCsncAss_xg,2960
+openai_sdk_helpers/response/vector_store.py,sha256=T1xiev85xv0C9f5t25ss8HUfir0c9zLPwXk3C1qAel0,2418
+openai_sdk_helpers/streamlit_app/__init__.py,sha256=RNcbMPaIERdFQ4wh_td3EjS6cJ_72eMBP-Ti7SVeiwY,261
+openai_sdk_helpers/streamlit_app/app.py,sha256=o-0Zh9lR_-ubOQX79sfA-6rFxdxhGWlRzOazmECxomE,8066
+openai_sdk_helpers/streamlit_app/configuration.py,sha256=KUo4E1yTSyuI9MV17Lw8_FP6OhEqS-zv2HdsGk9bCQA,10340
+openai_sdk_helpers/streamlit_app/streamlit_web_search.py,sha256=1eUCYFh0b_LnWb6HSBMztt1h92TF3fTW_InUNMOPkG8,2480
 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
+openai_sdk_helpers/structure/base.py,sha256=0OZao5cenz52AKoMLjLO8f_it_5Nm38FPvO8GGyMzNA,24170
 openai_sdk_helpers/structure/prompt.py,sha256=Yovho9WA1AZP1FhKBieBpVThrUn62g4k40mxNrBoY9s,582
 openai_sdk_helpers/structure/responses.py,sha256=KivhRltUlrK8ey9Tk9rDNceHb7uC2gNE38iQJXFOxug,3507
 openai_sdk_helpers/structure/summary.py,sha256=zYRKuBjZHz0GvLRofvJdfD9u101xKgVhFc5CZIlscUE,1682
 openai_sdk_helpers/structure/validation.py,sha256=IdlPb3I1PdCah7kciE8iDRZy_ltk5GSXQyRJUufz7K0,1405
 openai_sdk_helpers/structure/vector_search.py,sha256=M3TQwxOg9mJmZcLgx7UhZkclnbdcH2K_N-XxUU9Eoxo,2457
-openai_sdk_helpers/structure/web_search.py,sha256=XGJS5S-a0t62k7y8r65JzCEdIQh_5dr10EPT-k134Ys,1371
+openai_sdk_helpers/structure/web_search.py,sha256=6RA0gS8tAe_8zBMA1IS-YLNoGzLFmvS0YG0OwfUGo7Y,1496
 openai_sdk_helpers/structure/plan/__init__.py,sha256=OVTGp0MAb8RLjE7TZk5zoXjXIih7zzfwPYIyO7CCwVM,261
 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=54_AalcYtv3cgkg86yvHLe2cVuSEYizehf6arv37JJQ,507
+openai_sdk_helpers/utils/core.py,sha256=1Q8zaOkuorbj3tYcbM0iIjhURKJpD0xl6rEaXjI-080,9132
 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=alOetHIJUrZ6hjP3Q_3A-g5ROraw7FXJOWhOSdNorOA,19345
 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.8.dist-info/METADATA,sha256=OWSkOhsK10d3ko-ItS9O47OTtJDDS6QUgIGiBvXeKFg,6582
+openai_sdk_helpers-0.0.8.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.0.8.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.0.8.dist-info/RECORD,,