openai-sdk-helpers 0.0.8__py3-none-any.whl → 0.1.0__py3-none-any.whl

openai_sdk_helpers/structure/responses.py

@@ -1,8 +1,12 @@
-"""OpenAI response and tool helpers for structured outputs."""
+"""OpenAI response and tool helpers for structured outputs.
 
-from __future__ import annotations
+This module provides helper functions for creating OpenAI API response formats
+and tool definitions from BaseStructure classes. These helpers simplify the
+process of configuring structured outputs for both Assistant and chat
+completion APIs.
+"""
 
-from typing import Type
+from __future__ import annotations
 
 from openai.types.responses.response_format_text_json_schema_config_param import (
     ResponseFormatTextJSONSchemaConfigParam,
@@ -14,10 +18,13 @@ from ..utils import log
 
 
 def assistant_tool_definition(
-    structure: Type[BaseStructure], name: str, description: str
+    structure: type[BaseStructure], name: str, description: str
 ) -> dict:
     """Build a function tool definition for OpenAI Assistants.
 
+    Creates a tool definition compatible with the Assistant API that uses
+    the structure's schema as function parameters.
+
     Parameters
     ----------
     structure : type[BaseStructure]
@@ -30,7 +37,16 @@ def assistant_tool_definition(
     Returns
     -------
     dict
-        Assistant tool definition payload.
+        Assistant tool definition payload in OpenAI format.
+
+    Examples
+    --------
+    >>> from openai_sdk_helpers.structure import BaseStructure
+    >>> tool = assistant_tool_definition(
+    ...     BaseStructure,
+    ...     "process_data",
+    ...     "Process input data"
+    ... )
     """
     log(f"{structure.__name__}::assistant_tool_definition")
     return {
@@ -43,9 +59,12 @@ def assistant_tool_definition(
     }
 
 
-def assistant_format(structure: Type[BaseStructure]) -> dict:
+def assistant_format(structure: type[BaseStructure]) -> dict:
     """Build a response format definition for OpenAI Assistants.
 
+    Creates a response format specification that instructs the Assistant API
+    to return structured output matching the provided schema.
+
     Parameters
     ----------
     structure : type[BaseStructure]
@@ -54,7 +73,11 @@ def assistant_format(structure: Type[BaseStructure]) -> dict:
     Returns
     -------
     dict
-        Assistant response format definition.
+        Assistant response format definition in OpenAI format.
+
+    Examples
+    --------
+    >>> format_def = assistant_format(BaseStructure)
     """
     log(f"{structure.__name__}::assistant_format")
     return {
@@ -67,12 +90,15 @@ def assistant_format(structure: Type[BaseStructure]) -> dict:
 
 
 def response_tool_definition(
-    structure: Type[BaseStructure],
+    structure: type[BaseStructure],
     tool_name: str,
     tool_description: str,
 ) -> dict:
     """Build a tool definition for OpenAI chat completions.
 
+    Creates a function tool definition compatible with the chat completions
+    API, using the structure's schema as parameters.
+
     Parameters
     ----------
     structure : type[BaseStructure]
@@ -85,7 +111,15 @@ def response_tool_definition(
     Returns
     -------
     dict
-        Tool definition payload for chat completions.
+        Tool definition payload for chat completions API.
+
+    Examples
+    --------
+    >>> tool = response_tool_definition(
+    ...     BaseStructure,
+    ...     "analyze",
+    ...     "Analyze data"
+    ... )
     """
     log(f"{structure.__name__}::response_tool_definition")
     return {
@@ -98,9 +132,12 @@ def response_tool_definition(
     }
 
 
-def response_format(structure: Type[BaseStructure]) -> ResponseTextConfigParam:
+def response_format(structure: type[BaseStructure]) -> ResponseTextConfigParam:
     """Build a response format for OpenAI chat completions.
 
+    Creates a response format specification that instructs the chat
+    completions API to return structured output matching the schema.
+
     Parameters
     ----------
     structure : type[BaseStructure]
@@ -109,7 +146,11 @@ def response_format(structure: Type[BaseStructure]) -> ResponseTextConfigParam:
     Returns
     -------
     ResponseTextConfigParam
-        Response format definition.
+        Response format definition for chat completions API.
+
+    Examples
+    --------
+    >>> format_spec = response_format(BaseStructure)
     """
     log(f"{structure.__name__}::response_format")
     response_format_text_JSONSchema_config_param = (

openai_sdk_helpers/structure/summary.py

@@ -1,8 +1,10 @@
-"""Shared structured output models for summaries."""
+"""Structured output models for summaries.
 
-from __future__ import annotations
+This module defines Pydantic models for representing summarization results,
+including topic-level summaries with citations and consolidated text summaries.
+"""
 
-from typing import List
+from __future__ import annotations
 
 from .base import BaseStructure, spec_field
 
@@ -10,10 +12,30 @@ from .base import BaseStructure, spec_field
 class SummaryTopic(BaseStructure):
     """Capture a topic-level summary with supporting citations.
 
+    Represents a single topic or micro-trend identified in source excerpts,
+    along with a summary and supporting citations.
+
+    Attributes
+    ----------
+    topic : str
+        Topic or micro-trend identified in the provided excerpts.
+    summary : str
+        Concise explanation of what the excerpts convey about the topic.
+    citations : list[str]
+        Indices or short quotes that justify the topic summary.
+
     Methods
     -------
     print()
         Return a formatted string representation of the stored fields.
+
+    Examples
+    --------
+    >>> topic = SummaryTopic(
+    ...     topic="AI Trends",
+    ...     summary="Growing adoption of AI",
+    ...     citations=["Source 1", "Source 2"]
+    ... )
     """
 
     topic: str = spec_field(
@@ -26,7 +48,7 @@ class SummaryTopic(BaseStructure):
         default=...,
         description="Concise explanation of what the excerpts convey about the topic.",
     )
-    citations: List[str] = spec_field(
+    citations: list[str] = spec_field(
         "citations",
         default_factory=list,
         description="Indices or short quotes that justify the topic summary.",
@@ -34,12 +56,23 @@ class SummaryTopic(BaseStructure):
 
 
 class SummaryStructure(BaseStructure):
-    """Defines the consolidated summary returned by the summarizer agent.
+    """Consolidated summary returned by the summarizer agent.
+
+    Represents a synthesized summary text derived from multiple source excerpts.
+
+    Attributes
+    ----------
+    text : str
+        Combined summary synthesized from the supplied excerpts.
 
     Methods
     -------
     print()
         Return a formatted string representation of the stored fields.
+
+    Examples
+    --------
+    >>> summary = SummaryStructure(text="This is a summary")
     """
 
     text: str = spec_field(
@@ -50,15 +83,30 @@ class SummaryStructure(BaseStructure):
 
 
 class ExtendedSummaryStructure(SummaryStructure):
-    """Extend ``SummaryStructure`` with optional topic breakdown metadata.
+    """Extended summary with optional topic breakdown metadata.
+
+    Extends SummaryStructure to include topic-level summaries with citations,
+    providing more granular insight into the summarization.
+
+    Attributes
+    ----------
+    metadata : list[SummaryTopic]
+        Optional topic-level summaries with supporting citations.
 
     Methods
     -------
     print()
         Return a formatted string representation of the stored fields.
+
+    Examples
+    --------
+    >>> extended = ExtendedSummaryStructure(
+    ...     text="Overall summary",
+    ...     metadata=[SummaryTopic(topic="T1", summary="S1", citations=[])]
+    ... )
     """
 
-    metadata: List[SummaryTopic] = spec_field(
+    metadata: list[SummaryTopic] = spec_field(
         "metadata",
         default_factory=list,
         description="Optional topic-level summaries with supporting citations.",

openai_sdk_helpers/structure/validation.py

@@ -1,8 +1,10 @@
-"""Structures describing guardrail validation results."""
+"""Structures describing guardrail validation results.
 
-from __future__ import annotations
+This module defines Pydantic models for representing the results of guardrail
+validation checks on user inputs and agent outputs.
+"""
 
-from typing import List, Optional
+from __future__ import annotations
 
 from .base import BaseStructure, spec_field
 
@@ -10,10 +12,36 @@ from .base import BaseStructure, spec_field
 class ValidationResultStructure(BaseStructure):
     """Capture guardrail validation findings for user and agent messages.
 
+    Represents the results of safety and policy validation checks performed
+    on both user inputs and agent outputs, including detected violations
+    and recommended remediation actions.
+
+    Attributes
+    ----------
+    input_safe : bool
+        Whether the user-provided input is allowed within the guardrails.
+    output_safe : bool
+        Whether the agent output adheres to the safety guardrails.
+    violations : list[str]
+        Detected policy or safety issues that require mitigation.
+    recommended_actions : list[str]
+        Steps to remediate or respond to any detected violations.
+    sanitized_output : str or None
+        Optional redacted or rewritten text that fits the guardrails.
+
     Methods
     -------
     print()
         Return a formatted string representation of the stored fields.
+
+    Examples
+    --------
+    >>> result = ValidationResultStructure(
+    ...     input_safe=True,
+    ...     output_safe=True,
+    ...     violations=[],
+    ...     recommended_actions=[]
+    ... )
     """
 
     input_safe: bool = spec_field(
@@ -26,19 +54,19 @@ class ValidationResultStructure(BaseStructure):
         allow_null=False,
         description="Whether the agent output adheres to the safety guardrails.",
     )
-    violations: List[str] = spec_field(
+    violations: list[str] = spec_field(
         "violations",
         allow_null=False,
         default_factory=list,
         description="Detected policy or safety issues that require mitigation.",
     )
-    recommended_actions: List[str] = spec_field(
+    recommended_actions: list[str] = spec_field(
         "recommended_actions",
         allow_null=False,
         default_factory=list,
         description="Steps to remediate or respond to any detected violations.",
     )
-    sanitized_output: Optional[str] = spec_field(
+    sanitized_output: str | None = spec_field(
         "sanitized_output",
         description="Optional redacted or rewritten text that fits the guardrails.",
     )

openai_sdk_helpers/structure/vector_search.py

@@ -1,47 +1,108 @@
-"""Shared structured output models for vector search."""
+"""Structured output models for vector search workflows.
 
-from __future__ import annotations
+This module defines Pydantic models for representing vector search plans,
+results, and reports. These structures support multi-query vector search
+workflows with error tracking and result aggregation.
+"""
 
-from typing import List
+from __future__ import annotations
 
 from .base import BaseStructure, spec_field
 
 
 class VectorSearchItemStructure(BaseStructure):
-    """A single vector search to perform."""
+    """A single vector search to perform.
+
+    Represents one vector search query with rationale for its inclusion
+    in a multi-query search plan.
+
+    Attributes
+    ----------
+    reason : str
+        Explanation for why this search is needed.
+    query : str
+        Vector search query text.
+
+    Examples
+    --------
+    >>> item = VectorSearchItemStructure(
+    ...     reason="Find related documents",
+    ...     query="machine learning trends"
+    ... )
+    """
 
     reason: str = spec_field("reason")
     query: str = spec_field("query")
 
 
 class VectorSearchPlanStructure(BaseStructure):
-    """Collection of vector searches required to satisfy the query."""
+    """Collection of vector searches required to satisfy the query.
 
-    searches: List[VectorSearchItemStructure] = spec_field("searches")
+    Represents a plan containing multiple vector searches that together
+    provide comprehensive coverage for answering a user query.
+
+    Attributes
+    ----------
+    searches : list[VectorSearchItemStructure]
+        List of vector search queries to execute.
+
+    Examples
+    --------
+    >>> plan = VectorSearchPlanStructure(
+    ...     searches=[VectorSearchItemStructure(reason="R", query="Q")]
+    ... )
+    """
+
+    searches: list[VectorSearchItemStructure] = spec_field("searches")
 
 
 class VectorSearchItemResultStructure(BaseStructure):
-    """Result of a single vector search."""
+    """Result of a single vector search.
 
-    texts: List[str] = spec_field("texts")
+    Contains the text results retrieved from executing one vector search query.
+
+    Attributes
+    ----------
+    texts : list[str]
+        Retrieved text passages from the vector search.
+
+    Examples
+    --------
+    >>> result = VectorSearchItemResultStructure(texts=["Result 1", "Result 2"])
+    """
+
+    texts: list[str] = spec_field("texts")
 
 
 class VectorSearchItemResultsStructure(BaseStructure):
-    """Collection of search results returned from multiple queries.
+    """Collection of search results from multiple queries.
 
-    Failed searches are recorded in ``errors`` to allow callers to inspect
-    partial outcomes without losing visibility into issues.
+    Aggregates results from multiple vector searches while tracking any
+    errors encountered. Failed searches are recorded in the errors list
+    to allow inspection of partial outcomes.
+
+    Attributes
+    ----------
+    item_results : list[VectorSearchItemResultStructure]
+        List of successful search results.
+    errors : list[str]
+        List of error messages from failed searches.
 
     Methods
     -------
     append(item)
         Add a search result to the collection.
+
+    Examples
+    --------
+    >>> results = VectorSearchItemResultsStructure()
+    >>> results.append(VectorSearchItemResultStructure(texts=["Text"]))
     """
 
-    item_results: List[VectorSearchItemResultStructure] = spec_field(
+    item_results: list[VectorSearchItemResultStructure] = spec_field(
         "item_results", default_factory=list
     )
-    errors: List[str] = spec_field("errors", default_factory=list)
+    errors: list[str] = spec_field("errors", default_factory=list)
 
     def append(self, item: VectorSearchItemResultStructure) -> None:
         """Add a search result to the collection.
@@ -59,16 +120,69 @@ class VectorSearchItemResultsStructure(BaseStructure):
 
 
 class VectorSearchReportStructure(BaseStructure):
-    """Structured output from the vector search writer agent."""
+    """Structured output from the vector search writer agent.
+
+    Contains the final synthesized report from vector search results,
+    including summary, markdown report, follow-up questions, and sources.
+
+    Attributes
+    ----------
+    short_summary : str
+        Brief summary of the search findings.
+    markdown_report : str
+        Full markdown-formatted report.
+    follow_up_questions : list[str]
+        Suggested questions for further exploration.
+    sources : list[str]
+        Source references used in the report.
+
+    Examples
+    --------
+    >>> report = VectorSearchReportStructure(
+    ...     short_summary="Summary",
+    ...     markdown_report="# Report",
+    ...     follow_up_questions=["Q1?"],
+    ...     sources=["Source 1"]
+    ... )
+    """
 
     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")
+    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."""
+    """Complete output of a vector search workflow.
+
+    Represents the full lifecycle of a vector search operation, from the
+    original query through plan generation, execution, and final report.
+
+    Attributes
+    ----------
+    query : str
+        Original user query.
+    plan : VectorSearchPlanStructure
+        Generated search plan.
+    results : VectorSearchItemResultsStructure
+        Aggregated search results.
+    report : VectorSearchReportStructure
+        Final synthesized report.
+
+    Examples
+    --------
+    >>> workflow = VectorSearchStructure(
+    ...     query="Test query",
+    ...     plan=VectorSearchPlanStructure(searches=[]),
+    ...     results=VectorSearchItemResultsStructure(),
+    ...     report=VectorSearchReportStructure(
+    ...         short_summary="S",
+    ...         markdown_report="R",
+    ...         follow_up_questions=[],
+    ...         sources=[]
+    ...     )
+    ... )
+    """
 
     query: str = spec_field("query")
     plan: VectorSearchPlanStructure = spec_field("plan")
@@ -79,8 +193,8 @@ class VectorSearchStructure(BaseStructure):
 __all__ = [
     "VectorSearchReportStructure",
     "VectorSearchItemStructure",
+    "VectorSearchPlanStructure",
     "VectorSearchItemResultStructure",
     "VectorSearchItemResultsStructure",
-    "VectorSearchPlanStructure",
     "VectorSearchStructure",
 ]