openai-sdk-helpers 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

openai_sdk_helpers/vector_storage/storage.py

@@ -1,501 +0,0 @@
-"""Wrapper utilities for managing OpenAI vector stores."""
-
-from __future__ import annotations
-
-import glob
-import logging
-import mimetypes
-import os
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from typing import List, Optional, Union
-
-from openai import OpenAI
-from openai.pagination import SyncPage
-from openai.types.vector_store import VectorStore
-from openai.types.vector_store_search_response import VectorStoreSearchResponse
-from tqdm import tqdm
-
-from ..utils import ensure_list, log
-from .types import VectorStorageFileInfo, VectorStorageFileStats
-
-TEXT_MIME_PREFIXES = ("text/",)
-ALLOWED_TEXT_MIME_TYPES = {
-    "text/x-c",
-    "text/x-c++",
-    "text/x-csharp",
-    "text/css",
-    "text/x-golang",
-    "text/html",
-    "text/x-java",
-    "text/javascript",
-    "application/json",
-    "text/markdown",
-    "text/x-python",
-    "text/x-script.python",
-    "text/x-ruby",
-    "application/x-sh",
-    "text/x-tex",
-    "application/typescript",
-    "text/plain",
-}
-
-
-class VectorStorage:
-    """Manage an OpenAI vector store.
-
-    Methods
-    -------
-    id()
-        Return the ID of the underlying vector store.
-    existing_files()
-        Map cached file names to their IDs.
-    upload_file(file_path, purpose, attributes, overwrite, refresh_cache)
-        Upload a single file to the vector store.
-    upload_files(file_patterns, purpose, attributes, overwrite)
-        Upload files matching glob patterns by using a thread pool.
-    delete_file(file_id)
-        Delete a specific file from the vector store.
-    delete_files(file_ids)
-        Delete multiple files from the vector store.
-    delete()
-        Delete the entire vector store and associated files.
-    search(query, top_k)
-        Perform a search within the vector store.
-    summarize(query, top_k)
-        Summarize top search results returned by the vector store.
-    """
-
-    def __init__(
-        self,
-        store_name: str,
-        client: Optional[OpenAI] = None,
-        model: Optional[str] = None,
-    ) -> None:
-        """Initialize the vector store helper.
-
-        Parameters
-        ----------
-        store_name
-            Name of the vector store to create or connect to.
-        client
-            Optional preconfigured ``OpenAI`` client. Default ``None``.
-        model
-            Embedding model identifier. Default ``None`` to read ``OPENAI_MODEL``.
-
-        Raises
-        ------
-        ValueError
-            If no API key or embedding model can be resolved.
-        RuntimeError
-            If the OpenAI client cannot be initialized.
-        """
-        if client is None:
-            api_key = os.getenv("OPENAI_API_KEY")
-            if api_key is None:
-                raise ValueError("OpenAI API key is required")
-            try:
-                self._client = OpenAI(api_key=api_key)
-            except Exception as exc:
-                raise RuntimeError("Failed to initialize OpenAI client") from exc
-        else:
-            self._client = client
-
-        self._model = model or os.getenv("OPENAI_MODEL")
-        if self._model is None:
-            raise ValueError("OpenAI model is required")
-
-        self._vector_storage = self._get_or_create_vector_storage(store_name)
-        self._existing_files: Optional[dict[str, str]] = {}
-
-    @property
-    def id(self) -> str:
-        """Return the ID of the underlying OpenAI ``VectorStore`` object.
-
-        Returns
-        -------
-        str
-            Identifier of the vector store.
-        """
-        return self._vector_storage.id
-
-    def _get_or_create_vector_storage(self, store_name: str) -> VectorStore:
-        """Retrieve an existing vector store or create one if it does not exist.
-
-        Parameters
-        ----------
-        store_name
-            Desired name of the vector store.
-
-        Returns
-        -------
-        VectorStore
-            Retrieved or newly created vector store object.
-        """
-        vector_stores = self._client.vector_stores.list().data
-        existing = next((vs for vs in vector_stores if vs.name == store_name), None)
-        return existing or self._client.vector_stores.create(name=store_name)
-
-    @property
-    def existing_files(self) -> dict[str, str]:
-        """Map file names to their IDs for files currently in the vector store.
-
-        This property lazily loads the file list from the OpenAI API on first
-        access and caches it. The cache can be refreshed by calling
-        ``_load_existing_files`` or by setting ``refresh_cache=True`` in
-        ``upload_file``.
-
-        Returns
-        -------
-        dict[str, str]
-            Mapping of file names to file IDs.
-        """
-        if self._existing_files is None:
-            try:
-                files = self._client.vector_stores.files.list(
-                    vector_store_id=self._vector_storage.id
-                )
-                self._existing_files = {}
-                for f in files:
-                    file_name = (f.attributes or {}).get("file_name")
-                    if isinstance(file_name, str) and f.id:
-                        self._existing_files[file_name] = f.id
-
-            except Exception as exc:
-                log(f"Failed to load existing files: {exc}", level=logging.ERROR)
-                self._existing_files = {}
-        return self._existing_files
-
-    def _load_existing_files(self) -> dict[str, str]:
-        """Force a reload of the existing files from the OpenAI API.
-
-        Returns
-        -------
-        dict[str, str]
-            Updated mapping of file names to file IDs.
-        """
-        try:
-            files = self._client.vector_stores.files.list(
-                vector_store_id=self._vector_storage.id
-            )
-            result: dict[str, str] = {}
-            for f in files:
-                file_name = (f.attributes or {}).get("file_name")
-                if isinstance(file_name, str) and f.id:
-                    result[file_name] = f.id
-            return result
-        except Exception as exc:
-            log(f"Failed to load existing files: {exc}", level=logging.ERROR)
-            return {}
-
-    def upload_file(
-        self,
-        file_path: str,
-        purpose: str = "assistants",
-        attributes: Optional[dict[str, str | float | bool]] = None,
-        overwrite: bool = False,
-        refresh_cache: bool = False,
-    ) -> VectorStorageFileInfo:
-        """Upload a single file to the vector store.
-
-        Parameters
-        ----------
-        file_path
-            Local path to the file to upload.
-        purpose
-            Purpose of the file (for example ``"assistants"``). Default
-            ``"assistants"``.
-        attributes
-            Custom attributes to associate with the file. The ``file_name``
-            attribute is added automatically. Default ``None``.
-        overwrite
-            When ``True``, re-upload even if a file with the same name already
-            exists. Default ``False``.
-        refresh_cache
-            When ``True``, refresh the local cache of existing files before
-            checking for duplicates. Default ``False``.
-
-        Returns
-        -------
-        VectorStorageFileInfo
-            Information about the uploaded file, including its ID and status.
-        """
-        file_name = os.path.basename(file_path)
-        attributes = dict(attributes or {})
-        attributes["file_name"] = file_name
-
-        if refresh_cache:
-            self._existing_files = self._load_existing_files()
-
-        if not overwrite and file_name in self.existing_files:
-            return VectorStorageFileInfo(
-                name=file_name, id=self.existing_files[file_name], status="existing"
-            )
-
-        try:
-            mime_type, _ = mimetypes.guess_type(file_path)
-            mime_type = mime_type or ""
-
-            if mime_type in ALLOWED_TEXT_MIME_TYPES or mime_type.startswith(
-                TEXT_MIME_PREFIXES
-            ):
-                try:
-                    with open(file_path, "r", encoding="utf-8") as handle:
-                        content = handle.read()
-                    file_data = content.encode("utf-8")
-                except UnicodeDecodeError:
-                    with open(file_path, "r", encoding="utf-16") as handle:
-                        content = handle.read()
-                    file_data = content.encode("utf-16")
-            else:
-                with open(file_path, "rb") as handle:
-                    file_data = handle.read()
-
-            file = self._client.files.create(
-                file=(file_path, file_data), purpose=purpose  # type: ignore
-            )
-
-            self._client.vector_stores.files.create(
-                self._vector_storage.id,
-                file_id=file.id,
-                attributes=attributes,
-            )
-
-            self._client.vector_stores.files.poll(
-                file.id, vector_store_id=self._vector_storage.id
-            )
-
-            self.existing_files[file_name] = file.id
-
-            return VectorStorageFileInfo(name=file_name, id=file.id, status="success")
-        except Exception as exc:
-            log(f"Error uploading {file_name}: {str(exc)}", level=logging.ERROR)
-            return VectorStorageFileInfo(
-                name=file_name, id="", status="error", error=str(exc)
-            )
-
-    def upload_files(
-        self,
-        file_patterns: Union[str, List[str]],
-        purpose: str = "assistants",
-        attributes: Optional[dict[str, str | float | bool]] = None,
-        overwrite: bool = False,
-    ) -> VectorStorageFileStats:
-        """Upload files matching glob patterns to the vector store using a thread pool.
-
-        Parameters
-        ----------
-        file_patterns
-            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
-            When ``True``, re-upload files even if files with the same name
-            already exist. Default ``False``.
-
-        Returns
-        -------
-        VectorStorageFileStats
-            Aggregated statistics describing the upload results.
-        """
-        file_patterns = ensure_list(file_patterns)
-
-        all_paths = set()
-        for pattern in file_patterns:
-            all_paths.update(glob.glob(pattern, recursive=True))
-        if not all_paths:
-            log("No files to upload.", level=logging.INFO)
-            return VectorStorageFileStats(total=0)
-
-        if not overwrite:
-            existing_files = self.existing_files
-            all_paths = [
-                f for f in all_paths if os.path.basename(f) not in existing_files
-            ]
-
-        if not all_paths:
-            log("No new files to upload.", level=logging.INFO)
-            return VectorStorageFileStats()
-
-        stats = VectorStorageFileStats(total=len(all_paths))
-
-        with ThreadPoolExecutor(max_workers=10) as executor:
-            futures = {
-                executor.submit(
-                    self.upload_file,
-                    path,
-                    purpose,
-                    attributes,
-                    overwrite,
-                    False,
-                ): path
-                for path in all_paths
-            }
-
-            for future in tqdm(as_completed(futures), total=len(futures)):
-                result = future.result()
-                if result.status in {"success", "existing"}:
-                    stats.success += 1
-                    if result.status == "success":
-                        self.existing_files[result.name] = result.id
-                else:
-                    stats.fail += 1
-                    stats.errors.append(result)
-
-        return stats
-
-    def delete_file(self, file_id: str) -> VectorStorageFileInfo:
-        """Delete a specific file from the vector store.
-
-        Parameters
-        ----------
-        file_id
-            Identifier of the file to delete.
-
-        Returns
-        -------
-        VectorStorageFileInfo
-            Information about the deletion operation with status
-            ``"success"`` or ``"failed"``.
-        """
-        try:
-            self._client.vector_stores.files.delete(
-                vector_store_id=self._vector_storage.id, file_id=file_id
-            )
-
-            to_remove = [k for k, v in self.existing_files.items() if v == file_id]
-            for key in to_remove:
-                del self.existing_files[key]
-
-            return VectorStorageFileInfo(
-                name=to_remove[0] if to_remove else "", id=file_id, status="success"
-            )
-        except Exception as exc:
-            log(f"Error deleting file {file_id}: {str(exc)}", level=logging.ERROR)
-            return VectorStorageFileInfo(
-                name="", id=file_id, status="failed", error=str(exc)
-            )
-
-    def delete_files(self, file_ids: List[str]) -> VectorStorageFileStats:
-        """Delete multiple files from the vector store using a thread pool.
-
-        Parameters
-        ----------
-        file_ids
-            List of file IDs to delete.
-
-        Returns
-        -------
-        VectorStorageFileStats
-            Aggregated statistics describing the deletion results.
-        """
-        total_files = len(file_ids)
-        log(f"{total_files} files to delete...")
-        stats = VectorStorageFileStats(total=total_files)
-        with ThreadPoolExecutor(max_workers=10) as executor:
-            futures = {
-                executor.submit(self.delete_file, file_id): file_id
-                for file_id in file_ids
-            }
-
-            for future in tqdm(as_completed(futures), total=len(futures)):
-                result = future.result()
-                if result.status == "success":
-                    stats.success += 1
-                else:
-                    stats.fail += 1
-                    stats.errors.append(result)
-
-        return stats
-
-    def delete(self) -> None:
-        """Delete the entire vector store and all associated files.
-
-        This operation is irreversible. It first attempts to delete each file
-        individually from the store (and updates the local cache) before
-        deleting the store itself.
-
-        Returns
-        -------
-        None
-        """
-        try:
-            existing_files = list(self.existing_files.items())
-            for file_name, file_id in existing_files:
-                log(f"Deleting file {file_id} ({file_name}) from vector store")
-                self.delete_file(file_id)
-
-            self._client.vector_stores.delete(self._vector_storage.id)
-            self._existing_files = None  # clear cache
-            log(f"Vector store '{self._vector_storage.name}' deleted successfully.")
-
-        except Exception as exc:
-            log(
-                f"Error deleting vector store '{self._vector_storage.name}': {str(exc)}",
-                level=logging.ERROR,
-            )
-
-    def search(
-        self, query: str, top_k: int = 5
-    ) -> Optional[SyncPage[VectorStoreSearchResponse]]:
-        """Perform a search within the vector store.
-
-        Parameters
-        ----------
-        query
-            Search query string.
-        top_k
-            Maximum number of results to return. Default ``5``.
-
-        Returns
-        -------
-        Optional[SyncPage[VectorStoreSearchResponse]]
-            Page of search results from the OpenAI API, or ``None`` if an
-            error occurs.
-        """
-        try:
-            response = self._client.vector_stores.search(
-                vector_store_id=self._vector_storage.id,
-                query=query,
-                max_num_results=top_k,
-            )
-            return response
-        except Exception as exc:
-            log(f"Error searching vector store: {str(exc)}", level=logging.ERROR)
-            return None
-
-    def summarize(self, query: str, top_k: int = 15) -> Optional[str]:
-        """Perform a semantic search and summarize results by topic.
-
-        Parameters
-        ----------
-        query
-            Search query string used for summarization.
-        top_k
-            Number of top search results to retrieve and summarize. Default ``15``.
-
-        Returns
-        -------
-        Optional[str]
-            Summary generated by the OpenAI model or ``None`` when no results
-            are available or an error occurs.
-
-        Raises
-        ------
-        RuntimeError
-            If no summarizer is configured for this core helper.
-        """
-        response = self.search(query, top_k=top_k)
-        if not response or not response.data:
-            log("No search results to summarize.", level=logging.WARNING)
-            return None
-
-        raise RuntimeError(
-            "Summarizer is application-specific; override this method in an "
-            "application wrapper."
-        )
-
-
-__all__ = ["VectorStorage"]

openai_sdk_helpers/vector_storage/types.py

@@ -1,58 +0,0 @@
-"""Type definitions for vector storage."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import List, Optional
-
-
-@dataclass
-class VectorStorageFileInfo:
-    """Information about a file stored in a vector store.
-
-    Attributes
-    ----------
-    name : str
-        File name associated with the vector store item.
-    id : str
-        Unique identifier of the file in the vector store.
-    status : str
-        Outcome of the operation (for example ``"success"`` or ``"error"``).
-    error : str, optional
-        Error message when the operation fails. Default ``None``.
-
-    Methods
-    -------
-    None
-    """
-
-    name: str
-    id: str
-    status: str
-    error: Optional[str] = None
-
-
-@dataclass
-class VectorStorageFileStats:
-    """Aggregate statistics about batch file operations.
-
-    Attributes
-    ----------
-    total : int
-        Total number of files processed.
-    success : int
-        Number of files successfully handled.
-    fail : int
-        Number of files that failed to process.
-    errors : list[VectorStorageFileInfo]
-        Details for each failed file.
-
-    Methods
-    -------
-    None
-    """
-
-    total: int = 0
-    success: int = 0
-    fail: int = 0
-    errors: List[VectorStorageFileInfo] = field(default_factory=list)

openai_sdk_helpers-0.0.2.dist-info/RECORD

@@ -1,40 +0,0 @@
-openai_sdk_helpers/__init__.py,sha256=P4hUQXU7bfrltlPLQPw4iEv6tGw3qaVX6xSMuQs0BO0,779
-openai_sdk_helpers/config.py,sha256=O3MF2qypWWV9-zfmW3IXBWtud7YRojQDUhJVg9X49BE,4440
-openai_sdk_helpers/environment.py,sha256=t_AFP6OXjRBoIQVZdgjqZzcUWB-FDeYn4KzKn5FgrnY,693
-openai_sdk_helpers/agent/__init__.py,sha256=Nje9voDPuiYZfMekfCKUpuwKOXfH_zIkLHLsQVZ_juo,543
-openai_sdk_helpers/agent/base.py,sha256=aJ7ZN0IBcPP7_-Me-4GKz9VSx5ytpYQPpyTBBydFbFA,12729
-openai_sdk_helpers/agent/config.py,sha256=N7tzmwc5s6mpiTgF7b7tTsJCPOUycUwDNy1TcsQrZw0,1925
-openai_sdk_helpers/agent/project_manager.py,sha256=rKkIu-wG5GMbOoVg5zls6gf4DwSBdAKEyp_XL1i44iw,13529
-openai_sdk_helpers/agent/runner.py,sha256=cfgjgLZQYINK2WRMP7f-J22zz961i_woFZG2Zn-dW1g,3081
-openai_sdk_helpers/agent/utils.py,sha256=G7LR7koisYmpw0it-uEIEhxbif_GaFRUb6bALvIGNJY,1067
-openai_sdk_helpers/agent/vector_search.py,sha256=qV8Of37aBc7K8VvC0mJRegKMiner7OUq7SH6jtwM4Ms,12876
-openai_sdk_helpers/agent/web_search.py,sha256=ksjGH5VTr65WQPMaB-4RghleHtLey1xBv6YjG_jGpqM,12192
-openai_sdk_helpers/enums/__init__.py,sha256=HhzM9YVDqPijpnKzA-qnzbX62104FrGDcnN-cEYMD_w,149
-openai_sdk_helpers/enums/base.py,sha256=NGpnCYxS-6gsk-03zksu2m4tM8pGPQeAgM6YRcm159s,423
-openai_sdk_helpers/prompt/__init__.py,sha256=Pio9s99ej0ior5gKr8m-hSUgqkBOgFdNu1xofvjPEf8,2275
-openai_sdk_helpers/response/__init__.py,sha256=Jujf4pD9ilLoiTev07hgzNqiWibd6L_7ZkBCt3addyw,360
-openai_sdk_helpers/response/base.py,sha256=Yw6y2mZaH7eF0efyZSMU4cituOmIzKAWeLB9FsVj0gg,18561
-openai_sdk_helpers/response/messages.py,sha256=Ot432B9qbbvinGG0aO6mWYeeEUSVqmLiNlvulKbUlZQ,6487
-openai_sdk_helpers/response/runner.py,sha256=8OuTxww-GZoJiv6RmjGvavLmmTivXKxkmsx8mSlwhxQ,988
-openai_sdk_helpers/response/tool_call.py,sha256=kYUfkjmkLbEJun_QByMuAvYjdixwoRAjHNy2Sk_riXA,1937
-openai_sdk_helpers/structure/__init__.py,sha256=SNKpaZ8P9aIZTrBdss2q3r3ZNd74jDCeBMOoS3RJkms,1573
-openai_sdk_helpers/structure/base.py,sha256=3UNKeoc7Tm_4vVYdlYuBuizWqKeBa9rQYnzLQcfvx1g,18607
-openai_sdk_helpers/structure/prompt.py,sha256=Yovho9WA1AZP1FhKBieBpVThrUn62g4k40mxNrBoY9s,582
-openai_sdk_helpers/structure/responses.py,sha256=2Tp_EKmsXoyJolxxsVHIZ3NkPRchONFNbzhEHSXjOww,4188
-openai_sdk_helpers/structure/summary.py,sha256=zYRKuBjZHz0GvLRofvJdfD9u101xKgVhFc5CZIlscUE,1682
-openai_sdk_helpers/structure/vector_search.py,sha256=b8h2-8kkSc63upGpexLvztqadmlsXulG0MbrtfP-Jvw,2254
-openai_sdk_helpers/structure/web_search.py,sha256=XGJS5S-a0t62k7y8r65JzCEdIQh_5dr10EPT-k134Ys,1371
-openai_sdk_helpers/structure/plan/__init__.py,sha256=fPGw7xBDVGoqH9x_5Qsu6HeqzY4YZC59e0plEg40DBo,271
-openai_sdk_helpers/structure/plan/enum.py,sha256=Ufdhvt-xOkEV5MD3kE60L66NZtGV1bg26opdm-KKV_Y,1076
-openai_sdk_helpers/structure/plan/plan.py,sha256=M3PRzoK2n-wHw9mjy2dEAdRVG2N7gv_fezdo6QuPFko,2226
-openai_sdk_helpers/structure/plan/task.py,sha256=GvUtruRycxKVmYbJrYY07KseuMeqFsRvQ-_55egsRB8,3501
-openai_sdk_helpers/utils/__init__.py,sha256=jaItJ51pCLNGHzG3C2H0sPF1cV1h2BfXYqzGRUH1bO0,294
-openai_sdk_helpers/utils/core.py,sha256=rYlfz-F9Ms_eppF2ttCJBpUKoNN8caZPX7iZRJ1uo5Q,5567
-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/types.py,sha256=9u5oBxKTDf_ljvbWhp1dWVW1zrlVwLd4OpikygvlKJI,1298
-openai_sdk_helpers-0.0.2.dist-info/METADATA,sha256=Z5TSH1q-PH8cMb5vZtzWRnKFxgc8YcKAgEJzQEpph7w,4075
-openai_sdk_helpers-0.0.2.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.0.2.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.0.2.dist-info/RECORD,,