openai-sdk-helpers 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

openai_sdk_helpers/structure/responses.py

@@ -1,7 +1,7 @@
 """OpenAI response and tool helpers for structured outputs.
 
 This module provides helper functions for creating OpenAI API response formats
-and tool definitions from BaseStructure classes. These helpers simplify the
+and tool definitions from StructureBase classes. These helpers simplify the
 process of configuring structured outputs for both Assistant and chat
 completion APIs.
 """
@@ -13,12 +13,12 @@ from openai.types.responses.response_format_text_json_schema_config_param import
 )
 from openai.types.responses.response_text_config_param import ResponseTextConfigParam
 
-from .base import BaseStructure
+from .base import StructureBase
 from ..utils import log
 
 
 def assistant_tool_definition(
-    structure: type[BaseStructure], name: str, description: str
+    structure: type[StructureBase], name: str, description: str
 ) -> dict:
     """Build a function tool definition for OpenAI Assistants.
 
@@ -27,7 +27,7 @@ def assistant_tool_definition(
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the tool schema.
     name : str
         Name of the function tool.
@@ -41,9 +41,9 @@ def assistant_tool_definition(
 
     Examples
     --------
-    >>> from openai_sdk_helpers.structure import BaseStructure
+    >>> from openai_sdk_helpers.structure import StructureBase
     >>> tool = assistant_tool_definition(
-    ...     BaseStructure,
+    ...     StructureBase,
     ...     "process_data",
     ...     "Process input data"
     ... )
@@ -59,7 +59,7 @@ def assistant_tool_definition(
     }
 
 
-def assistant_format(structure: type[BaseStructure]) -> dict:
+def assistant_format(structure: type[StructureBase]) -> dict:
     """Build a response format definition for OpenAI Assistants.
 
     Creates a response format specification that instructs the Assistant API
@@ -67,7 +67,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the response schema.
 
     Returns
@@ -77,7 +77,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
     Examples
     --------
-    >>> format_def = assistant_format(BaseStructure)
+    >>> format_def = assistant_format(StructureBase)
     """
     log(f"{structure.__name__}::assistant_format")
     return {
@@ -90,7 +90,7 @@ def assistant_format(structure: type[BaseStructure]) -> dict:
 
 
 def response_tool_definition(
-    structure: type[BaseStructure],
+    structure: type[StructureBase],
     tool_name: str,
     tool_description: str,
 ) -> dict:
@@ -101,7 +101,7 @@ def response_tool_definition(
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the tool schema.
     tool_name : str
         Name of the function tool.
@@ -116,7 +116,7 @@ def response_tool_definition(
     Examples
     --------
     >>> tool = response_tool_definition(
-    ...     BaseStructure,
+    ...     StructureBase,
     ...     "analyze",
     ...     "Analyze data"
     ... )
@@ -132,7 +132,7 @@ def response_tool_definition(
     }
 
 
-def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
+def response_format(structure: type[StructureBase]) -> ResponseTextConfigParam:
     """Build a response format for OpenAI chat completions.
 
     Creates a response format specification that instructs the chat
@@ -140,7 +140,7 @@ def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
 
     Parameters
     ----------
-    structure : type[BaseStructure]
+    structure : type[StructureBase]
         Structure class that defines the response schema.
 
     Returns
@@ -150,7 +150,7 @@ def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
 
     Examples
     --------
-    >>> format_spec = response_format(BaseStructure)
+    >>> format_spec = response_format(StructureBase)
     """
     log(f"{structure.__name__}::response_format")
     response_format_text_JSONSchema_config_param = (

openai_sdk_helpers/structure/summary.py

@@ -6,10 +6,10 @@ including topic-level summaries with citations and consolidated text summaries.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class SummaryTopic(BaseStructure):
+class SummaryTopic(StructureBase):
     """Capture a topic-level summary with supporting citations.
 
     Represents a single topic or micro-trend identified in source excerpts,
@@ -55,7 +55,7 @@ class SummaryTopic(BaseStructure):
     )
 
 
-class SummaryStructure(BaseStructure):
+class SummaryStructure(StructureBase):
     """Consolidated summary returned by the summarizer agent.
 
     Represents a synthesized summary text derived from multiple source excerpts.

openai_sdk_helpers/structure/translation.py

@@ -0,0 +1,32 @@
+"""Structured output model for translations."""
+
+from __future__ import annotations
+
+from .base import StructureBase, spec_field
+
+
+class TranslationStructure(StructureBase):
+    """Structured representation of translated text.
+
+    Attributes
+    ----------
+    text : str
+        Translated text output from the agent.
+
+    Methods
+    -------
+    print()
+        Return the formatted model fields.
+
+    Examples
+    --------
+    >>> translation = TranslationStructure(text="Hola mundo")
+    >>> print(translation.text)
+    'Hola mundo'
+    """
+
+    text: str = spec_field(
+        "text",
+        description="Translated text output from the agent.",
+        examples=["Hola mundo", "Bonjour le monde"],
+    )

openai_sdk_helpers/structure/validation.py

@@ -6,10 +6,10 @@ validation checks on user inputs and agent outputs.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class ValidationResultStructure(BaseStructure):
+class ValidationResultStructure(StructureBase):
     """Capture guardrail validation findings for user and agent messages.
 
     Represents the results of safety and policy validation checks performed

openai_sdk_helpers/structure/vector_search.py

@@ -7,10 +7,10 @@ workflows with error tracking and result aggregation.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class VectorSearchItemStructure(BaseStructure):
+class VectorSearchItemStructure(StructureBase):
     """A single vector search to perform.
 
     Represents one vector search query with rationale for its inclusion
@@ -35,7 +35,7 @@ class VectorSearchItemStructure(BaseStructure):
     query: str = spec_field("query")
 
 
-class VectorSearchPlanStructure(BaseStructure):
+class VectorSearchPlanStructure(StructureBase):
     """Collection of vector searches required to satisfy the query.
 
     Represents a plan containing multiple vector searches that together
@@ -56,7 +56,7 @@ class VectorSearchPlanStructure(BaseStructure):
     searches: list[VectorSearchItemStructure] = spec_field("searches")
 
 
-class VectorSearchItemResultStructure(BaseStructure):
+class VectorSearchItemResultStructure(StructureBase):
     """Result of a single vector search.
 
     Contains the text results retrieved from executing one vector search query.
@@ -74,7 +74,7 @@ class VectorSearchItemResultStructure(BaseStructure):
     texts: list[str] = spec_field("texts")
 
 
-class VectorSearchItemResultsStructure(BaseStructure):
+class VectorSearchItemResultsStructure(StructureBase):
     """Collection of search results from multiple queries.
 
     Aggregates results from multiple vector searches while tracking any
@@ -119,7 +119,7 @@ class VectorSearchItemResultsStructure(BaseStructure):
         self.item_results.append(item)
 
 
-class VectorSearchReportStructure(BaseStructure):
+class VectorSearchReportStructure(StructureBase):
     """Structured output from the vector search writer agent.
 
     Contains the final synthesized report from vector search results,
@@ -152,7 +152,7 @@ class VectorSearchReportStructure(BaseStructure):
     sources: list[str] = spec_field("sources")
 
 
-class VectorSearchStructure(BaseStructure):
+class VectorSearchStructure(StructureBase):
     """Complete output of a vector search workflow.
 
     Represents the full lifecycle of a vector search operation, from the

openai_sdk_helpers/structure/web_search.py

@@ -7,10 +7,10 @@ workflows with comprehensive reporting.
 
 from __future__ import annotations
 
-from .base import BaseStructure, spec_field
+from .base import StructureBase, spec_field
 
 
-class WebSearchReportStructure(BaseStructure):
+class WebSearchReportStructure(StructureBase):
     """Structured output from the web search writer agent.
 
     Contains the final synthesized report from web search results,
@@ -43,7 +43,7 @@ class WebSearchReportStructure(BaseStructure):
     sources: list[str] = spec_field("sources")
 
 
-class WebSearchItemStructure(BaseStructure):
+class WebSearchItemStructure(StructureBase):
     """A single web search to perform.
 
     Represents one web search query with rationale for its inclusion
@@ -68,7 +68,7 @@ class WebSearchItemStructure(BaseStructure):
     query: str = spec_field("query")
 
 
-class WebSearchItemResultStructure(BaseStructure):
+class WebSearchItemResultStructure(StructureBase):
     """Result of a single web search.
 
     Contains the text content retrieved from executing one web search query.
@@ -86,7 +86,7 @@ class WebSearchItemResultStructure(BaseStructure):
     text: str = spec_field("text")
 
 
-class WebSearchPlanStructure(BaseStructure):
+class WebSearchPlanStructure(StructureBase):
     """Collection of web searches required to satisfy the query.
 
     Represents a plan containing multiple web searches that together
@@ -107,7 +107,7 @@ class WebSearchPlanStructure(BaseStructure):
     searches: list[WebSearchItemStructure] = spec_field("searches")
 
 
-class WebSearchStructure(BaseStructure):
+class WebSearchStructure(StructureBase):
     """Complete output of a web search workflow.
 
     Represents the full lifecycle of a web search operation, from the

openai_sdk_helpers/tools.py

@@ -10,19 +10,21 @@ definitions from named metadata structures.
 
 from __future__ import annotations
 
+import asyncio
 import inspect
+import threading
 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.structure.base import StructureBase
 from openai_sdk_helpers.utils import coerce_jsonable, customJSONEncoder
 import json
 
 T = TypeVar("T", bound=BaseModel)
-StructureType: TypeAlias = type[BaseStructure]
+StructureType: TypeAlias = type[StructureBase]
 
 
 def serialize_tool_result(result: Any) -> str:
@@ -81,7 +83,7 @@ def tool_handler_factory(
     The returned handler:
     1. Parses tool_call.arguments using parse_tool_arguments
     2. Validates arguments with input_model if provided
-    3. Calls func with validated/parsed arguments
+    3. Calls func with validated/parsed arguments (handles both sync and async)
     4. Serializes the result using serialize_tool_result
 
     Parameters
@@ -124,7 +126,13 @@ def tool_handler_factory(
     ...     limit: int = 10
     >>> def search_tool(query: str, limit: int = 10):
     ...     return {"results": [f"Result for {query}"]}
-    >>> handler = tool_handler_factory(search_tool, SearchInput)
+    >>> handler = tool_handler_factory(search_tool, input_model=SearchInput)
+
+    With async function:
+
+    >>> async def async_search_tool(query: str, limit: int = 10):
+    ...     return {"results": [f"Result for {query}"]}
+    >>> handler = tool_handler_factory(async_search_tool)
 
     The handler can then be used with OpenAI tool calls:
 
@@ -135,6 +143,7 @@ def tool_handler_factory(
     >>> tool_call = ToolCall()
     >>> result = handler(tool_call)  # doctest: +SKIP
     """
+    is_async = inspect.iscoroutinefunction(func)
 
     def handler(tool_call: Any) -> str:
         """Handle tool execution with parsing, validation, and serialization.
@@ -170,15 +179,32 @@ def tool_handler_factory(
         else:
             call_kwargs = parsed_args
 
-        # Execute function (sync only - async functions not supported)
-        if inspect.iscoroutinefunction(func):
-            raise TypeError(
-                f"Async functions are not supported by tool_handler_factory. "
-                f"Function '{func.__name__}' is async. "
-                "Wrap async functions in a synchronous adapter before passing to tool_handler_factory."
-            )
-
-        result = func(**call_kwargs)
+        # Execute function (sync or async with event loop detection)
+        if is_async:
+            # Handle async function with proper event loop detection
+            try:
+                loop = asyncio.get_running_loop()
+                # We're inside an event loop, need to run in thread
+                result_holder: dict[str, Any] = {"value": None, "exception": None}
+
+                def _thread_func() -> None:
+                    try:
+                        result_holder["value"] = asyncio.run(func(**call_kwargs))
+                    except Exception as exc:
+                        result_holder["exception"] = exc
+
+                thread = threading.Thread(target=_thread_func)
+                thread.start()
+                thread.join()
+
+                if result_holder["exception"]:
+                    raise result_holder["exception"]
+                result = result_holder["value"]
+            except RuntimeError:
+                # No event loop running, can use asyncio.run directly
+                result = asyncio.run(func(**call_kwargs))
+        else:
+            result = func(**call_kwargs)
 
         # Serialize result
         return serialize_tool_result(result)
@@ -200,14 +226,14 @@ class ToolSpec:
     Attributes
     ----------
     structure : StructureType
-        The BaseStructure class that defines the tool's input parameter schema.
+        The StructureBase 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.
+        Optional StructureBase 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.

openai_sdk_helpers/utils/__init__.py

@@ -21,8 +21,8 @@ coercion
     Numeric coercion helpers and list normalization.
 path_utils
     File and path helpers.
-json_utils
-    JSON encoding helpers and mixins.
+json
+    JSON encoding helpers and mixins for dataclasses and Pydantic models.
 logging_config
     Centralized logger factory and convenience log helper.
 validation
@@ -45,11 +45,18 @@ from .coercion import (
     coerce_optional_int,
     ensure_list,
 )
-from .json_utils import (
-    JSONSerializable,
+from .json import (
+    BaseModelJSONSerializable,
+    DataclassJSONSerializable,
     coerce_jsonable,
     customJSONEncoder,
+    decode_module_qualname,
+    encode_module_qualname,
+    get_module_qualname,
+    to_jsonable,
 )
+from .registry import BaseRegistry
+
 from .path_utils import check_filepath, ensure_directory
 from openai_sdk_helpers.logging_config import log
 from .validation import (
@@ -88,9 +95,14 @@ __all__ = [
     "coerce_optional_float",
     "coerce_optional_int",
     "coerce_dict",
+    "to_jsonable",
     "coerce_jsonable",
-    "JSONSerializable",
+    "DataclassJSONSerializable",
+    "BaseModelJSONSerializable",
     "customJSONEncoder",
+    "get_module_qualname",
+    "encode_module_qualname",
+    "decode_module_qualname",
     "log",
     # Validation helpers
     "validate_non_empty_string",
@@ -122,4 +134,6 @@ __all__ = [
     "create_image_data_url",
     "create_file_data_url",
     "is_image_file",
+    # Registry
+    "BaseRegistry",
 ]

openai_sdk_helpers/utils/instructions.py

@@ -0,0 +1,35 @@
+"""Utilities for resolving instructions from strings or file paths."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_instructions_from_path(instructions: str | Path) -> str:
+    """Resolve instructions from a string or file path.
+
+    Parameters
+    ----------
+    instructions : str or Path
+        Either plain-text instructions or a path to a file containing
+        instructions.
+
+    Returns
+    -------
+    str
+        The resolved instruction text.
+
+    Raises
+    ------
+    ValueError
+        If instructions is a Path that cannot be read.
+    """
+    if isinstance(instructions, Path):
+        instruction_path = instructions.expanduser()
+        try:
+            return instruction_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(
+                f"Unable to read instructions at '{instruction_path}': {exc}"
+            ) from exc
+    return instructions

openai_sdk_helpers/utils/json/__init__.py

@@ -0,0 +1,55 @@
+"""JSON serialization helpers for dataclasses, Pydantic models, and reference encoding.
+
+This package provides consistent to_json/from_json flows and a JSONEncoder that
+handles common types including dataclasses, Pydantic models, and reference encoding.
+
+Package Layout
+--------------
+utils.py
+    to_jsonable(), coerce_jsonable(), customJSONEncoder.
+data_class.py
+    DataclassJSONSerializable mixin with to_json, to_json_file, from_json, from_json_file.
+base_model.py
+    BaseModelJSONSerializable for Pydantic, with _serialize_fields/_deserialize_fields hooks.
+ref.py
+    Reference helpers get_module_qualname, encode_module_qualname, decode_module_qualname.
+
+Public API
+----------
+to_jsonable(value)
+    Convert common types to JSON-safe forms; recursive for containers/dicts.
+coerce_jsonable(value)
+    Ensures json.dumps succeeds; falls back to str when necessary. Special-cases ResponseBase.
+customJSONEncoder
+    json.JSONEncoder subclass delegating to to_jsonable.
+DataclassJSONSerializable
+    Mixin adding to_json(), to_json_file(path) -> str, from_json(data) -> T, from_json_file(path) -> T.
+BaseModelJSONSerializable
+    Pydantic BaseModel subclass adding to_json() -> dict, to_json_file(path) -> str,
+    from_json(data) -> T, from_json_file(path) -> T, plus overridable _serialize_fields(data)
+    and _deserialize_fields(data).
+get_module_qualname(obj) -> (module, qualname)
+    Safe retrieval.
+encode_module_qualname(obj) -> dict|None
+    {module, qualname} for import reconstruction.
+decode_module_qualname(ref) -> object|None
+    Import and getattr by encoded reference.
+"""
+
+from __future__ import annotations
+
+from .base_model import BaseModelJSONSerializable
+from .data_class import DataclassJSONSerializable
+from .ref import decode_module_qualname, encode_module_qualname, get_module_qualname
+from .utils import coerce_jsonable, customJSONEncoder, to_jsonable
+
+__all__ = [
+    "to_jsonable",
+    "coerce_jsonable",
+    "customJSONEncoder",
+    "DataclassJSONSerializable",
+    "BaseModelJSONSerializable",
+    "get_module_qualname",
+    "encode_module_qualname",
+    "decode_module_qualname",
+]