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

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",
 ]

openai_sdk_helpers/structure/web_search.py

@@ -1,50 +1,162 @@
-"""Shared structured output model for web search results."""
+"""Structured output models for web search workflows.
 
-from __future__ import annotations
+This module defines Pydantic models for representing web search plans,
+results, and reports. These structures support multi-query web search
+workflows with comprehensive reporting.
+"""
 
-from typing import List
+from __future__ import annotations
 
 from .base import BaseStructure, spec_field
 
 
 class WebSearchReportStructure(BaseStructure):
-    """Structured output from the writer agent."""
+    """Structured output from the web search writer agent.
+
+    Contains the final synthesized report from web 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 URLs and references used in the report.
+
+    Examples
+    --------
+    >>> report = WebSearchReportStructure(
+    ...     short_summary="Summary",
+    ...     markdown_report="# Report",
+    ...     follow_up_questions=["Q1?"],
+    ...     sources=["https://example.com"]
+    ... )
+    """
 
     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 WebSearchItemStructure(BaseStructure):
-    """A single web search to perform."""
+    """A single web search to perform.
+
+    Represents one web 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
+        Web search query text.
+
+    Examples
+    --------
+    >>> item = WebSearchItemStructure(
+    ...     reason="Find latest news",
+    ...     query="AI developments 2024"
+    ... )
+    """
 
     reason: str = spec_field("reason")
     query: str = spec_field("query")
 
 
 class WebSearchItemResultStructure(BaseStructure):
-    """Result of a single web search."""
+    """Result of a single web search.
+
+    Contains the text content retrieved from executing one web search query.
+
+    Attributes
+    ----------
+    text : str
+        Retrieved text content from the web search.
+
+    Examples
+    --------
+    >>> result = WebSearchItemResultStructure(text="Search result content")
+    """
 
     text: str = spec_field("text")
 
 
 class WebSearchPlanStructure(BaseStructure):
-    """Collection of searches required to satisfy the query."""
+    """Collection of web searches required to satisfy the query.
 
-    searches: List[WebSearchItemStructure] = spec_field("searches")
+    Represents a plan containing multiple web searches that together
+    provide comprehensive coverage for answering a user query.
+
+    Attributes
+    ----------
+    searches : list[WebSearchItemStructure]
+        List of web search queries to execute.
+
+    Examples
+    --------
+    >>> plan = WebSearchPlanStructure(
+    ...     searches=[WebSearchItemStructure(reason="R", query="Q")]
+    ... )
+    """
+
+    searches: list[WebSearchItemStructure] = spec_field("searches")
 
 
 class WebSearchStructure(BaseStructure):
-    """Complete output of a web search workflow."""
+    """Complete output of a web search workflow.
+
+    Represents the full lifecycle of a web search operation, from the
+    original query through plan generation, execution, and final report.
+
+    Attributes
+    ----------
+    query : str
+        Original user query.
+    web_search_plan : WebSearchPlanStructure
+        Generated search plan.
+    web_search_results : list[WebSearchItemResultStructure]
+        List of search results.
+    web_search_report : WebSearchReportStructure
+        Final synthesized report.
+
+    Methods
+    -------
+    print()
+        Return the markdown report.
+
+    Examples
+    --------
+    >>> workflow = WebSearchStructure(
+    ...     query="Test query",
+    ...     web_search_plan=WebSearchPlanStructure(searches=[]),
+    ...     web_search_results=[],
+    ...     web_search_report=WebSearchReportStructure(
+    ...         short_summary="S",
+    ...         markdown_report="R",
+    ...         follow_up_questions=[],
+    ...         sources=[]
+    ...     )
+    ... )
+    """
 
     query: str = spec_field("query")
     web_search_plan: WebSearchPlanStructure = spec_field("web_search_plan")
-    web_search_results: List[WebSearchItemResultStructure] = spec_field(
+    web_search_results: list[WebSearchItemResultStructure] = spec_field(
         "web_search_results"
     )
     web_search_report: WebSearchReportStructure = spec_field("web_search_report")
 
     def print(self) -> str:
-        """Return the markdown report."""
+        """Return the markdown report.
+
+        Returns
+        -------
+        str
+            Markdown-formatted report from web search results.
+        """
         return self.web_search_report.markdown_report

openai_sdk_helpers/types.py

@@ -0,0 +1,57 @@
+"""Common type definitions shared across the SDK.
+
+This module defines protocol types and type aliases for OpenAI client
+compatibility, enabling flexible client usage throughout the package.
+
+Classes
+-------
+SupportsOpenAIClient
+    Protocol describing the subset of OpenAI client interface used by the SDK.
+
+Type Aliases
+------------
+OpenAIClient
+    Union type accepting OpenAI client or compatible protocol implementations.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from openai import OpenAI
+
+
+class SupportsOpenAIClient(Protocol):
+    """Protocol describing the subset of the OpenAI client the SDK relies on.
+
+    Defines the minimum interface required for OpenAI client compatibility.
+    Custom implementations can satisfy this protocol for testing or
+    alternative backends.
+
+    Attributes
+    ----------
+    api_key : str or None
+        API key for authentication.
+    vector_stores : Any
+        Vector stores management interface.
+    responses : Any
+        Responses API interface.
+    files : Any
+        Files management interface.
+    """
+
+    api_key: str | None
+    vector_stores: Any
+    responses: Any
+    files: Any
+
+
+OpenAIClient = OpenAI | SupportsOpenAIClient
+"""Type alias for OpenAI client or compatible protocol implementation.
+
+Accepts either the official OpenAI client or any object satisfying the
+SupportsOpenAIClient protocol.
+"""
+
+
+__all__ = ["SupportsOpenAIClient", "OpenAIClient"]

openai_sdk_helpers/utils/__init__.py

@@ -1,4 +1,33 @@
-"""Shared utility helpers for openai-sdk-helpers."""
+"""Utility helpers for openai-sdk-helpers.
+
+This package provides common utility functions for type coercion, file
+handling, JSON serialization, and logging. These utilities are used
+throughout the openai_sdk_helpers package.
+
+Functions
+---------
+ensure_list(value)
+    Normalize a single item or iterable into a list.
+check_filepath(filepath, fullfilepath)
+    Ensure the parent directory for a file path exists.
+coerce_optional_float(value)
+    Convert a value to float or None.
+coerce_optional_int(value)
+    Convert a value to int or None.
+coerce_dict(value)
+    Convert a value to a string-keyed dictionary.
+coerce_jsonable(value)
+    Convert a value into a JSON-serializable representation.
+log(message, level)
+    Log a message with basic configuration.
+
+Classes
+-------
+JSONSerializable
+    Mixin for classes that can be serialized to JSON.
+customJSONEncoder
+    JSON encoder for common helper types like enums and paths.
+"""
 
 from __future__ import annotations