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

openai_sdk_helpers/structure/plan/plan.py

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

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

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

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

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

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

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

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