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

openai_sdk_helpers/__init__.py

@@ -46,6 +46,9 @@ from .structure import (
     ExtendedSummaryStructure,
     ValidationResultStructure,
     AgentBlueprint,
+    create_plan,
+    execute_task,
+    execute_plan,
 )
 from .prompt import PromptRenderer
 from .config import OpenAISettings
@@ -66,8 +69,19 @@ from .response import (
     ResponseMessage,
     ResponseMessages,
     ResponseToolCall,
+    ResponseConfiguration,
+    ResponseRegistry,
+    get_default_registry,
+    parse_tool_arguments,
     attach_vector_store,
 )
+from .tools import (
+    serialize_tool_result,
+    tool_handler_factory,
+)
+from .utils import (
+    build_openai_settings,
+)
 
 __all__ = [
     # Async utilities
@@ -133,5 +147,15 @@ __all__ = [
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",
+    "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
+    "parse_tool_arguments",
     "attach_vector_store",
+    "serialize_tool_result",
+    "tool_handler_factory",
+    "build_openai_settings",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
 ]

openai_sdk_helpers/config.py

@@ -141,39 +141,37 @@ class OpenAISettings(BaseModel):
         ValueError
             If OPENAI_API_KEY is not found in environment or dotenv file.
         """
-        env_file_values: Mapping[str, str | None]
+        env_file_values: Mapping[str, str | None] = {}
         if dotenv_path is not None:
             env_file_values = dotenv_values(dotenv_path)
-        else:
-            env_file_values = dotenv_values()
-
-        timeout_raw = (
-            overrides.get("timeout")
-            or env_file_values.get("OPENAI_TIMEOUT")
-            or os.getenv("OPENAI_TIMEOUT")
-        )
-        max_retries_raw = (
-            overrides.get("max_retries")
-            or env_file_values.get("OPENAI_MAX_RETRIES")
-            or os.getenv("OPENAI_MAX_RETRIES")
-        )
+
+        def first_non_none(*candidates: Any) -> Any:
+            for candidate in candidates:
+                if candidate is not None:
+                    return candidate
+            return None
+
+        def resolve_value(override_key: str, env_var: str) -> Any:
+            if dotenv_path is not None:
+                return first_non_none(
+                    overrides.get(override_key),
+                    env_file_values.get(env_var),
+                    os.getenv(env_var),
+                )
+            return first_non_none(
+                overrides.get(override_key),
+                os.getenv(env_var),
+            )
+
+        timeout_raw = resolve_value("timeout", "OPENAI_TIMEOUT")
+        max_retries_raw = resolve_value("max_retries", "OPENAI_MAX_RETRIES")
 
         values: dict[str, Any] = {
-            "api_key": overrides.get("api_key")
-            or env_file_values.get("OPENAI_API_KEY")
-            or os.getenv("OPENAI_API_KEY"),
-            "org_id": overrides.get("org_id")
-            or env_file_values.get("OPENAI_ORG_ID")
-            or os.getenv("OPENAI_ORG_ID"),
-            "project_id": overrides.get("project_id")
-            or env_file_values.get("OPENAI_PROJECT_ID")
-            or os.getenv("OPENAI_PROJECT_ID"),
-            "base_url": overrides.get("base_url")
-            or env_file_values.get("OPENAI_BASE_URL")
-            or os.getenv("OPENAI_BASE_URL"),
-            "default_model": overrides.get("default_model")
-            or env_file_values.get("OPENAI_MODEL")
-            or os.getenv("OPENAI_MODEL"),
+            "api_key": resolve_value("api_key", "OPENAI_API_KEY"),
+            "org_id": resolve_value("org_id", "OPENAI_ORG_ID"),
+            "project_id": resolve_value("project_id", "OPENAI_PROJECT_ID"),
+            "base_url": resolve_value("base_url", "OPENAI_BASE_URL"),
+            "default_model": resolve_value("default_model", "OPENAI_MODEL"),
             "timeout": coerce_optional_float(timeout_raw),
             "max_retries": coerce_optional_int(max_retries_raw),
             "extra_client_kwargs": coerce_dict(overrides.get("extra_client_kwargs")),

openai_sdk_helpers/prompt/base.py

@@ -2,12 +2,14 @@
 
 This module provides the PromptRenderer class for loading and rendering
 Jinja2 templates with context variables. Templates can be loaded from a
-specified directory or by absolute path.
+specified directory or by absolute path. Includes template caching for
+improved performance.
 """
 
 from __future__ import annotations
 
 import warnings
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
@@ -23,7 +25,8 @@ class PromptRenderer:
 
     Loads and renders Jinja2 templates from a base directory or by absolute
     path. The renderer supports variable substitution, template inheritance,
-    and all standard Jinja2 features for creating dynamic prompts.
+    and all standard Jinja2 features for creating dynamic prompts. Templates
+    are cached using LRU cache for improved performance on repeated renders.
 
     Templates are loaded from a base directory (defaulting to the built-in
     prompt package directory) or can be specified with absolute paths.
@@ -38,6 +41,8 @@ class PromptRenderer:
     -------
     render(template_path, context=None)
         Render a Jinja2 template with the given context variables.
+    clear_cache()
+        Clear the template compilation cache.
 
     Examples
     --------
@@ -103,12 +108,30 @@ class PromptRenderer:
             autoescape=False,  # Prompts are plain text
         )
 
+    @lru_cache(maxsize=128)
+    def _compile_template(self, template_path_str: str) -> Template:
+        """Compile a template by path with LRU caching.
+
+        Parameters
+        ----------
+        template_path_str : str
+            Absolute path to the template file.
+
+        Returns
+        -------
+        Template
+            Compiled Jinja2 template ready for rendering.
+        """
+        template_text = Path(template_path_str).read_text()
+        return Template(template_text)
+
     def render(self, template_path: str, context: dict[str, Any] | None = None) -> str:
         """Render a Jinja2 template with the given context variables.
 
         Loads the template from either an absolute path or a path relative
         to the base directory. The template is rendered with the provided
-        context dictionary using Jinja2's template engine.
+        context dictionary using Jinja2's template engine. Templates are
+        cached for improved performance on repeated renders.
 
         For security, relative paths are validated to prevent path traversal
         attacks. Absolute paths are allowed but should be used with caution
@@ -135,6 +158,8 @@ class PromptRenderer:
         InputValidationError
             If the path contains suspicious patterns or attempts to escape
             the base directory.
+        TemplateNotFound
+            If the template cannot be loaded by Jinja2.
 
         Examples
         --------
@@ -164,9 +189,34 @@ class PromptRenderer:
                 base_dir=self.base_dir,
                 field_name="template_path",
             )
-        template_path_text = template_path_.read_text()
-        template = Template(template_path_text)
+
+        # Check if template exists and provide clear error message
+        if not template_path_.exists():
+            raise FileNotFoundError(
+                f"Template not found: {template_path_}. "
+                f"Ensure the template exists in {self.base_dir} or provide an absolute path."
+            )
+
+        # Cache-compile template by path (not by content)
+        template = self._compile_template(str(template_path_))
         return template.render(context or {})
 
+    def clear_cache(self) -> None:
+        """Clear the template compilation cache.
+
+        Useful when templates are modified during runtime and need to be
+        reloaded. Call this method to force re-compilation of all templates
+        on next render.
+
+        Examples
+        --------
+        >>> renderer = PromptRenderer()
+        >>> renderer.render("template.jinja", {})  # Compiles and caches
+        >>> # ... modify template.jinja ...
+        >>> renderer.clear_cache()  # Clear cache
+        >>> renderer.render("template.jinja", {})  # Re-compiles
+        """
+        self._compile_template.cache_clear()
+
 
 __all__ = ["PromptRenderer"]

openai_sdk_helpers/response/__init__.py

@@ -33,20 +33,23 @@ attach_vector_store
 from __future__ import annotations
 
 from .base import BaseResponse
-from .config import ResponseConfiguration
+from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_async, run_streamed, run_sync
-from .tool_call import ResponseToolCall
+from .tool_call import ResponseToolCall, parse_tool_arguments
 from .vector_store import attach_vector_store
 
 __all__ = [
     "BaseResponse",
     "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
     "ResponseMessage",
     "ResponseMessages",
     "run_sync",
     "run_async",
     "run_streamed",
     "ResponseToolCall",
+    "parse_tool_arguments",
     "attach_vector_store",
 ]

openai_sdk_helpers/response/config.py

@@ -15,6 +15,148 @@ TIn = TypeVar("TIn", bound="BaseStructure")
 TOut = TypeVar("TOut", bound="BaseStructure")
 
 
+class ResponseRegistry:
+    """Registry for managing ResponseConfiguration instances.
+
+    Provides centralized storage and retrieval of response configurations,
+    enabling reusable response specs across the application. Configurations
+    are stored by name and can be retrieved or listed as needed.
+
+    Methods
+    -------
+    register(config)
+        Add a ResponseConfiguration to the registry.
+    get(name)
+        Retrieve a configuration by name.
+    list_names()
+        Return all registered configuration names.
+    clear()
+        Remove all registered configurations.
+
+    Examples
+    --------
+    >>> registry = ResponseRegistry()
+    >>> config = ResponseConfiguration(
+    ...     name="test",
+    ...     instructions="Test instructions",
+    ...     tools=None,
+    ...     input_structure=None,
+    ...     output_structure=None
+    ... )
+    >>> registry.register(config)
+    >>> retrieved = registry.get("test")
+    >>> retrieved.name
+    'test'
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry."""
+        self._configs: dict[str, ResponseConfiguration] = {}
+
+    def register(self, config: ResponseConfiguration) -> None:
+        """Add a ResponseConfiguration to the registry.
+
+        Parameters
+        ----------
+        config : ResponseConfiguration
+            Configuration to register.
+
+        Raises
+        ------
+        ValueError
+            If a configuration with the same name is already registered.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> config = ResponseConfiguration(...)
+        >>> registry.register(config)
+        """
+        if config.name in self._configs:
+            raise ValueError(
+                f"Configuration '{config.name}' is already registered. "
+                "Use a unique name or clear the registry first."
+            )
+        self._configs[config.name] = config
+
+    def get(self, name: str) -> ResponseConfiguration:
+        """Retrieve a configuration by name.
+
+        Parameters
+        ----------
+        name : str
+            Configuration name to look up.
+
+        Returns
+        -------
+        ResponseConfiguration
+            The registered configuration.
+
+        Raises
+        ------
+        KeyError
+            If no configuration with the given name exists.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> config = registry.get("test")
+        """
+        if name not in self._configs:
+            raise KeyError(
+                f"No configuration named '{name}' found. "
+                f"Available: {list(self._configs.keys())}"
+            )
+        return self._configs[name]
+
+    def list_names(self) -> list[str]:
+        """Return all registered configuration names.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of configuration names.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> registry.list_names()
+        []
+        """
+        return sorted(self._configs.keys())
+
+    def clear(self) -> None:
+        """Remove all registered configurations.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> registry.clear()
+        """
+        self._configs.clear()
+
+
+# Global default registry instance
+_default_registry = ResponseRegistry()
+
+
+def get_default_registry() -> ResponseRegistry:
+    """Return the global default registry instance.
+
+    Returns
+    -------
+    ResponseRegistry
+        Singleton registry for application-wide configuration storage.
+
+    Examples
+    --------
+    >>> registry = get_default_registry()
+    >>> config = ResponseConfiguration(...)
+    >>> registry.register(config)
+    """
+    return _default_registry
+
+
 @dataclass(frozen=True, slots=True)
 class ResponseConfiguration(Generic[TIn, TOut]):
     """

openai_sdk_helpers/response/tool_call.py

@@ -94,17 +94,20 @@ class ResponseToolCall:
         return function_call, function_call_output
 
 
-def parse_tool_arguments(arguments: str) -> dict:
+def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
     """Parse tool call arguments with fallback for malformed JSON.
 
     Attempts to parse arguments as JSON first, then falls back to
     ast.literal_eval for cases where the OpenAI API returns minor
     formatting issues like single quotes instead of double quotes.
+    Provides clear error context including tool name and raw payload.
 
     Parameters
     ----------
     arguments : str
         Raw argument string from a tool call, expected to be JSON.
+    tool_name : str
+        Tool name for improved error context (required).
 
     Returns
     -------
@@ -115,13 +118,14 @@ def parse_tool_arguments(arguments: str) -> dict:
     ------
     ValueError
         If the arguments cannot be parsed as valid JSON or Python literal.
+        Error message includes tool name and payload excerpt for debugging.
 
     Examples
     --------
-    >>> parse_tool_arguments('{"key": "value"}')
+    >>> parse_tool_arguments('{"key": "value"}', tool_name="search")
     {'key': 'value'}
 
-    >>> parse_tool_arguments("{'key': 'value'}")
+    >>> parse_tool_arguments("{'key': 'value'}", tool_name="search")
     {'key': 'value'}
     """
     try:
@@ -130,4 +134,11 @@ def parse_tool_arguments(arguments: str) -> dict:
         try:
             return ast.literal_eval(arguments)
         except Exception as exc:  # noqa: BLE001
-            raise ValueError(f"Invalid JSON arguments: {arguments}") from exc
+            # Build informative error message with context
+            payload_preview = (
+                arguments[:100] + "..." if len(arguments) > 100 else arguments
+            )
+            raise ValueError(
+                f"Failed to parse tool arguments for tool '{tool_name}'. "
+                f"Raw payload: {payload_preview}"
+            ) from exc

openai_sdk_helpers/structure/__init__.py

@@ -86,6 +86,9 @@ __all__ = [
     "AgentEnum",
     "TaskStructure",
     "PlanStructure",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
     "PromptStructure",
     "SummaryTopic",
     "SummaryStructure",

openai_sdk_helpers/structure/plan/__init__.py

@@ -2,7 +2,8 @@
 
 This package provides Pydantic models for representing agent execution plans,
 including task definitions, agent type enumerations, and plan structures with
-sequential execution support.
+sequential execution support. Also includes helper functions for creating and
+executing plans.
 
 Classes
 -------
@@ -12,6 +13,15 @@ TaskStructure
     Individual agent task with status tracking and results.
 AgentEnum
     Enumeration of available agent types.
+
+Functions
+---------
+create_plan
+    Create a PlanStructure from a sequence of tasks.
+execute_task
+    Execute a single task with an agent callable.
+execute_plan
+    Execute a complete plan using registered agent callables.
 """
 
 from __future__ import annotations
@@ -19,9 +29,13 @@ from __future__ import annotations
 from .plan import PlanStructure
 from .task import TaskStructure
 from .enum import AgentEnum
+from .helpers import create_plan, execute_task, execute_plan
 
 __all__ = [
     "PlanStructure",
     "TaskStructure",
     "AgentEnum",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
 ]

openai_sdk_helpers/structure/plan/helpers.py

@@ -0,0 +1,172 @@
+"""Helper functions for creating and executing agent plans.
+
+This module provides convenience functions for working with PlanStructure
+and TaskStructure, simplifying common workflows like plan creation, task
+execution, and result aggregation.
+"""
+
+from __future__ import annotations
+
+from .enum import AgentEnum
+from .plan import PlanStructure
+from .task import TaskStructure
+from .types import AgentCallable, AgentRegistry
+
+
+def create_plan(*tasks: TaskStructure) -> PlanStructure:
+    """Create a PlanStructure from a sequence of tasks.
+
+    Convenience factory function that constructs a plan from individual
+    tasks. Tasks are executed in the order they are provided.
+
+    Parameters
+    ----------
+    *tasks : TaskStructure
+        Variable number of task definitions to include in the plan.
+
+    Returns
+    -------
+    PlanStructure
+        New plan containing the provided tasks in order.
+
+    Examples
+    --------
+    >>> task1 = TaskStructure(
+    ...     task_type=AgentEnum.WEB_SEARCH,
+    ...     prompt="Search for AI trends"
+    ... )
+    >>> task2 = TaskStructure(
+    ...     task_type=AgentEnum.SUMMARIZER,
+    ...     prompt="Summarize findings"
+    ... )
+    >>> plan = create_plan(task1, task2)
+    >>> len(plan)
+    2
+    """
+    return PlanStructure(tasks=list(tasks))
+
+
+def execute_task(
+    task: TaskStructure,
+    agent_callable: AgentCallable,
+) -> list[str]:
+    """Execute a single task with an agent callable.
+
+    Runs one task using the provided agent function. Updates task status,
+    timing, and results. Context from previous tasks is not supported in this
+    helper - use execute_plan() for multi-task execution with context passing.
+
+    Parameters
+    ----------
+    task : TaskStructure
+        Task definition containing prompt and metadata.
+    agent_callable : AgentCallable
+        Synchronous or asynchronous callable responsible for executing the task.
+        Should accept the task prompt and an optional context keyword argument.
+
+    Returns
+    -------
+    list[str]
+        Normalized string results from task execution.
+
+    Raises
+    ------
+    Exception
+        Any exception raised by the agent_callable is propagated after
+        task status is updated.
+
+    Examples
+    --------
+    >>> def agent_fn(prompt, context=None):
+    ...     return f"Result for {prompt}"
+    >>> task = TaskStructure(prompt="Test task")
+    >>> results = execute_task(task, agent_fn)
+    >>> task.status
+    'done'
+    """
+    from datetime import datetime, timezone
+
+    task.start_date = datetime.now(timezone.utc)
+    task.status = "running"
+
+    # Build plan with single task and execute
+    # Normalize task_type to string value for registry key to match PlanStructure.execute lookup
+    plan = PlanStructure(tasks=[task])
+    # Convert AgentEnum to its string value for registry key
+    registry_key = (
+        task.task_type.value
+        if isinstance(task.task_type, AgentEnum)
+        else task.task_type
+    )
+    registry: dict[str, AgentCallable] = {
+        registry_key: agent_callable,
+    }
+
+    # Execute the plan - it will update task status
+    aggregated = plan.execute(
+        agent_registry=registry,
+        halt_on_error=True,
+    )
+
+    # If task failed, raise the exception
+    if task.status == "error":
+        # Extract error message from results
+        error_msg = task.results[0] if task.results else "Task execution failed"
+        # Raise RuntimeError with the error message
+        # The original exception type information is lost but the message is preserved
+        raise RuntimeError(f"Task execution error: {error_msg}")
+
+    return aggregated
+
+
+def execute_plan(
+    plan: PlanStructure,
+    agent_registry: AgentRegistry,
+    halt_on_error: bool = True,
+) -> list[str]:
+    """Execute a plan using registered agent callables.
+
+    Convenience wrapper around PlanStructure.execute() for cleaner syntax.
+    Runs all tasks in sequence, passing results between tasks as context.
+
+    Parameters
+    ----------
+    plan : PlanStructure
+        Plan containing ordered tasks to execute.
+    agent_registry : AgentRegistry
+        Lookup of agent identifiers to callables. Keys may be AgentEnum
+        instances or their string values.
+    halt_on_error : bool, default True
+        Whether execution should stop when a task raises an exception.
+
+    Returns
+    -------
+    list[str]
+        Flattened list of normalized outputs from all executed tasks.
+
+    Raises
+    ------
+    KeyError
+        If a task references an agent not in the registry.
+
+    Examples
+    --------
+    >>> def search_agent(prompt, context=None):
+    ...     return ["search results"]
+    >>> def summary_agent(prompt, context=None):
+    ...     return ["summary"]
+    >>> registry = {
+    ...     AgentEnum.WEB_SEARCH: search_agent,
+    ...     AgentEnum.SUMMARIZER: summary_agent,
+    ... }
+    >>> plan = PlanStructure(tasks=[...])  # doctest: +SKIP
+    >>> results = execute_plan(plan, registry)  # doctest: +SKIP
+    """
+    return plan.execute(agent_registry, halt_on_error=halt_on_error)
+
+
+__all__ = [
+    "create_plan",
+    "execute_task",
+    "execute_plan",
+]

openai_sdk_helpers/structure/plan/plan.py

@@ -10,12 +10,13 @@ import asyncio
 import inspect
 import threading
 from datetime import datetime, timezone
-from typing import Any, Awaitable, Callable, Coroutine, cast
+from typing import Any, Awaitable, Coroutine, cast
 from collections.abc import Mapping
 
 from .enum import AgentEnum
 from ..base import BaseStructure, spec_field
 from .task import TaskStructure
+from .types import AgentCallable, AgentRegistry
 
 
 class PlanStructure(BaseStructure):
@@ -108,9 +109,7 @@ class PlanStructure(BaseStructure):
 
     def execute(
         self,
-        agent_registry: Mapping[
-            AgentEnum | str, Callable[..., object | Coroutine[Any, Any, object]]
-        ],
+        agent_registry: AgentRegistry,
         *,
         halt_on_error: bool = True,
     ) -> list[str]:
@@ -121,7 +120,7 @@ class PlanStructure(BaseStructure):
 
         Parameters
         ----------
-        agent_registry : Mapping[AgentEnum | str, Callable[..., Any]]
+        agent_registry : AgentRegistry
             Lookup of agent identifiers to callables. Keys may be AgentEnum
             instances or their string values. Each callable receives the task
             prompt (augmented with prior context) and an optional context
@@ -147,13 +146,18 @@ class PlanStructure(BaseStructure):
         >>> plan = PlanStructure(tasks=[TaskStructure(prompt="Test")])
         >>> results = plan.execute(registry)  # doctest: +SKIP
         """
+        normalized_registry: dict[str, AgentCallable] = {
+            self._resolve_registry_key(key): value
+            for key, value in agent_registry.items()
+        }
+
         aggregated_results: list[str] = []
         for task in self.tasks:
             callable_key = self._resolve_registry_key(task.task_type)
-            if callable_key not in agent_registry:
+            if callable_key not in normalized_registry:
                 raise KeyError(f"No agent registered for '{callable_key}'.")
 
-            agent_callable = agent_registry[callable_key]
+            agent_callable = normalized_registry[callable_key]
             task.start_date = datetime.now(timezone.utc)
             task.status = "running"
 
@@ -207,7 +211,7 @@ class PlanStructure(BaseStructure):
     def _run_task(
         task: TaskStructure,
         *,
-        agent_callable: Callable[..., object | Coroutine[Any, Any, object]],
+        agent_callable: AgentCallable,
         aggregated_context: list[str],
     ) -> object | Coroutine[Any, Any, object]:
         """Execute a single task using the supplied callable.
@@ -219,7 +223,7 @@ class PlanStructure(BaseStructure):
         ----------
         task : TaskStructure
             Task definition containing inputs and metadata.
-        agent_callable : Callable[..., Any]
+        agent_callable : AgentCallable
             Function responsible for performing the task.
         aggregated_context : list[str]
             Accumulated results from previously executed tasks.

openai_sdk_helpers/structure/plan/types.py

@@ -0,0 +1,15 @@
+"""Type aliases for plan execution helpers."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, Callable, Coroutine, TypeAlias
+
+from .enum import AgentEnum
+
+AgentCallable = Callable[..., object | Coroutine[Any, Any, object]]
+AgentRegistry: TypeAlias = (
+    Mapping[str, AgentCallable] | Mapping[AgentEnum, AgentCallable]
+)
+
+__all__ = ["AgentCallable", "AgentRegistry"]

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/utils/__init__.py

@@ -1,8 +1,8 @@
 """Utility helpers for openai-sdk-helpers.
 
 This package provides common utility functions for type coercion, file
-handling, JSON serialization, and logging. These utilities are used
-throughout the openai_sdk_helpers package.
+handling, JSON serialization, logging, and OpenAI settings construction.
+These utilities are used throughout the openai_sdk_helpers package.
 
 Functions
 ---------
@@ -20,6 +20,8 @@ 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
 -------
@@ -33,6 +35,7 @@ from __future__ import annotations
 
 from .core import (
     JSONSerializable,
+    build_openai_settings,
     check_filepath,
     coerce_jsonable,
     coerce_dict,
@@ -53,4 +56,5 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
+    "build_openai_settings",
 ]

openai_sdk_helpers/utils/core.py

@@ -143,6 +143,130 @@ def coerce_dict(value: object) -> dict[str, Any]:
     raise TypeError("extra_client_kwargs must be a mapping or None")
 
 
+def build_openai_settings(
+    api_key: str | None = None,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    base_url: str | None = None,
+    default_model: str | None = None,
+    timeout: float | str | None = None,
+    max_retries: int | str | None = None,
+    dotenv_path: Path | None = None,
+    **extra_kwargs: Any,
+) -> Any:  # Returns OpenAISettings but use Any to avoid circular import
+    """Build OpenAI settings from environment with explicit validation.
+
+    Convenience function for creating OpenAISettings with validation and
+    clear error messages. Reads from environment variables and validates
+    required fields, with explicit type coercion for timeout and max_retries.
+
+    Parameters
+    ----------
+    api_key : str or None, default None
+        API key for OpenAI authentication. If None, reads from OPENAI_API_KEY.
+    org_id : str or None, default None
+        Organization ID. If None, reads from OPENAI_ORG_ID.
+    project_id : str or None, default None
+        Project ID. If None, reads from OPENAI_PROJECT_ID.
+    base_url : str or None, default None
+        Base URL for API requests. If None, reads from OPENAI_BASE_URL.
+    default_model : str or None, default None
+        Default model name. If None, reads from OPENAI_MODEL.
+    timeout : float, str, or None, default None
+        Request timeout in seconds. If None, reads from OPENAI_TIMEOUT.
+        Can be string that will be parsed to float.
+    max_retries : int, str, or None, default None
+        Maximum retry attempts. If None, reads from OPENAI_MAX_RETRIES.
+        Can be string that will be parsed to int.
+    dotenv_path : Path or None, default None
+        Path to .env file. If None, searches for .env in current directory.
+    **extra_kwargs : Any
+        Additional keyword arguments for extra_client_kwargs.
+
+    Returns
+    -------
+    OpenAISettings
+        Configured settings instance.
+
+    Raises
+    ------
+    ValueError
+        If OPENAI_API_KEY is not found in environment or parameters.
+        If timeout cannot be parsed as float.
+        If max_retries cannot be parsed as int.
+    TypeError
+        If timeout or max_retries have invalid types.
+
+    Examples
+    --------
+    Build from explicit parameters:
+
+    >>> settings = build_openai_settings(
+    ...     api_key="sk-...",
+    ...     default_model="gpt-4o",
+    ...     timeout=30.0
+    ... )
+
+    Build from environment:
+
+    >>> settings = build_openai_settings()  # doctest: +SKIP
+
+    With custom .env location:
+
+    >>> settings = build_openai_settings(
+    ...     dotenv_path=Path("/path/to/.env")
+    ... )  # doctest: +SKIP
+    """
+    # Import at runtime to avoid circular import
+    from openai_sdk_helpers.config import OpenAISettings
+
+    # Parse timeout with validation
+    parsed_timeout: float | None = None
+    if timeout is not None:
+        try:
+            parsed_timeout = coerce_optional_float(timeout)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid timeout value '{timeout}'. Must be a number or numeric string."
+            ) from exc
+
+    # Parse max_retries with validation
+    parsed_max_retries: int | None = None
+    if max_retries is not None:
+        try:
+            parsed_max_retries = coerce_optional_int(max_retries)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid max_retries value '{max_retries}'. "
+                "Must be an integer or numeric string."
+            ) from exc
+
+    # Build settings using from_env with overrides
+    overrides = {}
+    if api_key is not None:
+        overrides["api_key"] = api_key
+    if org_id is not None:
+        overrides["org_id"] = org_id
+    if project_id is not None:
+        overrides["project_id"] = project_id
+    if base_url is not None:
+        overrides["base_url"] = base_url
+    if default_model is not None:
+        overrides["default_model"] = default_model
+    if parsed_timeout is not None:
+        overrides["timeout"] = parsed_timeout
+    if parsed_max_retries is not None:
+        overrides["max_retries"] = parsed_max_retries
+    if extra_kwargs:
+        overrides["extra_client_kwargs"] = extra_kwargs
+
+    try:
+        return OpenAISettings.from_env(dotenv_path=dotenv_path, **overrides)
+    except ValueError as exc:
+        # Re-raise with more context but preserve original message
+        raise ValueError(f"Failed to build OpenAI settings: {exc}") from exc
+
+
 T = TypeVar("T")
 _configured_logging = False
 
@@ -465,4 +589,8 @@ __all__ = [
     "JSONSerializable",
     "customJSONEncoder",
     "log",
+    "coerce_optional_float",
+    "coerce_optional_int",
+    "coerce_dict",
+    "build_openai_settings",
 ]

{openai_sdk_helpers-0.0.9.dist-info → openai_sdk_helpers-0.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.9
+Version: 0.1.0
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

{openai_sdk_helpers-0.0.9.dist-info → openai_sdk_helpers-0.1.0.dist-info}/RECORD

@@ -1,12 +1,13 @@
-openai_sdk_helpers/__init__.py,sha256=rXQ5KjONsOf1aN31NKXfljN7FlEvxg8s29Z6LkIG3fw,3231
+openai_sdk_helpers/__init__.py,sha256=yFWF1rBF8-mCVPK-_PfiCaBMIVl_NGvJb4wySXWenhg,3765
 openai_sdk_helpers/async_utils.py,sha256=_GPiSDQhWehiZu2S_jB_Xgl0p2qGc5MNu1NN92zz3bg,3726
-openai_sdk_helpers/config.py,sha256=ChJmSfi71T3LyNYhsNpJF_bho1a3d5vCGIRD0IwLh9o,7662
+openai_sdk_helpers/config.py,sha256=841YGiUu7hvFrB2Bdr6ck4YKCtb2HRI0Uhk6HKpIqAc,7640
 openai_sdk_helpers/context_manager.py,sha256=9z54rjcJ-nAFdEoZHjFdk1YYpeD9bet13MOgn23FzM8,6629
 openai_sdk_helpers/environment.py,sha256=HSPI1h1JUuMxzcTSvr28ktHBvyEJLRzL4bZhNfy59lI,1372
 openai_sdk_helpers/errors.py,sha256=oytqn-6Jg6nPMQOP956ftfkLS0R5c1XBDX-lNstrb3Y,3135
 openai_sdk_helpers/logging_config.py,sha256=fOKBgisOkM0VYDt68pmUSxVWzTeO25_u-El0HOxqEYM,2928
 openai_sdk_helpers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openai_sdk_helpers/retry.py,sha256=3I5cZOq5X6d7kno3fk1SVDYJ7U2VDHqBS7ZsaXWbU6A,6529
+openai_sdk_helpers/tools.py,sha256=MW6bdJH9Ij16LKNCNNvSthq206T-orTOQTLFzLWxQTo,6043
 openai_sdk_helpers/types.py,sha256=xzldCRfwCZ3rZl18IBmfgA-PVdoZKSWNrlSIhirumSo,1451
 openai_sdk_helpers/validation.py,sha256=fr3zVZ7uEokJJqF3LSIcQm4wV3MvWXcep2ZRpseXZBk,7789
 openai_sdk_helpers/agent/__init__.py,sha256=giowU8jke0z0h7FFUG9V6Vssja8AYwvJMQbiMb3s64k,960
@@ -26,22 +27,22 @@ openai_sdk_helpers/agent/search/web.py,sha256=8le4xnZ3nllySqWb7rZaOq44ZR8q67c_Wi
 openai_sdk_helpers/enums/__init__.py,sha256=aFf79C4JBeLC3kMlJfSpehyjx5uNCtW6eK5rD6ZFfhM,322
 openai_sdk_helpers/enums/base.py,sha256=cNllDtzcgI0_eZYXxFko14yhxwicX6xbeDfz9gFE3qo,2753
 openai_sdk_helpers/prompt/__init__.py,sha256=MOqgKwG9KLqKudoKRlUfLxiSmdOi2aD6hNrWDFqLHkk,418
-openai_sdk_helpers/prompt/base.py,sha256=4VJFmJozVmKQ04dqm8jYSiOijcQbT0CSAll2NE8zF68,5734
+openai_sdk_helpers/prompt/base.py,sha256=FvQNEjIdYDLvGEiR9_dbEn6G47TPMsWm4r26jcLjgus,7569
 openai_sdk_helpers/prompt/summarizer.jinja,sha256=jliSetWDISbql1EkWi1RB8-L_BXUg8JMkRRsPRHuzbY,309
 openai_sdk_helpers/prompt/translator.jinja,sha256=SZhW8ipEzM-9IA4wyS_r2wIMTAclWrilmk1s46njoL0,291
 openai_sdk_helpers/prompt/validator.jinja,sha256=6t8q_IdxFd3mVBGX6SFKNOert1Wo3YpTOji2SNEbbtE,547
-openai_sdk_helpers/response/__init__.py,sha256=BbKIigsEVQGbxRSBp9FSLPM9OYsEndKHZpGHonnu8P4,1599
+openai_sdk_helpers/response/__init__.py,sha256=eoQF086o3OZYmVfJWXhSpYlPhQBb-VLDA5hvw7guLEc,1741
 openai_sdk_helpers/response/base.py,sha256=-d-vvY4OId_MU6EAN55bBPEftnskw9Ry8TVQ705f9Xw,27965
-openai_sdk_helpers/response/config.py,sha256=kSsZtDT9JYK8KgF3OaFeeP2rhGtSsFlw535HJoPqpUk,6523
+openai_sdk_helpers/response/config.py,sha256=WheEWkTxNFHL54_yvFY3M0LclNmajwTiMftSFeAH2eI,10300
 openai_sdk_helpers/response/messages.py,sha256=oVSHpSV_iQxHreCXm--a6MlHg_kkElQi3R2Y8Y7VphA,9134
 openai_sdk_helpers/response/runner.py,sha256=Rf13cQGsR7sN9gA81Y5th1tfH2DCCAwQ6RMs3bVgjnk,4269
-openai_sdk_helpers/response/tool_call.py,sha256=218mWOj-QGW3IwVsgnSurSRWRcdUiFT-5C44Zn_m4pQ,3943
+openai_sdk_helpers/response/tool_call.py,sha256=VYPvKUR-Ren0Y_nYS4jUSinhTyXKzFwQLxu-d3r_YuM,4506
 openai_sdk_helpers/response/vector_store.py,sha256=MyHUu6P9ueNsd9erbBkyVqq3stLK6qVuehdvmFAHq9E,3074
 openai_sdk_helpers/streamlit_app/__init__.py,sha256=RjJbnBDS5_YmAmxvaa3phB5u9UcXsXDEk_jMlY_pa5Q,793
 openai_sdk_helpers/streamlit_app/app.py,sha256=ID3B4fUQHvv1Cwuuvrlm4nK4d0nWL6uBE40O_T6r7yY,10808
 openai_sdk_helpers/streamlit_app/config.py,sha256=EK6LWACo7YIkDko1oesvupOx56cTuWWnwnXRiu8EYbs,15986
 openai_sdk_helpers/streamlit_app/streamlit_web_search.py,sha256=OrX-kgW_yaHgIsK6wY9gBVLbvDaMFXgkgdhKQDsA8kQ,2506
-openai_sdk_helpers/structure/__init__.py,sha256=YI15qqUr2hezDJoShUfhEfRWcO2iEe9CQEBM5tAQQB4,3280
+openai_sdk_helpers/structure/__init__.py,sha256=QUvRdJMbKsumjwJdWq9ihfcOED4ZbJMBQbmA1nmYJVw,3339
 openai_sdk_helpers/structure/agent_blueprint.py,sha256=2W-RBM5G3ZefMcYHqqoV6Y1witcSbMlUpdU1CA9n3tg,9698
 openai_sdk_helpers/structure/base.py,sha256=7RMsCMjQR7u3mksirqd0E6AgCgWEMVRQtgNefwHWPGo,28278
 openai_sdk_helpers/structure/prompt.py,sha256=7DBdLu6WDvXy2RkEBayDiX2Jn8T4-hJuohsOaKEoqJs,1075
@@ -50,17 +51,19 @@ openai_sdk_helpers/structure/summary.py,sha256=MyZzMuqHP9F8B4rYYxCGJwojy5RavWUkM
 openai_sdk_helpers/structure/validation.py,sha256=vsilA3Qs3fjWLeYlnZnMEGj9i_bOJtXc2J3mSIEHncg,2409
 openai_sdk_helpers/structure/vector_search.py,sha256=A0w2AR0r6aIFoYbNkscUAGT7VzTe6WuvxrqUsWT2PMQ,5782
 openai_sdk_helpers/structure/web_search.py,sha256=S8OdllBWqEGXaKf6Alocl89ZuG7BlvXK5ra1Lm7lfjE,4572
-openai_sdk_helpers/structure/plan/__init__.py,sha256=0kLN6n3wTAFuOvCOWiDrreWpv6RX4ycD4HNhVqF4pTs,667
+openai_sdk_helpers/structure/plan/__init__.py,sha256=IGr0Tk4inN_8o7fT2N02_FTi6U6l2T9_npcQHAlBwKA,1076
 openai_sdk_helpers/structure/plan/enum.py,sha256=seESSwH-IeeW-9BqIMUQyk3qjtchfU3TDhF9HPDB1OM,3079
-openai_sdk_helpers/structure/plan/plan.py,sha256=Rc8vwY2RmDrRRhVtiOv0BXjoRKn3T1RGY0Pi3wRvLjk,9602
+openai_sdk_helpers/structure/plan/helpers.py,sha256=25qXUMPY73y3E6EsE88n9VBwNj2JZkzXy1AaWGsoSLw,5132
+openai_sdk_helpers/structure/plan/plan.py,sha256=LtfwWwZiHGe06nFCXSbT8p3x3w9hhI0wXS7hTeeWXvY,9663
 openai_sdk_helpers/structure/plan/task.py,sha256=2dH8iaLhjC7MKZEW1T_HICaggi1RPyKSPOl9ORmmYdg,4538
-openai_sdk_helpers/utils/__init__.py,sha256=L4U5uaBIt0nIV-GhFc5Kotx9h69SryoCmfJL9u23IJU,1388
-openai_sdk_helpers/utils/core.py,sha256=XvQePx0CDkcwkENAatcPwF9H_b4N5nedlIX3viW2RtM,12684
+openai_sdk_helpers/structure/plan/types.py,sha256=7y9QEVdZreQUXV7n-R4RoNZzw5HeOVbJGWx9QkSfuNY,418
+openai_sdk_helpers/utils/__init__.py,sha256=oNMc8xyOGmXLNIOjwC5EhN8Jjy_S74Vgwzzg41RNb4g,1566
+openai_sdk_helpers/utils/core.py,sha256=Ehm9WePZTl9ypbbKlHNiyRkhI4a5ZhbDwKiSJTNTgz8,17262
 openai_sdk_helpers/vector_storage/__init__.py,sha256=L5LxO09puh9_yBB9IDTvc1CvVkARVkHqYY1KX3inB4c,975
 openai_sdk_helpers/vector_storage/cleanup.py,sha256=ImWIE-9lli-odD8qIARvmeaa0y8ZD4pYYP-kT0O3178,3552
 openai_sdk_helpers/vector_storage/storage.py,sha256=ZiTZnvCY28R-WUQjHdnjQo1xIRbXAM6JL0VhqW9MM9I,21725
 openai_sdk_helpers/vector_storage/types.py,sha256=jTCcOYMeOpZWvcse0z4T3MVs-RBOPC-fqWTBeQrgafU,1639
-openai_sdk_helpers-0.0.9.dist-info/METADATA,sha256=lKUWNHXa5c7maQW4p7pQA0uM0cPSyvNf_TMce5huHlo,18492
-openai_sdk_helpers-0.0.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.0.9.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.0.9.dist-info/RECORD,,
+openai_sdk_helpers-0.1.0.dist-info/METADATA,sha256=R-Lc44fSOhAohVtwOAVW_pg3_GMHfYW5ve3bwZlIETE,18492
+openai_sdk_helpers-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.1.0.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.1.0.dist-info/RECORD,,