Metadata-Version: 2.4
Name: neuralsmith-cli
Version: 1.0.1
Summary: NeuralSmith CLI - ML Engineering Made Accessible to All
Author-email: All Things Intelligence <info@allthingsintelligence.com>
License: # NeuralSmith Non-Commercial Research & Evaluation License
        
        **Version:** 1.0  
        **Effective Date:** April 3, 2025  
        **Issued by:** All Things Intelligence LLC
        
        ---
        
        ## Preamble
        
        NeuralSmith is an ML engineering platform developed and owned by All Things Intelligence LLC ("Licensor"). It is distributed as a Visual Studio Code extension and as a command-line interface (CLI) tool, and is designed to make machine learning model development, training, evaluation, and deployment accessible to individuals and organizations worldwide.
        
        This License is offered in the spirit of open learning. The Licensor believes that researchers, students, educators, and technology enthusiasts should have access to powerful ML tooling â€” free of charge â€” for the purposes of study, experimentation, and personal development. At the same time, the Licensor must sustain the investment required to build, maintain, and improve NeuralSmith. Accordingly, any use that generates, supports, or is reasonably associated with revenue or commercial benefit requires a separate Commercial License.
        
        By downloading, installing, accessing, copying, using, testing, or otherwise interacting with NeuralSmith in any form â€” including its source code, binaries, CLI tool, VS Code extension, associated documentation, model outputs, or any part thereof â€” you ("Licensee") agree to be bound by the terms of this License in their entirety. If you do not agree, you must immediately cease all use and delete all copies of NeuralSmith in your possession.
        
        ---
        
        ## 1. Definitions
        
        **1.1 "Software"** means the NeuralSmith platform in all its forms, including the VS Code extension (published under the identifier AllThingsIntelligence.neuralsmith), the CLI tool (including any distribution via pip, pipx, npm, or similar package registries), all associated source code, object code, compiled binaries, data files, documentation, configuration files, sample datasets, and any updates, patches, or new versions released by the Licensor under this License.
        
        **1.2 "Licensor"** means All Things Intelligence LLC, a limited liability company organized under the laws of the State of Wyoming, United States of America.
        
        **1.3 "Licensee" or "You"** means any individual or legal entity that downloads, installs, accesses, uses, copies, tests, evaluates, or otherwise interacts with the Software, whether or not they have executed a written agreement with the Licensor.
        
        **1.4 "Permitted Purpose"** means any use of the Software that falls within the categories expressly enumerated in Section 3 of this License, and that does not constitute a Prohibited Use under Section 4.
        
        **1.5 "Commercial Use"** means any use of the Software, directly or indirectly, in connection with any activity that generates, supports, enables, or is reasonably calculated to generate revenue, monetary consideration, financial benefit, or economic advantage of any kind â€” for the Licensee, any affiliated entity, any client, any employer, any investor, or any third party. Commercial Use includes, without limitation: production deployment, revenue-generating workflows, client service delivery, startup product development, venture-funded internal tooling, and investor demonstrations or pitches.
        
        **1.6 "Modification"** means any addition to, deletion from, alteration of, or adaptation of the Software's source code, object code, configuration, data files, or any other component of the Software, whether made locally, in a fork, in a derived repository, or in any other form â€” including minor changes of a single character.
        
        **1.7 "Derivative Output"** means any machine learning model, model weight file, ONNX export, serialized artifact, dataset, or other output that is produced directly by executing or operating the Software, including outputs from any modified version of the Software.
        
        **1.8 "Commercial License"** means a separate, written license agreement executed between the Licensor and a Licensee that expressly authorizes Commercial Use, production deployment, or any other use not permitted under this License.
        
        **1.9 "License Key"** means any software token, cryptographic key, API key, access credential, account authentication, or feature-flag mechanism used by the Software to control access to features, enforce license tiers, or verify authorization.
        
        **1.10 "Contribution"** means any code, documentation, configuration, data, or other material voluntarily submitted to the Licensor for potential inclusion in the Software.
        
        ---
        
        ## 2. Copyright Ownership & Reservation of Rights
        
        The Software is the exclusive intellectual property of the Licensor. All title, ownership, copyright, patent rights, trade secret rights, trademark rights, and all other intellectual property rights in and to the Software â€” including all Modifications made by any party and all Derivative Outputs produced by the Software â€” are and shall remain vested in the Licensor.
        
        This License does not transfer any ownership interest in the Software to the Licensee. The Licensee receives only the limited, conditional license expressly set out in Section 3 below. All rights not expressly granted herein are reserved by the Licensor.
        
        ---
        
        ## 3. License Grant & Permitted Purposes
        
        Subject to the Licensee's strict and continuing compliance with all terms and conditions of this License, the Licensor hereby grants the Licensee a limited, non-exclusive, non-transferable, non-sublicensable, royalty-free license to download, install, access, and use the Software solely for the following Permitted Purposes:
        
        **3.1 Academic Research & Scholarship** â€” Use by students, faculty, post-doctoral researchers, and independent scholars at accredited educational or public research institutions, for the purpose of conducting original research, publishing academic findings, or completing degree requirements â€” provided that no revenue is generated from such use.
        
        **3.2 Educational Instruction** â€” Use by teachers, instructors, professors, and trainers to demonstrate ML concepts, conduct classroom exercises, design course curricula, or create publicly available educational materials â€” including online courses offered at no charge to participants â€” provided that the Software is not itself monetized.
        
        **3.3 Personal Experimentation & Hobby Projects** â€” Use by individuals for personal learning, self-directed skill development, private experimentation, non-monetized hobby projects, or amateur pursuits â€” where no output, product, or service derived from such use is sold, licensed, or offered in exchange for compensation of any kind.
        
        **3.4 Pre-Commercial Evaluation & Benchmarking** â€” Use by individuals or organizations for the limited purpose of evaluating whether the Software is suitable for their needs, for a period not exceeding thirty (30) consecutive calendar days per organization. Evaluation use does not include use in production environments, deployment to end users, or demonstration to investors or clients for the purpose of raising capital or closing commercial deals.
        
        **3.5 Non-Profit & Public Interest Organizations** â€” Use by organizations that are (a) formally registered as non-profit, charitable, or public-benefit entities under applicable law, (b) educational institutions, (c) governmental bodies or agencies, or (d) public health, environmental, or humanitarian organizations â€” provided that such use is solely in furtherance of the organization's non-commercial mission and that no revenue is generated from such use.
        
        **3.6 Open-Source Contributions** â€” Use in connection with open-source software projects that are freely available to the public under an OSI-approved license, and where neither the project nor any output thereof is commercialized.
        
        > If your intended use is not listed above, it is NOT a Permitted Purpose. Uncertainty does not confer permission. Contact the Licensor at info@allthingsintelligence.com before proceeding.
        
        ---
        
        ## 4. Prohibited Uses
        
        The following uses are strictly prohibited under this License. Engaging in any Prohibited Use automatically and immediately terminates this License, constitutes copyright infringement, and may give rise to civil and criminal liability:
        
        - **Production or revenue-generating deployment.** Using the Software, any Modification thereof, or any Derivative Output in any production environment, live system, or operational workflow that directly or indirectly generates revenue, reduces costs for a commercial operation, supports client-facing services, or contributes to the financial performance of any individual or entity.
        - **Commercial product or service integration.** Incorporating the Software, any Modification, or any Derivative Output into any software product, platform, application, API, data pipeline, or service that is sold, licensed, subscribed to, or otherwise offered for monetary consideration.
        - **Startup and investor-facing use.** Using the Software to build, demonstrate, prototype, or pitch a product or service to investors, accelerators, venture capital firms, grant committees, or prospective customers in connection with any commercial venture â€” regardless of whether the venture has yet generated revenue.
        - **Hosted or managed service.** Providing the Software's functionality, in whole or in part, to any third party through a hosted, cloud-based, SaaS, PaaS, or managed service offering.
        - **Resale or sublicensing.** Selling, reselling, sublicensing, renting, leasing, lending, or otherwise transferring access to the Software or any rights under this License to any third party.
        - **Redistribution without authorization.** Distributing, publishing, uploading, or making available copies of the Software, modified or unmodified, to any third party without the Licensor's prior written consent. Authorized redistribution requires strict compliance with Section 7.
        - **Circumvention of License Key functionality.** Removing, disabling, bypassing, modifying, obscuring, or otherwise circumventing any License Key mechanism, feature gate, access control, authentication system, or entitlement check built into or associated with the Software.
        - **Removal of notices.** Deleting, altering, obscuring, or replacing any copyright notice, license notice, attribution notice, trademark notice, or other legal notice embedded in or distributed with the Software.
        - **Competing product development.** Using the Software, any Modification, or any Derivative Output to design, develop, train, benchmark, or evaluate any product, service, or software that competes with NeuralSmith or any other product offered by the Licensor.
        - **Reverse engineering for competitive purposes.** Decompiling, disassembling, or reverse engineering the Software for the purpose of creating a competing ML development tool or platform.
        - **Export control violations.** Exporting, re-exporting, or transferring the Software in violation of applicable export control laws and regulations.
        
        ---
        
        ## 5. Intellectual Property Ownership of Modifications & Derivative Outputs
        
        **5.1 Modifications to the Software** â€” Any Modification to the Software is and shall remain the exclusive property of the Licensor from the moment of its creation. The Licensee hereby irrevocably assigns all right, title, and interest in all Modifications to the Licensor, without further compensation.
        
        **5.2 Derivative Outputs** â€” All Derivative Outputs produced when the Software is used in connection with a Prohibited Use (including any Commercial Use) are and shall remain the exclusive property of the Licensor. Derivative Outputs produced solely in the course of Permitted Purposes remain the property of the Licensee.
        
        **5.3 License-Back for Permitted Modifications** â€” To the extent that any Modification is made under a Permitted Purpose, the Licensee grants to the Licensor a perpetual, irrevocable, worldwide, royalty-free, fully paid-up, non-exclusive license (with the right to sublicense) to use, reproduce, modify, prepare derivative works of, distribute, and otherwise exploit such Modification for any purpose.
        
        **5.4 Contributions** â€” If the Licensee submits any Contribution to the Licensor for inclusion in the Software, the Licensee represents that: (a) the Licensee has full authority to make the Contribution; (b) the Contribution does not infringe any third-party rights; and (c) the Licensee agrees to be bound by the Licensor's then-current Contributor License Agreement, available at neuralsmith.com.
        
        ---
        
        ## 6. Patent License
        
        Subject to the terms of this License, the Licensor grants the Licensee a limited, non-exclusive, non-transferable, royalty-free license under any patent claims that the Licensor can license that are necessarily infringed by the Software as delivered, to use the Software solely for Permitted Purposes.
        
        This patent license terminates automatically, effective immediately and without notice, if the Licensee (or any entity on whose behalf the Licensee acts) initiates, joins, or materially assists any legal or administrative proceeding alleging that the Software infringes any patent.
        
        ---
        
        ## 7. Permitted Redistribution
        
        The Licensee may redistribute unmodified copies of the Software to other individuals for Permitted Purposes only, subject to all of the following conditions:
        
        - The redistribution is made at no charge and not in connection with any commercial transaction
        - This License in its complete, unmodified form is included with every copy
        - All copyright notices, trademark notices, and attribution notices are preserved without alteration
        - The recipient is made clearly aware that their use is governed by this License and is restricted to Permitted Purposes
        - The Licensee obtains prior written authorization from the Licensor before distributing the Software through any public repository, package registry, marketplace, or platform other than as originally distributed by the Licensor
        
        ---
        
        ## 8. Attribution Requirements
        
        In any permitted use or redistribution of the Software, the Licensee must:
        
        - Retain all copyright notices in the form: Â© 2025 All Things Intelligence LLC. All rights reserved.
        - Include the following attribution in any documentation, research paper, presentation, or publication that describes work performed using the Software:
        
        > *"This work used NeuralSmith, an ML engineering platform developed by All Things Intelligence LLC (https://neuralsmith.com). Used under the NeuralSmith Non-Commercial Research & Evaluation License v1.0."*
        
        - Not use the name "NeuralSmith", "All Things Intelligence", or any associated logos, trademarks, or trade names in any manner that suggests endorsement, sponsorship, or affiliation without the Licensor's prior written consent.
        
        ---
        
        ## 9. Commercial Licensing
        
        This License does not grant any right to engage in Commercial Use or any Prohibited Use. If the Licensee wishes to use the Software for any purpose not expressly permitted by this License â€” including production deployment, commercial product integration, investor demonstrations, for-profit internal tooling, or redistribution as part of a commercial offering â€” the Licensee must obtain a Commercial License from the Licensor prior to commencing such use.
        
        To inquire about Commercial Licensing, contact: **info@allthingsintelligence.com** or visit **https://neuralsmith.com**.
        
        Use of the Software in any manner that exceeds the scope of this License without a valid Commercial License constitutes willful copyright infringement and may subject the Licensee to enhanced statutory damages of up to USD 150,000 per work infringed, injunctive relief, and recovery of the Licensor's attorneys' fees.
        
        ---
        
        ## 10. Termination
        
        **10.1 Automatic Termination** â€” Any breach of Sections 4, 5, 7, or 8 of this License automatically terminates this License immediately and without notice. Upon such termination, the Licensee must immediately cease all use of the Software and permanently destroy all copies in its possession, including any Modifications and Derivative Outputs.
        
        **10.2 Two-Strike Process for Other Breaches** â€” For breaches other than those specified in Section 10.1: (a) First Breach: The Licensor may provide written notice. If the Licensee cures the breach within thirty (30) days, rights are automatically reinstated. (b) Second or Subsequent Breach: Results in permanent, automatic termination without any cure period.
        
        **10.3 Effect of Termination** â€” Upon termination for any reason: (a) all licenses granted herein immediately cease; (b) the Licensor's rights in all Modifications and Derivative Outputs survive; (c) Sections 2, 5, 9, 10.3, 11, 12, and 13 survive termination indefinitely.
        
        ---
        
        ## 11. Disclaimer of Warranties
        
        THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTY OF ANY KIND. THE LICENSOR EXPRESSLY DISCLAIMS, TO THE FULLEST EXTENT PERMITTED BY APPLICABLE LAW, ALL WARRANTIES â€” WHETHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE â€” INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT; ANY WARRANTY THAT THE SOFTWARE WILL BE UNINTERRUPTED, ERROR-FREE, OR SECURE; AND ANY WARRANTY AS TO THE ACCURACY OR COMPLETENESS OF ANY OUTPUT PRODUCED BY THE SOFTWARE.
        
        ---
        
        ## 12. Limitation of Liability
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL THE LICENSOR, ITS OFFICERS, DIRECTORS, EMPLOYEES, AGENTS, LICENSORS, SUCCESSORS, OR ASSIGNS BE LIABLE TO THE LICENSEE OR ANY THIRD PARTY FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES; LOSS OF PROFITS, REVENUE, BUSINESS, DATA, GOODWILL, OR ANTICIPATED SAVINGS; BUSINESS INTERRUPTION OR SYSTEM FAILURE; OR ANY OTHER PECUNIARY LOSS ARISING OUT OF OR IN CONNECTION WITH THIS LICENSE OR THE USE OR INABILITY TO USE THE SOFTWARE.
        
        ---
        
        ## 13. Governing Law & Dispute Resolution
        
        This License shall be governed by and construed in accordance with the laws of the State of Wyoming, United States of America, without giving effect to any choice-of-law rules, and expressly excluding the United Nations Convention on Contracts for the International Sale of Goods (CISG) and the Uniform Computer Information Transactions Act (UCITA).
        
        Any dispute arising out of or relating to this License shall be subject to the exclusive jurisdiction of the state and federal courts located in Wyoming, United States of America.
        
        ---
        
        ## 14. General Provisions
        
        **14.1 Entire Agreement** â€” This License constitutes the entire agreement between the parties with respect to the use of the Software and supersedes all prior understandings, representations, and agreements.
        
        **14.2 Severability** â€” If any provision is held invalid or unenforceable, such provision shall be reformed to the minimum extent necessary, and the remaining provisions shall continue in full force and effect.
        
        **14.3 No Waiver** â€” The Licensor's failure to enforce any right or provision on any occasion shall not constitute a waiver of that right or provision.
        
        **14.4 No Assignment** â€” The Licensee may not assign, delegate, or transfer this License without the Licensor's prior written consent. Any purported assignment in violation of this provision is void. The Licensor may assign this License freely.
        
        **14.5 Updates to this License** â€” The Licensor reserves the right to update or replace this License at any time by publishing a new version at neuralsmith.com. Continued use of the Software after a new version is published constitutes the Licensee's acceptance of the updated terms.
        
        **14.6 Export Compliance** â€” The Licensee is solely responsible for compliance with all applicable export control laws and regulations in connection with its use of the Software.
        
        **14.7 Privacy & Data Processing** â€” The Software may collect limited telemetry data, usage statistics, and license verification information to support product improvement and license compliance. Such data is processed in accordance with the Licensor's Privacy Policy, available at neuralsmith.com.
        
        **14.8 Injunctive Relief** â€” The Licensee acknowledges that any breach of this License would cause irreparable harm to the Licensor for which monetary damages would be an inadequate remedy. Accordingly, the Licensor shall be entitled to seek equitable relief, including injunctive relief, without the requirement of posting a bond.
        
        **14.9 Interpretation** â€” This License shall be construed neither for nor against either party solely on account of authorship. Headings are for convenience only. The words "including" and "include" mean "including without limitation."
        
        ---
        
        *All Things Intelligence LLC*  
        info@allthingsintelligence.com Â· https://neuralsmith.com  
        Â© 2025 All Things Intelligence LLC. All rights reserved.
Keywords: machine-learning,neural-architecture-search,automl,deep-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: torch>=1.10.0
Requires-Dist: torchvision>=0.11.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost>=1.5.0
Requires-Dist: lightgbm>=3.3.0
Requires-Dist: pillow>=8.0.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: joblib>=1.0.0
Requires-Dist: imbalanced-learn>=0.8.0
Requires-Dist: momentfm==0.1.4; python_version < "3.12"
Requires-Dist: google-generativeai>=0.3.0
Requires-Dist: umap-learn>=0.5.3
Requires-Dist: aeon>=0.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: build>=0.10.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# 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)

```bash
cd CLI
pip install -e .
```

With development dependencies:

```bash
pip install -e ".[dev]"
```

### With Optional Features

```bash
# 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)

```bash
neuralsmith --config-key
```

Or set the environment variable directly:

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

### 2. Try CoPilot

```bash
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:**

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

**Tabular Classification:**

```bash
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.

```bash
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:**

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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:

```bash
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:

```bash
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:

```bash
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

```python
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

```python
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`:

```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

```bash
# 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:

```bash
python --version
```

### Missing Dependencies

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

### Memory Issues

Reduce image resolution and batch size:

```bash
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](https://neuralsmith.com/license.html) for details.

## Support

- Use CoPilot: `neuralsmith copilot`
- Check the training summary reports for model-specific guidance
- Email: info@neuralsmith.com
