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

openai_sdk_helpers/agent/{web_search.py → search/web.py}

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import asyncio
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
@@ -10,21 +9,21 @@ from agents import custom_span, gen_trace_id, trace
 from agents.model_settings import ModelSettings
 from agents.tool import WebSearchTool
 
-from ..structure.web_search import (
+from ...structure.web_search import (
     WebSearchItemStructure,
     WebSearchItemResultStructure,
     WebSearchStructure,
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from .base import AgentBase
-from .config import AgentConfig
-from .utils import run_coroutine_agent_sync
+from ..config import AgentConfig
+from ..utils import run_coroutine_agent_sync
+from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
 MAX_CONCURRENT_SEARCHES = 10
 
 
-class WebAgentPlanner(AgentBase):
+class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
     """Plan web searches to satisfy a user query.
 
     Methods
@@ -40,46 +39,33 @@ class WebAgentPlanner(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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 config.
+        """
+        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for the web planner agent.
 
         Returns
         -------
-        None
+        AgentConfig
+            Configuration with name, description, and output type.
         """
-        config = AgentConfig(
+        return AgentConfig(
             name="web_planner",
             description="Agent that plans web searches based on a user query.",
             output_type=WebSearchPlanStructure,
         )
-        super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
-        )
-
-    async def run_agent(self, query: str) -> WebSearchPlanStructure:
-        """Plan searches for ``query``.
-
-        Parameters
-        ----------
-        query : str
-            User search query.
-
-        Returns
-        -------
-        WebSearchPlanStructure
-            Plan describing searches to perform.
-        """
-        result: WebSearchPlanStructure = await self.run_async(
-            input=query,
-            output_type=self._output_type,
-        )
-
-        return result
 
 
-class WebSearchToolAgent(AgentBase):
+class WebSearchToolAgent(
+    SearchToolAgent[
+        WebSearchItemStructure, WebSearchItemResultStructure, WebSearchPlanStructure
+    ]
+):
     """Execute web searches defined in a plan.
 
     Methods
@@ -97,68 +83,32 @@ class WebSearchToolAgent(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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 config.
+        """
+        super().__init__(
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+            max_concurrent_searches=MAX_CONCURRENT_SEARCHES,
+        )
+
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for the web search tool agent.
 
         Returns
         -------
-        None
+        AgentConfig
+            Configuration with name, description, input type, and tools.
         """
-        config = AgentConfig(
+        return AgentConfig(
             name="web_search",
             description="Agent that performs web searches and summarizes results.",
             input_type=WebSearchPlanStructure,
             tools=[WebSearchTool()],
             model_settings=ModelSettings(tool_choice="required"),
         )
-        super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
-        )
-
-    async def run_agent(
-        self, search_plan: WebSearchPlanStructure
-    ) -> List[WebSearchItemResultStructure]:
-        """Execute all searches in the plan with a progress bar.
-
-        Parameters
-        ----------
-        search_plan : WebSearchPlanStructure
-            Plan describing each search to perform.
-
-        Returns
-        -------
-        list[WebSearchItemResultStructure]
-            Completed search results.
-        """
-        with custom_span("Search the web"):
-            semaphore = asyncio.Semaphore(MAX_CONCURRENT_SEARCHES)
-
-            async def _bounded_search(
-                item: WebSearchItemStructure,
-            ) -> WebSearchItemResultStructure:
-                """Execute a single search within the concurrency limit.
-
-                Parameters
-                ----------
-                item : WebSearchItemStructure
-                    Search item to process.
-
-                Returns
-                -------
-                WebSearchItemResultStructure
-                    Search result for ``item``.
-                """
-                async with semaphore:
-                    return await self.run_search(item)
-
-            tasks = [
-                asyncio.create_task(_bounded_search(item))
-                for item in search_plan.searches
-            ]
-            results = await asyncio.gather(*tasks)
-            return [result for result in results if result is not None]
 
     async def run_search(
         self, item: WebSearchItemStructure
@@ -173,25 +123,37 @@ class WebSearchToolAgent(AgentBase):
         Returns
         -------
         WebSearchItemResultStructure
-            Search result summarising the page.
+            Search result summarizing the page.
         """
-        template_context: Dict[str, Any] = {
-            "search_term": item.query,
-            "reason": item.reason,
-        }
-
-        result = await super().run_async(
-            input=item.query,
-            context=template_context,
-            output_type=str,
-        )
-        return self._coerce_item_result(result)
+        with custom_span("Search the web"):
+            template_context: Dict[str, Any] = {
+                "search_term": item.query,
+                "reason": item.reason,
+            }
+
+            result = await super(SearchToolAgent, self).run_async(
+                input=item.query,
+                context=template_context,
+                output_type=str,
+            )
+            return self._coerce_item_result(result)
 
     @staticmethod
     def _coerce_item_result(
         result: Union[str, WebSearchItemResultStructure, Any],
     ) -> WebSearchItemResultStructure:
-        """Return a WebSearchItemResultStructure from varied agent outputs."""
+        """Return a WebSearchItemResultStructure from varied agent outputs.
+
+        Parameters
+        ----------
+        result : str or WebSearchItemResultStructure or Any
+            Agent output that may be of various types.
+
+        Returns
+        -------
+        WebSearchItemResultStructure
+            Coerced search result structure.
+        """
         if isinstance(result, WebSearchItemResultStructure):
             return result
         try:
@@ -200,7 +162,7 @@ class WebSearchToolAgent(AgentBase):
             return WebSearchItemResultStructure(text="")
 
 
-class WebAgentWriter(AgentBase):
+class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
     """Summarize search results into a human-readable report.
 
     Methods
@@ -216,64 +178,38 @@ class WebAgentWriter(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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 config.
+        """
+        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+
+    def _configure_agent(self) -> AgentConfig:
+        """Return configuration for the web writer agent.
 
         Returns
         -------
-        None
+        AgentConfig
+            Configuration with name, description, and output type.
         """
-        config = AgentConfig(
+        return AgentConfig(
             name="web_writer",
             description="Agent that writes a report based on web search results.",
             output_type=WebSearchReportStructure,
         )
-        super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
-        )
-
-    async def run_agent(
-        self, query: str, search_results: List[WebSearchItemResultStructure]
-    ) -> WebSearchReportStructure:
-        """Compile a report from search results.
-
-        Parameters
-        ----------
-        query : str
-            Original search query.
-        search_results : list[WebSearchItemResultStructure]
-            Results produced by the search step.
-
-        Returns
-        -------
-        WebSearchReportStructure
-            Generated report for the query.
-        """
-        template_context: Dict[str, Any] = {
-            "original_query": query,
-            "search_results": search_results,
-        }
-        result: WebSearchReportStructure = await self.run_async(
-            input=query,
-            context=template_context,
-            output_type=self._output_type,
-        )
-
-        return result
 
 
-class WebAgentSearch(AgentBase):
+class WebAgentSearch:
     """Manage the complete web search workflow.
 
     Methods
     -------
-    run_agent(search_query)
+    run_agent_async(search_query)
         Execute the research workflow asynchronously.
     run_agent_sync(search_query)
         Execute the research workflow synchronously.
-    run_web_agent(search_query)
+    run_web_agent_async(search_query)
         Convenience asynchronous entry point for the workflow.
     run_web_agent_sync(search_query)
         Convenience synchronous entry point for the workflow.
@@ -281,7 +217,6 @@ class WebAgentSearch(AgentBase):
 
     def __init__(
         self,
-        config: Optional[AgentConfig] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
@@ -289,29 +224,15 @@ class WebAgentSearch(AgentBase):
 
         Parameters
         ----------
-        config : AgentConfig or None, default=None
-            Optional configuration for the agent.
-        prompt_dir : pathlib.Path or None, default=None
+        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 config.
-
-        Returns
-        -------
-        None
         """
-        if config is None:
-            config = AgentConfig(
-                name="web_agent",
-                description="Agent that coordinates web searches and report writing.",
-                output_type=WebSearchStructure,
-            )
-        super().__init__(
-            config=config, prompt_dir=prompt_dir, default_model=default_model
-        )
         self._prompt_dir = prompt_dir
+        self._default_model = default_model
 
-    async def run_agent(self, search_query: str) -> WebSearchStructure:
+    async def run_agent_async(self, search_query: str) -> WebSearchStructure:
         """Execute the entire research workflow for ``search_query``.
 
         Parameters
@@ -327,13 +248,13 @@ class WebAgentSearch(AgentBase):
         trace_id = gen_trace_id()
         with trace("WebAgentSearch trace", trace_id=trace_id):
             planner = WebAgentPlanner(
-                prompt_dir=self._prompt_dir, default_model=self.model
+                prompt_dir=self._prompt_dir, default_model=self._default_model
             )
             tool = WebSearchToolAgent(
-                prompt_dir=self._prompt_dir, default_model=self.model
+                prompt_dir=self._prompt_dir, default_model=self._default_model
             )
             writer = WebAgentWriter(
-                prompt_dir=self._prompt_dir, default_model=self.model
+                prompt_dir=self._prompt_dir, default_model=self._default_model
             )
             search_plan = await planner.run_agent(query=search_query)
             search_results = await tool.run_agent(search_plan=search_plan)
@@ -346,7 +267,7 @@ class WebAgentSearch(AgentBase):
         )
 
     def run_agent_sync(self, search_query: str) -> WebSearchStructure:
-        """Run :meth:`run_agent` synchronously for ``search_query``.
+        """Run :meth:`run_agent_async` synchronously for ``search_query``.
 
         Parameters
         ----------
@@ -358,10 +279,9 @@ class WebAgentSearch(AgentBase):
         WebSearchStructure
             Completed research output.
         """
-        return run_coroutine_agent_sync(self.run_agent(search_query))
+        return run_coroutine_agent_sync(self.run_agent_async(search_query))
 
-    @staticmethod
-    async def run_web_agent(search_query: str) -> WebSearchStructure:
+    async def run_web_agent_async(self, search_query: str) -> WebSearchStructure:
         """Return a research report for the given query using ``WebAgentSearch``.
 
         Parameters
@@ -374,11 +294,11 @@ class WebAgentSearch(AgentBase):
         WebSearchStructure
             Completed research output.
         """
-        return await WebAgentSearch().run_agent(search_query=search_query)
+        return await self.run_agent_async(search_query=search_query)
 
     @staticmethod
     def run_web_agent_sync(search_query: str) -> WebSearchStructure:
-        """Run :meth:`run_web_agent` synchronously for ``search_query``.
+        """Run :meth:`run_web_agent_async` synchronously for ``search_query``.
 
         Parameters
         ----------
@@ -391,7 +311,7 @@ class WebAgentSearch(AgentBase):
             Completed research output.
         """
         return run_coroutine_agent_sync(
-            WebAgentSearch.run_web_agent(search_query=search_query)
+            WebAgentSearch().run_web_agent_async(search_query=search_query)
         )
 
 

openai_sdk_helpers/agent/summarizer.py

@@ -14,6 +14,31 @@ from .prompt_utils import DEFAULT_PROMPT_DIR
 class SummarizerAgent(AgentBase):
     """Generate concise summaries from provided text.
 
+    This agent uses OpenAI models to create structured summaries from longer-form
+    content. The output follows the ``SummaryStructure`` format by default but
+    can be customized with a different output type.
+
+    Examples
+    --------
+    Basic usage with default settings:
+
+    >>> from openai_sdk_helpers.agent import SummarizerAgent
+    >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    >>> summary = summarizer.run_sync("Long text to summarize...")
+    >>> print(summary.text)
+
+    With custom metadata:
+
+    >>> import asyncio
+    >>> async def main():
+    ...     summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+    ...     result = await summarizer.run_agent(
+    ...         text="Article content...",
+    ...         metadata={"source": "news.txt", "date": "2025-01-01"}
+    ...     )
+    ...     return result
+    >>> asyncio.run(main())
+
     Methods
     -------
     run_agent(text, metadata)
@@ -31,17 +56,13 @@ class SummarizerAgent(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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_type : type, default=SummaryStructure
             Type describing the expected summary output.
-
-        Returns
-        -------
-        None
         """
         config = AgentConfig(
             name="summarizer",
@@ -56,14 +77,14 @@ class SummarizerAgent(AgentBase):
     async def run_agent(
         self, text: str, metadata: Optional[Dict[str, Any]] = None
     ) -> Any:
-        """Return a summary for ``text``.
+        """Generate a summary for ``text``.
 
         Parameters
         ----------
         text : str
             Source content to summarize.
-        metadata : dict, optional
-            Additional metadata to include in the prompt context. Default ``None``.
+        metadata : dict or None, default=None
+            Additional metadata to include in the prompt context.
 
         Returns
         -------

openai_sdk_helpers/agent/translator.py

@@ -13,6 +13,32 @@ from .prompt_utils import DEFAULT_PROMPT_DIR
 class TranslatorAgent(AgentBase):
     """Translate text into a target language.
 
+    This agent provides language translation services using OpenAI models,
+    supporting both synchronous and asynchronous execution modes.
+
+    Examples
+    --------
+    Basic translation:
+
+    >>> from openai_sdk_helpers.agent import TranslatorAgent
+    >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
+    >>> result = translator.run_sync("Hello world", target_language="Spanish")
+    >>> print(result)
+    'Hola mundo'
+
+    Async translation with context:
+
+    >>> import asyncio
+    >>> async def main():
+    ...     translator = TranslatorAgent(default_model="gpt-4o-mini")
+    ...     result = await translator.run_agent(
+    ...         text="Good morning",
+    ...         target_language="French",
+    ...         context={"formality": "formal"}
+    ...     )
+    ...     return result
+    >>> asyncio.run(main())
+
     Methods
     -------
     run_agent(text, target_language, context)
@@ -31,15 +57,11 @@ class TranslatorAgent(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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.
-
-        Returns
-        -------
-        None
         """
         config = AgentConfig(
             name="translator",
@@ -65,8 +87,8 @@ class TranslatorAgent(AgentBase):
             Source content to translate.
         target_language : str
             Language to translate the content into.
-        context : dict, optional
-            Additional context values to merge into the prompt. Default ``None``.
+        context : dict or None, default=None
+            Additional context values to merge into the prompt.
 
         Returns
         -------
@@ -99,21 +121,26 @@ class TranslatorAgent(AgentBase):
         ----------
         input : str
             Source content to translate.
-        context : dict, optional
-            Additional context values to merge into the prompt. Default ``None``.
-        output_type : type or None, optional
-            Optional output type cast for the response. Default ``None``.
-        target_language : str, optional
+        context : dict or None, default=None
+            Additional context values to merge into the prompt.
+        output_type : type or None, default=None
+            Optional output type cast for the response.
+        target_language : str or None, optional
             Target language to translate the content into. Required unless supplied
             within ``context`` or ``kwargs``.
         **kwargs
             Optional keyword arguments. ``context`` is accepted as an alias for
-            ``context`` for backward compatibility.
+            backward compatibility.
 
         Returns
         -------
         str
             Translated text returned by the agent.
+
+        Raises
+        ------
+        ValueError
+            If ``target_language`` is not provided.
         """
         merged_context: Dict[str, Any] = {}
 

openai_sdk_helpers/agent/validation.py

@@ -14,6 +14,34 @@ from .prompt_utils import DEFAULT_PROMPT_DIR
 class ValidatorAgent(AgentBase):
     """Check user prompts and agent responses against safety guardrails.
 
+    This agent validates inputs and outputs to ensure they comply with safety
+    policies and usage guidelines, returning structured validation results with
+    recommended actions.
+
+    Examples
+    --------
+    Validate user input:
+
+    >>> from openai_sdk_helpers.agent import ValidatorAgent
+    >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
+    >>> result = validator.run_sync("Tell me about Python programming")
+    >>> print(result.input_safe)  # True
+    >>> print(result.violations)  # []
+
+    Validate both input and output:
+
+    >>> import asyncio
+    >>> async def main():
+    ...     validator = ValidatorAgent(default_model="gpt-4o-mini")
+    ...     result = await validator.run_agent(
+    ...         user_input="Summarize this document",
+    ...         agent_output="Summary containing PII...",
+    ...         policy_notes="No PII in outputs"
+    ...     )
+    ...     if not result.output_safe:
+    ...         print(result.sanitized_output)
+    >>> asyncio.run(main())
+
     Methods
     -------
     run_agent(user_input, agent_output, policy_notes, extra_context)
@@ -30,15 +58,11 @@ class ValidatorAgent(AgentBase):
 
         Parameters
         ----------
-        prompt_dir : pathlib.Path or None, default=None
+        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.
-
-        Returns
-        -------
-        None
         """
         config = AgentConfig(
             name="validator",
@@ -64,13 +88,13 @@ class ValidatorAgent(AgentBase):
         ----------
         user_input : str
             Raw input provided by the user for the agent to evaluate.
-        agent_output : str, optional
+        agent_output : str or None, optional
             Latest agent response to validate against safety guardrails.
             Default ``None`` when only the input should be assessed.
-        policy_notes : str, optional
+        policy_notes : str or None, optional
             Additional policy snippets or guardrail expectations to reinforce.
             Default ``None``.
-        extra_context : dict, optional
+        extra_context : dict or None, optional
             Additional fields to merge into the validation context. Default ``None``.
 
         Returns