praisonai-train Package

Train agents or fine-tune LLMs without installing the full PraisonAI wrapper

Train agents or fine-tune LLMs without installing the full PraisonAI wrapper.

The praisonai-train PyPI package (import: praisonai_train) is Tier 2c — it sits on top of praisonaiagents and gives you the train CLI group and a standalone praisonai-train console script.

Prefer a UI? See Desktop → Training

The PraisonAI Desktop app wraps praisonai-train llm in a Train tab — live loss chart, log, and reconnect-safe progress.

Quick Start

1. Agent Training

   Improve an agent iteratively — no ML dependencies required.

   from praisonaiagents import Agent
   
   agent = Agent(instructions="You are a helpful assistant.")
   

   pip install praisonai-train
   
   praisonai-train agents --input "What is Python?"
   
2. LLM Fine-tuning

   Add the [llm] extra to pull the modern Unsloth/torch stack (unsloth>=2025.9.1, trl>=0.18.2, transformers>=4.51.3, torch>=2.6.0). The trainer uses each model’s own chat template, so chat_template is optional.

   pip install "praisonai-train[llm]"
   

   Llama

   praisonai-train llm dataset.json \
       --model unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit
   

   The base install now uses the modern TRL API (SFTConfig + SFTTrainer) and pulls the current Unsloth / TRL / torch 2.6+ stack. On old pins, upgrade with pip install -U "praisonai-train[llm]".

   praisonai-train llm <dataset> correctly trains on the dataset you pass. On PraisonAI releases before PR #4239 the dataset argument was silently dropped and the run fell back to yahma/alpaca-cleaned; upgrade if praisonai-train show <session> reports a model trained on a corpus you didn’t provide.

   As of PR #4317, praisonai train llm (the wrapper route) also actually launches the trainer. On earlier releases the legacy dispatcher had no train case and silently forwarded the literal word "train" to an LLM as a chat prompt, exited 0, and never invoked the trainer. Direct use of the praisonai-train llm console script was unaffected.

   Gemma

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

   Qwen

   praisonai-train llm dataset.json \
       --model unsloth/Qwen2.5-0.5B-Instruct-bnb-4bit
   

   From a config file

   Preview a run before you spend GPU time — --dry-run prints the resolved config and exits without loading the trainer. The tuning flags override the file (file first, flags on top).

   # Preview the resolved config before spending GPU time
   praisonai-train llm -c config.yaml --lora-r 32 --epochs 2 --dry-run
   
   # Then run it — flags override the file
   praisonai-train llm -c config.yaml --lora-r 32 --epochs 2
   

   Send it to a remote GPU box

   No GPU on this machine? Add --remote-host and the run happens on another box over SSH — the same as a remote: block in YAML or the desktop “Run on” dropdown. Set up key auth once with ssh-copy-id gpubox.

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

   The log streams while training; Ctrl-C stops the remote run. See Remote in one step.

3. Serve a trained model

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

   praisonai-train serve --gguf model.gguf
   

   See Serve & MTP Fast-Inference for the full walkthrough.

---

Beginner-safe defaults

A minimal fine-tuning config trains locally and pushes nowhere unless you opt in.

model_name: "unsloth/gemma-2-2b-it-bnb-4bit"
max_seq_length: 2048
dataset:
  - name: "yahma/alpaca-cleaned"
    num_samples: 20   # subset for a fast smoke test

# Trains locally, saves LoRA to lora_model/, no push.
praisonai-train llm dataset.yaml

Four headline safety guarantees (PraisonAI #3279):

• A minimal config trains locally — publishing to Hugging Face or Ollama is opt-in (set the flag and its target).
• assistant_only_loss: auto never crashes on a stock Gemma / Qwen / Llama template — it now masks via Unsloth turn markers when the template lacks {% generation %}, and falls back to full-sequence SFT only when neither route is available.
• Unknown / misnamed keys warn instead of crashing — a typo logs WARNING: ignoring unknown config key '...' and training continues.
• Environment preflight — missing or out-of-date training deps are now caught before the first heavy import; the CLI prints one pip install -U ... line that fixes them all.
• An unknown model_name warns, it doesn’t fail — the trainer prints one line pointing at praisonai-train models (with a “did you mean?” suggestion when there’s a close match) and continues, because unsloth also loads models it doesn’t map.

Beyond SFT, praisonai-train llm also supports preference tuning — DPO, ORPO, and KTO — via the method config key. See Preference Training.

Just before training, the trainer prints a run-summary block confirming the resolved model, example count, loss mask, steps, and output dir — see Train → Run summary.

---

When to Use praisonai-train vs praisonai train

Install the standalone package when you only need training; use the wrapper’s praisonai train when you already run the full stack.

Both entry points expose the same commands: every praisonai train <sub> also runs as praisonai-train <sub>.

---

CLI Subcommands

Eleven subcommands cover dataset tooling, benchmarking, fine-tuning, model discovery, serving, export, and agent training.

Subcommand	Purpose
praisonai-train generate [--config FILE]	Synthesize an instruction dataset from a teacher LLM
praisonai-train validate DATASET [--out FILE]	Quality-check / filter an instruction dataset
praisonai-train data from-trials REPORT	Export passing trial attempts to a trainer-ready SFT dataset
praisonai-train benchmark -d DEPLOYMENT ...	Rank deployments by generation speed
praisonai-train llm DATASET	Fine-tune an LLM via Unsloth (as of PR #4317, the wrapper route praisonai train llm also actually launches the trainer instead of falling through to a chat prompt)
praisonai-train models [SEARCH]	List the models the trainer knows how to load — with --json / -n and * starting-point markers
praisonai-train export {ollama|gguf|hf}	Publish an already-trained model without re-running training
praisonai-train agents [AGENT_FILE]	Iteratively train an agent
praisonai-train serve --gguf FILE [--benchmark]	Serve a fine-tuned GGUF over an OpenAI-compatible endpoint (auto-fetches the MTP drafter on Gemma-4)
praisonai-train list	List training sessions
praisonai-train show SESSION_ID	Show a session’s iterations and best score
praisonai-train apply SESSION_ID	Apply learned suggestions to an agent

See Train CLI for full flags.

---

Supported models

praisonai-train llm fine-tunes any Unsloth-supported model. The full list — ~246 repos on a recent unsloth release, including every 4-bit key and its 16-bit mirror — is discoverable from the CLI itself:

praisonai-train models              # everything, capped at 40
praisonai-train models gemma        # filter by family
praisonai-train models 7b           # or by size
praisonai-train models --json       # machine-readable
praisonai-train models -n 0         # the full list

Rows marked * are the curated starting set — one current base per major family, sized to fit a single 24 GB GPU in 4-bit. Pick one of these if you haven’t chosen yet:

Model family	Curated --model	Optional chat_template
Llama	unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit	llama-3.1 / llama-3
Qwen	unsloth/Qwen2.5-7B-Instruct-bnb-4bit	qwen-2.5 / qwen-3
Gemma	unsloth/gemma-2-9b-it-bnb-4bit	gemma / gemma-2
Mistral	unsloth/mistral-7b-instruct-v0.3-bnb-4bit	mistral
Phi	unsloth/Phi-3.5-mini-instruct-bnb-4bit	phi-3
Qwen (small)	unsloth/Qwen2.5-3B-Instruct-bnb-4bit	qwen-2.5
Gemma (small)	unsloth/gemma-2-2b-it-bnb-4bit	gemma / gemma-2

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

Unknown model_name warns, it doesn’t refuse. A model_name not in the unsloth catalog prints one line at validation time — e.g. WARNING: 'unsloth/Meta-Llama-3.1-8B-Instrct-bnb-4bit' is not in unsloth's model list, so it may not load. Did you mean: unsloth/Meta-Llama-3.1-8B-Instruct-bnb-4bit? Run \praisonai-train models` to see the full list.— and training proceeds. unsloth's loader falls through to a generic path for models it doesn't map, so refusing would block working configurations; but a typo no longer costs a Hugging Face download to discover. Suggestions match the repo name, not the full id, so a right model under the wrong org (e.g.meta-llama/…) surfaces the unsloth/…` mirror.

When unsloth isn’t installed (pip install praisonai-train without [llm]), the same command still works — it falls back to the 7-entry curated set so models is useful in a lightweight agent-training env too.

PraisonAI PR #3274 validated unsloth/Qwen2.5-0.5B-Instruct-bnb-4bit and unsloth/gemma-2-2b-it-bnb-4bit end-to-end. See Train → Model & template keys for the full chat_template reference.

---

Common Patterns

Fine-tune a non-Llama base (Gemma / Qwen)

Point --model at any Gemma or Qwen base — the trainer uses each model’s own chat template automatically.

pip install "praisonai-train[llm]"

# Gemma 2 (uses the model's own template automatically)
praisonai-train llm dataset.json \
    --model unsloth/gemma-2-2b-it-bnb-4bit

# Qwen 2.5
praisonai-train llm dataset.json \
    --model unsloth/Qwen2.5-0.5B-Instruct-bnb-4bit

The trainer previously force-applied the Llama-3.1 template to every model, corrupting Gemma / Qwen runs. Fixed as of PraisonAI PR #3274 — set chat_template in config.yaml only when a base model has no built-in template.

Fine-tune on 2 GPUs with checkpointing

Launch under torchrun and add a handful of checkpoint keys — an interrupted run resumes from the latest. See Multi-GPU.

# config.yaml
model_name: "unsloth/gemma-2-2b-it-bnb-4bit"
max_seq_length: 2048
dataset:
  - name: "yahma/alpaca-cleaned"
save_strategy: "steps"
save_steps: 50
resume_from_checkpoint: true

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

Train, review, apply

Run a training session, inspect the iterations, then bake the best one into your agent.

# --iterations N is a max — training stops early on a score >= 9.5 in LLM mode
praisonai-train agents --input "Explain AI" --human
praisonai-train list
praisonai-train show train-abc123 --iterations
praisonai-train apply train-abc123 --run "Explain AI"

Apply in Python

Apply a session’s suggestions to an agent directly.

from praisonaiagents import Agent
from praisonai_train.train.agents import apply_training

agent = Agent(instructions="You are a helpful assistant.")
apply_training(agent, session_id="train-abc123")

Train on any console

The same commands run identically on macOS, Linux, and Windows — no encoding configuration needed.

# Works identically on macOS/Linux/Windows — no encoding config needed
from praisonaiagents import Agent

agent = Agent(instructions="You are a helpful assistant.")

# On a Windows cp1252 console, the summary renders as plain ASCII
# and the session is still persisted for later review.
praisonai-train agents --input "What is Python?"
praisonai-train show train-abc123

Force all iterations

Benchmarks, regression tests, and demos that need to observe the feedback loop across every iteration should pass --no-early-stop (CLI) or no_early_stop=True (Python) so the 9.5 threshold is bypassed.

# CLI — always runs all 3 iterations
praisonai-train agents --input "What is Python?" --iterations 3 --no-early-stop

from praisonaiagents import Agent
from praisonai_train.train.agents import AgentTrainer, TrainingScenario

agent = Agent(instructions="You are a helpful assistant.")
trainer = AgentTrainer(agent=agent, iterations=3, no_early_stop=True)
trainer.scenarios.append(TrainingScenario(input_text="What is Python?"))
report = trainer.run()

Without this flag, --iterations behaves as a maximum in LLM-as-Judge mode — training stops as soon as any iteration scores ≥ 9.5.

---

Exporting an already-trained model

Publish a lora_model/ you trained earlier — no dataset, no re-training.

1. Push to Hugging Face

   praisonai-train export hf --model-dir lora_model --hf me/my-model
   
2. Export a GGUF

   Writes a local .gguf; add --hf to also push it to the Hub.

   praisonai-train export gguf --model-dir lora_model --hf me/my-model --quant q4_k_m
   
3. Push to Ollama

   praisonai-train export ollama --model-dir lora_model --ollama me/my-model --quant q4_k_m
   

Export doesn't need a dataset

for_export() skips the training-only validation, so an export-only run needs no dataset: — and no config file at all.

Chat template is inferred

The base model (for chat-template selection) is read from <model-dir>/config.json:_name_or_path, falling back to the directory name. Override it with --base-model.

Quantization is validated up front

--quant accepts the same values as the LLM training path (q4_k_m, q5_k_m, q8_0, q4_0, q4_1, q5_0, q5_1, q3_k_m, q6_k, f16, bf16, q2_k). A typo fails fast, listing every valid choice.

Ollama needs a namespaced model + registered key

The model must be namespaced <username>/<name>, and your public key must be registered at https://ollama.com/settings/keys. An unauthorized push tells you exactly where to click and prints your local ~/.ollama/id_ed25519.pub.

Python API

Export-only, straight from a config dict — no dataset required.

from praisonai_train import TrainModel

trainer = TrainModel.for_export({
    "model_name": "unsloth/gemma-2-2b-it-bnb-4bit",
    "final_model_dir": "lora_model",
    "hf_model_name": "me/my-model",
    "quantization_method": "q4_k_m",
})
model, tokenizer = trainer.load_model()
trainer.model, trainer.hf_tokenizer = model, tokenizer
trainer.save_model_merged()            # merged HF push
# or  trainer.push_model_gguf()        # GGUF-to-HF push
# or  trainer.create_and_push_ollama_model()   # Ollama push

for_export() accepts either model_name or its alias model (matching the --model CLI flag), and validates quantization_method up front — a typo like q4km raises ValueError with the full valid-methods list.

See praisonai train export for every flag and exit code.

---

Windows & non-UTF-8 Consoles

praisonai-train agents renders its summary table with emoji (✅ PASSED, ❌ NEEDS WORK, ★ best-iteration marker) when stdout supports UTF-8, and automatically falls back to ASCII (PASSED, NEEDS WORK, *) when it doesn’t. It detects the console’s encoding at runtime.

The ASCII summary is the correct output on a cp1252 Windows console — not a truncation. The session is saved either way; praisonai-train show <session-id> re-renders it in whichever encoding your current console supports.

---

Exit Codes

praisonai-train agents reports three distinct outcomes.

Exit	Meaning
0	Training completed and the report was persisted (praisonai-train list will show it). A warning is printed if only the console display failed to encode.
1	Training itself failed — the run raised an exception (including encoding errors that hit before save_report) or arguments were invalid. No report is persisted.
130	Interrupted by Ctrl-C.

A genuine agent failure (LLM provider unreachable, bad credentials, request timeout) now also surfaces as exit 1. Previously these errors were captured as an “output” string, graded, persisted, and reported as a successful training run — discard any train apply guidance derived from an "Error: ..." output. Fixed in PraisonAI PR #4239.

On a cp1252 Windows console, a completed training session now exits 0 even if Rich cannot render the summary emoji — you’ll see Training complete but summary could not be displayed: 'charmap' codec can't encode .... Run praisonai-train show <session-id> to inspect the persisted result. If you want the full emoji summary, run chcp 65001 first or set PYTHONIOENCODING=utf-8.

---

Best Practices

Install the base package for agent training

pip install praisonai-train pulls praisonaiagents plus litellm (needed for LLM-as-Judge grading) — enough for agents, list, show, and apply. Add [llm] only when you need Unsloth fine-tuning.

Use the standalone script when you don't want the wrapper

The praisonai-train console script exposes the full train group without installing praisonai. Ideal for lightweight training-only environments.

Old imports keep working

Existing praisonai.train.*, praisonai.train_vision, and praisonai.upload_vision imports still resolve to the same module objects in praisonai_train. Nothing to migrate.

Let the tokenizer's native template win

For LLM fine-tuning, only set chat_template for models without one, or to force a specific one. Forcing llama-3.1 on Gemma/Qwen was the old default and silently corrupted training — the trainer now uses each model’s own template by default. See Train → Chat Template.

Update to the modern Unsloth stack

The [llm] extra now requires unsloth>=2025.9.1, trl>=0.18.2, transformers>=4.51.3, and torch>=2.6.0. If you had pinned trl<0.9.0, upgrade — the pre-0.9 TRL API is no longer supported. As of PraisonAI PR #4365, the trainer refuses to import a stale stack at all and tells you the exact pip install -U ... to run.

Fix a GPU out-of-memory run in order

When a fine-tuning run stops with “The GPU ran out of memory”, lower max_seq_length first (biggest lever), then enable use_gradient_checkpointing: unsloth, then halve per_device_train_batch_size while doubling gradient_accumulation_steps, and switch to a 4-bit base model only as a last resort. See Train → GPU out of memory for the full walkthrough.

Backward-compatible: if you already have the wrapper installed, praisonai.train.* imports and the setup-conda-env entry point continue to work unchanged.

---

Related

Train

Training overview and fine-tuning setup.

Desktop → Training

Prefer a UI? Run a fine-tune from the Desktop app’s Train tab.

Train CLI

Full flag reference for every subcommand.

Preference Training

Fine-tune on preferences with DPO, ORPO, and KTO.

Serve & MTP Fast-Inference

Serve a GGUF over OpenAI HTTP with lossless MTP speculative decoding.

Ollama

Publish and run fine-tuned models locally with Ollama.

Dataset Tooling

Generate and quality-check instruction datasets.

Speed Benchmark

Rank deployments by generation speed before you fine-tune.

Multi-GPU Training

Fine-tune across multiple GPUs with torchrun.

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.

Installation Extras

The train install matrix.

Package Tiers

How the six packages stack.

Windows Terminal Encoding

Fix Rich crashes and ASCII rendering on legacy Windows consoles.