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

openai_sdk_helpers/structure/base.py

@@ -233,7 +233,7 @@ class BaseStructure(BaseModel):
         return prompt_lines
 
     @classmethod
-    def assistant_tool_definition(cls, name: str, description: str) -> dict:
+    def assistant_tool_definition(cls, name: str, *, description: str) -> dict:
         """Build an Assistant API function tool definition for this structure.
 
         Creates a tool definition compatible with the OpenAI Assistant API,
@@ -255,7 +255,7 @@ class BaseStructure(BaseModel):
         --------
         >>> tool = MyStructure.assistant_tool_definition(
         ...     "analyze_data",
-        ...     "Analyze the provided data"
+        ...     description="Analyze the provided data"
         ... )
         """
         from .responses import assistant_tool_definition
@@ -283,7 +283,7 @@ class BaseStructure(BaseModel):
         return assistant_format(cls)
 
     @classmethod
-    def response_tool_definition(cls, tool_name: str, tool_description: str) -> dict:
+    def response_tool_definition(cls, tool_name: str, *, tool_description: str) -> dict:
         """Build a chat completion tool definition for this structure.
 
         Creates a function tool definition compatible with the chat
@@ -305,7 +305,7 @@ class BaseStructure(BaseModel):
         --------
         >>> tool = MyStructure.response_tool_definition(
         ...     "process_data",
-        ...     "Process the input data"
+        ...     tool_description="Process the input data"
         ... )
         """
         from .responses import response_tool_definition
@@ -725,7 +725,7 @@ class BaseStructure(BaseModel):
         return cls.from_raw_input(structured_data)
 
     @staticmethod
-    def format_output(label: str, value: Any) -> str:
+    def format_output(label: str, *, value: Any) -> str:
         """
         Format a label and value for string output.
 
@@ -772,7 +772,7 @@ class BaseStructure(BaseModel):
         """
         return "\n".join(
             [
-                BaseStructure.format_output(field, value)
+                BaseStructure.format_output(field, value=value)
                 for field, value in self.model_dump().items()
             ]
         )

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,173 @@
+"""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/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/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,296 @@
+"""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.
+
+Also provides declarative tool specification helpers for building tool
+definitions from named metadata structures.
+"""
+
+from __future__ import annotations
+
+import inspect
+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:
+    """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"}'
+    """
+    if isinstance(result, BaseModel):
+        return result.model_dump_json()
+
+    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.
+
+    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
+
+
+@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",
+]