feat: add unified monster interface

README.md

@@ -84,6 +84,26 @@ x_star, _ = algorithms.gradient_descent(x0, functions.SEPARABLE_QUARTIC.grad)
 This structure allows you to experiment with the reference NumPy
 implementations directly in your projects.
 
+The PyTorch optimisers ``PSDOptimizer`` and ``PerturbedAdam`` are also
+available directly via ``from psd import ...``.
+
+### All-in-One "Monster" Interface
+
+For rapid experimentation without navigating submodules, import the aggregated
+``psd.monster`` module.  It re-exports the core algorithms, analytic test
+functions and framework-specific optimisers in a single namespace:
+
+```python
+import numpy as np
+from psd import monster
+
+x0 = np.array([1.0, -1.0])
+x_star, _ = monster.gradient_descent(x0, monster.SEPARABLE_QUARTIC.grad)
+```
+
+This unified view aims to be approachable for both humans and language models
+exploring the project.
+
 ### Generating Synthetic Data
 
 ```bash

src/psd/__init__.py

@@ -19,6 +19,12 @@
     PSDTorch = None  # type: ignore
     PSDTensorFlow = None  # type: ignore
 
+try:  # Optional PyTorch optimizers
+    from psd_optimizer import PerturbedAdam, PSDOptimizer
+except Exception:  # pragma: no cover - dependencies may be missing
+    PSDOptimizer = None  # type: ignore
+    PerturbedAdam = None  # type: ignore
+
 try:
     __version__ = version("psd-optimizer")
 except PackageNotFoundError:  # pragma: no cover
@@ -36,6 +42,8 @@
     "disable",
     "PSDTorch",
     "PSDTensorFlow",
+    "PSDOptimizer",
+    "PerturbedAdam",
     "LogStats",
     "analyze_log",
     "summarize_logs",

src/psd/monster.py

@@ -0,0 +1,32 @@
+"""Unified "monster" interface for the PSD library.
+
+This module pulls together the core algorithms, analytic test functions
+and framework-specific optimisers into a single namespace.  It provides a
+single import point for quick experiments, appealing to both humans and
+LLM systems exploring the repository.
+"""
+
+from __future__ import annotations
+
+from . import algorithms as _algorithms
+from . import functions as _functions
+from .algorithms import *  # noqa: F401,F403
+from .functions import *  # noqa: F401,F403
+
+try:  # Optional framework-specific optimisers
+    from .framework_optimizers import PSDTensorFlow, PSDTorch
+except Exception:  # pragma: no cover - dependencies may be missing
+    PSDTorch = None  # type: ignore
+    PSDTensorFlow = None  # type: ignore
+
+try:  # Optional PyTorch optimizers
+    from psd_optimizer import PerturbedAdam, PSDOptimizer
+except Exception:  # pragma: no cover - dependencies may be missing
+    PSDOptimizer = None  # type: ignore
+    PerturbedAdam = None  # type: ignore
+
+__all__ = (
+    _algorithms.__all__  # type: ignore[attr-defined]
+    + _functions.__all__  # type: ignore[attr-defined]
+    + ["PSDTorch", "PSDTensorFlow", "PSDOptimizer", "PerturbedAdam"]
+)