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

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openai-sdk-helpers
-Version: 0.0.9
+Version: 0.1.0
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

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

@@ -1,6 +1,6 @@
 [project]
 name = "openai-sdk-helpers"
-version = "0.0.9"
+version = "0.1.0"
 requires-python = ">=3.10"
 readme = "README.md"
 description = "Composable helpers for OpenAI SDK agents, prompts, and storage"

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

@@ -46,6 +46,9 @@ from .structure import (
     ExtendedSummaryStructure,
     ValidationResultStructure,
     AgentBlueprint,
+    create_plan,
+    execute_task,
+    execute_plan,
 )
 from .prompt import PromptRenderer
 from .config import OpenAISettings
@@ -66,8 +69,19 @@ 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,
+)
+from .utils import (
+    build_openai_settings,
+)
 
 __all__ = [
     # Async utilities
@@ -133,5 +147,15 @@ __all__ = [
     "ResponseMessage",
     "ResponseMessages",
     "ResponseToolCall",
+    "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
+    "parse_tool_arguments",
     "attach_vector_store",
+    "serialize_tool_result",
+    "tool_handler_factory",
+    "build_openai_settings",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
 ]

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/config.py

@@ -141,39 +141,37 @@ class OpenAISettings(BaseModel):
         ValueError
             If OPENAI_API_KEY is not found in environment or dotenv file.
         """
-        env_file_values: Mapping[str, str | None]
+        env_file_values: Mapping[str, str | None] = {}
         if dotenv_path is not None:
             env_file_values = dotenv_values(dotenv_path)
-        else:
-            env_file_values = dotenv_values()
-
-        timeout_raw = (
-            overrides.get("timeout")
-            or env_file_values.get("OPENAI_TIMEOUT")
-            or os.getenv("OPENAI_TIMEOUT")
-        )
-        max_retries_raw = (
-            overrides.get("max_retries")
-            or env_file_values.get("OPENAI_MAX_RETRIES")
-            or os.getenv("OPENAI_MAX_RETRIES")
-        )
+
+        def first_non_none(*candidates: Any) -> Any:
+            for candidate in candidates:
+                if candidate is not None:
+                    return candidate
+            return None
+
+        def resolve_value(override_key: str, env_var: str) -> Any:
+            if dotenv_path is not None:
+                return first_non_none(
+                    overrides.get(override_key),
+                    env_file_values.get(env_var),
+                    os.getenv(env_var),
+                )
+            return first_non_none(
+                overrides.get(override_key),
+                os.getenv(env_var),
+            )
+
+        timeout_raw = resolve_value("timeout", "OPENAI_TIMEOUT")
+        max_retries_raw = resolve_value("max_retries", "OPENAI_MAX_RETRIES")
 
         values: dict[str, Any] = {
-            "api_key": overrides.get("api_key")
-            or env_file_values.get("OPENAI_API_KEY")
-            or os.getenv("OPENAI_API_KEY"),
-            "org_id": overrides.get("org_id")
-            or env_file_values.get("OPENAI_ORG_ID")
-            or os.getenv("OPENAI_ORG_ID"),
-            "project_id": overrides.get("project_id")
-            or env_file_values.get("OPENAI_PROJECT_ID")
-            or os.getenv("OPENAI_PROJECT_ID"),
-            "base_url": overrides.get("base_url")
-            or env_file_values.get("OPENAI_BASE_URL")
-            or os.getenv("OPENAI_BASE_URL"),
-            "default_model": overrides.get("default_model")
-            or env_file_values.get("OPENAI_MODEL")
-            or os.getenv("OPENAI_MODEL"),
+            "api_key": resolve_value("api_key", "OPENAI_API_KEY"),
+            "org_id": resolve_value("org_id", "OPENAI_ORG_ID"),
+            "project_id": resolve_value("project_id", "OPENAI_PROJECT_ID"),
+            "base_url": resolve_value("base_url", "OPENAI_BASE_URL"),
+            "default_model": resolve_value("default_model", "OPENAI_MODEL"),
             "timeout": coerce_optional_float(timeout_raw),
             "max_retries": coerce_optional_int(max_retries_raw),
             "extra_client_kwargs": coerce_dict(overrides.get("extra_client_kwargs")),

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/prompt/base.py

@@ -2,12 +2,14 @@
 
 This module provides the PromptRenderer class for loading and rendering
 Jinja2 templates with context variables. Templates can be loaded from a
-specified directory or by absolute path.
+specified directory or by absolute path. Includes template caching for
+improved performance.
 """
 
 from __future__ import annotations
 
 import warnings
+from functools import lru_cache
 from pathlib import Path
 from typing import Any
 
@@ -23,7 +25,8 @@ class PromptRenderer:
 
     Loads and renders Jinja2 templates from a base directory or by absolute
     path. The renderer supports variable substitution, template inheritance,
-    and all standard Jinja2 features for creating dynamic prompts.
+    and all standard Jinja2 features for creating dynamic prompts. Templates
+    are cached using LRU cache for improved performance on repeated renders.
 
     Templates are loaded from a base directory (defaulting to the built-in
     prompt package directory) or can be specified with absolute paths.
@@ -38,6 +41,8 @@ class PromptRenderer:
     -------
     render(template_path, context=None)
         Render a Jinja2 template with the given context variables.
+    clear_cache()
+        Clear the template compilation cache.
 
     Examples
     --------
@@ -103,12 +108,30 @@ class PromptRenderer:
             autoescape=False,  # Prompts are plain text
         )
 
+    @lru_cache(maxsize=128)
+    def _compile_template(self, template_path_str: str) -> Template:
+        """Compile a template by path with LRU caching.
+
+        Parameters
+        ----------
+        template_path_str : str
+            Absolute path to the template file.
+
+        Returns
+        -------
+        Template
+            Compiled Jinja2 template ready for rendering.
+        """
+        template_text = Path(template_path_str).read_text()
+        return Template(template_text)
+
     def render(self, template_path: str, context: dict[str, Any] | None = None) -> str:
         """Render a Jinja2 template with the given context variables.
 
         Loads the template from either an absolute path or a path relative
         to the base directory. The template is rendered with the provided
-        context dictionary using Jinja2's template engine.
+        context dictionary using Jinja2's template engine. Templates are
+        cached for improved performance on repeated renders.
 
         For security, relative paths are validated to prevent path traversal
         attacks. Absolute paths are allowed but should be used with caution
@@ -135,6 +158,8 @@ class PromptRenderer:
         InputValidationError
             If the path contains suspicious patterns or attempts to escape
             the base directory.
+        TemplateNotFound
+            If the template cannot be loaded by Jinja2.
 
         Examples
         --------
@@ -164,9 +189,34 @@ class PromptRenderer:
                 base_dir=self.base_dir,
                 field_name="template_path",
             )
-        template_path_text = template_path_.read_text()
-        template = Template(template_path_text)
+
+        # Check if template exists and provide clear error message
+        if not template_path_.exists():
+            raise FileNotFoundError(
+                f"Template not found: {template_path_}. "
+                f"Ensure the template exists in {self.base_dir} or provide an absolute path."
+            )
+
+        # Cache-compile template by path (not by content)
+        template = self._compile_template(str(template_path_))
         return template.render(context or {})
 
+    def clear_cache(self) -> None:
+        """Clear the template compilation cache.
+
+        Useful when templates are modified during runtime and need to be
+        reloaded. Call this method to force re-compilation of all templates
+        on next render.
+
+        Examples
+        --------
+        >>> renderer = PromptRenderer()
+        >>> renderer.render("template.jinja", {})  # Compiles and caches
+        >>> # ... modify template.jinja ...
+        >>> renderer.clear_cache()  # Clear cache
+        >>> renderer.render("template.jinja", {})  # Re-compiles
+        """
+        self._compile_template.cache_clear()
+
 
 __all__ = ["PromptRenderer"]

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/response/__init__.py

@@ -33,20 +33,23 @@ attach_vector_store
 from __future__ import annotations
 
 from .base import BaseResponse
-from .config import ResponseConfiguration
+from .config import ResponseConfiguration, ResponseRegistry, get_default_registry
 from .messages import ResponseMessage, ResponseMessages
 from .runner import run_async, run_streamed, run_sync
-from .tool_call import ResponseToolCall
+from .tool_call import ResponseToolCall, parse_tool_arguments
 from .vector_store import attach_vector_store
 
 __all__ = [
     "BaseResponse",
     "ResponseConfiguration",
+    "ResponseRegistry",
+    "get_default_registry",
     "ResponseMessage",
     "ResponseMessages",
     "run_sync",
     "run_async",
     "run_streamed",
     "ResponseToolCall",
+    "parse_tool_arguments",
     "attach_vector_store",
 ]

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/response/config.py

@@ -15,6 +15,148 @@ TIn = TypeVar("TIn", bound="BaseStructure")
 TOut = TypeVar("TOut", bound="BaseStructure")
 
 
+class ResponseRegistry:
+    """Registry for managing ResponseConfiguration instances.
+
+    Provides centralized storage and retrieval of response configurations,
+    enabling reusable response specs across the application. Configurations
+    are stored by name and can be retrieved or listed as needed.
+
+    Methods
+    -------
+    register(config)
+        Add a ResponseConfiguration to the registry.
+    get(name)
+        Retrieve a configuration by name.
+    list_names()
+        Return all registered configuration names.
+    clear()
+        Remove all registered configurations.
+
+    Examples
+    --------
+    >>> registry = ResponseRegistry()
+    >>> config = ResponseConfiguration(
+    ...     name="test",
+    ...     instructions="Test instructions",
+    ...     tools=None,
+    ...     input_structure=None,
+    ...     output_structure=None
+    ... )
+    >>> registry.register(config)
+    >>> retrieved = registry.get("test")
+    >>> retrieved.name
+    'test'
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry."""
+        self._configs: dict[str, ResponseConfiguration] = {}
+
+    def register(self, config: ResponseConfiguration) -> None:
+        """Add a ResponseConfiguration to the registry.
+
+        Parameters
+        ----------
+        config : ResponseConfiguration
+            Configuration to register.
+
+        Raises
+        ------
+        ValueError
+            If a configuration with the same name is already registered.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> config = ResponseConfiguration(...)
+        >>> registry.register(config)
+        """
+        if config.name in self._configs:
+            raise ValueError(
+                f"Configuration '{config.name}' is already registered. "
+                "Use a unique name or clear the registry first."
+            )
+        self._configs[config.name] = config
+
+    def get(self, name: str) -> ResponseConfiguration:
+        """Retrieve a configuration by name.
+
+        Parameters
+        ----------
+        name : str
+            Configuration name to look up.
+
+        Returns
+        -------
+        ResponseConfiguration
+            The registered configuration.
+
+        Raises
+        ------
+        KeyError
+            If no configuration with the given name exists.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> config = registry.get("test")
+        """
+        if name not in self._configs:
+            raise KeyError(
+                f"No configuration named '{name}' found. "
+                f"Available: {list(self._configs.keys())}"
+            )
+        return self._configs[name]
+
+    def list_names(self) -> list[str]:
+        """Return all registered configuration names.
+
+        Returns
+        -------
+        list[str]
+            Sorted list of configuration names.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> registry.list_names()
+        []
+        """
+        return sorted(self._configs.keys())
+
+    def clear(self) -> None:
+        """Remove all registered configurations.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> registry.clear()
+        """
+        self._configs.clear()
+
+
+# Global default registry instance
+_default_registry = ResponseRegistry()
+
+
+def get_default_registry() -> ResponseRegistry:
+    """Return the global default registry instance.
+
+    Returns
+    -------
+    ResponseRegistry
+        Singleton registry for application-wide configuration storage.
+
+    Examples
+    --------
+    >>> registry = get_default_registry()
+    >>> config = ResponseConfiguration(...)
+    >>> registry.register(config)
+    """
+    return _default_registry
+
+
 @dataclass(frozen=True, slots=True)
 class ResponseConfiguration(Generic[TIn, TOut]):
     """

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/response/tool_call.py

@@ -94,17 +94,20 @@ class ResponseToolCall:
         return function_call, function_call_output
 
 
-def parse_tool_arguments(arguments: str) -> dict:
+def parse_tool_arguments(arguments: str, tool_name: str) -> dict:
     """Parse tool call arguments with fallback for malformed JSON.
 
     Attempts to parse arguments as JSON first, then falls back to
     ast.literal_eval for cases where the OpenAI API returns minor
     formatting issues like single quotes instead of double quotes.
+    Provides clear error context including tool name and raw payload.
 
     Parameters
     ----------
     arguments : str
         Raw argument string from a tool call, expected to be JSON.
+    tool_name : str
+        Tool name for improved error context (required).
 
     Returns
     -------
@@ -115,13 +118,14 @@ def parse_tool_arguments(arguments: str) -> dict:
     ------
     ValueError
         If the arguments cannot be parsed as valid JSON or Python literal.
+        Error message includes tool name and payload excerpt for debugging.
 
     Examples
     --------
-    >>> parse_tool_arguments('{"key": "value"}')
+    >>> parse_tool_arguments('{"key": "value"}', tool_name="search")
     {'key': 'value'}
 
-    >>> parse_tool_arguments("{'key': 'value'}")
+    >>> parse_tool_arguments("{'key': 'value'}", tool_name="search")
     {'key': 'value'}
     """
     try:
@@ -130,4 +134,11 @@ def parse_tool_arguments(arguments: str) -> dict:
         try:
             return ast.literal_eval(arguments)
         except Exception as exc:  # noqa: BLE001
-            raise ValueError(f"Invalid JSON arguments: {arguments}") from exc
+            # Build informative error message with context
+            payload_preview = (
+                arguments[:100] + "..." if len(arguments) > 100 else arguments
+            )
+            raise ValueError(
+                f"Failed to parse tool arguments for tool '{tool_name}'. "
+                f"Raw payload: {payload_preview}"
+            ) from exc

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/structure/__init__.py

@@ -86,6 +86,9 @@ __all__ = [
     "AgentEnum",
     "TaskStructure",
     "PlanStructure",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
     "PromptStructure",
     "SummaryTopic",
     "SummaryStructure",

{openai_sdk_helpers-0.0.9 → openai_sdk_helpers-0.1.0}/src/openai_sdk_helpers/structure/plan/__init__.py

@@ -2,7 +2,8 @@
 
 This package provides Pydantic models for representing agent execution plans,
 including task definitions, agent type enumerations, and plan structures with
-sequential execution support.
+sequential execution support. Also includes helper functions for creating and
+executing plans.
 
 Classes
 -------
@@ -12,6 +13,15 @@ TaskStructure
     Individual agent task with status tracking and results.
 AgentEnum
     Enumeration of available agent types.
+
+Functions
+---------
+create_plan
+    Create a PlanStructure from a sequence of tasks.
+execute_task
+    Execute a single task with an agent callable.
+execute_plan
+    Execute a complete plan using registered agent callables.
 """
 
 from __future__ import annotations
@@ -19,9 +29,13 @@ from __future__ import annotations
 from .plan import PlanStructure
 from .task import TaskStructure
 from .enum import AgentEnum
+from .helpers import create_plan, execute_task, execute_plan
 
 __all__ = [
     "PlanStructure",
     "TaskStructure",
     "AgentEnum",
+    "create_plan",
+    "execute_task",
+    "execute_plan",
 ]