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

openai_sdk_helpers/__init__.py

@@ -16,6 +16,7 @@ from .errors import (
     InputValidationError,
     AsyncExecutionError,
     ResourceCleanupError,
+    ExtractionError,
 )
 
 from .utils.validation import (
@@ -40,6 +41,11 @@ from .structure import (
     ExtendedSummaryStructure,
     ValidationResultStructure,
     AgentBlueprint,
+    AnnotatedDocumentStructure,
+    AttributeStructure,
+    DocumentStructure,
+    ExampleDataStructure,
+    ExtractionStructure,
     create_plan,
     execute_task,
     execute_plan,
@@ -67,15 +73,15 @@ from .response import (
     ResponseConfiguration,
     ResponseRegistry,
     get_default_registry,
-    parse_tool_arguments,
     attach_vector_store,
 )
 from .tools import (
-    serialize_tool_result,
     tool_handler_factory,
     StructureType,
+    ToolHandler,
+    ToolHandlerRegistration,
     ToolSpec,
-    build_tool_definitions,
+    build_tool_definition_list,
 )
 from .settings import build_openai_settings
 from .utils.output_validation import (
@@ -87,7 +93,17 @@ from .utils.output_validation import (
     OutputValidator,
     validate_output,
 )
-
+from .utils.langextract import LangExtractAdapter, build_langextract_adapter
+from .extract import (
+    DocumentExtractor,
+    EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS,
+    EXTRACTOR_CONFIG_GENERATOR,
+    PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS,
+    generate_document_extractor_config,
+    generate_document_extractor_config_with_agent,
+    optimize_extractor_prompt,
+    optimize_extractor_prompt_with_agent,
+)
 
 __all__ = [
     # Environment utilities
@@ -106,6 +122,7 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
+    "ExtractionError",
     # Validation
     "validate_non_empty_string",
     "validate_max_length",
@@ -143,6 +160,11 @@ __all__ = [
     "WebSearchStructure",
     "VectorSearchStructure",
     "ValidationResultStructure",
+    "AnnotatedDocumentStructure",
+    "AttributeStructure",
+    "DocumentStructure",
+    "ExampleDataStructure",
+    "ExtractionStructure",
     "ResponseBase",
     "ResponseMessage",
     "ResponseMessages",
@@ -150,13 +172,13 @@ __all__ = [
     "ResponseConfiguration",
     "ResponseRegistry",
     "get_default_registry",
-    "parse_tool_arguments",
     "attach_vector_store",
-    "serialize_tool_result",
     "tool_handler_factory",
     "StructureType",
+    "ToolHandler",
+    "ToolHandlerRegistration",
     "ToolSpec",
-    "build_tool_definitions",
+    "build_tool_definition_list",
     "build_openai_settings",
     "create_plan",
     "execute_task",
@@ -169,4 +191,16 @@ __all__ = [
     "LengthValidator",
     "OutputValidator",
     "validate_output",
+    # LangExtract
+    "LangExtractAdapter",
+    "build_langextract_adapter",
+    # Extraction helpers
+    "DocumentExtractor",
+    "EXTRACTOR_CONFIG_AGENT_INSTRUCTIONS",
+    "EXTRACTOR_CONFIG_GENERATOR",
+    "PROMPT_OPTIMIZER_AGENT_INSTRUCTIONS",
+    "generate_document_extractor_config",
+    "generate_document_extractor_config_with_agent",
+    "optimize_extractor_prompt",
+    "optimize_extractor_prompt_with_agent",
 ]

openai_sdk_helpers/agent/__init__.py

@@ -5,7 +5,7 @@ from .base import AgentBase
 from .configuration import AgentConfiguration, AgentRegistry, get_default_registry
 from ..structure.plan.enum import AgentEnum
 from .coordinator import CoordinatorAgent
-from .runner import run_sync, run_async, run_streamed
+from .runner import run_sync, run_async
 from .search.base import SearchPlanner, SearchToolAgent, SearchWriter
 from .summarizer import SummarizerAgent
 from .translator import TranslatorAgent
@@ -23,7 +23,6 @@ __all__ = [
     "CoordinatorAgent",
     "run_sync",
     "run_async",
-    "run_streamed",
     "run_coroutine_agent_sync",
     "SearchPlanner",
     "SearchToolAgent",

openai_sdk_helpers/agent/base.py

@@ -2,41 +2,36 @@
 
 from __future__ import annotations
 
-import json
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Protocol, cast
+from typing import TYPE_CHECKING, Any, Dict, Optional, Protocol, cast
 import uuid
 
-from agents import (
-    Agent,
-    Handoff,
-    InputGuardrail,
-    OutputGuardrail,
-    RunResultStreaming,
-    Session,
-)
+from agents import Agent, Handoff, InputGuardrail, OutputGuardrail, Session
 from agents.model_settings import ModelSettings
 from agents.run_context import RunContextWrapper
 from agents.tool import Tool
 from jinja2 import Template
 
+from ..environment import get_data_path
+
 from ..utils.json.data_class import DataclassJSONSerializable
 from ..structure.base import StructureBase
-from ..structure.prompt import PromptStructure
-
+from ..tools import (
+    StructureType,
+    ToolHandlerRegistration,
+    ToolSpec,
+)
 
 from ..utils import (
     check_filepath,
     log,
 )
 
-from ..tools import tool_handler_factory
-
-from .runner import run_async, run_streamed, run_sync
+from .runner import run_async, run_sync
 
 if TYPE_CHECKING:
     from ..settings import OpenAISettings
-    from ..response.base import ResponseBase, ToolHandler
+    from ..response.base import ResponseBase
 
 
 class AgentConfigurationProtocol(Protocol):
@@ -52,18 +47,14 @@ class AgentConfigurationProtocol(Protocol):
         """Agent description."""
         ...
 
-    @property
-    def model(self) -> Optional[str]:
-        """Model identifier."""
-        ...
-
     @property
     def template_path(self) -> Optional[str | Path]:
         """Template path."""
         ...
 
-    def resolve_prompt_path(self, prompt_dir: Path | None = None) -> Path | None:
-        """Resolve the prompt template path."""
+    @property
+    def model(self) -> Optional[str]:
+        """Model identifier."""
         ...
 
     @property
@@ -136,7 +127,7 @@ class AgentBase(DataclassJSONSerializable):
     ...     description="A custom agent",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration)
     >>> result = agent.run_sync("What is 2+2?")
 
     Use absolute path to template:
@@ -146,7 +137,7 @@ class AgentBase(DataclassJSONSerializable):
     ...     template_path="/absolute/path/to/template.jinja",
     ...     model="gpt-4o-mini"
     ... )
-    >>> agent = AgentBase(configuration=configuration, default_model="gpt-4o-mini")
+    >>> agent = AgentBase(configuration=configuration)
 
     Use async execution:
 
@@ -186,8 +177,6 @@ class AgentBase(DataclassJSONSerializable):
         Execute the agent asynchronously and optionally cast the result.
     run_sync(input, context, output_structure, session)
         Execute the agent synchronously.
-    run_streamed(input, context, output_structure, session)
-        Return a streaming result for the agent execution.
     as_tool()
         Return the agent as a callable tool.
     as_response_tool()
@@ -204,8 +193,6 @@ class AgentBase(DataclassJSONSerializable):
         configuration: AgentConfigurationProtocol,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         data_path: Path | str | None = None,
-        prompt_dir: Optional[Path] = None,
-        default_model: Optional[str] = None,
     ) -> None:
         """Initialize the AgentBase using a configuration object.
 
@@ -215,39 +202,31 @@ class AgentBase(DataclassJSONSerializable):
             Configuration describing this agent.
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
-        prompt_dir : Path or None, default=None
-            Optional directory holding prompt templates. Used when
-            ``configuration.template_path`` is not provided or is relative. If
-            ``configuration.template_path`` is an absolute path, this parameter is
-            ignored.
-        default_model : str or None, default=None
-            Optional fallback model identifier if the configuration does not supply one.
+        data_path : Path | str | None, default=None
+            Optional base path for storing agent data.
         """
-        name = configuration.name
-        description = configuration.description or ""
-        model = configuration.model or default_model
-        if not model:
-            raise ValueError("Model is required to construct the agent.")
-
-        prompt_path = configuration.resolve_prompt_path(prompt_dir)
+        self._configuration = configuration
+        self.uuid = uuid.uuid4()
+        self._model = configuration.model
+        if self._model is None:
+            raise ValueError(
+                f"Model must be specified in configuration for agent '{configuration.name}'."
+            )
 
         # Build template from file or fall back to instructions
-        if prompt_path is None:
+        self._template_path = configuration.template_path
+        if self._template_path is None:
             instructions_text = configuration.instructions_text
             self._template = Template(instructions_text)
             self._instructions = instructions_text
-        elif prompt_path.exists():
-            self._template = Template(prompt_path.read_text(encoding="utf-8"))
-            self._instructions = None
         else:
-            raise FileNotFoundError(
-                f"Prompt template for agent '{name}' not found at {prompt_path}."
-            )
-
-        self._name = name
-        self.uuid = uuid.uuid4()
-        self.description = description
-        self.model = model
+            self._template_path = Path(self._template_path)
+            if not self._template_path.exists():
+                raise FileNotFoundError(
+                    f"Template for agent '{self._configuration.name}' not found at {self._template_path}."
+                )
+            self._template = Template(self._template_path.read_text(encoding="utf-8"))
+            self._instructions = None
 
         # Resolve data_path with class name appended
         class_name = self.__class__.__name__
@@ -337,7 +316,29 @@ class AgentBase(DataclassJSONSerializable):
         str
             Name used to identify the agent.
         """
-        return self._name
+        return self._configuration.name
+
+    @property
+    def description(self) -> Optional[str]:
+        """Return the description of this agent.
+
+        Returns
+        -------
+        str or None
+            Description of the agent's purpose.
+        """
+        return self._configuration.description
+
+    @property
+    def model(self) -> str:
+        """Return the model identifier for this agent.
+
+        Returns
+        -------
+        str
+            Model identifier used by the agent.
+        """
+        return self._model  # pyright: ignore[reportReturnType]
 
     @property
     def instructions_text(self) -> str:
@@ -348,9 +349,7 @@ class AgentBase(DataclassJSONSerializable):
         str
             Rendered instructions text using the current run context.
         """
-        if self._instructions is not None:
-            return self._instructions
-        return self._build_prompt_from_jinja()
+        return self._configuration.instructions_text
 
     @property
     def tools(self) -> Optional[list]:
@@ -361,7 +360,7 @@ class AgentBase(DataclassJSONSerializable):
         list or None
             Tool definitions configured for the agent.
         """
-        return self._tools
+        return self._configuration.tools
 
     @property
     def output_structure(self) -> Optional[type[StructureBase]]:
@@ -372,7 +371,7 @@ class AgentBase(DataclassJSONSerializable):
         type[StructureBase] or None
             Output type used to cast responses.
         """
-        return self._output_structure
+        return self._configuration.output_structure
 
     @property
     def model_settings(self) -> Optional[ModelSettings]:
@@ -438,14 +437,14 @@ class AgentBase(DataclassJSONSerializable):
             Initialized agent ready for execution.
         """
         agent_config: Dict[str, Any] = {
-            "name": self._name,
-            "instructions": self._build_prompt_from_jinja() or ".",
-            "model": self.model,
+            "name": self._configuration.name,
+            "instructions": self._configuration.instructions_text or ".",
+            "model": self._model,
         }
-        if self._output_structure:
-            agent_config["output_type"] = self._output_structure
-        if self._tools:
-            agent_config["tools"] = self._tools
+        if self._configuration.output_structure:
+            agent_config["output_type"] = self._configuration.output_structure
+        if self._configuration.tools:
+            agent_config["tools"] = self._configuration.tools
         if self._model_settings:
             agent_config["model_settings"] = self._model_settings
         if self._handoffs:
@@ -535,47 +534,6 @@ class AgentBase(DataclassJSONSerializable):
             session=session_to_use,
         )
 
-    def run_streamed(
-        self,
-        input: str,
-        *,
-        context: Optional[Dict[str, Any]] = None,
-        output_structure: Optional[type[StructureBase]] = None,
-        session: Optional[Any] = None,
-    ) -> RunResultStreaming | StructureBase:
-        """Stream the agent execution results.
-
-        Parameters
-        ----------
-        input : str
-            Prompt or query for the agent.
-        context : dict or None, default=None
-            Optional dictionary passed to the agent.
-        output_structure : type[StructureBase] or None, default=None
-            Optional type used to cast the final output.
-        session : Session or None, default=None
-            Optional session for maintaining conversation history across runs.
-            If not provided, uses the session from configuration if available.
-
-        Returns
-        -------
-        RunResultStreaming
-            Streaming output wrapper from the agent execution.
-        """
-        # Use session from parameter, fall back to configuration session
-        session_to_use = session if session is not None else self._session
-        output_structure_to_use = output_structure or self._output_structure
-        result = run_streamed(
-            agent=self.get_agent(),
-            input=input,
-            context=context,
-            output_structure=output_structure_to_use,
-            session=session_to_use,
-        )
-        if output_structure_to_use and hasattr(result, "final_output_as"):
-            return cast(Any, result).final_output_as(output_structure_to_use)
-        return result
-
     def as_tool(self) -> Tool:
         """Return the agent as a callable tool.
 
@@ -586,78 +544,35 @@ class AgentBase(DataclassJSONSerializable):
         """
         agent = self.get_agent()
         tool_obj: Tool = agent.as_tool(
-            tool_name=self._name, tool_description=self.description
+            tool_name=self._configuration.name,
+            tool_description=self._configuration.description,
         )
         return tool_obj
 
-    def as_response_tool(
+    def as_tool_handler_registration(
         self,
-        *,
-        tool_name: str | None = None,
-        tool_description: str | None = None,
-    ) -> tuple[dict[str, Callable[..., Any]], dict[str, Any]]:
-        """Return response tool handler and definition for Responses API use.
-
-        The returned handler serializes tool output as JSON using
-        ``tool_handler_factory`` so downstream response flows can rely on a
-        consistent payload format.
+    ) -> ToolHandlerRegistration:
+        """Return the agent as a ToolHandlerRegistration for Responses API use.
 
         Parameters
         ----------
         tool_name : str or None, default=None
             Optional override for the tool name. When None, uses the agent name.
-        tool_description : str or None, default=None
-            Optional override for the tool description. When None, uses the
-            agent description.
-
-        Returns
-        -------
-        tuple[dict[str, Callable[..., Any]], dict[str, Any]]
-            Tool handler mapping and tool definition for Responses API usage.
-
-        Examples
-        --------
-        >>> tool_handler, tool_definition = agent.as_response_tool()
-        >>> response = ResponseBase(
-        ...     name="agent_tool",
-        ...     instructions="Use the agent tool when needed.",
-        ...     tools=[tool_definition],
-        ...     output_structure=None,
-        ...     tool_handlers=tool_handler,
-        ...     openai_settings=settings,
-        ... )
-        >>> response.run_sync("Invoke the agent tool")  # doctest: +SKIP
         """
-
-        def _run_agent(**kwargs: Any) -> Any:
-            prompt = kwargs.get("prompt")
-            if prompt is None:
-                if len(kwargs) == 1:
-                    prompt = next(iter(kwargs.values()))
-                else:
-                    prompt = json.dumps(kwargs)
-            return self.run_sync(str(prompt))
-
-        name = tool_name or self.name
-        description = tool_description or self.description
-        input_model = self._input_structure or PromptStructure
-        tool_handler = {name: tool_handler_factory(_run_agent, input_model=input_model)}
-        tool_definition = {
-            "type": "function",
-            "name": name,
-            "description": description,
-            "strict": True,
-            "additionalProperties": False,
-            "parameters": self._build_response_parameters(),
-        }
-        return tool_handler, tool_definition
+        tool_spec = ToolSpec(
+            tool_name=self.name,
+            tool_description=self.description,
+            input_structure=cast(StructureType, self._configuration.input_structure),
+            output_structure=cast(StructureType, self._configuration.output_structure),
+        )
+        return ToolHandlerRegistration(handler=self.run_sync, tool_spec=tool_spec)
 
     def build_response(
         self,
         *,
         openai_settings: OpenAISettings,
         data_path: Path | str | None = None,
-        tool_handlers: dict[str, ToolHandler] | None = None,
+        tool_handlers: dict[str, ToolHandlerRegistration] | None = None,
         system_vector_store: list[str] | None = None,
     ) -> ResponseBase[StructureBase]:
         """Build a ResponseBase instance from this agent configuration.
@@ -669,8 +584,9 @@ class AgentBase(DataclassJSONSerializable):
         data_path : Path, str, or None, default None
             Optional path for storing response artifacts. When None, the
             response uses the default data directory.
-        tool_handlers : dict[str, ToolHandler] or None, default None
-            Optional mapping of tool names to handler callables.
+        tool_handlers : dict[str, ToolHandlerRegistration] or None, default None
+            Optional mapping of tool names to handler registrations. Registrations
+            can include ToolSpec metadata to parse tool outputs by name.
         system_vector_store : list[str] or None, default None
             Optional list of vector store names to attach as system context.
 
@@ -684,7 +600,7 @@ class AgentBase(DataclassJSONSerializable):
         >>> from openai_sdk_helpers import OpenAISettings
         >>> response = agent.build_response(openai_settings=OpenAISettings.from_env())
         """
-        from ..response.base import ResponseBase, ToolHandler
+        from ..response.base import ResponseBase
         from ..settings import OpenAISettings
 
         if not isinstance(openai_settings, OpenAISettings):
@@ -693,8 +609,8 @@ class AgentBase(DataclassJSONSerializable):
         tools = self._normalize_response_tools(self.tools)
 
         return ResponseBase(
-            name=self.name,
-            instructions=self.instructions_text,
+            name=self._configuration.name,
+            instructions=self._configuration.instructions_text,
             tools=tools,
             output_structure=self.output_structure,
             system_vector_store=system_vector_store,
@@ -773,7 +689,7 @@ class AgentBase(DataclassJSONSerializable):
 
         Examples
         --------
-        >>> agent = AgentBase(configuration, default_model="gpt-4o-mini")
+        >>> agent = AgentBase(configuration)
         >>> try:
         ...     result = agent.run_sync("query")
         ... finally:
@@ -790,7 +706,7 @@ class AgentBase(DataclassJSONSerializable):
         str
             String representation including agent name and model.
         """
-        return f"<AgentBase name={self._name!r} model={self.model!r}>"
+        return f"<AgentBase name={self.name!r} model={self.model!r}>"
 
     def save(self, filepath: str | Path | None = None) -> None:
         """Serialize the message history to a JSON file.
@@ -809,7 +725,7 @@ class AgentBase(DataclassJSONSerializable):
             target = Path(filepath)
         else:
             filename = f"{str(self.uuid).lower()}.json"
-            target = self._data_path / self._name / filename
+            target = self._data_path / self.name / filename
 
         checked = check_filepath(filepath=target)
         self.to_json_file(filepath=checked)

openai_sdk_helpers/agent/configuration.py

@@ -150,7 +150,7 @@ class AgentConfiguration(DataclassJSONSerializable):
         Return the resolved instruction content as a string.
     resolve_prompt_path(prompt_dir)
         Resolve the prompt template path for this configuration.
-    gen_agent(run_context_wrapper, prompt_dir, default_model)
+    gen_agent(run_context_wrapper)
         Create a AgentBase instance from this configuration.
     replace(**changes)
         Create a new AgentConfiguration with specified fields replaced.
@@ -176,17 +176,17 @@ class AgentConfiguration(DataclassJSONSerializable):
 
     name: str
     instructions: str | Path
-    description: Optional[str] = None
-    model: Optional[str] = None
-    template_path: Optional[str | Path] = None
-    input_structure: Optional[Type[StructureBase]] = None
-    output_structure: Optional[Type[StructureBase]] = None
-    tools: Optional[list] = None
-    model_settings: Optional[ModelSettings] = None
-    handoffs: Optional[list[Agent | Handoff]] = None
-    input_guardrails: Optional[list[InputGuardrail]] = None
-    output_guardrails: Optional[list[OutputGuardrail]] = None
-    session: Optional[Session] = None
+    description: str | None = None
+    model: str | None = None
+    template_path: str | Path | None = None
+    input_structure: type[StructureBase] | None = None
+    output_structure: type[StructureBase] | None = None
+    tools: list | None = None
+    model_settings: ModelSettings | None = None
+    handoffs: list[Agent | Handoff] | None = None
+    input_guardrails: list[InputGuardrail] | None = None
+    output_guardrails: list[OutputGuardrail] | None = None
+    session: Session | None = None
     add_output_instructions: bool = False
     add_web_search_tool: bool = False
 
@@ -294,8 +294,6 @@ class AgentConfiguration(DataclassJSONSerializable):
     def gen_agent(
         self,
         run_context_wrapper: Any = None,
-        prompt_dir: Path | None = None,
-        default_model: str | None = None,
     ) -> Any:
         """Create a AgentBase instance from this configuration.
 
@@ -305,10 +303,6 @@ class AgentConfiguration(DataclassJSONSerializable):
         ----------
         run_context_wrapper : RunContextWrapper or None, default=None
             Optional wrapper providing runtime context for prompt rendering.
-        prompt_dir : Path or None, default=None
-            Optional directory holding prompt templates.
-        default_model : str or None, default=None
-            Optional fallback model identifier if configuration doesn't specify one.
 
         Returns
         -------
@@ -329,8 +323,6 @@ class AgentConfiguration(DataclassJSONSerializable):
         return AgentBase(
             configuration=self,
             run_context_wrapper=run_context_wrapper,
-            prompt_dir=prompt_dir,
-            default_model=default_model,
         )
 
     def replace(self, **changes: Any) -> AgentConfiguration: