coremat 0.9.0__py3-none-any.whl

coremat/__init__.py

@@ -0,0 +1,200 @@
+"""
+COREMat Framework -- Public API
+================================
+
+COREMat (COmputable REgression for Materials) is a Python framework for
+tabular machine learning covering the full workflow from raw data to
+predictions and evaluation.
+
+Quick Start::
+
+    from coremat import ModelTrainer, FrameworkConfig, PathsConfig
+
+All heavy dependencies (scikit-learn, optuna, tabpfn, shapiq, torch) are
+imported lazily so that ``import coremat`` is fast and lightweight.
+
+Exports
+-------
+Configuration (always available):
+    FrameworkConfig, PathsConfig, DataPreprocessingConfig, PreprocessSettings,
+    TrainConfig, OptunaConfig, ModelsConfig, ModelRunOverride, ResolvedModelConfig,
+    TransformConfig, EvalConfig, RunConfig
+
+Types (always available):
+    PreprocessPolicy
+
+Training (lazy):
+    ModelTrainer
+
+Preprocessing (lazy):
+    CustomPreprocessor, DataframePreprocessingPipeline
+
+Evaluation (lazy):
+    compute_metrics
+
+Registry (lazy):
+    ModelSpec, get_model_spec
+
+Runtime (lazy):
+    run_training, run_evaluation
+"""
+from __future__ import annotations
+
+import importlib
+
+# ---------------------------------------------------------------------------
+# Version -- derived from installed package metadata (setuptools-scm)
+# ---------------------------------------------------------------------------
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _metadata_version
+from typing import TYPE_CHECKING, Any
+
+try:
+    __version__: str = _metadata_version("coremat")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# ---------------------------------------------------------------------------
+# Lightweight config imports (dataclasses only, no heavy deps)
+# ---------------------------------------------------------------------------
+from .core.config import (
+    DataPreprocessingConfig,
+    EvalConfig,
+    FrameworkConfig,
+    ModelRunOverride,
+    ModelsConfig,
+    OptunaConfig,
+    PathsConfig,
+    PreprocessSettings,
+    ResolvedModelConfig,
+    RunConfig,
+    TrainConfig,
+    TransformConfig,
+)
+from .core.types import PreprocessPolicy
+
+# ---------------------------------------------------------------------------
+# __all__ -- defines the public API surface
+# ---------------------------------------------------------------------------
+__all__ = [
+    # Metadata
+    "__version__",
+    # Configuration dataclasses
+    "FrameworkConfig",
+    "PathsConfig",
+    "DataPreprocessingConfig",
+    "PreprocessSettings",
+    "TrainConfig",
+    "OptunaConfig",
+    "ModelsConfig",
+    "ModelRunOverride",
+    "ResolvedModelConfig",
+    "TransformConfig",
+    "EvalConfig",
+    "RunConfig",
+    # Core types
+    "PreprocessPolicy",
+    # Training (lazy)
+    "ModelTrainer",
+    # Preprocessing (lazy)
+    "CustomPreprocessor",
+    "DataframePreprocessingPipeline",
+    # Evaluation (lazy)
+    "compute_metrics",
+    # Registry (lazy) — custom-model extension point (#141)
+    "ModelSpec",
+    "get_model_spec",
+    "register",
+    "model_description",
+    # Recommend (lazy)
+    "recommend",
+    "RecommendResult",
+    # Runtime (lazy)
+    "run_training",
+    "run_evaluation",
+]
+
+# ---------------------------------------------------------------------------
+# Lazy imports -- heavy modules are only loaded on first access
+# ---------------------------------------------------------------------------
+# Mapping from attribute name to (module_path, attribute_name)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # Training
+    "ModelTrainer": (".trainlab.train", "ModelTrainer"),
+    # Preprocessing
+    "CustomPreprocessor": (".preplab.preprocessing", "CustomPreprocessor"),
+    "DataframePreprocessingPipeline": (
+        ".preplab.preprocessing",
+        "DataframePreprocessingPipeline",
+    ),
+    # Evaluation
+    "compute_metrics": (".evallab.evaluation", "compute_metrics"),
+    # Registry
+    "ModelSpec": (".trainlab.registry", "ModelSpec"),
+    "get_model_spec": (".trainlab.registry", "get_model_spec"),
+    "register": (".trainlab.registry", "register"),
+    "model_description": (".trainlab.registry", "model_description"),
+    # Recommend
+    "recommend": (".trainlab.recommend", "recommend"),
+    "RecommendResult": (".trainlab.recommend", "RecommendResult"),
+    # Runtime
+    "run_training": (".runtime.train_runner", "run_training"),
+    "run_evaluation": (".runtime.eval_runner", "run_evaluation"),
+}
+
+if TYPE_CHECKING:
+    # Provide static type information for lazy imports
+    from .evallab.evaluation import compute_metrics as compute_metrics
+    from .preplab.preprocessing import (
+        CustomPreprocessor as CustomPreprocessor,
+    )
+    from .preplab.preprocessing import (
+        DataframePreprocessingPipeline as DataframePreprocessingPipeline,
+    )
+    from .runtime.eval_runner import run_evaluation as run_evaluation
+    from .runtime.train_runner import run_training as run_training
+    from .trainlab.recommend import (
+        RecommendResult as RecommendResult,
+    )
+    from .trainlab.recommend import (
+        recommend as recommend,
+    )
+    from .trainlab.registry import (
+        ModelSpec as ModelSpec,
+    )
+    from .trainlab.registry import (
+        get_model_spec as get_model_spec,
+    )
+    from .trainlab.registry import (
+        model_description as model_description,
+    )
+    from .trainlab.registry import (
+        register as register,
+    )
+    from .trainlab.train import ModelTrainer as ModelTrainer
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load heavy modules on first attribute access.
+
+    This keeps ``import coremat`` fast by deferring imports of modules that
+    pull in scikit-learn, optuna, tabpfn, shapiq, or torch until they are
+    actually needed.
+
+    Args:
+        name: The attribute name being accessed.
+
+    Returns:
+        The lazily imported object.
+
+    Raises:
+        AttributeError: If *name* is not a public API member.
+    """
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = importlib.import_module(module_path, package=__name__)
+        obj = getattr(module, attr_name)
+        # Cache on the module so __getattr__ is not called again
+        globals()[name] = obj
+        return obj
+    raise AttributeError(f"module 'coremat' has no attribute {name!r}")