openai-sdk-helpers 0.0.5__py3-none-any.whl → 0.0.6__py3-none-any.whl

openai_sdk_helpers/response/messages.py

@@ -0,0 +1,211 @@
+"""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"
+        ]

openai_sdk_helpers/response/runner.py

@@ -0,0 +1,104 @@
+"""Convenience runners for response workflows."""
+
+from __future__ import annotations
+
+import asyncio
+
+from typing import Any, Optional, Type, TypeVar
+
+from .base import ResponseBase
+
+
+R = TypeVar("R", bound=ResponseBase[Any])
+
+
+def run_sync(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow synchronously and close resources.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response from :meth:`ResponseBase.run_response`.
+    """
+    response = response_cls(**(response_kwargs or {}))
+    try:
+        return response.run_sync(content=content)
+    finally:
+        response.close()
+
+
+async def run_async(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow asynchronously and close resources.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response from :meth:`ResponseBase.run_response_async`.
+    """
+    response = response_cls(**(response_kwargs or {}))
+    try:
+        return await response.run_async(content=content)
+    finally:
+        response.close()
+
+
+def run_streamed(
+    response_cls: Type[R],
+    *,
+    content: str,
+    response_kwargs: Optional[dict[str, Any]] = None,
+) -> Any:
+    """Run a response workflow and return the asynchronous result.
+
+    This mirrors the agent API for discoverability. Streaming responses are not
+    currently supported by :class:`ResponseBase`, so this returns the same value
+    as :func:`run_async`.
+
+    Parameters
+    ----------
+    response_cls
+        Response class to instantiate.
+    content
+        Prompt text to send to the OpenAI API.
+    response_kwargs
+        Keyword arguments forwarded to ``response_cls``. Default ``None``.
+
+    Returns
+    -------
+    Any
+        Parsed response returned from :func:`run_async`.
+    """
+    return asyncio.run(
+        run_async(response_cls, content=content, response_kwargs=response_kwargs)
+    )
+
+
+__all__ = ["run_sync", "run_async", "run_streamed"]

openai_sdk_helpers/response/tool_call.py

@@ -0,0 +1,70 @@
+"""Tool call representation for shared responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Tuple
+
+from openai.types.responses.response_function_tool_call_param import (
+    ResponseFunctionToolCallParam,
+)
+from openai.types.responses.response_input_param import FunctionCallOutput
+
+
+@dataclass
+class ResponseToolCall:
+    """Container for tool call data used in a conversation.
+
+    Attributes
+    ----------
+    call_id : str
+        Identifier of the tool call.
+    name : str
+        Name of the tool invoked.
+    arguments : str
+        JSON string with the arguments passed to the tool.
+    output : str
+        JSON string representing the result produced by the tool.
+
+    Methods
+    -------
+    to_response_input_item_param()
+        Convert stored data into OpenAI tool call objects.
+    """
+
+    call_id: str
+    name: str
+    arguments: str
+    output: str
+
+    def to_response_input_item_param(
+        self,
+    ) -> Tuple[ResponseFunctionToolCallParam, FunctionCallOutput]:
+        """Convert stored data into OpenAI tool call objects.
+
+        Returns
+        -------
+        tuple[ResponseFunctionToolCallParam, FunctionCallOutput]
+            The function call object and the corresponding output object
+            suitable for inclusion in an OpenAI request.
+        """
+        from typing import cast
+
+        function_call = cast(
+            ResponseFunctionToolCallParam,
+            {
+                "arguments": self.arguments,
+                "call_id": self.call_id,
+                "name": self.name,
+                "type": "function_call",
+            },
+        )
+        function_call_output = cast(
+            FunctionCallOutput,
+            {
+                "call_id": self.call_id,
+                "output": self.output,
+                "type": "function_call_output",
+            },
+        )
+        return function_call, function_call_output

openai_sdk_helpers/structure/__init__.py

@@ -0,0 +1,43 @@
+"""Shared structured output models and base helpers."""
+
+from __future__ import annotations
+
+from .agent_blueprint import AgentBlueprint
+from .plan import *
+from .base import *
+from .prompt import PromptStructure
+from .responses import *
+from .summary import *
+from .vector_search import *
+from .validation import ValidationResultStructure
+from .web_search import *
+
+__all__ = [
+    "BaseStructure",
+    "SchemaOptions",
+    "spec_field",
+    "AgentBlueprint",
+    "AgentEnum",
+    "TaskStructure",
+    "PlanStructure",
+    "PromptStructure",
+    "SummaryTopic",
+    "SummaryStructure",
+    "ExtendedSummaryStructure",
+    "WebSearchStructure",
+    "WebSearchPlanStructure",
+    "WebSearchItemStructure",
+    "WebSearchItemResultStructure",
+    "WebSearchReportStructure",
+    "VectorSearchReportStructure",
+    "VectorSearchItemStructure",
+    "VectorSearchItemResultStructure",
+    "VectorSearchItemResultsStructure",
+    "VectorSearchPlanStructure",
+    "VectorSearchStructure",
+    "ValidationResultStructure",
+    "assistant_tool_definition",
+    "assistant_format",
+    "response_tool_definition",
+    "response_format",
+]

openai_sdk_helpers/structure/agent_blueprint.py

@@ -0,0 +1,224 @@
+"""Structures for designing and planning new agents."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from .plan.enum import AgentEnum
+from .base import BaseStructure, spec_field
+from .plan import TaskStructure, PlanStructure
+
+
+class AgentBlueprint(BaseStructure):
+    """Capture the core requirements for creating a new agent.
+
+    Methods
+    -------
+    summary()
+        Return a human-readable overview of the blueprint.
+    build_plan()
+        Convert the blueprint into an ordered ``PlanStructure``.
+    """
+
+    name: str = spec_field(
+        "name",
+        allow_null=False,
+        description="Name of the agent to build.",
+        examples=["ResearchCoordinator", "EvaluationRouter"],
+    )
+    mission: str = spec_field(
+        "mission",
+        allow_null=False,
+        description="Primary goal or charter for the agent.",
+        examples=["Coordinate a research sprint", "Score model outputs"],
+    )
+    capabilities: List[str] = spec_field(
+        "capabilities",
+        default_factory=list,
+        description="Core skills the agent must perform.",
+    )
+    constraints: List[str] = spec_field(
+        "constraints",
+        default_factory=list,
+        description="Boundaries, policies, or limits the agent must honor.",
+    )
+    required_tools: List[str] = spec_field(
+        "required_tools",
+        default_factory=list,
+        description="External tools the agent must integrate.",
+    )
+    data_sources: List[str] = spec_field(
+        "data_sources",
+        default_factory=list,
+        description="Data inputs that inform the agent's work.",
+    )
+    evaluation_plan: List[str] = spec_field(
+        "evaluation_plan",
+        default_factory=list,
+        description="Checks, tests, or metrics that validate the agent.",
+    )
+    rollout_plan: List[str] = spec_field(
+        "rollout_plan",
+        default_factory=list,
+        description="Deployment or launch steps for the agent.",
+    )
+    guardrails: List[str] = spec_field(
+        "guardrails",
+        default_factory=list,
+        description="Safety rules and governance requirements.",
+    )
+    notes: Optional[str] = spec_field(
+        "notes",
+        description="Additional context that informs the build.",
+    )
+
+    def summary(self) -> str:
+        """Return a multi-line summary highlighting key requirements.
+
+        Returns
+        -------
+        str
+            Human-readable description of the blueprint fields.
+        """
+
+        def _format(label: str, values: list[str]) -> str:
+            return f"{label}: " + (", ".join(values) if values else "None")
+
+        lines = [
+            f"Agent name: {self.name}",
+            f"Mission: {self.mission}",
+            _format("Capabilities", self.capabilities),
+            _format("Constraints", self.constraints),
+            _format("Required tools", self.required_tools),
+            _format("Data sources", self.data_sources),
+            _format("Guardrails", self.guardrails),
+            _format("Evaluation", self.evaluation_plan),
+            _format("Rollout", self.rollout_plan),
+        ]
+
+        if self.notes:
+            lines.append(f"Notes: {self.notes}")
+        return "\n".join(lines)
+
+    def build_plan(self) -> PlanStructure:
+        """Translate the blueprint into a structured plan of execution steps.
+
+        Returns
+        -------
+        PlanStructure
+            Ordered list of tasks representing the build lifecycle.
+        """
+        tasks = [
+            TaskStructure(
+                task_type=AgentEnum.PLANNER,
+                prompt=self._scope_prompt(),
+                context=self.constraints,
+            ),
+            TaskStructure(
+                task_type=AgentEnum.DESIGNER,
+                prompt=self._design_prompt(),
+                context=self.required_tools + self.data_sources,
+            ),
+            TaskStructure(
+                task_type=AgentEnum.BUILDER,
+                prompt=self._synthesis_prompt(),
+                context=self.capabilities,
+            ),
+            TaskStructure(
+                task_type=AgentEnum.VALIDATOR,
+                prompt=self._validation_prompt(),
+                context=self.guardrails,
+            ),
+            TaskStructure(
+                task_type=AgentEnum.EVALUATOR,
+                prompt=self._evaluation_prompt(),
+                context=self.evaluation_plan,
+            ),
+            TaskStructure(
+                task_type=AgentEnum.RELEASE_MANAGER,
+                prompt=self._deployment_prompt(),
+                context=self.rollout_plan,
+            ),
+        ]
+        plan = PlanStructure(tasks=tasks)
+        return plan
+
+    def _scope_prompt(self) -> str:
+        """Return a scoping prompt based on mission, constraints, and guardrails."""
+        return "\n".join(
+            [
+                f"Mission: {self.mission}",
+                self._bullet_block("Guardrails", self.guardrails),
+                self._bullet_block("Constraints", self.constraints),
+            ]
+        )
+
+    def _design_prompt(self) -> str:
+        """Return a design prompt covering tools, data, and capabilities."""
+        return "\n".join(
+            [
+                self._bullet_block("Capabilities", self.capabilities),
+                self._bullet_block("Required tools", self.required_tools),
+                self._bullet_block("Data sources", self.data_sources),
+            ]
+        )
+
+    def _synthesis_prompt(self) -> str:
+        """Return a build prompt focused on interfaces and prompts."""
+        return "\n".join(
+            [
+                "Design system and developer prompts that cover:",
+                self._bullet_block("Mission", [self.mission]),
+                self._bullet_block(
+                    "Capabilities to implement",
+                    self.capabilities or ["Draft standard handlers"],
+                ),
+            ]
+        )
+
+    def _validation_prompt(self) -> str:
+        """Return a prompt instructing validation of guardrails and behaviors."""
+        return "\n".join(
+            [
+                "Create automated validation for:",
+                self._bullet_block("Guardrails", self.guardrails),
+                self._bullet_block("Constraints", self.constraints),
+            ]
+        )
+
+    def _evaluation_prompt(self) -> str:
+        """Return an evaluation prompt emphasizing tests and metrics."""
+        return "\n".join(
+            [
+                "Run evaluation and red-team scenarios using:",
+                self._bullet_block("Evaluation plan", self.evaluation_plan),
+                self._bullet_block("Capabilities", self.capabilities),
+            ]
+        )
+
+    def _deployment_prompt(self) -> str:
+        """Return a deployment prompt capturing rollout and monitoring."""
+        return "\n".join(
+            [
+                self._bullet_block("Rollout steps", self.rollout_plan),
+                self._bullet_block(
+                    "Launch checklist",
+                    [
+                        "Observability hooks enabled",
+                        "Runbook prepared",
+                        "Rollback and kill switches validated",
+                    ],
+                ),
+            ]
+        )
+
+    @staticmethod
+    def _bullet_block(label: str, items: list[str]) -> str:
+        """Return a labeled bullet block for use in prompts."""
+        if not items:
+            return f"{label}: None"
+        bullets = "\n".join(f"- {item}" for item in items)
+        return f"{label}:\n{bullets}"
+
+
+__all__ = ["AgentBlueprint"]