Fundamental Python SDK: API Reference Guide

This guide provides a detailed technical reference for the Fundamental Python SDK, designed for teams integrating the NEXUS model for tabular data into their infrastructure.

1. Architecture Overview

The SDK acts as a high-level wrapper around the Fundamental REST API. It follows the scikit-learn estimator pattern, providing a familiar interface for data scientists while handling complex backend operations like dataset uploads, asynchronous job management, and AWS-native authentication.

2. Client Configuration & Authentication

The SDK supports two primary authentication modes: standard API Key and AWS IAM SigV4 (for private deployments).

Fundamental (Standard Client)

Used for standard API access via keys.

Constructor:

Fundamental(api_key=None, fit_timeout=3600, predict_timeout=3600, retries=2)

Parameter	Type	Description
api_key	str	Your API Key. Defaults to FUNDAMENTAL_API_KEY environment variable.
fit_timeout	int	Max time (seconds) to wait for training jobs.
predict_timeout	int	Max time (seconds) to wait for inference results.
retries	int	Number of automated retry attempts for transient network errors.

FundamentalEC2Client (AWS Private Deployment)

Optimized for AWS environments (EC2, EKS, ECS). It uses AWS SigV4 to sign requests using the environment's IAM role.

Constructor:

FundamentalEC2Client(aws_region, api_url=None)

Parameter	Type	Description
aws_region	str	Required. The AWS region where the service is deployed.
api_url	str	The private endpoint URL. Defaults to FUNDAMENTAL_API_URL.

3. Estimator API

The SDK provides NEXUSClassifier and NEXUSRegressor. Both are scikit-learn compatible.

Common Parameters

Parameter	Type	Default	Description
mode	str	"quality"	"quality" (higher accuracy) or "speed" (faster training).

Core Methods

.fit(X, y)

Synchronously trains a model on the provided tabular data.

• X: pandas.DataFrame or numpy.ndarray.
• y: pandas.Series or numpy.ndarray.
• Post-condition: Sets self.trained_model_id_.

.predict(X) / .predict_proba(X)

Performs inference using the fitted model.

• Returns: numpy.ndarray of predictions or class probabilities.

.load_model(trained_model_id)

Re-initializes an estimator with a previously trained model ID, skipping the training step.

4. Asynchronous Workflow (Long-Running Tasks)

Training and explainability tasks can be handled asynchronously to prevent blocking the main thread.

Training Methods

Method	Description
submit_fit_task(X, y)	Submits a training job to the cluster. Returns a task_id.
poll_fit_result(task_id)	Returns the fitted model if complete, otherwise returns None.

Feature Importance Methods

Method	Description
submit_feature_importance_task(X)	Triggers background importance calculation.
poll_feature_importance_result(task_id)	Returns importance scores (dict) or None.

5. Model Management

Access the model registry via client.models.

Method	Parameters	Description
list()	—	Returns a list of all models accessible to the user/role.
get(model_id)	model_id	Returns metadata, including creation date and attributes.
delete(model_id)	model_id	Deletes the model from Fundamental's storage.
set_attributes(id, attrs)	id, dict	Updates metadata tags (e.g., stage: "production").

6. Error Handling & Diagnostics

The SDK utilizes a structured exception hierarchy. All exceptions include a trace_id for infrastructure logging and support.

Exception	Code	Typical Trigger
ValidationError	400	Categorical data detected (NEXUS requires numeric encoding).
AuthenticationError	401	Invalid API Key or expired IAM token.
AuthorizationError	403	Attempting to access/delete a model owned by another user.
RateLimitError	429	Exceeding the concurrent training/inference limit.
ServerError	500+	Internal API or cluster compute failure.

7. Data Specifications

• Dimensionality: Supports high-dimensional tabular data (N-features).
• Types: Numeric types only (float, int).
• Categorical Handling: Users must perform pre-processing (e.g., Label Encoding or One-Hot Encoding) before passing data to the SDK.
• Missing Values: Handled natively by the NEXUS architecture.

8. Development & Integration Tips

• Global Client: Set a global client once using fundamental.set_client() to avoid passing instances to every estimator.
• AWS Integration: When using FundamentalEC2Client, ensure the IAM role attached to the compute resource has permissions to reach the specified api_url.
• Version Pinning: The SDK follows SemVer. Check version programmatically with fundamental.__version__.