neuralsmith-cli 1.0.1

NeuralSmith CLI - ML Engineering Made Accessible to All

NeuralSmith CLI

A standalone command-line tool for automated neural architecture search and machine learning model training — no IDE required.

Overview

The NeuralSmith CLI brings the full power of the NeuralSmith training engine to your terminal. Whether you prefer working outside VS Code or need to automate training pipelines in CI/CD environments, the CLI gives you direct, scriptable access to every wizard.

Features at a glance:

• 🖼️ Image Classification — Train models using Neural Architecture Search across 14 model experiments simultaneously
• 📊 Tabular Classification & Regression — Train on CSV data with built-in EDA, smart imputation, and automatic feature selection
• 📈 Time Series — Classification and regression for time series data with temporal-safe train/val/test splitting
• 🏷️ Auto Labeler — Automatically label unlabeled data using weighted KNN
• 🤖 CoPilot — Interactive AI assistant for guidance, troubleshooting, dataset validation, and live training status

---

Installation

Prerequisites

• Python 3.8 or higher
• pip or pipx

From Source (Development)

cd CLI
pip install -e .

With development dependencies:

pip install -e ".[dev]"

With Optional Features

# CoPilot support (requires Gemini API key)
pip install -e ".[copilot]"

# Auto-labeler support
pip install -e ".[auto-labeler]"

# Everything including dev dependencies
pip install -e ".[copilot,auto-labeler,dev]"

---

Quick Start

1. Configure API Key (for CoPilot)

neuralsmith --config-key

Or set the environment variable directly:

export NEURALSMITH_GEMINI_API_KEY="your-api-key-here"

2. Try CoPilot

neuralsmith copilot

Ask questions like:

• "How do I train an image classification model?"
• "What options does tabular-classification support?"
• "Help me validate my dataset"

3. Train Your First Model

Image Classification:

neuralsmith image-classification \
  --data-path ./my_images \
  --output-dir ./results \
  --epochs 10

Tabular Classification:

neuralsmith tabular-classification \
  --data-path ./data.csv \
  --target-column species \
  --mode fast

---

Command Reference

All commands follow the pattern neuralsmith <wizard> [OPTIONS]. Append --help to any subcommand for the full options list.

image-classification

Train image classification models using Neural Architecture Search.

neuralsmith image-classification \
  --data-path <folder> \
  --output-dir <dir> \
  [--target-size H,W] \
  [--epochs N] \
  [--val-split 0.1] \
  [--batch-size N] \
  [--learning-rate 0.001] \
  [--device cpu|cuda] \
  [--seed 42]

Example:

neuralsmith image-classification \
  --data-path ./my_images \
  --output-dir ./results \
  --target-size 128,128 \
  --epochs 100 \
  --val-split 0.2

tabular-classification

Train classification models on CSV data with automatic EDA.

neuralsmith tabular-classification \
  --data-path <csv> \
  --target-column <n> \
  [--output-dir <dir>] \
  [--mode fast++|fast|exhaustive] \
  [--train-percent 80.0] \
  [--val-percent 0.0] \
  [--test-percent 20.0] \
  [--no-eda]

tabular-regression

Same options as tabular-classification — swap the subcommand for continuous target prediction.

timeseries-classification & timeseries-regression

Train on time series data. Accepts CSV or pre-windowed NumPy splits.

neuralsmith timeseries-classification \
  --data-path <csv or dir> \
  [--time-column <n>] \
  --target-column <n> \
  [--window-size <n>] \
  [--mode fast|fast++|exhaustive] \
  [--split-method temporal|random] \
  [--train-percent 70.0] \
  [--val-percent 15.0] \
  [--test-percent 15.0]

Note: Use --split-method temporal (the default) to avoid overlap leakage between train/val/test windows. For NumPy directory input, provide files named X_train.npy, y_train.npy, X_val.npy, y_val.npy, X_test.npy, y_test.npy.

auto-labeler

Automatically label unlabeled data using weighted KNN.

neuralsmith auto-labeler \
  --data-path <path> \
  --data-type image|tabular|timeseries \
  --labeled-column <n> \
  --label-column <n> \
  --output-path <path> \
  [--k 5] \
  [--min-confidence 0.5]

---

CoPilot & Agent Modes

CoPilot is an interactive AI assistant powered by Gemini. Beyond answering questions, it can validate datasets, watch live training progress, and in agent modes — plan and execute full training runs for you.

neuralsmith copilot [--gemini-key <key>]

Modes

Mode	Flag	Behaviour
Ask	(default)	Answers questions. You run !validate, !status, !watch yourself.
Agent	--agent	Can call read-only tools and propose full training commands. Each run requires yes confirmation.
Agent-plus (experimental)	--agent-plus	Same as Agent but proposed commands run without confirmation. Use only in trusted environments.

In-session Commands

Command	Description
help	Show available commands
!validate <path>	Validate a dataset
!status [path]	Read the newest run status JSON
!watch [path]	Poll status every ~2s until completed or failed
exit	Quit CoPilot

How Agent Mode Works

1. You describe a task — e.g. "train a quick tabular classifier on this CSV"
2. CoPilot inspects files and validates data with read-only tools
3. CoPilot prints the exact proposed command
4. Nothing runs until you type yes (with --agent) — or immediately with --agent-plus
5. Training output streams in the same terminal

---

Common Workflows

Image Classification

1. Organise images into one sub-folder per class:

my_images/
├── class1/
│   ├── img1.jpg
│   └── img2.jpg
└── class2/
    ├── img3.jpg
    └── img4.jpg

2. Run training:

neuralsmith image-classification \
  --data-path ./my_images \
  --output-dir ./results \
  --epochs 50 \
  --val-split 0.2

3. Check results in ./results/ — a full training summary report is generated automatically.

Tabular Classification

1. Prepare your CSV with a clearly named target column.
2. Run EDA and training:

neuralsmith tabular-classification \
  --data-path ./data.csv \
  --target-column target \
  --mode exhaustive \
  --output-dir ./results

3. Review ranked models in ./results/models/

Time Series

1. Prepare your CSV with a time column and feature columns.
2. Run training:

neuralsmith timeseries-classification \
  --data-path ./timeseries.csv \
  --time-column timestamp \
  --target-column label \
  --window-size 20 \
  --mode fast \
  --split-method temporal

---

Using Trained Models

After training completes, NeuralSmith writes a comprehensive training summary report alongside your model artifacts.

Report files:

• Markdown: {output_dir}/training_summary_report.md
• JSON: {output_dir}/training_summary_report.json

Each report contains an executive summary, a ranked comparison table of all candidate models, full details on the best-performing model, and ready-to-use code examples.

Loading an Image Classification Model

from neuralsmith.model_loader import load_model
import torch
import numpy as np
from PIL import Image

model = load_model('results/model_*.pth')

image = Image.open('your_image.jpg')
image = image.resize((64, 64))  # match your training --target-size
img_array = np.array(image).astype(np.float32) / 255.0
img_array = np.transpose(img_array, (2, 0, 1))  # HWC → CHW
img_tensor = torch.FloatTensor(img_array).unsqueeze(0)

model.eval()
with torch.no_grad():
    prediction = model(img_tensor)
    predicted_class = torch.argmax(prediction, dim=1).item()
    probabilities = torch.softmax(prediction, dim=1)[0]

print(f'Predicted class: {predicted_class}')
print(f'Probabilities: {probabilities.numpy()}')

Loading a Tabular Model

from neuralsmith.model_loader import load_model
import pandas as pd

model, preprocessor = load_model('results/models/best_model_*/')

new_data = pd.read_csv('new_data.csv')
X_processed = preprocessor.transform(new_data)
predictions = model.predict(X_processed)

if hasattr(model, 'predict_proba'):
    probabilities = model.predict_proba(X_processed)
    print(f'Predictions: {predictions}')
    print(f'Probabilities:\n{probabilities}')
else:
    print(f'Predictions: {predictions}')

Best practices:

• Always check the training summary report first for exact model paths and architecture details
• Use the same preprocessing pipeline bundled with the trained model
• Match input shapes — for images, match --target-size; for tabular, match training feature names
• Ensure data and model are on the same device (CPU or CUDA)
• Use CoPilot for customised code generation: "Generate code to load my model from results/"

---

Configuration

Configuration is stored in ~/.neuralsmith/config.json:

{
  "gemini_api_key": "your-api-key",
  "default_output_dir": "./models",
  "log_level": "INFO"
}

Environment variables (override config file values):

Variable	Description
NEURALSMITH_GEMINI_API_KEY	Gemini API key for CoPilot

---

Troubleshooting

API Key Issues

# Re-run interactive key setup
neuralsmith --config-key

# Or export directly
export NEURALSMITH_GEMINI_API_KEY="your-key"

Python Version

Confirm you are running Python 3.8 or higher:

python --version

Missing Dependencies

pip install -e ".[copilot,auto-labeler]"

Memory Issues

Reduce image resolution and batch size:

neuralsmith image-classification \
  --data-path ./large_dataset \
  --target-size 64,64 \
  --batch-size 16

Model Loading Errors

Error	Fix
Model Not Found	Check training_summary_report.md for exact paths
Shape Mismatch	For images: match --target-size. For tabular: match feature names exactly
Preprocessing Error	Load preprocessor from the same model directory

Still stuck? Ask CoPilot: "Help me debug my model loading code" or "Why am I getting a shape mismatch error?"

---

---

License

See NeuralSmith License for details.

Support

• Use CoPilot: neuralsmith copilot
• Check the training summary reports for model-specific guidance
• Email: [e-mail]