# FineTuneMyAI

> The cloud coordinates. Your hardware computes. Zero weights, private corpora, or training prompts ever leave your workstation.

FineTuneMyAI is a local-first, privacy-preserving AI fine-tuning, retrieval-augmented generation (RAG), and evaluation platform. It supports parameter-efficient fine-tuning (PEFT) via LoRA, QLoRA (4-bit NormalFloat NF4), and DoRA on local consumer and workstation hardware including Apple Silicon (MLX framework) and NVIDIA GPUs (CUDA).

## Core Architectural Invariants

1. **Zero-Upload Privacy Policy**: Model weights, training datasets, adapter checkpoints, vector embeddings, and prompt completions remain strictly on the user's workstation. The cloud control plane exclusively coordinates scheduling, telemetry, and job status using opaque identifiers (`dev_*`, `model_*`, `corpus_*`, `job_*`).
2. **Deterministic Opaque Identifiers**: Local filesystem paths are never sent over the network. The local daemon generates SHA-256 derived hashes that map to local paths only on the compute node.
3. **Automated VRAM Headroom Budgeting**: The platform calculates peak memory requirements (weights + activations + optimizer states) and enforces a 15-20% safety headroom to prevent out-of-memory (OOM) crashes.
4. **No Universal Best-K Invariant**: Clearly distinguishes between LoRA Rank ($r$, typically 8-64), Retrieval Candidate $k$ (vector search 10-50), Lexical Reranker $k$ (3-5), and Generation Top-P/Top-K.

## Key Subsystems

- **Fine-Tuning Studio (`/app/training`)**: Orchestrates LoRA and QLoRA fine-tuning with automated pre-flight checks, 3 intuitive goal presets (Fast Prototyping, Balanced Adaptation, High-Quality SFT), and unrestricted expert controls for 12 low-level hyperparameters.
- **Corpora & Quality Auditor (`/app/corpora`)**: Ingests JSONL, CSV, and plain text datasets with transparent 0-100 quality scoring across 4 pillars: Completeness, Uniqueness, Length Distribution, and Hygiene. Automatically creates 85/15 train/valid splits.
- **Local RAG Studio (`/app/rag`)**: On-device vector indexing and dual-stage semantic retrieval (dense cosine similarity + keyword-density cross-encoder re-ranking).
- **Evaluation Playground (`/app/inference`)**: Side-by-side comparative generation comparing base models against fine-tuned adapters with live streaming tokens, hardware-measured latency (ms), and throughput (tokens/sec).
- **Compute Node Daemon (`agent/agent.js`)**: Lightweight node agent executing ML jobs locally and reporting status via cryptographic HMAC heartbeat.

## Documentation & Technical References

- [Installation & Quickstart](https://finetunemyai.com/docs/installation): How to install and configure the native runner on macOS, Linux, and Windows.
- [Device Pairing Protocol](https://finetunemyai.com/docs/pair-device): Ephemeral 6-digit one-time code pairing and cryptographic HMAC mutual authentication.
- [Local Model Registry](https://finetunemyai.com/docs/models): Auto-scanning Hugging Face cache, Ollama models, and local weights without path disclosure.
- [Corpus Quality & Splits](https://finetunemyai.com/docs/corpus): Data cleaning heuristics, deduplication, and automated train/validation split generation.
- [Fine-Tuning Hyperparameters](https://finetunemyai.com/docs/fine-tuning): Mathematical guidance on LoRA rank, alpha scaling ($\alpha = 2 \times r$), learning rate, and QLoRA 4-bit calibration.
- [Local RAG Architecture](https://finetunemyai.com/docs/rag): Semantic chunking, 384-dimensional vector embedding, and hybrid retrieval mechanics.
- [VPS & Server Deployment](https://finetunemyai.com/docs/vps-deployment): Production deployment on Ubuntu/Debian VPS via Docker Compose, Systemd, Nginx reverse proxy, and Let's Encrypt SSL.
- [CyberPanel & OpenLiteSpeed](https://finetunemyai.com/docs/cyberpanel-deployment): Native non-Docker deployment on CyberPanel VPS using native MariaDB (port 3306), PM2, and OpenLiteSpeed reverse proxy.
- [QLoRA & 4-bit Quantization](https://finetunemyai.com/qlora): Deep dive into NormalFloat 4 (NF4), double quantization, and paged 8-bit AdamW.
- [Supported Hardware](https://finetunemyai.com/supported-platforms): Compatibility matrix for Apple Silicon (M1/M2/M3/M4) and NVIDIA RTX GPUs.

## Standard Verification Commands

```bash
# Run automated test suite (28 unit tests across 7 test suites)
npm test

# Build production bundle (55 routes)
npm run build

# Start production server (Port 3050)
npm run prod

# Test programmatic diagnostics API
curl -s http://localhost:3050/api/v1/diagnostics

# Test dataset split status
curl -s http://localhost:3050/api/v1/training/prepare
```