ai-trainer Guide

What ai-trainer Does

ai-trainer is the model workshop of the Kodachi AI suite. It builds a command-embedding database from a JSON file of command metadata, scores that database against a test file, versions it as snapshots, exports it, and downloads the optional model files (the ONNX sentence-embedding model and the GGUF models for the local LLM tier). It does not run queries itself: ai-cmd does that.

Key Capabilities

Models and Databases: What Ships, What You Create

Three different things get called "the model", and only one of them is something you train. This table is the whole picture for a Kodachi 9 or 10 install.

Where the files live

• Command line: the data/, models/, feedback/ and db/ folders of the AI runtime directory. On a standard Kodachi 9 install that is the hooks folder itself, so the database lands at /opt/kodachi/dashboard/hooks/data/embeddings.db. Run the commands from that folder, as every example on this page does.
• Dashboard: the dashboard runs the AI binaries with their own per-user runtime directory, ~/.local/share/kodachi/ai/ (override with the KODACHI_AI_RUNTIME_DIR environment variable), so the system install stays read-only. A database trained from the dashboard therefore lives under your home directory, not under /opt.
• Not sure which one a build uses? ai-learner status --json prints database_path, and a failing ai-trainer status names the path it looked for.

Where Training Data Comes From

You write it, or you download the starter files below. Training data is not collected from your usage and it is not shipped inside the binary pack. Here is how the three layers fit together:

1. The intent classifier is trained by the Kodachi team from the command registry, the built-in intent patterns and the workflow profiles (about ten thousand example sentences across 32 categories). You receive the finished ONNX file. There is nothing for you to train here.
2. The command-embedding database is built by ai-trainer train from a JSON file of command metadata that you supply. The two starter files below are the same command metadata the Kodachi tooling uses, and they are the fastest way to get a first trained database.
3. Feedback is collected as you go: every executed query is recorded by ai-cmd, and ai-cmd feedback "<query>" --correct-intent <id> records a correction. On Kodachi 10 ai-cmd consults those corrections when it ranks matches; on Kodachi 9 they are stored only. Feedback never rewrites the classifier and never edits your training JSON, so it is a separate channel from training, not a source of training data.

Starter files

# Put the starter files where the binaries expect them (Kodachi 9 standard install)
cd /opt/kodachi/dashboard/hooks
sudo mkdir -p data
sudo curl -fsSL -o data/training-data.json https://kodachi.cloud/docs/ai/samples/training-data.json
sudo curl -fsSL -o data/test-cases.json    https://kodachi.cloud/docs/ai/samples/test-cases.json
jq .command_count data/training-data.json     # prints 111

Training Data Format (exact)

This is the structure the binary parses. It is the same in Kodachi 9 and 10. A file in any other shape, including one with a wrapper object around these fields, is rejected with Failed to parse training data JSON.

{
  "version": "9.0.1",
  "generated_at": "2026-02-09T00:00:00Z",
  "command_count": 2,
  "commands": [
    {
      "command_id": "health-control-net-check",
      "service": "health-control",
      "command": "net-check",
      "description": "Check network connectivity and internet accessibility",
      "category": "network",
      "examples": ["health-control net-check", "check network", "am i online"],
      "keywords": ["health-control", "net-check", "network"],
      "typical_queries": ["check network", "test internet", "network status"]
    },
    {
      "command_id": "tor-switch-status",
      "service": "tor-switch",
      "command": "status",
      "description": "Show the current Tor connection status",
      "category": "tor",
      "examples": ["tor-switch status", "is tor running", "tor status"],
      "keywords": ["tor", "status", "anonymity"],
      "typical_queries": ["check tor status", "is tor working", "show tor state"]
    }
  ]
}

Rules the parser enforces

What the trainer does with an entry. It joins service, command, description, every keyword, every example and every typical query into one text document, computes a TF-IDF vector over all documents, and stores one vector per command_id. Validation then vectorises each test query and picks the closest command. So two commands whose phrasings overlap will confuse each other, and a command with four to six distinct phrasings scores much better than one with a bare description.

Test file format

Used by validate --test-data. The key is test_cases; min_score is optional and defaults to 0.5.

{
  "version": "9.0.1",
  "test_cases": [
    { "query": "check my internet connection", "expected_command_id": "health-control-net-check", "min_score": 0.5 },
    { "query": "is tor working",               "expected_command_id": "tor-switch-status" }
  ]
}

A test case passes when the top match is expected_command_id and its similarity is at least min_score. The run as a whole passes when the share of passing cases reaches --threshold (default 0.85).

Writing good training data

• Give every command four to six phrasings in examples or typical_queries, written the way a person would type them ("am i online", not "verify connectivity status").
• Do not reuse a phrasing across two commands; it makes them indistinguishable.
• Keep command_id stable once you have validated against it, because the test file references it.
• Balance the categories. A hundred network entries and five DNS entries will pull ambiguous queries toward network.
• After every edit, check the file parses (jq . data/training-data.json) and that command_count still matches (jq '.commands | length').

Step by Step: Command Line

Run from the hooks folder. train, incremental, export, snapshot and download-model run with sudo; train, incremental and export also check for a signed-in online-auth session and stop with "Authentication required" without one. validate, status and list-snapshots need neither.

# 0. Go where the binaries are
cd /opt/kodachi/dashboard/hooks

# 1. Before training: no database yet, this is expected
ai-trainer status

# 2. Get the starter files (or write your own in the format above)
sudo mkdir -p data
sudo curl -fsSL -o data/training-data.json https://kodachi.cloud/docs/ai/samples/training-data.json
sudo curl -fsSL -o data/test-cases.json    https://kodachi.cloud/docs/ai/samples/test-cases.json

# 3. Build the database (creates data/embeddings.db)
sudo ai-trainer train --data data/training-data.json
sudo ai-trainer train --data data/training-data.json --json      # same, machine readable

# 4. Score it
ai-trainer validate --test-data data/test-cases.json
ai-trainer validate --test-data data/test-cases.json --threshold 0.90 --json

# 5. Keep a rollback point
sudo ai-trainer snapshot --snapshot-version 1.0.0
ai-trainer list-snapshots

# 6. Export for backup or inspection (the path must stay inside the runtime directory)
sudo ai-trainer export --output data/model_export.json --format compact
sudo ai-trainer export --output data/model_stats.json --format stats --json

# 7. Add commands later without rebuilding: a second file in the same format
sudo ai-trainer incremental --new-data data/my-new-commands.json
ai-trainer validate --test-data data/test-cases.json

# 8. Try a training run without touching the real database
sudo ai-trainer train --data data/training-data.json --database data/embeddings-test.db
ai-trainer validate --test-data data/test-cases.json --database data/embeddings-test.db --json

train versus incremental. train clears the database and rebuilds every vector from the file you give it; it is the command to use for a clean rebuild or after editing existing entries. incremental keeps what is there and adds the entries of the new file; it requires an existing database and is the command to use when you only have new commands to add.

Starting over. Delete data/embeddings.db (or train into a different --database) and run train again. Snapshots are separate copies under data/models/ (one .db plus one .json of metadata per snapshot) and survive that.

Downloading model files

download-model is the only command on this page that touches the network. Without flags it fetches the all-MiniLM-L6-v2 ONNX model and tokenizer into models/. With --llm it fetches a GGUF model for the local LLM tier (Mistral.rs); pick the size that fits the machine:

sudo ai-trainer download-model                      # ONNX embedding model and tokenizer
sudo ai-trainer download-model --llm                # default GGUF (Qwen3-1.7B Q4_K_M)
sudo ai-trainer download-model --llm xlarge-hq      # quality-tuned 8B
sudo ai-trainer download-model --all                # ONNX plus the default GGUF
sudo ai-trainer download-model --show-models        # what is installed, what is available, sizes
sudo ai-trainer download-model --force              # re-download and overwrite
sudo ai-trainer download-model --output-dir models/custom

There is no RAM guard before a local model is loaded. Loading xlarge-hq on a 4 GB machine ends in an out-of-memory kill under inference, so match the tier to the host before selecting it.

Step by Step: Lite Dashboard

Everything above is also available without a terminal. The Lite dashboard has two panels for it, both running the same ai-trainer binary. Because the dashboard launches the AI tools in your per-user runtime directory (~/.local/share/kodachi/ai/), there is no sudo prompt and a database trained here is separate from one trained on the command line under /opt.

AI Commander, "Model Trainer (advanced)"

Open Essentials, then the AI Commander tab, then its Commander sub-tab. Below the "Ask for what you want" query box is a collapsed card named Model Trainer (advanced). Expand it and work down the panels in this order:

The training and test files are picked from anywhere on disk with the folder button; the starter files above work as they are. Each button's tooltip shows the exact command line it runs, and the output lands in the dashboard's output log.

Kodachi AI command builder, "Training" tab

When you want every flag rather than guided defaults, open the Command Builders group and choose Kodachi AI. Its Training tab exposes ai-trainer one command per card, with a field per flag and the resulting command line shown before you run it:

• Train Model: Data File (required), Database.
• Incremental Training: New Data File (required), Database.
• Validate Model: Test Data File (required), Accuracy Threshold (default 0.85), Database.
• Export Model: Output File (required), Export Format (Full, Compact, Stats Only).
• Create Snapshot: Version (required). List Snapshots: no options.
• Download Model: Output Directory, LLM Model Size (small, default, large, xlarge, xlarge-hq), Download All, Force Download, Show Available Models.

The same page has Learning (ai-learner), Admin (ai-admin database backup, restore, integrity check, migrate, info), Scheduler and Discovery tabs, so the whole train, validate, snapshot, back up cycle can be done from one screen. Output format (plain, JSON, JSON pretty) is a global switch at the top of the page.

AI Chat is a different thing

The "AI Assistant" button on the shared rail opens AI Chat, a conversation window that drafts and explains commands. It uses the shipped classifier and, if you enable them, local or cloud language models. It has no training controls and does not read the embedding database; use AI Commander or the command builder for that.

What Training Changes, and What It Does Not

• data/embeddings.db is ai-trainer's own model store. validate scores it, export dumps it, snapshot versions it, status counts it. Building a good one is how you evaluate and ship a command catalogue for your own set of commands.
• ai-cmd resolves your sentence against the command catalogue compiled into it, the shipped intent classifier and, on Kodachi 10, the corrections you have submitted with ai-cmd feedback. Retraining with ai-trainer does not replace the shipped classifier and cannot break ai-cmd; if a training run goes wrong, delete the database or restore a snapshot and nothing else is affected.
• Nothing on this page sends data anywhere. Training, validation, snapshots and export are local file operations. Only download-model reaches the network, and only when you run it.

Questions People Ask

Do I have to train before I can use ai-cmd? No. ai-cmd works out of the box with the shipped classifier and its built-in catalogue. Training is for people who want to build, score and version their own command catalogue.

Is the database created by the installer? No. It is created the first time you run ai-trainer train. Until then status, validate and export report "Database not found".

Where do I get training data? Download the starter files above, or write your own in the format above. It is never generated from your usage.

Does the AI learn from what I type? ai-cmd records executed queries and the corrections you submit with ai-cmd feedback. On Kodachi 10 those corrections influence ranking; on Kodachi 9 they are stored only. See the ai-learner guide for the learning side.

Which threshold should I use for validate? Start with the default 0.85. Use a lower value (for example 0.2) to see whether the plumbing works on a tiny test file, and 0.90 or higher as a release gate for a catalogue you maintain.

Can I keep several catalogues? Yes, with --database on train, incremental and validate. Only the default data/embeddings.db is what status, export and snapshot look at.

Why does export refuse my output path? The path is confined to the runtime directory. Use a relative path such as data/model_export.json.

Why does incremental fail on a fresh install? It adds to an existing database and does not create one. Run train once first.

Why does the dashboard not see the database I trained in the terminal? The dashboard uses ~/.local/share/kodachi/ai/, the terminal uses the hooks folder. Train in the place you will use, or point both at one path with KODACHI_AI_RUNTIME_DIR.

Related Workflows

• ai-learner, feedback, learning cycles, analysis and reports
• ai-cmd, querying, preview and feedback
• ai-discovery, binary detection and command metadata extraction
• ai-admin, database backup, restore and integrity
• AI suite overview, all eight binaries and how they connect
• Full CLI Reference: ai-trainer commands

Troubleshooting