Binary reference

ai-trainer

AI model training and validation for Kodachi OS command intelligence

Version9.8.4Size8.2MBAuthorWarith Al Maawali <warith@digi77.com>LicenseLicenseRef-Kodachi-SAN-1.1Websitehttps://www.digi77.com

File Information

Property	Value
Binary Name	ai-trainer
Version	9.8.4
Build Date	Not disclosed
Rust Version	1.82.0
File Size	8.2MB
Author	Warith Al Maawali <warith@digi77.com>
License	LicenseRef-Kodachi-SAN-1.1
Category	Kodachi Binary
Description	AI model training and validation for Kodachi OS command intelligence
Git Commit	unknown
Metadata Generated	2026-08-10T13:23:01Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

e698e4fca7d1ca43d3f6bb598bb34fc1da0632103b8634aad5b2006db81cd0b8

Features

#	Feature
1	TF-IDF based command embeddings
2	Incremental model updates
3	Model validation and accuracy testing

Security Features

Feature	Description
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core

System Requirements

Requirement	Value
OS	Linux (Debian-based)
Privileges	root/sudo for system operations
Dependencies	OpenSSL, libcurl

Global Options

Flag	Description
`-h, --help`	Print help information
`-v, --version`	Print version information
`-n, --info`	Display detailed information
`-e, --examples`	Show usage examples
`--json`	Output in JSON format
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--json-filter <FIELD1,FIELD2>`	Return only specified JSON fields (comma-separated)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)

Commands

Model Management

`export`

Export model embeddings and metadata to JSON file

Usage:

ai-trainer export --output <FILE> [--format <FORMAT>]

Options:

--output <FILE>: Where to write the export. The path is confined to the install directory: a path outside it is rejected
--format <FORMAT>: full (every embedding vector, largest file), compact (metadata and commands, embedding vectors dropped), stats (counts and metrics only, no commands and no vectors)
--json: Emit the export result as a JSON envelope

Examples:

sudo ai-trainer export --output data/model_export.json

sudo ai-trainer export --output data/model_compact.json --format compact

sudo ai-trainer export --output data/model_stats.json --format stats --json

`snapshot`

Save current model as versioned snapshot

Usage:

ai-trainer snapshot --snapshot-version <VERSION>

Options:

-s, --snapshot-version <VERSION>: Version label using only ASCII letters, digits, '.', '-' and '_', for example 1.0.0
--json: Emit the snapshot name, version and embedding count as a JSON envelope

Examples:

sudo ai-trainer snapshot --snapshot-version 1.0.0

sudo ai-trainer snapshot -s 1.1.0-beta

sudo ai-trainer snapshot --snapshot-version 1.0.0 --json

`list-snapshots`

List all saved model snapshots

Usage:

ai-trainer list-snapshots

Options:

--json: Emit the snapshot list as a JSON envelope

Examples:

ai-trainer list-snapshots

ai-trainer list-snapshots --json

`status`

Display current model status and statistics

Usage:

ai-trainer status

Options:

--json: Emit the model status as a JSON envelope

Examples:

ai-trainer status

ai-trainer status --json

`download-model`

Download the ONNX embeddings model and tokenizer, or a GGUF model for the local LLM

Usage:

ai-trainer download-model [--llm [default|small|large|xlarge|xlarge-hq]] [--show-models] [--all] [--output-dir <DIR>] [--force] [--allow-unverified-model]

Options:

--llm [SIZE]: Download a GGUF model for the local LLM. Sizes: small (Qwen3-1.7B Q4_K_S, ~1.0 GB), default (Qwen3-1.7B Q4_K_M, ~1.1 GB), large (Phi-3.5-mini, ~2.3 GB), xlarge (Qwen3-8B Q4_K_M, ~4.8 GB, tuned for speed), xlarge-hq (Qwen3-8B Q5_K_M, ~5.6 GB, tuned for quality). The value may be omitted
--all: Download the ONNX embeddings model (all-MiniLM-L6-v2) and the default GGUF model in one go
--show-models: List what is already downloaded and what is available, with sizes. Downloads nothing
--output-dir <DIR>: Directory the model files are written to
-f, --force: Re-download and overwrite files that already exist
--allow-unverified-model: Acknowledge that no SHA-256 hash is pinned. Downloads proceed either way and print a warning; this flag only records the opt-in
--json: Emit the download or inventory result as a JSON envelope

Examples:

sudo ai-trainer download-model

sudo ai-trainer download-model --llm

sudo ai-trainer download-model --llm small

sudo ai-trainer download-model --llm large

sudo ai-trainer download-model --llm xlarge

sudo ai-trainer download-model --llm xlarge-hq

sudo ai-trainer download-model --all

sudo ai-trainer download-model --output-dir models

sudo ai-trainer download-model --force

sudo ai-trainer download-model --show-models

Model Training

`train`

Train AI model from command metadata (full retraining)

Usage:

ai-trainer train --data <FILE> [--database <DB_PATH>]

Options:

--data <FILE>: Training data JSON. The file shipped with Kodachi is data/training-data.json
--database <DB_PATH>: Embedding database to write
--json: Emit the training metrics as a JSON envelope

Examples:

sudo ai-trainer train --data data/training-data.json

sudo ai-trainer train --data data/training-data.json --json

`incremental`

Update model incrementally with new command data

Usage:

ai-trainer incremental --new-data <FILE> [--database <DB_PATH>]

Options:

--new-data <FILE>: JSON file with the new commands to fold in. The file shipped with Kodachi is data/incremental-training-data.json
--database <DB_PATH>: Embedding database to update. It must already exist: `incremental` adds to a trained model, it does not create one
--json: Emit the incremental metrics as a JSON envelope

Examples:

sudo ai-trainer incremental --new-data data/incremental-training-data.json

sudo ai-trainer incremental --new-data data/incremental-training-data.json --json

Validation & Testing

`validate`

Validate model accuracy against test dataset

Usage:

ai-trainer validate --test-data <FILE> [--threshold <THRESHOLD>]

Options:

--test-data <FILE>: Test dataset JSON. The file shipped with Kodachi is data/test-cases.json
--threshold <THRESHOLD>: Accuracy the run must reach to be reported as a pass, between 0.0 and 1.0
--database <DB_PATH>: Embedding database to validate against
--json: Emit the validation metrics as a JSON envelope

Examples:

ai-trainer validate --test-data data/test-cases.json

ai-trainer validate --test-data data/test-cases.json --threshold 0.90

ai-trainer validate --test-data data/test-cases.json --threshold 0.2 --json

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Model Training

Retrain the command-embedding model from scratch. The training corpus that ships with Kodachi is data/training-data.json.

Step 1: Rebuild the model from the shipped training corpus

sudo ai-trainer train --data data/training-data.json

Expected Output: The number of commands trained, the vocabulary size and the embedding count, then the database path that was written

Note

Needs root (it rewrites the embedding database in the install directory) and a prior `online-auth` login. This REPLACES the existing model.

Step 2: Train into a separate database instead of the live one

sudo ai-trainer train --data data/training-data.json --database data/embeddings-test.db

Expected Output: The same training summary, written to the database path you named

Note

Needs root and a prior `online-auth` login. Use this to try a training run without touching data/embeddings.db, which is the one the AI actually reads.

Step 3: Train and capture the metrics for a pipeline

sudo ai-trainer train --data data/training-data.json --json

Expected Output: Envelope with the training metrics

Note

Needs root and a prior `online-auth` login.

Scenario 2: Incremental Training

Fold new commands into a model that already exists, instead of retraining from scratch. The incremental corpus that ships with Kodachi is data/incremental-training-data.json.

Step 1: Add the new commands to the existing model

sudo ai-trainer incremental --new-data data/incremental-training-data.json

Expected Output: The count of new embeddings added and the new total

Note

Needs root and a prior `online-auth` login. Requires an already-trained database: run `train` first.

Step 2: Incremental update with a machine-readable result

sudo ai-trainer incremental --new-data data/incremental-training-data.json --json

Expected Output: Envelope with the incremental training metrics

Note

Needs root and a prior `online-auth` login.

Scenario 3: Validation

Score the trained model against a labelled test set. `validate` is read-only: no root, no authentication. The test set that ships with Kodachi is data/test-cases.json.

Step 1: Check the model against the shipped test cases

ai-trainer validate --test-data data/test-cases.json

Expected Output: The measured accuracy and whether it passed the 0.85 default threshold

Note

--threshold defaults to 0.85. A freshly trained model on the small shipped test set can score below that: a fail here is a threshold statement, not a crash.

Step 2: Demand 90 percent accuracy instead of the default 85

ai-trainer validate --test-data data/test-cases.json --threshold 0.90

Expected Output: The measured accuracy and a pass or fail against 0.90

Note

--threshold is a fraction between 0.0 and 1.0, not a percentage.

Step 3: A low-bar smoke check for CI, machine-readable

ai-trainer validate --test-data data/test-cases.json --threshold 0.2 --json

Expected Output: Envelope with the accuracy and the pass or fail verdict

Note

0.2 is deliberately permissive: it only proves the model loads and classifies, it does not prove quality.

Step 4: Validate a candidate database before promoting it

ai-trainer validate --test-data data/test-cases.json --database data/embeddings-test.db --json

Expected Output: Envelope with the accuracy of the database you named

Scenario 4: Model Export

Dump the trained model to a JSON file. --output is confined to the install directory: a path outside it is rejected.

Step 1: Export the whole model, embedding vectors included

sudo ai-trainer export --output data/model_export.json

Expected Output: data/model_export.json written, with the command metadata and every embedding vector

Note

Needs root and a prior `online-auth` login. The full format is the largest: every vector is serialized.

Step 2: Export without the embedding vectors to keep the file small

sudo ai-trainer export --output data/model_compact.json --format compact

Expected Output: data/model_compact.json with the commands and metadata but no vectors

Note

Needs root and a prior `online-auth` login. compact DROPS the embedding vectors, so the file cannot rebuild the model, only describe it.

Step 3: Export only the counts and metrics

sudo ai-trainer export --output data/model_stats.json --format stats --json

Expected Output: data/model_stats.json with the embedding count, vocabulary size and metrics, and nothing else

Note

Needs root and a prior `online-auth` login. stats drops BOTH the commands and the vectors.

Scenario 5: Snapshots

Save and list versioned copies of the trained model, so a bad training run can be identified and compared.

Step 1: Freeze the current model under a version label

sudo ai-trainer snapshot --snapshot-version 1.0.0

Expected Output: The snapshot name, its version and the number of embeddings captured

Note

Needs root and a prior `online-auth` login. Take a snapshot BEFORE a retrain if you may want to compare against the old model.

Step 2: Snapshot with the short flag and a machine-readable result

sudo ai-trainer snapshot -s 1.1.0-beta --json

Expected Output: Envelope with the snapshot name, version and embedding count

Note

Needs root and a prior `online-auth` login.

Step 3: See every snapshot that has been taken

ai-trainer list-snapshots

Expected Output: One line per snapshot with its version and metadata

Step 4: The snapshot list as JSON

ai-trainer list-snapshots --json

Expected Output: Envelope with the snapshot array

Scenario 6: Model Download

Fetch the model files the AI engine needs: the all-MiniLM-L6-v2 ONNX embeddings model, and a GGUF model for the local LLM. NOTE: no SHA-256 hash is currently pinned for any of these files, so their integrity is NOT verified after download. Every download prints a warning saying so.

Step 1: Download the ONNX embeddings model and its tokenizer

sudo ai-trainer download-model

Expected Output: all-MiniLM-L6-v2.onnx and tokenizer.json written to models/, preceded by the no-pinned-hash warning

Note

Needs root (writes into the install directory) and a prior `online-auth` login. Needs network access. The download is NOT hash-verified: no hash is pinned for this file.

Step 2: Download the default local LLM (Qwen3-1.7B Q4_K_M, about 1.1 GB)

sudo ai-trainer download-model --llm

Expected Output: The GGUF file written to models/, preceded by the no-pinned-hash warning

Note

Needs root, network access and a prior `online-auth` login. Best balance of quality, speed and size for CPU inference. NOT hash-verified.

Step 3: Download the smallest local LLM (Qwen3-1.7B Q4_K_S, about 1.0 GB)

sudo ai-trainer download-model --llm small

Expected Output: The small GGUF file written to models/

Note

Needs root, network access and a prior `online-auth` login. Choose this on systems with under 4 GB of free RAM. NOT hash-verified.

Step 4: Download the mid-size local LLM (Phi-3.5-mini, about 2.3 GB)

sudo ai-trainer download-model --llm large

Expected Output: The large GGUF file written to models/

Note

Needs root, network access and a prior `online-auth` login. Better reasoning and a 128K trained context. NOT hash-verified.

Step 5: Download the 8B model tuned for speed (Qwen3-8B Q4_K_M, about 4.8 GB)

sudo ai-trainer download-model --llm xlarge

Expected Output: The Qwen3-8B Q4_K_M file written to models/

Note

Needs root, network access and a prior `online-auth` login. 4-bit quantization, for 8 GB RAM and up: faster tokens per second, lower quality than xlarge-hq. NOT hash-verified.

Step 6: Download the 8B model tuned for quality (Qwen3-8B Q5_K_M, about 5.6 GB)

sudo ai-trainer download-model --llm xlarge-hq

Expected Output: The Qwen3-8B Q5_K_M file written to models/

Note

Needs root, network access and a prior `online-auth` login. 5-bit quantization, recommended on 16 GB RAM and up: the best local-LLM quality in the catalog, roughly 15 percent slower than xlarge. NOT hash-verified.

Step 7: Download the ONNX embeddings model and the default GGUF in one go

sudo ai-trainer download-model --all

Expected Output: Both the ONNX files and the default GGUF written to models/

Note

Needs root, network access and a prior `online-auth` login. This is the complete first-time setup. NOT hash-verified.

Step 8: Download into a directory you choose instead of the default

sudo ai-trainer download-model --output-dir models

Expected Output: The model files written to the directory you named

Note

Needs root, network access and a prior `online-auth` login. --output-dir defaults to models/, so this only matters if you want a different location.

Step 9: Re-download the ONNX model even though the files are already there

sudo ai-trainer download-model --force

Expected Output: The existing files are overwritten with a fresh download

Note

Needs root, network access and a prior `online-auth` login. Overwrites: use it when a file is suspected to be truncated or corrupt.

Step 10: See what is already downloaded and what is available

ai-trainer download-model --show-models

Expected Output: The model inventory: each catalog entry with its size and whether it is present on disk

Note

Downloads nothing, so it needs neither root nor authentication.

Step 11: The model inventory as JSON

ai-trainer download-model --show-models --json

Expected Output: Envelope listing the downloaded and available models

Scenario 7: Status

Check whether a trained model exists and what is in it. `status` is read-only: no root, no authentication.

Step 1: Show whether the model is trained and how big it is

ai-trainer status

Expected Output: The database path, the embedding count and the model statistics, or a clear message that no model has been trained yet

Step 2: The model status as JSON for the dashboard

ai-trainer status --json

Expected Output: Envelope with the model status and statistics

Environment Variables

Variable	Description	Default	Values
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
5	File not found
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Network error