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

openai_sdk_helpers/agent/search/vector.py

@@ -6,7 +6,9 @@ from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
 from agents import custom_span, gen_trace_id, trace
+from agents.model_settings import ModelSettings
 
+from ...environment import DEFAULT_PROMPT_DIR
 from ...structure.prompt import PromptStructure
 from ...structure.vector_search import (
     VectorSearchItemStructure,
@@ -18,7 +20,7 @@ from ...structure.vector_search import (
 )
 from ...tools import tool_handler_factory
 from ...vector_storage import VectorStorage
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -31,9 +33,10 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     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
     -------
@@ -54,7 +57,8 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
         """Initialize the planner agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(prompt_dir=prompt_directory, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector planner agent.
@@ -69,6 +73,7 @@ class VectorAgentPlanner(SearchPlanner[VectorSearchPlanStructure]):
             instructions="Agent instructions",
             description="Plan vector searches based on a user query.",
             output_structure=VectorSearchPlanStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
 
@@ -84,9 +89,10 @@ class VectorSearchTool(
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     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.
     store_name : str or None, default=None
         Name of the vector store to query.
     max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
@@ -125,13 +131,14 @@ class VectorSearchTool(
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
     ) -> None:
         """Initialize the search tool agent."""
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
         self._vector_storage: Optional[VectorStorage] = None
         self._store_name = store_name or "editorial"
         self._vector_storage_factory = vector_storage_factory
         if vector_storage is not None:
             self._vector_storage = vector_storage
         super().__init__(
-            prompt_dir=prompt_dir,
+            prompt_dir=prompt_directory,
             default_model=default_model,
             max_concurrent_searches=max_concurrent_searches,
         )
@@ -150,6 +157,7 @@ class VectorSearchTool(
             description="Perform vector searches based on a search plan.",
             input_structure=VectorSearchPlanStructure,
             output_structure=VectorSearchItemResultsStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
     def _get_vector_storage(self) -> VectorStorage:
@@ -202,9 +210,10 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     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
     -------
@@ -225,7 +234,8 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
         self, prompt_dir: Optional[Path] = None, default_model: Optional[str] = None
     ) -> None:
         """Initialize the writer agent."""
-        super().__init__(prompt_dir=prompt_dir, default_model=default_model)
+        prompt_directory = prompt_dir or DEFAULT_PROMPT_DIR
+        super().__init__(prompt_dir=prompt_directory, default_model=default_model)
 
     def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector writer agent.
@@ -240,6 +250,7 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
             instructions="Agent instructions",
             description="Write a report based on search results.",
             output_structure=VectorSearchReportStructure,
+            model_settings=ModelSettings(tool_choice="none"),
         )
 
 
@@ -254,9 +265,10 @@ class VectorAgentSearch:
     Parameters
     ----------
     prompt_dir : Path or None, default=None
-        Directory containing prompt templates.
+        Directory containing prompt templates. Defaults to the packaged
+        ``prompt`` directory when not provided.
     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.
     vector_store_name : str or None, default=None
         Name of the vector store to query.
     max_concurrent_searches : int, default=MAX_CONCURRENT_SEARCHES
@@ -318,7 +330,7 @@ class VectorAgentSearch:
         vector_storage_factory: Optional[Callable[[str], VectorStorage]] = None,
     ) -> None:
         """Create the main VectorSearch agent."""
-        self._prompt_dir = prompt_dir
+        self._prompt_dir = prompt_dir or DEFAULT_PROMPT_DIR
         self._default_model = default_model
         self._vector_store_name = vector_store_name
         self._max_concurrent_searches = max_concurrent_searches

openai_sdk_helpers/agent/search/web.py

@@ -18,7 +18,7 @@ from ...structure.web_search import (
     WebSearchReportStructure,
 )
 from ...tools import tool_handler_factory
-from ..config import AgentConfiguration
+from ..configuration import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -33,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
     -------
@@ -84,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
     -------
@@ -189,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
     -------
@@ -236,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
     -------

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

@@ -18,8 +18,6 @@ get_data_path(name)
 
 from __future__ import annotations
 
-import os
-import os
 from pathlib import Path
 from dotenv import load_dotenv
 
@@ -61,18 +59,15 @@ def get_data_path(name: str) -> Path:
     return ensure_directory(path)
 
 
-def get_model() -> str:
-    """Return the default model identifier.
+def get_package_path() -> Path:
+    """Return the root path of the openai-sdk-helpers package.
 
     Returns
     -------
-    str
-        Default OpenAI model identifier.
-
-    Examples
-    --------
-    >>> from openai_sdk_helpers.environment import _get_default_model
-    >>> _get_default_model()
-    'gpt-4o-mini'
+    Path
+        Root directory path of the openai-sdk-helpers package.
     """
-    return os.getenv("DEFAULT_MODEL", DEFAULT_MODEL)
+    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'
     """
 

openai_sdk_helpers/response/planner.py

@@ -1,7 +1,7 @@
 """Planner response configuration."""
 
 from ..structure.plan.plan import PlanStructure
-from .config import ResponseConfiguration
+from .configuration import ResponseConfiguration
 
 PLANNER = ResponseConfiguration(
     name="planner",

openai_sdk_helpers/response/prompter.py

@@ -1,6 +1,6 @@
 """Prompter response configuration."""
 
-from .config import ResponseConfiguration
+from .configuration import ResponseConfiguration
 from ..structure.prompt import PromptStructure
 
 PROMPTER = ResponseConfiguration(

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,
         )