Getting Started#

Overview#

The Neuralk AI SDK is a Python library that provides access to the Neuralk AI platform — a solution designed to accelerate the deployment of off-the-shelf AI use cases on tabular data.

With the Neuralk AI platform, you can:

  • Upload and manage datasets with ease

  • Organize your work into shareable projects for team collaboration

  • Run powerful pre-built AI analyses, including:

    • Classification Assign labels to data rows based on training data.

    • Categorization Organize products into categories using customizable taxonomies.

    • Enrichment Enhance product catalogs by categorizing products and extracting their attributes.

Installation#

The Neuralk AI SDK is available on PyPI and can be installed using pip:

$ pip install neuralk

This is the recommended installation method for users who want to integrate the SDK into their Python projects.

Verifying Your Installation#

You can simply test that the package was installed properly by importing it:

$ python -c "import neuralk; print('Neuralk imported successfully')"

Quick Start Guide#

This guide walks you through the essential steps to get started with the Neuralk AI SDK:

  1. Authentication - Connect to the platform

  2. Project Creation - Set up your workspace

  3. Dataset Upload - Add your data

  4. Analysis Execution - Launch an analysis

  5. Results Retrieval - Get your results

Basic Example#

Here’s a complete example that demonstrates the typical workflow:

from neuralk import Neuralk

# 1. Authenticate
client = Neuralk(user_id="your_user_id", password="your_password")

# 2. Create a project (or use an existing one)
project = client.projects.create(name="My First Project")

# 3. Upload a dataset to your project
dataset = client.datasets.create(
    project=project,
    name="Sample Dataset",
    file_path="/path/to/your_data.csv",
)

# 4. Launch an analysis to fit a classifier
classifier_fit = client.analysis.create_classifier_fit(
    dataset=dataset,
    name="My Classifier Fit",
    target_column="target_column_name",
    id_columns=["id_column_name"],  # Optional
    feature_column_name_list=["feature1", "feature2"]  # Optional
)

# 5. Monitor the analysis progress
classifier_fit = client.analysis.wait_until_complete(
    classifier_fit,
    refresh_time=10,  # Check progress every 10 seconds
    verbose=True      # Display progress updates
)

# 6. Download the results to your local machine
client.analysis.download_results(classifier_fit, folder_path="./results/")

# 7. Logout when done
client.logout()

For more detailed examples, see the Examples page.

Core Concepts#

The SDK is built around two main concepts:

  • Handlers - High-level methods that interact with the Neuralk AI platform

  • Models - Data structures that represent a static view of platform objects (projects, datasets, etc.)

All functionality is accessible through a single Neuralk client instance.

Handlers#

Handlers provide the main interface for interacting with different aspects of the platform.

Project Handler#

The ProjectHandler allows you to create, retrieve, list and delete projects.

# Create a new project
project = client.projects.create(name="My Project")

# Retrieve an existing project
project = client.projects.get("<project_id>")

# List all your projects
projects = client.projects.get_list()

# Delete a project (use with caution!)
client.projects.delete(project)

# Manage project access
client.projects.add_user(project, user_email="user@example.com", role="owner")
client.projects.delete_user(project, user_email="user@example.com")
users = client.projects.list_user(project)

Dataset Handler#

The DatasetHandler allows you to create, retrieve, list and delete datasets.

# Upload a dataset to a project
dataset = client.datasets.create(
    project=project,
    name="My Dataset",
    file_path="/path/to/data.csv",
)

# Retrieve an existing dataset
dataset = client.datasets.get(dataset)

# Delete a dataset
client.datasets.delete(dataset)

Project File Handler#

The ProjectFileHandler allows you to create, retrieve, list and delete business files, such as taxonomies.

# Upload a taxonomy file
project_file = client.project_files.create(
    project=project,
    name="product_taxonomy.json",
    file_path="/path/to/taxonomy.json",
)

# Remove a file
client.project_files.delete(project_file)

Analysis Handler#

The AnalysisHandler allows you to create, monitor, fetch analyses and download the associated results.

# Categorization Fit
categorizer_fit = client.analysis.create_categorization_fit(
    dataset=dataset,
    name="My Categorization Fit",
    taxonomy_file=project_file,  # Optional
    target_columns="target_columns",  # Optional
    id_columns=["id_col"],  # Optional
    categorizer_feature_cols=["cat_col1"]  # Optional
)

# Use the trained analysis for predictions
categorizer_predict = client.analysis.create_categorization_predict(
    dataset=dataset,
    name="My Categorizer Predict",
    categorization_fit_analysis=categorizer_fit
)

Core Models#

The SDK uses structured data models to represent platform objects. These models provide easy access to object properties and relationships.

class Project:
    id: str                    # Unique project identifier
    name: str                  # Project display name
    dataset_list: list[Dataset]           # Datasets in this project
    user_list: list[tuple[str, User]]     # Users with access (role, user)
    project_file_list: list[ProjectFile]  # Files in this project
    analysis_list: list[Analysis]         # Analyses in this project

class Dataset:
    id: str                    # Unique dataset identifier
    name: str                  # Dataset display name
    file_name: str             # Filename
    analysis_list: list[Analysis]         # Analyses using this dataset

class Analysis:
    id: str                    # Unique analysis identifier
    name: str                  # Analysis display name
    advancement: int           # Progress percentage (0-100)
    error: str                 # Error message if failed
    status: str                # Current status (IN PENDING, IN RUNNING, SUCCEEDED, FAILED)

class User:
    id: str                    # Unique user identifier
    email: str                 # User's email address
    firstname: str             # User's first name
    lastname: str              # User's last name

class ProjectFile:
    id: str                    # Unique file identifier
    name: str                  # File display name
    file_name: str             # Original filename

Best Practices#

  • Always call logout() when done to invalidate your session

  • Use role appropriately when assigning users to projects

  • Use refresh_time and verbose to monitor the progress of analyses while running