NICLClassifier

class NICLClassifier(api_key=None, *, host=None, dataset_name='dataset', model='nicl-small', strategy=None, memory_optimization=True, n_groups=None, column_names=None, selected_features=None, timeout_s=900, metadata=None, user=None, api_version=None, default_headers=None)

Sklearn-compatible classifier using the Neuralk API.

This classifier connects to either the Neuralk cloud API or an on-premise NICL server and provides a scikit-learn compatible interface for classification tasks. Both modes use tar-based binary protocol for efficient data transfer.

Parameters:

  • api_key (str, optional) – API key for authentication (e.g., “nk_live_xxxx”). Required for cloud mode. If not provided, reads from the NEURALK_API_KEY environment variable. Optional for on-premise mode.

  • host (str, optional) – Base URL of the server. If not provided, uses the Neuralk cloud endpoint. When provided, enables on-premise mode which doesn’t require an API key.

  • dataset_name (str, default="dataset") – Name identifier for the dataset used in API requests.

  • model (str, default="nicl-small") – Model identifier to use for inference (e.g., “nicl-small”, “nicl-large”).

  • strategy (str, optional) – Prompting strategy for group-wise processing: - “feature”: Groups based on specified features - “random”: Random assignment to groups - “correlation”: Groups based on target-correlated features - “precomputed_groups”: Uses pre-existing group IDs

  • memory_optimization (bool, default=True) – Enable server-side memory optimization.

  • n_groups (int, optional) – Number of groups for the prompting strategy.

  • column_names (List[str], optional) – Column names corresponding to features in X.

  • selected_features (List[str], optional) – Features to use for grouping strategies.

  • timeout_s (int, default=900) – Request timeout in seconds.

  • metadata (dict, optional) – Optional metadata to include with requests.

  • user (str, optional) – Optional user identifier for request tracking.

  • api_version (str, optional) – Optional API version string to send as ‘Nicl-Version’ header.

  • default_headers (dict, optional) – Optional default headers to include with every request.

Variables:

  • classes (ndarray of shape (n_classes,)) – The unique class labels found during fit.

  • X_train (ndarray of shape (n_samples, n_features)) – Training data stored during fit.

  • y_train (ndarray of shape (n_samples,)) – Encoded training labels stored during fit.

  • last_response (dict) – The last response from the API, containing: - request_id: str - model: str - predictions: List[int] - probabilities: List[List[float]] - credits_consumed: int (cloud mode only) - latency_ms: int

Examples

Cloud mode (default):

>>> from neuralk import NICLClassifier
>>> import numpy as np
>>>
>>> # API key from environment variable NEURALK_API_KEY
>>> clf = NICLClassifier()
>>>
>>> # Or explicit API key
>>> clf = NICLClassifier(api_key="nk_live_xxxx")
>>>
>>> X_train = np.random.randn(100, 10).astype(np.float32)
>>> y_train = np.random.randint(0, 2, 100)
>>>
>>> clf.fit(X_train, y_train)
>>>
>>> X_test = np.random.randn(10, 10).astype(np.float32)
>>> predictions = clf.predict(X_test)
>>> probabilities = clf.predict_proba(X_test)
>>>
>>> # Check credits consumed (cloud mode)
>>> print(clf.credits_consumed)

On-premise mode:

>>> clf = NICLClassifier(host="http://localhost:8000")
>>>
>>> clf.fit(X_train, y_train)
>>> predictions = clf.predict(X_test)