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

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.2.0.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.2.0
+Version: 0.3.0
 Summary: Composable helpers for OpenAI SDK agents, prompts, and storage
 Author: openai-sdk-helpers maintainers
 License: MIT

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

@@ -1,4 +1,4 @@
-openai_sdk_helpers/__init__.py,sha256=rsCoQ2yB8jJmWZxbXeXTf0dPcyWJIzghCS_CVPkBWKg,4626
+openai_sdk_helpers/__init__.py,sha256=uqVd5iDoSo5_jlL9xX8sVRpZZhmc4isna7cr6RTP2Gc,4640
 openai_sdk_helpers/cli.py,sha256=J62XKPkGgYzYHKHfnkFy53Dp4rvBXf9cPEl1hrev3ZU,7400
 openai_sdk_helpers/config.py,sha256=pjBzjYM9Fs4DQqwio387lBt_4IwWKct_VNZBSe-bMqg,10972
 openai_sdk_helpers/context_manager.py,sha256=QqlrtenwKoz2krY0IzuToKdTX1HptUYtIEylxieybgY,6633
@@ -11,20 +11,20 @@ openai_sdk_helpers/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 openai_sdk_helpers/retry.py,sha256=J10oQYphfzDXm3BnLoXwxk7PAhN93TC2LQOv0VDGOwI,6533
 openai_sdk_helpers/tools.py,sha256=C2xl0euovFyrDVh0qf1pEyuaicmrTmoZcJu9CxCKqic,9534
 openai_sdk_helpers/types.py,sha256=xzldCRfwCZ3rZl18IBmfgA-PVdoZKSWNrlSIhirumSo,1451
-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=mAIEjWJ7xnagKssLCrOEn1oOp-XoqYpQOdRlZpUyw90,16610
+openai_sdk_helpers/agent/__init__.py,sha256=Dst1jjP5a-iLItis0B-RMMYiHB_yw_2ZusU38u7YQyE,1086
+openai_sdk_helpers/agent/base.py,sha256=RotgsaCXVfxhrEE_7fyiR3ekhGunecTdwJ6p8lAyEM8,17348
+openai_sdk_helpers/agent/config.py,sha256=dY76c5Tqn_MYe7huN_1HIDQCVkerEJwqaFGvPaXF8kQ,13773
+openai_sdk_helpers/agent/coordination.py,sha256=rxUWhdgdEvPOrab6CbQIquzpOZDsIVXgFLNJEe_nVaY,16720
 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
-openai_sdk_helpers/agent/translator.py,sha256=GhUuwFTBecgOO9pMQ41VPvK9mTub5DXJ_7BIS9Xp7bs,5082
+openai_sdk_helpers/agent/runner.py,sha256=w7gBFEuYGn7aKPpf9KNULboNY3pM2yLcoRcl_w80Wr4,4662
+openai_sdk_helpers/agent/summarizer.py,sha256=gmQlzhL4DaSzItlqLMfqFC4Xns0imPG3OIaIzjDVDrQ,3327
+openai_sdk_helpers/agent/translator.py,sha256=PbwfC6sbLkaU4bHwY5LdBqn5gMzYzKazZwJwk5nDLSo,5143
 openai_sdk_helpers/agent/utils.py,sha256=DTD5foCqGYfXf13F2bZMYIQROl7SbDSy5GDPGi0Zl-0,1089
-openai_sdk_helpers/agent/validation.py,sha256=JIYVhBTTs0tTxYyzYgY3BHC-9psyzE3LLQDZDqpg13M,4191
+openai_sdk_helpers/agent/validation.py,sha256=uQBi1irE7sX2B_tvkpTpOX97Yz9oVdCXXIUTCyhM37o,4252
 openai_sdk_helpers/agent/search/__init__.py,sha256=xqosfzH4HcBs9IFZks9msG_694rS5q6Ea4_qNeRQRmU,798
-openai_sdk_helpers/agent/search/base.py,sha256=EP4WCIC-IItToTFVRVpg1pj1PC5QtqheIiK1l087yRg,8613
-openai_sdk_helpers/agent/search/vector.py,sha256=xMWhuRQENdWfLN1NTBzEjMfq1WsaGS6yn70-Xq9oFj4,13622
-openai_sdk_helpers/agent/search/web.py,sha256=8le4xnZ3nllySqWb7rZaOq44ZR8q67c_WiE57ncmL90,10014
+openai_sdk_helpers/agent/search/base.py,sha256=lSfh7kMphmGRLrmBzDLprs_Owm7tL9moYbKhkU1tZ0M,8704
+openai_sdk_helpers/agent/search/vector.py,sha256=bkd6OJT0FSioWaVgp1ZOLaHYV33HNrOyfCSCkFbhBtk,13833
+openai_sdk_helpers/agent/search/web.py,sha256=81qPBmwj7HnMqJW0g3f_9_OoPOiVlKAy-gEUM92WROk,10225
 openai_sdk_helpers/enums/__init__.py,sha256=aFf79C4JBeLC3kMlJfSpehyjx5uNCtW6eK5rD6ZFfhM,322
 openai_sdk_helpers/enums/base.py,sha256=cNllDtzcgI0_eZYXxFko14yhxwicX6xbeDfz9gFE3qo,2753
 openai_sdk_helpers/prompt/__init__.py,sha256=MOqgKwG9KLqKudoKRlUfLxiSmdOi2aD6hNrWDFqLHkk,418
@@ -33,8 +33,8 @@ 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=Y77LbnNB50-CG_KPYxM6XU0lIj9pYvAQt7FzekeHhF4,30176
-openai_sdk_helpers/response/config.py,sha256=pZgjh5GOb4juy1Afnyn28QS3yIArByU2MAJIc1_i3WM,13237
+openai_sdk_helpers/response/base.py,sha256=oX2uIjRDVEOSJVp3_WkJrBI6a2DPVaEBiKSrRj-oD-4,32869
+openai_sdk_helpers/response/config.py,sha256=bbl1kCvOhAS1vIoN60c-gNRavXZHO1kY_RqYztPqN30,9150
 openai_sdk_helpers/response/files.py,sha256=ANCoedNHXmpTXSaaGUvesAGq2DIUXT7SKZDCIJlXOv8,13226
 openai_sdk_helpers/response/messages.py,sha256=AbxLy2Q3sDHFLhhhoKfCcrRVlA8M7Ts9SuYx0PODi54,10061
 openai_sdk_helpers/response/runner.py,sha256=Rf13cQGsR7sN9gA81Y5th1tfH2DCCAwQ6RMs3bVgjnk,4269
@@ -64,16 +64,18 @@ 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=Z-9AugR0CbNMLXcaJk1IJ-SwGNdo_d0a3r6MqP8rbYs,7089
+openai_sdk_helpers/utils/instructions.py,sha256=trbjxjxv2otQR9VmBsPFk1_CJj8nA85Sgtj_5QmQOKI,942
+openai_sdk_helpers/utils/json_utils.py,sha256=g8x497URz0bNYHgdcYM_3kNzj9QKsN5xionH1yh5nMk,7674
 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/registry.py,sha256=qezdmsCRokrV9snXNyUG2rJ-jBG-UCCkp7-rRBE9LFY,5565
 openai_sdk_helpers/utils/validation.py,sha256=ZjnZNOy5AoFlszRxarNol6YZwfgw6LnwPtkCekZmwAU,7826
 openai_sdk_helpers/vector_storage/__init__.py,sha256=L5LxO09puh9_yBB9IDTvc1CvVkARVkHqYY1KX3inB4c,975
 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.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,,
+openai_sdk_helpers-0.3.0.dist-info/METADATA,sha256=7KeZYCdLQTmtvQj0mZVWzimqkA0hNzU9RNnN_25z2CY,23557
+openai_sdk_helpers-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+openai_sdk_helpers-0.3.0.dist-info/entry_points.txt,sha256=gEOD1ZeXe8d2OP-KzUlG-b_9D9yUZTCt-GFW3EDbIIY,63
+openai_sdk_helpers-0.3.0.dist-info/licenses/LICENSE,sha256=CUhc1NrE50bs45tcXF7OcTQBKEvkUuLqeOHgrWQ5jaA,1067
+openai_sdk_helpers-0.3.0.dist-info/RECORD,,