openai-sdk-helpers 0.2.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

openai_sdk_helpers/agent/search/web.py

@@ -16,7 +16,7 @@ from ...structure.web_search import (
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from ..config import AgentConfig
+from ..config import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -26,38 +26,47 @@ 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) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web planner agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="web_planner",
+            instructions="Agent instructions",
             description="Agent that plans web searches based on a user query.",
-            output_type=WebSearchPlanStructure,
+            output_structure=WebSearchPlanStructure,
         )
 
 
@@ -68,44 +77,53 @@ 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,
             max_concurrent_searches=MAX_CONCURRENT_SEARCHES,
         )
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web search tool agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, input type, and tools.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             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"),
         )
@@ -134,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)
 
@@ -165,44 +182,60 @@ 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) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web writer agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             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)
@@ -213,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__(
@@ -220,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,11 +3,12 @@
 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 ..structure.base import StructureBase
 from .base import AgentBase
-from .config import AgentConfig
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
@@ -18,6 +19,16 @@ class SummarizerAgent(AgentBase):
     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(AgentBase):
         *,
         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,13 +72,23 @@ class SummarizerAgent(AgentBase):
             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 = AgentConfig(
+        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__(
@@ -90,6 +111,11 @@ class SummarizerAgent(AgentBase):
         -------
         Any
             Structured summary produced by the agent.
+
+        Raises
+        ------
+        APIError
+            If the OpenAI API call fails.
         """
         context: Optional[Dict[str, Any]] = None
         if metadata:
@@ -98,7 +124,7 @@ class SummarizerAgent(AgentBase):
         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

@@ -6,8 +6,10 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 from .base import AgentBase
-from .config import AgentConfig
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
+from ..structure import TranslationStructure
+from ..structure.base import StructureBase
 
 
 class TranslatorAgent(AgentBase):
@@ -16,6 +18,14 @@ class TranslatorAgent(AgentBase):
     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(AgentBase):
     >>> 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,11 +72,21 @@ class TranslatorAgent(AgentBase):
             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 = AgentConfig(
+        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__(
@@ -78,7 +98,7 @@ class TranslatorAgent(AgentBase):
         text: str,
         target_language: str,
         context: Optional[Dict[str, Any]] = None,
-    ) -> str:
+    ) -> TranslationStructure:
         """Translate ``text`` to ``target_language``.
 
         Parameters
@@ -92,29 +112,41 @@ class TranslatorAgent(AgentBase):
 
         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
@@ -123,31 +155,32 @@ class TranslatorAgent(AgentBase):
             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
 
@@ -155,10 +188,11 @@ class TranslatorAgent(AgentBase):
             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

@@ -7,7 +7,7 @@ from typing import Any, Dict, Optional
 
 from ..structure.validation import ValidationResultStructure
 from .base import AgentBase
-from .config import AgentConfig
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
@@ -18,6 +18,14 @@ class ValidatorAgent(AgentBase):
     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,11 +71,21 @@ class ValidatorAgent(AgentBase):
             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 = AgentConfig(
+        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__(
@@ -101,6 +119,19 @@ class ValidatorAgent(AgentBase):
         -------
         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:
@@ -113,7 +144,7 @@ class ValidatorAgent(AgentBase):
         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)