openai-sdk-helpers 0.0.2__tar.gz → 0.0.4__tar.gz

{openai_sdk_helpers-0.0.2 → openai_sdk_helpers-0.0.4}/PKG-INFO

@@ -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.2 → openai_sdk_helpers-0.0.4}/README.md

@@ -23,6 +23,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
 
@@ -32,6 +33,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:
 
@@ -58,9 +62,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
 
@@ -113,6 +147,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/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-0.0.4/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-0.0.2/src → openai_sdk_helpers-0.0.4}/openai_sdk_helpers/agent/base.py

@@ -11,10 +11,11 @@ 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 BaseAgent."""
+    """Protocol describing the configuration attributes for AgentBase."""
 
     name: str
     description: Optional[str]
@@ -26,24 +27,26 @@ class AgentConfigLike(Protocol):
     model_settings: Optional[Any]
 
 
-class BaseAgent:
+class AgentBase:
     """Factory for creating and configuring specialized agents.
 
     Methods
     -------
     from_config(config, run_context_wrapper)
-        Instantiate a ``BaseAgent`` from configuration.
+        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(agent_input, agent_context, output_type)
+    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(agent_input, agent_context, output_type)
+    run_sync(input, context, output_type)
         Execute the agent synchronously.
-    run_streamed(agent_input, agent_context, output_type)
+    run_streamed(input, context, output_type)
         Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
@@ -56,7 +59,7 @@ class BaseAgent:
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
     ) -> None:
-        """Initialize the ``BaseAgent`` using a configuration object.
+        """Initialize the ``AgentBase`` using a configuration object.
 
         Parameters
         ----------
@@ -88,10 +91,14 @@ class BaseAgent:
         else:
             prompt_path = None
 
-        if prompt_path is not None and prompt_path.exists():
+        if prompt_path is None:
+            self._template = Template("")
+        elif prompt_path.exists():
             self._template = Template(prompt_path.read_text())
         else:
-            self._template = Template("")
+            raise FileNotFoundError(
+                f"Prompt template for agent '{name}' not found at {prompt_path}."
+            )
 
         self.agent_name = name
         self.description = description
@@ -110,8 +117,8 @@ class BaseAgent:
         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.
+    ) -> "AgentBase":
+        """Create a :class:`AgentBase` instance from configuration.
 
         Parameters
         ----------
@@ -126,7 +133,7 @@ class BaseAgent:
 
         Returns
         -------
-        BaseAgent
+        AgentBase
             Instantiated agent.
         """
         return cls(
@@ -136,7 +143,7 @@ class BaseAgent:
             default_model=default_model,
         )
 
-    def _build_instructions_from_jinja(self) -> str:
+    def _build_prompt_from_jinja(self) -> str:
         """Return the rendered instructions prompt for this agent.
 
         Returns
@@ -200,7 +207,7 @@ class BaseAgent:
         """
         agent_config: Dict[str, Any] = {
             "name": self.agent_name,
-            "instructions": self._build_instructions_from_jinja(),
+            "instructions": self._build_prompt_from_jinja(),
             "model": self.model,
         }
         if self._output_type:
@@ -212,19 +219,19 @@ class BaseAgent:
 
         return Agent(**agent_config)
 
-    async def run(
+    async def run_async(
         self,
-        agent_input: str,
-        agent_context: Optional[Dict[str, Any]] = None,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> Any:
         """Execute the agent asynchronously.
 
         Parameters
         ----------
-        agent_input
+        input
             Prompt or query for the agent.
-        agent_context
+        context
             Optional dictionary passed to the agent. Default ``None``.
         output_type
             Optional type used to cast the final output. Default ``None``.
@@ -236,26 +243,26 @@ class BaseAgent:
         """
         if self._output_type is not None and output_type is None:
             output_type = self._output_type
-        return await _run_agent(
+        return await run_async(
             agent=self.get_agent(),
-            agent_input=agent_input,
-            agent_context=agent_context,
+            input=input,
+            context=context,
             output_type=output_type,
         )
 
     def run_sync(
         self,
-        agent_input: str,
-        agent_context: Optional[Dict[str, Any]] = None,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> Any:
         """Run the agent synchronously.
 
         Parameters
         ----------
-        agent_input
+        input
             Prompt or query for the agent.
-        agent_context
+        context
             Optional dictionary passed to the agent. Default ``None``.
         output_type
             Optional type used to cast the final output. Default ``None``.
@@ -265,30 +272,26 @@ class BaseAgent:
         Any
             Agent result, optionally converted to ``output_type``.
         """
-        result = _run_agent_sync(
-            self.get_agent(),
-            agent_input,
-            agent_context=agent_context,
+        return run_sync(
+            agent=self.get_agent(),
+            input=input,
+            context=context,
+            output_type=output_type,
         )
-        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,
+        input: str,
+        context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> RunResultStreaming:
         """Return a streaming result for the agent execution.
 
         Parameters
         ----------
-        agent_input
+        input
             Prompt or query for the agent.
-        agent_context
+        context
             Optional dictionary passed to the agent. Default ``None``.
         output_type
             Optional type used to cast the final output. Default ``None``.
@@ -298,10 +301,10 @@ class BaseAgent:
         RunResultStreaming
             Streaming output wrapper from the agent execution.
         """
-        result = _run_agent_streamed(
+        result = run_streamed(
             agent=self.get_agent(),
-            agent_input=agent_input,
-            context=agent_context,
+            input=input,
+            context=context,
         )
         if self._output_type and not output_type:
             output_type = self._output_type
@@ -324,109 +327,4 @@ class BaseAgent:
         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",
-]
+__all__ = ["AgentConfigLike", "AgentBase"]

{openai_sdk_helpers-0.0.2/src → openai_sdk_helpers-0.0.4}/openai_sdk_helpers/agent/config.py

@@ -1,4 +1,4 @@
-"""Configuration helpers for ``BaseAgent``."""
+"""Configuration helpers for ``AgentBase``."""
 
 from __future__ import annotations
 
@@ -11,7 +11,7 @@ from ..structure import BaseStructure
 
 
 class AgentConfig(BaseStructure):
-    """Configuration required to build a :class:`BaseAgent`.
+    """Configuration required to build a :class:`AgentBase`.
 
     Methods
     -------