openai-sdk-helpers 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

openai_sdk_helpers/agent/search/vector.py

@@ -16,7 +16,7 @@ from ...structure.vector_search import (
     VectorSearchReportStructure,
 )
 from ...vector_storage import VectorStorage
-from ..config import AgentConfig
+from ..config import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -46,16 +46,17 @@ class VectorSearchPlanner(SearchPlanner[VectorSearchPlanStructure]):
         """
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector planner agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_planner",
+            instructions="Agent instructions",
             description="Plan vector searches based on a user query.",
             output_type=VectorSearchPlanStructure,
         )
@@ -117,16 +118,17 @@ class VectorSearchTool(
             max_concurrent_searches=max_concurrent_searches,
         )
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector search tool agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and input type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_search",
+            instructions="Agent instructions",
             description="Perform vector searches based on a search plan.",
             input_type=VectorSearchPlanStructure,
             output_type=VectorSearchItemResultsStructure,
@@ -199,16 +201,17 @@ class VectorSearchWriter(SearchWriter[VectorSearchReportStructure]):
         """
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the vector writer agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="vector_writer",
+            instructions="Agent instructions",
             description="Write a report based on search results.",
             output_type=VectorSearchReportStructure,
         )

openai_sdk_helpers/agent/search/web.py

@@ -16,7 +16,7 @@ from ...structure.web_search import (
     WebSearchPlanStructure,
     WebSearchReportStructure,
 )
-from ..config import AgentConfig
+from ..config import AgentConfiguration
 from ..utils import run_coroutine_agent_sync
 from .base import SearchPlanner, SearchToolAgent, SearchWriter
 
@@ -46,16 +46,17 @@ class WebAgentPlanner(SearchPlanner[WebSearchPlanStructure]):
         """
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web planner agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="web_planner",
+            instructions="Agent instructions",
             description="Agent that plans web searches based on a user query.",
             output_type=WebSearchPlanStructure,
         )
@@ -94,16 +95,17 @@ class WebSearchToolAgent(
             max_concurrent_searches=MAX_CONCURRENT_SEARCHES,
         )
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web search tool agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, input type, and tools.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="web_search",
+            instructions="Agent instructions",
             description="Agent that performs web searches and summarizes results.",
             input_type=WebSearchPlanStructure,
             tools=[WebSearchTool()],
@@ -185,16 +187,17 @@ class WebAgentWriter(SearchWriter[WebSearchReportStructure]):
         """
         super().__init__(prompt_dir=prompt_dir, default_model=default_model)
 
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for the web writer agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output type.
         """
-        return AgentConfig(
+        return AgentConfiguration(
             name="web_writer",
+            instructions="Agent instructions",
             description="Agent that writes a report based on web search results.",
             output_type=WebSearchReportStructure,
         )

openai_sdk_helpers/agent/summarizer.py

@@ -6,12 +6,12 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 from ..structure import SummaryStructure
-from .base import AgentBase
-from .config import AgentConfig
+from .base import BaseAgent
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
-class SummarizerAgent(AgentBase):
+class SummarizerAgent(BaseAgent):
     """Generate concise summaries from provided text.
 
     This agent uses OpenAI models to create structured summaries from longer-form
@@ -64,8 +64,9 @@ class SummarizerAgent(AgentBase):
         output_type : type, default=SummaryStructure
             Type describing the expected summary output.
         """
-        config = AgentConfig(
+        config = AgentConfiguration(
             name="summarizer",
+            instructions="Agent instructions",
             description="Summarize passages into concise findings.",
             output_type=output_type,
         )

openai_sdk_helpers/agent/translator.py

@@ -5,12 +5,12 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any, Dict, Optional
 
-from .base import AgentBase
-from .config import AgentConfig
+from .base import BaseAgent
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
-class TranslatorAgent(AgentBase):
+class TranslatorAgent(BaseAgent):
     """Translate text into a target language.
 
     This agent provides language translation services using OpenAI models,
@@ -63,8 +63,9 @@ class TranslatorAgent(AgentBase):
         default_model : str or None, default=None
             Fallback model identifier when not specified elsewhere.
         """
-        config = AgentConfig(
+        config = AgentConfiguration(
             name="translator",
+            instructions="Agent instructions",
             description="Translate text into the requested language.",
             output_type=str,
         )

openai_sdk_helpers/agent/validation.py

@@ -6,12 +6,12 @@ from pathlib import Path
 from typing import Any, Dict, Optional
 
 from ..structure.validation import ValidationResultStructure
-from .base import AgentBase
-from .config import AgentConfig
+from .base import BaseAgent
+from .config import AgentConfiguration
 from .prompt_utils import DEFAULT_PROMPT_DIR
 
 
-class ValidatorAgent(AgentBase):
+class ValidatorAgent(BaseAgent):
     """Check user prompts and agent responses against safety guardrails.
 
     This agent validates inputs and outputs to ensure they comply with safety
@@ -64,8 +64,9 @@ class ValidatorAgent(AgentBase):
         default_model : str or None, default=None
             Fallback model identifier when not specified elsewhere.
         """
-        config = AgentConfig(
+        config = AgentConfiguration(
             name="validator",
+            instructions="Agent instructions",
             description="Validate user input and agent output against guardrails.",
             output_type=ValidationResultStructure,
         )

openai_sdk_helpers/response/base.py

@@ -56,6 +56,7 @@ from ..utils import (
 
 if TYPE_CHECKING:  # pragma: no cover - only for typing hints
     from openai_sdk_helpers.streamlit_app.config import StreamlitAppConfig
+    from .config import ResponseConfiguration
 
 T = TypeVar("T", bound=BaseStructure)
 ToolHandler = Callable[[ResponseFunctionToolCall], str | Any]
@@ -253,11 +254,80 @@ class BaseResponse(Generic[T]):
                 ),
             )
 
+            # Add retrieval guidance to system instructions to encourage RAG usage
+            try:
+                store_names = ", ".join(system_vector_store)
+            except Exception:
+                store_names = "attached vector stores"
+            guidance_text = (
+                "Retrieval guidance: You have access to a file_search tool "
+                f"connected to vector store(s) {store_names}. When relevant, "
+                "use file_search to retrieve supporting passages before answering. "
+                "Cite or reference retrieved content when helpful."
+            )
+            system_content.append(
+                ResponseInputTextParam(type="input_text", text=guidance_text)
+            )
+
         self.messages = ResponseMessages()
         self.messages.add_system_message(content=system_content)
         if self._data_path is not None:
             self.save()
 
+    @classmethod
+    def from_configuration(
+        cls: type[RB],
+        config: "ResponseConfiguration[Any, T]",
+        *,
+        openai_settings: OpenAISettings,
+        tool_handlers: dict[str, ToolHandler] | None = None,
+        add_output_instructions: bool = True,
+    ) -> RB:
+        """Construct a response instance from a configuration object.
+
+        Parameters
+        ----------
+        config : ResponseConfiguration
+            Configuration describing the response inputs, outputs, and tools.
+        openai_settings : OpenAISettings
+            OpenAI authentication and model configuration used for the response.
+        tool_handlers : dict[str, ToolHandler] or None, default None
+            Mapping of tool names to callable handlers. Defaults to an empty
+            dictionary when not provided.
+        add_output_instructions : bool, default True
+            Append structured output instructions when an output structure is
+            present.
+
+        Returns
+        -------
+        BaseResponse
+            Instance of ``cls`` configured from ``config``.
+        """
+        handlers = tool_handlers or {}
+
+        output_instructions = ""
+        if config.output_structure is not None and add_output_instructions:
+            output_instructions = config.output_structure.get_prompt(
+                add_enum_values=False
+            )
+
+        instructions = (
+            f"{config.instructions_text}\n{output_instructions}"
+            if output_instructions
+            else config.instructions_text
+        )
+
+        return cls(
+            name=config.name,
+            instructions=instructions,
+            tools=config.tools,
+            output_structure=config.output_structure,
+            system_vector_store=config.system_vector_store,
+            data_path=config.data_path,
+            tool_handlers=handlers,
+            openai_settings=openai_settings,
+        )
+
     @property
     def name(self) -> str:
         """Return the name of this response session.

openai_sdk_helpers/response/config.py

@@ -11,29 +11,18 @@ from ..config import OpenAISettings
 from ..structure.base import BaseStructure
 from ..response.base import BaseResponse, ToolHandler
 from ..utils import JSONSerializable
-from ..utils.path_utils import ensure_directory
+from ..utils.registry import BaseRegistry
+from ..utils.instructions import resolve_instructions_from_path
 
 TIn = TypeVar("TIn", bound="BaseStructure")
 TOut = TypeVar("TOut", bound="BaseStructure")
 
 
-class ResponseRegistry:
+class ResponseRegistry(BaseRegistry["ResponseConfiguration"]):
     """Registry for managing ResponseConfiguration instances.
 
-    Provides centralized storage and retrieval of response configurations,
-    enabling reusable response specs across the application. Configurations
-    are stored by name and can be retrieved or listed as needed.
-
-    Methods
-    -------
-    register(config)
-        Add a ResponseConfiguration to the registry.
-    get(name)
-        Retrieve a configuration by name.
-    list_names()
-        Return all registered configuration names.
-    clear()
-        Remove all registered configurations.
+    Inherits from BaseRegistry to provide centralized storage and retrieval
+    of response configurations, enabling reusable response specs across the application.
 
     Examples
     --------
@@ -51,130 +40,7 @@ class ResponseRegistry:
     'test'
     """
 
-    def __init__(self) -> None:
-        """Initialize an empty registry."""
-        self._configs: dict[str, ResponseConfiguration] = {}
-
-    def register(self, config: ResponseConfiguration) -> None:
-        """Add a ResponseConfiguration to the registry.
-
-        Parameters
-        ----------
-        config : ResponseConfiguration
-            Configuration to register.
-
-        Raises
-        ------
-        ValueError
-            If a configuration with the same name is already registered.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> config = ResponseConfiguration(...)
-        >>> registry.register(config)
-        """
-        if config.name in self._configs:
-            raise ValueError(
-                f"Configuration '{config.name}' is already registered. "
-                "Use a unique name or clear the registry first."
-            )
-        self._configs[config.name] = config
-
-    def get(self, name: str) -> ResponseConfiguration:
-        """Retrieve a configuration by name.
-
-        Parameters
-        ----------
-        name : str
-            Configuration name to look up.
-
-        Returns
-        -------
-        ResponseConfiguration
-            The registered configuration.
-
-        Raises
-        ------
-        KeyError
-            If no configuration with the given name exists.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> config = registry.get("test")
-        """
-        if name not in self._configs:
-            raise KeyError(
-                f"No configuration named '{name}' found. "
-                f"Available: {list(self._configs.keys())}"
-            )
-        return self._configs[name]
-
-    def list_names(self) -> list[str]:
-        """Return all registered configuration names.
-
-        Returns
-        -------
-        list[str]
-            Sorted list of configuration names.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.list_names()
-        []
-        """
-        return sorted(self._configs.keys())
-
-    def clear(self) -> None:
-        """Remove all registered configurations.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.clear()
-        """
-        self._configs.clear()
-
-    def save_to_directory(self, path: Path | str) -> None:
-        """Export all registered configurations to JSON files in a directory.
-
-        Serializes each registered ResponseConfiguration to an individual JSON file
-        named after the configuration. Creates the directory if it does not exist.
-
-        Parameters
-        ----------
-        path : Path or str
-            Directory path where JSON files will be saved. Will be created if
-            it does not already exist.
-
-        Returns
-        -------
-        None
-
-        Raises
-        ------
-        OSError
-            If the directory cannot be created or files cannot be written.
-
-        Examples
-        --------
-        >>> registry = ResponseRegistry()
-        >>> registry.save_to_directory("./data")
-        >>> registry.save_to_directory(Path("exports"))
-        """
-        dir_path = ensure_directory(Path(path))
-        config_names = self.list_names()
-
-        if not config_names:
-            return
-
-        for config_name in config_names:
-            config = self.get(config_name)
-            filename = f"{config_name}.json"
-            filepath = dir_path / filename
-            config.to_json_file(filepath)
+    pass
 
 
 # Global default registry instance
@@ -335,15 +201,7 @@ class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
         return self._resolve_instructions()
 
     def _resolve_instructions(self) -> str:
-        if isinstance(self.instructions, Path):
-            instruction_path = self.instructions.expanduser()
-            try:
-                return instruction_path.read_text(encoding="utf-8")
-            except OSError as exc:
-                raise ValueError(
-                    f"Unable to read instructions at '{instruction_path}': {exc}"
-                ) from exc
-        return self.instructions
+        return resolve_instructions_from_path(self.instructions)
 
     def gen_response(
         self,

openai_sdk_helpers/utils/instructions.py

@@ -0,0 +1,35 @@
+"""Utilities for resolving instructions from strings or file paths."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_instructions_from_path(instructions: str | Path) -> str:
+    """Resolve instructions from a string or file path.
+
+    Parameters
+    ----------
+    instructions : str or Path
+        Either plain-text instructions or a path to a file containing
+        instructions.
+
+    Returns
+    -------
+    str
+        The resolved instruction text.
+
+    Raises
+    ------
+    ValueError
+        If instructions is a Path that cannot be read.
+    """
+    if isinstance(instructions, Path):
+        instruction_path = instructions.expanduser()
+        try:
+            return instruction_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(
+                f"Unable to read instructions at '{instruction_path}': {exc}"
+            ) from exc
+    return instructions

openai_sdk_helpers/utils/json_utils.py

@@ -161,9 +161,17 @@ class JSONSerializable:
                         origin = get_origin(field_type)
                         if origin is Union:
                             type_args = get_args(field_type)
-                            # Check if Path is one of the union types
+                            # Only convert to Path if:
+                            # 1. Path is in the union AND
+                            # 2. str is NOT in the union (to avoid converting string fields)
+                            #    OR the field name suggests it's a path (contains "path")
                             if Path in type_args:
-                                should_convert_to_path = True
+                                if str not in type_args:
+                                    # Path-only union (e.g., Union[Path, None])
+                                    should_convert_to_path = True
+                                elif "path" in key.lower():
+                                    # Field name contains "path", likely meant to be a path
+                                    should_convert_to_path = True
 
                     # Convert string to Path if needed
                     if (