openai-sdk-helpers 0.4.3__py3-none-any.whl → 0.5.0__py3-none-any.whl

openai_sdk_helpers/agent/search/web.py

@@ -3,13 +3,14 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 from agents import custom_span, gen_trace_id, trace
 from agents.model_settings import ModelSettings
 from agents.tool import WebSearchTool
 
 from ...structure.prompt import PromptStructure
+from ..base import AgentBase
 from ...structure.web_search import (
     WebSearchItemStructure,
     WebSearchItemResultStructure,
@@ -17,10 +18,10 @@ from ...structure.web_search import (
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from ...tools import tool_handler_factory
 from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
+from ...tools import ToolSpec, ToolHandlerRegistration
 
 MAX_CONCURRENT_SEARCHES = 10
 
@@ -30,10 +31,10 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in configuration.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -43,20 +44,19 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> planner = WebAgentPlanner(default_model="gpt-4o-mini")
+    >>> planner = WebAgentPlanner(model="gpt-4o-mini")
     """
 
-    def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
-    ) -> None:
-        """Initialize the planner agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
-
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web planner agent.
 
         Returns
@@ -68,6 +68,8 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
             name="web_planner",
             instructions="Agent instructions",
             description="Agent that plans web searches based on a user query.",
+            template_path=template_path,
+            model=model,
             output_structure=WebSearchPlanStructure,
         )
 
@@ -81,10 +83,10 @@ class WebSearchToolAgent(
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in configuration.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str or None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -96,24 +98,20 @@ class WebSearchToolAgent(
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model is not provided.
 
     Examples
     --------
-    >>> tool = WebSearchToolAgent(default_model="gpt-4o-mini")
+    >>> tool = WebSearchToolAgent(model="gpt-4o-mini")
     """
 
-    def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
-    ) -> None:
-        """Initialize the search tool agent."""
-        super().__init__(
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-            max_concurrent_searches=MAX_CONCURRENT_SEARCHES,
-        )
-
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        *,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web search tool agent.
 
         Returns
@@ -125,6 +123,8 @@ class WebSearchToolAgent(
             name="web_search",
             instructions="Agent instructions",
             description="Agent that performs web searches and summarizes results.",
+            template_path=template_path,
+            model=model,
             input_structure=WebSearchPlanStructure,
             tools=[WebSearchTool()],
             model_settings=ModelSettings(tool_choice="required"),
@@ -186,10 +186,10 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in configuration.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -199,20 +199,31 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the configuration omits a model identifier.
 
     Examples
     --------
-    >>> writer = WebAgentWriter(default_model="gpt-4o-mini")
+    >>> writer = WebAgentWriter(model="gpt-4o-mini")
     """
 
     def __init__(
-        self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
     ) -> None:
         """Initialize the writer agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        configuration = self._configure_agent(
+            template_path=template_path, model=model, **kwargs
+        )
+        super().__init__(configuration=configuration)
 
-    def _configure_agent(self) -> AgentConfiguration:
+    def _configure_agent(
+        self,
+        template_path: Path | str | None = None,
+        model: str | None = None,
+        **kwargs: Any,
+    ) -> AgentConfiguration:
         """Return configuration for the web writer agent.
 
         Returns
@@ -224,19 +235,21 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
             name="web_writer",
             instructions="Agent instructions",
             description="Agent that writes a report based on web search results.",
+            template_path=template_path,
+            model=model,
             output_structure=WebSearchReportStructure,
         )
 
 
-class WebAgentSearch:
+class WebAgentSearch(AgentBase):
     """Manage the complete web search workflow.
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
-    default_model : str or None, default=None
-        Default model identifier to use when not defined in configuration.
+    template_path : Path | str | None, default=None
+        Template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -254,21 +267,36 @@ class WebAgentSearch:
     Raises
     ------
     ValueError
-        If the default model is not provided.
+        If the model identifier is not provided.
 
     Examples
     --------
-    >>> search = WebAgentSearch(default_model="gpt-4o-mini")
+    >>> search = WebAgentSearch(model="gpt-4o-mini")
     """
 
     def __init__(
         self,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        *,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
-        """Create the main web search agent."""
-        self._prompt_dir = prompt_dir
-        self._default_model = default_model
+        """Initialize the web search orchestration agent.
+
+        Parameters
+        ----------
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use when not defined in configuration.
+        """
+        configuration = AgentConfiguration(
+            name="web_agent_search",
+            instructions="Agent instructions",
+            description="Run a multi-step web search workflow.",
+            template_path=template_path,
+            model=model,
+        )
+        super().__init__(configuration=configuration)
 
     async def run_agent_async(self, search_query: str) -> WebSearchStructure:
         """Execute the entire research workflow for ``search_query``.
@@ -286,14 +314,12 @@ class WebAgentSearch:
         trace_id = gen_trace_id()
         with trace("WebAgentSearch trace", trace_id=trace_id):
             planner = WebAgentPlanner(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._template_path, model=self.model
             )
             tool = WebSearchToolAgent(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
-            )
-            writer = WebAgentWriter(
-                prompt_dir=self._prompt_dir, default_model=self._default_model
+                template_path=self._template_path, model=self.model
             )
+            writer = WebAgentWriter(template_path=self._template_path, model=self.model)
             search_plan = await planner.run_agent(query=search_query)
             search_results = await tool.run_agent(search_plan=search_plan)
             search_report = await writer.run_agent(search_query, search_results)
@@ -320,37 +346,33 @@ class WebAgentSearch:
         """
         return run_coroutine_agent_sync(self.run_agent_async(search_query))
 
-    def as_response_tool(
-        self,
-        *,
-        tool_name: str = "web_search",
-        tool_description: str = "Run the web search workflow.",
-    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
-        """Return a Responses API tool handler and definition.
+    def as_tool_registration(
+        self, tool_name: str, tool_description: str
+    ) -> ToolHandlerRegistration:
+        """Build a Responses API tool definition and handler for the web search agent.
 
         Parameters
         ----------
-        tool_name : str, default="web_search"
-            Name to use for the response tool.
-        tool_description : str, default="Run the web search workflow."
-            Description for the response tool.
+        tool_name : str
+            Name of the tool.
+        tool_description : str
+            Description of the tool.
 
         Returns
         -------
-        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
-            Tool handler mapping and tool definition for Responses API usage.
+        ToolHandlerRegistration
+            Tool definition and handler for the Responses API.
         """
-
-        def _run_search(prompt: str) -> WebSearchStructure:
-            return run_coroutine_agent_sync(self.run_agent_async(search_query=prompt))
-
-        tool_handler = {
-            tool_name: tool_handler_factory(_run_search, input_model=PromptStructure)
-        }
-        tool_definition = PromptStructure.response_tool_definition(
-            tool_name, tool_description=tool_description
+        tool_spec = ToolSpec(
+            input_structure=PromptStructure,
+            tool_name=tool_name,
+            tool_description=tool_description,
+            output_structure=WebSearchStructure,
+        )
+        return ToolHandlerRegistration(
+            handler=self.run_agent_sync,
+            tool_spec=tool_spec,
         )
-        return tool_handler, tool_definition
 
 
 __all__ = [

openai_sdk_helpers/agent/summarizer.py

@@ -3,13 +3,12 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Optional, Type
+from typing import Any, Dict, Optional
 
 from ..structure import SummaryStructure
 from ..structure.base import StructureBase
 from .base import AgentBase
 from .configuration import AgentConfiguration
-from ..environment import DEFAULT_PROMPT_DIR
 
 
 class SummarizerAgent(AgentBase):
@@ -21,11 +20,10 @@ class SummarizerAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for summarization.
     output_structure : type[StructureBase], default=SummaryStructure
         Type describing the expected summary output.
 
@@ -34,7 +32,7 @@ class SummarizerAgent(AgentBase):
     Basic usage with default settings:
 
     >>> from openai_sdk_helpers.agent import SummarizerAgent
-    >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    >>> summarizer = SummarizerAgent(model="gpt-4o-mini")
     >>> summary = summarizer.run_sync("Long text to summarize...")
     >>> print(summary.text)
 
@@ -42,7 +40,7 @@ class SummarizerAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    ...     summarizer = SummarizerAgent(model="gpt-4o-mini")
     ...     result = await summarizer.run_agent(
     ...         text="Article content...",
     ...         metadata={"source": "news.txt", "date": "2025-01-01"}
@@ -59,44 +57,38 @@ class SummarizerAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
-        output_structure: Type[StructureBase] = SummaryStructure,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the summarizer agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
-        output_structure : type[StructureBase], default=SummaryStructure
-            Type describing the expected summary output.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for summarization.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+        >>> summarizer = SummarizerAgent(model="gpt-4o-mini")
         """
         configuration = AgentConfiguration(
             name="summarizer",
             instructions="Agent instructions",
             description="Summarize passages into concise findings.",
-            output_structure=output_structure,
-        )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_directory,
-            default_model=default_model,
+            template_path=template_path,
+            output_structure=SummaryStructure,
+            model=model,
         )
 
+        super().__init__(configuration=configuration)
+
     async def run_agent(
         self, text: str, metadata: Optional[Dict[str, Any]] = None
     ) -> Any:

openai_sdk_helpers/agent/translator.py

@@ -8,7 +8,6 @@ from typing import Any, Dict, Optional
 
 from ..structure import TranslationStructure
 from ..structure.base import StructureBase
-from ..environment import DEFAULT_PROMPT_DIR
 
 from .base import AgentBase
 from .configuration import AgentConfiguration
@@ -22,18 +21,17 @@ class TranslatorAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for translation.
 
     Examples
     --------
     Basic translation:
 
     >>> from openai_sdk_helpers.agent import TranslatorAgent
-    >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
+    >>> translator = TranslatorAgent(model="gpt-4o-mini")
     >>> result = translator.run_sync("Hello world", target_language="Spanish")
     >>> print(result.text)
     'Hola mundo'
@@ -42,7 +40,7 @@ class TranslatorAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     translator = TranslatorAgent(default_model="gpt-4o-mini")
+    ...     translator = TranslatorAgent(model="gpt-4o-mini")
     ...     result = await translator.run_agent(
     ...         text="Good morning",
     ...         target_language="French",
@@ -62,40 +60,36 @@ class TranslatorAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the translation agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for translation.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
+        >>> translator = TranslatorAgent(model="gpt-4o-mini")
         """
         configuration = AgentConfiguration(
             name="translator",
             instructions="Agent instructions",
             description="Translate text into the requested language.",
+            template_path=template_path,
             output_structure=TranslationStructure,
+            model=model,
         )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_directory,
-            default_model=default_model,
-        )
+        super().__init__(configuration=configuration)
 
     async def run_agent(
         self,

openai_sdk_helpers/agent/validator.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from ..environment import DEFAULT_PROMPT_DIR
 from ..structure.validation import ValidationResultStructure
 from .base import AgentBase
 from .configuration import AgentConfiguration
@@ -20,18 +19,17 @@ class ValidatorAgent(AgentBase):
 
     Parameters
     ----------
-    prompt_dir : Path or None, default=None
-        Optional directory containing Jinja prompt templates. Defaults to the
-        packaged ``prompt`` directory when not provided.
-    default_model : str or None, default=None
-        Fallback model identifier when not specified elsewhere.
+    template_path : Path | str | None, default=None
+        Optional template file path for prompt rendering.
+    model : str | None, default=None
+        Model identifier to use for validation.
 
     Examples
     --------
     Validate user input:
 
     >>> from openai_sdk_helpers.agent import ValidatorAgent
-    >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
+    >>> validator = ValidatorAgent(model="gpt-4o-mini")
     >>> result = validator.run_sync("Tell me about Python programming")
     >>> print(result.input_safe)  # True
     >>> print(result.violations)  # []
@@ -40,7 +38,7 @@ class ValidatorAgent(AgentBase):
 
     >>> import asyncio
     >>> async def main():
-    ...     validator = ValidatorAgent(default_model="gpt-4o-mini")
+    ...     validator = ValidatorAgent(model="gpt-4o-mini")
     ...     result = await validator.run_agent(
     ...         user_input="Summarize this document",
     ...         agent_output="Summary containing PII...",
@@ -59,40 +57,36 @@ class ValidatorAgent(AgentBase):
     def __init__(
         self,
         *,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
+        template_path: Path | str | None = None,
+        model: str | None = None,
     ) -> None:
         """Initialize the validator agent configuration.
 
         Parameters
         ----------
-        prompt_dir : Path or None, default=None
-            Optional directory containing Jinja prompt templates. Defaults to the
-            packaged ``prompt`` directory when not provided.
-        default_model : str or None, default=None
-            Fallback model identifier when not specified elsewhere.
+        template_path : Path | str | None, default=None
+            Optional template file path for prompt rendering.
+        model : str | None, default=None
+            Model identifier to use for validation.
 
         Raises
         ------
         ValueError
-            If the default model is not provided.
+            If the model is not provided.
 
         Examples
         --------
-        >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
+        >>> validator = ValidatorAgent(model="gpt-4o-mini")
         """
         configuration = AgentConfiguration(
             name="validator",
             instructions="Agent instructions",
             description="Validate user input and agent output against guardrails.",
+            template_path=template_path,
             output_structure=ValidationResultStructure,
+            model=model,
         )
-        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
-        super().__init__(
-            configuration=configuration,
-            prompt_dir=prompt_directory,
-            default_model=default_model,
-        )
+        super().__init__(configuration=configuration)
 
     async def run_agent(
         self,

openai_sdk_helpers/errors.py

@@ -119,3 +119,12 @@ class ResourceCleanupError(OpenAISDKError):
     """
 
     pass
+
+
+class ExtractionError(OpenAISDKError):
+    """Extraction execution failed.
+
+    Raised when LangExtract operations fail or output validation fails.
+    """
+
+    pass

openai_sdk_helpers/extract/__init__.py

@@ -0,0 +1,23 @@
+"""LangExtract-powered document extraction helpers."""
+
+from .extractor import DocumentExtractor
+from .generator import (
+    EXTRACTOR_CONFIG_GENERATOR,
+    EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS,
+    PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS,
+    generate_document_extractor_config,
+    generate_document_extractor_config_with_agent,
+    optimize_extractor_prompt,
+    optimize_extractor_prompt_with_agent,
+)
+
+__all__ = [
+    "DocumentExtractor",
+    "EXTRACTOR_CONFIG_GENERATOR",
+    "EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS",
+    "PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS",
+    "generate_document_extractor_config",
+    "generate_document_extractor_config_with_agent",
+    "optimize_extractor_prompt",
+    "optimize_extractor_prompt_with_agent",
+]