fundamental-client 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

fundamental/__init__.py

@@ -1,14 +1,19 @@
 """Fundamental Python SDK for tabular machine learning."""
 
+from importlib.metadata import PackageNotFoundError, version
 from typing import Optional
 
-from fundamental.clients import BaseClient, Fundamental, FundamentalEC2Client
+from fundamental.clients import BaseClient, Fundamental, FundamentalAWSMarketplaceClient
 
 # Deprecated aliases
 from fundamental.deprecated import FTMClassifier, FTMRegressor
 from fundamental.estimator import NEXUSClassifier, NEXUSRegressor
 
-__version__ = "0.1.4"
+try:
+    # Distribution name on PyPI is `fundamental-client` (import name is `fundamental`).
+    __version__ = version("fundamental-client")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
 
 _global_client: Optional[BaseClient] = None
 
@@ -26,7 +31,7 @@ __all__ = [
     "FTMClassifier",
     "FTMRegressor",
     "Fundamental",
-    "FundamentalEC2Client",
+    "FundamentalAWSMarketplaceClient",
     "NEXUSClassifier",
     "NEXUSRegressor",
     "get_client",

fundamental/clients/__init__.py

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

fundamental/clients/{ec2.py → aws_marketplace.py}

@@ -1,4 +1,4 @@
-"""Fundamental EC2 client for private deployment with AWS SigV4 authentication."""
+"""Fundamental AWS Marketplace client with AWS SigV4 authentication."""
 
 from typing import Any, Optional
 
@@ -6,10 +6,10 @@ 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.
+class FundamentalAWSMarketplaceClient(BaseClient):
+    """Client for Fundamental API on AWS Marketplace deployments using AWS SigV4 authentication.
 
-    This client is pre-configured for private deployment mode where authentication
+    This client is designed for AWS Marketplace deployments 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.
     """
@@ -20,7 +20,7 @@ class FundamentalEC2Client(BaseClient):
         api_url: Optional[str] = None,
         **kwargs: Any,  # noqa: ANN401
     ):
-        """Initialize the Fundamental EC2 client.
+        """Initialize the Fundamental AWS Marketplace client.
 
         Args:
             aws_region: AWS region for SigV4 signing (required)

fundamental/config.py

@@ -2,7 +2,7 @@
 
 import os
 from dataclasses import dataclass
-from importlib.metadata import version
+from importlib.metadata import PackageNotFoundError, version
 from typing import Optional
 
 from fundamental.constants import (
@@ -133,6 +133,6 @@ class Config:
     def get_version(self) -> str:
         """Get the SDK version."""
         try:
-            return version("fundamental")
-        except Exception:
+            return version("fundamental-client")
+        except PackageNotFoundError:
             return "unknown"

fundamental/constants.py

@@ -37,5 +37,5 @@ X_TRAIN_FILE_NAME = "x_train_file"
 Y_TRAIN_FILE_NAME = "y_train_file"
 X_TEST_FILE_NAME = "x_test_file"
 
-# EC2/SigV4 authentication
+# AWS Marketplace/SigV4 authentication
 SIGV4_SERVICE_NAME = "execute-api"

fundamental/utils/http.py

@@ -40,9 +40,9 @@ def _sign_request_sigv4(
         from botocore.awsrequest import AWSRequest  # pyright: ignore[reportMissingImports]
     except ImportError as e:
         raise ImportError(
-            "boto3 is required for EC2/SigV4 authentication. "
-            'Install it with: pip install "fundamental-client[ec2]" '
-            'or: uv add "fundamental-client[ec2]"'
+            "boto3 is required for AWS Marketplace/SigV4 authentication."
+            'Install it with: pip install "fundamental-client[aws-marketplace]" '
+            'or: uv add "fundamental-client[aws-marketplace]"'
         ) from e
 
     session = boto3.Session()

{fundamental_client-0.2.3.dist-info → fundamental_client-0.2.5.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: fundamental-client
-Version: 0.2.3
+Version: 0.2.5
 Summary: Scikit-learn–compatible client SDK for NEXUS, Fundamental's large model for tabular data
-Project-URL: documentation, https://fundamental.tech/docs
+Project-URL: documentation, https://launch.fundamental.tech/docs/guides/sdk/user-guide
 Author-email: Fundamental Tech <support@fundamental.tech>
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -225,6 +225,8 @@ Requires-Dist: pyarrow>=19.0.0
 Requires-Dist: pydantic<3.0.0,>=2.10.0
 Requires-Dist: safetensors>=0.5.0
 Requires-Dist: scikit-learn<2.0.0,>=1.5.0
+Provides-Extra: aws-marketplace
+Requires-Dist: boto3>=1.34.0; extra == 'aws-marketplace'
 Provides-Extra: dev
 Requires-Dist: datamodel-code-generator[http]>=0.26.0; extra == 'dev'
 Requires-Dist: minimum-dependencies; extra == 'dev'
@@ -237,5 +239,422 @@ Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
 Requires-Dist: pytest>=8.4.2; extra == 'dev'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.13.1; extra == 'dev'
-Provides-Extra: ec2
-Requires-Dist: boto3>=1.34.0; extra == 'ec2'
+Description-Content-Type: text/markdown
+
+# Fundamental Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/fundamental-client.svg?label=pypi%20package)](https://pypi.org/project/fundamental-client/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/fundamental-client?color=%2334D058)](https://pypi.org/project/fundamental-client)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+A scikit-learn compatible Python SDK for NEXUS, Fundamental's large model for tabular data.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Quick Start](#quick-start)
+  - [Using Pre-trained Models](#using-pre-trained-models)
+  - [Async Training](#async-training)
+  - [Model Management](#model-management)
+  - [Explainability & Insights](#explainability--insights)
+    - [Feature Importance](#feature-importance)
+- [Configuration](#configuration)
+  - [Client Configuration](#client-configuration)
+    - [API Key](#api-key)
+    - [AWS Marketplace](#aws-marketplace)
+    - [Timeouts and Retries](#timeouts-and-retries)
+  - [Model Configuration](#model-configuration)
+    - [Mode](#mode)
+- [Supported Data Types](#supported-data-types)
+- [Handling Errors](#handling-errors)
+  - [Diagnostics and Support Information](#diagnostics-and-support-information)
+  - [Exception Types](#exception-types)
+- [Troubleshooting](#troubleshooting)
+- [Versioning](#versioning)
+- [Requirements](#requirements)
+- [License](#license)
+- [Security](#security)
+- [Support](#support)
+
+## Installation
+
+```sh
+# install from PyPI
+pip install fundamental-client
+```
+
+## Usage
+
+The Fundamental SDK provides scikit-learn compatible estimators for classification and regression tasks, along with a flexible client for API interactions.
+
+
+### Quick Start
+
+Make sure `FUNDAMENTAL_API_KEY` is set (or call `fundamental.set_client(...)`) before running the examples below.
+
+```python
+from sklearn.datasets import load_breast_cancer, load_diabetes
+from sklearn.model_selection import train_test_split
+from fundamental import NEXUSClassifier, NEXUSRegressor
+
+# Load classification data
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5, random_state=42)
+
+# Classification
+classifier = NEXUSClassifier()
+classifier.fit(X_train, y_train)
+
+# After fitting, the model ID can be saved and used later
+print(f"Trained model ID: {classifier.trained_model_id_}")
+
+predictions = classifier.predict(X_test)
+probabilities = classifier.predict_proba(X_test)
+
+# Load regression data
+X, y = load_diabetes(return_X_y=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.5, random_state=42)
+
+# Regression
+regressor = NEXUSRegressor()
+regressor.fit(X_train, y_train)
+predictions = regressor.predict(X_test)
+```
+
+### Using Pre-trained Models
+
+If you have a trained model from a previous session, you can use it directly without retraining:
+
+```python
+from fundamental import NEXUSClassifier, NEXUSRegressor
+
+classifier = NEXUSClassifier().load_model(trained_model_id="model_abc123")
+predictions = classifier.predict(X_test)
+probabilities = classifier.predict_proba(X_test)
+
+regressor = NEXUSRegressor().load_model(trained_model_id="model_def456")
+predictions = regressor.predict(X_test)
+```
+
+### Async Training
+
+Model training is often a long-running operation. To support non-blocking workflows, you can submit training via `submit_fit_task()` and poll for completion. Once submitted, the training job runs in the background and its status can be queried at any time.
+
+```python
+from fundamental import NEXUSClassifier
+import time
+
+classifier = NEXUSClassifier()
+
+# Submit training task without waiting
+task_id = classifier.submit_fit_task(X_train, y_train)
+print(f"Training task submitted: {task_id}")
+
+# Poll status periodically
+result = None
+while result is None:
+    result = classifier.poll_fit_result(task_id)
+    if result is None:
+        print("Training in progress...")
+        time.sleep(10)  # Wait before polling again
+
+# Model is now fitted and ready for predictions
+predictions = classifier.predict(X_test)
+```
+
+### Model Management
+
+The client provides methods for managing your trained models:
+
+```python
+from fundamental import Fundamental
+
+# Create a client
+client = Fundamental()
+
+# List all available models
+models = client.models.list()
+print(f"Available models: {models}")
+
+# Get information about a specific model
+model_info = client.models.get("model_id_123")
+print(f"Model info: {model_info}")
+print(f"Attributes: {model_info.attributes}")
+
+# Delete a model
+client.models.delete("model_id_123")
+```
+
+#### Model Attributes
+
+You can set attributes on your models to help organize and identify them.
+We recommend always setting a `name` attribute; if omitted, the name will default to
+`<model_version> [id:<model_id_suffix>]`.
+
+```python
+# Set attributes directly on a fitted model
+classifier.set_attributes({"name": "Breast Cancer Classifier", "stage": "prod"})
+
+# Or using the client
+client.models.set_attributes(
+    "model_id_123",
+    attributes={"name": "Breast Cancer Classifier", "description": "Production model v1"}
+)
+```
+
+### Explainability & Insights
+
+#### Feature Importance
+
+After fitting a model, you can compute feature importance to quantify the contribution of each input feature to the model's output:
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from fundamental import NEXUSClassifier
+
+
+# Load data
+X, y = load_breast_cancer(return_X_y=True)
+X_train, X_val, y_train, y_val = train_test_split(X, y, test_size=0.5, random_state=42)
+# Fit the model
+classifier = NEXUSClassifier()
+classifier.fit(X_train, y_train)
+# Get feature importance (waits for computation to complete)
+feature_importance = classifier.get_feature_importance(X_val)
+print(f"Feature importance: {feature_importance}")
+```
+
+Feature importance computation can take a significant amount of time. If you prefer to submit the task and check its status periodically, you can use the asynchronous approach:
+
+```python
+# Submit task without waiting
+task_id = classifier.submit_feature_importance_task(X_val)
+
+# Poll status later
+result = classifier.poll_feature_importance_result(task_id)
+if result is not None:
+    print(f"Feature importance: {result}")
+```
+
+## Configuration
+
+### Client Configuration
+
+Configure the SDK client through environment variables or programmatically.
+
+#### API Key
+
+You can provide your API key in two ways:
+
+```python
+# 1. Programmatic
+import fundamental
+from fundamental import Fundamental, NEXUSClassifier
+
+fundamental.set_client(Fundamental(api_key="your_api_key_here"))
+classifier = NEXUSClassifier()
+```
+
+```bash
+# 2. Environment variable
+export FUNDAMENTAL_API_KEY="your_api_key_here"
+```
+
+#### AWS Marketplace
+
+For AWS Marketplace deployments, use the `FundamentalAWSMarketplaceClient` which authenticates using AWS IAM roles via SigV4 signing instead of API keys:
+
+```python
+import fundamental
+from fundamental import FundamentalAWSMarketplaceClient, NEXUSClassifier
+
+# Set the AWS Marketplace client with your deployment URL and AWS region
+fundamental.set_client(FundamentalAWSMarketplaceClient(
+    aws_region="us-west-2",  # Required
+    api_url="http://your-private-server:8000"
+))
+
+# Use the SDK as normal
+classifier = NEXUSClassifier()
+classifier.fit(X_train, y_train)
+predictions = classifier.predict(X_test)
+```
+
+The `FundamentalAWSMarketplaceClient` automatically uses AWS credentials from the environment (IAM role, environment variables, or AWS config file) to sign requests. No API key is needed.
+
+You can also configure using environment variables:
+
+```bash
+export FUNDAMENTAL_API_URL="http://your-private-server:8000"
+```
+
+```python
+fundamental.set_client(
+    FundamentalAWSMarketplaceClient(
+        aws_region="us-west-2",  # Required
+        # api_url="http://your-private-server:8000",  # Optional; overrides FUNDAMENTAL_API_URL
+    )
+)
+```
+
+#### Timeouts and Retries
+
+Configure timeouts and retries when creating a client:
+
+> **Note**: Timeouts apply only to the processing phase, starting after the dataset upload has completed.
+
+```python
+import fundamental
+from fundamental import Fundamental, NEXUSClassifier
+
+# Create and set a client with custom timeouts and retries
+fundamental.set_client(Fundamental(
+    fit_timeout=600,  # 10 minutes for training (default: 3 hours)
+    predict_timeout=30,  # 30 seconds for predictions (default: 1 hour)
+    retries=0  # Number of retries (default: 1)
+))
+
+# Estimators will use the global client
+classifier = NEXUSClassifier()
+```
+
+### Model Configuration
+
+Configure model behavior and training parameters.
+
+#### Mode
+
+NEXUS offers two training modes to balance between speed and accuracy:
+
+- **`quality` mode (default)**: Optimizes for the highest accuracy. This mode uses more comprehensive training processes and may take longer to complete.
+- **`speed` mode**: Optimizes for faster training times while maintaining good accuracy.
+
+```python
+import fundamental
+from fundamental import NEXUSClassifier, NEXUSRegressor
+
+# Use quality mode (default)
+classifier = NEXUSClassifier(mode="quality")
+classifier.fit(X_train, y_train)
+
+# Use speed mode for faster training
+classifier_fast = NEXUSClassifier(mode="speed")
+classifier_fast.fit(X_train, y_train)
+
+# Same for regression
+regressor = NEXUSRegressor(mode="speed")
+regressor.fit(X_train, y_train)
+```
+
+## Supported Data Types
+
+The SDK supports flexible input formats:
+
+- **Input features (X)**:
+  - `pandas.DataFrame`
+  - `numpy.ndarray`
+
+- **Target values (y)**:
+  - `numpy.ndarray`
+  - `pandas.Series`
+
+> **Note**: Data must be serializable to Parquet via PyArrow. If you hit a serialization error, ensure columns have consistent numeric or string dtypes; complex numbers are not supported.
+
+## Handling Errors
+
+The SDK provides detailed error handling with specific exception types:
+
+```python
+from fundamental import NEXUSClassifier
+from fundamental.exceptions import (
+    NEXUSError,
+    ValidationError,
+    AuthenticationError,
+    RateLimitError,
+    ServerError
+)
+
+classifier = NEXUSClassifier()
+
+try:
+    classifier.fit(X_train, y_train)
+except ValidationError as e:
+    print(f"Invalid input data: {e}")
+    print(f"Status code: {e.status_code}")
+except AuthenticationError as e:
+    print("Authentication failed - check your API key")
+except RateLimitError as e:
+    print("Rate limit exceeded - please wait before retrying")
+except ServerError as e:
+    print("Server error - please try again later")
+except NEXUSError as e:
+    print(f"An error occurred: {e}")
+```
+
+### Diagnostics and Support Information
+
+All exceptions include a `trace_id` attribute that you can share with Fundamental support to help diagnose issues more quickly.
+
+```python
+except ServerError as e:
+    if e.trace_id:
+        print(f"Error trace_id: {e.trace_id}")
+```
+
+### Exception Types
+
+| Error Type | Description | Status Code |
+| ---------- | ----------- | ----------- |
+| `ValidationError` | Input validation failed (bad request) | 400 |
+| `AuthenticationError` | Authentication failed (missing/invalid API key) | 401 |
+| `AuthorizationError` | Authorization failed (insufficient permissions) | 403 |
+| `NotFoundError` | Resource not found | 404 |
+| `RateLimitError` | API rate limit exceeded | 429 |
+| `ServerError` | Server-side error | 500+ |
+| `NetworkError` | Network connectivity issues | 503 |
+| `RequestTimeoutError` | Request timed out | 504 |
+
+## Troubleshooting
+
+- **Missing API key** (`ValueError: API key is required...`): set `FUNDAMENTAL_API_KEY` or configure a client via `fundamental.set_client(...)`.
+- **Serialization errors (PyArrow)**: ensure `X`/`y` contain consistent numeric or string types; avoid mixed-type/object columns.
+- **Large datasets / memory use**: datasets are serialized to Parquet in-memory before upload. If you run into memory or upload issues, try sampling, reducing columns, or using batching.
+
+To enable debug logs:
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+```
+
+## Versioning
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions.
+
+To check the installed version:
+
+```python
+import fundamental
+print(fundamental.__version__)
+```
+
+## Requirements
+
+- Python 3.10 or higher
+- See [pyproject.toml](pyproject.toml) for full dependency list
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## Security
+
+If you believe you’ve found a security vulnerability, please email [support@fundamental.tech](mailto:support@fundamental.tech) and include a minimal reproduction. Please do not open a public GitHub issue.
+
+## Support
+
+- **SDK docs**: [SDK User Guide](https://launch.fundamental.tech/docs/guides/sdk/user-guide)
+- **Issues**: [GitHub Issues](https://github.com/Fundamental-Technologies/fundamental-client/issues)
+- **Email**: [support@fundamental.tech](mailto:support@fundamental.tech)

{fundamental_client-0.2.3.dist-info → fundamental_client-0.2.5.dist-info}/RECORD

@@ -1,11 +1,11 @@
-fundamental/__init__.py,sha256=d2xvMhGApfdpRVQCBE9B7qC8vzvJNO0CvtDg-Z1_H80,748
-fundamental/config.py,sha256=aYco0rk5LJDQKre4wfRq9p1cMXJ-EWoqTLwLpJLojn0,5920
-fundamental/constants.py,sha256=qUqITO1IPghToWSYbZHLIDy8X5LfNWImGMy9QHE-sgg,1608
+fundamental/__init__.py,sha256=dnbAH6chnXsb3ls2HxcNvBY9YbbvSIBYOeYsoEVbwpE,1027
+fundamental/config.py,sha256=S-OrWFpwljr4TCCm_vPx3MFyikXlvlSlZh-3r0uJVMI,5960
+fundamental/constants.py,sha256=gvaQ9XFiXLc69pDxU6x0dFhI-4GaT9pySVp0CNpZZ-M,1620
 fundamental/deprecated.py,sha256=hAM-5zdWapRLk8USnNCacPxHBThdWxFiUsbLA1dbYuk,1321
 fundamental/exceptions.py,sha256=m6GZMuVdeo3GsH51wpi_onLDtyf-bq41qY1VksTizN0,2046
-fundamental/clients/__init__.py,sha256=7DYzKRaFbCBvU9xdHDR2BIDh0RIUB8vlzfNlNgiftco,277
+fundamental/clients/__init__.py,sha256=rAKVwphny42dHWDbaF86eqq244V_qNQrdxi_3AlvyVc,311
+fundamental/clients/aws_marketplace.py,sha256=WJmqV0LnN9VN0yJ5A3yi2efbNlJsSYQRqDCrZYnzavA,1331
 fundamental/clients/base.py,sha256=8Ly2jc_7numhli2w-1ZKnam4MX5Wd7NjxQ6KJYrXfSk,1159
-fundamental/clients/ec2.py,sha256=VNDNT38YfnC5k1sBkIRQnfALtzOFcgRwD5bMjOCIU8E,1317
 fundamental/clients/fundamental.py,sha256=fQ9BNH658JUPfzj8NoaAp-NRAC1ECdssui61zwnNxEU,463
 fundamental/estimator/__init__.py,sha256=hU-VtzBeNjG5jyKN9XDYdJk-58wEHfNyrV9wlEWgUtk,426
 fundamental/estimator/base.py,sha256=YN6umVeZa0KErvDKy_kWXlQ_DYUc3HxHaRuK3mj3hg8,7773
@@ -20,10 +20,10 @@ fundamental/services/inference.py,sha256=Y1a9DRwrfRpUQwFJBe_ROb2wd0I0s_Y47zmBk-6
 fundamental/services/models.py,sha256=tAjV1mHbeZsRpkwSVt2qmp0TqMik_GBCKKadE93ylXo,4989
 fundamental/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 fundamental/utils/data.py,sha256=Ppy9F3B-6yAp7i433LeyiGXdi8iEVh3z-nK-W6I8a70,12520
-fundamental/utils/http.py,sha256=qLCdbFqQ4GMxGtkXSuHWP46lHawoIkcCGU-Q-UFOws8,9924
+fundamental/utils/http.py,sha256=_Q_6PvhYbBwgshkguiPHUjNnOWtq5qjb7f9AdTWiGrw,9959
 fundamental/utils/polling.py,sha256=OUWd256FLvH3j-fbbojXRKblL6vNnExzxQbIIus1QzY,2769
 fundamental/utils/safetensors_deserialize.py,sha256=cWRTQS1Eui5NtMPzYCho5v7w8Ympn42U8cVXrRL3WeQ,3465
-fundamental_client-0.2.3.dist-info/METADATA,sha256=d7a4mrT6WQBAj-E-tX8yCEBKwTkjq9s1Fw7QYfrHCJo,14722
-fundamental_client-0.2.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fundamental_client-0.2.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-fundamental_client-0.2.3.dist-info/RECORD,,
+fundamental_client-0.2.5.dist-info/METADATA,sha256=U4K-ULSw8VPOPIdlZqymG9Wd062T9kRBs12m9NkrcM8,27759
+fundamental_client-0.2.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fundamental_client-0.2.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+fundamental_client-0.2.5.dist-info/RECORD,,