openai-sdk-helpers 0.4.1__py3-none-any.whl → 0.4.3__py3-none-any.whl

openai_sdk_helpers/agent/search/web.py

@@ -3,12 +3,13 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Callable, Dict, List, Optional, Union
 
 from agents import custom_span, gen_trace_id, trace
 from agents.model_settings import ModelSettings
 from agents.tool import WebSearchTool
 
+from ...structure.prompt import PromptStructure
 from ...structure.web_search import (
     WebSearchItemStructure,
     WebSearchItemResultStructure,
@@ -16,7 +17,8 @@ from ...structure.web_search import (
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from ..config import AgentConfiguration
+from ...tools import tool_handler_factory
+from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -31,7 +33,7 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
     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.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -82,7 +84,7 @@ class WebSearchToolAgent(
     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.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -187,7 +189,7 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
     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.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -234,7 +236,7 @@ class WebAgentSearch:
     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.
+        Default model identifier to use when not defined in configuration.
 
     Methods
     -------
@@ -242,6 +244,8 @@ class WebAgentSearch:
         Execute the research workflow asynchronously.
     run_agent_sync(search_query)
         Execute the research workflow synchronously.
+    as_response_tool(tool_name, tool_description)
+        Build a Responses API tool definition and handler.
     run_web_agent_async(search_query)
         Convenience asynchronous entry point for the workflow.
     run_web_agent_sync(search_query)
@@ -301,7 +305,7 @@ class WebAgentSearch:
         )
 
     def run_agent_sync(self, search_query: str) -> WebSearchStructure:
-        """Run :meth:`run_agent_async` synchronously for ``search_query``.
+        """Execute the entire research workflow for ``search_query`` synchronously.
 
         Parameters
         ----------
@@ -312,41 +316,41 @@ class WebAgentSearch:
         -------
         WebSearchStructure
             Completed research output.
+
         """
         return run_coroutine_agent_sync(self.run_agent_async(search_query))
 
-    async def run_web_agent_async(self, search_query: str) -> WebSearchStructure:
-        """Return a research report for the given query using ``WebAgentSearch``.
+    def as_response_tool(
+        self,
+        *,
+        tool_name: str = "web_search",
+        tool_description: str = "Run the web search workflow.",
+    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
+        """Return a Responses API tool handler and definition.
 
         Parameters
         ----------
-        search_query : str
-            User's research query.
+        tool_name : str, default="web_search"
+            Name to use for the response tool.
+        tool_description : str, default="Run the web search workflow."
+            Description for the response tool.
 
         Returns
         -------
-        WebSearchStructure
-            Completed research output.
+        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
+            Tool handler mapping and tool definition for Responses API usage.
         """
-        return await self.run_agent_async(search_query=search_query)
 
-    @staticmethod
-    def run_web_agent_sync(search_query: str) -> WebSearchStructure:
-        """Run :meth:`run_web_agent_async` synchronously for ``search_query``.
+        def _run_search(prompt: str) -> WebSearchStructure:
+            return run_coroutine_agent_sync(self.run_agent_async(search_query=prompt))
 
-        Parameters
-        ----------
-        search_query : str
-            User's research query.
-
-        Returns
-        -------
-        WebSearchStructure
-            Completed research output.
-        """
-        return run_coroutine_agent_sync(
-            WebAgentSearch().run_web_agent_async(search_query=search_query)
+        tool_handler = {
+            tool_name: tool_handler_factory(_run_search, input_model=PromptStructure)
+        }
+        tool_definition = PromptStructure.response_tool_definition(
+            tool_name, tool_description=tool_description
         )
+        return tool_handler, tool_definition
 
 
 __all__ = [

openai_sdk_helpers/agent/summarizer.py

@@ -8,8 +8,8 @@ from typing import Any, Dict, Optional, Type
 from ..structure import SummaryStructure
 from ..structure.base import StructureBase
 from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+from .configuration import AgentConfiguration
+from ..environment import DEFAULT_PROMPT_DIR
 
 
 class SummarizerAgent(AgentBase):
@@ -84,7 +84,7 @@ class SummarizerAgent(AgentBase):
         --------
         >>> summarizer = SummarizerAgent(default_model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="summarizer",
             instructions="Agent instructions",
             description="Summarize passages into concise findings.",
@@ -92,7 +92,9 @@ class SummarizerAgent(AgentBase):
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
+            configuration=configuration,
+            prompt_dir=prompt_directory,
+            default_model=default_model,
         )
 
     async def run_agent(

openai_sdk_helpers/agent/translator.py

@@ -5,11 +5,13 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+
 from ..structure import TranslationStructure
 from ..structure.base import StructureBase
+from ..environment import DEFAULT_PROMPT_DIR
+
+from .base import AgentBase
+from .configuration import AgentConfiguration
 
 
 class TranslatorAgent(AgentBase):
@@ -82,7 +84,7 @@ class TranslatorAgent(AgentBase):
         --------
         >>> translator = TranslatorAgent(default_model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="translator",
             instructions="Agent instructions",
             description="Translate text into the requested language.",
@@ -90,7 +92,9 @@ class TranslatorAgent(AgentBase):
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
+            configuration=configuration,
+            prompt_dir=prompt_directory,
+            default_model=default_model,
         )
 
     async def run_agent(

openai_sdk_helpers/agent/{validation.py → validator.py}

@@ -5,10 +5,10 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
+from ..environment import DEFAULT_PROMPT_DIR
 from ..structure.validation import ValidationResultStructure
 from .base import AgentBase
-from .config import AgentConfiguration
-from .prompt_utils import DEFAULT_PROMPT_DIR
+from .configuration import AgentConfiguration
 
 
 class ValidatorAgent(AgentBase):
@@ -81,7 +81,7 @@ class ValidatorAgent(AgentBase):
         --------
         >>> validator = ValidatorAgent(default_model="gpt-4o-mini")
         """
-        config = AgentConfiguration(
+        configuration = AgentConfiguration(
             name="validator",
             instructions="Agent instructions",
             description="Validate user input and agent output against guardrails.",
@@ -89,7 +89,9 @@ class ValidatorAgent(AgentBase):
         )
         prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         super().__init__(
-            config=config, prompt_dir=prompt_directory, default_model=default_model
+            configuration=configuration,
+            prompt_dir=prompt_directory,
+            default_model=default_model,
         )
 
     async def run_agent(

openai_sdk_helpers/cli.py

@@ -18,17 +18,8 @@ registry inspect
 from __future__ import annotations
 
 import argparse
-import json
 import sys
 from pathlib import Path
-from typing import Any
-
-try:
-    import openai_sdk_helpers
-
-    __version__ = getattr(openai_sdk_helpers, "__version__", "unknown")
-except ImportError:
-    __version__ = "unknown"
 
 
 def cmd_agent_test(args: argparse.Namespace) -> int:
@@ -159,8 +150,8 @@ def cmd_registry_list(args: argparse.Namespace) -> int:
 
     print("Registered configurations:")
     for name in sorted(names):
-        config = registry.get(name)
-        tools_count = len(config.tools) if config.tools else 0
+        configuration = registry.get(name)
+        tools_count = len(configuration.tools) if configuration.tools else 0
         print(f"  - {name} ({tools_count} tools)")
 
     return 0
@@ -199,7 +190,7 @@ def cmd_registry_inspect(args: argparse.Namespace) -> int:
     registry = get_default_registry()
 
     try:
-        config = registry.get(args.config_name)
+        configuration = registry.get(args.config_name)
     except KeyError:
         print(f"Error: Configuration '{args.config_name}' not found", file=sys.stderr)
         print("\nAvailable configurations:")
@@ -207,17 +198,17 @@ def cmd_registry_inspect(args: argparse.Namespace) -> int:
             print(f"  - {name}")
         return 1
 
-    print(f"Configuration: {config.name}")
-    instructions_str = str(config.instructions)
+    print(f"Configuration: {configuration.name}")
+    instructions_str = str(configuration.instructions)
     instructions_preview = (
         instructions_str[:100] if len(instructions_str) > 100 else instructions_str
     )
     print(f"Instructions: {instructions_preview}...")
-    print(f"Tools: {len(config.tools) if config.tools else 0}")
+    print(f"Tools: {len(configuration.tools) if configuration.tools else 0}")
 
-    if config.tools:
+    if configuration.tools:
         print("\nTool names:")
-        for tool in config.tools:
+        for tool in configuration.tools:
             tool_name = tool.get("function", {}).get("name", "unknown")
             print(f"  - {tool_name}")
 
@@ -245,11 +236,6 @@ def main(argv: list[str] | None = None) -> int:
         prog="openai-helpers",
         description="OpenAI SDK Helpers CLI",
     )
-    parser.add_argument(
-        "--version",
-        action="version",
-        version=f"openai-sdk-helpers {__version__}",
-    )
 
     subparsers = parser.add_subparsers(dest="command", help="Commands")
 

openai_sdk_helpers/environment.py

@@ -19,9 +19,12 @@ get_data_path(name)
 from __future__ import annotations
 
 from pathlib import Path
+from dotenv import load_dotenv
+
 
 from openai_sdk_helpers.utils import ensure_directory
 
+load_dotenv()
 DATETIME_FMT = "%Y%m%d_%H%M%S"
 DEFAULT_MODEL = "gpt-4o-mini"
 
@@ -54,3 +57,17 @@ def get_data_path(name: str) -> Path:
     base = Path(__file__).parent.parent.parent / "data"
     path = base / name
     return ensure_directory(path)
+
+
+def get_package_path() -> Path:
+    """Return the root path of the openai-sdk-helpers package.
+
+    Returns
+    -------
+    Path
+        Root directory path of the openai-sdk-helpers package.
+    """
+    return Path(__file__).parent
+
+
+DEFAULT_PROMPT_DIR = get_package_path() / "prompt"

openai_sdk_helpers/prompt/vector_planner.jinja

@@ -0,0 +1,7 @@
+You are a vector search planner.
+
+Instructions:
+- Break the user query into 1-5 focused vector search queries.
+- Prefer short, keyword-rich queries optimized for semantic retrieval.
+- Avoid web-search phrasing like "site:" or "latest news."
+- Provide a clear reason for each query.

openai_sdk_helpers/prompt/vector_search.jinja

@@ -0,0 +1,6 @@
+You are a vector search executor.
+
+Instructions:
+- Use the provided search plan to retrieve relevant chunks from the vector store.
+- Return only the retrieved text without adding external context.
+- Do not perform web searches or fabricate sources.

openai_sdk_helpers/prompt/vector_writer.jinja

@@ -0,0 +1,7 @@
+You are a vector search report writer.
+
+Instructions:
+- Use only the provided vector search results.
+- Summarize findings without referencing the public web.
+- If sources are requested, describe them as vector store entries (e.g., file names or "vector store chunk").
+- Keep the report focused on information grounded in the retrieved texts.

openai_sdk_helpers/response/__init__.py

@@ -35,7 +35,7 @@ process_files
 from __future__ import annotations
 
 from .base import ResponseBase
-from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
+from .configuration import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .files import process_files
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_async, run_streamed, run_sync

openai_sdk_helpers/response/base.py

@@ -43,7 +43,7 @@ from openai.types.responses.response_input_text_param import ResponseInputTextPa
 from openai.types.responses.response_output_message import ResponseOutputMessage
 
 from .messages import ResponseMessage, ResponseMessages
-from ..config import OpenAISettings
+from ..settings import OpenAISettings
 from ..structure import StructureBase
 from ..types import OpenAIClient
 from ..utils import (
@@ -55,7 +55,7 @@ from ..utils import (
 )
 
 if TYPE_CHECKING:  # pragma: no cover - only for typing hints
-    from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
+    from openai_sdk_helpers.streamlit_app.configuration import StreamlitAppConfig
 
 T = TypeVar("T", bound=StructureBase)
 ToolHandler = Callable[[ResponseFunctionToolCall], str | Any]
@@ -814,14 +814,14 @@ class ResponseBase(Generic[T]):
 
         Examples
         --------
-        >>> config = MyResponse.build_streamlit_config(
+        >>> configuration = MyResponse.build_streamlit_config(
         ...     display_title="My Assistant",
         ...     description="A helpful AI assistant",
         ...     system_vector_store=["docs", "kb"],
         ...     model="gpt-4"
         ... )
         """
-        from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
+        from openai_sdk_helpers.streamlit_app.configuration import StreamlitAppConfig
 
         normalized_stores = None
         if system_vector_store is not None:

openai_sdk_helpers/response/{config.py → configuration.py}

@@ -6,9 +6,9 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Generic, Optional, Sequence, Type, TypeVar
 
-from ..config import OpenAISettings
+from ..settings import OpenAISettings
 from ..structure.base import StructureBase
-from ..response.base import ResponseBase, ToolHandler
+from .base import ResponseBase, ToolHandler
 from ..utils.json.data_class import DataclassJSONSerializable
 from ..utils.registry import RegistryBase
 from ..utils.instructions import resolve_instructions_from_path
@@ -26,14 +26,14 @@ class ResponseRegistry(RegistryBase["ResponseConfiguration"]):
     Examples
     --------
     >>> registry = ResponseRegistry()
-    >>> config = ResponseConfiguration(
+    >>> configuration = ResponseConfiguration(
     ...     name="test",
     ...     instructions="Test instructions",
     ...     tools=None,
     ...     input_structure=None,
     ...     output_structure=None
     ... )
-    >>> registry.register(config)
+    >>> registry.register(configuration)
     >>> retrieved = registry.get("test")
     >>> retrieved.name
     'test'
@@ -53,8 +53,8 @@ def get_default_registry() -> ResponseRegistry:
     Examples
     --------
     >>> registry = get_default_registry()
-    >>> config = ResponseConfiguration(...)
-    >>> registry.register(config)
+    >>> configuration = ResponseConfiguration(...)
+    >>> registry.register(configuration)
     """
     return _default_registry
 
@@ -119,13 +119,13 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
 
     Examples
     --------
-    >>> config = Configuration(
+    >>> configuration = Configuration(
     ...     name="targeting_to_plan",
     ...     tools=None,
     ...     input_structure=PromptStructure,
     ...     output_structure=WebSearchStructure,
     ... )
-    >>> config.name
+    >>> configuration.name
     'prompt_to_websearch'
     """
 
@@ -135,7 +135,7 @@ class ResponseConfiguration(DataclassJSONSerializable, Generic[TIn, TOut]):
     input_structure: Optional[Type[TIn]]
     output_structure: Optional[Type[TOut]]
     system_vector_store: Optional[list[str]] = None
-    add_output_instructions: bool = True
+    add_output_instructions: bool = False
     add_web_search_tool: bool = False
 
     def __post_init__(self) -> None:

openai_sdk_helpers/response/planner.py

@@ -0,0 +1,12 @@
+"""Planner response configuration."""
+
+from ..structure.plan.plan import PlanStructure
+from .configuration import ResponseConfiguration
+
+PLANNER = ResponseConfiguration(
+    name="planner",
+    instructions="Generates structured prompts based on user input.",
+    tools=None,
+    input_structure=None,
+    output_structure=PlanStructure,
+)

openai_sdk_helpers/response/prompter.py

@@ -0,0 +1,12 @@
+"""Prompter response configuration."""
+
+from .configuration import ResponseConfiguration
+from ..structure.prompt import PromptStructure
+
+PROMPTER = ResponseConfiguration(
+    name="prompter",
+    instructions="Generates structured prompts based on user input.",
+    tools=None,
+    input_structure=None,
+    output_structure=PromptStructure,
+)

openai_sdk_helpers/streamlit_app/__init__.py

@@ -17,7 +17,7 @@ _load_configuration
     Load configuration with user-friendly error handling for Streamlit UI.
 """
 
-from .config import (
+from .configuration import (
     StreamlitAppConfig,
     StreamlitAppRegistry,
     _load_configuration,

openai_sdk_helpers/streamlit_app/app.py

@@ -28,7 +28,6 @@ from openai_sdk_helpers.utils import (
     coerce_jsonable,
     customJSONEncoder,
     ensure_list,
-    log,
 )
 
 # Supported file extensions for OpenAI Assistants file search and vision
@@ -226,7 +225,7 @@ def _build_raw_output(result: Any, response: ResponseBase[Any]) -> dict[str, Any
     }
 
 
-def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
+def _get_response_instance(configuration: StreamlitAppConfig) -> ResponseBase[Any]:
     """Instantiate and cache the configured ResponseBase.
 
     Creates a new response instance from the configuration if not already
@@ -235,7 +234,7 @@ def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
 
     Parameters
     ----------
-    config : StreamlitAppConfig
+    configuration : StreamlitAppConfig
         Loaded configuration with response handler definition.
 
     Returns
@@ -258,13 +257,13 @@ def _get_response_instance(config: StreamlitAppConfig) -> ResponseBase[Any]:
         if isinstance(cached, ResponseBase):
             return cached
 
-    response = config.create_response()
+    response = configuration.create_response()
 
-    if config.preserve_vector_stores:
+    if configuration.preserve_vector_stores:
         setattr(response, "_cleanup_system_vector_storage", False)
         setattr(response, "_cleanup_user_vector_storage", False)
 
-    vector_stores = config.normalized_vector_stores()
+    vector_stores = configuration.normalized_vector_stores()
     if vector_stores:
         attach_vector_store(response=response, vector_stores=vector_stores)
 
@@ -357,7 +356,7 @@ def _render_chat_history() -> None:
 
 def _handle_user_message(
     prompt: str,
-    config: StreamlitAppConfig,
+    configuration: StreamlitAppConfig,
     attachment_paths: list[str] | None = None,
     attachment_names: list[str] | None = None,
 ) -> None:
@@ -371,7 +370,7 @@ def _handle_user_message(
     ----------
     prompt : str
         User-entered text to send to the assistant.
-    config : StreamlitAppConfig
+    configuration : StreamlitAppConfig
         Loaded configuration with response handler definition.
     attachment_paths : list[str] or None, default None
         Optional list of file paths to attach to the message.
@@ -395,7 +394,7 @@ def _handle_user_message(
         {"role": "user", "content": prompt, "attachments": display_names}
     )
     try:
-        response = _get_response_instance(config)
+        response = _get_response_instance(configuration)
     except Exception as exc:  # pragma: no cover - surfaced in UI
         st.error(f"Failed to start response session: {exc}")
         return
@@ -442,15 +441,15 @@ def main(config_path: Path) -> None:
     >>> from pathlib import Path
     >>> main(Path("./my_config.py"))
     """
-    config = _load_configuration(config_path)
-    st.set_page_config(page_title=config.display_title, layout="wide")
+    configuration = _load_configuration(config_path)
+    st.set_page_config(page_title=configuration.display_title, layout="wide")
     _init_session_state()
 
-    st.title(config.display_title)
-    if config.description:
-        st.caption(config.description)
-    if config.model:
-        st.caption(f"Model: {config.model}")
+    st.title(configuration.display_title)
+    if configuration.description:
+        st.caption(configuration.description)
+    if configuration.model:
+        st.caption(f"Model: {configuration.model}")
 
     close_col, _ = st.columns([1, 5])
     with close_col:
@@ -514,7 +513,7 @@ def main(config_path: Path) -> None:
         st.session_state["attachment_names"] = []
         _handle_user_message(
             prompt,
-            config,
+            configuration,
             attachment_paths or None,
             attachment_display_names or None,
         )