Train

Model training and fine-tuning

The train command group covers LLM fine-tuning and iterative agent training.

Usage

praisonai train {generate|validate|benchmark|dedup|from-trials|llm|models|agents|export|serve|list|show|apply|checkpoints|infer|remote}

Requirements

Pick the install that matches what you want to train.

praisonai train generate

Synthesize an instruction dataset from a teacher LLM.

praisonai train generate [OPTIONS]

Options

YAML-only keys

These have no CLI flag — set them in --config.

Examples

# One-command dataset
praisonai train generate -r tamil -d gpt-4o -n 1000 -o data/tamil.jsonl

# Drive everything from YAML
praisonai train generate --config generate.yaml

# Disjoint parallel slice (offset past the first worker)
praisonai train generate -r tamil -d gpt-4o -n 5000 --start-offset 5000 -o data/b.jsonl

See Dataset Tooling for recipes, dedup, snapshots, and the generate_dataset() Python API.

praisonai train validate

Quality-check and filter an instruction dataset (dedup, boilerplate/refusal, script purity, diversity).

praisonai train validate [OPTIONS] DATASET

Options

YAML-only keys

Examples

# Validate and write the clean rows
praisonai train validate data/tamil.jsonl --out data/clean.jsonl

# Drive thresholds from YAML
praisonai train validate --config validate.yaml

# Skip the O(n^2) near-dup pass on a large dataset
praisonai train validate data/big.jsonl --no-near-dup --out data/clean.jsonl

The command prints an in / kept / drops / flags / metrics report to stdout. Malformed JSONL lines are skipped with a warning — the run still succeeds on the remaining rows.

See Dataset Tooling for the full check list and the score() / filter_rows() Python API.

praisonai train benchmark

Measure and rank generation speed across LLM deployments.

praisonai train benchmark [OPTIONS]

Options

YAML-only keys

Examples

# Compare two deployments from the environment credentials
praisonai train benchmark -d gpt-4o -d gpt-4o-mini --n 24 --concurrency 8 -o bench.json

# Drive everything from YAML
praisonai train benchmark --config benchmark.yaml

# OpenAI-compatible endpoint without JSON mode
praisonai train benchmark -d llama-3.1-70b --no-json-mode

The command prints each target as it finishes, then a table ranked by rows/min. n < 1 or concurrency < 1 raises ValueError; if every request fails the CLI exits 1.

See Speed Benchmark for the benchmark_deployments() Python API and cross-endpoint benchmarking.

praisonai train dedup

Merge many JSONL files into one deduped file with a single shared exact + MinHash/LSH index — catching the cross-file near-duplicates that per-file validate always misses.

praisonai train dedup FILES... --out MERGED.jsonl \
    [--method minhash|sliding] \
    [--threshold 0.7] \
    [--exact-only]

Options

Examples

# Merge parallel-generation batches, remove exact + near-duplicates
praisonai train dedup batch_*.jsonl --out data/merged.jsonl

# Exact-only, fastest path (no near-dup pass)
praisonai train dedup a.jsonl b.jsonl c.jsonl --out merged.jsonl --exact-only

Drive it from YAML for a reproducible config:

# dedup.yaml
inputs: [batch_1.jsonl, batch_2.jsonl, batch_3.jsonl]
out: data/merged.jsonl
near_dup_method: minhash
near_dup_jaccard: 0.75
minhash_perm: 128
ngram_n: 4
minhash_seed: 1

praisonai train dedup --config dedup.yaml

The command prints a in / kept / removed stats block on completion and exits non-zero only on IO errors. The write is atomic — an --out that aliases an input is never truncated before its rows are read.

praisonai train data from-trials

Export the passing attempts from a scored trials report into a trainer-ready SFT dataset (plus a provenance sidecar) — the “keep what verified, then fine-tune on it” step of the trials loop.

praisonai train data from-trials REPORT [OPTIONS]

Options

Examples

# Basic: keep passing, tool-free, frontier attempts as ShareGPT rows
praisonai-train data from-trials trials.json -o data/train.jsonl

# Small report: include failed/unscored attempts and saturated cases
praisonai-train data from-trials trials.json --all --include-saturated -o data/train.jsonl

# Alpaca instead of ShareGPT
praisonai-train data from-trials trials.json --format alpaca -o data/train.jsonl

# Run the exported rows through the same QC filter as validate
praisonai-train data from-trials trials.json --qc -o data/train.jsonl

Every run also writes {out}.jsonl.meta.json — a provenance sidecar mapping each emitted row to its source case, attempt, and score.

praisonai train llm

Fine-tune an LLM using Unsloth.

praisonai train llm [OPTIONS] [DATASET]

Pass a dataset path, or --config a file that names one — one of the two is required.

Options

Precedence

The resolved config is built in three layers — each layer overrides the one above.

An untouched config key survives when a different key is overridden by a flag.

Preview a run with --dry-run

--dry-run prints the resolved config as YAML you can paste back into a file, then a comment listing which keys came from flags — and exits without training.

praisonai-train llm -c config.yaml --lora-r 32 --epochs 2 --dry-run

lora_r: 32
max_seq_length: 2048
model_name: unsloth/gemma-2-2b-it-bnb-4bit
num_train_epochs: 2.0

# 2 value(s) came from flags: lora_r, num_train_epochs

When --remote-host (or --remote-python, --remote-workdir, --remote-gpus) is on the command line, the settled remote: block appears in the printed YAML with credentials redacted — the host, interpreter, workdir, and GPU count the run would actually use:

praisonai-train llm -c config.yaml --remote-host gpubox --dry-run

lora_r: 32
model_name: unsloth/gemma-2-2b-it-bnb-4bit
remote:
  gpus: 1
  host: gpubox
  python: python3
  workdir: ~/.praisonai-train

A bad remote: block is caught here too: a malformed block exits 1 with Bad remote settings at --dry-run, not after dispatch.

--dry-run does not load the training runner, so it works even without the [llm] extra installed.

Supported models

The trainer uses each model’s own chat template, so chat_template is optional — set it only to override.

Examples

# Fine-tune with a dataset
praisonai train llm dataset.json

# Fine-tune with a specific base model
praisonai train llm --model llama-3.1 dataset.json

# Fine-tune Gemma or Qwen with their native templates (no config needed)
praisonai train llm dataset.json --model unsloth/gemma-2-2b-it-bnb-4bit
praisonai train llm dataset.json --model unsloth/Qwen2.5-0.5B-Instruct-bnb-4bit

# Override tuning knobs straight from the CLI
praisonai-train llm data.jsonl --lora-r 32 --epochs 2

# Start from a config file, override one key
praisonai-train llm -c config.yaml --max-seq-length 4096

# Preview the resolved config without training
praisonai-train llm -c config.yaml --dry-run

Where config.yaml comes from

The CLI writes ./config.yaml from your flags plus resolved defaults in the invocation directory, then hands that single file to the trainer.

1. Materialise the config

   praisonai train llm resolves the config (file first, flags on top) and writes it to ./config.yaml in the directory you ran from — the only path the legacy dispatcher and its trainer subprocess read.

2. Back up any existing config.yaml

   If a config.yaml was already there and its contents differ from what’s about to be written, the previous contents are saved to ./config.yaml.bak and the run continues:

   NOTE: config.yaml already existed; the previous contents were saved to config.yaml.bak.

3. No-op writes leave no .bak

   Re-running the same command produces no .bak file — an identical write is detected and skipped. A first run in an empty directory also writes no .bak.

Config keys for LLM fine-tuning

Drive fine-tuning from config.yaml (all keys optional and backward compatible).

Unsloth surface keys

Model access, PEFT selectors, quant, and vLLM rollouts — all optional and additive. See Unsloth Surface for the full walkthrough.

See Train → Config.yaml example for the full file.

Publishing

Publishing defaults off — set the flag and its matching target to push a fine-tuned model.

Enabling a flag without its target fails fast on load:

ValueError: hf_model_name is required when huggingface_save or huggingface_save_gguf is enabled.
ValueError: ollama_model is required when ollama_save is enabled.

Preflight validation

Before any model or GPU load, the trainer fails fast with a single friendly line for the five most common misconfigurations: stale/missing training deps (checked first, before any heavy import), no CUDA GPU, missing Hugging Face credentials, low disk (< 10 GB free), and an invalid quantization_method. The GPU check is skipped when train: false, so publish-only / export-only runs succeed on CPU.

See Train → Preflight validation for the full check table, fix guidance, and the 35 valid quantization values.

Exit codes

The llm (and the praisonai_train.train.llm.trainer module) entrypoint prints a clean one-line error instead of a traceback for expected failures.

Missing-deps behaviour

On a bare pip install praisonai-train, llm prints one of two messages: LLM fine-tuning dependencies not installed with pip install "praisonai-train[llm]" when praisonai-code is absent, or `Failed to load LLM fine-tuning runner:

when praisonai-code` is present but a downstream import (torch/unsloth) failed. See Train for the full flow.

Errors you may see

The most common error after pip install --no-deps or on a hand-built conda env is a stale training stack. The trainer version-checks six packages (torch, transformers, unsloth, trl, peft, bitsandbytes) before any heavy import and prints one actionable block:

Training dependencies are missing or too old.
Missing: unsloth
torch 2.5.1 is older than the required 2.6.0
Install with: pip install -U "unsloth>=2025.9.1" "torch>=2.6.0"

Run the printed pip install -U ... command — it upgrades every listed package at once. A dev / rc suffix on a matching release satisfies the floor (2.6.0rc1 counts as 2.6.0). See Train → Runtime version-floor enforcement.

Multi-GPU launch

Fine-tune across every GPU on the machine with torchrun — --nproc_per_node is the number of GPUs.

torchrun --nproc_per_node=2 -m praisonai_train.train.llm.trainer train --config config.yaml

The trainer detects the distributed launch, loads the full model per rank, and lets only rank 0 save and publish. See Multi-GPU for the full walkthrough.

Remote in one step

Send this one run to a remote GPU box with --remote-host — the same as a remote: block in config.yaml or the desktop “Run on” dropdown. Precedence is flag > YAML > default; with no host settled, the command trains locally as before.

praisonai-train llm dataset.json --model unsloth/gemma-2-2b-it-bnb-4bit --remote-host gpubox

The dispatcher ships the config (stripping the remote: block so the far side does not dispatch again), streams the log, and forwards Ctrl-C to the remote run. Credentials in the block (password, token, identity_file, …) are refused up front. See Remote in one step.

Resume

Set resume_from_checkpoint: true in config.yaml, then re-run the same command — the trainer picks the latest checkpoint in output_dir.

# config.yaml
save_strategy: "steps"
save_steps: 50
resume_from_checkpoint: true

praisonai-train llm config.yaml

See Checkpointing for save_total_limit, best-checkpoint, and early-stopping keys.

Environment variables

torchrun sets the distributed variables; you set only your Hugging Face token.

praisonai train models

List every model praisonai train llm knows how to load — the same catalog model_name is validated against.

praisonai train models [SEARCH] [OPTIONS]

Options

Examples

# Everything unsloth maps (~246 repos on a recent unsloth release)
praisonai train models

# Just the Gemma family
praisonai train models gemma

# JSON for scripts
praisonai train models --json

# The full list, un-truncated
praisonai train models -n 0

Each row is prefixed with * if it’s part of the small curated starting set, or a space otherwise:

* unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit
  unsloth/Meta-Llama-3.1-8B-Instruct
  ...

The trailing line explains the marker (* = a good starting point.) and, when the output was truncated, prints {shown} of {total}; -n 0 for all.

How the catalog is built

The command reads unsloth.models.mapper at runtime — both the 4-bit repo keys and their 16-bit mirror values — rather than shipping a vendored copy that would go stale between releases.

When unsloth isn’t installed (the CLI is importable without the training extra), the command falls back to a 7-entry curated list of one current base per family, sized for a single 24 GB GPU in 4-bit. See Supported models.

Exit codes

praisonai train export

Publish an already-trained model to Hugging Face, GGUF, or Ollama without re-running training.

praisonai train export {ollama|gguf|hf} --model-dir DIR [--hf REPO] [--ollama NAME] [--quant Q] [--base-model NAME] [--config FILE] [--push|--no-push]

Point it at a lora_model/ you trained earlier — no dataset, no re-training. The hf target pushes a merged model to the Hub; gguf writes a local .gguf (and additionally pushes to the Hub when --hf is set); ollama creates and pushes an Ollama model (add --no-push to keep it local).

Options

Examples

# Push a merged model to Hugging Face
praisonai-train export hf     --model-dir lora_model --hf     me/my-model

# Write a local GGUF (and push it to HF when --hf is given)
praisonai-train export gguf   --model-dir lora_model --quant q4_k_m
praisonai-train export gguf   --model-dir lora_model --hf     me/my-model --quant q4_k_m

# Push to Ollama (default)
praisonai-train export ollama --model-dir lora_model --ollama me/my-model --quant q4_k_m

# Keep local only — never upload
praisonai-train export ollama --model-dir lora_model --ollama my-model --quant q4_k_m --no-push

Exit codes

See praisonai train llm for the full training path that produces the model you export here.

praisonai train agents

Train agents through iterative feedback loops.

praisonai train agents [OPTIONS] [AGENT_FILE]

Options

Early Stop (LLM mode)

--iterations N is a maximum, not an exact count. In LLM-as-Judge mode, training stops early as soon as any iteration scores ≥ 9.5 — easy factual prompts often finish in one iteration.

When training stops early, an INFO line is logged even in --quiet mode:

INFO ...orchestrator: Early stop after iteration 1/3 (score 10.0 >= 9.5 threshold). Use no_early_stop=True to run all iterations.

Reaching 9.5 on the final iteration counts as a full run — Stopped Early stays absent from the summary.

Human-in-the-loop mode (--human) does not use the 9.5 threshold — the user decides when to stop.

Examples

# Simple training with single input
praisonai train agents --input "What is Python?"

# Training with expected output
praisonai train agents --input "What is 2+2?" --expected "4"

# Training with scenarios file
praisonai train agents --scenarios scenarios.json

# Human feedback mode
praisonai train agents --input "Explain AI" --human

# More iterations
praisonai train agents --input "Hello" --iterations 5

# Force all iterations even if a score hits 9.5
praisonai-train agents --input "What is Python?" --iterations 3 --no-early-stop

# See the early-stop INFO line in the console
praisonai-train agents --input "Capital of Italy?" --iterations 3 --verbose

# With agent file
praisonai train agents my_agent.yaml --scenarios scenarios.json

Summary Rows

When training completes, the summary table always shows Total Iterations, Average / Min / Max Score, Improvement, and Status. Two extra rows appear only when the run was truncated:

The session JSON persists both signals as metadata.target_iterations (int) and metadata.early_stopped (bool), so tools reading persisted sessions can distinguish “user asked for 3, got 1 due to 9.5” from “user asked for 1, got 1”.

Storage Backend Options

Store training data in different backends.

# SQLite backend (recommended for production)
praisonai train agents --input "Hello" --storage-backend sqlite --storage-path ~/.praisonai/train.db

# Redis backend (for distributed systems)
praisonai train agents --input "Hello" --storage-backend redis://localhost:6379

# File backend (default)
praisonai train agents --input "Hello" --storage-backend file --storage-path ~/.praisonai/train

Exit Codes

praisonai train serve

Serve a fine-tuned GGUF over an OpenAI-compatible endpoint — auto-fetching the MTP drafter for lossless fast inference on Gemma-4.

praisonai train serve [OPTIONS]

Options

How MTP is auto-detected

The base model name (from --base-model, --config, or the model directory’s config.json) drives drafter selection. A Gemma-4 target fetches its matching stock drafter from the Hub; any other family falls back to plain serving with a clear message.

Examples

# Serve a single GGUF on the default OpenAI endpoint (:8080)
praisonai train serve --gguf model.gguf

# Serve from a model directory (target GGUF auto-detected)
praisonai train serve --model-dir lora_model

# One-shot benchmark: tokens/sec + MTP draft acceptance, then exit
praisonai train serve --gguf gemma4-e4b.gguf --benchmark

praisonai train checkpoints

List the checkpoints a training run saved — answers “what did it save?” without an ls.

praisonai train checkpoints [OPTIONS]

Options

Examples

# List saved checkpoints, newest step first
praisonai train checkpoints -d outputs

# Machine-readable output for scripts
praisonai train checkpoints -d outputs --json

Matches checkpoint-<n> exactly (a checkpoint-final directory is skipped), sorts numerically newest-first, and reports each checkpoint’s size on disk. An empty or missing directory exits 1 with a remediation. JSON entries are {"step": int, "path": str, "bytes": int}.

See List Checkpoints for the full workflow and jq patterns.

praisonai train infer

Run a single generation against a model you just trained — answers “did it work?”.

praisonai train infer -d lora_model "Summarise this release."

Options

Examples

# Simplest one-liner — reply streams to stdout
praisonai train infer -d lora_model "Summarise this release."

# Longer, more focused output
praisonai train infer -d lora_model "Write release notes." \
    --max-new-tokens 512 --temperature 0.3

Output streams via TextStreamer(skip_prompt=True), so the prompt is not echoed and the first token arrives early. Without the Unsloth / Transformers stack it exits 1 with pip install "praisonai-train[llm]".

See Infer (one-shot inference) for the full walkthrough and the infer vs serve vs benchmark decision guide.

praisonai train list

List all training sessions.

praisonai train list [OPTIONS]

Options

Examples

# List recent sessions
praisonai train list

# Show more sessions as JSON
praisonai train list --limit 50 --json

# List sessions from a SQLite backend
praisonai train list --storage-backend sqlite --storage-path ~/.praisonai/train.db

# List sessions from Redis
praisonai train list --storage-backend redis://localhost:6379

# List sessions from a custom file directory
praisonai train list --storage-backend file --storage-path ~/.praisonai/train

Each row shows the session ID, iteration count, size, and last-modified time.

praisonai train show

Show details of a training session, including its iterations and best score.

praisonai train show [OPTIONS] SESSION_ID

Options

Examples

# Show session summary
praisonai train show train-abc123

# Show with detailed iterations
praisonai train show train-abc123 --iterations

# Output as JSON
praisonai train show train-abc123 --json

# Session stored in a SQLite database
praisonai train show train-abc123 \
    --storage-backend sqlite --storage-path ~/.praisonai/train.db

# Session stored in Redis
praisonai train show train-abc123 --storage-backend redis://localhost:6379

# Session stored in a custom file directory
praisonai train show train-abc123 \
    --storage-backend file --storage-path ~/.praisonai/train

The summary highlights the best iteration (★) with its score and feedback.

praisonai train apply

Apply learned suggestions from a session to an agent via hooks. Uses the best-scoring iteration by default.

praisonai train apply [OPTIONS] SESSION_ID

Options

Examples

# Apply best iteration to default agent
praisonai train apply train-abc123

# Apply a specific iteration
praisonai train apply train-abc123 --iteration 2

# Apply to an agent from a YAML file
praisonai train apply train-abc123 --agent my_agent.yaml

# Apply and run immediately
praisonai train apply train-abc123 --run "Hello, how are you?"

# Apply a session stored in SQLite
praisonai train apply train-abc123 \
    --storage-backend sqlite --storage-path ~/.praisonai/train.db

# Apply a session stored in Redis, then run
praisonai train apply train-abc123 \
    --storage-backend redis://localhost:6379 \
    --run "Hello, how are you?"

# Apply a session written to a custom file dir
praisonai train apply train-abc123 \
    --storage-backend file --storage-path ~/.praisonai/train

Standalone script

Install praisonai-train on its own to get a praisonai-train console script that exposes the same subcommands directly.

pip install praisonai-train

praisonai-train agents --input "What is Python?"
praisonai-train data from-trials trials.json -o data/train.jsonl
praisonai-train list
praisonai-train show train-abc123 --iterations
praisonai-train apply train-abc123 --iteration 2 --run "Hello, how are you?"
praisonai-train export hf --model-dir lora_model --hf me/my-model

Every praisonai train <sub> example above runs as-is with the praisonai-train <sub> prefix.

See Also

• Train – Training overview and fine-tuning setup
• Export a trained model – Publish a trained model without re-training
• Unsloth Surface – Gated models, PEFT selectors, offline merge, and vLLM rollouts
• Train → Preflight validation – Fast, friendly config checks before any GPU load
• Serve & MTP Fast-Inference – Serve a GGUF over OpenAI HTTP with MTP speculative decoding
• Dataset Tooling – Generate and quality-check instruction datasets
• praisonai-train Package – Standalone package guide
• Multi-GPU Training – Fine-tune across multiple GPUs with torchrun
• Remote Training – Ship a run to a GPU box over SSH with the remote group
• Remote in one step – Send a run to a remote GPU box with --remote-host, remote: YAML, or the desktop dropdown
• Checkpointing – Save, resume, and keep the best checkpoint
• Eval – Evaluation and testing
• Storage Backends – Pluggable storage backends