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

openai_sdk_helpers/agent/coordination.py

@@ -44,6 +44,14 @@ class CoordinatorAgent(AgentBase, JSONSerializable):
         Return a JSON-serializable snapshot of stored project data.
     save()
         Persist the stored project data to a JSON file.
+    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).
     """
 
     def __init__(

openai_sdk_helpers/response/base.py

@@ -126,10 +126,10 @@ class BaseResponse(Generic[T]):
         instructions: str,
         tools: list | None,
         output_structure: type[T] | None,
-        tool_handlers: dict[str, ToolHandler],
-        openai_settings: OpenAISettings,
         system_vector_store: list[str] | None = None,
         data_path: Path | str | None = None,
+        tool_handlers: dict[str, ToolHandler] | None = None,
+        openai_settings: OpenAISettings | None = None,
     ) -> None:
         """Initialize a response session with OpenAI configuration.
 
@@ -150,18 +150,19 @@ class BaseResponse(Generic[T]):
             Structure class used to parse tool call outputs. When provided,
             the schema is automatically generated using the structure's
             response_format() method. Pass None for unstructured responses.
-        tool_handlers : dict[str, ToolHandler]
-            Mapping from tool names to callable handlers. Each handler receives
-            a ResponseFunctionToolCall and returns a string or any serializable
-            result.
-        openai_settings : OpenAISettings
-            Fully configured OpenAI settings with API key and default model.
         system_vector_store : list[str] or None, default None
             Optional list of vector store names to attach as system context.
         data_path : Path, str, or None, default None
             Optional absolute directory path for storing artifacts. If not provided,
             defaults to get_data_path(class_name). Session files are saved as
             data_path / uuid.json.
+        tool_handlers : dict[str, ToolHandler] or None, default None
+            Mapping from tool names to callable handlers. Each handler receives
+            a ResponseFunctionToolCall and returns a string or any serializable
+            result. Defaults to an empty dict when not provided.
+        openai_settings : OpenAISettings or None, default None
+            Fully configured OpenAI settings with API key and default model.
+            Required for normal operation.
 
         Raises
         ------
@@ -184,6 +185,11 @@ class BaseResponse(Generic[T]):
         ...     openai_settings=settings,
         ... )
         """
+        if tool_handlers is None:
+            tool_handlers = {}
+        if openai_settings is None:
+            raise ValueError("openai_settings is required")
+
         self._tool_handlers = tool_handlers
         self._name = name
 

openai_sdk_helpers/response/config.py

@@ -10,6 +10,8 @@ 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.path_utils import ensure_directory
 
 TIn = TypeVar("TIn", bound="BaseStructure")
 TOut = TypeVar("TOut", bound="BaseStructure")
@@ -135,6 +137,45 @@ class ResponseRegistry:
         """
         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 ResponseConfiguration 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.
+
+        Returns
+        -------
+        None
+
+        Raises
+        ------
+        OSError
+            If the directory cannot be created or files cannot be written.
+
+        Examples
+        --------
+        >>> registry = ResponseRegistry()
+        >>> registry.save_to_directory("./data")
+        >>> registry.save_to_directory(Path("exports"))
+        """
+        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
+            config.to_json_file(filepath)
+
 
 # Global default registry instance
 _default_registry = ResponseRegistry()
@@ -158,12 +199,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 +223,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 +249,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 +275,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:
         """
@@ -328,6 +386,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/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,105 @@ 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)
+                            # Check if Path is one of the union types
+                            if Path in type_args:
+                                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-0.1.4.dist-info → openai_sdk_helpers-0.2.0.dist-info}/METADATA

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

{openai_sdk_helpers-0.1.4.dist-info → openai_sdk_helpers-0.2.0.dist-info}/RECORD

@@ -14,7 +14,7 @@ openai_sdk_helpers/types.py,sha256=xzldCRfwCZ3rZl18IBmfgA-PVdoZKSWNrlSIhirumSo,1
 openai_sdk_helpers/agent/__init__.py,sha256=giowU8jke0z0h7FFUG9V6Vssja8AYwvJMQbiMb3s64k,960
 openai_sdk_helpers/agent/base.py,sha256=8ZkW57vL8_fYzuLr6f9kMvBChYq5lN5vQ8MMJtcWD9s,11784
 openai_sdk_helpers/agent/config.py,sha256=htqy5bcrJeMf3rIpRdL9CKlYwyQI4po420rcgR3i8XI,1971
-openai_sdk_helpers/agent/coordination.py,sha256=knhQtOyQGGkqKb6Q-pWSRwrVW0qJcVvxelinIctNs-A,16152
+openai_sdk_helpers/agent/coordination.py,sha256=mAIEjWJ7xnagKssLCrOEn1oOp-XoqYpQOdRlZpUyw90,16610
 openai_sdk_helpers/agent/prompt_utils.py,sha256=-1M66tqQxh9wWCFg6X-K7cCcqauca3yA04ZjvOpN3bA,337
 openai_sdk_helpers/agent/runner.py,sha256=1_azIWx1Bcy7RRlEbizTD0LXBdYgof_tYMpDUcnJJuM,4164
 openai_sdk_helpers/agent/summarizer.py,sha256=fH8AnYK_68ERf2U7mv0nwXL8KyhrluE-TDY_M5TCdD0,3266
@@ -33,10 +33,10 @@ openai_sdk_helpers/prompt/summarizer.jinja,sha256=jliSetWDISbql1EkWi1RB8-L_BXUg8
 openai_sdk_helpers/prompt/translator.jinja,sha256=SZhW8ipEzM-9IA4wyS_r2wIMTAclWrilmk1s46njoL0,291
 openai_sdk_helpers/prompt/validator.jinja,sha256=6t8q_IdxFd3mVBGX6SFKNOert1Wo3YpTOji2SNEbbtE,547
 openai_sdk_helpers/response/__init__.py,sha256=td-HTSPLtl1d5AkUFZ0rrUBUfsacM_CGtZQNj1_GWB8,1886
-openai_sdk_helpers/response/base.py,sha256=rDzFBLl8hU1Rho7SfLUcd0eQLRpn1ZRAvvzXDqdWf0c,29854
-openai_sdk_helpers/response/config.py,sha256=zZ4w2-GTSKg-7XgK6iUb5pDK-5aBFd2WkvbIjvegyHU,10871
+openai_sdk_helpers/response/base.py,sha256=Y77LbnNB50-CG_KPYxM6XU0lIj9pYvAQt7FzekeHhF4,30176
+openai_sdk_helpers/response/config.py,sha256=pZgjh5GOb4juy1Afnyn28QS3yIArByU2MAJIc1_i3WM,13237
 openai_sdk_helpers/response/files.py,sha256=ANCoedNHXmpTXSaaGUvesAGq2DIUXT7SKZDCIJlXOv8,13226
-openai_sdk_helpers/response/messages.py,sha256=G4V8a9gis4b8wFW5XnvBE0AHMX0FrkOzqiQ6FxigpnU,9145
+openai_sdk_helpers/response/messages.py,sha256=AbxLy2Q3sDHFLhhhoKfCcrRVlA8M7Ts9SuYx0PODi54,10061
 openai_sdk_helpers/response/runner.py,sha256=Rf13cQGsR7sN9gA81Y5th1tfH2DCCAwQ6RMs3bVgjnk,4269
 openai_sdk_helpers/response/tool_call.py,sha256=VYPvKUR-Ren0Y_nYS4jUSinhTyXKzFwQLxu-d3r_YuM,4506
 openai_sdk_helpers/response/vector_store.py,sha256=MyHUu6P9ueNsd9erbBkyVqq3stLK6qVuehdvmFAHq9E,3074
@@ -64,7 +64,7 @@ openai_sdk_helpers/utils/async_utils.py,sha256=9KbPEVfi6IXdbwkTUE0h5DleK8TI7I6P_
 openai_sdk_helpers/utils/coercion.py,sha256=Pq1u7tAbD7kTZ84lK-7Fb9CyYKKKQt4fypG5BlSI6oQ,3774
 openai_sdk_helpers/utils/deprecation.py,sha256=VF0VDDegawYhsu5f-vE6dop9ob-jv8egxsm0KsPvP9E,4753
 openai_sdk_helpers/utils/encoding.py,sha256=oDtlNGZ5p-edXiHW76REs-0-8NXkQNReKJdj6sHLkt8,4615
-openai_sdk_helpers/utils/json_utils.py,sha256=dpv0IPZp4WKL7HsDAQY2za820ukn0cre6kAv-pYw7P0,3141
+openai_sdk_helpers/utils/json_utils.py,sha256=Z-9AugR0CbNMLXcaJk1IJ-SwGNdo_d0a3r6MqP8rbYs,7089
 openai_sdk_helpers/utils/output_validation.py,sha256=O9Adt-fxL5DtnMd1GuZ9E2YxX3yj4uzSZuBNKVH2GkI,12152
 openai_sdk_helpers/utils/path_utils.py,sha256=qGGDpuDnY5EODOACzH23MYECQOE2rKhrQ3sbDvefwEg,1307
 openai_sdk_helpers/utils/validation.py,sha256=ZjnZNOy5AoFlszRxarNol6YZwfgw6LnwPtkCekZmwAU,7826
@@ -72,8 +72,8 @@ openai_sdk_helpers/vector_storage/__init__.py,sha256=L5LxO09puh9_yBB9IDTvc1CvVkA
 openai_sdk_helpers/vector_storage/cleanup.py,sha256=ImWIE-9lli-odD8qIARvmeaa0y8ZD4pYYP-kT0O3178,3552
 openai_sdk_helpers/vector_storage/storage.py,sha256=1juu3Qq6hy33afvVfQeI5A35fQzIPjVZumZ-aP_MxhU,23305
 openai_sdk_helpers/vector_storage/types.py,sha256=jTCcOYMeOpZWvcse0z4T3MVs-RBOPC-fqWTBeQrgafU,1639
-openai_sdk_helpers-0.1.4.dist-info/METADATA,sha256=xYqGRG7IMVPkN-THuqKYxN8wwZVrDlldfXV0MDwIb38,23557
-openai_sdk_helpers-0.1.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-openai_sdk_helpers-0.1.4.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
-openai_sdk_helpers-0.1.4.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
-openai_sdk_helpers-0.1.4.dist-info/RECORD,,
+openai_sdk_helpers-0.2.0.dist-info/METADATA,sha256=4uIwpDW0oqwdAqsf5uhb_GmutPvrlek0pbO6G4zYVXU,23557
+openai_sdk_helpers-0.2.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.2.0.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
+openai_sdk_helpers-0.2.0.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.2.0.dist-info/RECORD,,