openai-sdk-helpers 0.0.2__py3-none-any.whl → 0.0.3__py3-none-any.whl

openai_sdk_helpers/response/base.py

@@ -1,477 +0,0 @@
-"""Base response handling for OpenAI interactions."""
-
-from __future__ import annotations
-
-import asyncio
-import inspect
-import json
-import logging
-import threading
-import uuid
-from pathlib import Path
-from typing import (
-    Any,
-    Callable,
-    Generic,
-    List,
-    Optional,
-    Tuple,
-    Type,
-    TypeVar,
-    Union,
-    cast,
-)
-
-from openai import OpenAI
-from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
-from openai.types.responses.response_input_file_param import ResponseInputFileParam
-from openai.types.responses.response_input_message_content_list_param import (
-    ResponseInputMessageContentListParam,
-)
-from openai.types.responses.response_input_param import ResponseInputItemParam
-from openai.types.responses.response_input_text_param import ResponseInputTextParam
-from openai.types.responses.response_output_message import ResponseOutputMessage
-
-from .messages import ResponseMessages
-from ..structure import BaseStructure
-from ..utils import ensure_list, log
-
-T = TypeVar("T", bound=BaseStructure)
-ToolHandler = Callable[[ResponseFunctionToolCall], Union[str, Any]]
-ProcessContent = Callable[[str], Tuple[str, List[str]]]
-
-
-class ResponseBase(Generic[T]):
-    """Manage OpenAI interactions for structured responses.
-
-    This base class handles input construction, OpenAI requests, tool calls,
-    and optional parsing into structured output models.
-
-    Methods
-    -------
-    generate_response_async(content, attachments)
-        Generate a response asynchronously and return parsed output.
-    generate_response(content, attachments)
-        Synchronous wrapper around ``generate_response_async``.
-    save(filepath)
-        Serialize the message history to disk.
-    close()
-        Clean up remote resources (vector stores).
-    """
-
-    def __init__(
-        self,
-        *,
-        instructions: str,
-        tools: Optional[list],
-        schema: Optional[Any],
-        output_structure: Optional[Type[T]],
-        tool_handlers: dict[str, ToolHandler],
-        process_content: Optional[ProcessContent] = None,
-        module_name: Optional[str] = None,
-        vector_storage_cls: Optional[type] = None,
-        client: Optional[OpenAI] = None,
-        model: Optional[str] = None,
-        api_key: Optional[str] = None,
-        attachments: Optional[Union[Tuple[str, str], list[Tuple[str, str]]]] = None,
-        data_path_fn: Optional[Callable[[str], Path]] = None,
-        save_path: Optional[Path | str] = None,
-    ) -> None:
-        """Initialize a response session.
-
-        Parameters
-        ----------
-        instructions : str
-            System instructions for the OpenAI response.
-        tools : list or None
-            Tool definitions for the OpenAI request.
-        schema : object or None
-            Optional response schema configuration.
-        output_structure : type[BaseStructure] or None
-            Structure type used to parse tool call outputs.
-        tool_handlers : dict[str, ToolHandler]
-            Mapping of tool names to handler callables.
-        process_content : callable, optional
-            Callback that cleans input text and extracts attachments.
-        module_name : str, optional
-            Module name used to build the data path.
-        vector_storage_cls : type, optional
-            Vector storage class used for file uploads.
-        client : OpenAI or None, default=None
-            Optional pre-initialized OpenAI client.
-        model : str or None, default=None
-            Optional OpenAI model name override.
-        api_key : str or None, default=None
-            Optional OpenAI API key override.
-        attachments : tuple or list of tuples, optional
-            File attachments in the form ``(file_path, tool_type)``.
-        data_path_fn : callable or None, default=None
-            Function that maps ``module_name`` to a base data path.
-        save_path : Path | str or None, default=None
-            Optional path to a directory or file for persisted messages.
-
-        Raises
-        ------
-        ValueError
-            If API key or model is missing.
-        RuntimeError
-            If the OpenAI client fails to initialize.
-        """
-        self._tool_handlers = tool_handlers
-        self._process_content = process_content
-        self._module_name = module_name
-        self._vector_storage_cls = vector_storage_cls
-        self._data_path_fn = data_path_fn
-        self._save_path = Path(save_path) if save_path is not None else None
-        self._instructions = instructions
-        self._tools = tools if tools is not None else []
-        self._schema = schema
-        self._output_structure = output_structure
-
-        if client is None:
-            if api_key is None:
-                raise ValueError("OpenAI API key is required")
-            try:
-                self._client = OpenAI(api_key=api_key)
-            except Exception as exc:
-                raise RuntimeError("Failed to initialize OpenAI client") from exc
-        else:
-            self._client = client
-
-        self._model = model
-        if not self._model:
-            raise ValueError("OpenAI model is required")
-
-        self.uuid = uuid.uuid4()
-        self.name = self.__class__.__name__.lower()
-
-        system_content: ResponseInputMessageContentListParam = [
-            ResponseInputTextParam(type="input_text", text=instructions)
-        ]
-
-        self._system_vector_storage: Optional[Any] = None
-        self._user_vector_storage: Optional[Any] = None
-
-        if attachments:
-            if self._vector_storage_cls is None:
-                raise RuntimeError("vector_storage_cls is required for attachments.")
-            self.file_objects: dict[str, List[str]] = {}
-            storage_name = f"{self.__class__.__name__.lower()}_{self.name}_system"
-            self._system_vector_storage = self._vector_storage_cls(
-                store_name=storage_name, client=self._client, model=self._model
-            )
-            system_vector_storage = cast(Any, self._system_vector_storage)
-            for file_path, tool_type in attachments:
-                uploaded_file = system_vector_storage.upload_file(file_path=file_path)
-                self.file_objects.setdefault(tool_type, []).append(uploaded_file.id)
-
-            self.tool_resources = {}
-            required_tools = []
-
-            for tool_type, file_ids in self.file_objects.items():
-                required_tools.append({"type": tool_type})
-                self.tool_resources[tool_type] = {"file_ids": file_ids}
-                if tool_type == "file_search":
-                    self.tool_resources[tool_type]["vector_store_ids"] = [
-                        system_vector_storage.id
-                    ]
-
-            existing_tool_types = {tool["type"] for tool in self._tools}
-            for tool in required_tools:
-                tool_type = tool["type"]
-                if tool_type == "file_search":
-                    tool["vector_store_ids"] = [system_vector_storage.id]
-                if tool_type not in existing_tool_types:
-                    self._tools.append(tool)
-
-        self.messages = ResponseMessages()
-        self.messages.add_system_message(content=system_content)
-        if self._save_path is not None or (
-            self._data_path_fn is not None and self._module_name is not None
-        ):
-            self.save()
-
-    @property
-    def data_path(self) -> Path:
-        """Return the directory used to persist artifacts for this session.
-
-        Returns
-        -------
-        Path
-            Absolute path for persisting response artifacts.
-        """
-        if self._data_path_fn is None or self._module_name is None:
-            raise RuntimeError(
-                "data_path_fn and module_name are required to build data paths."
-            )
-        base_path = self._data_path_fn(self._module_name)
-        return base_path / self.__class__.__name__.lower() / self.name
-
-    def _build_input(
-        self,
-        content: Union[str, List[str]],
-        attachments: Optional[List[str]] = None,
-    ) -> None:
-        """Build the list of input messages for the OpenAI request.
-
-        Parameters
-        ----------
-        content
-            String or list of strings to include as user messages.
-        attachments
-            Optional list of file paths to upload and attach.
-        """
-        contents = ensure_list(content)
-
-        for raw_content in contents:
-            if self._process_content is None:
-                processed_text, content_attachments = raw_content, []
-            else:
-                processed_text, content_attachments = self._process_content(raw_content)
-            input_content: List[
-                Union[ResponseInputTextParam, ResponseInputFileParam]
-            ] = [ResponseInputTextParam(type="input_text", text=processed_text)]
-
-            all_attachments = (attachments or []) + content_attachments
-
-            for file_path in all_attachments:
-                if self._user_vector_storage is None:
-                    if self._vector_storage_cls is None:
-                        raise RuntimeError(
-                            "vector_storage_cls is required for attachments."
-                        )
-                    store_name = f"{self.__class__.__name__.lower()}_{self.name}_{self.uuid}_user"
-                    self._user_vector_storage = self._vector_storage_cls(
-                        store_name=store_name,
-                        client=self._client,
-                        model=self._model,
-                    )
-                    user_vector_storage = cast(Any, self._user_vector_storage)
-                    if not any(
-                        tool.get("type") == "file_search" for tool in self._tools
-                    ):
-                        self._tools.append(
-                            {
-                                "type": "file_search",
-                                "vector_store_ids": [user_vector_storage.id],
-                            }
-                        )
-                    else:
-                        for tool in self._tools:
-                            if tool.get("type") == "file_search":
-                                if self._system_vector_storage is not None:
-                                    tool["vector_store_ids"] = [
-                                        cast(Any, self._system_vector_storage).id,
-                                        user_vector_storage.id,
-                                    ]
-                user_vector_storage = cast(Any, self._user_vector_storage)
-                uploaded_file = user_vector_storage.upload_file(file_path)
-                input_content.append(
-                    ResponseInputFileParam(type="input_file", file_id=uploaded_file.id)
-                )
-
-            message = cast(
-                ResponseInputItemParam,
-                {"role": "user", "content": input_content},
-            )
-            self.messages.add_user_message(message)
-
-    async def generate_response_async(
-        self,
-        content: Union[str, List[str]],
-        attachments: Optional[Union[str, List[str]]] = None,
-    ) -> Optional[T]:
-        """Generate a response asynchronously.
-
-        Parameters
-        ----------
-        content
-            Prompt text or list of texts.
-        attachments
-            Optional file path or list of paths to upload and attach.
-
-        Returns
-        -------
-        Optional[T]
-            Parsed response object or ``None``.
-
-        Raises
-        ------
-        RuntimeError
-            If the API returns no output or a tool handler errors.
-        ValueError
-            If no handler is found for a tool invoked by the API.
-        """
-        log(f"{self.__class__.__name__}::generate_response")
-        parsed_result: Optional[T] = None
-
-        self._build_input(
-            content=content,
-            attachments=(ensure_list(attachments) if attachments else None),
-        )
-
-        kwargs = {
-            "input": self.messages.to_openai_payload(),
-            "model": self._model,
-        }
-        if self._schema is not None:
-            kwargs["text"] = self._schema
-
-        if self._tools:
-            kwargs["tools"] = self._tools
-            kwargs["tool_choice"] = "auto"
-        response = self._client.responses.create(**kwargs)
-
-        if not response.output:
-            log("No output returned from OpenAI.", level=logging.ERROR)
-            raise RuntimeError("No output returned from OpenAI.")
-
-        for response_output in response.output:
-            if isinstance(response_output, ResponseFunctionToolCall):
-                log(
-                    f"Tool call detected. Executing {response_output.name}.",
-                    level=logging.INFO,
-                )
-
-                tool_name = response_output.name
-                handler = self._tool_handlers.get(tool_name)
-
-                if handler is None:
-                    log(
-                        f"No handler found for tool '{tool_name}'",
-                        level=logging.ERROR,
-                    )
-                    raise ValueError(f"No handler for tool: {tool_name}")
-
-                try:
-                    if inspect.iscoroutinefunction(handler):
-                        tool_result_json = await handler(response_output)
-                    else:
-                        tool_result_json = handler(response_output)
-                    if isinstance(tool_result_json, str):
-                        tool_result = json.loads(tool_result_json)
-                        tool_output = tool_result_json
-                    else:
-                        tool_result = tool_result_json
-                        tool_output = json.dumps(tool_result)
-                    self.messages.add_tool_message(
-                        content=response_output, output=tool_output
-                    )
-                    self.save()
-                except Exception as exc:
-                    log(
-                        f"Error executing tool handler '{tool_name}': {exc}",
-                        level=logging.ERROR,
-                    )
-                    raise RuntimeError(f"Error in tool handler '{tool_name}': {exc}")
-
-                if self._output_structure:
-                    output_dict = self._output_structure.from_raw_input(tool_result)
-                    output_dict.console_print()
-                    parsed_result = output_dict
-                else:
-                    print(tool_result)
-                    parsed_result = cast(T, tool_result)
-
-            if isinstance(response_output, ResponseOutputMessage):
-                self.messages.add_assistant_message(response_output, kwargs)
-                self.save()
-                if hasattr(response, "output_text") and response.output_text:
-                    raw_text = response.output_text
-                    log("No tool call. Parsing output_text.")
-                    try:
-                        output_dict = json.loads(raw_text)
-                        if self._output_structure and self._schema:
-                            return self._output_structure.from_raw_input(output_dict)
-                        return output_dict
-                    except Exception:
-                        print(raw_text)
-        if parsed_result is not None:
-            return parsed_result
-        return None
-
-    def generate_response(
-        self,
-        content: Union[str, List[str]],
-        attachments: Optional[Union[str, List[str]]] = None,
-    ) -> Optional[T]:
-        """Run :meth:`generate_response_async` synchronously."""
-
-        async def runner() -> Optional[T]:
-            return await self.generate_response_async(
-                content=content, attachments=attachments
-            )
-
-        try:
-            asyncio.get_running_loop()
-        except RuntimeError:
-            return asyncio.run(runner())
-        result: Optional[T] = None
-
-        def _thread_func() -> None:
-            nonlocal result
-            result = asyncio.run(runner())
-
-        thread = threading.Thread(target=_thread_func)
-        thread.start()
-        thread.join()
-        return result
-
-    def save(self, filepath: Optional[str | Path] = None) -> None:
-        """Serialize the message history to a JSON file."""
-        if filepath is not None:
-            target = Path(filepath)
-        elif self._save_path is not None:
-            if self._save_path.suffix == ".json":
-                target = self._save_path
-            else:
-                filename = f"{str(self.uuid).lower()}.json"
-                target = self._save_path / filename
-        elif self._data_path_fn is not None and self._module_name is not None:
-            filename = f"{str(self.uuid).lower()}.json"
-            target = self.data_path / filename
-        else:
-            log(
-                "Skipping save: no filepath, save_path, or data_path_fn configured.",
-                level=logging.DEBUG,
-            )
-            return
-
-        self.messages.to_json_file(str(target))
-        log(f"Saved messages to {target}")
-
-    def __repr__(self) -> str:
-        """Return an unambiguous representation including model and UUID."""
-        data_path = None
-        if self._data_path_fn is not None and self._module_name is not None:
-            data_path = self.data_path
-        return (
-            f"<{self.__class__.__name__}(model={self._model}, uuid={self.uuid}, "
-            f"messages={len(self.messages.messages)}, data_path={data_path}>"
-        )
-
-    def __enter__(self) -> "ResponseBase[T]":
-        """Enter the context manager for this response session."""
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
-        """Exit the context manager and close remote resources."""
-        self.close()
-
-    def close(self) -> None:
-        """Delete remote vector stores and clean up the session."""
-        log(f"Closing session {self.uuid} for {self.__class__.__name__}")
-
-        try:
-            if self._user_vector_storage:
-                self._user_vector_storage.delete()
-                log("User vector store deleted.")
-        except Exception as exc:
-            log(f"Error deleting user vector store: {exc}", level=logging.WARNING)
-        try:
-            if self._system_vector_storage:
-                self._system_vector_storage.delete()
-                log("System vector store deleted.")
-        except Exception as exc:
-            log(f"Error deleting system vector store: {exc}", level=logging.WARNING)
-        log(f"Session {self.uuid} closed.")

openai_sdk_helpers/response/messages.py

@@ -1,211 +0,0 @@
-"""Message containers for shared OpenAI responses."""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from typing import Dict, List, Union, cast
-
-from openai.types.responses.response_function_tool_call import ResponseFunctionToolCall
-from openai.types.responses.response_function_tool_call_param import (
-    ResponseFunctionToolCallParam,
-)
-from openai.types.responses.response_input_message_content_list_param import (
-    ResponseInputMessageContentListParam,
-)
-from openai.types.responses.response_input_param import (
-    FunctionCallOutput,
-    ResponseInputItemParam,
-)
-from openai.types.responses.response_output_message import ResponseOutputMessage
-
-from ..utils import JSONSerializable
-from .tool_call import ResponseToolCall
-
-
-@dataclass
-class ResponseMessage(JSONSerializable):
-    """Single message exchanged with the OpenAI client.
-
-    Methods
-    -------
-    to_openai_format()
-        Return the payload in the format expected by the OpenAI client.
-    """
-
-    role: str  # "user", "assistant", "tool", etc.
-    content: (
-        ResponseInputItemParam
-        | ResponseOutputMessage
-        | ResponseFunctionToolCallParam
-        | FunctionCallOutput
-        | ResponseInputMessageContentListParam
-    )
-    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
-    metadata: Dict[str, Union[str, float, bool]] = field(default_factory=dict)
-
-    def to_openai_format(
-        self,
-    ) -> (
-        ResponseInputItemParam
-        | ResponseOutputMessage
-        | ResponseFunctionToolCallParam
-        | FunctionCallOutput
-        | ResponseInputMessageContentListParam
-    ):
-        """Return the message in the format expected by the OpenAI client.
-
-        Returns
-        -------
-        ResponseInputItemParam | ResponseOutputMessage | ResponseFunctionToolCallParam | FunctionCallOutput | ResponseInputMessageContentListParam
-            Stored message content in OpenAI format.
-        """
-        return self.content
-
-
-@dataclass
-class ResponseMessages(JSONSerializable):
-    """Represent a collection of messages in a response.
-
-    This dataclass encapsulates user inputs and assistant outputs during an
-    OpenAI API interaction.
-
-    Methods
-    -------
-    add_system_message(content, **metadata)
-        Append a system message to the conversation.
-    add_user_message(input_content, **metadata)
-        Append a user message to the conversation.
-    add_assistant_message(content, metadata)
-        Append an assistant message to the conversation.
-    add_tool_message(content, output, **metadata)
-        Record a tool call and its output.
-    to_openai_payload()
-        Convert stored messages to the OpenAI input payload.
-    """
-
-    messages: List[ResponseMessage] = field(default_factory=list)
-
-    def add_system_message(
-        self, content: ResponseInputMessageContentListParam, **metadata
-    ) -> None:
-        """Append a system message to the conversation.
-
-        Parameters
-        ----------
-        content : ResponseInputMessageContentListParam
-            System message content in OpenAI format.
-        **metadata
-            Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
-        """
-        response_input = cast(
-            ResponseInputItemParam, {"role": "system", "content": content}
-        )
-        self.messages.append(
-            ResponseMessage(role="system", content=response_input, metadata=metadata)
-        )
-
-    def add_user_message(
-        self, input_content: ResponseInputItemParam, **metadata
-    ) -> None:
-        """Append a user message to the conversation.
-
-        Parameters
-        ----------
-        input_content : ResponseInputItemParam
-            Message payload supplied by the user.
-        **metadata
-            Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
-        """
-        self.messages.append(
-            ResponseMessage(role="user", content=input_content, metadata=metadata)
-        )
-
-    def add_assistant_message(
-        self,
-        content: ResponseOutputMessage,
-        metadata: Dict[str, Union[str, float, bool]],
-    ) -> None:
-        """Append an assistant message to the conversation.
-
-        Parameters
-        ----------
-        content : ResponseOutputMessage
-            Assistant response message.
-        metadata : dict[str, Union[str, float, bool]]
-            Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
-        """
-        self.messages.append(
-            ResponseMessage(role="assistant", content=content, metadata=metadata)
-        )
-
-    def add_tool_message(
-        self, content: ResponseFunctionToolCall, output: str, **metadata
-    ) -> None:
-        """Record a tool call and its output in the conversation history.
-
-        Parameters
-        ----------
-        content : ResponseFunctionToolCall
-            Tool call received from OpenAI.
-        output : str
-            JSON string returned by the executed tool.
-        **metadata
-            Optional metadata to store with the message.
-
-        Returns
-        -------
-        None
-        """
-        tool_call = ResponseToolCall(
-            call_id=content.call_id,
-            name=content.name,
-            arguments=content.arguments,
-            output=output,
-        )
-        function_call, function_call_output = tool_call.to_response_input_item_param()
-        self.messages.append(
-            ResponseMessage(role="tool", content=function_call, metadata=metadata)
-        )
-        self.messages.append(
-            ResponseMessage(
-                role="tool", content=function_call_output, metadata=metadata
-            )
-        )
-
-    def to_openai_payload(
-        self,
-    ) -> List[
-        ResponseInputItemParam
-        | ResponseOutputMessage
-        | ResponseFunctionToolCallParam
-        | FunctionCallOutput
-        | ResponseInputMessageContentListParam
-    ]:
-        """Convert stored messages to the input payload expected by OpenAI.
-
-        Notes
-        -----
-        Assistant messages are model outputs and are not included in the
-        next request's input payload.
-
-        Returns
-        -------
-        list
-            List of message payloads excluding assistant outputs.
-        """
-        return [
-            msg.to_openai_format() for msg in self.messages if msg.role != "assistant"
-        ]