openai-sdk-helpers 0.1.4__py3-none-any.whl → 0.3.0__py3-none-any.whl

openai_sdk_helpers/response/config.py

@@ -10,28 +10,19 @@ from openai.types.responses.response_text_config_param import ResponseTextConfig
 from ..config import OpenAISettings
 from ..structure.base import BaseStructure
 from ..response.base import BaseResponse, ToolHandler
+from ..utils import JSONSerializable
+from ..utils.registry import BaseRegistry
+from ..utils.instructions import resolve_instructions_from_path
 
 TIn = TypeVar("TIn", bound="BaseStructure")
 TOut = TypeVar("TOut", bound="BaseStructure")
 
 
-class ResponseRegistry:
+class ResponseRegistry(BaseRegistry["ResponseConfiguration"]):
     """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.
+    Inherits from BaseRegistry to provide centralized storage and retrieval
+    of response configurations, enabling reusable response specs across the application.
 
     Examples
     --------
@@ -49,91 +40,7 @@ class ResponseRegistry:
     '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()
+    pass
 
 
 # Global default registry instance
@@ -158,12 +65,13 @@ def get_default_registry() -> ResponseRegistry:
 
 
 @dataclass(frozen=True, slots=True)
-class ResponseConfiguration(Generic[TIn, TOut]):
+class ResponseConfiguration(JSONSerializable, Generic[TIn, TOut]):
     """
     Represent an immutable configuration describing input and output structures.
 
     Encapsulate all metadata required to define how a request is interpreted and
     how a response is structured, while enforcing strict type and runtime safety.
+    Inherits from JSONSerializable to support serialization to JSON format.
 
     Parameters
     ----------
@@ -181,6 +89,12 @@ class ResponseConfiguration(Generic[TIn, TOut]):
         Structure class used to format or validate output. Schema is
         automatically generated from this structure. Must subclass
         BaseStructure. Default is None.
+    system_vector_store : list[str], optional
+        Optional list of vector store names to attach as system context.
+        Default is None.
+    data_path : Path, str, or None, optional
+        Optional absolute directory path for storing artifacts. If not provided,
+        defaults to get_data_path(class_name). Default is None.
 
     Raises
     ------
@@ -201,6 +115,14 @@ class ResponseConfiguration(Generic[TIn, TOut]):
         Validate configuration invariants and enforce BaseStructure subclassing.
     instructions_text
         Return the resolved instruction content as a string.
+    to_json()
+        Return a JSON-compatible dict representation (inherited from JSONSerializable).
+    to_json_file(filepath)
+        Write serialized JSON data to a file path (inherited from JSONSerializable).
+    from_json(data)
+        Create an instance from a JSON-compatible dict (class method, inherited from JSONSerializable).
+    from_json_file(filepath)
+        Load an instance from a JSON file (class method, inherited from JSONSerializable).
 
     Examples
     --------
@@ -219,6 +141,8 @@ class ResponseConfiguration(Generic[TIn, TOut]):
     tools: Optional[list]
     input_structure: Optional[Type[TIn]]
     output_structure: Optional[Type[TOut]]
+    system_vector_store: Optional[list[str]] = None
+    data_path: Optional[Path | str] = None
 
     def __post_init__(self) -> None:
         """
@@ -277,15 +201,7 @@ class ResponseConfiguration(Generic[TIn, TOut]):
         return self._resolve_instructions()
 
     def _resolve_instructions(self) -> str:
-        if isinstance(self.instructions, Path):
-            instruction_path = self.instructions.expanduser()
-            try:
-                return instruction_path.read_text(encoding="utf-8")
-            except OSError as exc:
-                raise ValueError(
-                    f"Unable to read instructions at '{instruction_path}': {exc}"
-                ) from exc
-        return self.instructions
+        return resolve_instructions_from_path(self.instructions)
 
     def gen_response(
         self,
@@ -328,6 +244,8 @@ class ResponseConfiguration(Generic[TIn, TOut]):
             instructions=instructions,
             tools=self.tools,
             output_structure=self.output_structure,
+            system_vector_store=self.system_vector_store,
+            data_path=self.data_path,
             tool_handlers=tool_handlers,
             openai_settings=openai_settings,
         )

openai_sdk_helpers/response/messages.py

@@ -50,6 +50,14 @@ class ResponseMessage(JSONSerializable):
     -------
     to_openai_format()
         Return the message content in OpenAI API format.
+    to_json()
+        Return a JSON-compatible dict representation (inherited from JSONSerializable).
+    to_json_file(filepath)
+        Write serialized JSON data to a file path (inherited from JSONSerializable).
+    from_json(data)
+        Create an instance from a JSON-compatible dict (class method, inherited from JSONSerializable).
+    from_json_file(filepath)
+        Load an instance from a JSON file (class method, inherited from JSONSerializable).
     """
 
     role: str  # "user", "assistant", "tool", etc.
@@ -113,6 +121,14 @@ class ResponseMessages(JSONSerializable):
         Return the most recent tool message or None.
     get_last_user_message()
         Return the most recent user message or None.
+    to_json()
+        Return a JSON-compatible dict representation (inherited from JSONSerializable).
+    to_json_file(filepath)
+        Write serialized JSON data to a file path (inherited from JSONSerializable).
+    from_json(data)
+        Create an instance from a JSON-compatible dict (class method, inherited from JSONSerializable).
+    from_json_file(filepath)
+        Load an instance from a JSON file (class method, inherited from JSONSerializable).
     """
 
     messages: list[ResponseMessage] = field(default_factory=list)

openai_sdk_helpers/utils/instructions.py

@@ -0,0 +1,35 @@
+"""Utilities for resolving instructions from strings or file paths."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def resolve_instructions_from_path(instructions: str | Path) -> str:
+    """Resolve instructions from a string or file path.
+
+    Parameters
+    ----------
+    instructions : str or Path
+        Either plain-text instructions or a path to a file containing
+        instructions.
+
+    Returns
+    -------
+    str
+        The resolved instruction text.
+
+    Raises
+    ------
+    ValueError
+        If instructions is a Path that cannot be read.
+    """
+    if isinstance(instructions, Path):
+        instruction_path = instructions.expanduser()
+        try:
+            return instruction_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            raise ValueError(
+                f"Unable to read instructions at '{instruction_path}': {exc}"
+            ) from exc
+    return instructions

openai_sdk_helpers/utils/json_utils.py

@@ -3,14 +3,16 @@
 from __future__ import annotations
 
 import json
-from dataclasses import asdict, is_dataclass
+from dataclasses import asdict, fields, is_dataclass
 from datetime import datetime
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
 
 from .path_utils import check_filepath
 
+T = TypeVar("T", bound="JSONSerializable")
+
 
 def _to_jsonable(value: Any) -> Any:
     """Convert common helper types to JSON-serializable forms."""
@@ -65,7 +67,19 @@ class customJSONEncoder(json.JSONEncoder):
 
 
 class JSONSerializable:
-    """Mixin for classes that can be serialized to JSON."""
+    """Mixin for classes that can be serialized to and from JSON.
+
+    Methods
+    -------
+    to_json()
+        Return a JSON-compatible dict representation.
+    to_json_file(filepath)
+        Write serialized JSON data to a file path.
+    from_json(data)
+        Create an instance from a JSON-compatible dict (class method).
+    from_json_file(filepath)
+        Load an instance from a JSON file (class method).
+    """
 
     def to_json(self) -> dict[str, Any]:
         """Return a JSON-compatible dict representation."""
@@ -77,7 +91,18 @@ class JSONSerializable:
         return _to_jsonable(self.__dict__)
 
     def to_json_file(self, filepath: str | Path) -> str:
-        """Write serialized JSON data to a file path."""
+        """Write serialized JSON data to a file path.
+
+        Parameters
+        ----------
+        filepath : str or Path
+            Path where the JSON file will be written.
+
+        Returns
+        -------
+        str
+            Absolute path to the written file.
+        """
         target = Path(filepath)
         check_filepath(fullfilepath=str(target))
         with open(target, "w", encoding="utf-8") as handle:
@@ -90,6 +115,113 @@ class JSONSerializable:
             )
         return str(target)
 
+    @classmethod
+    def from_json(cls: type[T], data: dict[str, Any]) -> T:
+        """Create an instance from a JSON-compatible dict.
+
+        For dataclasses, this reconstructs Path objects and passes the
+        dict keys directly as constructor arguments.
+
+        Parameters
+        ----------
+        data : dict[str, Any]
+            JSON-compatible dictionary containing the instance data.
+
+        Returns
+        -------
+        T
+            New instance of the class.
+
+        Examples
+        --------
+        >>> json_data = {"name": "test", "path": "/tmp/data"}
+        >>> instance = MyClass.from_json(json_data)
+        """
+        if is_dataclass(cls):
+            # Get resolved field types using get_type_hints
+            try:
+                field_types = get_type_hints(cls)
+            except Exception:
+                # Fallback to raw annotations if get_type_hints fails
+                field_types = {f.name: f.type for f in fields(cls)}
+
+            converted_data = {}
+
+            for key, value in data.items():
+                if key in field_types:
+                    field_type = field_types[key]
+
+                    # Check if this field should be converted to Path
+                    should_convert_to_path = False
+
+                    if field_type is Path:
+                        should_convert_to_path = True
+                    else:
+                        # Handle Union/Optional types
+                        origin = get_origin(field_type)
+                        if origin is Union:
+                            type_args = get_args(field_type)
+                            # Only convert to Path if:
+                            # 1. Path is in the union AND
+                            # 2. str is NOT in the union (to avoid converting string fields)
+                            #    OR the field name suggests it's a path (contains "path")
+                            if Path in type_args:
+                                if str not in type_args:
+                                    # Path-only union (e.g., Union[Path, None])
+                                    should_convert_to_path = True
+                                elif "path" in key.lower():
+                                    # Field name contains "path", likely meant to be a path
+                                    should_convert_to_path = True
+
+                    # Convert string to Path if needed
+                    if (
+                        should_convert_to_path
+                        and value is not None
+                        and isinstance(value, str)
+                    ):
+                        converted_data[key] = Path(value)
+                    else:
+                        converted_data[key] = value
+                else:
+                    converted_data[key] = value
+
+            return cls(**converted_data)  # type: ignore[return-value]
+
+        # For non-dataclass types, try to instantiate with data as kwargs
+        return cls(**data)  # type: ignore[return-value]
+
+    @classmethod
+    def from_json_file(cls: type[T], filepath: str | Path) -> T:
+        """Load an instance from a JSON file.
+
+        Parameters
+        ----------
+        filepath : str or Path
+            Path to the JSON file to load.
+
+        Returns
+        -------
+        T
+            New instance of the class loaded from the file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the file does not exist.
+
+        Examples
+        --------
+        >>> instance = MyClass.from_json_file("config.json")
+        """
+        target = Path(filepath)
+        if not target.exists():
+            raise FileNotFoundError(f"JSON file not found: {target}")
+
+        with open(target, "r", encoding="utf-8") as handle:
+            data = json.load(handle)
+
+        return cls.from_json(data)
+
 
 __all__ = [
     "coerce_jsonable",

openai_sdk_helpers/utils/registry.py

@@ -0,0 +1,183 @@
+"""Base registry class for managing configuration instances."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Generic, TypeVar
+
+from .path_utils import ensure_directory
+
+T = TypeVar("T")
+
+
+class BaseRegistry(Generic[T]):
+    """Base registry for managing configuration instances.
+
+    Provides centralized storage and retrieval of configurations,
+    enabling reusable specs across the application. Configurations
+    are stored by name and can be retrieved or listed as needed.
+
+    Type Parameters
+    ---------------
+    T
+        The configuration type this registry manages.
+
+    Methods
+    -------
+    register(config)
+        Add a configuration to the registry.
+    get(name)
+        Retrieve a configuration by name.
+    list_names()
+        Return all registered configuration names.
+    clear()
+        Remove all registered configurations.
+    save_to_directory(path)
+        Export all registered configurations to JSON files.
+    load_from_directory(path)
+        Load configurations from JSON files in a directory.
+    """
+
+    def __init__(self) -> None:
+        """Initialize an empty registry."""
+        self._configs: dict[str, T] = {}
+
+    def register(self, config: T) -> None:
+        """Add a configuration to the registry.
+
+        Parameters
+        ----------
+        config : T
+            Configuration to register. Must have a 'name' attribute.
+
+        Raises
+        ------
+        ValueError
+            If a configuration with the same name is already registered.
+        """
+        name = getattr(config, "name")
+        if name in self._configs:
+            raise ValueError(
+                f"Configuration '{name}' is already registered. "
+                "Use a unique name or clear the registry first."
+            )
+        self._configs[name] = config
+
+    def get(self, name: str) -> T:
+        """Retrieve a configuration by name.
+
+        Parameters
+        ----------
+        name : str
+            Configuration name to look up.
+
+        Returns
+        -------
+        T
+            The registered configuration.
+
+        Raises
+        ------
+        KeyError
+            If no configuration with the given name exists.
+        """
+        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.
+        """
+        return sorted(self._configs.keys())
+
+    def clear(self) -> None:
+        """Remove all registered configurations."""
+        self._configs.clear()
+
+    def save_to_directory(self, path: Path | str) -> None:
+        """Export all registered configurations to JSON files in a directory.
+
+        Serializes each registered configuration to an individual JSON file
+        named after the configuration. Creates the directory if it does not exist.
+
+        Parameters
+        ----------
+        path : Path or str
+            Directory path where JSON files will be saved. Will be created if
+            it does not already exist.
+
+        Raises
+        ------
+        OSError
+            If the directory cannot be created or files cannot be written.
+        """
+        dir_path = ensure_directory(Path(path))
+        config_names = self.list_names()
+
+        if not config_names:
+            return
+
+        for config_name in config_names:
+            config = self.get(config_name)
+            filename = f"{config_name}.json"
+            filepath = dir_path / filename
+            # Call to_json_file on the config
+            getattr(config, "to_json_file")(filepath)
+
+    def load_from_directory(self, path: Path | str, *, config_class: type[T]) -> int:
+        """Load all configurations from JSON files in a directory.
+
+        Scans the directory for JSON files and attempts to load each as a
+        configuration. Successfully loaded configurations are registered.
+        If a file fails to load, a warning is issued and processing continues
+        with the remaining files.
+
+        Parameters
+        ----------
+        path : Path or str
+            Directory path containing JSON configuration files.
+        config_class : type[T]
+            The configuration class to use for deserialization.
+
+        Returns
+        -------
+        int
+            Number of configurations successfully loaded and registered.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the directory does not exist.
+        NotADirectoryError
+            If the path is not a directory.
+        """
+        dir_path = Path(path)
+        if not dir_path.exists():
+            raise FileNotFoundError(f"Directory not found: {dir_path}")
+
+        if not dir_path.is_dir():
+            raise NotADirectoryError(f"Path is not a directory: {dir_path}")
+
+        count = 0
+        for json_file in sorted(dir_path.glob("*.json")):
+            try:
+                config = getattr(config_class, "from_json_file")(json_file)
+                self.register(config)
+                count += 1
+            except Exception as exc:
+                # Log warning but continue processing other files
+                warnings.warn(
+                    f"Failed to load configuration from {json_file}: {exc}",
+                    stacklevel=2,
+                )
+
+        return count

{openai_sdk_helpers-0.1.4.dist-info → openai_sdk_helpers-0.3.0.dist-info}/METADATA

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