Epoch

End-to-end CLI platform for fine-tuning LLMs — Vercel for model training.

Quickstart

pip install -e ".[dev]"

epoch data create train.jsonl --pipeline clean,dedup        # ingest and process data
epoch run --model meta-llama/Llama-3.2-1B --data v1         # start fine-tuning
epoch eval run --run latest -b mmlu,hellaswag --limit 5     # evaluate the result
epoch deploy --run latest --endpoint my-model-v1            # deploy to HuggingFace Hub

Or with a config file:

epoch init                    # create epoch.yaml
epoch run                     # train using config

Cloud training:

export RUNPOD_API_KEY=your_key
epoch run --model meta-llama/Llama-3.2-1B --data v1 --cloud   # auto-picks GPU
epoch run --gpu a100                                            # specific GPU
epoch init --cloud                                              # cloud config template

Commands

Training

Command	Description
epoch init [--cloud]	Create a default epoch.yaml config
epoch run [config]	Launch a fine-tuning run from a config file
epoch run --model <name> --data <name>	Launch a run without a config file
epoch run --cloud	Run on cloud GPU (auto-selects GPU)
epoch run --gpu <type>	Run on specific cloud GPU (a100, 4090, h100, ...)
epoch status [run_id]	Show status of a run (defaults to latest)
epoch stop [run_id]	Stop a running job

Run Analysis

Command	Description
epoch runs list [-n LIMIT]	List recent training runs
epoch runs show <run_id>	Detailed run info with metrics, config, and evals
epoch runs compare <id1> <id2> ...	Side-by-side run comparison

Data Management

Command	Description
epoch data create <path>	Ingest, process, and register a dataset in one step (--pipeline clean,dedup,quality)
epoch data upload <path>	Register a dataset (--name, --format)
epoch data list	List registered datasets
epoch data inspect <name>	Dataset stats (--model for token counts)
epoch data process <source>	Dedup, filter, and quality-score a dataset

Evaluation

Command	Description
epoch eval run	Run benchmarks (--run <id|latest> or --model <path>, -b <benchmarks>)
epoch eval list	List past evaluations (--run <id> to filter)
epoch eval show <eval_id>	Per-metric results for an evaluation
epoch eval benchmarks	List available benchmark names

Deployment

Command	Description
epoch deploy --run <id|latest> --endpoint <name>	Deploy a model to HuggingFace Hub
epoch deploy --model <path> --endpoint <name>	Deploy a standalone model directory

Web Dashboard

Command	Description
epoch dashboard	Launch the web dashboard at http://127.0.0.1:8585
epoch dashboard -p 9000	Custom port
epoch dashboard --host 0.0.0.0	Bind to all interfaces

---

Web Dashboard

A local web UI that mirrors the CLI with interactive charts and live auto-refresh.

pip install -e ".[web]"   # one-time setup
epoch dashboard            # open http://127.0.0.1:8585

Pages:

Page	What it shows
Runs	All training runs with status, duration, final loss. Select rows to compare.
Run Detail	Info card, config, metrics summary, 4 interactive charts (loss, LR, grad norm, GPU memory). Running jobs poll every 5s.
Compare	Config diff, metrics table, overlay loss chart, eval scores side-by-side.
Evaluations	All evals with optional run filter. Click through for per-benchmark breakdowns.
Datasets	Registered datasets with format, example count, and size.

The dashboard reads from the same SQLite database as the CLI — no extra setup.

---

Training Methods

Configured via training.method in your YAML config:

Method	Description
LoRA	Parameter-efficient adapter training (default)
QLoRA	4-bit quantized LoRA for reduced memory
Full	Full model weight fine-tuning

All methods include live metrics tracking, checkpoint saving, and graceful interrupt handling (Ctrl+C saves a checkpoint).

Data Processing

# One-step: ingest, clean, and register
epoch data create data.jsonl --pipeline clean,dedup,quality --name v1

# Or use the granular process command for more control
epoch data process data.jsonl --dedup --quality --min-tokens 50 --max-tokens 4096 -o cleaned.jsonl

Step	Description
Deduplication	SHA256-based exact duplicate removal
Length filtering	Min/max token count thresholds
Quality filtering	Heuristic scoring (repetition, length, special chars, word length)
Format detection	Auto-detects ChatML, Alpaca, and completion formats

Evaluation

Powered by lm-eval-harness. Install with pip install -e ".[eval]".

epoch eval run --run 1 -b mmlu,hellaswag        # evaluate a training run
epoch eval run --model gpt2 -b mmlu --limit 5   # evaluate a standalone model
epoch eval show 1                                # view results

Supported benchmarks: MMLU, HellaSwag, ARC-Challenge, GSM8K, TruthfulQA, HumanEval, WinoGrande.

Results are stored in the database and shown automatically in runs show and runs compare.

Deployment

Deploy trained models to HuggingFace Hub with inference instructions.

epoch deploy --run latest --endpoint my-model-v1           # deploy latest run
epoch deploy --run 3 --endpoint my-model --hub-org my-org  # deploy to an org
epoch deploy --model ./output --endpoint my-model-v1       # deploy a local model

Prints ready-to-use Python inference code and vLLM serving instructions after upload.

Cloud GPU Training

Train on cloud GPUs with RunPod. Install with pip install -e ".[cloud]".

export RUNPOD_API_KEY=your_key_here
epoch run config.yaml    # with provider.type: runpod in config

Epoch provisions a GPU pod, uploads your data and a self-contained training script, streams metrics back in real-time, downloads the trained model, and terminates the pod automatically.

# epoch.yaml — cloud training config
provider:
  type: runpod
  gpu_type_id: "NVIDIA RTX A6000"
  gpu_count: 1
  cloud_type: SECURE            # SECURE or COMMUNITY
  disk_gb: 50
  # api_key: ...                # or set RUNPOD_API_KEY env var

Provider field	Default	Description
type	local	local or runpod
gpu_type_id	—	Required for RunPod (e.g. NVIDIA RTX A6000, NVIDIA A100 80GB PCIe)
gpu_count	1	Number of GPUs to provision
cloud_type	SECURE	SECURE or COMMUNITY
disk_gb	50	Container disk size in GB
image	runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04	Docker image

Interrupting with Ctrl+C during cloud training terminates the pod to avoid charges.

Configuration

Epoch uses a YAML config file (epoch.yaml by default). Run epoch init to generate a template.

name: my-finetune
model:
  name: meta-llama/Llama-3.2-1B
data:
  path: training_data.jsonl
  format: chatml
  max_seq_length: 2048
  processing:
    deduplicate: true
    quality_filter: true
training:
  method: lora
  epochs: 3
  batch_size: 4
  learning_rate: 2e-4
  lora:
    r: 16
    alpha: 32
    target_modules: [q_proj, v_proj]
output:
  dir: ./output
  push_to_hub: false