Best Practices

Quick reference for getting the most out of NICL. Each section links to detailed documentation.

Data Preparation

✅ Do:

  • Impute missing values before passing data to NICL

  • Encode categorical features as integers

  • Convert datetime objects to numeric features

  • Apply PCA for datasets with more than 1,000 features

❌ Avoid:

  • Passing raw text or datetime objects directly

  • High-cardinality one-hot encodings

Note

Native support for missing values and datetime features is coming soon.

→ See Advanced Configuration for pipeline examples

Choosing the Right Model

nicl-flash

Prototyping, real-time apps, latency-sensitive use cases

nicl-small

General use, balanced speed/accuracy (default)

nicl-large

Complex tasks, maximum accuracy, batch processing

→ See API Reference for full model specifications

Context Quality Over Quantity

NICL learns from context examples. Quality matters more than quantity:

  • Include representative samples from each class

  • Ensure diversity in your training data

  • Start small and increase until diminishing returns

→ See Built-in selection of the most informative context for sampling strategies

Error Handling

Always handle API errors gracefully in production:

from neuralk import NICLClassifier, NeuralkException

try:
    predictions = clf.predict(X_test)
except NeuralkException as e:
    logger.error(f"Prediction failed: {e.message}")
    # Implement fallback or retry logic

→ See Advanced Configuration for error codes and solutions

Production Checklist

Before deploying to production:

☐ Use environment variables for API keys (never hardcode)

☐ Set appropriate timeout_s for your dataset size

☐ Implement retry logic for transient errors (429, 503)

☐ Monitor credits_consumed and latency_ms

☐ Consider On-Premise Deployment for latency-critical applications