fundamental-client 0.2.3__py3-none-any.whl

fundamental/estimator/nexus_estimator.py

@@ -0,0 +1,120 @@
+"""
+NEXUS Estimator with public API methods.
+
+This module contains NEXUSEstimator which extends BaseNEXUSEstimator with public API methods.
+"""
+
+from abc import ABC
+from typing import Optional
+
+import numpy as np
+from sklearn.utils.validation import check_is_fitted
+
+from fundamental.estimator.base import BaseNEXUSEstimator
+from fundamental.services import remote_get_feature_importance
+from fundamental.services.feature_importance import (
+    poll_feature_importance_result,
+    submit_feature_importance_task,
+)
+from fundamental.utils.data import XType, validate_data, validate_inputs_type
+
+
+class NEXUSEstimator(BaseNEXUSEstimator, ABC):
+    """
+    NEXUS Estimator with public API methods.
+
+    Extends BaseNEXUSEstimator with advanced operations.
+    """
+
+    def get_feature_importance(
+        self,
+        X: XType,
+    ) -> np.ndarray:
+        """
+        Get feature importance for the fitted model.
+
+        Submits the task and waits for completion.
+
+        Parameters
+        ----------
+        X : XType
+            Input features for feature importance computation.
+
+        Returns
+        -------
+        np.ndarray
+            Feature importance values.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+        """
+        validate_inputs_type(X=X)
+        validate_data(X=X)
+        check_is_fitted(self)
+        assert self.trained_model_id_ is not None
+        return remote_get_feature_importance(
+            X=X,
+            trained_model_id=self.trained_model_id_,
+            client=self._get_client(),
+        )
+
+    def submit_feature_importance_task(
+        self,
+        X: XType,
+    ) -> str:
+        """
+        Submit a feature importance computation task without waiting for completion.
+
+        Parameters
+        ----------
+        X : XType
+            Input features for feature importance computation.
+
+        Returns
+        -------
+        str
+            The task ID to use with poll_feature_importance_result.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+        """
+        validate_inputs_type(X=X)
+        validate_data(X=X)
+        check_is_fitted(self)
+        assert self.trained_model_id_ is not None
+        return submit_feature_importance_task(
+            X=X,
+            trained_model_id=self.trained_model_id_,
+            client=self._get_client(),
+        )
+
+    def poll_feature_importance_result(self, task_id: str) -> Optional[np.ndarray]:
+        """
+        Check the status of a feature importance task.
+
+        Parameters
+        ----------
+        task_id : str
+            The task ID returned by submit_feature_importance_task.
+
+        Returns
+        -------
+        Optional[np.ndarray]
+            Feature importance values if completed, None if still in progress.
+
+        Raises
+        ------
+        NotFittedError
+            If the model has not been fitted yet.
+        """
+        check_is_fitted(self)
+        assert self.trained_model_id_ is not None
+        return poll_feature_importance_result(
+            task_id=task_id,
+            trained_model_id=self.trained_model_id_,
+            client=self._get_client(),
+        )

fundamental/estimator/regression.py

@@ -0,0 +1,22 @@
+"""NEXUS Regression estimator."""
+
+import logging
+from typing import Literal
+
+from sklearn.base import RegressorMixin
+
+from fundamental.estimator.nexus_estimator import NEXUSEstimator
+
+logger = logging.getLogger(__name__)
+
+
+class NEXUSRegressor(RegressorMixin, NEXUSEstimator):
+    """NEXUS Model for Regression Tasks."""
+
+    _task_type = "regression"  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        mode: Literal["quality", "speed"] = "quality",
+    ):
+        super().__init__(mode=mode)

fundamental/exceptions.py

@@ -0,0 +1,78 @@
+"""Custom exceptions for NEXUS Client SDK."""
+
+from typing import Any, Dict, Literal, Optional
+
+
+class NEXUSError(Exception):
+    """Base exception for all NEXUS client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        details: Optional[Dict[str, Any]] = None,
+        trace_id: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.details = details or {}
+        self.trace_id = trace_id
+
+
+class HTTPError(NEXUSError):
+    """Base class for HTTP errors with status codes."""
+
+    status_code: int
+
+    def __str__(self) -> str:
+        return f"HTTP {self.status_code}: {super().__str__()}"
+
+
+class ValidationError(HTTPError):
+    """Raised when input validation fails."""
+
+    status_code: Literal[400] = 400  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class AuthenticationError(HTTPError):
+    """Raised when authentication fails."""
+
+    status_code: Literal[401] = 401  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class AuthorizationError(HTTPError):
+    """Raised when authorization fails."""
+
+    status_code: Literal[403] = 403  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class NotFoundError(HTTPError):
+    """Raised when resource is not found."""
+
+    status_code: Literal[404] = 404  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class RateLimitError(HTTPError):
+    """Raised when API rate limits are exceeded."""
+
+    status_code: Literal[429] = 429  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class ServerError(HTTPError):
+    """Raised when server returns 5xx errors."""
+
+    status_code: int = 500
+
+
+class NetworkError(HTTPError):
+    """Raised when network connectivity issues occur."""
+
+    status_code: Literal[503] = 503  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class RequestTimeoutError(HTTPError):
+    """Raised when requests timeout."""
+
+    status_code: Literal[504] = 504  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+# Deprecated alias for backward compatibility
+FTMError = NEXUSError

fundamental/models/__init__.py

@@ -0,0 +1,4 @@
+# Auto-generated Pydantic models from OpenAPI spec
+# Run `scripts/generate-models` to regenerate
+
+from fundamental.models.generated import *  # noqa: F403

fundamental/models/generated.py

@@ -0,0 +1,431 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+#   timestamp: 2026-01-21T12:25:52+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import AwareDatetime, BaseModel, Field, RootModel
+
+
+class BYOBSettings(BaseModel):
+    enabled: bool = Field(..., description="Whether BYOB is enabled", title="Enabled")
+    role_arn: str | None = Field(
+        default=None, description="AWS IAM role ARN for assuming role", title="Role Arn"
+    )
+    external_id: str | None = Field(
+        default=None, description="External ID for role assumption", title="External Id"
+    )
+    data_bucket_name: str | None = Field(
+        default=None,
+        description="S3 bucket name for temporary data",
+        title="Data Bucket Name",
+    )
+    model_bucket_name: str | None = Field(
+        default=None,
+        description="S3 bucket name for trained models",
+        title="Model Bucket Name",
+    )
+
+
+class BaseModelResultWithEvalMetric(BaseModel):
+    name: str = Field(..., description="Name of the model", title="Name")
+    type: str = Field(..., description="Type of model (internal or external)", title="Type")
+    success: bool = Field(
+        ..., description="Whether the model execution was successful", title="Success"
+    )
+    eval_metric: float | None = Field(
+        default=None, description="Model evaluation metric value", title="Eval Metric"
+    )
+
+
+class BodyFitPredictApiV1ModelFitPredictPost(BaseModel):
+    task: str = Field(..., description="Task type: 'classification' or 'regression'", title="Task")
+    target_column: str = Field(
+        ...,
+        description="Name of the target column in both train and test datasets",
+        title="Target Column",
+    )
+    train_dataset: bytes = Field(
+        ...,
+        description="Training dataset CSV file containing features and target",
+        title="Train Dataset",
+    )
+    test_dataset: bytes = Field(
+        ...,
+        description="Test dataset CSV file containing features and target",
+        title="Test Dataset",
+    )
+
+
+class CompleteMultipartUploadPart(BaseModel):
+    PartNumber: int = Field(..., description="Part number (1-indexed)", title="Partnumber")
+    ETag: str = Field(..., description="ETag from part upload response", title="Etag")
+
+
+class FileType(Enum):
+    X_TRAIN = "x_train"
+    Y_TRAIN = "y_train"
+    X_TEST = "x_test"
+    X_FEATURE_IMPORTANCE = "x_feature_importance"
+    Y_FEATURE_IMPORTANCE = "y_feature_importance"
+
+
+class CompleteMultipartUploadRequest(BaseModel):
+    trained_model_id: str = Field(..., description="Trained model ID", title="Trained Model Id")
+    file_type: FileType = Field(..., description="Type of file being uploaded", title="File Type")
+    upload_id: str = Field(..., description="Multipart upload ID", title="Upload Id")
+    parts: list[CompleteMultipartUploadPart] = Field(
+        ..., description="List of uploaded parts with their ETags", title="Parts"
+    )
+    request_id: str | None = Field(
+        default=None,
+        description="Request ID (required for x_test, x_feature_importance, and y_feature_importance uploads)",
+        title="Request Id",
+    )
+
+
+class CompleteMultipartUploadResponse(BaseModel):
+    message: str = Field(..., description="Success message", title="Message")
+    object_key: str = Field(
+        ..., description="S3 object key of the completed upload", title="Object Key"
+    )
+
+
+class CreateAPIKeyRequest(BaseModel):
+    key_name: str = Field(
+        ...,
+        description="Human-readable name for the API key",
+        max_length=100,
+        min_length=1,
+        title="Key Name",
+    )
+
+
+class CreateAPIKeyResponse(BaseModel):
+    message: str = Field(..., description="Success message", title="Message")
+    api_key: str = Field(..., description="Generated API key", title="Api Key")
+    key_name: str = Field(..., description="Name of the API key", title="Key Name")
+    organization_id: str = Field(..., description="Organization ID", title="Organization Id")
+    expires_at: AwareDatetime | None = Field(
+        default=None, description="API key expiration time", title="Expires At"
+    )
+    created_at: AwareDatetime = Field(..., description="API key creation time", title="Created At")
+    creator: str = Field(..., description="User ID who created this API key", title="Creator")
+
+
+class DailyUsage(BaseModel):
+    date: str = Field(..., description="Date in YYYY-MM-DD format", title="Date")
+    usage_count: int = Field(
+        ...,
+        description="Total usage count (predict + fit-predict)",
+        title="Usage Count",
+    )
+
+
+class DeleteTrainedModelResponse(BaseModel):
+    message: str = Field(..., description="Success message", title="Message")
+    trained_model_id: str = Field(
+        ..., description="Deleted trained model ID", title="Trained Model Id"
+    )
+    user_id: str = Field(..., description="User ID", title="User Id")
+
+
+class FeatureImportanceMultipartMetadataRequest(BaseModel):
+    trained_model_id: str = Field(
+        ..., description="Trained model ID from training", title="Trained Model Id"
+    )
+    x_size: int = Field(..., description="Size of X data file in bytes", gt=0, title="X Size")
+
+
+class FeatureImportanceRequest(BaseModel):
+    trained_model_id: str = Field(..., description="Trained model ID", title="Trained Model Id")
+    request_id: str = Field(
+        ..., description="Request ID from metadata generation", title="Request Id"
+    )
+
+
+class FeatureImportanceResponse(BaseModel):
+    task_id: str = Field(
+        ..., description="Task ID for the feature importance request", title="Task Id"
+    )
+
+
+class FitMultipartMetadataRequest(BaseModel):
+    x_train_size: int = Field(
+        ..., description="Size of x_train file in bytes", gt=0, title="X Train Size"
+    )
+    y_train_size: int = Field(
+        ..., description="Size of y_train file in bytes", gt=0, title="Y Train Size"
+    )
+
+
+class FitPredictResponse(BaseModel):
+    metric_name: str = Field(
+        ..., description="Name of the evaluation metric used", title="Metric Name"
+    )
+    csv_data: str = Field(
+        ..., description="Base64-encoded CSV data with predictions", title="Csv Data"
+    )
+    csv_filename: str = Field(
+        ..., description="Filename for the CSV download", title="Csv Filename"
+    )
+    models: list[BaseModelResultWithEvalMetric] = Field(
+        ..., description="List of model results", title="Models"
+    )
+
+
+class Task(Enum):
+    CLASSIFICATION = "classification"
+    REGRESSION = "regression"
+
+
+class Mode(Enum):
+    QUALITY = "quality"
+    SPEED = "speed"
+
+
+class Timeout(RootModel[int]):
+    root: int = Field(..., description="Time limit in seconds", gt=0, title="Timeout")
+
+
+class FitRequest(BaseModel):
+    trained_model_id: str = Field(
+        ...,
+        description="Trained model ID from metadata generation",
+        title="Trained Model Id",
+    )
+    task: Task = Field(..., description="Task type for the model", title="Task")
+    mode: Mode | None = Field(
+        default=None, description="Training mode: 'quality' or 'speed'", title="Mode"
+    )
+    timeout: Timeout | None = Field(
+        default=None, description="Time limit in seconds", title="Timeout"
+    )
+
+
+class FitResponse(BaseModel):
+    trained_model_id: str = Field(
+        ...,
+        description="Trained model ID for this fitted model",
+        title="Trained Model Id",
+    )
+    task_id: str = Field(..., description="task id", title="Task Id")
+    status_code: int = Field(..., description="HTTP status code", title="Status Code")
+    error_codes: list[str] | None = Field(
+        default=[], description="List of error codes if any", title="Error Codes"
+    )
+
+
+class MaskedApiKeyInfo(BaseModel):
+    key_name: str = Field(..., description="Human-readable name for the API key", title="Key Name")
+    api_key_suffix: str = Field(
+        ..., description="Last 4 characters of the API key", title="Api Key Suffix"
+    )
+    api_key_hash: str = Field(..., description="Hash of the API key", title="Api Key Hash")
+    organization_id: str = Field(
+        ..., description="Associated organization ID", title="Organization Id"
+    )
+    created_at: AwareDatetime = Field(..., description="Creation timestamp", title="Created At")
+    expires_at: AwareDatetime | None = Field(
+        default=None, description="Expiration timestamp", title="Expires At"
+    )
+    creator: str = Field(..., description="User ID who created this API key", title="Creator")
+
+
+class MultipartUploadInfo(BaseModel):
+    upload_id: str = Field(..., description="S3 multipart upload ID", title="Upload Id")
+    upload_urls: list[str] = Field(
+        ..., description="List of presigned URLs for each part", title="Upload Urls"
+    )
+    num_parts: int = Field(..., description="Number of parts to upload", title="Num Parts")
+    part_size: int = Field(..., description="Size of each part in bytes", title="Part Size")
+
+
+class OrganizationSettings(BaseModel):
+    bring_your_own_bucket: BYOBSettings | None = Field(
+        default=None, description="Bring Your Own Bucket settings"
+    )
+
+
+class PredictMultipartMetadataRequest(BaseModel):
+    trained_model_id: str = Field(
+        ..., description="Trained model ID from training", title="Trained Model Id"
+    )
+    x_test_size: int = Field(
+        ..., description="Size of x_test file in bytes", gt=0, title="X Test Size"
+    )
+
+
+class PredictMultipartMetadataResponse(BaseModel):
+    request_id: str = Field(
+        ..., description="Request ID for tracking the upload", title="Request Id"
+    )
+    part_size: int = Field(..., description="Size of each part in bytes", title="Part Size")
+    upload_id: str = Field(..., description="S3 multipart upload ID", title="Upload Id")
+    upload_urls: list[str] = Field(
+        ..., description="List of presigned URLs for each part", title="Upload Urls"
+    )
+    num_parts: int = Field(..., description="Number of parts to upload", title="Num Parts")
+    trace_id: str = Field(
+        ..., description="Root trace ID for the predict operation", title="Trace Id"
+    )
+    span_id: str = Field(..., description="Span ID for the predict operation", title="Span Id")
+
+
+class PredictRequest(BaseModel):
+    trained_model_id: str = Field(
+        ..., description="Trained model ID from training", title="Trained Model Id"
+    )
+    request_id: str = Field(
+        ..., description="Request ID from metadata generation", title="Request Id"
+    )
+    output_type: str | None = Field(
+        default="preds",
+        description="Output type: 'preds' or 'probas'",
+        title="Output Type",
+    )
+    timeout: Timeout | None = Field(
+        default=None, description="Time limit in seconds", title="Timeout"
+    )
+
+
+class PredictResponse(BaseModel):
+    request_id: str = Field(
+        ..., description="Request ID for the prediction request", title="Request Id"
+    )
+    task_id: str = Field(..., description="Task ID for the prediction request", title="Task Id")
+
+
+class RevokeAPIKeyRequest(BaseModel):
+    api_key_hash: str = Field(
+        ..., description="Hash of the API key to revoke", title="Api Key Hash"
+    )
+
+
+class RevokeAPIKeyResponse(BaseModel):
+    message: str = Field(..., description="Success message", title="Message")
+    organization_id: str = Field(..., description="Organization ID", title="Organization Id")
+    status: str = Field(..., description="Revocation status", title="Status")
+
+
+class TaskResult(BaseModel):
+    download_url: str = Field(
+        ..., description="Presigned URL to download task results", title="Download Url"
+    )
+
+
+class TaskStatus(Enum):
+    SUCCESS = "success"
+    IN_PROGRESS = "in_progress"
+    VALIDATION_ERROR = "validation_error"
+
+
+class TaskStatusResponse(BaseModel):
+    status: TaskStatus = Field(..., description="Task state (in_progress, success)")
+    result: TaskResult | None = Field(
+        default=None,
+        description="Task result with download URL when successful, None otherwise",
+    )
+
+
+class TrainedModelFields(BaseModel):
+    estimator_fields: bytes = Field(
+        ..., description="Trained model fields file", title="Estimator Fields"
+    )
+
+
+class TrainedModelListResponse(RootModel[list[str]]):
+    root: list[str] = Field(
+        ...,
+        description="Model that returns just a list directly, no wrapper key.",
+        examples=[["user_123_model_abc", "user_123_model_def"]],
+        title="TrainedModelListResponse",
+    )
+
+
+class TrainedModelMetadata(BaseModel):
+    trained_model_id: str = Field(..., description="Trained model ID", title="Trained Model Id")
+    attributes: dict[str, str] = Field(
+        default_factory=dict,
+        description="Structured key/value labels for organization",
+        title="Attributes",
+    )
+
+
+class UpdateAttributesRequest(BaseModel):
+    attributes: dict[str, str] = Field(
+        ...,
+        description="Structured key/value labels for organization (max 20 pairs)",
+        title="Attributes",
+    )
+
+
+class UpdateAttributesResponse(BaseModel):
+    attributes: dict[str, str] = Field(..., description="Updated attributes", title="Attributes")
+
+
+class UpdateSettingsRequest(BaseModel):
+    settings: OrganizationSettings = Field(..., description="Organization settings to update")
+
+
+class UpdateSettingsResponse(BaseModel):
+    message: str = Field(..., description="Success message", title="Message")
+    organization_id: str = Field(..., description="Organization ID", title="Organization Id")
+
+
+class ValidationError(BaseModel):
+    loc: list[str | int] = Field(..., title="Location")
+    msg: str = Field(..., title="Message")
+    type: str = Field(..., title="Error Type")
+
+
+class AnalyticsResponse(BaseModel):
+    week_start: str = Field(
+        ..., description="Week start date in YYYY-MM-DD format", title="Week Start"
+    )
+    daily_usage: list[DailyUsage] = Field(
+        ..., description="Daily usage breakdown for 7 days", title="Daily Usage"
+    )
+
+
+class FeatureImportanceMultipartMetadataResponse(BaseModel):
+    request_id: str = Field(
+        ..., description="Request ID for tracking the upload", title="Request Id"
+    )
+    x_upload: MultipartUploadInfo = Field(..., description="X data multipart upload info")
+    trace_id: str = Field(
+        ...,
+        description="Root trace ID for the feature importance operation",
+        title="Trace Id",
+    )
+    span_id: str = Field(
+        ..., description="Span ID for the feature importance operation", title="Span Id"
+    )
+
+
+class FitMultipartMetadataResponse(BaseModel):
+    trained_model_id: str = Field(
+        ..., description="Generated trained model ID", title="Trained Model Id"
+    )
+    x_train_upload: MultipartUploadInfo = Field(..., description="X train multipart upload info")
+    y_train_upload: MultipartUploadInfo = Field(..., description="Y train multipart upload info")
+    trace_id: str = Field(..., description="Root trace ID for the fit operation", title="Trace Id")
+    span_id: str = Field(..., description="Span ID for the fit operation", title="Span Id")
+
+
+class GetSettingsResponse(BaseModel):
+    organization_id: str = Field(..., description="Organization ID", title="Organization Id")
+    settings: OrganizationSettings = Field(..., description="Organization settings")
+
+
+class HTTPValidationError(BaseModel):
+    detail: list[ValidationError] | None = Field(default=None, title="Detail")
+
+
+class ListAPIKeysResponse(BaseModel):
+    organization_id: str = Field(..., description="Organization ID", title="Organization Id")
+    organization_name: str = Field(..., description="Organization name", title="Organization Name")
+    api_keys: list[MaskedApiKeyInfo] = Field(..., description="List of API keys", title="Api Keys")
+    total_count: int = Field(..., description="Total number of API keys", title="Total Count")

fundamental/services/__init__.py

@@ -0,0 +1,25 @@
+"""Services package for NEXUS client."""
+
+from fundamental.services.feature_importance import (
+    poll_feature_importance_result,
+    remote_get_feature_importance,
+    submit_feature_importance_task,
+)
+from fundamental.services.inference import (
+    poll_fit_result,
+    remote_fit,
+    remote_predict,
+    submit_fit_task,
+)
+from fundamental.services.models import ModelsService
+
+__all__ = [
+    "ModelsService",
+    "poll_feature_importance_result",
+    "poll_fit_result",
+    "remote_fit",
+    "remote_get_feature_importance",
+    "remote_predict",
+    "submit_feature_importance_task",
+    "submit_fit_task",
+]