openai-sdk-helpers 0.0.9__tar.gz → 0.1.1__tar.gz

openai_sdk_helpers-0.0.9/README.md → openai_sdk_helpers-0.1.1/PKG-INFO

@@ -1,3 +1,38 @@
+Metadata-Version: 2.4
+Name: openai-sdk-helpers
+Version: 0.1.1
+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
@@ -477,6 +532,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 +578,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.0.9/PKG-INFO → openai_sdk_helpers-0.1.1/README.md

@@ -1,28 +1,3 @@
-Metadata-Version: 2.4
-Name: openai-sdk-helpers
-Version: 0.0.9
-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
@@ -502,6 +497,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 +543,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.0.9 → openai_sdk_helpers-0.1.1}/pyproject.toml

@@ -1,11 +1,23 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.0.9"
+version = "0.1.1"
 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.0.9 → openai_sdk_helpers-0.1.1}/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,
@@ -46,6 +45,9 @@ from .structure import (
     ExtendedSummaryStructure,
     ValidationResultStructure,
     AgentBlueprint,
+    create_plan,
+    execute_task,
+    execute_plan,
 )
 from .prompt import PromptRenderer
 from .config import OpenAISettings
@@ -66,8 +68,38 @@ from .response import (
     ResponseMessage,
     ResponseMessages,
     ResponseToolCall,
+    ResponseConfiguration,
+    ResponseRegistry,
+    get_default_registry,
+    parse_tool_arguments,
     attach_vector_store,
 )
+from .tools import (
+    serialize_tool_result,
+    tool_handler_factory,
+    StructureType,
+    ToolSpec,
+    build_tool_definitions,
+)
+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__ = [
     # Async utilities
@@ -84,8 +116,6 @@ __all__ = [
     "InputValidationError",
     "AsyncExecutionError",
     "ResourceCleanupError",
-    # Logging
-    "LoggerFactory",
     # Retry utilities
     "with_exponential_backoff",
     # Context managers
@@ -133,5 +163,33 @@ __all__ = [
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",
+    "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
+    "parse_tool_arguments",
     "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.0.9 → openai_sdk_helpers-0.1.1}/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.0.9 → openai_sdk_helpers-0.1.1}/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.0.9 → openai_sdk_helpers-0.1.1}/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.0.9 → openai_sdk_helpers-0.1.1}/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.0.9 → openai_sdk_helpers-0.1.1}/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,