ai-learner Guide
Analyses feedback and predictions, runs learning cycles and reports accuracy per intent. This guide explains where feedback comes from, which files it lands in, what a learning cycle does today, and how to run it from the terminal or the Lite dashboard.
ai-learner at a glance
ai-learner keeps its own SQLite database of feedback, predictions and learning runs, runs learning cycles over that feedback, reports accuracy, confidence and F1 per intent, and writes reports. It does not train the embedding database and it does not answer queries.
Reference and verification
This is a scenario-first guide: operational workflows, real run order, and troubleshooting. For the full autogenerated command and flag catalog, use the ai-learner CLI Reference, or read the raw signer JSON.
SHA256 (v10.0.3): 1819c6740604f23883f3d7042c2565acdf6d9835f11f1b6c4e415670b1276896
What ai-learner Does
ai-learner is the analysis and learning side of the Kodachi AI suite. It keeps its own SQLite database of feedback, predictions and learning runs, runs learning cycles over that feedback, reports accuracy, confidence and F1 per intent, and writes reports. It does not train the command-embedding database (that is ai-trainer) and it does not answer queries (that is ai-cmd).
Key Capabilities
| Command | What it does | Needs |
|---|---|---|
learn |
Runs a learning cycle over the feedback in the learner database, updates intent weights, records the run. --incremental processes only feedback newer than the last run; --learning-rate and --min-feedback tune it; --output-policy also writes and signs results/ai-policy.json |
No sudo. Creates data/kaics.db on first run |
analyze |
Accuracy, confidence and F1 per intent for a window: last-day, last-7-days, last-30-days, last-year or all-time. --learning-curve appends the accuracy series of every learning run |
No sudo |
report |
Writes the same numbers as a JSON, Markdown or HTML report, to stdout or to a file under results/ |
No sudo |
status |
Whether the learner database exists, its path, the totals, the last 7 days of activity and the last run timestamps. --verbose adds the SQLite size, pages and fragmentation |
No sudo. Never creates anything |
Where Feedback Comes From, and Where It Goes
This is the part people ask about most, so here it is end to end, with the file each step writes.
| Step | Who | Writes | Created when |
|---|---|---|---|
| You run a query | ai-cmd query "..." |
data/learning.db: the query, the command it resolved to, whether it ran and how long it took |
First query. The database and its tables are created on the spot |
| You correct a wrong match | ai-cmd feedback "..." --correct-intent <id> or --correct-command "..." |
feedback/feedback.json (the log) and data/learning.db (the corrected mapping) |
First feedback |
| ai-cmd uses it | ai-cmd, next query |
Nothing. On Kodachi 10 it reads the learned mappings back and lets them influence ranking. On Kodachi 9 the records are stored and not read back | |
| You run a learning cycle | ai-learner learn |
data/kaics.db: the learner's own feedback, predictions and learning-run tables |
First learn. The file and schema are created on the spot |
Current state of the loop, so you are not surprised
In the current Kodachi 9 and 10 builds ai-learner reads only its own database (data/kaics.db), and the bridge that copies ai-cmd's corrections into it is not wired yet. On a fresh install ai-learner learn therefore reports "No feedback available to process" (or "Insufficient feedback") and analyze reports zero predictions, even after you have submitted corrections. Your corrections are not lost: they sit in data/learning.db and feedback/feedback.json, and on Kodachi 10 ai-cmd already uses them directly. This page is updated when the bridge lands.
So, is the training data built by hand or learned from use? Both channels exist and they are separate. The training JSON that ai-trainer reads is written by hand (or downloaded from the starter files) and is never generated from your usage. The feedback channel above is collected from use and never edits that JSON or the shipped intent classifier.
Step by Step: Command Line
None of these commands need sudo. Run them from the hooks folder (/opt/kodachi/dashboard/hooks on a standard install), which is where the data/ and results/ folders are created.
# 1. Find the intent id of a wrong match, then correct it
ai-cmd preview "check tor" # shows the ranked matches and their intent ids
ai-cmd feedback "check tor" --correct-intent tor_status
ai-cmd feedback "dns leak" --correct-command "dns-leak test"
ai-cmd feedback "network check" --correct-intent network_check --comment "picked the wrong tool"
# 2. See what the learner has (fresh install: initialized false, database_exists false)
ai-learner status
ai-learner status --verbose --json
# 3. Run a learning cycle (creates data/kaics.db on the first run)
ai-learner learn
ai-learner learn --incremental # only feedback since the last run; needs one full run first
ai-learner learn --learning-rate 0.05 --min-feedback 10
ai-learner learn --output-policy # also writes and signs results/ai-policy.json
ai-learner learn --json
# 4. Measure
ai-learner analyze # last 7 days, all metrics
ai-learner analyze --period last-30-days --metric accuracy
ai-learner analyze --metric f1-score --learning-curve
ai-learner analyze --period all-time --json
# 5. Report (the --output path is relative to results/, pass a bare filename)
ai-learner report
ai-learner report --format markdown --output learning-report.md
ai-learner report --format html --period last-30-days --output learning-report.html
ai-learner report --period last-7-days --json
Parameters. --learning-rate must be inside (0.0, 1.0]; the engine default is 0.01, and 0.05 is the usual upper value for a quick convergence test. --min-feedback skips the run unless at least that many feedback entries exist (the engine default is 10). --period applies to accuracy and F1; confidence is always computed over the last 7 days.
Automate it. ai-scheduler runs any of these on a cron expression:
ai-scheduler add --name "daily-learn" --command "ai-learner learn --incremental" --cron "0 2 * * *"
ai-scheduler add --name "weekly-analyze" --command "ai-learner analyze --period last-7-days --json" --cron "0 3 * * 0"
ai-scheduler list
Step by Step: Lite Dashboard
The dashboard runs ai-learner and ai-cmd in your per-user runtime directory (~/.local/share/kodachi/ai/), so the databases it creates live under your home directory and no sudo prompt appears.
Submitting feedback
Open Essentials, then AI Commander, then the Commander sub-tab. Type a request in "Ask for what you want" and run it. Under the result there is a Submit Feedback for This Query button; it opens a small form with three optional fields, Comment, Correct Intent ID (for example network_check) and Correct Command (for example health-control net-check). Submitting it runs ai-cmd feedback with those values. The form is not offered for answers that came from an external reasoning engine (Codex, OpenCode), because there is no classifier match to correct.
AI Commander, "Learning" tab
The Learning sub-tab of AI Commander is the learner front end. From top to bottom:
| Control | What it does | Runs |
|---|---|---|
| Run Learning Cycle | One cycle with default parameters. Results appear in a "Learning Cycle Results" panel: patterns analysed, new patterns learned, accuracy improvement, duration | ai-learner learn |
| Analyze Performance | Metrics for the last 7 days, shown as a performance panel | ai-learner analyze |
| Load Patterns | Per-intent accuracy table plus the learning curve | ai-learner analyze --metric accuracy --learning-curve |
| Learning Configuration panel | Incremental Learning toggle, Learning Rate slider (0.01 to 1.0), Min Feedback Count, then Run Configured Learning | ai-learner learn with --incremental, --learning-rate, --min-feedback |
| Performance Analysis Options panel | Time Period (last day to all time), Metric (all, accuracy, confidence, F1), Show Learning Curve toggle, then Analyze with Options | ai-learner analyze --period --metric [--learning-curve] |
| Generate Report panel | Format (JSON, Markdown, HTML), Period, Output File, then Generate Report | ai-learner report --format --period --output |
The same tab also carries the daemon controls for ai-monitor, ai-scheduler and ai-discovery, so the "daily-learn" schedule above can be added from here too. Every button's tooltip names the command it runs, and the output is written to the dashboard's output log.
Kodachi AI command builder, "Learning" tab
For every flag, open Command Builders, choose Kodachi AI, then the Learning tab. It has one card per command, shows the command line it will run, and offers plain, JSON and JSON pretty output:
- Run Learning Cycle: Incremental, Learning Rate (default 0.1 in the builder), Min Feedback (default 5), Output Policy.
- Analyze Performance: Time Period (default last 7 days), Metric (default all).
- Generate Report: Report Format (default JSON), Time Period (default last 30 days), Output File.
- Learner Status: Verbose.
The Commander tab of the same page has the Submit Feedback card (Original Query, Correct Intent, Correct Command, Comment) for corrections with every field exposed.
Questions People Ask
Do I need to train anything before ai-learner works? No. It creates its own database on the first learn. It does not use ai-trainer's embedding database at all.
Where is the learner database? data/kaics.db under the runtime directory: the hooks folder on the command line, ~/.local/share/kodachi/ai/ from the dashboard. ai-learner status --json prints the exact database_path.
Why does learn say "No feedback available to process" right after I submitted corrections? Because corrections are stored by ai-cmd in data/learning.db and the learner reads data/kaics.db; see the note above. The corrections are kept and, on Kodachi 10, used by ai-cmd itself.
Does feedback change the shipped intent classifier or my training JSON? No. The classifier (models/kodachi-intent-classifier.onnx) is pre-trained and read-only, and the training JSON is only ever written by you.
How do I find the intent id to put in --correct-intent? ai-cmd preview "<your query>" lists the ranked matches with their ids, and ai-cmd export-intents --output intents.json dumps the whole catalogue.
Does any of this leave the machine? No. ai-learner is local file and SQLite work only.
Can I reset it? Delete data/kaics.db; the next learn recreates it. ai-cmd's data/learning.db and feedback/feedback.json are separate and untouched.
Related Workflows
- ai-trainer, models, databases, training data format and training steps
- ai-cmd, querying, preview and feedback
- ai-scheduler, scheduling learning and analysis runs
- ai-admin, database backup, restore and integrity
- AI suite overview, all eight binaries and how they connect
- Full CLI Reference: ai-learner commands
Troubleshooting
| Problem | Cause | Solution |
|---|---|---|
| "No feedback available to process" or "Insufficient feedback" | Fewer feedback rows in the learner database than --min-feedback (default 10), and in current builds ai-cmd corrections are not copied into it |
Expected on current builds; lower --min-feedback only changes the threshold, not the source. Keep submitting corrections, ai-cmd on Kodachi 10 uses them directly |
status reports initialized: false |
No learning cycle has run yet | Run ai-learner learn once; status never creates the database itself |
--incremental fails |
No previous full run to serve as a baseline | Run ai-learner learn without the flag first |
report --output rejects the path |
The path is already relative to results/, and .. is refused |
Pass a bare filename such as report.html |
| Accuracy drops after a learning run | Conflicting corrections, or a learning rate too high | Review with ai-learner report, rerun with --learning-rate 0.01 |
| The dashboard and the terminal show different numbers | Two runtime directories: ~/.local/share/kodachi/ai/ and the hooks folder |
Use one of them, or point both at one path with KODACHI_AI_RUNTIME_DIR |