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

openai_sdk_helpers/__init__.py

@@ -0,0 +1,62 @@
+"""Shared AI helpers and base structures."""
+
+from __future__ import annotations
+
+from .structure import *
+from .prompt import PromptRenderer
+from .config import OpenAISettings
+from .vector_storage import *
+from .agent import (
+    AgentBase,
+    AgentConfig,
+    AgentEnum,
+    ProjectManager,
+    SummarizerAgent,
+    TranslatorAgent,
+    ValidatorAgent,
+    VectorSearch,
+    WebAgentSearch,
+)
+from .response import (
+    ResponseBase,
+    ResponseMessage,
+    ResponseMessages,
+    ResponseToolCall,
+)
+
+__all__ = [
+    "BaseStructure",
+    "SchemaOptions",
+    "spec_field",
+    "PromptRenderer",
+    "OpenAISettings",
+    "VectorStorage",
+    "VectorStorageFileInfo",
+    "VectorStorageFileStats",
+    "assistant_tool_definition",
+    "assistant_format",
+    "response_tool_definition",
+    "response_format",
+    "SummaryStructure",
+    "PromptStructure",
+    "AgentBlueprint",
+    "TaskStructure",
+    "PlanStructure",
+    "AgentEnum",
+    "AgentBase",
+    "AgentConfig",
+    "ProjectManager",
+    "SummarizerAgent",
+    "TranslatorAgent",
+    "ValidatorAgent",
+    "VectorSearch",
+    "WebAgentSearch",
+    "ExtendedSummaryStructure",
+    "WebSearchStructure",
+    "VectorSearchStructure",
+    "ValidationResultStructure",
+    "ResponseBase",
+    "ResponseMessage",
+    "ResponseMessages",
+    "ResponseToolCall",
+]

openai_sdk_helpers/agent/__init__.py

@@ -0,0 +1,31 @@
+"""Shared agent helpers built on the OpenAI Agents SDK."""
+
+from __future__ import annotations
+
+from .base import AgentBase
+from .config import AgentConfig
+from ..structure.plan.enum import AgentEnum
+from .project_manager import ProjectManager
+from .runner import run_sync, run_async, run_streamed
+from .summarizer import SummarizerAgent
+from .translator import TranslatorAgent
+from .validation import ValidatorAgent
+from .utils import run_coroutine_agent_sync
+from .vector_search import VectorSearch
+from .web_search import WebAgentSearch
+
+__all__ = [
+    "AgentBase",
+    "AgentConfig",
+    "AgentEnum",
+    "ProjectManager",
+    "run_sync",
+    "run_async",
+    "run_streamed",
+    "run_coroutine_agent_sync",
+    "SummarizerAgent",
+    "TranslatorAgent",
+    "ValidatorAgent",
+    "VectorSearch",
+    "WebAgentSearch",
+]

openai_sdk_helpers/agent/base.py

@@ -0,0 +1,330 @@
+"""Base agent helpers built on the OpenAI Agents SDK."""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from pathlib import Path
+from typing import Any, Dict, Optional, Protocol
+
+from agents import Agent, Runner, RunResult, RunResultStreaming
+from agents.run_context import RunContextWrapper
+from agents.tool import FunctionTool
+from jinja2 import Template
+from .runner import run_sync, run_streamed, run_async
+
+
+class AgentConfigLike(Protocol):
+    """Protocol describing the configuration attributes for AgentBase."""
+
+    name: str
+    description: Optional[str]
+    model: Optional[str]
+    template_path: Optional[str]
+    input_type: Optional[Any]
+    output_type: Optional[Any]
+    tools: Optional[Any]
+    model_settings: Optional[Any]
+
+
+class AgentBase:
+    """Factory for creating and configuring specialized agents.
+
+    Methods
+    -------
+    from_config(config, run_context_wrapper)
+        Instantiate a ``AgentBase`` from configuration.
+    build_prompt_from_jinja(run_context_wrapper)
+        Render the agent prompt using Jinja and optional context.
+    get_prompt(run_context_wrapper, _)
+        Render the agent prompt using the provided run context.
+    get_agent()
+        Construct the configured :class:`agents.Agent` instance.
+    run(input, context, output_type)
+        Execute the agent asynchronously (alias of ``run_async``).
+    run_async(input, context, output_type)
+        Execute the agent asynchronously and optionally cast the result.
+    run_sync(input, context, output_type)
+        Execute the agent synchronously.
+    run_streamed(input, context, output_type)
+        Return a streaming result for the agent execution.
+    as_tool()
+        Return the agent as a callable tool.
+    """
+
+    def __init__(
+        self,
+        config: AgentConfigLike,
+        run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
+        prompt_dir: Optional[Path] = None,
+        default_model: Optional[str] = None,
+    ) -> None:
+        """Initialize the ``AgentBase`` using a configuration object.
+
+        Parameters
+        ----------
+        config
+            Configuration describing this agent.
+        run_context_wrapper
+            Optional wrapper providing runtime context for prompt rendering.
+            Default ``None``.
+        prompt_dir
+            Optional directory holding prompt templates.
+        default_model
+            Optional fallback model identifier if the config does not supply one.
+
+        Returns
+        -------
+        None
+        """
+        name = config.name
+        description = config.description or ""
+        model = config.model or default_model
+        if not model:
+            raise ValueError("Model is required to construct the agent.")
+
+        prompt_path: Optional[Path]
+        if config.template_path:
+            prompt_path = Path(config.template_path)
+        elif prompt_dir is not None:
+            prompt_path = prompt_dir / f"{name}.jinja"
+        else:
+            prompt_path = None
+
+        if prompt_path is None:
+            self._template = Template("")
+        elif prompt_path.exists():
+            self._template = Template(prompt_path.read_text())
+        else:
+            raise FileNotFoundError(
+                f"Prompt template for agent '{name}' not found at {prompt_path}."
+            )
+
+        self.agent_name = name
+        self.description = description
+        self.model = model
+
+        self._input_type = config.input_type
+        self._output_type = config.output_type or config.input_type
+        self._tools = config.tools
+        self._model_settings = config.model_settings
+        self._run_context_wrapper = run_context_wrapper
+
+    @classmethod
+    def from_config(
+        cls,
+        config: AgentConfigLike,
+        run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
+        prompt_dir: Optional[Path] = None,
+        default_model: Optional[str] = None,
+    ) -> "AgentBase":
+        """Create a :class:`AgentBase` instance from configuration.
+
+        Parameters
+        ----------
+        config
+            Configuration describing the agent.
+        run_context_wrapper
+            Optional wrapper providing runtime context. Default ``None``.
+        prompt_dir
+            Optional directory holding prompt templates.
+        default_model
+            Optional fallback model identifier.
+
+        Returns
+        -------
+        AgentBase
+            Instantiated agent.
+        """
+        return cls(
+            config=config,
+            run_context_wrapper=run_context_wrapper,
+            prompt_dir=prompt_dir,
+            default_model=default_model,
+        )
+
+    def _build_prompt_from_jinja(self) -> str:
+        """Return the rendered instructions prompt for this agent.
+
+        Returns
+        -------
+        str
+            Prompt text rendered from the Jinja template.
+        """
+        return self.build_prompt_from_jinja(
+            run_context_wrapper=self._run_context_wrapper
+        )
+
+    def build_prompt_from_jinja(
+        self, run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None
+    ) -> str:
+        """Render the agent prompt using the provided run context.
+
+        Parameters
+        ----------
+        run_context_wrapper
+            Wrapper whose ``context`` dictionary is used to render the Jinja
+            template. Default ``None``.
+
+        Returns
+        -------
+        str
+            Rendered prompt text.
+        """
+        context = {}
+        if run_context_wrapper is not None:
+            context = run_context_wrapper.context
+
+        return self._template.render(context)
+
+    def get_prompt(
+        self, run_context_wrapper: RunContextWrapper[Dict[str, Any]], _: Agent
+    ) -> str:
+        """Render the agent prompt using the provided run context.
+
+        Parameters
+        ----------
+        run_context_wrapper
+            Wrapper around the current run context whose ``context`` dictionary
+            is used to render the Jinja template.
+        _
+            Underlying :class:`agents.Agent` instance (ignored).
+
+        Returns
+        -------
+        str
+            The rendered prompt.
+        """
+        return self.build_prompt_from_jinja(run_context_wrapper)
+
+    def get_agent(self) -> Agent:
+        """Construct and return the configured :class:`agents.Agent` instance.
+
+        Returns
+        -------
+        Agent
+            Initialized agent ready for execution.
+        """
+        agent_config: Dict[str, Any] = {
+            "name": self.agent_name,
+            "instructions": self._build_prompt_from_jinja(),
+            "model": self.model,
+        }
+        if self._output_type:
+            agent_config["output_type"] = self._output_type
+        if self._tools:
+            agent_config["tools"] = self._tools
+        if self._model_settings:
+            agent_config["model_settings"] = self._model_settings
+
+        return Agent(**agent_config)
+
+    async def run_async(
+        self,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
+        output_type: Optional[Any] = None,
+    ) -> Any:
+        """Execute the agent asynchronously.
+
+        Parameters
+        ----------
+        input
+            Prompt or query for the agent.
+        context
+            Optional dictionary passed to the agent. Default ``None``.
+        output_type
+            Optional type used to cast the final output. Default ``None``.
+
+        Returns
+        -------
+        Any
+            Agent result, optionally converted to ``output_type``.
+        """
+        if self._output_type is not None and output_type is None:
+            output_type = self._output_type
+        return await run_async(
+            agent=self.get_agent(),
+            input=input,
+            context=context,
+            output_type=output_type,
+        )
+
+    def run_sync(
+        self,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
+        output_type: Optional[Any] = None,
+    ) -> Any:
+        """Run the agent synchronously.
+
+        Parameters
+        ----------
+        input
+            Prompt or query for the agent.
+        context
+            Optional dictionary passed to the agent. Default ``None``.
+        output_type
+            Optional type used to cast the final output. Default ``None``.
+
+        Returns
+        -------
+        Any
+            Agent result, optionally converted to ``output_type``.
+        """
+        return run_sync(
+            agent=self.get_agent(),
+            input=input,
+            context=context,
+            output_type=output_type,
+        )
+
+    def run_streamed(
+        self,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
+        output_type: Optional[Any] = None,
+    ) -> RunResultStreaming:
+        """Return a streaming result for the agent execution.
+
+        Parameters
+        ----------
+        input
+            Prompt or query for the agent.
+        context
+            Optional 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=self.get_agent(),
+            input=input,
+            context=context,
+        )
+        if self._output_type and not output_type:
+            output_type = self._output_type
+        if output_type:
+            return result.final_output_as(output_type)
+        return result
+
+    def as_tool(self) -> FunctionTool:
+        """Return the agent as a callable tool.
+
+        Returns
+        -------
+        FunctionTool
+            Tool instance wrapping this agent.
+        """
+        agent = self.get_agent()
+        tool_obj: FunctionTool = agent.as_tool(
+            tool_name=self.agent_name, tool_description=self.description
+        )  # type: ignore
+        return tool_obj
+
+
+__all__ = ["AgentConfigLike", "AgentBase"]

openai_sdk_helpers/agent/config.py

@@ -0,0 +1,66 @@
+"""Configuration helpers for ``AgentBase``."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional, Type
+
+from agents.model_settings import ModelSettings
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..structure import BaseStructure
+
+
+class AgentConfig(BaseStructure):
+    """Configuration required to build a :class:`AgentBase`.
+
+    Methods
+    -------
+    print()
+        Return a human readable representation of the configuration.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: str = Field(title="Agent Name", description="Unique name for the agent")
+    description: Optional[str] = Field(
+        default=None, title="Description", description="Short description of the agent"
+    )
+    model: Optional[str] = Field(
+        default=None, title="Model", description="Model identifier to use"
+    )
+    template_path: Optional[str] = Field(
+        default=None, title="Template Path", description="Path to the Jinja template"
+    )
+    input_type: Optional[Type[BaseModel]] = Field(
+        default=None,
+        title="Input Type",
+        description="Pydantic model describing the agent input",
+    )
+    output_type: Optional[Type[Any]] = Field(
+        default=None,
+        title="Output Type",
+        description="Type describing the agent output; commonly a Pydantic model or builtin like ``str``",
+    )
+    tools: Optional[List[Any]] = Field(
+        default=None,
+        title="Tools",
+        description="Tools available to the agent",
+    )
+    model_settings: Optional[ModelSettings] = Field(
+        default=None, title="Model Settings", description="Additional model settings"
+    )
+
+    def print(self) -> str:
+        """Return a human readable representation.
+
+        Returns
+        -------
+        str
+            The agent's name.
+        """
+        return self.name
+
+
+__all__ = ["AgentConfig"]
+
+AgentConfig.model_rebuild()