fundamental-client 0.2.3__py3-none-any.whl

fundamental/__init__.py

@@ -0,0 +1,34 @@
+"""Fundamental Python SDK for tabular machine learning."""
+
+from typing import Optional
+
+from fundamental.clients import BaseClient, Fundamental, FundamentalEC2Client
+
+# Deprecated aliases
+from fundamental.deprecated import FTMClassifier, FTMRegressor
+from fundamental.estimator import NEXUSClassifier, NEXUSRegressor
+
+__version__ = "0.1.4"
+
+_global_client: Optional[BaseClient] = None
+
+
+def set_client(client: BaseClient) -> None:
+    global _global_client
+    _global_client = client
+
+
+def get_client() -> BaseClient:
+    return _global_client or Fundamental()
+
+
+__all__ = [
+    "FTMClassifier",
+    "FTMRegressor",
+    "Fundamental",
+    "FundamentalEC2Client",
+    "NEXUSClassifier",
+    "NEXUSRegressor",
+    "get_client",
+    "set_client",
+]

fundamental/clients/__init__.py

@@ -0,0 +1,7 @@
+"""Client implementations for Fundamental API."""
+
+from fundamental.clients.base import BaseClient
+from fundamental.clients.ec2 import FundamentalEC2Client
+from fundamental.clients.fundamental import Fundamental
+
+__all__ = ["BaseClient", "Fundamental", "FundamentalEC2Client"]

fundamental/clients/base.py

@@ -0,0 +1,37 @@
+"""Base client for API interactions."""
+
+from abc import ABC
+from typing import TYPE_CHECKING, Dict, Optional
+
+from fundamental.config import Config
+
+if TYPE_CHECKING:
+    from fundamental.services.models import ModelsService
+
+
+class BaseClient(ABC):
+    """Abstract base client for API interactions.
+
+    All client implementations should inherit from this.
+    """
+
+    config: Config
+    models: "ModelsService"
+    _trace_dict: Optional[Dict[str, str]]
+
+    def __init__(self, *, config: Config) -> None:
+        """Initialize the base client with service properties."""
+        # Local import to avoid circular dependency at runtime
+        from fundamental.services.models import ModelsService
+
+        self.config = config
+        self.models = ModelsService(client=self)
+        self._trace_dict = None
+
+    def get_trace_dict(self) -> Optional[Dict[str, str]]:
+        """Get the current trace dictionary for workflow correlation."""
+        return self._trace_dict
+
+    def _set_trace_dict(self, trace_dict: Optional[Dict[str, str]]) -> None:
+        """Set the current trace dictionary (internal use only)."""
+        self._trace_dict = trace_dict

fundamental/clients/ec2.py

@@ -0,0 +1,37 @@
+"""Fundamental EC2 client for private deployment with AWS SigV4 authentication."""
+
+from typing import Any, Optional
+
+from fundamental.clients.base import BaseClient
+from fundamental.config import Config
+
+
+class FundamentalEC2Client(BaseClient):
+    """Client for Fundamental API on private EC2 deployments using AWS SigV4 authentication.
+
+    This client is pre-configured for private deployment mode where authentication
+    is done via AWS IAM roles instead of API keys. It uses SigV4 signing to
+    authenticate requests using the AWS credentials available in the environment.
+    """
+
+    def __init__(
+        self,
+        aws_region: str,
+        api_url: Optional[str] = None,
+        **kwargs: Any,  # noqa: ANN401
+    ):
+        """Initialize the Fundamental EC2 client.
+
+        Args:
+            aws_region: AWS region for SigV4 signing (required)
+            api_url: Base URL for the private deployment API server (API Gateway URL).
+                     Defaults to FUNDAMENTAL_API_URL environment variable if not provided.
+            **kwargs: Additional configuration options passed to Config
+        """
+        cfg = Config(
+            api_url=api_url or "",
+            use_sigv4_auth=True,
+            aws_region=aws_region,
+            **kwargs,
+        )
+        super().__init__(config=cfg)

fundamental/clients/fundamental.py

@@ -0,0 +1,20 @@
+"""Fundamental client implementation."""
+
+from typing import Any
+
+from fundamental.clients.base import BaseClient
+from fundamental.config import Config
+
+
+class Fundamental(BaseClient):
+    """Default client for Fundamental API interactions."""
+
+    def __init__(
+        self,
+        **kwargs: Any,  # noqa: ANN401
+    ):
+        """Initialize the Fundamental client."""
+        cfg = Config(
+            **kwargs,
+        )
+        super().__init__(config=cfg)

fundamental/config.py

@@ -0,0 +1,138 @@
+"""Configuration management for Fundamental SDK."""
+
+import os
+from dataclasses import dataclass
+from importlib.metadata import version
+from typing import Optional
+
+from fundamental.constants import (
+    API_URL,
+    COMPLETE_MULTIPART_UPLOAD_PATH,
+    DEFAULT_DOWNLOAD_RESULT_TIMEOUT_SECONDS,
+    DEFAULT_FEATURE_IMPORTANCE_TIMEOUT_SECONDS,
+    DEFAULT_FIT_TIMEOUT_SECONDS,
+    DEFAULT_PREDICT_TIMEOUT_SECONDS,
+    DEFAULT_RETRIES_COUNT,
+    DEFAULT_TIMEOUT_SECONDS,
+    FEATURE_IMPORTANCE_MODEL_METADATA_GENERATE_PATH,
+    FEATURE_IMPORTANCE_PATH,
+    FEATURE_IMPORTANCE_STATUS_PATH,
+    FIT_MODEL_METADATA_GENERATE_PATH,
+    FIT_PATH,
+    FIT_STATUS_PATH,
+    MODEL_MANAGEMENT_PATH,
+    PREDICT_MODEL_METADATA_GENERATE_PATH,
+    PREDICT_PATH,
+    PREDICT_STATUS_PATH,
+)
+
+
+@dataclass(frozen=True)
+class Config:
+    """Immutable configuration for Fundamental SDK.
+
+    Attributes:
+        api_key: API key for authentication (defaults to FUNDAMENTAL_API_KEY env var)
+        api_url: Base URL for the API (defaults to FUNDAMENTAL_API_URL env var or API_URL)
+        retries: Number of retries for failed requests
+        timeout: Default timeout in seconds
+        fit_timeout: Timeout for fit operations
+        predict_timeout: Timeout for predict operations
+        feature_importance_timeout: Timeout for feature importance operations
+        download_prediction_result_timeout: Timeout for downloading prediction results
+        download_feature_importance_result_timeout: Timeout for downloading feature
+            importance results
+        use_sigv4_auth: Use AWS SigV4 authentication instead of API key (for private deployment)
+        aws_region: AWS region for SigV4 signing (required when use_sigv4_auth=True)
+    """
+
+    api_key: str = ""
+    api_url: str = ""
+    retries: int = DEFAULT_RETRIES_COUNT
+    timeout: int = DEFAULT_TIMEOUT_SECONDS
+    fit_timeout: int = DEFAULT_FIT_TIMEOUT_SECONDS
+    predict_timeout: int = DEFAULT_PREDICT_TIMEOUT_SECONDS
+    feature_importance_timeout: int = DEFAULT_FEATURE_IMPORTANCE_TIMEOUT_SECONDS
+    download_prediction_result_timeout: int = DEFAULT_DOWNLOAD_RESULT_TIMEOUT_SECONDS
+    download_feature_importance_result_timeout: int = DEFAULT_DOWNLOAD_RESULT_TIMEOUT_SECONDS
+    use_sigv4_auth: bool = False
+    aws_region: str = ""
+
+    def __post_init__(self) -> None:
+        """Initialize config with environment variables if not provided."""
+        api_key: Optional[str] = self.api_key or os.getenv("FUNDAMENTAL_API_KEY")
+        object.__setattr__(self, "api_key", api_key)
+        url: str = self.api_url or os.getenv("FUNDAMENTAL_API_URL") or API_URL
+        object.__setattr__(self, "api_url", url)
+
+        if self.use_sigv4_auth:
+            # Validate AWS region is provided when using SigV4 auth
+            if not self.aws_region:
+                raise ValueError(
+                    "AWS region is required when using SigV4 authentication. "
+                    "Please provide it via aws_region parameter."
+                )
+        else:
+            # Validate API key when not using SigV4 auth
+            _ = self.get_api_key()  # quick fail on missing api keys
+
+    def get_api_key(self) -> str:
+        """Get the API key, raising an error if not set."""
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Please provide it via:\n"
+                "1. Fundamental(api_key='your-key')\n"
+                "2. Set FUNDAMENTAL_API_KEY environment variable"
+            )
+        return self.api_key
+
+    def get_full_fit_url(self) -> str:
+        """Get the complete URL for the fit endpoint."""
+        return f"{self.api_url.rstrip('/')}{FIT_PATH}"
+
+    def get_full_predict_url(self) -> str:
+        """Get the complete URL for the predict endpoint."""
+        return f"{self.api_url.rstrip('/')}{PREDICT_PATH}"
+
+    def get_full_model_management_url(self) -> str:
+        """Get the complete URL for the model management endpoint."""
+        return f"{self.api_url.rstrip('/')}{MODEL_MANAGEMENT_PATH}"
+
+    def get_full_fit_model_metadata_generate_url(self) -> str:
+        """Get the complete URL for the model metadata generation endpoint."""
+        return f"{self.api_url.rstrip('/')}{FIT_MODEL_METADATA_GENERATE_PATH}"
+
+    def get_full_predict_model_metadata_generate_url(self) -> str:
+        """Get the complete URL for the predict metadata generation endpoint."""
+        return f"{self.api_url.rstrip('/')}{PREDICT_MODEL_METADATA_GENERATE_PATH}"
+
+    def get_full_complete_multipart_upload_url(self) -> str:
+        """Get the complete URL for the complete multipart upload endpoint."""
+        return f"{self.api_url.rstrip('/')}{COMPLETE_MULTIPART_UPLOAD_PATH}"
+
+    def get_full_fit_status_url(self) -> str:
+        """Get the complete URL for the fit status endpoint."""
+        return f"{self.api_url.rstrip('/')}{FIT_STATUS_PATH}"
+
+    def get_full_predict_status_url(self) -> str:
+        """Get the complete URL for the predict status endpoint."""
+        return f"{self.api_url.rstrip('/')}{PREDICT_STATUS_PATH}"
+
+    def get_full_feature_importance_url(self) -> str:
+        """Get the complete URL for the feature importance endpoint."""
+        return f"{self.api_url.rstrip('/')}{FEATURE_IMPORTANCE_PATH}"
+
+    def get_full_feature_importance_status_url(self) -> str:
+        """Get the complete URL for the feature importance status endpoint."""
+        return f"{self.api_url.rstrip('/')}{FEATURE_IMPORTANCE_STATUS_PATH}"
+
+    def get_full_feature_importance_model_metadata_generate_url(self) -> str:
+        """Get the complete URL for the feature importance metadata generation endpoint."""
+        return f"{self.api_url.rstrip('/')}{FEATURE_IMPORTANCE_MODEL_METADATA_GENERATE_PATH}"
+
+    def get_version(self) -> str:
+        """Get the SDK version."""
+        try:
+            return version("fundamental")
+        except Exception:
+            return "unknown"

fundamental/constants.py

@@ -0,0 +1,41 @@
+API_URL = "https://api.fundamental.tech"
+FIT_PATH = "/api/v1/model/fit"
+PREDICT_PATH = "/api/v1/model/predict"
+FIT_STATUS_PATH = "/api/v1/model/fit/status"
+PREDICT_STATUS_PATH = "/api/v1/model/predict/status"
+FEATURE_IMPORTANCE_PATH = "/api/v1/model/feature-importance"
+FEATURE_IMPORTANCE_STATUS_PATH = "/api/v1/model/feature-importance/status"
+FEATURE_IMPORTANCE_MODEL_METADATA_GENERATE_PATH = "/api/v1/model/feature-importance/create-metadata"
+MODEL_MANAGEMENT_PATH = "/api/v1/model-management/trained-models"
+FIT_MODEL_METADATA_GENERATE_PATH = "/api/v1/model/fit/create-metadata"
+PREDICT_MODEL_METADATA_GENERATE_PATH = "/api/v1/model/predict/create-metadata"
+COMPLETE_MULTIPART_UPLOAD_PATH = "/api/v1/model/complete-multipart-upload"
+
+DEFAULT_TIMEOUT_SECONDS = 30
+DEFAULT_RETRIES_COUNT = 1
+
+# Shared default constants
+DEFAULT_POLLING_INTERVAL_SECONDS = 2
+DEFAULT_SUBMIT_REQUEST_TIMEOUT_SECONDS = 30
+DEFAULT_DOWNLOAD_RESULT_TIMEOUT_SECONDS = 60 * 60 * 3  # 3 hours
+DEFAULT_MODEL_METADATA_UPLOAD_TIMEOUT_SECONDS = 60 * 60 * 1  # 1 hour
+DEFAULT_COMPLETE_MULTIPART_UPLOAD_TIMEOUT_SECONDS = 30
+DEFAULT_MODEL_METADATA_GENERATE_TIMEOUT_SECONDS = 30
+
+# Predict-specific
+DEFAULT_PREDICT_POLLING_REQUESTS_WITHOUT_DELAY = 100
+DEFAULT_PREDICT_TIMEOUT_SECONDS = 60 * 60  # 1 hour
+
+# Feature importance-specific
+DEFAULT_FEATURE_IMPORTANCE_TIMEOUT_SECONDS = 60 * 60 * 24  # 24 hours
+
+# Fit-specific
+DEFAULT_FIT_TIMEOUT_SECONDS = 60 * 60 * 3  # 3 hours
+
+
+X_TRAIN_FILE_NAME = "x_train_file"
+Y_TRAIN_FILE_NAME = "y_train_file"
+X_TEST_FILE_NAME = "x_test_file"
+
+# EC2/SigV4 authentication
+SIGV4_SERVICE_NAME = "execute-api"

fundamental/deprecated.py

@@ -0,0 +1,43 @@
+"""
+Deprecated aliases for backward compatibility.
+
+This module contains deprecated estimator class aliases that will be removed in a future version.
+Estimator classes emit FutureWarning when instantiated.
+
+Note: FTMError alias is in fundamental.exceptions (not here) to avoid circular imports.
+
+TO REMOVE:
+1. Delete this file
+2. Remove imports from fundamental/__init__.py
+"""
+
+import warnings
+from typing import Literal
+
+from fundamental.estimator.classification import NEXUSClassifier
+from fundamental.estimator.regression import NEXUSRegressor
+
+
+def _deprecation_warning(old_name: str, new_name: str) -> None:
+    """Emit a FutureWarning for renamed classes."""
+    warnings.warn(
+        f"{old_name} is deprecated. Use {new_name} instead.",
+        FutureWarning,
+        stacklevel=3,
+    )
+
+
+class FTMClassifier(NEXUSClassifier):
+    """Deprecated: Use NEXUSClassifier instead."""
+
+    def __init__(self, mode: Literal["quality", "speed"] = "quality"):
+        _deprecation_warning("FTMClassifier", "NEXUSClassifier")
+        super().__init__(mode=mode)
+
+
+class FTMRegressor(NEXUSRegressor):
+    """Deprecated: Use NEXUSRegressor instead."""
+
+    def __init__(self, mode: Literal["quality", "speed"] = "quality"):
+        _deprecation_warning("FTMRegressor", "NEXUSRegressor")
+        super().__init__(mode=mode)

fundamental/estimator/__init__.py

@@ -0,0 +1,16 @@
+"""
+NEXUS Estimators Module
+
+This module provides scikit-learn compatible estimators for the NEXUS foundation
+model, organized by task type.
+
+Note: Deprecated FTMClassifier/FTMRegressor aliases are available from `fundamental` package.
+"""
+
+from fundamental.estimator.classification import NEXUSClassifier
+from fundamental.estimator.regression import NEXUSRegressor
+
+__all__ = [
+    "NEXUSClassifier",
+    "NEXUSRegressor",
+]

fundamental/estimator/base.py

@@ -0,0 +1,263 @@
+"""
+Base classes and model registry for NEXUS estimators.
+
+This module contains the ModelRegistry for managing available models and
+the abstract BaseNEXUSEstimator class that provides common functionality
+for both classification and regression tasks.
+"""
+
+import logging
+from abc import ABC
+from typing import Any, ClassVar, Literal, Optional
+
+import numpy.typing as npt
+from sklearn.base import BaseEstimator
+from sklearn.utils.validation import check_is_fitted
+from typing_extensions import Self
+
+import fundamental
+from fundamental.clients import BaseClient
+from fundamental.services import poll_fit_result, remote_fit, remote_predict, submit_fit_task
+from fundamental.services.models import ModelsService
+from fundamental.utils.data import (
+    XType,
+    YType,
+    check_n_features_compat,
+    validate_data,
+    validate_inputs_type,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BaseNEXUSEstimator(BaseEstimator, ABC):  # type: ignore[misc]
+    """
+    Abstract base class for NEXUS estimators.
+
+    Provides common functionality and interface for both classification
+    and regression estimators.
+    """
+
+    _task_type: ClassVar[Literal["classification", "regression"]]
+
+    def __init__(
+        self,
+        mode: Literal["quality", "speed"] = "quality",
+    ):
+        """Initialize the estimator.
+
+        Args:
+            mode: Training mode - "quality" for best performance, "speed" for faster training.
+        """
+        self.mode: Literal["quality", "speed"] = mode
+
+    def _get_client(self) -> BaseClient:
+        return fundamental.get_client()
+
+    def _set_n_features_in(self, X: XType) -> None:
+        """Set n_features_in_ attribute for sklearn compatibility.
+
+        Args:
+            X: Input features array or dataframe.
+        """
+        self.n_features_in_ = X.shape[1]
+
+    def load_model(self, trained_model_id: str) -> Self:
+        """
+        Load a trained model.
+        """
+        self._load_trained_model(trained_model_id)
+        self.fitted_ = True
+        return self
+
+    def fit(self, X: XType, y: YType) -> Self:
+        """
+        Fit the model to training data.
+
+        Parameters
+        ----------
+        X : XType
+            Training features as numpy array, pandas DataFrame.
+        y : YType
+            Training targets as numpy array, pandas Series.
+
+        Returns
+        -------
+        Self
+            Self for method chaining.
+        """
+        validate_inputs_type(X=X, y=y)
+        validate_data(X=X, y=y)
+
+        response = remote_fit(
+            X=X,
+            y=y,
+            task=type(self)._task_type,
+            mode=self.mode,
+            client=self._get_client(),
+        )
+        self._load_estimator_fields(response.estimator_fields)
+        self.trained_model_id_ = response.trained_model_id
+        self.fitted_ = True
+        self._set_n_features_in(X)
+        return self
+
+    def set_attributes(
+        self,
+        attributes: dict[str, str],
+    ) -> Self:
+        """
+        Set attributes on the fitted model.
+
+        Parameters
+        ----------
+        attributes : dict[str, str]
+            Dictionary of key-value pairs to set as model attributes.
+
+        Returns
+        -------
+        Self
+            Self for method chaining.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+
+        Examples
+        --------
+        >>> clf.set_attributes({"stage": "prod", "owner": "lital"})
+        """
+        check_is_fitted(self)
+        assert self.trained_model_id_ is not None
+
+        models_service = ModelsService(client=self._get_client())
+        models_service.set_attributes(
+            model_id=self.trained_model_id_,
+            attributes=attributes,
+        )
+        return self
+
+    def submit_fit_task(self, X: XType, y: YType) -> str:
+        """
+        Submit a fit task without waiting for completion.
+
+        Parameters
+        ----------
+        X : XType
+            Training features as numpy array, pandas DataFrame.
+        y : YType
+            Training targets as numpy array, pandas Series.
+
+        Returns
+        -------
+        str
+            Task ID for polling with poll_fit_result.
+        """
+        validate_inputs_type(X=X, y=y)
+        validate_data(X=X, y=y)
+        result = submit_fit_task(
+            X=X,
+            y=y,
+            task=type(self)._task_type,
+            mode=self.mode,
+            client=self._get_client(),
+        )
+        # Store for poll_fit_result to use
+        self._pending_trained_model_id = result.trained_model_id
+        self._pending_n_features_in = X.shape[1]
+        return result.task_id
+
+    def poll_fit_result(self, task_id: str) -> Optional[Self]:
+        """
+        Check fit task status and load model if complete.
+
+        Parameters
+        ----------
+        task_id : str
+            The task ID returned by submit_fit_task.
+
+        Returns
+        -------
+        Optional[Self]
+            Self if fitting completed (for method chaining), None if still in progress.
+        """
+        result = poll_fit_result(
+            task_id=task_id,
+            trained_model_id=self._pending_trained_model_id,
+            client=self._get_client(),
+        )
+        if result is not None:
+            self._load_estimator_fields(result.estimator_fields)
+            self.trained_model_id_ = result.trained_model_id
+            self.fitted_ = True
+            self.n_features_in_ = self._pending_n_features_in
+            # Clean up pending attributes
+            del self._pending_n_features_in
+            del self._pending_trained_model_id
+            return self
+        return None
+
+    def predict(self, X: XType) -> npt.NDArray[Any]:
+        """
+        Predict preds function.
+
+        Parameters
+        ----------
+        X : XType
+            Input features as numpy array, pandas DataFrame.
+
+
+        Returns
+        -------
+        np.ndarray
+            Model predictions.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+        """
+        return self._predict(X=X, output_type="preds")
+
+    def _predict(
+        self,
+        X: XType,
+        output_type: Literal["preds", "probas"],
+    ) -> npt.NDArray[Any]:
+        """Internal prediction method with configurable output type."""
+        validate_inputs_type(X=X)
+        validate_data(X=X)
+        check_is_fitted(self)
+
+        # Validate n_features_in_ for sklearn compatibility
+        check_n_features_compat(self, X, reset=False)
+
+        assert self.trained_model_id_ is not None
+        return remote_predict(
+            X=X,
+            output_type=output_type,
+            trained_model_id=self.trained_model_id_,
+            client=self._get_client(),
+        )
+
+    def _load_trained_model(self, model_id: str) -> None:
+        try:
+            models_service = ModelsService(client=self._get_client())
+            response = models_service.load(
+                trained_model_id=model_id,
+            )
+            self._load_estimator_fields(response.estimator_fields)
+            self.trained_model_id_ = model_id
+        except Exception as e:
+            logger.error(f"Failed to load model {model_id}: {e}")
+            raise e
+
+    def _load_estimator_fields(self, estimator_fields: dict[str, Any]) -> None:
+        for field, value in estimator_fields.items():
+            try:
+                # Keep private attrs as-is, add underscore to public attrs (sklearn convention)
+                field_name = field if field.endswith("_") or field.startswith("_") else f"{field}_"
+                setattr(self, field_name, value)
+            except AttributeError:
+                logger.warning(f"Field {field} is not a valid attribute in the current estimator")

fundamental/estimator/classification.py

@@ -0,0 +1,46 @@
+"""NEXUS Classification estimator."""
+
+import logging
+from typing import Any, Literal
+
+import numpy.typing as npt
+from sklearn.base import ClassifierMixin
+
+from fundamental.estimator.nexus_estimator import NEXUSEstimator
+from fundamental.utils.data import XType
+
+logger = logging.getLogger(__name__)
+
+
+class NEXUSClassifier(ClassifierMixin, NEXUSEstimator):
+    """NEXUS Model for Classification Tasks."""
+
+    _task_type = "classification"  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        mode: Literal["quality", "speed"] = "quality",
+    ):
+        super().__init__(mode=mode)
+
+    def predict_proba(self, X: XType) -> npt.NDArray[Any]:
+        """
+        Predict probabilities function.
+
+        Parameters
+        ----------
+        X : XType
+            Input features as numpy array, pandas DataFrame.
+
+
+        Returns
+        -------
+        np.ndarray
+            Model probabilities.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+        """
+        return self._predict(X=X, output_type="probas")