fundamental-client 0.2.3__tar.gz → 0.2.5__tar.gz

fundamental_client-0.2.5/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.5"
+}

{fundamental_client-0.2.3 → fundamental_client-0.2.5}/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 <!-- version list -->
 
+## [0.2.5](https://github.com/Fundamental-Technologies/fundamental-client/compare/0.2.4...0.2.5) (2026-02-05)
+
+
+### Bug Fixes
+
+* improve README and version reporting (ENG-594) ([#68](https://github.com/Fundamental-Technologies/fundamental-client/issues/68)) ([2c1bfc5](https://github.com/Fundamental-Technologies/fundamental-client/commit/2c1bfc5795203ef70cc066352d35f1b775e92b65))
+
+## [0.2.4](https://github.com/Fundamental-Technologies/fundamental-client/compare/0.2.3...0.2.4) (2026-02-04)
+
+
+### Bug Fixes
+
+* eng-575-user-facing-readme ([#64](https://github.com/Fundamental-Technologies/fundamental-client/issues/64)) ([591bcce](https://github.com/Fundamental-Technologies/fundamental-client/commit/591bccefed4abeaeddca9b8a03d81044d2d4bb25))
+* update documentation URL in pyproject.toml ([#66](https://github.com/Fundamental-Technologies/fundamental-client/issues/66)) ([1d21409](https://github.com/Fundamental-Technologies/fundamental-client/commit/1d214095abdb61a47abaecde66e5cee9a69a7ba3))
+
 ## [0.2.3](https://github.com/Fundamental-Technologies/fundamental-client/compare/0.2.2...0.2.3) (2026-02-03)
 
 

fundamental_client-0.2.5/CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Contributing to Fundamental Python SDK
+
+We welcome contributions to the Fundamental Python SDK! Whether it's a bug fix, documentation improvement, or additional tests, your help is appreciated.
+
+## Reporting Issues
+
+Go to this repository's [issues page](https://github.com/Fundamental-Technologies/fundamental-client/issues) and click "New Issue". Please check if the issue has already been reported before creating a new one.
+
+Include the following information:
+
+- Describe what you expected to happen
+- If possible, include a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
+- Describe what actually happened, including the full traceback if there was an exception
+- List your Python version and SDK version
+
+## Development Setup
+
+Fork the repository and clone it locally:
+
+```bash
+git clone https://github.com/YOUR-USERNAME/fundamental-client
+cd fundamental-client
+git checkout -b my-feature-branch main
+```
+
+### Quick Setup
+
+We recommend using our bootstrap script for easy setup:
+
+```bash
+./scripts/bootstrap
+```
+
+### Manual Installation
+
+```bash
+# Install with development dependencies using uv (recommended)
+uv sync --extra dev
+
+# Or (pip-compatible) install in editable mode
+uv pip install -e ".[dev]"
+
+# Or with pip
+pip install -e ".[dev]"
+```
+
+## Making Changes
+
+1. Make your changes
+2. Format code: `./scripts/format`
+3. Check linting: `./scripts/lint`
+4. Run tests: `./scripts/test`
+
+## Testing
+
+We use [pytest](https://docs.pytest.org/) for testing. To run tests:
+
+```bash
+# Run all tests using the test script
+./scripts/test
+
+# Or run directly with nox for all Python versions
+uv run nox -s tests
+
+# Run tests for specific Python version
+uv run nox -s tests-3.10
+
+# Run tests with minimum dependencies
+uv run nox -s tests-3.10 -- minimum
+
+# Run specific test file directly
+uv run pytest tests/unit/test_estimators.py -v
+```
+
+When adding new tests, place them in the `tests/` directory following the same structure as the source code.
+
+## Code Quality
+
+```bash
+# Format code using the format script
+./scripts/format
+
+# Run all linting checks using the lint script
+./scripts/lint
+
+# Or run individual checks:
+# Ruff check
+uv run ruff check .
+
+# Type checking with pyright
+uv run pyright
+
+# Type checking with mypy
+uv run mypy .
+
+# Run all pre-commit hooks
+uv run pre-commit run --all-files
+```
+
+## Generating API Models
+
+The SDK uses auto-generated Pydantic models from the Fundamental API's OpenAPI specification. This ensures type safety and keeps the client in sync with the API.
+
+```bash
+# Regenerate models from the OpenAPI spec
+./scripts/generate-models
+
+# Use a different OpenAPI URL (e.g., production)
+OPENAPI_URL=https://api.fundamental-dev.tech/openapi.json ./scripts/generate-models
+```
+
+Generated models are placed in `src/fundamental/models/generated.py` and can be imported from `fundamental.models`:
+
+```python
+from fundamental.models import (
+    FitRequest,
+    FitResponse,
+    TaskStatus,
+    TaskStatusResponse,
+)
+```
+
+When the API changes, simply re-run the generation script to update the models.
+
+## Versioning and Release Flow
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. We use [Release Please](https://github.com/googleapis/release-please) for automated versioning and changelog generation.
+
+**Main Branch (Stable Releases):**
+1. Push to `main` triggers Release Please to create/update a Release PR
+2. Merging the Release PR creates a GitHub Release
+3. The GitHub Release triggers publishing to CodeArtifact and TestPyPI
+
+**Feature Branches (Dev Releases):**
+1. Push to any non-main branch publishes a dev version to CodeArtifact
+2. Dev version format: `X.Y.Z.dev0+<commit-hash>`
+
+> **Note:** CodeArtifact may show dev versions as "Latest", but `pip install fundamental-client` will install the stable version. Use `--pre` to install dev versions.
+
+## Opening a Pull Request
+
+Push your branch and open a pull request against the `main` branch. Include:
+
+- Clear title following Conventional Commits format
+- Description of what you changed and why
+- Reference any related issues
+
+Make sure all CI checks pass before requesting review.
+
+## Getting Help
+
+- **Issues**: [GitHub Issues](https://github.com/Fundamental-Technologies/fundamental-client/issues) for bugs and feature requests
+- **Email**: support@fundamental.tech for questions
+- **Documentation**: See README.md for usage examples
+
+We appreciate all contributions and will provide constructive feedback on pull requests. Thank you for helping improve the Fundamental Python SDK!

{fundamental_client-0.2.3 → fundamental_client-0.2.5}/PKG-INFO

@@ -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)