NeuroLab

Research-grade neural network laboratory for the terminal.

Build. Train. Visualize.

NeuroLab is a terminal-first machine learning CLI that lets you load data, inspect it, train neural networks, visualize training progress, compare experiments, and generate commands with an AI copilot -- all from your terminal.

It is designed for researchers, quants, developers, and advanced students who want a fast, reproducible, and visually polished workflow for neural network experimentation.

Installation

npm install -g neurolab

Requirements:

• Node.js >= 18
• Python >= 3.8 with PyTorch (pip install torch)

Verify your setup:

neurolab doctor

Quick Start

# Initialize a project
neurolab init

# Inspect a dataset
neurolab inspect data.csv

# Train an MLP on tabular data
neurolab train data.csv --target y --model mlp

# Train a Transformer for time series forecasting
neurolab train prices.csv --target returns --model transformer \
  --task timeseries_forecasting --seq-len 64 --split chronological

# AI copilot: generate commands from natural language
neurolab ask "train an LSTM for forecasting with early stopping"

# Compare runs
neurolab compare run_001 run_002 run_003

Commands

| Command | Description | |---------|-------------| | neurolab init | Initialize a NeuroLab project | | neurolab inspect <source> | Inspect dataset: schema, statistics, quality, task suggestions | | neurolab train <source> | Train a neural network model | | neurolab eval <run_id> | Evaluate a saved run on test data | | neurolab predict <run_id> | Run predictions with a saved model | | neurolab compare <runs...> | Compare multiple runs side by side | | neurolab models [name] | List supported model architectures | | neurolab runs | List saved training runs | | neurolab show <run_id> | Show detailed run info and metrics | | neurolab plot <run_id> | Plot training curves in terminal | | neurolab ask <message> | AI copilot: generate CLI commands | | neurolab doctor | Check environment setup | | neurolab config | Manage configuration |

Supported Models

| Model | Architecture | Best For | |-------|-------------|----------| | mlp | Multilayer Perceptron | Tabular regression/classification | | lstm | Long Short-Term Memory | Time series, sequences | | transformer | Self-Attention | Complex time series patterns | | rnn | Recurrent Neural Network | Short sequences | | gru | Gated Recurrent Unit | Efficient sequence modeling | | cnn | 1D Convolutional | Local pattern detection |

Supported Tasks

• regression -- predict continuous values
• classification -- predict discrete labels
• timeseries_forecasting -- predict future values from historical sequences

Data Sources

NeuroLab accepts:

• Local CSV files -- neurolab train data.csv
• Local JSON files -- neurolab train data.json
• URLs -- neurolab train https://example.com/data.csv

Training Examples

Tabular Regression

neurolab train housing.csv --target price --model mlp \
  --epochs 200 --lr 0.001 --hidden 128 --layers 3 --normalize

Binary Classification

neurolab train customers.csv --target churn --model mlp \
  --task classification --early-stopping --patience 15

Time Series Forecasting

neurolab train stock_prices.csv --target close --model transformer \
  --task timeseries_forecasting --seq-len 64 --split chronological \
  --time-col date --standardize --early-stopping

Using a Config File

neurolab train --config train.transformer.json

AI Copilot

NeuroLab includes an AI copilot powered by Claude Opus 4.6 that generates explicit CLI commands from natural language.

# Generate commands (displays only, does not execute)
neurolab ask "forecast next-day returns with a transformer using 64-step sequences"

# Generate with explanation
neurolab ask "compare MLP and LSTM for classification" --explain

# Generate and execute
neurolab ask "train a model on my data" --run

# Local generation without API (works offline)
neurolab ask "train an LSTM on data.csv" --safe

Configure AI

# Interactive API key setup
neurolab config api-key

# Or set environment variable
export ANTHROPIC_API_KEY=sk-ant-...

The AI generates explicit, reproducible NeuroLab commands -- it never executes anything silently.

Run Management

Every training run is saved with full reproducibility:

.neurolab/runs/run_001/
  config.json      # full hyperparameter snapshot
  metrics.json     # final metrics
  history.json     # epoch-by-epoch training history
  summary.json     # run summary
  model.pt         # saved model checkpoint
  data/            # training data snapshot
  plots/           # generated plots

# List all runs
neurolab runs

# Show run details
neurolab show run_001

# Plot training curves
neurolab plot run_001 --metric loss

# Compare runs
neurolab compare run_001 run_002

Configuration

Initialize a project config:

neurolab init

This creates neurolab.config.json:

{
  "dataDir": "data",
  "runsDir": ".neurolab/runs",
  "defaultDevice": "cpu",
  "defaultSeed": 42,
  "ai": {
    "provider": "anthropic",
    "model": "claude-opus-4-6",
    "safeMode": true
  }
}

Manage config:

neurolab config show
neurolab config set defaultDevice cuda
neurolab config api-key

Architecture

src/
  cli/          # Command definitions and help
  core/         # Types, model registry, orchestration, process bridge
  data/         # Loaders (CSV, JSON, URL), schema inference, preprocessing
  runs/         # Run storage, listing, comparison
  ui/           # Terminal rendering: tables, charts, progress, formatting
  ai/           # AI copilot: prompt templates, command generation
  config/       # Config schemas (zod), defaults, loading
  utils/        # Errors, logging, filesystem, validation

python_backend/
  models/       # PyTorch model implementations (MLP, LSTM, Transformer, ...)
  utils/        # Metrics, data utilities
  train.py      # Training entrypoint (JSON IPC with Node.js)
  evaluate.py   # Evaluation entrypoint
  predict.py    # Prediction entrypoint

Roadmap

Phase 1 (Current)

• [x] Core CLI with 13 commands
• [x] Data inspection with smart analysis
• [x] 6 model architectures (MLP, LSTM, Transformer, RNN, GRU, CNN)
• [x] 3 task types (regression, classification, timeseries forecasting)
• [x] AI copilot with Claude Opus 4.6
• [x] Run management and comparison
• [x] Terminal charts and rich UI

Phase 2

• [ ] Database support (PostgreSQL, SQLite)
• [ ] Confusion matrix visualization
• [ ] Auto model selection
• [ ] Hyperparameter search
• [ ] Config templates

Phase 3

• [ ] Interactive dashboard mode
• [ ] Plugin model registry
• [ ] Advanced run search
• [ ] Hyperparameter sweeps
• [ ] Export to ONNX

License

MIT