openai-sdk-helpers 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

openai_sdk_helpers/agent/search/web.py

@@ -26,24 +26,32 @@ MAX_CONCURRENT_SEARCHES = 10
 class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
     """Plan web searches to satisfy a user query.
 
+    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 config.
+
     Methods
     -------
     run_agent(query)
         Generate a search plan for the provided query.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> planner = WebAgentPlanner(default_model="gpt-4o-mini")
     """
 
     def __init__(
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
-        """Initialize the planner agent.
-
-        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 config.
-        """
+        """Initialize the planner agent."""
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
@@ -58,7 +66,7 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
             name="web_planner",
             instructions="Agent instructions",
             description="Agent that plans web searches based on a user query.",
-            output_type=WebSearchPlanStructure,
+            output_structure=WebSearchPlanStructure,
         )
 
 
@@ -69,26 +77,34 @@ class WebSearchToolAgent(
 ):
     """Execute web searches defined in a plan.
 
+    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 config.
+
     Methods
     -------
     run_agent(search_plan)
         Execute searches described by the plan.
     run_search(item)
         Perform a single web search and summarise the result.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> tool = WebSearchToolAgent(default_model="gpt-4o-mini")
     """
 
     def __init__(
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
-        """Initialize the search tool agent.
-
-        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 config.
-        """
+        """Initialize the search tool agent."""
         super().__init__(
             prompt_dir=prompt_dir,
             default_model=default_model,
@@ -107,7 +123,7 @@ class WebSearchToolAgent(
             name="web_search",
             instructions="Agent instructions",
             description="Agent that performs web searches and summarizes results.",
-            input_type=WebSearchPlanStructure,
+            input_structure=WebSearchPlanStructure,
             tools=[WebSearchTool()],
             model_settings=ModelSettings(tool_choice="required"),
         )
@@ -136,7 +152,6 @@ class WebSearchToolAgent(
             result = await super(SearchToolAgent, self).run_async(
                 input=item.query,
                 context=template_context,
-                output_type=str,
             )
             return self._coerce_item_result(result)
 
@@ -167,24 +182,32 @@ class WebSearchToolAgent(
 class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
     """Summarize search results into a human-readable report.
 
+    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 config.
+
     Methods
     -------
     run_agent(query, search_results)
         Compile a report from search results.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> writer = WebAgentWriter(default_model="gpt-4o-mini")
     """
 
     def __init__(
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
-        """Initialize the writer agent.
-
-        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 config.
-        """
+        """Initialize the writer agent."""
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
@@ -199,13 +222,20 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
             name="web_writer",
             instructions="Agent instructions",
             description="Agent that writes a report based on web search results.",
-            output_type=WebSearchReportStructure,
+            output_structure=WebSearchReportStructure,
         )
 
 
 class WebAgentSearch:
     """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 config.
+
     Methods
     -------
     run_agent_async(search_query)
@@ -216,6 +246,15 @@ class WebAgentSearch:
         Convenience asynchronous entry point for the workflow.
     run_web_agent_sync(search_query)
         Convenience synchronous entry point for the workflow.
+
+    Raises
+    ------
+    ValueError
+        If the default model is not provided.
+
+    Examples
+    --------
+    >>> search = WebAgentSearch(default_model="gpt-4o-mini")
     """
 
     def __init__(
@@ -223,15 +262,7 @@ class WebAgentSearch:
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Create the main web search agent.
-
-        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 config.
-        """
+        """Create the main web search agent."""
         self._prompt_dir = prompt_dir
         self._default_model = default_model
 

openai_sdk_helpers/agent/summarizer.py

@@ -3,21 +3,32 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Type
 
 from ..structure import SummaryStructure
-from .base import BaseAgent
+from ..structure.base import StructureBase
+from .base import AgentBase
 from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
-class SummarizerAgent(BaseAgent):
+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.
 
+    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.
+
     Examples
     --------
     Basic usage with default settings:
@@ -50,7 +61,7 @@ class SummarizerAgent(BaseAgent):
         *,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
-        output_type: type[Any] = SummaryStructure,
+        output_structure: Type[StructureBase] = SummaryStructure,
     ) -> None:
         """Initialize the summarizer agent configuration.
 
@@ -61,14 +72,23 @@ class SummarizerAgent(BaseAgent):
             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
+        output_structure : type[StructureBase], default=SummaryStructure
             Type describing the expected summary output.
+
+        Raises
+        ------
+        ValueError
+            If the default model is not provided.
+
+        Examples
+        --------
+        >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
         """
         config = AgentConfiguration(
             name="summarizer",
             instructions="Agent instructions",
             description="Summarize passages into concise findings.",
-            output_type=output_type,
+            output_structure=output_structure,
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
@@ -91,6 +111,11 @@ class SummarizerAgent(BaseAgent):
         -------
         Any
             Structured summary produced by the agent.
+
+        Raises
+        ------
+        APIError
+            If the OpenAI API call fails.
         """
         context: Optional[Dict[str, Any]] = None
         if metadata:
@@ -99,7 +124,7 @@ class SummarizerAgent(BaseAgent):
         result = await self.run_async(
             input=text,
             context=context,
-            output_type=self._output_type,
+            output_structure=self._output_structure,
         )
         return result
 

openai_sdk_helpers/agent/translator.py

@@ -5,17 +5,27 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from .base import BaseAgent
+from .base import AgentBase
 from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
+from ..structure import TranslationStructure
+from ..structure.base import StructureBase
 
 
-class TranslatorAgent(BaseAgent):
+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.
 
+    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.
+
     Examples
     --------
     Basic translation:
@@ -23,7 +33,7 @@ class TranslatorAgent(BaseAgent):
     >>> 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)
+    >>> print(result.text)
     'Hola mundo'
 
     Async translation with context:
@@ -62,12 +72,21 @@ class TranslatorAgent(BaseAgent):
             packaged ``prompt`` directory when not provided.
         default_model : str or None, default=None
             Fallback model identifier when not specified elsewhere.
+
+        Raises
+        ------
+        ValueError
+            If the default model is not provided.
+
+        Examples
+        --------
+        >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
         """
         config = AgentConfiguration(
             name="translator",
             instructions="Agent instructions",
             description="Translate text into the requested language.",
-            output_type=str,
+            output_structure=TranslationStructure,
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
@@ -79,7 +98,7 @@ class TranslatorAgent(BaseAgent):
         text: str,
         target_language: str,
         context: Optional[Dict[str, Any]] = None,
-    ) -> str:
+    ) -> TranslationStructure:
         """Translate ``text`` to ``target_language``.
 
         Parameters
@@ -93,29 +112,41 @@ class TranslatorAgent(BaseAgent):
 
         Returns
         -------
-        str
-            Translated text returned by the agent.
+        TranslationStructure
+            Structured translation output from the agent.
+
+        Raises
+        ------
+        APIError
+            If the OpenAI API call fails.
+
+        Examples
+        --------
+        >>> import asyncio
+        >>> async def main():
+        ...     result = await translator.run_agent("Hello", "Spanish")
+        ...     return result
+        >>> asyncio.run(main())
         """
         template_context: Dict[str, Any] = {"target_language": target_language}
         if context:
             template_context.update(context)
 
-        result: str = await self.run_async(
+        result: TranslationStructure = await self.run_async(
             input=text,
             context=template_context,
-            output_type=str,
         )
         return result
 
     def run_sync(
         self,
         input: str,
-        context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
         *,
+        context: Optional[Dict[str, Any]] = None,
+        output_structure: Optional[type[StructureBase]] = None,
+        session: Optional[Any] = None,
         target_language: Optional[str] = None,
-        **kwargs: Any,
-    ) -> str:
+    ) -> TranslationStructure:
         """Translate ``input`` to ``target_language`` synchronously.
 
         Parameters
@@ -124,31 +155,32 @@ class TranslatorAgent(BaseAgent):
             Source content to translate.
         context : dict or None, default=None
             Additional context values to merge into the prompt.
-        output_type : type or None, default=None
+        output_structure : type[StructureBase] 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
-            backward compatibility.
+            within ``context``.
+        session : Session or None, default=None
+            Optional session for maintaining conversation history across runs.
 
         Returns
         -------
-        str
-            Translated text returned by the agent.
+        TranslationStructure
+            Structured translation output from the agent.
 
         Raises
         ------
         ValueError
             If ``target_language`` is not provided.
+
+        Examples
+        --------
+        >>> result = translator.run_sync("Hello", target_language="Spanish")
         """
         merged_context: Dict[str, Any] = {}
 
         if context:
             merged_context.update(context)
-        if "context" in kwargs and kwargs["context"]:
-            merged_context.update(kwargs["context"])
         if target_language:
             merged_context["target_language"] = target_language
 
@@ -156,10 +188,11 @@ class TranslatorAgent(BaseAgent):
             msg = "target_language is required for translation"
             raise ValueError(msg)
 
-        result: str = super().run_sync(
+        result: TranslationStructure = super().run_sync(
             input=input,
             context=merged_context,
-            output_type=output_type or str,
+            output_structure=output_structure or self._output_structure,
+            session=session,
         )
         return result
 

openai_sdk_helpers/agent/validation.py

@@ -6,18 +6,26 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 from ..structure.validation import ValidationResultStructure
-from .base import BaseAgent
+from .base import AgentBase
 from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
-class ValidatorAgent(BaseAgent):
+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.
 
+    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.
+
     Examples
     --------
     Validate user input:
@@ -63,12 +71,21 @@ class ValidatorAgent(BaseAgent):
             packaged ``prompt`` directory when not provided.
         default_model : str or None, default=None
             Fallback model identifier when not specified elsewhere.
+
+        Raises
+        ------
+        ValueError
+            If the default model is not provided.
+
+        Examples
+        --------
+        >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
         """
         config = AgentConfiguration(
             name="validator",
             instructions="Agent instructions",
             description="Validate user input and agent output against guardrails.",
-            output_type=ValidationResultStructure,
+            output_structure=ValidationResultStructure,
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
@@ -102,6 +119,19 @@ class ValidatorAgent(BaseAgent):
         -------
         ValidationResultStructure
             Structured validation result describing any violations and actions.
+
+        Raises
+        ------
+        APIError
+            If the OpenAI API call fails.
+
+        Examples
+        --------
+        >>> import asyncio
+        >>> async def main():
+        ...     result = await validator.run_agent("Safe input")
+        ...     return result
+        >>> asyncio.run(main())
         """
         context: Dict[str, Any] = {"user_input": user_input}
         if agent_output is not None:
@@ -114,7 +144,7 @@ class ValidatorAgent(BaseAgent):
         result: ValidationResultStructure = await self.run_async(
             input=user_input,
             context=context,
-            output_type=ValidationResultStructure,
+            output_structure=ValidationResultStructure,
         )
         return result
 

openai_sdk_helpers/cli.py

@@ -43,6 +43,15 @@ def cmd_agent_test(args: argparse.Namespace) -> int:
     -------
     int
         Exit code (0 for success).
+
+    Raises
+    ------
+    NotImplementedError
+        As the function is not yet implemented.
+
+    Examples
+    --------
+    >>> cmd_agent_test(argparse.Namespace(agent_name="test", input="hello"))
     """
     print(f"Testing agent: {args.agent_name}")
     print(f"Input: {args.input}")
@@ -62,6 +71,15 @@ def cmd_template_validate(args: argparse.Namespace) -> int:
     -------
     int
         Exit code (0 for success, 1 for validation errors).
+
+    Raises
+    ------
+    FileNotFoundError
+        If the template path does not exist.
+
+    Examples
+    --------
+    >>> cmd_template_validate(argparse.Namespace(template_path="."))
     """
     from jinja2 import Environment, FileSystemLoader, TemplateSyntaxError
 
@@ -116,6 +134,15 @@ def cmd_registry_list(args: argparse.Namespace) -> int:
     -------
     int
         Exit code (0 for success).
+
+    Raises
+    ------
+    ImportError
+        If openai_sdk_helpers is not installed.
+
+    Examples
+    --------
+    >>> cmd_registry_list(argparse.Namespace())
     """
     try:
         from openai_sdk_helpers import get_default_registry
@@ -151,6 +178,17 @@ def cmd_registry_inspect(args: argparse.Namespace) -> int:
     -------
     int
         Exit code (0 for success, 1 for not found).
+
+    Raises
+    ------
+    ImportError
+        If openai_sdk_helpers is not installed.
+    KeyError
+        If the configuration is not found in the registry.
+
+    Examples
+    --------
+    >>> cmd_registry_inspect(argparse.Namespace(config_name="my_config"))
     """
     try:
         from openai_sdk_helpers import get_default_registry
@@ -198,6 +236,10 @@ def main(argv: list[str] | None = None) -> int:
     -------
     int
         Exit code.
+
+    Examples
+    --------
+    >>> main(["agent", "test", "my_agent"])
     """
     parser = argparse.ArgumentParser(
         prog="openai-helpers",

openai_sdk_helpers/config.py

@@ -156,7 +156,6 @@ class OpenAISettings(BaseModel):
                 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),

openai_sdk_helpers/environment.py

@@ -40,7 +40,7 @@ def get_data_path(name: str) -> Path:
     Returns
     -------
     Path
-        Directory path under ~/.openai-sdk-helpers specific to name.
+        Directory path under ~/openai-sdk-helpers specific to name.
         The directory is created if it does not exist.
 
     Examples
@@ -50,6 +50,7 @@ def get_data_path(name: str) -> Path:
     >>> path.exists()
     True
     """
-    base = Path.home() / ".openai-sdk-helpers"
+    # Use the workspace 'data' directory, with a subdirectory for the module name
+    base = Path(__file__).parent.parent.parent / "data"
     path = base / name
     return ensure_directory(path)