openai-sdk-helpers 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

{openai_sdk_helpers-0.0.2.dist-info → openai_sdk_helpers-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.2
+Version: 0.0.4
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT
@@ -39,6 +39,7 @@ application-specific prompts and tools to the consuming project.
   predictable inputs and outputs.
 - **Vector and web search flows** that coordinate planning, execution, and
   reporting.
+- **Reusable text agents** for summarization and translation tasks.
 
 ## Installation
 
@@ -48,6 +49,9 @@ Install the package directly from PyPI to reuse it across projects:
 pip install openai-sdk-helpers
 ```
 
+Type information ships with the published wheel via `py.typed`, so external
+projects can rely on the bundled annotations without adding custom stubs.
+
 For local development, install with editable sources and the optional dev
 dependencies:
 
@@ -74,9 +78,39 @@ report = vector_search.run_agent_sync("Explain quantum entanglement for beginner
 print(report.report)
 ```
 
-You can plug in your own prompt templates by placing matching `.jinja` files in
-the provided `prompt_dir` and naming them after the agent (for example,
-`vector_planner.jinja`).
+### Text utilities
+
+Use the built-in text helpers when you need lightweight single-step agents.
+
+```python
+from openai_sdk_helpers.agent import (
+    SummarizerAgent,
+    TranslatorAgent,
+    ValidatorAgent,
+)
+
+
+summarizer = SummarizerAgent(default_model="gpt-4o-mini")
+translator = TranslatorAgent(default_model="gpt-4o-mini")
+validator = ValidatorAgent(default_model="gpt-4o-mini")
+
+summary = summarizer.run_sync("Long-form content to condense")
+translation = translator.run_sync("Bonjour", target_language="English")
+guardrails = validator.run_sync(
+    "Share meeting notes with names removed", agent_output=summary.text
+)
+```
+
+Prompt templates are optional for the built-in text helpers. They already ship
+with defaults under `src/openai_sdk_helpers/prompt`, so you do **not** need to
+create placeholder files when installing from PyPI. Only pass a `prompt_dir`
+when you have real replacements you want to load.
+
+The vector search workflow expects real prompts for each agent (for example,
+`vector_planner.jinja`, `vector_search.jinja`, and `vector_writer.jinja`). If
+you point `prompt_dir` at a folder that does not contain those files, agent
+construction fails with a `FileNotFoundError`. Skip `prompt_dir` entirely unless
+you have working templates ready.
 
 ### Centralized OpenAI configuration
 
@@ -129,6 +163,25 @@ pytest -q --cov=src --cov-report=term-missing --cov-fail-under=70
 - `src/openai_sdk_helpers/vector_storage`: Minimal vector store abstraction.
 - `tests/`: Unit tests covering core modules and structures.
 
+## Key modules
+
+The package centers around a handful of cohesive building blocks:
+
+- `openai_sdk_helpers.agent.project_manager.ProjectManager` coordinates prompt
+  creation, plan building, task execution, and summarization while persisting
+  intermediate artifacts to disk.
+- `openai_sdk_helpers.agent.vector_search.VectorSearch` bundles the planners,
+  executors, and summarizers required to run a multi-turn vector search flow
+  from a single entry point.
+- `openai_sdk_helpers.agent.summarizer.SummarizerAgent`,
+  `agent.translator.TranslatorAgent`, and `agent.validator.ValidatorAgent`
+  expose streamlined text-processing utilities that reuse shared prompt
+  templates.
+- `openai_sdk_helpers.response` contains the response runners and helpers used
+  to normalize outputs from agents, including streaming responses.
+- `openai_sdk_helpers.utils` holds JSON serialization helpers, logging
+  utilities, and common validation helpers used across modules.
+
 ## Contributing
 
 Contributions are welcome! Please accompany functional changes with relevant

openai_sdk_helpers-0.0.4.dist-info/RECORD

@@ -0,0 +1,4 @@
+openai_sdk_helpers-0.0.4.dist-info/METADATA,sha256=bZKdcLHnfVo5mGC6fGJvUuw7C2cGdM4oAmsNX3PIy4w,6338
+openai_sdk_helpers-0.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.0.4.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.0.4.dist-info/RECORD,,

openai_sdk_helpers/__init__.py

@@ -1,34 +0,0 @@
-"""Shared AI helpers and base structures."""
-
-from __future__ import annotations
-
-__version__ = "0.0.1"
-
-from .structure import (
-    BaseStructure,
-    SchemaOptions,
-    spec_field,
-    assistant_tool_definition,
-    assistant_format,
-    response_tool_definition,
-    response_format,
-)
-from .prompt import PromptRenderer
-from .config import OpenAISettings
-from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
-
-__all__ = [
-    "__version__",
-    "BaseStructure",
-    "SchemaOptions",
-    "spec_field",
-    "PromptRenderer",
-    "OpenAISettings",
-    "VectorStorage",
-    "VectorStorageFileInfo",
-    "VectorStorageFileStats",
-    "assistant_tool_definition",
-    "assistant_format",
-    "response_tool_definition",
-    "response_format",
-]

openai_sdk_helpers/agent/__init__.py

@@ -1,23 +0,0 @@
-"""Shared agent helpers built on the OpenAI Agents SDK."""
-
-from __future__ import annotations
-
-from .base import BaseAgent
-from .config import AgentConfig
-from .project_manager import ProjectManager
-from .runner import run, run_streamed, run_sync
-from .utils import run_coro_sync
-from .vector_search import VectorSearch
-from .web_search import WebAgentSearch
-
-__all__ = [
-    "BaseAgent",
-    "AgentConfig",
-    "ProjectManager",
-    "run",
-    "run_sync",
-    "run_streamed",
-    "run_coro_sync",
-    "VectorSearch",
-    "WebAgentSearch",
-]

openai_sdk_helpers/agent/base.py

@@ -1,432 +0,0 @@
-"""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
-
-
-class AgentConfigLike(Protocol):
-    """Protocol describing the configuration attributes for BaseAgent."""
-
-    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 BaseAgent:
-    """Factory for creating and configuring specialized agents.
-
-    Methods
-    -------
-    from_config(config, run_context_wrapper)
-        Instantiate a ``BaseAgent`` 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(agent_input, agent_context, output_type)
-        Execute the agent asynchronously and optionally cast the result.
-    run_sync(agent_input, agent_context, output_type)
-        Execute the agent synchronously.
-    run_streamed(agent_input, agent_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 ``BaseAgent`` 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 not None and prompt_path.exists():
-            self._template = Template(prompt_path.read_text())
-        else:
-            self._template = Template("")
-
-        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,
-    ) -> "BaseAgent":
-        """Create a :class:`BaseAgent` 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
-        -------
-        BaseAgent
-            Instantiated agent.
-        """
-        return cls(
-            config=config,
-            run_context_wrapper=run_context_wrapper,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
-        )
-
-    def _build_instructions_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_instructions_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(
-        self,
-        agent_input: str,
-        agent_context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
-    ) -> Any:
-        """Execute the agent asynchronously.
-
-        Parameters
-        ----------
-        agent_input
-            Prompt or query for the agent.
-        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_agent(
-            agent=self.get_agent(),
-            agent_input=agent_input,
-            agent_context=agent_context,
-            output_type=output_type,
-        )
-
-    def run_sync(
-        self,
-        agent_input: str,
-        agent_context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
-    ) -> Any:
-        """Run the agent synchronously.
-
-        Parameters
-        ----------
-        agent_input
-            Prompt or query for the agent.
-        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``.
-        """
-        result = _run_agent_sync(
-            self.get_agent(),
-            agent_input,
-            agent_context=agent_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 run_streamed(
-        self,
-        agent_input: str,
-        agent_context: Optional[Dict[str, Any]] = None,
-        output_type: Optional[Any] = None,
-    ) -> RunResultStreaming:
-        """Return a streaming result for the agent execution.
-
-        Parameters
-        ----------
-        agent_input
-            Prompt or query for the agent.
-        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_agent_streamed(
-            agent=self.get_agent(),
-            agent_input=agent_input,
-            context=agent_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
-
-
-async def _run_agent(
-    agent: Agent,
-    agent_input: str,
-    agent_context: Optional[Dict[str, Any]] = None,
-    output_type: Optional[Any] = None,
-) -> Any:
-    """Run an ``Agent`` asynchronously.
-
-    Parameters
-    ----------
-    agent
-        Configured agent instance to execute.
-    agent_input
-        Prompt or query string for the agent.
-    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, agent_input, context=agent_context)
-    if output_type is not None:
-        result = result.final_output_as(output_type)
-    return result
-
-
-def _run_agent_sync(
-    agent: Agent,
-    agent_input: str,
-    agent_context: Optional[Dict[str, Any]] = None,
-) -> RunResult:
-    """Run an ``Agent`` synchronously.
-
-    Parameters
-    ----------
-    agent
-        Configured agent instance to execute.
-    agent_input
-        Prompt or query string for the agent.
-    agent_context
-        Optional context dictionary passed to the agent. Default ``None``.
-
-    Returns
-    -------
-    RunResult
-        Result from the agent execution.
-    """
-    coro = Runner.run(agent, agent_input, context=agent_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_agent_streamed(
-    agent: 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.
-    agent_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, agent_input, context=context)
-    return result
-
-
-__all__ = [
-    "AgentConfigLike",
-    "BaseAgent",
-    "_run_agent",
-    "_run_agent_sync",
-    "_run_agent_streamed",
-]

openai_sdk_helpers/agent/config.py

@@ -1,66 +0,0 @@
-"""Configuration helpers for ``BaseAgent``."""
-
-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:`BaseAgent`.
-
-    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()