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

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/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/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/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/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/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,

openai_sdk_helpers/cli.py

@@ -0,0 +1,265 @@
+"""Command-line interface for openai-sdk-helpers development.
+
+Provides CLI commands for testing agents, validating templates,
+and inspecting the response registry.
+
+Commands
+--------
+agent test
+    Test an agent locally with sample inputs.
+template validate
+    Validate Jinja2 templates for syntax errors.
+registry list
+    List all registered response configurations.
+registry inspect
+    Inspect a specific configuration.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+try:
+    import openai_sdk_helpers
+
+    __version__ = getattr(openai_sdk_helpers, "__version__", "unknown")
+except ImportError:
+    __version__ = "unknown"
+
+
+def cmd_agent_test(args: argparse.Namespace) -> int:
+    """Test an agent locally.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command arguments containing agent_name and input.
+
+    Returns
+    -------
+    int
+        Exit code (0 for success).
+    """
+    print(f"Testing agent: {args.agent_name}")
+    print(f"Input: {args.input}")
+    print("\n[Not yet implemented - agent testing framework coming soon]")
+    return 0
+
+
+def cmd_template_validate(args: argparse.Namespace) -> int:
+    """Validate Jinja2 templates.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command arguments containing template_path.
+
+    Returns
+    -------
+    int
+        Exit code (0 for success, 1 for validation errors).
+    """
+    from jinja2 import Environment, FileSystemLoader, TemplateSyntaxError
+
+    template_path = Path(args.template_path)
+
+    if not template_path.exists():
+        print(f"Error: Path not found: {template_path}", file=sys.stderr)
+        return 1
+
+    if template_path.is_file():
+        # Validate single file
+        templates = [template_path]
+        base_dir = template_path.parent
+    else:
+        # Validate directory
+        templates = list(template_path.glob("**/*.jinja"))
+        base_dir = template_path
+
+    if not templates:
+        print(f"No .jinja templates found in {template_path}")
+        return 0
+
+    env = Environment(loader=FileSystemLoader(base_dir))
+    errors = []
+
+    for template_file in templates:
+        relative_path = template_file.relative_to(base_dir)
+        try:
+            env.get_template(str(relative_path))
+            print(f"✓ {relative_path}")
+        except TemplateSyntaxError as e:
+            errors.append((relative_path, str(e)))
+            print(f"✗ {relative_path}: {e}", file=sys.stderr)
+
+    if errors:
+        print(f"\n{len(errors)} template(s) with errors", file=sys.stderr)
+        return 1
+
+    print(f"\n{len(templates)} template(s) validated successfully")
+    return 0
+
+
+def cmd_registry_list(args: argparse.Namespace) -> int:
+    """List all registered response configurations.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command arguments.
+
+    Returns
+    -------
+    int
+        Exit code (0 for success).
+    """
+    try:
+        from openai_sdk_helpers import get_default_registry
+    except ImportError:
+        print("Error: openai_sdk_helpers not installed", file=sys.stderr)
+        return 1
+
+    registry = get_default_registry()
+    names = registry.list_names()
+
+    if not names:
+        print("No configurations registered")
+        return 0
+
+    print("Registered configurations:")
+    for name in sorted(names):
+        config = registry.get(name)
+        tools_count = len(config.tools) if config.tools else 0
+        print(f"  - {name} ({tools_count} tools)")
+
+    return 0
+
+
+def cmd_registry_inspect(args: argparse.Namespace) -> int:
+    """Inspect a specific configuration.
+
+    Parameters
+    ----------
+    args : argparse.Namespace
+        Command arguments containing config_name.
+
+    Returns
+    -------
+    int
+        Exit code (0 for success, 1 for not found).
+    """
+    try:
+        from openai_sdk_helpers import get_default_registry
+    except ImportError:
+        print("Error: openai_sdk_helpers not installed", file=sys.stderr)
+        return 1
+
+    registry = get_default_registry()
+
+    try:
+        config = registry.get(args.config_name)
+    except KeyError:
+        print(f"Error: Configuration '{args.config_name}' not found", file=sys.stderr)
+        print("\nAvailable configurations:")
+        for name in sorted(registry.list_names()):
+            print(f"  - {name}")
+        return 1
+
+    print(f"Configuration: {config.name}")
+    instructions_str = str(config.instructions)
+    instructions_preview = (
+        instructions_str[:100] if len(instructions_str) > 100 else instructions_str
+    )
+    print(f"Instructions: {instructions_preview}...")
+    print(f"Tools: {len(config.tools) if config.tools else 0}")
+
+    if config.tools:
+        print("\nTool names:")
+        for tool in config.tools:
+            tool_name = tool.get("function", {}).get("name", "unknown")
+            print(f"  - {tool_name}")
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI interface.
+
+    Parameters
+    ----------
+    argv : list[str], optional
+        Command-line arguments. If None, uses sys.argv.
+
+    Returns
+    -------
+    int
+        Exit code.
+    """
+    parser = argparse.ArgumentParser(
+        prog="openai-helpers",
+        description="OpenAI SDK Helpers CLI",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"openai-sdk-helpers {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # Agent test command
+    agent_parser = subparsers.add_parser("agent", help="Agent operations")
+    agent_sub = agent_parser.add_subparsers(dest="agent_command")
+
+    test_parser = agent_sub.add_parser("test", help="Test an agent")
+    test_parser.add_argument("agent_name", help="Agent name to test")
+    test_parser.add_argument("--input", default="", help="Test input")
+
+    # Template validate command
+    template_parser = subparsers.add_parser("template", help="Template operations")
+    template_sub = template_parser.add_subparsers(dest="template_command")
+
+    validate_parser = template_sub.add_parser("validate", help="Validate templates")
+    validate_parser.add_argument(
+        "template_path",
+        help="Path to template file or directory",
+    )
+
+    # Registry commands
+    registry_parser = subparsers.add_parser("registry", help="Registry operations")
+    registry_sub = registry_parser.add_subparsers(dest="registry_command")
+
+    registry_sub.add_parser("list", help="List registered configurations")
+
+    inspect_parser = registry_sub.add_parser("inspect", help="Inspect configuration")
+    inspect_parser.add_argument("config_name", help="Configuration name")
+
+    args = parser.parse_args(argv)
+
+    if not args.command:
+        parser.print_help()
+        return 0
+
+    # Route commands
+    if args.command == "agent":
+        if args.agent_command == "test":
+            return cmd_agent_test(args)
+    elif args.command == "template":
+        if args.template_command == "validate":
+            return cmd_template_validate(args)
+    elif args.command == "registry":
+        if args.registry_command == "list":
+            return cmd_registry_list(args)
+        elif args.registry_command == "inspect":
+            return cmd_registry_inspect(args)
+
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

openai_sdk_helpers/config.py

@@ -116,7 +116,7 @@ class OpenAISettings(BaseModel):
 
     @classmethod
     def from_env(
-        cls, dotenv_path: Path | None = None, **overrides: Any
+        cls, *, dotenv_path: Path | None = None, **overrides: Any
     ) -> OpenAISettings:
         """Load settings from the environment and optional overrides.
 
@@ -232,4 +232,95 @@ class OpenAISettings(BaseModel):
         return OpenAI(**self.client_kwargs())
 
 
-__all__ = ["OpenAISettings"]
+__all__ = ["OpenAISettings", "build_openai_settings"]
+
+
+def build_openai_settings(
+    api_key: str | None = None,
+    org_id: str | None = None,
+    project_id: str | None = None,
+    base_url: str | None = None,
+    default_model: str | None = None,
+    timeout: float | str | None = None,
+    max_retries: int | str | None = None,
+    dotenv_path: Path | None = None,
+    **extra_kwargs: Any,
+) -> OpenAISettings:
+    """Build OpenAISettings with validation and clear errors.
+
+    Parameters
+    ----------
+    api_key : str or None, default None
+        API key for OpenAI authentication. If None, reads from OPENAI_API_KEY.
+    org_id : str or None, default None
+        Organization ID. If None, reads from OPENAI_ORG_ID.
+    project_id : str or None, default None
+        Project ID. If None, reads from OPENAI_PROJECT_ID.
+    base_url : str or None, default None
+        Base URL for API requests. If None, reads from OPENAI_BASE_URL.
+    default_model : str or None, default None
+        Default model name. If None, reads from OPENAI_MODEL.
+    timeout : float, str, or None, default None
+        Request timeout in seconds. If None, reads from OPENAI_TIMEOUT.
+        Strings are parsed to float.
+    max_retries : int, str, or None, default None
+        Maximum retry attempts. If None, reads from OPENAI_MAX_RETRIES.
+        Strings are parsed to int.
+    dotenv_path : Path or None, default None
+        Path to a .env file. If None, uses environment only.
+    **extra_kwargs : Any
+        Additional keyword arguments forwarded to ``extra_client_kwargs``.
+
+    Returns
+    -------
+    OpenAISettings
+        Configured settings instance.
+
+    Raises
+    ------
+    ValueError
+        If required values are missing or cannot be parsed.
+    TypeError
+        If timeout or max_retries have invalid types.
+    """
+    parsed_timeout: float | None = None
+    if timeout is not None:
+        try:
+            parsed_timeout = coerce_optional_float(timeout)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid timeout value '{timeout}'. Must be a number or numeric string."
+            ) from exc
+
+    parsed_max_retries: int | None = None
+    if max_retries is not None:
+        try:
+            parsed_max_retries = coerce_optional_int(max_retries)
+        except (ValueError, TypeError) as exc:
+            raise ValueError(
+                f"Invalid max_retries value '{max_retries}'. "
+                "Must be an integer or numeric string."
+            ) from exc
+
+    overrides = {}
+    if api_key is not None:
+        overrides["api_key"] = api_key
+    if org_id is not None:
+        overrides["org_id"] = org_id
+    if project_id is not None:
+        overrides["project_id"] = project_id
+    if base_url is not None:
+        overrides["base_url"] = base_url
+    if default_model is not None:
+        overrides["default_model"] = default_model
+    if parsed_timeout is not None:
+        overrides["timeout"] = parsed_timeout
+    if parsed_max_retries is not None:
+        overrides["max_retries"] = parsed_max_retries
+    if extra_kwargs:
+        overrides["extra_client_kwargs"] = extra_kwargs
+
+    try:
+        return OpenAISettings.from_env(dotenv_path=dotenv_path, **overrides)
+    except ValueError as exc:
+        raise ValueError(f"Failed to build OpenAI settings: {exc}") from exc

openai_sdk_helpers/context_manager.py

@@ -11,7 +11,7 @@ from contextlib import asynccontextmanager
 from types import TracebackType
 from typing import Any, AsyncIterator, Generic, Optional, TypeVar
 
-from openai_sdk_helpers.utils.core import log
+from openai_sdk_helpers.logging_config import log
 
 T = TypeVar("T")