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

openai_sdk_helpers/agent/search/base.py

@@ -12,8 +12,8 @@ from abc import ABC, abstractmethod
 from pathlib import Path
 from typing import Generic, List, Optional, TypeVar, Union
 
-from ..base import AgentBase
-from ..config import AgentConfig
+from ..base import BaseAgent
+from ..config import AgentConfiguration
 
 # Type variables for search workflow components
 ItemType = TypeVar("ItemType")  # Search item structure (e.g., WebSearchItemStructure)
@@ -23,7 +23,7 @@ ReportType = TypeVar("ReportType")  # Final report structure
 OutputType = TypeVar("OutputType")  # Generic output type
 
 
-class SearchPlanner(AgentBase, Generic[PlanType]):
+class SearchPlanner(BaseAgent, Generic[PlanType]):
     """Generic planner agent for search workflows.
 
     Subclasses implement specific planner logic by overriding the
@@ -34,7 +34,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
     run_agent(query)
         Generate a search plan for the provided query.
     _configure_agent()
-        Return AgentConfig for this planner instance.
+        Return AgentConfiguration for this planner instance.
     """
 
     def __init__(
@@ -59,17 +59,17 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this planner.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output_type set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_planner",
         ...     description="Plan web searches",
         ...     output_type=WebSearchPlanStructure,
@@ -98,7 +98,7 @@ class SearchPlanner(AgentBase, Generic[PlanType]):
         return result
 
 
-class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
+class SearchToolAgent(BaseAgent, Generic[ItemType, ResultType, PlanType]):
     """Generic tool agent for executing search workflows.
 
     Executes individual searches in a plan with concurrency control.
@@ -112,7 +112,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
     run_search(item)
         Execute a single search item.
     _configure_agent()
-        Return AgentConfig for this tool agent.
+        Return AgentConfiguration for this tool agent.
     """
 
     def __init__(
@@ -142,17 +142,17 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this tool agent.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, input_type, and tools set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_search",
         ...     description="Perform web searches",
         ...     input_type=WebSearchPlanStructure,
@@ -205,7 +205,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
         return [result for result in results if result is not None]
 
 
-class SearchWriter(AgentBase, Generic[ReportType]):
+class SearchWriter(BaseAgent, Generic[ReportType]):
     """Generic writer agent for search workflow reports.
 
     Synthesizes search results into a final report. Subclasses implement
@@ -216,7 +216,7 @@ class SearchWriter(AgentBase, Generic[ReportType]):
     run_agent(query, search_results)
         Generate a report from search results.
     _configure_agent()
-        Return AgentConfig for this writer instance.
+        Return AgentConfiguration for this writer instance.
     """
 
     def __init__(
@@ -241,17 +241,17 @@ class SearchWriter(AgentBase, Generic[ReportType]):
         )
 
     @abstractmethod
-    def _configure_agent(self) -> AgentConfig:
+    def _configure_agent(self) -> AgentConfiguration:
         """Return configuration for this writer.
 
         Returns
         -------
-        AgentConfig
+        AgentConfiguration
             Configuration with name, description, and output_type set.
 
         Examples
         --------
-        >>> config = AgentConfig(
+        >>> config = AgentConfiguration(
         ...     name="web_writer",
         ...     description="Write web search report",
         ...     output_type=WebSearchReportStructure,

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]
@@ -126,10 +127,10 @@ class BaseResponse(Generic[T]):
         instructions: str,
         tools: list | None,
         output_structure: type[T] | None,
-        tool_handlers: dict[str, ToolHandler],
-        openai_settings: OpenAISettings,
         system_vector_store: list[str] | None = None,
         data_path: Path | str | None = None,
+        tool_handlers: dict[str, ToolHandler] | None = None,
+        openai_settings: OpenAISettings | None = None,
     ) -> None:
         """Initialize a response session with OpenAI configuration.
 
@@ -150,18 +151,19 @@ class BaseResponse(Generic[T]):
             Structure class used to parse tool call outputs. When provided,
             the schema is automatically generated using the structure's
             response_format() method. Pass None for unstructured responses.
-        tool_handlers : dict[str, ToolHandler]
-            Mapping from tool names to callable handlers. Each handler receives
-            a ResponseFunctionToolCall and returns a string or any serializable
-            result.
-        openai_settings : OpenAISettings
-            Fully configured OpenAI settings with API key and default model.
         system_vector_store : list[str] or None, default None
             Optional list of vector store names to attach as system context.
         data_path : Path, str, or None, default None
             Optional absolute directory path for storing artifacts. If not provided,
             defaults to get_data_path(class_name). Session files are saved as
             data_path / uuid.json.
+        tool_handlers : dict[str, ToolHandler] or None, default None
+            Mapping from tool names to callable handlers. Each handler receives
+            a ResponseFunctionToolCall and returns a string or any serializable
+            result. Defaults to an empty dict when not provided.
+        openai_settings : OpenAISettings or None, default None
+            Fully configured OpenAI settings with API key and default model.
+            Required for normal operation.
 
         Raises
         ------
@@ -184,6 +186,11 @@ class BaseResponse(Generic[T]):
         ...     openai_settings=settings,
         ... )
         """
+        if tool_handlers is None:
+            tool_handlers = {}
+        if openai_settings is None:
+            raise ValueError("openai_settings is required")
+
         self._tool_handlers = tool_handlers
         self._name = name
 
@@ -247,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.