{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:42Z", "binary_name": "ai-trainer" }, "binary": { "name": "ai-trainer", "path": "/opt/kodachi/dashboard/hooks/ai-trainer", "timestamp": "2026-07-21T01:54:42Z", "file_info": { "size": 4468688, "sha256": "ef5fd92bb2c64d66dfe600d1a18e44b2766492d0ec6a0b9475b459e0b951d4f2" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:42.133849598Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-trainer", "version": "9.8.4", "author": "Warith Al Maawali ", "description": "AI model training and validation for Kodachi OS command intelligence", "copyright": "© 2026 Kodachi OS", "website": "https://www.digi77.com", "license": "LicenseRef-Kodachi-SAN-1.1", "features": [ "TF-IDF based command embeddings", "Incremental model updates", "Model validation and accuracy testing" ], "securityFeatures": { "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core", "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core" }, "systemRequirements": { "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations", "dependencies": [ "OpenSSL", "libcurl" ] } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_v": { "status": "success", "timestamp": "2026-07-21T01:54:42.275880336Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-trainer", "version": "9.8.4", "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "rustVersion": "1.82.0" }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_h": { "status": "success", "timestamp": "2026-07-21T01:54:42.443123013Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-trainer", "description": "AI model training and validation for Kodachi OS command intelligence", "usage": "ai-trainer [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Model Management", "commands": [ { "name": "export", "description": "Export model embeddings and metadata to JSON file", "usage": "ai-trainer export --output [--format ]", "options": [ { "flag": "--output ", "description": "Where to write the export. The path is confined to the install directory: a path outside it is rejected", "required": true }, { "flag": "--format ", "description": "full (every embedding vector, largest file), compact (metadata and commands, embedding vectors dropped), stats (counts and metrics only, no commands and no vectors)", "default": "full" }, { "flag": "--json", "description": "Emit the export result as a JSON envelope" } ], "requires_sudo": true, "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" ] }, { "name": "snapshot", "description": "Save current model as versioned snapshot", "usage": "ai-trainer snapshot --snapshot-version ", "options": [ { "flag": "-s, --snapshot-version ", "description": "Version label using only ASCII letters, digits, '.', '-' and '_', for example 1.0.0", "required": true }, { "flag": "--json", "description": "Emit the snapshot name, version and embedding count as a JSON envelope" } ], "requires_sudo": true, "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" ] }, { "name": "list-snapshots", "description": "List all saved model snapshots", "usage": "ai-trainer list-snapshots", "options": [ { "flag": "--json", "description": "Emit the snapshot list as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-trainer list-snapshots", "ai-trainer list-snapshots --json" ] }, { "name": "status", "description": "Display current model status and statistics", "usage": "ai-trainer status", "options": [ { "flag": "--json", "description": "Emit the model status as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-trainer status", "ai-trainer status --json" ] }, { "name": "download-model", "description": "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 ] [--force] [--allow-unverified-model]", "options": [ { "flag": "--llm [SIZE]", "description": "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", "default": "default (when --llm is given with no value)" }, { "flag": "--all", "description": "Download the ONNX embeddings model (all-MiniLM-L6-v2) and the default GGUF model in one go" }, { "flag": "--show-models", "description": "List what is already downloaded and what is available, with sizes. Downloads nothing" }, { "flag": "--output-dir ", "description": "Directory the model files are written to", "default": "models/" }, { "flag": "-f, --force", "description": "Re-download and overwrite files that already exist" }, { "flag": "--allow-unverified-model", "description": "Acknowledge that no SHA-256 hash is pinned. Downloads proceed either way and print a warning; this flag only records the opt-in" }, { "flag": "--json", "description": "Emit the download or inventory result as a JSON envelope" } ], "requires_sudo": true, "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" ] } ] }, { "category": "Model Training", "commands": [ { "name": "train", "description": "Train AI model from command metadata (full retraining)", "usage": "ai-trainer train --data [--database ]", "options": [ { "flag": "--data ", "description": "Training data JSON. The file shipped with Kodachi is data/training-data.json", "required": true }, { "flag": "--database ", "description": "Embedding database to write", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the training metrics as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer train --data data/training-data.json", "sudo ai-trainer train --data data/training-data.json --json" ] }, { "name": "incremental", "description": "Update model incrementally with new command data", "usage": "ai-trainer incremental --new-data [--database ]", "options": [ { "flag": "--new-data ", "description": "JSON file with the new commands to fold in. The file shipped with Kodachi is data/incremental-training-data.json", "required": true }, { "flag": "--database ", "description": "Embedding database to update. It must already exist: `incremental` adds to a trained model, it does not create one", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the incremental metrics as a JSON envelope" } ], "requires_sudo": true, "examples": [ "sudo ai-trainer incremental --new-data data/incremental-training-data.json", "sudo ai-trainer incremental --new-data data/incremental-training-data.json --json" ] } ] }, { "category": "Validation & Testing", "commands": [ { "name": "validate", "description": "Validate model accuracy against test dataset", "usage": "ai-trainer validate --test-data [--threshold ]", "options": [ { "flag": "--test-data ", "description": "Test dataset JSON. The file shipped with Kodachi is data/test-cases.json", "required": true }, { "flag": "--threshold ", "description": "Accuracy the run must reach to be reported as a pass, between 0.0 and 1.0", "default": "0.85" }, { "flag": "--database ", "description": "Embedding database to validate against", "default": "data/embeddings.db" }, { "flag": "--json", "description": "Emit the validation metrics as a JSON envelope" } ], "requires_sudo": false, "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" ] } ] } ], "globalOptions": [ { "flag": "-h, --help", "description": "Print help information" }, { "flag": "-v, --version", "description": "Print version information" }, { "flag": "-n, --info", "description": "Display detailed information" }, { "flag": "-e, --examples", "description": "Show usage examples" }, { "flag": "--json", "description": "Output in JSON format" }, { "flag": "-o, --output-format ", "description": "Force output format (text|json)" }, { "flag": "--json-pretty", "description": "Pretty-print JSON output with indentation" }, { "flag": "--json-human", "description": "Enhanced JSON output with improved formatting (like jq)" }, { "flag": "--json-filter ", "description": "Return only specified JSON fields (comma-separated)" }, { "flag": "--fields ", "description": "Select specific fields to include in output (comma-separated)" }, { "flag": "--limit ", "description": "Limit number of results returned" }, { "flag": "--offset ", "description": "Skip first N results (for pagination)" }, { "flag": "-d, --work-dir ", "description": "Working directory (defaults to auto-detected base directory)" }, { "flag": "--port ", "description": "Set custom port number (1024-65535)" }, { "flag": "--log-level ", "description": "Set log level (error|warn|info|debug)" }, { "flag": "--verbose", "description": "Enable verbose output" }, { "flag": "--quiet", "description": "Suppress non-essential output" }, { "flag": "--no-color", "description": "Disable colored output" }, { "flag": "--config ", "description": "Use custom configuration file" }, { "flag": "--timeout ", "description": "Set operation timeout in seconds (optional; no default applied)" } ], "environmentVariables": [ { "name": "NO_COLOR", "description": "Disable all colored output when set", "default": "unset", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "3": "Permission denied", "2": "Invalid arguments", "0": "Success", "4": "Network error", "5": "File not found", "1": "General error" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:42.742434194Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-trainer", "description": "Usage examples for ai-trainer", "categories": [ { "id": "1_model_training", "title": "Model Training", "description": "Retrain the command-embedding model from scratch. The training corpus that ships with Kodachi is data/training-data.json.", "examples": [ { "command": "sudo ai-trainer train --data data/training-data.json", "description": "Rebuild the model from the shipped training corpus", "expectedOutput": "The number of commands trained, the vocabulary size and the embedding count, then the database path that was written", "notes": "Needs root (it rewrites the embedding database in the install directory) and a prior `online-auth` login. This REPLACES the existing model." }, { "command": "sudo ai-trainer train --data data/training-data.json --database data/embeddings-test.db", "description": "Train into a separate database instead of the live one", "expectedOutput": "The same training summary, written to the database path you named", "notes": "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." }, { "command": "sudo ai-trainer train --data data/training-data.json --json", "description": "Train and capture the metrics for a pipeline", "expectedOutput": "Envelope with the training metrics", "notes": "Needs root and a prior `online-auth` login." } ] }, { "id": "2_incremental_training", "title": "Incremental Training", "description": "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.", "examples": [ { "command": "sudo ai-trainer incremental --new-data data/incremental-training-data.json", "description": "Add the new commands to the existing model", "expectedOutput": "The count of new embeddings added and the new total", "notes": "Needs root and a prior `online-auth` login. Requires an already-trained database: run `train` first." }, { "command": "sudo ai-trainer incremental --new-data data/incremental-training-data.json --json", "description": "Incremental update with a machine-readable result", "expectedOutput": "Envelope with the incremental training metrics", "notes": "Needs root and a prior `online-auth` login." } ] }, { "id": "3_validation", "title": "Validation", "description": "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.", "examples": [ { "command": "ai-trainer validate --test-data data/test-cases.json", "description": "Check the model against the shipped test cases", "expectedOutput": "The measured accuracy and whether it passed the 0.85 default threshold", "notes": "--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." }, { "command": "ai-trainer validate --test-data data/test-cases.json --threshold 0.90", "description": "Demand 90 percent accuracy instead of the default 85", "expectedOutput": "The measured accuracy and a pass or fail against 0.90", "notes": "--threshold is a fraction between 0.0 and 1.0, not a percentage." }, { "command": "ai-trainer validate --test-data data/test-cases.json --threshold 0.2 --json", "description": "A low-bar smoke check for CI, machine-readable", "expectedOutput": "Envelope with the accuracy and the pass or fail verdict", "notes": "0.2 is deliberately permissive: it only proves the model loads and classifies, it does not prove quality." }, { "command": "ai-trainer validate --test-data data/test-cases.json --database data/embeddings-test.db --json", "description": "Validate a candidate database before promoting it", "expectedOutput": "Envelope with the accuracy of the database you named" } ] }, { "id": "4_model_export", "title": "Model Export", "description": "Dump the trained model to a JSON file. --output is confined to the install directory: a path outside it is rejected.", "examples": [ { "command": "sudo ai-trainer export --output data/model_export.json", "description": "Export the whole model, embedding vectors included", "expectedOutput": "data/model_export.json written, with the command metadata and every embedding vector", "notes": "Needs root and a prior `online-auth` login. The full format is the largest: every vector is serialized." }, { "command": "sudo ai-trainer export --output data/model_compact.json --format compact", "description": "Export without the embedding vectors to keep the file small", "expectedOutput": "data/model_compact.json with the commands and metadata but no vectors", "notes": "Needs root and a prior `online-auth` login. compact DROPS the embedding vectors, so the file cannot rebuild the model, only describe it." }, { "command": "sudo ai-trainer export --output data/model_stats.json --format stats --json", "description": "Export only the counts and metrics", "expectedOutput": "data/model_stats.json with the embedding count, vocabulary size and metrics, and nothing else", "notes": "Needs root and a prior `online-auth` login. stats drops BOTH the commands and the vectors." } ] }, { "id": "5_snapshots", "title": "Snapshots", "description": "Save and list versioned copies of the trained model, so a bad training run can be identified and compared.", "examples": [ { "command": "sudo ai-trainer snapshot --snapshot-version 1.0.0", "description": "Freeze the current model under a version label", "expectedOutput": "The snapshot name, its version and the number of embeddings captured", "notes": "Needs root and a prior `online-auth` login. Take a snapshot BEFORE a retrain if you may want to compare against the old model." }, { "command": "sudo ai-trainer snapshot -s 1.1.0-beta --json", "description": "Snapshot with the short flag and a machine-readable result", "expectedOutput": "Envelope with the snapshot name, version and embedding count", "notes": "Needs root and a prior `online-auth` login." }, { "command": "ai-trainer list-snapshots", "description": "See every snapshot that has been taken", "expectedOutput": "One line per snapshot with its version and metadata" }, { "command": "ai-trainer list-snapshots --json", "description": "The snapshot list as JSON", "expectedOutput": "Envelope with the snapshot array" } ] }, { "id": "6_download", "title": "Model Download", "description": "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.", "examples": [ { "command": "sudo ai-trainer download-model", "description": "Download the ONNX embeddings model and its tokenizer", "expectedOutput": "all-MiniLM-L6-v2.onnx and tokenizer.json written to models/, preceded by the no-pinned-hash warning", "notes": "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." }, { "command": "sudo ai-trainer download-model --llm", "description": "Download the default local LLM (Qwen3-1.7B Q4_K_M, about 1.1 GB)", "expectedOutput": "The GGUF file written to models/, preceded by the no-pinned-hash warning", "notes": "Needs root, network access and a prior `online-auth` login. Best balance of quality, speed and size for CPU inference. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm small", "description": "Download the smallest local LLM (Qwen3-1.7B Q4_K_S, about 1.0 GB)", "expectedOutput": "The small GGUF file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. Choose this on systems with under 4 GB of free RAM. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm large", "description": "Download the mid-size local LLM (Phi-3.5-mini, about 2.3 GB)", "expectedOutput": "The large GGUF file written to models/", "notes": "Needs root, network access and a prior `online-auth` login. Better reasoning and a 128K trained context. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --llm xlarge", "description": "Download the 8B model tuned for speed (Qwen3-8B Q4_K_M, about 4.8 GB)", "expectedOutput": "The Qwen3-8B Q4_K_M file written to models/", "notes": "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." }, { "command": "sudo ai-trainer download-model --llm xlarge-hq", "description": "Download the 8B model tuned for quality (Qwen3-8B Q5_K_M, about 5.6 GB)", "expectedOutput": "The Qwen3-8B Q5_K_M file written to models/", "notes": "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." }, { "command": "sudo ai-trainer download-model --all", "description": "Download the ONNX embeddings model and the default GGUF in one go", "expectedOutput": "Both the ONNX files and the default GGUF written to models/", "notes": "Needs root, network access and a prior `online-auth` login. This is the complete first-time setup. NOT hash-verified." }, { "command": "sudo ai-trainer download-model --output-dir models", "description": "Download into a directory you choose instead of the default", "expectedOutput": "The model files written to the directory you named", "notes": "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." }, { "command": "sudo ai-trainer download-model --force", "description": "Re-download the ONNX model even though the files are already there", "expectedOutput": "The existing files are overwritten with a fresh download", "notes": "Needs root, network access and a prior `online-auth` login. Overwrites: use it when a file is suspected to be truncated or corrupt." }, { "command": "ai-trainer download-model --show-models", "description": "See what is already downloaded and what is available", "expectedOutput": "The model inventory: each catalog entry with its size and whether it is present on disk", "notes": "Downloads nothing, so it needs neither root nor authentication." }, { "command": "ai-trainer download-model --show-models --json", "description": "The model inventory as JSON", "expectedOutput": "Envelope listing the downloaded and available models" } ] }, { "id": "7_status", "title": "Status", "description": "Check whether a trained model exists and what is in it. `status` is read-only: no root, no authentication.", "examples": [ { "command": "ai-trainer status", "description": "Show whether the model is trained and how big it is", "expectedOutput": "The database path, the embedding count and the model statistics, or a clear message that no model has been trained yet" }, { "command": "ai-trainer status --json", "description": "The model status as JSON for the dashboard", "expectedOutput": "Envelope with the model status and statistics" } ] } ], "quickReference": [ "ai-trainer --help", "ai-trainer --version", "ai-trainer --info --json", "ai-trainer --examples", "ai-trainer status", "ai-trainer validate --test-data data/test-cases.json", "ai-trainer download-model --show-models", "sudo ai-trainer train --data data/training-data.json" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } } }