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

openai_sdk_helpers/structure/plan/task.py

@@ -140,13 +140,13 @@ class TaskStructure(BaseStructure):
         """
         return "\n".join(
             [
-                BaseStructure.format_output("Task type", self.task_type),
-                BaseStructure.format_output("Prompt", self.prompt),
-                BaseStructure.format_output("Context", self.context),
-                BaseStructure.format_output("Status", self.status),
-                BaseStructure.format_output("Start date", self.start_date),
-                BaseStructure.format_output("End date", self.end_date),
-                BaseStructure.format_output("Results", self.results),
+                BaseStructure.format_output("Task type", value=self.task_type),
+                BaseStructure.format_output("Prompt", value=self.prompt),
+                BaseStructure.format_output("Context", value=self.context),
+                BaseStructure.format_output("Status", value=self.status),
+                BaseStructure.format_output("Start date", value=self.start_date),
+                BaseStructure.format_output("End date", value=self.end_date),
+                BaseStructure.format_output("Results", value=self.results),
             ]
         )
 

openai_sdk_helpers/tools.py

@@ -3,19 +3,26 @@
 This module provides generic tool handling infrastructure including argument
 parsing, Pydantic validation, function execution, and result serialization.
 These utilities reduce boilerplate and ensure consistent tool behavior.
+
+Also provides declarative tool specification helpers for building tool
+definitions from named metadata structures.
 """
 
 from __future__ import annotations
 
 import inspect
-import json
-from typing import Any, Callable, TypeVar
+from dataclasses import dataclass
+from typing import Any, Callable, TypeAlias, TypeVar
 
 from pydantic import BaseModel, ValidationError
 
 from openai_sdk_helpers.response.tool_call import parse_tool_arguments
+from openai_sdk_helpers.structure.base import BaseStructure
+from openai_sdk_helpers.utils import coerce_jsonable, customJSONEncoder
+import json
 
 T = TypeVar("T", bound=BaseModel)
+StructureType: TypeAlias = type[BaseStructure]
 
 
 def serialize_tool_result(result: Any) -> str:
@@ -53,24 +60,16 @@ def serialize_tool_result(result: Any) -> str:
     >>> serialize_tool_result({"key": "value"})
     '{"key": "value"}'
     """
-    # Handle Pydantic models
     if isinstance(result, BaseModel):
         return result.model_dump_json()
 
-    # Handle strings - wrap in JSON string format
-    if isinstance(result, str):
-        return json.dumps(result)
-
-    # Handle other JSON-serializable types (lists, dicts, primitives)
-    try:
-        return json.dumps(result)
-    except (TypeError, ValueError):
-        # Fallback to string representation for non-JSON types
-        return json.dumps(str(result))
+    payload = coerce_jsonable(result)
+    return json.dumps(payload, cls=customJSONEncoder)
 
 
 def tool_handler_factory(
     func: Callable[..., Any],
+    *,
     input_model: type[T] | None = None,
 ) -> Callable[[Any], str]:
     """Create a generic tool handler that parses, validates, and serializes.
@@ -187,7 +186,111 @@ def tool_handler_factory(
     return handler
 
 
+@dataclass(frozen=True)
+class ToolSpec:
+    """Capture tool metadata for response configuration.
+
+    Provides a named structure for representing tool specifications, making
+    tool definitions explicit and eliminating ambiguous tuple ordering.
+
+    Supports tools with separate input and output structures, where the input
+    structure defines the tool's parameter schema and the output structure
+    documents the expected return type (for reference only).
+
+    Attributes
+    ----------
+    structure : StructureType
+        The BaseStructure class that defines the tool's input parameter schema.
+        Used to generate the OpenAI tool definition.
+    tool_name : str
+        Name identifier for the tool.
+    tool_description : str
+        Human-readable description of what the tool does.
+    output_structure : StructureType or None, default=None
+        Optional BaseStructure class that defines the tool's output schema.
+        This is for documentation/reference only and is not sent to OpenAI.
+        Useful when a tool accepts one type of input but returns a different
+        structured output.
+
+    Examples
+    --------
+    Define a tool with same input/output structure:
+
+    >>> from openai_sdk_helpers import ToolSpec
+    >>> from openai_sdk_helpers.structure import PromptStructure
+    >>> spec = ToolSpec(
+    ...     structure=PromptStructure,
+    ...     tool_name="web_agent",
+    ...     tool_description="Run a web research workflow"
+    ... )
+
+    Define a tool with different input and output structures:
+
+    >>> from openai_sdk_helpers.structure import PromptStructure, SummaryStructure
+    >>> spec = ToolSpec(
+    ...     structure=PromptStructure,
+    ...     tool_name="summarizer",
+    ...     tool_description="Summarize the provided prompt",
+    ...     output_structure=SummaryStructure
+    ... )
+    """
+
+    structure: StructureType
+    tool_name: str
+    tool_description: str
+    output_structure: StructureType | None = None
+
+
+def build_tool_definitions(tool_specs: list[ToolSpec]) -> list[dict]:
+    """Build tool definitions from named tool specs.
+
+    Converts a list of ToolSpec objects into OpenAI-compatible tool
+    definitions for use in response configurations. Each ToolSpec is
+    transformed into a tool definition using the structure's
+    response_tool_definition method.
+
+    Parameters
+    ----------
+    tool_specs : list[ToolSpec]
+        List of tool specifications to convert.
+
+    Returns
+    -------
+    list[dict]
+        List of tool definition dictionaries ready for OpenAI API.
+
+    Examples
+    --------
+    Build multiple tool definitions:
+
+    >>> from openai_sdk_helpers import ToolSpec, build_tool_definitions
+    >>> from openai_sdk_helpers.structure import PromptStructure
+    >>> tools = build_tool_definitions([
+    ...     ToolSpec(
+    ...         structure=PromptStructure,
+    ...         tool_name="web_agent",
+    ...         tool_description="Run a web research workflow"
+    ...     ),
+    ...     ToolSpec(
+    ...         structure=PromptStructure,
+    ...         tool_name="vector_agent",
+    ...         tool_description="Run a vector search workflow"
+    ...     ),
+    ... ])
+    """
+    return [
+        spec.structure.response_tool_definition(
+            tool_name=spec.tool_name,
+            tool_description=spec.tool_description,
+        )
+        for spec in tool_specs
+    ]
+
+
 __all__ = [
     "serialize_tool_result",
     "tool_handler_factory",
+    "StructureType",
+    "ToolSpec",
+    "build_tool_definitions",
 ]

openai_sdk_helpers/utils/__init__.py

@@ -1,54 +1,90 @@
 """Utility helpers for openai-sdk-helpers.
 
-This package provides common utility functions for type coercion, file
-handling, JSON serialization, logging, and OpenAI settings construction.
-These utilities are used throughout the openai_sdk_helpers package.
+The utils package collects cross-cutting helpers used across the project:
 
-Functions
----------
-ensure_list(value)
-    Normalize a single item or iterable into a list.
-check_filepath(filepath, fullfilepath)
-    Ensure the parent directory for a file path exists.
-coerce_optional_float(value)
-    Convert a value to float or None.
-coerce_optional_int(value)
-    Convert a value to int or None.
-coerce_dict(value)
-    Convert a value to a string-keyed dictionary.
-coerce_jsonable(value)
-    Convert a value into a JSON-serializable representation.
-log(message, level)
-    Log a message with basic configuration.
-build_openai_settings(**kwargs)
-    Build OpenAI settings from environment with validation.
+* Core helpers: coercion, path handling, JSON encoding, and logging basics.
+* Validation: input validation helpers for strings, choices, URLs, etc.
+* Concurrency: async bridging helpers.
+* Output validation: JSON Schema and semantic validators.
+* Instrumentation helpers: deprecation utilities.
+* Encoding: base64 encoding for images and files.
 
-Classes
--------
-JSONSerializable
-    Mixin for classes that can be serialized to JSON.
-customJSONEncoder
-    JSON encoder for common helper types like enums and paths.
+Import style
+------------
+Public helpers are re-exported from ``openai_sdk_helpers.utils`` for a
+consistent import surface. You can import from submodules when you need a
+smaller surface area, but top-level imports remain stable.
+
+Submodules
+----------
+coercion
+    Numeric coercion helpers and list normalization.
+path_utils
+    File and path helpers.
+json_utils
+    JSON encoding helpers and mixins.
+logging_config
+    Centralized logger factory and convenience log helper.
+validation
+    Input validation helpers for strings, URLs, collections, and paths.
+async_utils
+    Async-to-sync bridging helpers.
+output_validation
+    JSON Schema and semantic output validation utilities.
+deprecation
+    Deprecation helpers and warning utilities.
+encoding
+    Base64 encoding helpers for images and files.
 """
 
 from __future__ import annotations
 
-from .core import (
-    JSONSerializable,
-    build_openai_settings,
-    check_filepath,
-    coerce_jsonable,
+from .coercion import (
     coerce_dict,
     coerce_optional_float,
     coerce_optional_int,
-    customJSONEncoder,
     ensure_list,
-    log,
+)
+from .json_utils import (
+    JSONSerializable,
+    coerce_jsonable,
+    customJSONEncoder,
+)
+from .path_utils import check_filepath, ensure_directory
+from openai_sdk_helpers.logging_config import log
+from .validation import (
+    validate_choice,
+    validate_dict_mapping,
+    validate_list_items,
+    validate_max_length,
+    validate_non_empty_string,
+    validate_safe_path,
+    validate_url_format,
+)
+from .async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
+from .output_validation import (
+    JSONSchemaValidator,
+    LengthValidator,
+    OutputValidator,
+    SemanticValidator,
+    ValidationResult,
+    ValidationRule,
+    validate_output,
+)
+from .deprecation import DeprecationHelper, deprecated, warn_deprecated
+from .encoding import (
+    create_file_data_url,
+    create_image_data_url,
+    encode_file,
+    encode_image,
+    get_mime_type,
+    is_image_file,
 )
 
 __all__ = [
     "ensure_list",
     "check_filepath",
+    "ensure_directory",
     "coerce_optional_float",
     "coerce_optional_int",
     "coerce_dict",
@@ -56,5 +92,34 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
-    "build_openai_settings",
+    # Validation helpers
+    "validate_non_empty_string",
+    "validate_max_length",
+    "validate_url_format",
+    "validate_dict_mapping",
+    "validate_list_items",
+    "validate_choice",
+    "validate_safe_path",
+    # Async helpers
+    "run_coroutine_thread_safe",
+    "run_coroutine_with_fallback",
+    # Output validation
+    "ValidationResult",
+    "ValidationRule",
+    "JSONSchemaValidator",
+    "SemanticValidator",
+    "LengthValidator",
+    "OutputValidator",
+    "validate_output",
+    # Deprecation
+    "deprecated",
+    "warn_deprecated",
+    "DeprecationHelper",
+    # Encoding
+    "encode_image",
+    "encode_file",
+    "get_mime_type",
+    "create_image_data_url",
+    "create_file_data_url",
+    "is_image_file",
 ]

openai_sdk_helpers/{async_utils.py → utils/async_utils.py}

@@ -10,17 +10,17 @@ import threading
 from typing import Any, Coroutine, Generic, TypeVar
 
 from openai_sdk_helpers.errors import AsyncExecutionError
-from openai_sdk_helpers.utils.core import log
 
 T = TypeVar("T")
 
 # Default timeout constants
 DEFAULT_COROUTINE_TIMEOUT = 300.0  # 5 minutes
-THREAD_JOIN_TIMEOUT = 5.0  # 5 seconds
+THREAD_JOIN_TIMEOUT = 0.5  # 0.5 seconds
 
 
 def run_coroutine_thread_safe(
     coro: Coroutine[Any, Any, T],
+    *,
     timeout: float = DEFAULT_COROUTINE_TIMEOUT,
 ) -> T:
     """Run a coroutine in a thread-safe manner from a sync context.
@@ -80,10 +80,9 @@ def run_coroutine_thread_safe(
         # Ensure thread is cleaned up
         thread.join(timeout=THREAD_JOIN_TIMEOUT)
         if thread.is_alive():
-            log(
-                f"Thread {thread.name} did not terminate within {THREAD_JOIN_TIMEOUT} seconds",
-                level=20,  # logging.INFO
-            )
+            # Thread did not terminate, likely still running async operation
+            # This is expected for timeout scenarios, so we don't log here
+            pass
 
 
 def run_coroutine_with_fallback(

openai_sdk_helpers/utils/coercion.py

@@ -0,0 +1,138 @@
+"""Type coercion and collection normalization helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def coerce_optional_float(value: object) -> float | None:
+    """Return a float when the provided value can be coerced, otherwise None.
+
+    Handles float, int, and string inputs. Empty strings or None return None.
+
+    Parameters
+    ----------
+    value : object
+        Value to convert into a float. Strings must be parseable as floats.
+
+    Returns
+    -------
+    float or 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: object) -> int | None:
+    """Return an int when the provided value can be coerced, otherwise None.
+
+    Handles int, float (if whole number), and string inputs. Empty strings
+    or None return None. Booleans are not considered valid integers.
+
+    Parameters
+    ----------
+    value : object
+        Value to convert into an int. Strings must be parseable as integers.
+
+    Returns
+    -------
+    int or 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: object) -> dict[str, Any]:
+    """Return a string-keyed dictionary built from value if possible.
+
+    Converts Mapping objects to dictionaries. None returns an empty dict.
+
+    Parameters
+    ----------
+    value : object
+        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")
+
+
+def ensure_list(value: Iterable[T] | T | None) -> list[T]:
+    """Normalize a single item or iterable into a list.
+
+    Converts None to empty list, tuples to lists, and wraps single items in 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]
+
+
+__all__ = [
+    "coerce_optional_float",
+    "coerce_optional_int",
+    "coerce_dict",
+    "ensure_list",
+]

openai_sdk_helpers/utils/deprecation.py

@@ -0,0 +1,167 @@
+"""Deprecation utilities for managing deprecated features.
+
+This module provides infrastructure for marking and managing deprecated
+functions, classes, and features with consistent warning messages.
+
+Functions
+---------
+deprecated
+    Decorator to mark functions or classes as deprecated.
+warn_deprecated
+    Emit a deprecation warning with optional custom message.
+
+Classes
+-------
+DeprecationHelper
+    Utility class for managing deprecation warnings and versions.
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class DeprecationHelper:
+    """Utility class for managing deprecation warnings.
+
+    Provides consistent formatting and control of deprecation warnings
+    across the package.
+
+    Methods
+    -------
+    warn
+        Emit a deprecation warning with standard formatting.
+    """
+
+    @staticmethod
+    def warn(
+        feature_name: str,
+        removal_version: str,
+        alternative: str | None = None,
+        extra_message: str | None = None,
+    ) -> None:
+        """Emit a deprecation warning for a feature.
+
+        Parameters
+        ----------
+        feature_name : str
+            Name of the deprecated feature (e.g., "MyClass.old_method").
+        removal_version : str
+            Version in which the feature will be removed.
+        alternative : str, optional
+            Recommended alternative to use instead.
+        extra_message : str, optional
+            Additional context or migration instructions.
+
+        Raises
+        ------
+        DeprecationWarning
+            Always issues a DeprecationWarning to stderr.
+        """
+        msg = f"{feature_name} is deprecated and will be removed in version {removal_version}."
+        if alternative:
+            msg += f" Use {alternative} instead."
+        if extra_message:
+            msg += f" {extra_message}"
+
+        warnings.warn(msg, DeprecationWarning, stacklevel=3)
+
+
+def deprecated(
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> Callable[[F], F]:
+    """Mark a function or class as deprecated.
+
+    Parameters
+    ----------
+    removal_version : str
+        Version in which the decorated feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Returns
+    -------
+    Callable
+        Decorator function that wraps the target function or class.
+
+    Examples
+    --------
+    >>> @deprecated("1.0.0", "new_function")
+    ... def old_function():
+    ...     pass
+
+    >>> class OldClass:
+    ...     @deprecated("1.0.0", "NewClass")
+    ...     def old_method(self):
+    ...         pass
+    """
+
+    def decorator(func_or_class: F) -> F:
+        feature_name = f"{func_or_class.__module__}.{func_or_class.__qualname__}"
+
+        if isinstance(func_or_class, type):
+            # Handle class deprecation
+            original_init = func_or_class.__init__
+
+            @functools.wraps(original_init)
+            def new_init(self: Any, *args: Any, **kwargs: Any) -> None:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                original_init(self, *args, **kwargs)
+
+            func_or_class.__init__ = new_init
+        else:
+            # Handle function deprecation
+            @functools.wraps(func_or_class)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                DeprecationHelper.warn(
+                    feature_name,
+                    removal_version,
+                    alternative,
+                    extra_message,
+                )
+                return func_or_class(*args, **kwargs)
+
+            return wrapper  # type: ignore
+
+        return func_or_class  # type: ignore[return-value]
+
+    return decorator
+
+
+def warn_deprecated(
+    feature_name: str,
+    removal_version: str,
+    alternative: str | None = None,
+    extra_message: str | None = None,
+) -> None:
+    """Issue a deprecation warning.
+
+    Parameters
+    ----------
+    feature_name : str
+        Name of the deprecated feature.
+    removal_version : str
+        Version in which the feature will be removed.
+    alternative : str, optional
+        Recommended alternative to use instead.
+    extra_message : str, optional
+        Additional context or migration instructions.
+
+    Examples
+    --------
+    >>> warn_deprecated("old_config_key", "1.0.0", "new_config_key")
+    """
+    DeprecationHelper.warn(feature_name, removal_version, alternative, extra_message)