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

openai_sdk_helpers/structure/web_search.py

@@ -1,50 +1,162 @@
-"""Shared structured output model for web search results."""
+"""Structured output models for web search workflows.
 
-from __future__ import annotations
+This module defines Pydantic models for representing web search plans,
+results, and reports. These structures support multi-query web search
+workflows with comprehensive reporting.
+"""
 
-from typing import List
+from __future__ import annotations
 
 from .base import BaseStructure, spec_field
 
 
 class WebSearchReportStructure(BaseStructure):
-    """Structured output from the writer agent."""
+    """Structured output from the web search writer agent.
+
+    Contains the final synthesized report from web search results,
+    including summary, markdown report, follow-up questions, and sources.
+
+    Attributes
+    ----------
+    short_summary : str
+        Brief summary of the search findings.
+    markdown_report : str
+        Full markdown-formatted report.
+    follow_up_questions : list[str]
+        Suggested questions for further exploration.
+    sources : list[str]
+        Source URLs and references used in the report.
+
+    Examples
+    --------
+    >>> report = WebSearchReportStructure(
+    ...     short_summary="Summary",
+    ...     markdown_report="# Report",
+    ...     follow_up_questions=["Q1?"],
+    ...     sources=["https://example.com"]
+    ... )
+    """
 
     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")
+    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."""
+    """A single web search to perform.
+
+    Represents one web search query with rationale for its inclusion
+    in a multi-query search plan.
+
+    Attributes
+    ----------
+    reason : str
+        Explanation for why this search is needed.
+    query : str
+        Web search query text.
+
+    Examples
+    --------
+    >>> item = WebSearchItemStructure(
+    ...     reason="Find latest news",
+    ...     query="AI developments 2024"
+    ... )
+    """
 
     reason: str = spec_field("reason")
     query: str = spec_field("query")
 
 
 class WebSearchItemResultStructure(BaseStructure):
-    """Result of a single web search."""
+    """Result of a single web search.
+
+    Contains the text content retrieved from executing one web search query.
+
+    Attributes
+    ----------
+    text : str
+        Retrieved text content from the web search.
+
+    Examples
+    --------
+    >>> result = WebSearchItemResultStructure(text="Search result content")
+    """
 
     text: str = spec_field("text")
 
 
 class WebSearchPlanStructure(BaseStructure):
-    """Collection of searches required to satisfy the query."""
+    """Collection of web searches required to satisfy the query.
 
-    searches: List[WebSearchItemStructure] = spec_field("searches")
+    Represents a plan containing multiple web searches that together
+    provide comprehensive coverage for answering a user query.
+
+    Attributes
+    ----------
+    searches : list[WebSearchItemStructure]
+        List of web search queries to execute.
+
+    Examples
+    --------
+    >>> plan = WebSearchPlanStructure(
+    ...     searches=[WebSearchItemStructure(reason="R", query="Q")]
+    ... )
+    """
+
+    searches: list[WebSearchItemStructure] = spec_field("searches")
 
 
 class WebSearchStructure(BaseStructure):
-    """Complete output of a web search workflow."""
+    """Complete output of a web search workflow.
+
+    Represents the full lifecycle of a web search operation, from the
+    original query through plan generation, execution, and final report.
+
+    Attributes
+    ----------
+    query : str
+        Original user query.
+    web_search_plan : WebSearchPlanStructure
+        Generated search plan.
+    web_search_results : list[WebSearchItemResultStructure]
+        List of search results.
+    web_search_report : WebSearchReportStructure
+        Final synthesized report.
+
+    Methods
+    -------
+    print()
+        Return the markdown report.
+
+    Examples
+    --------
+    >>> workflow = WebSearchStructure(
+    ...     query="Test query",
+    ...     web_search_plan=WebSearchPlanStructure(searches=[]),
+    ...     web_search_results=[],
+    ...     web_search_report=WebSearchReportStructure(
+    ...         short_summary="S",
+    ...         markdown_report="R",
+    ...         follow_up_questions=[],
+    ...         sources=[]
+    ...     )
+    ... )
+    """
 
     query: str = spec_field("query")
     web_search_plan: WebSearchPlanStructure = spec_field("web_search_plan")
-    web_search_results: List[WebSearchItemResultStructure] = spec_field(
+    web_search_results: list[WebSearchItemResultStructure] = spec_field(
         "web_search_results"
     )
     web_search_report: WebSearchReportStructure = spec_field("web_search_report")
 
     def print(self) -> str:
-        """Return the markdown report."""
+        """Return the markdown report.
+
+        Returns
+        -------
+        str
+            Markdown-formatted report from web search results.
+        """
         return self.web_search_report.markdown_report

openai_sdk_helpers/tools.py

@@ -0,0 +1,193 @@
+"""Tool handler utilities for OpenAI SDK interactions.
+
+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.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from typing import Any, Callable, TypeVar
+
+from pydantic import BaseModel, ValidationError
+
+from openai_sdk_helpers.response.tool_call import parse_tool_arguments
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def serialize_tool_result(result: Any) -> str:
+    """Serialize tool results into a standardized JSON string.
+
+    Handles Pydantic models, lists, dicts, and plain strings with consistent
+    JSON formatting. Pydantic models are serialized using model_dump(),
+    while other types are converted to JSON or string representation.
+
+    Parameters
+    ----------
+    result : Any
+        Tool result to serialize. Can be a Pydantic model, list, dict, str,
+        or any JSON-serializable type.
+
+    Returns
+    -------
+    str
+        JSON-formatted string representation of the result.
+
+    Examples
+    --------
+    >>> from pydantic import BaseModel
+    >>> class Result(BaseModel):
+    ...     value: int
+    >>> serialize_tool_result(Result(value=42))
+    '{"value": 42}'
+
+    >>> serialize_tool_result(["item1", "item2"])
+    '["item1", "item2"]'
+
+    >>> serialize_tool_result("plain text")
+    '"plain text"'
+
+    >>> 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))
+
+
+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.
+
+    Wraps a tool function with automatic argument parsing, optional Pydantic
+    validation, execution, and result serialization. This eliminates
+    repetitive boilerplate for tool implementations.
+
+    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
+    4. Serializes the result using serialize_tool_result
+
+    Parameters
+    ----------
+    func : Callable[..., Any]
+        The actual tool implementation function. Should accept keyword
+        arguments matching the tool's parameter schema. Can be synchronous
+        or asynchronous.
+    input_model : type[BaseModel] or None, default None
+        Optional Pydantic model for input validation. When provided,
+        arguments are validated and converted to this model before being
+        passed to func.
+
+    Returns
+    -------
+    Callable[[Any], str]
+        Handler function that accepts a tool_call object (with arguments
+        and name attributes) and returns a JSON string result.
+
+    Raises
+    ------
+    ValidationError
+        If input_model is provided and validation fails.
+    ValueError
+        If argument parsing fails.
+
+    Examples
+    --------
+    Basic usage without validation:
+
+    >>> def search_tool(query: str, limit: int = 10):
+    ...     return {"results": [f"Result for {query}"]}
+    >>> handler = tool_handler_factory(search_tool)
+
+    With Pydantic validation:
+
+    >>> from pydantic import BaseModel
+    >>> class SearchInput(BaseModel):
+    ...     query: str
+    ...     limit: int = 10
+    >>> def search_tool(query: str, limit: int = 10):
+    ...     return {"results": [f"Result for {query}"]}
+    >>> handler = tool_handler_factory(search_tool, SearchInput)
+
+    The handler can then be used with OpenAI tool calls:
+
+    >>> class ToolCall:
+    ...     def __init__(self):
+    ...         self.arguments = '{"query": "test", "limit": 5}'
+    ...         self.name = "search"
+    >>> tool_call = ToolCall()
+    >>> result = handler(tool_call)  # doctest: +SKIP
+    """
+
+    def handler(tool_call: Any) -> str:
+        """Handle tool execution with parsing, validation, and serialization.
+
+        Parameters
+        ----------
+        tool_call : Any
+            Tool call object with 'arguments' and 'name' attributes.
+
+        Returns
+        -------
+        str
+            JSON-formatted result from the tool function.
+
+        Raises
+        ------
+        ValueError
+            If argument parsing fails.
+        ValidationError
+            If Pydantic validation fails (when input_model is provided).
+        """
+        # Extract tool name for error context (required)
+        tool_name = getattr(tool_call, "name", "unknown")
+
+        # Parse arguments with error context
+        parsed_args = parse_tool_arguments(tool_call.arguments, tool_name=tool_name)
+
+        # Validate with Pydantic if model provided
+        if input_model is not None:
+            validated_input = input_model(**parsed_args)
+            # Convert back to dict for function call
+            call_kwargs = validated_input.model_dump()
+        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)
+
+        # Serialize result
+        return serialize_tool_result(result)
+
+    return handler
+
+
+__all__ = [
+    "serialize_tool_result",
+    "tool_handler_factory",
+]

openai_sdk_helpers/types.py

@@ -0,0 +1,57 @@
+"""Common type definitions shared across the SDK.
+
+This module defines protocol types and type aliases for OpenAI client
+compatibility, enabling flexible client usage throughout the package.
+
+Classes
+-------
+SupportsOpenAIClient
+    Protocol describing the subset of OpenAI client interface used by the SDK.
+
+Type Aliases
+------------
+OpenAIClient
+    Union type accepting OpenAI client or compatible protocol implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from openai import OpenAI
+
+
+class SupportsOpenAIClient(Protocol):
+    """Protocol describing the subset of the OpenAI client the SDK relies on.
+
+    Defines the minimum interface required for OpenAI client compatibility.
+    Custom implementations can satisfy this protocol for testing or
+    alternative backends.
+
+    Attributes
+    ----------
+    api_key : str or None
+        API key for authentication.
+    vector_stores : Any
+        Vector stores management interface.
+    responses : Any
+        Responses API interface.
+    files : Any
+        Files management interface.
+    """
+
+    api_key: str | None
+    vector_stores: Any
+    responses: Any
+    files: Any
+
+
+OpenAIClient = OpenAI | SupportsOpenAIClient
+"""Type alias for OpenAI client or compatible protocol implementation.
+
+Accepts either the official OpenAI client or any object satisfying the
+SupportsOpenAIClient protocol.
+"""
+
+
+__all__ = ["SupportsOpenAIClient", "OpenAIClient"]

openai_sdk_helpers/utils/__init__.py

@@ -1,9 +1,41 @@
-"""Shared utility helpers for openai-sdk-helpers."""
+"""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.
+
+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.
+
+Classes
+-------
+JSONSerializable
+    Mixin for classes that can be serialized to JSON.
+customJSONEncoder
+    JSON encoder for common helper types like enums and paths.
+"""
 
 from __future__ import annotations
 
 from .core import (
     JSONSerializable,
+    build_openai_settings,
     check_filepath,
     coerce_jsonable,
     coerce_dict,
@@ -24,4 +56,5 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
+    "build_openai_settings",
 ]