Metadata-Version: 2.4
Name: fattummy
Version: 0.5.4
Summary: A declarative, ultra-minimalist ML framework for zero-boilerplate hardware-agnostic inference and training.
Project-URL: Homepage, https://github.com/shukladwij5-maker/fattummy
Author-email: Origin-Labs <Shukladwij5@gmail.com>
License-Expression: GPL-3.0
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Requires-Dist: anthropic
Requires-Dist: datasets
Requires-Dist: google-genai
Requires-Dist: huggingface-hub
Requires-Dist: lion-pytorch
Requires-Dist: openai
Requires-Dist: torch
Requires-Dist: transformers
Provides-Extra: all
Requires-Dist: anthropic; extra == 'all'
Requires-Dist: datasets; extra == 'all'
Requires-Dist: google-genai; extra == 'all'
Requires-Dist: huggingface-hub; extra == 'all'
Requires-Dist: openai; extra == 'all'
Requires-Dist: torch; extra == 'all'
Requires-Dist: transformers; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic; extra == 'anthropic'
Provides-Extra: data
Requires-Dist: datasets; extra == 'data'
Requires-Dist: huggingface-hub; extra == 'data'
Provides-Extra: gemini
Requires-Dist: google-genai; extra == 'gemini'
Provides-Extra: hf
Requires-Dist: torch; extra == 'hf'
Requires-Dist: transformers; extra == 'hf'
Provides-Extra: native
Requires-Dist: torch; extra == 'native'
Provides-Extra: openai
Requires-Dist: openai; extra == 'openai'
Provides-Extra: train
Requires-Dist: torch; extra == 'train'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/pypi/v/fattummy?color=7c3aed&label=fattummy&style=for-the-badge" alt="PyPI Version">
  <img src="https://img.shields.io/pypi/pyversions/fattummy?color=06b6d4&style=for-the-badge" alt="Python Versions">
  <img src="https://img.shields.io/github/license/shukladwij5-maker/fattummy?color=10b981&style=for-the-badge" alt="License">
  <img src="https://img.shields.io/badge/status-experimental-f59e0b?style=for-the-badge" alt="Status">
</p>

<h1 align="center">🍔 FatTummy</h1>
<p align="center"><b>The zero-boilerplate ML framework that trains, chats, and predicts — in one line.</b></p>
<p align="center">
  Native models · HuggingFace · OpenAI · Anthropic · Gemini · Ollama · CSV Forecasting
</p>

---

## What is FatTummy?

FatTummy is an all-in-one Python ML toolkit built for people who want to **build and use language models without spending weeks on boilerplate**.

It wires together every stage of the ML workflow — dataset loading, training, inference, and prediction — behind a single, clean builder API. Switch from a local native model to GPT-4o to a HuggingFace checkpoint by changing one word.

> **"Using FatTummy just beats fiddling with PyTorch for centuries."**
> — Origin-Labs

---

## ✨ Features at a Glance

| Feature | Detail |
|---|---|
| 🔧 **Zero boilerplate** | `ft.engine("mooe").data("roneneldan/TinyStories").finetune()` — that's it |
| 🧠 **Native MOOE architecture** | Built-in Mixture-of-Optimized-Experts model, no external dependencies |
| 🌊 **SpaceByte encoding** | Byte-level tokenization — train on raw text, no vocab needed |
| 📦 **HuggingFace native** | Stream any HF dataset or load any HF model with one call |
| ☁️ **Cloud adapters** | OpenAI, Anthropic (Claude), Google Gemini — same API for all |
| 🤗 **Ollama support** | Local LLM inference via Ollama, no config files |
| 📈 **CSV forecasting** | Adaptive time-series prediction from any CSV file |
| ⚡ **Auto dependency install** | First `import FatTummy` silently installs everything missing |
| 🎛️ **Full training control** | Optimizers, schedulers, warmup, gradient clipping — all chainable |
| 🧪 **175+ tests passing** | Battle-tested across real HF datasets and native model architectures |

---

## 🚀 Installation

```bash
pip install fattummy
```

On **first import**, FatTummy automatically detects and installs any missing optional dependencies:

```python
import FatTummy as ft
# FatTummy: installing missing dependencies: torch, datasets ...
# FatTummy: dependencies ready.
```

> **Recommended:** Python 3.11 or 3.12.
> Python 3.14 works for API chat, but PyTorch native training is best on 3.11/3.12.

---

## ⚡ Quick Start

### 1 — Interactive Wizard (Easiest)

```python
import FatTummy as ft
ft.build()
```

The terminal launches a wizard — pick an action, fill in the blanks, and you're training or chatting in minutes.

---

### 2 — Native Model (MOOE)

Train FatTummy's built-in **Mixture-of-Optimized-Experts** model on any dataset:

```python
import FatTummy as ft

ft.engine("mooe") \
  .modelbuild("small") \
  .data("roneneldan/TinyStories") \
  .epochs(3) \
  .finetune()

print(ft.generate("Once upon a time"))
```

---

### 3 — Fine-Tune a HuggingFace Model

```python
import FatTummy as ft

ft.engine("hf") \
  .type("mistralai/Mistral-7B-v0.1") \
  .data("tatsu-lab/alpaca") \
  .epochs(1) \
  .finetune()

ft.chat()
```

---

### 4 — Cloud Chat (OpenAI / Anthropic / Gemini)

```python
import FatTummy as ft

ft.engine("openai").key("sk-...").chat()

# Or Anthropic Claude:
ft.engine("anthropic").key("sk-ant-...").chat()

# Or Google Gemini:
ft.engine("gemini").key("AIza...").chat()
```

---

### 5 — CSV Time-Series Forecasting

```python
import FatTummy as ft

results = ft.predict_csv(
    "sales_data.csv",
    target_column="revenue",
    steps=7,            # predict 7 days ahead
    date_column="date"
)
print(results)
```

Or pass a raw list:

```python
ft.predict([100, 105, 98, 112, 130, 145], steps=3)
# → [158.2, 172.0, 186.4]
```

---

## 🏗️ Supported Engines

| Engine | Type | Description |
|--------|------|-------------|
| `mooe` | Native | Mixture-of-Optimized-Experts (built-in, no API key) |
| `lion` | Native | Lion-optimizer native model |
| `spacebyte` | Native | Byte-level tokenization, vocab-free training |
| `hf` | Local | Any HuggingFace Transformers model |
| `ollama` | Local | Local inference via Ollama runtime |
| `openai` | Cloud | GPT-4o, GPT-4, GPT-3.5, and all OpenAI models |
| `anthropic` | Cloud | Claude 3, Claude Sonnet, Haiku |
| `gemini` | Cloud | Gemini 1.5 Pro/Flash and all Google models |

---

## 🎛️ Full Builder API

Every method is chainable and returns the engine for fluent composition:

```python
import FatTummy as ft

ft.engine("mooe")           # pick engine
  .modelbuild("small")      # model scale: tiny / small / medium / large
  .data("user/dataset")     # HF repo, local .txt/.csv/.json, or raw text
  .epochs(5)                # training epochs
  .token_limit(512)         # max tokens to generate
  .optimizer("lion")        # adamw | lion | sgd | adagrad
  .lr_scheduler("cosine")   # none | cosine | linear
  .weight_decay(0.01)       # L2 regularization
  .warmup(100)              # warmup steps
  .clip_grad(1.0)           # gradient clipping norm
  .quantize("int8")         # quantization hint for HF models
  .temp(0.8)                # generation temperature
  .finetune()               # train

result = ft.generate("The future of AI is")
```

---

## 📦 Dataset Handling

FatTummy auto-detects your data source:

| Source | Example | Mode |
|--------|---------|------|
| HuggingFace repo | `"roneneldan/TinyStories"` | Stream if > 500 MB |
| Local `.txt` | `"corpus.txt"` | Full load |
| Local `.json` / `.jsonl` | `"alpaca.json"` | Full load |
| Local `.csv` | `"data.csv"` | Full load |
| Multiple sources | `"src1, src2"` | Mixed |

**Non-standard schemas are handled automatically** — `instruction/output`, `text`, `conversations`, `code`, and more field layouts all work out of the box.

---

## 🧠 MOOE Architecture

FatTummy's built-in **Mixture-of-Optimized-Experts (MOOE)** model is a lightweight, from-scratch transformer designed for fast experimentation:

```
Input → Embedding → [MOOE Layer × N] → LM Head → Output
                         ↓
               Router (softmax gate)
               → Top-K expert selection
               → Expert FFN (GELU)
               → Weighted sum
```

| Parameter | Tiny | Small | Medium |
|-----------|------|-------|--------|
| Hidden size | 128 | 256 | 512 |
| Experts | 4 | 4 | 8 |
| Layers | 2 | 4 | 6 |
| Vocab | 32k / 256* | 32k / 256* | 32k / 256* |

*256 when SpaceByte byte-level encoding is enabled.

---

## 🌊 SpaceByte — Byte-Level Training

No vocabulary, no tokenizer. Train directly on raw bytes:

```python
import FatTummy as ft

ft.engine("spacebyte") \
  .modelbuild("small") \
  .data("my_raw_logs.txt") \
  .finetune()

print(ft.generate("ERROR: connection"))
```

SpaceByte uses `vocab_size=256` (all possible bytes) — perfect for code, logs, and multilingual data.

---

## 🧪 Run in Google Colab

```python
!pip install fattummy

import FatTummy as ft

# API chat (no GPU needed)
ft.engine("openai").key("sk-...").chat()
```

```python
# Or train a native model (free Colab GPU)
ft.engine("mooe").modelbuild("small").data("roneneldan/TinyStories").epochs(2).finetune()
```

> Colab is preferred over Kaggle for interactive wizard mode.

---

## 🔒 HuggingFace Token

For gated models and private datasets:

```python
import FatTummy as ft

ft.hf_login("hf_your_token_here") \
  .engine("hf") \
  .type("meta-llama/Llama-2-7b-chat-hf") \
  .chat()
```

Or set it as an environment variable: `HF_TOKEN=hf_...`

---

## 🗂️ Package Structure

```
FatTummy/
├── __init__.py          # Global API + auto-installer hook
├── engine.py            # Builder engine (the core orchestrator)
├── installer.py         # Silent dependency auto-installer
├── interactive.py       # Terminal wizard (ft.build())
├── predictor.py         # CSV / numeric forecasting
├── exceptions.py        # Typed error classes
├── models/
│   └── mooe.py          # Native MOOE architecture
├── data/
│   └── loader.py        # HF + local dataset resolution
├── tuning/
│   └── trainer.py       # Training loop (epochs, checkpointing)
└── inference/
    ├── cloud_adapters.py # OpenAI / Anthropic / Gemini
    └── local_adapters.py # HuggingFace / Ollama
```

---

## 📊 Real-World Scenarios Tested

FatTummy is verified against real production-style workloads:

- ✅ **E-commerce sales forecasting** — CSV-based multi-step prediction
- ✅ **Log anomaly analysis** — byte-level SpaceByte training on server logs
- ✅ **Support knowledge base** — Alpaca-style instruction fine-tuning
- ✅ **Streaming large HF datasets** — TinyStories, WikiText-2, Alpaca (live HF Hub)
- ✅ **End-to-end: train → generate** — Full pipeline in < 10 lines of code

---

## 🛣️ Roadmap

- [ ] LoRA / QLoRA adapters for efficient fine-tuning
- [ ] GGUF / llama.cpp inference backend
- [ ] Model merging and SLERP interpolation
- [ ] FatTummy Hub — community model sharing
- [ ] Web UI dashboard (already in `app.py`)
- [ ] Stable v1.0 release

---

## 🤝 Contributing

FatTummy is **100% open-source and free**. Contributions, issues, and feature requests are welcome.

```bash
git clone https://github.com/shukladwij5-maker/fattummy
cd fattummy
pip install -e ".[all]"
pytest tests/
```

---

## 📄 License

GNU General Public License v3.0 — see [LICENSE](LICENSE) for details.

---

## 💬 Philosophy

> FatTummy is built for **everyone** — researchers, engineers, students, and people with zero ML experience who just want AI to work.
>
> No configuration files. No YAML hell. No 300-line training scripts.
> Just Python.

<p align="center">Made with ❤️ by <a href="https://github.com/shukladwij5-maker">Origin-Labs</a></p>
