<div align="center">

![Neuralk SDK](https://docs.neuralk-ai.com/_images/cover.png)

<h3>A Tabular Machine Learning SDK for Industrial Applications</h3>

[![PyPI version](https://img.shields.io/pypi/v/neuralk.svg)](https://pypi.org/project/neuralk/)
[![Python versions](https://img.shields.io/pypi/pyversions/neuralk.svg)](https://pypi.org/project/neuralk/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-neuralk--ai.com-blue)](https://docs.neuralk-ai.com/)

[Documentation](https://docs.neuralk-ai.com/) | [API Reference](https://docs.neuralk-ai.com/api/) | [Examples](https://docs.neuralk-ai.com/auto_examples/)

</div>

---

## Overview

The Neuralk SDK provides Python developers with a scikit-learn compatible interface to access **NICL (Neuralk In-Context Learning)**, a foundation model specifically designed for tabular classification tasks.

**Key Features:**

- **Zero hyperparameter tuning** - Strong baseline performance out of the box
- **Scikit-learn compatible** - Works with pipelines, cross-validation, and familiar fit/predict interface
- **Flexible deployment** - Cloud API or on-premise server
- **Mixed feature types** - Handles numerical and categorical data
- **Multiple model sizes** - Choose between speed (nicl-flash) and accuracy (nicl-large)

## Installation

```bash
pip install neuralk
```

**Requirements:** Python 3.11+

## Quick Start

### 1. Get your API key

```bash
neuralk login
```

This displays instructions to create your account at [prediction.neuralk-ai.com/register](https://prediction.neuralk-ai.com/register).

### 2. Set your API key

```bash
export NEURALK_API_KEY=nk_live_your_api_key_here
```

### 3. Make your first prediction

```python
from sklearn.model_selection import train_test_split
from sklearn.metrics import accuracy_score
from neuralk import NICLClassifier
from neuralk.datasets import two_moons

# Load example dataset
X, y = two_moons()
X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=42)

# Create classifier and predict
clf = NICLClassifier()
clf.fit(X_train, y_train)
predictions = clf.predict(X_test)

print(f"Accuracy: {accuracy_score(y_test, predictions):.2%}")
```

### Using with scikit-learn pipelines

```python
from sklearn.pipeline import make_pipeline
from sklearn.impute import SimpleImputer
from skrub import TableVectorizer
from neuralk import NICLClassifier

clf = make_pipeline(
    TableVectorizer(),
    SimpleImputer(),
    NICLClassifier(),
)

clf.fit(X_train, y_train)
predictions = clf.predict(X_test)
```

### On-premise deployment

```python
from neuralk import NICLClassifier

clf = NICLClassifier(host="http://your-server:8000")
clf.fit(X_train, y_train)
predictions = clf.predict(X_test)
```

## Available Models

| Model | Description |
|-------|-------------|
| `nicl-flash` | Fastest model, optimized for low latency |
| `nicl-small` | Balanced model (default) |
| `nicl-large` | Most accurate, recommended for complex tasks |

```python
clf = NICLClassifier(model="nicl-large")
```

## Documentation

- [Getting Started Guide](https://docs.neuralk-ai.com/getting_started/quickstart.html)
- [Understanding In-Context Learning](https://docs.neuralk-ai.com/getting_started/introduction.html)
- [Advanced Configuration](https://docs.neuralk-ai.com/getting_started/direct_model_usage.html)
- [Context Selection Strategies](https://docs.neuralk-ai.com/getting_started/prompting_modules.html)
- [Example Gallery](https://docs.neuralk-ai.com/auto_examples/)

## Citation

If you use Neuralk in your research, please cite:

```bibtex
@software{neuralk2026sdk,
    title = {Neuralk: A Foundation Model for Industrial Tabular Data},
    author = {Neuralk AI},
    year = {2026},
    url = {https://www.neuralk-ai.com/}
}
```

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Contact

- **Questions & Feature Requests:** alex@neuralk-ai.com
- **Collaborations:** antoine@neuralk-ai.com
