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

openai_sdk_helpers/structure/validation.py

@@ -0,0 +1,47 @@
+"""Structures describing guardrail validation results."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .base import BaseStructure, spec_field
+
+
+class ValidationResultStructure(BaseStructure):
+    """Capture guardrail validation findings for user and agent messages.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    input_safe: bool = spec_field(
+        "input_safe",
+        allow_null=False,
+        description="Whether the user-provided input is allowed within the guardrails.",
+    )
+    output_safe: bool = spec_field(
+        "output_safe",
+        allow_null=False,
+        description="Whether the agent output adheres to the safety guardrails.",
+    )
+    violations: List[str] = spec_field(
+        "violations",
+        allow_null=False,
+        default_factory=list,
+        description="Detected policy or safety issues that require mitigation.",
+    )
+    recommended_actions: List[str] = spec_field(
+        "recommended_actions",
+        allow_null=False,
+        default_factory=list,
+        description="Steps to remediate or respond to any detected violations.",
+    )
+    sanitized_output: Optional[str] = spec_field(
+        "sanitized_output",
+        description="Optional redacted or rewritten text that fits the guardrails.",
+    )
+
+
+__all__ = ["ValidationResultStructure"]

openai_sdk_helpers/structure/vector_search.py

@@ -0,0 +1,86 @@
+"""Shared structured output models for vector search."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class VectorSearchItemStructure(BaseStructure):
+    """A single vector search to perform."""
+
+    reason: str = spec_field("reason")
+    query: str = spec_field("query")
+
+
+class VectorSearchPlanStructure(BaseStructure):
+    """Collection of vector searches required to satisfy the query."""
+
+    searches: List[VectorSearchItemStructure] = spec_field("searches")
+
+
+class VectorSearchItemResultStructure(BaseStructure):
+    """Result of a single vector search."""
+
+    texts: List[str] = spec_field("texts")
+
+
+class VectorSearchItemResultsStructure(BaseStructure):
+    """Collection of search results returned from multiple queries.
+
+    Failed searches are recorded in ``errors`` to allow callers to inspect
+    partial outcomes without losing visibility into issues.
+
+    Methods
+    -------
+    append(item)
+        Add a search result to the collection.
+    """
+
+    item_results: List[VectorSearchItemResultStructure] = spec_field(
+        "item_results", default_factory=list
+    )
+    errors: List[str] = spec_field("errors", default_factory=list)
+
+    def append(self, item: VectorSearchItemResultStructure) -> None:
+        """Add a search result to the collection.
+
+        Parameters
+        ----------
+        item : VectorSearchItemResultStructure
+            Result item to append.
+
+        Returns
+        -------
+        None
+        """
+        self.item_results.append(item)
+
+
+class VectorSearchReportStructure(BaseStructure):
+    """Structured output from the vector search writer agent."""
+
+    short_summary: str = spec_field("short_summary")
+    markdown_report: str = spec_field("markdown_report")
+    follow_up_questions: List[str] = spec_field("follow_up_questions")
+    sources: List[str] = spec_field("sources")
+
+
+class VectorSearchStructure(BaseStructure):
+    """Complete output of a vector search workflow."""
+
+    query: str = spec_field("query")
+    plan: VectorSearchPlanStructure = spec_field("plan")
+    results: VectorSearchItemResultsStructure = spec_field("results")
+    report: VectorSearchReportStructure = spec_field("report")
+
+
+__all__ = [
+    "VectorSearchReportStructure",
+    "VectorSearchItemStructure",
+    "VectorSearchItemResultStructure",
+    "VectorSearchItemResultsStructure",
+    "VectorSearchPlanStructure",
+    "VectorSearchStructure",
+]

openai_sdk_helpers/structure/web_search.py

@@ -0,0 +1,46 @@
+"""Shared structured output model for web search results."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class WebSearchReportStructure(BaseStructure):
+    """Structured output from the writer agent."""
+
+    short_summary: str = spec_field("short_summary")
+    markdown_report: str = spec_field("markdown_report")
+    follow_up_questions: List[str] = spec_field("follow_up_questions")
+    sources: List[str] = spec_field("sources")
+
+
+class WebSearchItemStructure(BaseStructure):
+    """A single web search to perform."""
+
+    reason: str = spec_field("reason")
+    query: str = spec_field("query")
+
+
+class WebSearchItemResultStructure(BaseStructure):
+    """Result of a single web search."""
+
+    text: str = spec_field("text")
+
+
+class WebSearchPlanStructure(BaseStructure):
+    """Collection of searches required to satisfy the query."""
+
+    searches: List[WebSearchItemStructure] = spec_field("searches")
+
+
+class WebSearchStructure(BaseStructure):
+    """Complete output of a web search workflow."""
+
+    query: str = spec_field("query")
+    web_search_plan: WebSearchPlanStructure = spec_field("web_search_plan")
+    web_search_results: List[WebSearchItemResultStructure] = spec_field(
+        "web_search_results"
+    )
+    web_search_report: WebSearchReportStructure = spec_field("web_search_report")

openai_sdk_helpers/utils/__init__.py

@@ -0,0 +1,25 @@
+"""Shared utility helpers for openai-sdk-helpers."""
+
+from __future__ import annotations
+
+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

@@ -0,0 +1,300 @@
+"""Core utility helpers for openai-sdk-helpers."""
+
+from __future__ import annotations
+
+import json
+import logging
+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, 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
+
+
+def ensure_list(value: Iterable[T] | T | None) -> List[T]:
+    """Normalize a single item or iterable into a list.
+
+    Parameters
+    ----------
+    value : Iterable[T] | T | None
+        Item or iterable to wrap. ``None`` yields an empty list.
+
+    Returns
+    -------
+    list[T]
+        Normalized list representation of ``value``.
+    """
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple):
+        return list(value)
+    return [value]  # type: ignore[list-item]
+
+
+def check_filepath(
+    filepath: Path | None = None, *, fullfilepath: str | None = None
+) -> Path:
+    """Ensure the parent directory for a file path exists.
+
+    Parameters
+    ----------
+    filepath : Path | None, optional
+        Path object to validate. Mutually exclusive with ``fullfilepath``.
+    fullfilepath : str | None, optional
+        String path to validate. Mutually exclusive with ``filepath``.
+
+    Returns
+    -------
+    Path
+        Path object representing the validated file path.
+
+    Raises
+    ------
+    ValueError
+        If neither ``filepath`` nor ``fullfilepath`` is provided.
+    """
+    if filepath is None and fullfilepath is None:
+        raise ValueError("filepath or fullfilepath is required.")
+    if fullfilepath is not None:
+        target = Path(fullfilepath)
+    elif filepath is not None:
+        target = Path(filepath)
+    else:
+        raise ValueError("filepath or fullfilepath is required.")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    return target
+
+
+def _to_jsonable(value: Any) -> Any:
+    """Convert common helper types to JSON-serializable forms.
+
+    Parameters
+    ----------
+    value : Any
+        Value to convert.
+
+    Returns
+    -------
+    Any
+        A JSON-safe representation of ``value``.
+    """
+    if value is None:
+        return None
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if is_dataclass(value) and not isinstance(value, type):
+        return {k: _to_jsonable(v) for k, v in asdict(value).items()}
+    if hasattr(value, "model_dump"):
+        model_dump = getattr(value, "model_dump")
+        return model_dump()
+    if isinstance(value, dict):
+        return {str(k): _to_jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set)):
+        return [_to_jsonable(v) for v in value]
+    return value
+
+
+class customJSONEncoder(json.JSONEncoder):
+    """Encode common helper types like enums and paths.
+
+    Methods
+    -------
+    default(o)
+        Return a JSON-serializable representation of ``o``.
+    """
+
+    def default(self, o: Any) -> Any:
+        """Return a JSON-serializable representation of ``o``.
+
+        Parameters
+        ----------
+        o : Any
+            Object to serialize.
+
+        Returns
+        -------
+        Any
+            JSON-safe representation of ``o``.
+        """
+        return _to_jsonable(o)
+
+
+class JSONSerializable:
+    """Mixin for classes that can be serialized to JSON.
+
+    Methods
+    -------
+    to_json()
+        Return a JSON-compatible dict representation of the instance.
+    to_json_file(filepath)
+        Write serialized JSON data to a file path.
+    """
+
+    def to_json(self) -> Dict[str, Any]:
+        """Return a JSON-compatible dict representation.
+
+        Returns
+        -------
+        dict[str, Any]
+            Mapping with only JSON-serializable values.
+        """
+        if is_dataclass(self) and not isinstance(self, type):
+            return {k: _to_jsonable(v) for k, v in asdict(self).items()}
+        if hasattr(self, "model_dump"):
+            model_dump = getattr(self, "model_dump")
+            return _to_jsonable(model_dump())
+        return _to_jsonable(self.__dict__)
+
+    def to_json_file(self, filepath: str | Path) -> str:
+        """Write serialized JSON data to a file path.
+
+        Parameters
+        ----------
+        filepath : str | Path
+            Destination file path. Parent directories are created as needed.
+
+        Returns
+        -------
+        str
+            String representation of the file path written.
+        """
+        target = Path(filepath)
+        check_filepath(fullfilepath=str(target))
+        with open(target, "w", encoding="utf-8") as handle:
+            json.dump(
+                self.to_json(),
+                handle,
+                indent=2,
+                ensure_ascii=False,
+                cls=customJSONEncoder,
+            )
+        return str(target)
+
+
+def log(message: str, level: int = logging.INFO) -> None:
+    """Log a message with a basic configuration.
+
+    Parameters
+    ----------
+    message : str
+        Message to emit.
+    level : int, optional
+        Logging level, by default ``logging.INFO``.
+    """
+    global _configured_logging
+    if not _configured_logging:
+        logging.basicConfig(
+            level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+        )
+        _configured_logging = True
+    logging.log(level, message)
+
+
+__all__ = [
+    "ensure_list",
+    "check_filepath",
+    "JSONSerializable",
+    "customJSONEncoder",
+    "log",
+]

openai_sdk_helpers/vector_storage/__init__.py

@@ -0,0 +1,15 @@
+"""Vector store helpers."""
+
+from __future__ import annotations
+
+from .cleanup import _delete_all_files, _delete_all_vector_stores
+from .storage import VectorStorage
+from .types import VectorStorageFileInfo, VectorStorageFileStats
+
+__all__ = [
+    "VectorStorage",
+    "VectorStorageFileInfo",
+    "VectorStorageFileStats",
+    "_delete_all_vector_stores",
+    "_delete_all_files",
+]

openai_sdk_helpers/vector_storage/cleanup.py

@@ -0,0 +1,91 @@
+"""Cleanup helpers for vector stores."""
+
+from __future__ import annotations
+
+import logging
+
+from openai import OpenAI
+
+from ..utils import log
+
+
+def _delete_all_vector_stores() -> None:
+    """Delete all vector stores and clean up any orphaned files.
+
+    This utility iterates over every vector store owned by the account,
+    deleting each one after removing all of its files. Any standalone files that
+    remain after the stores are deleted are also removed.
+
+    Returns
+    -------
+    None
+    """
+    try:
+        client = OpenAI()
+        stores = client.vector_stores.list().data
+        log(f"Found {len(stores)} vector stores.")
+
+        attached_file_ids = set()
+
+        for store in stores:
+            log(f"Deleting vector store: {store.name} (ID: {store.id})")
+
+            files = client.vector_stores.files.list(vector_store_id=store.id).data
+            for file in files:
+                attached_file_ids.add(file.id)
+                log(f" - Deleting file {file.id}")
+                try:
+                    client.vector_stores.files.delete(
+                        vector_store_id=store.id, file_id=file.id
+                    )
+                except Exception as file_err:
+                    log(
+                        f"Failed to delete file {file.id}: {file_err}",
+                        level=logging.WARNING,
+                    )
+
+            try:
+                client.vector_stores.delete(store.id)
+                log(f"Vector store {store.name} deleted.")
+            except Exception as store_err:
+                log(
+                    f"Failed to delete vector store {store.name}: {store_err}",
+                    level=logging.WARNING,
+                )
+
+        log("Checking for orphaned files in client.files...")
+        all_files = client.files.list().data
+        for file in all_files:
+            if file.id not in attached_file_ids:
+                try:
+                    log(f"Deleting orphaned file {file.id}")
+                    client.files.delete(file_id=file.id)
+                except Exception as exc:
+                    log(
+                        f"Failed to delete orphaned file {file.id}: {exc}",
+                        level=logging.WARNING,
+                    )
+
+    except Exception as exc:
+        log(f"Error during cleanup: {exc}", level=logging.ERROR)
+
+
+def _delete_all_files() -> None:
+    """Delete all files from the OpenAI account.
+
+    This utility iterates over every file owned by the account and deletes them.
+    It does not check for vector stores, so it will delete all files regardless
+    of their association.
+
+    Returns
+    -------
+    None
+    """
+    client = OpenAI()
+    all_files = client.files.list().data
+    for file in all_files:
+        try:
+            log(f"Deleting file {file.id}")
+            client.files.delete(file_id=file.id)
+        except Exception as exc:
+            log(f"Failed to delete file {file.id}: {exc}", level=logging.WARNING)