Metadata-Version: 2.4
Name: neuralsmith-cli
Version: 1.0.0
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.

## Features

- 🖼️ **Image Classification** - Train models using Neural Architecture Search (14-model experiments)
- 📊 **Tabular Classification & Regression** - Train models on CSV data with EDA
- 📈 **Time Series Classification & Regression** - Train models on time series data
- 🏷️ **Auto Labeler** - Automatically label unlabeled data using weighted KNN
- 🤖 **CoPilot** - Interactive AI assistant for guidance and troubleshooting

## Functionality Docs

Each major functionality now has a dedicated in-package README:

- `neuralsmith/image_classification/README.md`
- `neuralsmith/tabular/README.md`
- `neuralsmith/timeseries/README.md`
- `neuralsmith/auto_labeler/README.md`
- `neuralsmith/copilot/README.md`
- `neuralsmith/README.md` (index + core package internals)

## Installation

### Prerequisites

- Python 3.8 or higher
- pip or pipx

```

### From PyPI (Future)

```bash
pipx install neuralsmith
```

## Quick Start

### 1. Configure API Key (for CoPilot)

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

Or set environment variable:
```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
```

## Commands

### Image Classification

Train image classification models using NAS:

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

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

**Example:**
```bash
neuralsmith tabular-classification \
  --data-path ./data.csv \
  --target-column species \
  --mode exhaustive \
  --output-dir ./results
```

### Tabular Regression

Same as classification, but for regression tasks:

```bash
neuralsmith tabular-regression \
  --data-path <csv> \
  --target-column <name> \
  [OPTIONS]
```

### Time Series Classification

Train classification models on time series data:

```bash
neuralsmith timeseries-classification \
  --data-path <csv> \
  [--time-column <name>] \
  --target-column <name> \
  [--window-size <n>] \
  [--mode fast|fast++|exhaustive] \
  [--split-method temporal|random] \
  [--train-percent 70.0] \
  [--val-percent 15.0] \
  [--test-percent 15.0] \
  [--random-state 42] \
  [--no-normalize] \
  [--epochs 10] \
  [--batch-size 32]
```

### Time Series Regression

Same as classification, but for regression:

```bash
neuralsmith timeseries-regression \
  --data-path <csv> \
  [--time-column <name>] \
  --target-column <name> \
  [--window-size <n>] \
  [OPTIONS]
```

Notes:
- `--data-path` can point to either a CSV file or a directory containing pre-windowed NumPy splits:
  - `X_train.npy`, `y_train.npy`, `X_val.npy`, `y_val.npy`, `X_test.npy`, `y_test.npy`
- For CSV input, `--time-column` and `--window-size` are required.
- For NumPy input, `--time-column` and `--window-size` are ignored.
- Default split is `--split-method temporal` to avoid overlap leakage between train/val/test windows.

### Auto Labeler

Automatically label unlabeled data:

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

### CoPilot

Start interactive AI assistant:

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

**Modes (default is Ask — plain chat, no autonomous tools):**

| Mode | Flag | Behavior |
|------|------|----------|
| Ask | _(default)_ | Answers questions; you run `!validate`, `!status`, `!watch` yourself. |
| Agent | `--agent` | The model can call read-only tools (inspect paths, CSV, validation, run status) and **propose** full `neuralsmith` training commands. Each training run is shown as an exact argv and runs only if you type `yes`. |
| Agent-plus (experimental) | `--agent-plus` | Same tools as Agent, but proposed training commands run **without** confirmation. Use only in trusted environments. |

Examples:

```bash
neuralsmith copilot --agent
neuralsmith copilot --agent-plus   # experimental
```

In CoPilot, you can:
- Ask questions about NeuralSmith commands
- Get help with workflows
- Validate datasets: `!validate <path>`
- Live status for running wizards (from another terminal):
  - `!status [path]` - read the newest `neuralsmith_run_status.json` under `--output-dir` (or the parent folder of `--output-path` for `auto-labeler`)
  - `!watch [path]` - poll status every ~2s until the run is `completed` or `failed`
- Type `help` for commands, `exit` to quit

Agent modes use the same `!` commands as Ask mode. Training wizards themselves are unchanged; the agent only invokes the existing CLI in a subprocess with an allowlisted set of flags.

#### Agent / Agent-plus Quick Guide

Use this when you want CoPilot to help prepare and run training commands end-to-end.

**Start modes**

```bash
neuralsmith copilot --agent
neuralsmith copilot --agent-plus   # experimental
```

**How `--agent` works (recommended default)**

1. You ask for a task (for example: "train a quick tabular classifier on this CSV").
2. CoPilot may inspect files / validate data with read-only tools.
3. CoPilot prints a proposed exact command, for example:
   - `python -m neuralsmith tabular-classification ...`
4. Nothing runs until you confirm by typing `yes`.
5. Training output streams in the same terminal.

**How `--agent-plus` works**

- Same planning/tool behavior as `--agent`
- Difference: proposed training commands run immediately without the `yes` confirmation step
- Use only in trusted, local environments

**What agent modes can do**

- Validate inputs with `!validate <path>`
- Check run snapshot with `!status [path]`
- Follow live progress with `!watch [path]`
- Propose and execute existing NeuralSmith training wizards (`image-classification`, `tabular-*`, `timeseries-*`, `auto-labeler`)

**Safe usage tips**

- Prefer `--agent` for normal use
- Provide explicit paths and target columns in your prompt to reduce retries
- Use `--agent-plus` only if you are comfortable with automatic execution

**Quick test with bundled sample data**

```text
!validate tests/data/tabular_classification/iris_like_100.csv
Train a quick tabular classification model on tests/data/tabular_classification/iris_like_100.csv using target column species and mode fast.
```

Example (two terminals):
1. Start a wizard with `--output-dir` (for example `./run_live_test`)
2. In CoPilot, run `!watch ./run_live_test` to keep getting posted while training runs

## Common Workflows

### Image Classification Workflow

1. **Prepare your images** in a folder structure:
   ```
   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/` directory

### Tabular Classification Workflow

1. **Prepare your CSV** with a 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 models** in `./results/models/`

### Time Series Workflow

1. **Prepare CSV** with time column and features

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 Your Trained Models

After training completes, NeuralSmith automatically generates comprehensive training summary reports and provides easy-to-use model loading utilities.

### Training Summary Report

After each training run, NeuralSmith generates a comprehensive report at:
- **Markdown Report:** `{output_dir}/training_summary_report.md`
- **JSON Report:** `{output_dir}/training_summary_report.json`

The report includes:
- **Executive Summary:** Total models trained, best model identification
- **Model Performance Comparison:** Ranked table of all models with metrics
- **Best Model Details:** Complete information about the best performing model
- **Model Usage Instructions:** Ready-to-use code examples

### Loading Models

#### Image Classification Models

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

# Load the trained model
model = load_model('results/model_*.pth')

# Preprocess an image
image = Image.open('your_image.jpg')
image = image.resize((64, 64))  # Match your training 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)

# Make prediction
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()}')
```

#### Tabular Classification/Regression Models

```python
from neuralsmith.model_loader import load_model
import pandas as pd

# Load model and preprocessing pipeline
model, preprocessor = load_model('results/models/best_model_*/')

# Load your new data
new_data = pd.read_csv('new_data.csv')

# Preprocess using the same pipeline (handles imputation, scaling, feature selection)
X_processed = preprocessor.transform(new_data)

# Make predictions
predictions = model.predict(X_processed)

# For classification, get probabilities
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}')
```

### Using CoPilot for Model Usage

After training, you can ask CoPilot for help using your models:

```bash
neuralsmith copilot
```

**Example Questions:**
- "How do I use the model I just trained?"
- "Generate code to load my model from results/"
- "Show me how to make predictions on new images"
- "How do I use my tabular model for batch predictions?"

### Best Practices

1. **Always check the training summary report** first for model details
2. **Use the same preprocessing** that was used during training
3. **Match input shapes** - especially for image models (size, channels)
4. **Handle device placement** - ensure data and model are on the same device
5. **Use CoPilot** for customized code generation based on your specific needs

## 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):
- `NEURALSMITH_GEMINI_API_KEY` - Gemini API key
- `NEURALSMITH_TEST_MODE` - Enable test mode (limits epochs/models)

## Getting Help

### Command Help
```bash
neuralsmith --help
neuralsmith image-classification --help
neuralsmith tabular-classification --help
```

### CoPilot Assistant
```bash
neuralsmith copilot
```

Then type:
- `help` - Show available commands
- `!validate <path>` - Validate a dataset
- Ask any question about NeuralSmith

## Troubleshooting

### API Key Issues
```bash
# Check if API key is set
neuralsmith --config-key

# Or use environment variable
export NEURALSMITH_GEMINI_API_KEY="your-key"
```

### Python Environment
Make sure you have Python 3.8+:
```bash
python --version
```

### Missing Dependencies
Install all dependencies:
```bash
pip install -e ".[copilot,auto-labeler]"
```

### Memory Issues
For large datasets, use smaller batch sizes or reduce image sizes:
```bash
neuralsmith image-classification \
  --data-path ./large_dataset \
  --target-size 64,64 \
  --batch-size 16
```

### Model Loading Issues

**Model Not Found:**
- Check the training summary report for exact model paths
- Verify the output directory path is correct

**Shape Mismatch Errors:**
- For images: Ensure image size matches training size
- For tabular: Ensure feature names match training features

**Preprocessing Errors:**
- Load the preprocessor from the same model directory
- Use the same preprocessing pipeline that was used during training

**Ask CoPilot:**
If you encounter issues, ask CoPilot:
- "Help me debug my model loading code"
- "Why am I getting a shape mismatch error?"
- "How do I preprocess my data correctly?"

## Testing

The repository includes a comprehensive test suite in the `tests/` directory.

### Running Tests

Install test dependencies:
```bash
pip install -e ".[dev]"
```

Run all tests:
```bash
pytest tests/ -v
```

Run fast tests only (skip slow training tests):
```bash
pytest tests/ -v -m "not slow"
```

Run a specific test file:
```bash
pytest tests/test_image_classification.py -v
```

### Test Coverage

The test suite includes:
- CLI entry point and argument parsing tests
- Image classification wizard tests
- Tabular classification/regression wizard tests
- Time series classification/regression wizard tests
- Auto-labeler wizard tests
- CoPilot functionality tests
- Configuration management tests
- Integration tests for full workflows

Test datasets are stored in `tests/data/` and include small synthetic datasets for all wizard types.

## Development

### Setup

1. **Clone the repository** (if not already done)
2. **Navigate to CLI directory:**
   ```bash
   cd CLI
   ```

3. **Install in development mode:**
   ```bash
   pip install -e ".[dev]"
   ```

### Project Structure

```
CLI/
├── neuralsmith/          # Main package
│   ├── cli.py           # CLI entry point
│   ├── config.py        # Configuration management
│   ├── model_loader.py  # Model loading utilities
│   ├── reporting.py     # Report generation
│   ├── image_classification/
│   ├── tabular/
│   ├── timeseries/
│   ├── auto_labeler/
│   └── copilot/
├── Legacy_utils/         # Shared Python scripts
├── scripts/             # Utility scripts
├── pyproject.toml       # Package configuration
└── README.md            # This file
```

### Development Workflow

1. **Make changes** to code in `neuralsmith/`
2. **Add tests** for new functionality (if applicable)
3. **Test manually** to ensure everything works
4. **Update documentation** in `README.md` if needed

### Building the Package

```bash
cd CLI
python -m build
```

This creates `dist/` with source distribution and wheel.

### Code Style

- Follow PEP 8
- Use type hints where possible
- Add docstrings to public functions
- Keep functions focused and testable

### Adding New Features

1. **Implement the feature** in appropriate module
2. **Add CLI command** in `neuralsmith/cli.py`
3. **Update documentation** in `README.md`
4. **Test end-to-end** with real data

## Requirements

- Python 3.8+
- See `pyproject.toml` for full dependency list

## License

NeuralSmith

## Support

For issues and questions:
- Use CoPilot: `neuralsmith copilot`
- Check the training summary reports for model-specific guidance
- Review this README for common workflows and troubleshooting
