Metadata-Version: 2.4
Name: aiforge-studio
Version: 0.1.4
Summary: No-code neural network studio in your terminal: build, train, fine-tune and export PyTorch models.
Author-email: Duc Dinh <dinhduc4work@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/ducdinh-codehub/ai-forge
Project-URL: Source, https://github.com/ducdinh-codehub/ai-forge
Project-URL: Issues, https://github.com/ducdinh-codehub/ai-forge/issues
Keywords: no-code,deep-learning,machine-learning,neural-network,pytorch,model-builder,tui,terminal,textual,transfer-learning,fine-tuning,cnn,transformer,computer-vision,text-classification,onnx,education,beginner-friendly,automl,training,visual-model-builder,deep-learning-gui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.5
Requires-Dist: torchvision>=0.20
Requires-Dist: textual>=8.0
Requires-Dist: safetensors>=0.4
Requires-Dist: onnx>=1.15
Requires-Dist: pillow>=10
Requires-Dist: psutil>=5.9
Provides-Extra: nvidia
Requires-Dist: nvidia-ml-py>=12; extra == "nvidia"
Dynamic: license-file

# AIForge

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-3776AB?style=flat"></a>
  <a href="https://pytorch.org"><img alt="PyTorch 2.5+" src="https://img.shields.io/badge/PyTorch-2.5%2B-EE4C2C?style=flat"></a>
  <a href="https://textual.textualize.io"><img alt="Textual 8.0+" src="https://img.shields.io/badge/Textual-8.0%2B-7B2CBF?style=flat"></a>
  <a href="https://onnx.ai"><img alt="ONNX export" src="https://img.shields.io/badge/ONNX-export-E8A0BF?style=flat"></a>
  <br>
  <a href="https://pypi.org/project/aiforge-studio/"><img alt="pypi package" src="https://img.shields.io/pypi/v/aiforge-studio?label=pypi%20package&color=4c1&style=flat"></a>
  <a href="https://pepy.tech/project/aiforge-studio"><img alt="downloads" src="https://img.shields.io/pepy/dt/aiforge-studio?label=downloads&color=0e75b6&style=flat"></a>
  <img alt="AI Powered" src="https://img.shields.io/badge/AI-Powered-ff69b4?style=flat">
  <a href="https://github.com/ducdinh-codehub/ai-forge/blob/main/LICENSE"><img alt="license MIT" src="https://img.shields.io/badge/license-MIT-D4A72C?style=flat"></a>
  <br>
  <img alt="status alpha" src="https://img.shields.io/badge/status-alpha-E05D44?style=flat">
  <a href="https://github.com/ducdinh-codehub/ai-forge/commits/main"><img alt="development active" src="https://img.shields.io/badge/development-active-44CC11?style=flat"></a>
</p>

**Build, train and use your own AI models in the terminal, without writing any code.**

![AIForge model library](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/10-home.png)

With the mouse or keyboard you can:

1. **Design** a neural network by picking layers from a list
2. **Train** it on a CSV table, text, images, or a famous public dataset
3. **Fine-tune** a trained model for a new, related task
4. **Use** it to make predictions
5. **Export** it for Python, ONNX Runtime, mobile apps and more

No PyTorch or Python knowledge needed. The built-in **Guide** (`g`) teaches the ML basics.

## Contents

1. [Install](#1-install)
2. [Quick start: your first model in 5 minutes](#2-quick-start-your-first-model-in-5-minutes)
3. [The screens](#3-the-screens)
4. [Data](#4-data)
5. [Which template should I choose?](#5-which-template-should-i-choose)
6. [Reading the training charts](#6-reading-the-training-charts)
7. [Keyboard shortcuts](#7-keyboard-shortcuts)
8. [Troubleshooting](#8-troubleshooting)
9. [Where are my files?](#9-where-are-my-files)
10. [For developers](#10-for-developers)

---

## 1. Install

**You need:** Python 3.10+, about 2 GB of disk space (mostly PyTorch), and a terminal window
of at least **120 × 35**. A GPU is optional: NVIDIA (CUDA) and Apple Silicon (MPS) are used
automatically.

```bash
pipx install aiforge-studio      # recommended (or: pip install aiforge-studio)
aiforge                          # start the app
```

<details>
<summary>No pipx yet? / NVIDIA GPU stats / install from source</summary>

```bash
# Install pipx once, then reopen the terminal
python3 -m pip install --user pipx && python3 -m pipx ensurepath

# Show GPU usage and temperature on NVIDIA cards
pipx inject aiforge-studio nvidia-ml-py

# Update later
pipx upgrade aiforge-studio

# From source (developers)
git clone https://github.com/ducdinh-codehub/ai-forge.git && cd ai-forge
python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/aiforge                # Windows: .venv\Scripts\aiforge
```
</details>

**Moving around:** click with the mouse, or press the keys shown in the bottom bar.
`Tab` = next box · `Enter` = confirm · `Esc` = back · `q` = quit.

---

## 2. Quick start: your first model in 5 minutes

You'll teach a model to tell apart three spirals of points. The data is built in.

| Step | Do this |
|---|---|
| **1. Create** | Press `n`. Name it `spiral-classifier`, keep **Tabular data** → **MLP classifier**, click **Create & open builder**. |
| **2. Look** | The builder shows every layer, its shape and parameter count. Press `Ctrl+S`, then `Esc`. |
| **3. Train** | Press `t`. Choose *Synthetic toy data* → **spirals**, click **Load data**, then **Auto-fit model to data**. Set Epochs `40`, Learning rate `0.005`, click **▶ Start**. |
| **4. Use** | Press `p`, type `0.1, 0.45`, press Enter. The model answers **arm-0**. |
| **5. Export** | Press `x`, tick formats with the space bar, click **⇩ Export**. |

![Model builder](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/03-builder.png)

![Training](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/06-train-done.png)

Loss going **down** and accuracy going **up** means it's learning. AIForge always saves the
**best** epoch. 🎉 You built, trained, used and exported a neural network without code.

---

## 3. The screens

### Home (model library)
Your models on the left, details and training history on the right. Every action has a button
and a key (see [shortcuts](#7-keyboard-shortcuts)).

### Builder: design the model
| I want to… | Do this |
|---|---|
| Add a layer | `a`, highlight a layer, `Enter` |
| Edit a layer | Select it, change the boxes on the right |
| Change input size / type / task | Select the **Input** row |
| Move · copy · remove a layer | `Shift+↑/↓` · `Ctrl+D` · `Del` |
| Undo · save | `Ctrl+Z` · `Ctrl+S` |
| Learn what a layer does | `Ctrl+E` (Explain tab) or `?` (full Guide) |

Mistakes show up in red right away. Layers you don't change **keep what they learned**.

### Train: teach the model
1. **① Data:** choose a source and click **Load data** (see [Data](#4-data)). A yellow warning
   means the model doesn't fit the data: click **Auto-fit model to data**. If the structure
   is wrong (e.g. a table model for images), **🔧 Fix model…** offers checked fixes.
2. **② Settings:** the defaults are fine to start. Common ones:

   | Setting | Meaning | Start with |
   |---|---|---|
   | Epochs | Passes through the data | 10–50 |
   | Batch size | Examples per update | 32–128 |
   | Learning rate | Step size: too high = unstable, too low = slow | 0.001 |
   | Early stop | Stop after N epochs with no improvement (0 = off) | 0 or 5 |
   | Device | CPU or GPU | auto |

3. Click **▶ Start** (`Ctrl+R`). Watch the charts, the log and the **💻 This computer** panel
   (CPU, RAM, GPU usage, samples/s).

Press **F1** for the **📖 Guide panel**: a live diagnosis of your run ("✅ healthy",
"⚠️ overfitting…") and every setting explained with your values.

### Fine-tune: reuse a trained model
Like Train, plus: **freeze** layers you want to keep (try **Freeze all but head**), optionally
reset the output layer, and save under a **new name** so the original stays safe.

### Use: get predictions
| Model trained on | Type |
|---|---|
| A table | Values in column order: `6, 3.5, red` |
| Text | A sentence: `what an amazing movie` |
| Images | An image path: `~/Pictures/cat.jpg` |

Give it a whole CSV or image folder for **batch prediction** (writes a CSV with predictions).

### Export
| Format | Use it to… |
|---|---|
| AIForge bundle `.zip` | Back up or share with another AIForge user |
| Weights `.pt` / `.safetensors` | Load in your own PyTorch / Hugging Face code |
| PyTorch code `.py` · JSON · summary | Read, edit or document the model |
| TorchScript · ONNX | Run in C++, mobile, ONNX Runtime, TensorRT, browsers… |

### Import
Press `i`: AIForge bundles, `.json`, `.safetensors`, or a PyTorch `nn.Sequential` saved with
`torch.save`. ⚠️ **Only import `.pt`/`.pth` files you trust**, as they can run code.

### Guide
Press `g`. Beginner lessons (ML basics, model types), a step-by-step walk-through of your
model with a design review, and an encyclopedia of every layer.

![Guide](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/13-guide-overview.png)

---

## 4. Data

### Option A: download a famous dataset (easiest)

Press `s` on the home screen (or **🗄 Get a famous dataset…** on the Train screen). Pick one,
press **⇩ Download**, then **▶ Train on it**. AIForge fills in all the fields and loads it.

![Dataset hub](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/17-datasets.png)

| Model type | Datasets |
|---|---|
| 📊 Tabular | Iris · Wine · Breast cancer · Adult income · Red wine quality · California housing |
| 🖼 Vision | MNIST · Fashion-MNIST · CIFAR-10 · CIFAR-100 · Imagenette · Oxford-IIIT Pets |
| 💬 Text | SMS Spam · SST-2 · IMDB reviews · AG News |

All come from their official sources (UCI, Stanford, Oxford, U. Toronto, Zalando, fast.ai).
Each one shows its publisher, license, size and the templates that suit it. Downloads show
their progress and can be cancelled:

![Downloading a dataset](https://raw.githubusercontent.com/ducdinh-codehub/ai-forge/main/docs/images/18-datasets-download.png)

### Option B: your own files

Click **📂 Browse** to pick a file; the preview shows its columns or classes.
Sample files are under **📦 Examples** in the browser.

| Kind | Format |
|---|---|
| **Table** (CSV) | One row per example. The **last column** is predicted (or choose another). Text columns and missing numbers are handled for you. |
| **Text** (CSV) | A text column and a label column: `"great movie",pos` |
| **Images** | A folder with **one sub-folder per class** (`cat/`, `dog/`). Images are resized automatically. |

> **How much data?** For images, aim for 50–100+ per class. With fewer, use a
> **Transfer learning** template.

---

## 5. Which template should I choose?

| Your data | Template |
|---|---|
| 📊 Table → predict a category / a number | MLP classifier / MLP regressor |
| 🖼 Small grayscale images (28×28) | Small CNN |
| 🖼 Small colour images (32×32) | CNN (CIFAR-10) · ViT · Hybrid CNN + Transformer |
| 🖼 Your own photos, from scratch | Deep CNN (64×64) |
| 🖼 Photos, especially with few examples | Transfer learning: **MobileNetV3** (fast) · **ResNet18** · **EfficientNet-B0** (accurate) |
| 💬 Sentences / reviews | Text Transformer classifier |
| 💬 Longer or harder texts | BERT-style Transformer |
| 💬 Simpler / faster | LSTM · bidirectional GRU · Bag of words (fastest) |
| ✎ Design it all yourself | Blank |

You can change any layer after creating the model.

---

## 6. Reading the training charts

| You see | Meaning | Do this |
|---|---|---|
| Both losses go down and level off | 👍 Learning well | Nothing |
| Train loss down, **val loss up** | Overfitting (memorizing) | Add Dropout, fewer epochs, Early stop, more data |
| Both stay high | Underfitting | More epochs, bigger model, higher learning rate |
| Lines jump around | Learning rate too high | Lower it (0.001 → 0.0003) |
| Loss is `nan` | Training broke | Much lower learning rate, start again |

New to the words (epoch, loss, overfitting…)? Press `g` → **🎓 ML basics**.

---

## 7. Keyboard shortcuts

| Home | | Builder | | Train | |
|---|---|---|---|---|---|
| `n` | New | `a` | Layer list | `Ctrl+R` | Start |
| `i` | Import | `Enter` | Add layer | `F1` | Guide panel |
| `e` | Edit | `Del` | Remove layer | `<` `>` | Panel wider / narrower |
| `t` | Train | `Shift+↑/↓` | Move layer | `Esc` | Back |
| `f` | Fine-tune | `Ctrl+D` | Duplicate layer | | |
| `p` | Use | `Ctrl+Z` | Undo | | |
| `x` | Export | `Ctrl+S` | Save | | |
| `s` | Datasets | `Ctrl+E` | Explain tab | | |
| `g` | Guide | `?` | Full guide | | |
| `w` `c` `r` `d` | Load weights · Duplicate · Rename · Delete | | | | |

Everywhere: `Esc` back · `Tab` next · `Ctrl+P` command palette · `Ctrl+Q` quit.

---

## 8. Troubleshooting

| Problem | Fix |
|---|---|
| `command not found: aiforge` | Run `python3 -m pipx ensurepath` and reopen the terminal (from source: `.venv/bin/aiforge`) |
| Old models missing after an update | Start AIForge in the folder containing `workspace/`, or run `aiforge -w path/to/workspace` |
| Screen looks cut off / odd symbols | Enlarge the terminal (120×35+); use iTerm2 or Windows Terminal with a font like JetBrains Mono |
| "Model input is … but data is …" | Click **Auto-fit model to data** |
| "Final output must be a flat vector" | Click **🔧 Fix model…** and pick a fix |
| Training is slow | Check *Training on* in the 💻 panel, set Device to `auto`, or set **Max samples** to e.g. `5000` |
| GPU "none found" | NVIDIA: install the CUDA build of PyTorch from [pytorch.org](https://pytorch.org/get-started/locally/) |
| A dataset download fails | Check your internet and try again; partial files are removed automatically |
| Predictions look random | Make sure the model shows *trained* and check its validation accuracy |

---

## 9. Where are my files?

Everything lives in one workspace folder: **`~/AIForge`** by default (or `./workspace` if it
exists, or `aiforge -w <folder>` / `AIFORGE_WORKSPACE`).

```
AIForge/
├── models/<name>/     spec.json (structure) · weights.pt · history.json
├── exports/           files created by Export
├── data/              downloaded datasets (data/hub/ for the dataset hub)
└── settings.json      your preferences
```

---

## 10. For developers

```
aiforge/
├── layers.py     layer registry: settings, building, parameter formulas
├── spec.py       model description, workspace storage, templates, code generation
├── data.py       dataset loaders and input preprocessing
├── hub.py        dataset hub: catalog of trusted datasets, download + conversion
├── trainer.py    training / fine-tuning loop
├── predict.py    single and batch predictions
├── model_io.py   export and import
├── guide.py      layer encyclopedia, model walk-through, design review
├── learn.py      beginner lessons
├── fixes.py      fixes for models that don't fit the data
├── sysinfo.py    hardware specs and live usage
└── tui/          the Textual interface (one module per screen)
docs/make_screenshots.py   regenerates the README screenshots
```

**Release:** bump `__version__` in `aiforge/__init__.py`, then `python -m build && twine upload dist/*`.

Built with [PyTorch](https://pytorch.org) and [Textual](https://textual.textualize.io) ·
[MIT License](https://github.com/ducdinh-codehub/ai-forge/blob/main/LICENSE)
