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

openai_sdk_helpers/structure/plan/plan.py

@@ -0,0 +1,104 @@
+"""Structured output model for agent plans."""
+
+from __future__ import annotations
+
+from typing import List
+
+from ..base import BaseStructure, spec_field
+from .task import AgentTaskStructure
+
+
+class PlanStructure(BaseStructure):
+    """Structured representation of an ordered list of agent tasks.
+
+    Methods
+    -------
+    print()
+        Return a formatted description of every task in order.
+    __len__()
+        Return the count of tasks in the plan.
+    append(task)
+        Append an ``AgentTaskStructure`` to the plan.
+    """
+
+    tasks: List[AgentTaskStructure] = spec_field(
+        "tasks",
+        default_factory=list,
+        description="Ordered list of agent tasks to execute.",
+    )
+
+    def print(self) -> str:
+        """Return a human-readable representation of the plan.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            Concatenated description of each plan step.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> PlanStructure().print()
+        'No tasks defined.'
+        """
+        if not self.tasks:
+            return "No tasks defined."
+        return "\n\n".join(
+            [f"Task {idx + 1}:\n{task.print()}" for idx, task in enumerate(self.tasks)]
+        )
+
+    def __len__(self) -> int:
+        """Return the number of tasks contained in the plan.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        int
+            Count of stored agent tasks.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> len(PlanStructure())
+        0
+        """
+        return len(self.tasks)
+
+    def append(self, task: AgentTaskStructure) -> None:
+        """Add a task to the plan in execution order.
+
+        Parameters
+        ----------
+        task : AgentTaskStructure
+            Task to append to the plan.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> plan = PlanStructure()
+        >>> plan.append(AgentTaskStructure(prompt="Test"))  # doctest: +SKIP
+        """
+        self.tasks.append(task)
+
+
+__all__ = ["PlanStructure"]

openai_sdk_helpers/structure/plan/task.py

@@ -0,0 +1,122 @@
+"""Structured output model for agent tasks."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Literal, Optional
+
+from pydantic import field_validator
+
+from ..base import BaseStructure, spec_field
+from .enum import AgentEnum
+
+
+class AgentTaskStructure(BaseStructure):
+    """Structured representation of a single agent task.
+
+    Methods
+    -------
+    print()
+        Return a formatted multi-line description of the task.
+    """
+
+    task_type: AgentEnum = spec_field(
+        "task_type",
+        default=AgentEnum.WEB_SEARCH,
+        description="Agent type responsible for executing the task.",
+    )
+    prompt: str = spec_field(
+        "prompt",
+        description="Input passed to the agent.",
+        examples=["Research the latest trends in AI-assisted data analysis."],
+    )
+    context: List[str] | None = spec_field(
+        "context",
+        default_factory=list,
+        description="Additional context forwarded to the agent callable.",
+    )
+    start_date: Optional[datetime] = spec_field(
+        "start_date",
+        default=None,
+        description="Timestamp marking when the task started (UTC).",
+    )
+    end_date: Optional[datetime] = spec_field(
+        "end_date",
+        default=None,
+        description="Timestamp marking when the task completed (UTC).",
+    )
+    status: Literal["waiting", "running", "done", "error"] = spec_field(
+        "status",
+        default="waiting",
+        description="Current lifecycle state for the task.",
+    )
+    results: List[str] = spec_field(
+        "results",
+        default_factory=list,
+        description="Normalized string outputs returned by the agent.",
+    )
+
+    @field_validator("task_type", mode="before")
+    @classmethod
+    def _coerce_task_type(cls, value: AgentEnum | str) -> AgentEnum:
+        """Coerce string inputs into ``AgentEnum`` values.
+
+        Parameters
+        ----------
+        value : AgentEnum | str
+            Enum instance or enum value string.
+
+        Returns
+        -------
+        AgentEnum
+            Parsed enum instance.
+
+        Raises
+        ------
+        ValueError
+            If the value cannot be mapped to a valid enum member.
+
+        Examples
+        --------
+        >>> AgentTaskStructure._coerce_task_type("WebAgentSearch")
+        <AgentEnum.WEB_SEARCH: 'WebAgentSearch'>
+        """
+        if isinstance(value, AgentEnum):
+            return value
+        return AgentEnum(value)
+
+    def print(self) -> str:
+        """Return a human-readable representation of the task.
+
+        Parameters
+        ----------
+        None
+
+        Returns
+        -------
+        str
+            Multi-line description of the task metadata.
+
+        Raises
+        ------
+        None
+
+        Examples
+        --------
+        >>> AgentTaskStructure(prompt="Test").print()
+        'Task type: ...'  # doctest: +SKIP
+        """
+        return "\n".join(
+            [
+                BaseStructure.format_output("Task type", self.task_type),
+                BaseStructure.format_output("Prompt", self.prompt),
+                BaseStructure.format_output("Context", self.context),
+                BaseStructure.format_output("Status", self.status),
+                BaseStructure.format_output("Start date", self.start_date),
+                BaseStructure.format_output("End date", self.end_date),
+                BaseStructure.format_output("Results", self.results),
+            ]
+        )
+
+
+__all__ = ["AgentTaskStructure"]

openai_sdk_helpers/structure/prompt.py

@@ -0,0 +1,24 @@
+"""Shared structured output model for prompts."""
+
+from __future__ import annotations
+
+from .base import BaseStructure, spec_field
+
+
+class PromptStructure(BaseStructure):
+    """The prompt text to use for the OpenAI API request.
+
+    Methods
+    -------
+    print()
+        Return the formatted model fields.
+    """
+
+    prompt: str = spec_field(
+        "prompt",
+        description="The prompt text to use for the OpenAI API request.",
+        examples=[
+            "What is the capital of France?",
+            "Generate a summary of the latest news in AI.",
+        ],
+    )

openai_sdk_helpers/structure/responses.py

@@ -0,0 +1,148 @@
+"""OpenAI response and tool helpers for structured outputs."""
+
+from __future__ import annotations
+
+from typing import Type
+
+from openai.types.responses.response_format_text_json_schema_config_param import (
+    ResponseFormatTextJSONSchemaConfigParam,
+)
+from openai.types.responses.response_text_config_param import ResponseTextConfigParam
+
+from .base import BaseStructure
+from ..utils import log
+
+
+def assistant_tool_definition(
+    structure: Type[BaseStructure],
+    name: str,
+    description: str,
+    force_required: bool = False,
+) -> dict:
+    """Build a function tool definition for OpenAI Assistants.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the tool schema.
+    name : str
+        Name of the function tool.
+    description : str
+        Description of what the function tool does.
+    force_required : bool, default=False
+        When ``True``, mark all object properties as required.
+
+    Returns
+    -------
+    dict
+        Assistant tool definition payload.
+    """
+    log(f"{structure.__name__}::assistant_tool_definition")
+    return {
+        "type": "function",
+        "function": {
+            "name": name,
+            "description": description,
+            "parameters": structure.get_schema(force_required=force_required),
+        },
+    }
+
+
+def assistant_format(
+    structure: Type[BaseStructure], force_required: bool = False
+) -> dict:
+    """Build a response format definition for OpenAI Assistants.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the response schema.
+    force_required : bool, default=False
+        When ``True``, mark all object properties as required.
+
+    Returns
+    -------
+    dict
+        Assistant response format definition.
+    """
+    log(f"{structure.__name__}::assistant_format")
+    return {
+        "type": "json_schema",
+        "json_schema": {
+            "name": structure.__name__,
+            "schema": structure.get_schema(force_required=force_required),
+        },
+    }
+
+
+def response_tool_definition(
+    structure: Type[BaseStructure],
+    tool_name: str,
+    tool_description: str,
+    force_required: bool = False,
+) -> dict:
+    """Build a tool definition for OpenAI chat completions.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the tool schema.
+    tool_name : str
+        Name of the function tool.
+    tool_description : str
+        Description of what the function tool does.
+    force_required : bool, default=False
+        When ``True``, mark all object properties as required.
+
+    Returns
+    -------
+    dict
+        Tool definition payload for chat completions.
+    """
+    log(f"{structure.__name__}::response_tool_definition")
+    return {
+        "type": "function",
+        "name": tool_name,
+        "description": tool_description,
+        "parameters": structure.get_schema(force_required=force_required),
+        "strict": True,
+        "additionalProperties": False,
+    }
+
+
+def response_format(
+    structure: Type[BaseStructure], force_required: bool = False
+) -> ResponseTextConfigParam:
+    """Build a response format for OpenAI chat completions.
+
+    Parameters
+    ----------
+    structure : type[BaseStructure]
+        Structure class that defines the response schema.
+    force_required : bool, default=False
+        When ``True``, mark all object properties as required.
+
+    Returns
+    -------
+    ResponseTextConfigParam
+        Response format definition.
+    """
+    log(f"{structure.__name__}::response_format")
+    response_format_text_JSONSchema_config_param = (
+        ResponseFormatTextJSONSchemaConfigParam(
+            name=structure.__name__,
+            schema=structure.get_schema(force_required=force_required),
+            type="json_schema",
+            description="This is a JSON schema format for the output structure.",
+            strict=True,
+        )
+    )
+    return ResponseTextConfigParam(format=response_format_text_JSONSchema_config_param)
+
+
+__all__ = [
+    "assistant_tool_definition",
+    "assistant_format",
+    "response_tool_definition",
+    "response_format",
+]

openai_sdk_helpers/structure/summary.py

@@ -0,0 +1,65 @@
+"""Shared structured output models for summaries."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class SummaryTopic(BaseStructure):
+    """Capture a topic-level summary with supporting citations.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    topic: str = spec_field(
+        "topic",
+        default=...,
+        description="Topic or micro-trend identified in the provided excerpts.",
+    )
+    summary: str = spec_field(
+        "summary",
+        default=...,
+        description="Concise explanation of what the excerpts convey about the topic.",
+    )
+    citations: List[str] = spec_field(
+        "citations",
+        default_factory=list,
+        description="Indices or short quotes that justify the topic summary.",
+    )
+
+
+class SummaryStructure(BaseStructure):
+    """Defines the consolidated summary returned by the summarizer agent.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    text: str = spec_field(
+        "text",
+        default=...,
+        description="Combined summary synthesized from the supplied excerpts.",
+    )
+
+
+class ExtendedSummaryStructure(SummaryStructure):
+    """Extend ``SummaryStructure`` with optional topic breakdown metadata.
+
+    Methods
+    -------
+    print()
+        Return a formatted string representation of the stored fields.
+    """
+
+    metadata: List[SummaryTopic] = spec_field(
+        "metadata",
+        default_factory=list,
+        description="Optional topic-level summaries with supporting citations.",
+    )

openai_sdk_helpers/structure/vector_search.py

@@ -0,0 +1,82 @@
+"""Shared structured output models for vector search."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class VectorSearchItemStructure(BaseStructure):
+    """A single vector search to perform."""
+
+    reason: str = spec_field("reason")
+    query: str = spec_field("query")
+
+
+class VectorSearchPlanStructure(BaseStructure):
+    """Collection of vector searches required to satisfy the query."""
+
+    searches: List[VectorSearchItemStructure] = spec_field("searches")
+
+
+class VectorSearchItemResultStructure(BaseStructure):
+    """Result of a single vector search."""
+
+    texts: List[str] = spec_field("texts")
+
+
+class VectorSearchItemResultsStructure(BaseStructure):
+    """Collection of search results returned from multiple queries.
+
+    Methods
+    -------
+    append(item)
+        Add a search result to the collection.
+    """
+
+    item_results: List[VectorSearchItemResultStructure] = spec_field(
+        "item_results", default_factory=list
+    )
+
+    def append(self, item: VectorSearchItemResultStructure) -> None:
+        """Add a search result to the collection.
+
+        Parameters
+        ----------
+        item : VectorSearchItemResultStructure
+            Result item to append.
+
+        Returns
+        -------
+        None
+        """
+        self.item_results.append(item)
+
+
+class VectorSearchReportStructure(BaseStructure):
+    """Structured output from the vector search writer agent."""
+
+    short_summary: str = spec_field("short_summary")
+    markdown_report: str = spec_field("markdown_report")
+    follow_up_questions: List[str] = spec_field("follow_up_questions")
+    sources: List[str] = spec_field("sources")
+
+
+class VectorSearchStructure(BaseStructure):
+    """Complete output of a vector search workflow."""
+
+    query: str = spec_field("query")
+    plan: VectorSearchPlanStructure = spec_field("plan")
+    results: VectorSearchItemResultsStructure = spec_field("results")
+    report: VectorSearchReportStructure = spec_field("report")
+
+
+__all__ = [
+    "VectorSearchReportStructure",
+    "VectorSearchItemStructure",
+    "VectorSearchItemResultStructure",
+    "VectorSearchItemResultsStructure",
+    "VectorSearchPlanStructure",
+    "VectorSearchStructure",
+]

openai_sdk_helpers/structure/web_search.py

@@ -0,0 +1,46 @@
+"""Shared structured output model for web search results."""
+
+from __future__ import annotations
+
+from typing import List
+
+from .base import BaseStructure, spec_field
+
+
+class WebSearchReportStructure(BaseStructure):
+    """Structured output from the writer agent."""
+
+    short_summary: str = spec_field("short_summary")
+    markdown_report: str = spec_field("markdown_report")
+    follow_up_questions: List[str] = spec_field("follow_up_questions")
+    sources: List[str] = spec_field("sources")
+
+
+class WebSearchItemStructure(BaseStructure):
+    """A single web search to perform."""
+
+    reason: str = spec_field("reason")
+    query: str = spec_field("query")
+
+
+class WebSearchItemResultStructure(BaseStructure):
+    """Result of a single web search."""
+
+    text: str = spec_field("text")
+
+
+class WebSearchPlanStructure(BaseStructure):
+    """Collection of searches required to satisfy the query."""
+
+    searches: List[WebSearchItemStructure] = spec_field("searches")
+
+
+class WebSearchStructure(BaseStructure):
+    """Complete output of a web search workflow."""
+
+    query: str = spec_field("query")
+    web_search_plan: WebSearchPlanStructure = spec_field("web_search_plan")
+    web_search_results: List[WebSearchItemResultStructure] = spec_field(
+        "web_search_results"
+    )
+    web_search_report: WebSearchReportStructure = spec_field("web_search_report")

openai_sdk_helpers/utils/__init__.py

@@ -0,0 +1,13 @@
+"""Shared utility helpers for openai-sdk-helpers."""
+
+from __future__ import annotations
+
+from .core import JSONSerializable, check_filepath, customJSONEncoder, ensure_list, log
+
+__all__ = [
+    "ensure_list",
+    "check_filepath",
+    "JSONSerializable",
+    "customJSONEncoder",
+    "log",
+]