openai-sdk-helpers 0.1.0__tar.gz → 0.1.2__tar.gz

openai_sdk_helpers-0.1.0/README.md → openai_sdk_helpers-0.1.2/PKG-INFO

@@ -1,3 +1,38 @@
+Metadata-Version: 2.4
+Name: openai-sdk-helpers
+Version: 0.1.2
+Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
+Author: openai-sdk-helpers maintainers
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jinja2
+Requires-Dist: openai-agents<1.0.0,>=0.6.4
+Requires-Dist: openai<3.0.0,>=2.14.0
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: python-dotenv
+Requires-Dist: streamlit
+Requires-Dist: typing-extensions<5,>=4.15.0
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: black[jupyter]; extra == 'dev'
+Requires-Dist: pydocstyle; extra == 'dev'
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 # openai-sdk-helpers
@@ -65,6 +100,26 @@ The `agent` module provides a higher-level abstraction for building agents, whil
 - **Tool execution framework** with custom handlers and structured outputs
 - **Session persistence** for saving and restoring conversation history
 
+#### Infrastructure & Utilities
+- **Centralized logger factory** for consistent application logging
+- **Retry patterns** with exponential backoff and jitter
+- **Output validation** framework with JSON schema, semantic, and length validators
+- **CLI tool** for testing agents, validating templates, and inspecting registries
+- **Deprecation utilities** for managing API changes
+
+#### Shared Components
+- **Typed structures** using Pydantic for prompts, responses, and search workflows 
+  to ensure predictable inputs and outputs
+- **OpenAI configuration management** with environment variable and `.env` file support
+- **Vector storage abstraction** for seamless integration with OpenAI vector stores
+- **Type-safe interfaces** with full type hints and `py.typed` marker for external projects
+  - **ValidatorAgent**: Check inputs and outputs against safety guardrails
+
+#### Response Module (Built on `openai` SDK)
+- **Response handling utilities** for direct API control with fine-grained message management
+- **Tool execution framework** with custom handlers and structured outputs
+- **Session persistence** for saving and restoring conversation history
+
 #### Shared Components
 - **Typed structures** using Pydantic for prompts, responses, and search workflows 
   to ensure predictable inputs and outputs
@@ -251,6 +306,99 @@ response.close()
 
 ## Advanced Usage
 
+### Image and File Analysis
+
+The `response` module automatically detects file types and handles them appropriately:
+
+```python
+from openai_sdk_helpers.response import BaseResponse
+from openai_sdk_helpers import OpenAISettings
+
+settings = OpenAISettings.from_env()
+
+with BaseResponse(
+    name="analyzer",
+    instructions="You are a helpful assistant that can analyze files.",
+    tools=None,
+    output_structure=None,
+    tool_handlers={},
+    openai_settings=settings,
+) as response:
+    # Automatic type detection - single files parameter
+    # Images are sent as base64-encoded images
+    # Documents are sent as base64-encoded file data
+    result = response.run_sync(
+        "Analyze these files",
+        files=["photo.jpg", "document.pdf"]
+    )
+    print(result)
+    
+    # Single file - automatically detected
+    result = response.run_sync(
+        "What's in this image?",
+        files="photo.jpg"  # Automatically detected as image
+    )
+    print(result)
+    
+    # Use vector store for RAG (Retrieval-Augmented Generation)
+    result = response.run_sync(
+        "Search these documents",
+        files=["doc1.pdf", "doc2.pdf"],
+        use_vector_store=True  # Enable RAG with vector stores
+    )
+    print(result)
+```
+
+**How It Works:**
+
+- **Images** (jpg, png, gif, etc.) are automatically sent as base64-encoded images
+- **Documents** (pdf, txt, xlsx, etc.) are sent as base64-encoded file data by default
+- **Vector Stores** can optionally be used for documents when `use_vector_store=True`
+- **Batch Processing** is automatically used for multiple files (>3) for efficient encoding
+
+**Advanced File Processing:**
+
+```python
+from openai_sdk_helpers.response import process_files
+
+# Process files directly with the dedicated module
+vector_files, base64_files, images = process_files(
+    response,
+    files=["photo1.jpg", "photo2.jpg", "doc1.pdf", "doc2.pdf"],
+    use_vector_store=False,
+    batch_size=20,      # Files per batch
+    max_workers=10,     # Concurrent workers
+)
+```
+
+**Base64 Encoding Utilities:**
+
+```python
+from openai_sdk_helpers.utils import (
+    encode_image,
+    encode_file,
+    is_image_file,
+    create_image_data_url,
+    create_file_data_url,
+)
+
+# Check if a file is an image
+is_image_file("photo.jpg")  # True
+is_image_file("document.pdf")  # False
+
+# Encode an image to base64
+base64_image = encode_image("photo.jpg")
+
+# Create a data URL for an image
+image_url, detail = create_image_data_url("photo.jpg", detail="high")
+
+# Encode a file to base64
+base64_file = encode_file("document.pdf")
+
+# Create a data URL for a file
+file_data = create_file_data_url("document.pdf")
+```
+
 ### Custom Prompt Templates
 
 Create custom Jinja2 templates for specialized agent behaviors:
@@ -477,6 +625,31 @@ See `AGENTS.md` for detailed contributing guidelines and conventions.
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 for details.
 
+## CLI Tool
+
+The package includes a command-line tool for development and testing:
+
+```bash
+# List all registered response configurations
+openai-helpers registry list
+
+# Inspect a specific configuration
+openai-helpers registry inspect my_config
+
+# Validate Jinja2 templates
+openai-helpers template validate ./templates
+
+# Test an agent (coming soon)
+openai-helpers agent test MyAgent --input "test input"
+```
+
+### CLI Commands
+
+- **registry list** - Show all registered response configurations
+- **registry inspect** - Display details of a configuration
+- **template validate** - Check template syntax and structure
+- **agent test** - Test agents locally with sample inputs
+
 ## Troubleshooting
 
 ### Common Issues
@@ -498,6 +671,7 @@ OPENAI_API_KEY=your-api-key-here
 Vector search workflows require custom prompt templates. Either:
 1. Create the required `.jinja` files in your `prompt_dir`
 2. Omit the `prompt_dir` parameter to use built-in defaults (for text agents only)
+3. Use the CLI to validate templates: `openai-helpers template validate ./templates`
 
 **Import errors after installation**
 

openai_sdk_helpers-0.1.0/PKG-INFO → openai_sdk_helpers-0.1.2/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: openai-sdk-helpers
-Version: 0.1.0
-Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
-Author: openai-sdk-helpers maintainers
-License: MIT
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: jinja2
-Requires-Dist: openai
-Requires-Dist: openai-agents
-Requires-Dist: pydantic<3,>=2.7
-Requires-Dist: python-dotenv
-Requires-Dist: streamlit
-Requires-Dist: typing-extensions<5,>=4.15.0
-Provides-Extra: dev
-Requires-Dist: black; extra == 'dev'
-Requires-Dist: black[jupyter]; extra == 'dev'
-Requires-Dist: pydocstyle; extra == 'dev'
-Requires-Dist: pyright; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-asyncio; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 # openai-sdk-helpers
@@ -90,6 +65,26 @@ The `agent` module provides a higher-level abstraction for building agents, whil
 - **Tool execution framework** with custom handlers and structured outputs
 - **Session persistence** for saving and restoring conversation history
 
+#### Infrastructure & Utilities
+- **Centralized logger factory** for consistent application logging
+- **Retry patterns** with exponential backoff and jitter
+- **Output validation** framework with JSON schema, semantic, and length validators
+- **CLI tool** for testing agents, validating templates, and inspecting registries
+- **Deprecation utilities** for managing API changes
+
+#### Shared Components
+- **Typed structures** using Pydantic for prompts, responses, and search workflows 
+  to ensure predictable inputs and outputs
+- **OpenAI configuration management** with environment variable and `.env` file support
+- **Vector storage abstraction** for seamless integration with OpenAI vector stores
+- **Type-safe interfaces** with full type hints and `py.typed` marker for external projects
+  - **ValidatorAgent**: Check inputs and outputs against safety guardrails
+
+#### Response Module (Built on `openai` SDK)
+- **Response handling utilities** for direct API control with fine-grained message management
+- **Tool execution framework** with custom handlers and structured outputs
+- **Session persistence** for saving and restoring conversation history
+
 #### Shared Components
 - **Typed structures** using Pydantic for prompts, responses, and search workflows 
   to ensure predictable inputs and outputs
@@ -276,6 +271,99 @@ response.close()
 
 ## Advanced Usage
 
+### Image and File Analysis
+
+The `response` module automatically detects file types and handles them appropriately:
+
+```python
+from openai_sdk_helpers.response import BaseResponse
+from openai_sdk_helpers import OpenAISettings
+
+settings = OpenAISettings.from_env()
+
+with BaseResponse(
+    name="analyzer",
+    instructions="You are a helpful assistant that can analyze files.",
+    tools=None,
+    output_structure=None,
+    tool_handlers={},
+    openai_settings=settings,
+) as response:
+    # Automatic type detection - single files parameter
+    # Images are sent as base64-encoded images
+    # Documents are sent as base64-encoded file data
+    result = response.run_sync(
+        "Analyze these files",
+        files=["photo.jpg", "document.pdf"]
+    )
+    print(result)
+    
+    # Single file - automatically detected
+    result = response.run_sync(
+        "What's in this image?",
+        files="photo.jpg"  # Automatically detected as image
+    )
+    print(result)
+    
+    # Use vector store for RAG (Retrieval-Augmented Generation)
+    result = response.run_sync(
+        "Search these documents",
+        files=["doc1.pdf", "doc2.pdf"],
+        use_vector_store=True  # Enable RAG with vector stores
+    )
+    print(result)
+```
+
+**How It Works:**
+
+- **Images** (jpg, png, gif, etc.) are automatically sent as base64-encoded images
+- **Documents** (pdf, txt, xlsx, etc.) are sent as base64-encoded file data by default
+- **Vector Stores** can optionally be used for documents when `use_vector_store=True`
+- **Batch Processing** is automatically used for multiple files (>3) for efficient encoding
+
+**Advanced File Processing:**
+
+```python
+from openai_sdk_helpers.response import process_files
+
+# Process files directly with the dedicated module
+vector_files, base64_files, images = process_files(
+    response,
+    files=["photo1.jpg", "photo2.jpg", "doc1.pdf", "doc2.pdf"],
+    use_vector_store=False,
+    batch_size=20,      # Files per batch
+    max_workers=10,     # Concurrent workers
+)
+```
+
+**Base64 Encoding Utilities:**
+
+```python
+from openai_sdk_helpers.utils import (
+    encode_image,
+    encode_file,
+    is_image_file,
+    create_image_data_url,
+    create_file_data_url,
+)
+
+# Check if a file is an image
+is_image_file("photo.jpg")  # True
+is_image_file("document.pdf")  # False
+
+# Encode an image to base64
+base64_image = encode_image("photo.jpg")
+
+# Create a data URL for an image
+image_url, detail = create_image_data_url("photo.jpg", detail="high")
+
+# Encode a file to base64
+base64_file = encode_file("document.pdf")
+
+# Create a data URL for a file
+file_data = create_file_data_url("document.pdf")
+```
+
 ### Custom Prompt Templates
 
 Create custom Jinja2 templates for specialized agent behaviors:
@@ -502,6 +590,31 @@ See `AGENTS.md` for detailed contributing guidelines and conventions.
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 for details.
 
+## CLI Tool
+
+The package includes a command-line tool for development and testing:
+
+```bash
+# List all registered response configurations
+openai-helpers registry list
+
+# Inspect a specific configuration
+openai-helpers registry inspect my_config
+
+# Validate Jinja2 templates
+openai-helpers template validate ./templates
+
+# Test an agent (coming soon)
+openai-helpers agent test MyAgent --input "test input"
+```
+
+### CLI Commands
+
+- **registry list** - Show all registered response configurations
+- **registry inspect** - Display details of a configuration
+- **template validate** - Check template syntax and structure
+- **agent test** - Test agents locally with sample inputs
+
 ## Troubleshooting
 
 ### Common Issues
@@ -523,6 +636,7 @@ OPENAI_API_KEY=your-api-key-here
 Vector search workflows require custom prompt templates. Either:
 1. Create the required `.jinja` files in your `prompt_dir`
 2. Omit the `prompt_dir` parameter to use built-in defaults (for text agents only)
+3. Use the CLI to validate templates: `openai-helpers template validate ./templates`
 
 **Import errors after installation**
 

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/pyproject.toml

@@ -1,11 +1,23 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.1.0"
+version = "0.1.2"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"
 license = {text = "MIT"}
 authors = [{name = "openai-sdk-helpers maintainers"}]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
 dependencies = [
 
     # Template rendering
@@ -21,9 +33,9 @@ dependencies = [
     "python-dotenv",
 
 
-    # OpenAI functionality
-    "openai",
-    "openai-agents",
+    # OpenAI functionality (tested with openai==2.14.0, openai-agents==0.6.4)
+    "openai>=2.14.0,<3.0.0",
+    "openai-agents>=0.6.4,<1.0.0",
 
 
     # Web UI
@@ -66,3 +78,9 @@ extraPaths = ["src"]
 
 [tool.pydocstyle]
 convention = "numpy"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[project.scripts]
+openai-helpers = "openai_sdk_helpers.cli:main"

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from .async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
+from .utils.async_utils import run_coroutine_thread_safe, run_coroutine_with_fallback
 from .context_manager import (
     AsyncManagedResource,
     ManagedResource,
@@ -22,9 +22,8 @@ from .errors import (
     AsyncExecutionError,
     ResourceCleanupError,
 )
-from .logging_config import LoggerFactory
 from .retry import with_exponential_backoff
-from .validation import (
+from .utils.validation import (
     validate_choice,
     validate_dict_mapping,
     validate_list_items,
@@ -52,6 +51,7 @@ from .structure import (
 )
 from .prompt import PromptRenderer
 from .config import OpenAISettings
+from .files_api import FilesAPIManager, FilePurpose
 from .vector_storage import VectorStorage, VectorStorageFileInfo, VectorStorageFileStats
 from .agent import (
     AgentBase,
@@ -78,9 +78,28 @@ from .response import (
 from .tools import (
     serialize_tool_result,
     tool_handler_factory,
+    StructureType,
+    ToolSpec,
+    build_tool_definitions,
 )
-from .utils import (
-    build_openai_settings,
+from .config import build_openai_settings
+from .utils.deprecation import (
+    deprecated,
+    warn_deprecated,
+    DeprecationHelper,
+)
+from .utils.output_validation import (
+    ValidationResult,
+    ValidationRule,
+    JSONSchemaValidator,
+    SemanticValidator,
+    LengthValidator,
+    OutputValidator,
+    validate_output,
+)
+from .types import (
+    SupportsOpenAIClient,
+    OpenAIClient,
 )
 
 __all__ = [
@@ -98,8 +117,6 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
-    # Logging
-    "LoggerFactory",
     # Retry utilities
     "with_exponential_backoff",
     # Context managers
@@ -122,6 +139,8 @@ __all__ = [
     "spec_field",
     "PromptRenderer",
     "OpenAISettings",
+    "FilesAPIManager",
+    "FilePurpose",
     "VectorStorage",
     "VectorStorageFileInfo",
     "VectorStorageFileStats",
@@ -154,8 +173,26 @@ __all__ = [
     "attach_vector_store",
     "serialize_tool_result",
     "tool_handler_factory",
+    "StructureType",
+    "ToolSpec",
+    "build_tool_definitions",
     "build_openai_settings",
     "create_plan",
     "execute_task",
     "execute_plan",
+    # Type definitions
+    "SupportsOpenAIClient",
+    "OpenAIClient",
+    # Deprecation utilities
+    "deprecated",
+    "warn_deprecated",
+    "DeprecationHelper",
+    # Output validation
+    "ValidationResult",
+    "ValidationRule",
+    "JSONSchemaValidator",
+    "SemanticValidator",
+    "LengthValidator",
+    "OutputValidator",
+    "validate_output",
 ]

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/agent/base.py

@@ -146,6 +146,7 @@ class AgentBase:
     def from_config(
         cls,
         config: AgentConfigLike,
+        *,
         run_context_wrapper: Optional[RunContextWrapper[Dict[str, Any]]] = None,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
@@ -213,7 +214,7 @@ class AgentBase:
         return self._template.render(context)
 
     def get_prompt(
-        self, run_context_wrapper: RunContextWrapper[Dict[str, Any]], _: Agent
+        self, run_context_wrapper: RunContextWrapper[Dict[str, Any]], *, _: Agent
     ) -> str:
         """Render the agent prompt using the provided run context.
 
@@ -257,6 +258,7 @@ class AgentBase:
     async def run_async(
         self,
         input: str,
+        *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> Any:
@@ -288,6 +290,7 @@ class AgentBase:
     def run_sync(
         self,
         input: str,
+        *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> Any:
@@ -317,6 +320,7 @@ class AgentBase:
     def run_streamed(
         self,
         input: str,
+        *,
         context: Optional[Dict[str, Any]] = None,
         output_type: Optional[Any] = None,
     ) -> RunResultStreaming:

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/agent/coordination.py

@@ -12,8 +12,7 @@ from typing import Any, Callable, Dict, List, Optional
 
 
 from ..structure import TaskStructure, PlanStructure, PromptStructure
-from ..environment import DATETIME_FMT
-from ..utils import JSONSerializable, log
+from ..utils import JSONSerializable, ensure_directory, log
 from .base import AgentBase
 from .config import AgentConfig
 from ..structure.plan.enum import AgentEnum
@@ -49,6 +48,7 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
 
     def __init__(
         self,
+        *,
         prompt_fn: PromptFn,
         build_plan_fn: BuildPlanFn,
         execute_plan_fn: ExecutePlanFn,
@@ -207,7 +207,7 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
         """
         if not self.start_date:
             self.start_date = datetime.now(timezone.utc)
-        start_date_str = self.start_date.strftime(DATETIME_FMT)
+        start_date_str = self.start_date.strftime("%Y%m%d_%H%M%S")
         return self._module_data_path / self._name / f"{start_date_str}.json"
 
     def save(self) -> Path:
@@ -447,8 +447,7 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
                 / "coordinator_agent"
                 / timestamp
             )
-        self._run_directory.mkdir(parents=True, exist_ok=True)
-        return self._run_directory
+        return ensure_directory(self._run_directory)
 
     @staticmethod
     def _task_label(task: TaskStructure) -> str:

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/agent/runner.py

@@ -11,12 +11,13 @@ from typing import Any, Dict, Optional
 
 from agents import Agent, RunResult, RunResultStreaming, Runner
 
-from openai_sdk_helpers.async_utils import run_coroutine_with_fallback
+from openai_sdk_helpers.utils.async_utils import run_coroutine_with_fallback
 
 
 async def run_async(
     agent: Agent,
     input: str,
+    *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> Any:
@@ -57,6 +58,7 @@ async def run_async(
 def run_sync(
     agent: Agent,
     input: str,
+    *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> Any:
@@ -103,6 +105,7 @@ def run_sync(
 def run_streamed(
     agent: Agent,
     input: str,
+    *,
     context: Optional[Dict[str, Any]] = None,
     output_type: Optional[Any] = None,
 ) -> RunResultStreaming:

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/agent/search/base.py

@@ -117,6 +117,7 @@ class SearchToolAgent(AgentBase, Generic[ItemType, ResultType, PlanType]):
 
     def __init__(
         self,
+        *,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
         max_concurrent_searches: int = 10,

{openai_sdk_helpers-0.1.0 → openai_sdk_helpers-0.1.2}/src/openai_sdk_helpers/agent/search/vector.py

@@ -80,6 +80,7 @@ class VectorSearchTool(
 
     def __init__(
         self,
+        *,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
         store_name: Optional[str] = None,
@@ -256,6 +257,7 @@ class VectorSearch:
 
     def __init__(
         self,
+        *,
         prompt_dir: Optional[Path] = None,
         default_model: Optional[str] = None,
         vector_store_name: Optional[str] = None,