openai-sdk-helpers 0.0.5__py3-none-any.whl → 0.0.6__py3-none-any.whl

openai_sdk_helpers/agent/runner.py

@@ -0,0 +1,215 @@
+"""Convenience wrappers for running OpenAI agents.
+
+These helpers provide a narrow surface around the lower-level functions in
+``openai-sdk-helpers.agent.base`` so that callers can execute agents with consistent
+signatures whether they need asynchronous, synchronous, or streamed results.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+import asyncio
+import threading
+from agents import Agent, Runner, RunResult, RunResultStreaming
+
+
+async def _run_async(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+    output_type: Optional[Any] = None,
+) -> Any:
+    """Run an ``Agent`` asynchronously.
+
+    Parameters
+    ----------
+    agent
+        Configured agent instance to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+    output_type
+        Optional type used to cast the final output. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Agent response, optionally converted to ``output_type``.
+    """
+    result = await Runner.run(agent, input, context=context)
+    if output_type is not None:
+        result = result.final_output_as(output_type)
+    return result
+
+
+def _run_sync(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+) -> RunResult:
+    """Run an ``Agent`` synchronously.
+
+    Parameters
+    ----------
+    agent
+        Configured agent instance to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+
+    Returns
+    -------
+    RunResult
+        Result from the agent execution.
+    """
+    coro = Runner.run(agent, input, context=context)
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    if loop.is_running():
+        result: RunResult | None = None
+
+        def _thread_runner() -> None:
+            nonlocal result
+            result = asyncio.run(coro)
+
+        thread = threading.Thread(target=_thread_runner, daemon=True)
+        thread.start()
+        thread.join()
+        if result is None:
+            raise RuntimeError("Agent execution did not return a result.")
+        return result
+
+    return loop.run_until_complete(coro)
+
+
+def _run_streamed(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+) -> RunResultStreaming:
+    """Run an ``Agent`` synchronously and return a streaming result.
+
+    Parameters
+    ----------
+    agent
+        Configured agent to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+
+    Returns
+    -------
+    RunResultStreaming
+        Instance for streaming outputs.
+    """
+    result = Runner.run_streamed(agent, input, context=context)
+    return result
+
+
+async def run_async(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+    output_type: Optional[Any] = None,
+) -> Any:
+    """Run an ``Agent`` asynchronously.
+
+    Parameters
+    ----------
+    agent
+        Configured agent instance to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+    output_type
+        Optional type used to cast the final output. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Agent response, optionally converted to ``output_type``.
+    """
+    return await _run_async(
+        agent=agent,
+        input=input,
+        context=context,
+        output_type=output_type,
+    )
+
+
+def run_sync(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+    output_type: Optional[Any] = None,
+) -> Any:
+    """Run an ``Agent`` synchronously.
+
+    Parameters
+    ----------
+    agent
+        Configured agent instance to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+    output_type
+        Optional type used to cast the final output. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Agent response, optionally converted to ``output_type``.
+    """
+    result: RunResult = _run_sync(
+        agent=agent,
+        input=input,
+        context=context,
+    )
+    if output_type:
+        return result.final_output_as(output_type)
+    return result
+
+
+def run_streamed(
+    agent: Agent,
+    input: str,
+    context: Optional[Dict[str, Any]] = None,
+    output_type: Optional[Any] = None,
+) -> RunResultStreaming:
+    """Run an ``Agent`` and return a streaming result.
+
+    Parameters
+    ----------
+    agent
+        Configured agent instance to execute.
+    input
+        Prompt or query string for the agent.
+    context
+        Optional context dictionary passed to the agent. Default ``None``.
+    output_type
+        Optional type used to cast the final output. Default ``None``.
+
+    Returns
+    -------
+    RunResultStreaming
+        Streaming output wrapper from the agent execution.
+    """
+    result = _run_streamed(
+        agent=agent,
+        input=input,
+        context=context,
+    )
+    if output_type:
+        return result.final_output_as(output_type)
+    return result
+
+
+__all__ = ["run_sync", "run_async", "run_streamed"]

openai_sdk_helpers/agent/summarizer.py

@@ -0,0 +1,85 @@
+"""Lightweight agent for summarizing text."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..structure import SummaryStructure
+from .base import AgentBase
+from .config import AgentConfig
+from .prompt_utils import DEFAULT_PROMPT_DIR
+
+
+class SummarizerAgent(AgentBase):
+    """Generate concise summaries from provided text.
+
+    Methods
+    -------
+    run_agent(text, metadata)
+        Summarize the supplied text with optional metadata context.
+    """
+
+    def __init__(
+        self,
+        *,
+        prompt_dir: Optional[Path] = None,
+        default_model: Optional[str] = None,
+        output_type: type[Any] = SummaryStructure,
+    ) -> None:
+        """Initialize the summarizer agent configuration.
+
+        Parameters
+        ----------
+        prompt_dir : pathlib.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",
+            description="Summarize passages into concise findings.",
+            output_type=output_type,
+        )
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(
+            config=config, prompt_dir=prompt_directory, default_model=default_model
+        )
+
+    async def run_agent(
+        self, text: str, metadata: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        """Return a summary for ``text``.
+
+        Parameters
+        ----------
+        text : str
+            Source content to summarize.
+        metadata : dict, optional
+            Additional metadata to include in the prompt context. Default ``None``.
+
+        Returns
+        -------
+        Any
+            Structured summary produced by the agent.
+        """
+        context: Optional[Dict[str, Any]] = None
+        if metadata:
+            context = {"metadata": metadata}
+
+        result = await self.run_async(
+            input=text,
+            context=context,
+            output_type=self._output_type,
+        )
+        return result
+
+
+__all__ = ["SummarizerAgent"]

openai_sdk_helpers/agent/translator.py

@@ -0,0 +1,139 @@
+"""Lightweight agent for translating text into a target language."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from .base import AgentBase
+from .config import AgentConfig
+from .prompt_utils import DEFAULT_PROMPT_DIR
+
+
+class TranslatorAgent(AgentBase):
+    """Translate text into a target language.
+
+    Methods
+    -------
+    run_agent(text, target_language, context)
+        Translate the supplied text into the target language.
+    run_sync(text, target_language, context)
+        Translate the supplied text synchronously.
+    """
+
+    def __init__(
+        self,
+        *,
+        prompt_dir: Optional[Path] = None,
+        default_model: Optional[str] = None,
+    ) -> None:
+        """Initialize the translation agent configuration.
+
+        Parameters
+        ----------
+        prompt_dir : pathlib.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",
+            description="Translate text into the requested language.",
+            output_type=str,
+        )
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(
+            config=config, prompt_dir=prompt_directory, default_model=default_model
+        )
+
+    async def run_agent(
+        self,
+        text: str,
+        target_language: str,
+        context: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Translate ``text`` to ``target_language``.
+
+        Parameters
+        ----------
+        text : str
+            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``.
+
+        Returns
+        -------
+        str
+            Translated text returned by the agent.
+        """
+        template_context: Dict[str, Any] = {"target_language": target_language}
+        if context:
+            template_context.update(context)
+
+        result: str = 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,
+        *,
+        target_language: Optional[str] = None,
+        **kwargs: Any,
+    ) -> str:
+        """Translate ``input`` to ``target_language`` synchronously.
+
+        Parameters
+        ----------
+        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
+            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.
+
+        Returns
+        -------
+        str
+            Translated text returned by the agent.
+        """
+        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
+
+        if "target_language" not in merged_context:
+            msg = "target_language is required for translation"
+            raise ValueError(msg)
+
+        result: str = super().run_sync(
+            input=input,
+            context=merged_context,
+            output_type=output_type or str,
+        )
+        return result
+
+
+__all__ = ["TranslatorAgent"]

openai_sdk_helpers/agent/utils.py

@@ -0,0 +1,47 @@
+"""Utility helpers for synchronous interaction with async agents."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from typing import Any, Coroutine, TypeVar
+
+T = TypeVar("T")
+
+
+def run_coroutine_agent_sync(coro: Coroutine[Any, Any, T]) -> T:
+    """Run a coroutine from synchronous code.
+
+    Parameters
+    ----------
+    coro : Coroutine[Any, Any, T]
+        Coroutine to execute.
+
+    Returns
+    -------
+    T
+        Result returned by the coroutine.
+    """
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    if loop.is_running():
+        result: T | None = None
+
+        def _thread_runner() -> None:
+            nonlocal result
+            result = asyncio.run(coro)
+
+        thread = threading.Thread(target=_thread_runner, daemon=True)
+        thread.start()
+        thread.join()
+        if result is None:
+            raise RuntimeError("Coroutine execution did not return a result.")
+        return result
+
+    return loop.run_until_complete(coro)
+
+
+__all__ = ["run_coroutine_agent_sync"]

openai_sdk_helpers/agent/validation.py

@@ -0,0 +1,97 @@
+"""Agent helper for validating inputs and outputs against guardrails."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from ..structure.validation import ValidationResultStructure
+from .base import AgentBase
+from .config import AgentConfig
+from .prompt_utils import DEFAULT_PROMPT_DIR
+
+
+class ValidatorAgent(AgentBase):
+    """Check user prompts and agent responses against safety guardrails.
+
+    Methods
+    -------
+    run_agent(user_input, agent_output, policy_notes, extra_context)
+        Validate user and agent messages and return a structured report.
+    """
+
+    def __init__(
+        self,
+        *,
+        prompt_dir: Optional[Path] = None,
+        default_model: Optional[str] = None,
+    ) -> None:
+        """Initialize the validator agent configuration.
+
+        Parameters
+        ----------
+        prompt_dir : pathlib.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",
+            description="Validate user input and agent output against guardrails.",
+            output_type=ValidationResultStructure,
+        )
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(
+            config=config, prompt_dir=prompt_directory, default_model=default_model
+        )
+
+    async def run_agent(
+        self,
+        user_input: str,
+        *,
+        agent_output: Optional[str] = None,
+        policy_notes: Optional[str] = None,
+        extra_context: Optional[Dict[str, Any]] = None,
+    ) -> ValidationResultStructure:
+        """Validate user and agent messages.
+
+        Parameters
+        ----------
+        user_input : str
+            Raw input provided by the user for the agent to evaluate.
+        agent_output : str, optional
+            Latest agent response to validate against safety guardrails.
+            Default ``None`` when only the input should be assessed.
+        policy_notes : str, optional
+            Additional policy snippets or guardrail expectations to reinforce.
+            Default ``None``.
+        extra_context : dict, optional
+            Additional fields to merge into the validation context. Default ``None``.
+
+        Returns
+        -------
+        ValidationResultStructure
+            Structured validation result describing any violations and actions.
+        """
+        context: Dict[str, Any] = {"user_input": user_input}
+        if agent_output is not None:
+            context["agent_output"] = agent_output
+        if policy_notes is not None:
+            context["policy_notes"] = policy_notes
+        if extra_context:
+            context.update(extra_context)
+
+        result: ValidationResultStructure = await self.run_async(
+            input=user_input,
+            context=context,
+            output_type=ValidationResultStructure,
+        )
+        return result
+
+
+__all__ = ["ValidatorAgent"]