Binary reference

ai-learner

AI learning engine for continuous improvement and performance analysis

Version9.8.4Size28.1MBAuthorWarith Al Maawali <warith@digi77.com>LicenseLicenseRef-Kodachi-SAN-1.1Websitehttps://kodachi.cloud

File Information

Property	Value
Binary Name	ai-learner
Version	9.8.4
Build Date	Not disclosed
Rust Version	1.82.0
File Size	28.1MB
Author	Warith Al Maawali <warith@digi77.com>
License	LicenseRef-Kodachi-SAN-1.1
Category	Kodachi Binary
Description	AI learning engine for continuous improvement and performance analysis
Git Commit	unknown
Metadata Generated	2026-08-10T13:22:49Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

fd5a39afd4b936bc680f12a8cdcc0f973f630be68007e8ca3664fe0001667741

Features

#	Feature
1	Feedback aggregation and analysis
2	Incremental learning with convergence detection
3	Performance tracking and trend analysis
4	Multi-format report generation (JSON, Markdown, HTML)

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

Analysis Operations

`analyze`

Analyze model performance and trends

Usage:

ai-learner analyze [OPTIONS]

Options:

--period <PERIOD>: Accuracy and F1 window: last-day, last-7-days, last-30-days, last-year or all-time. Confidence always uses the last 7 days
--metric <METRIC>: Metric to report: accuracy, confidence, f1-score or all
--learning-curve: Append the all-time learning-run accuracy series to the selected metric summary
--json: Emit the per-intent metrics as a JSON envelope

Examples:

ai-learner analyze

ai-learner analyze --period last-7-days

ai-learner analyze --metric accuracy --json

ai-learner analyze --learning-curve

Learning Operations

`learn`

Run learning cycle to improve model based on feedback

Usage:

ai-learner learn [OPTIONS]

Options:

--incremental: Only process feedback recorded since the last learning run. Needs a previous full run to have a baseline
--learning-rate <RATE>: Override the learning rate. Must be finite and inside (0.0, 1.0]
--min-feedback <COUNT>: Skip the learning run unless at least this many feedback entries exist
--output-policy: After learning, write and sign results/ai-policy.json (intent thresholds, tool allowlist, risk mode). Overwrites the existing policy
--json: Emit the learning metrics as a JSON envelope

Examples:

sudo ai-learner learn

sudo ai-learner learn --incremental

sudo ai-learner learn --learning-rate 0.05 --min-feedback 100

sudo ai-learner learn --output-policy --json

Reporting Operations

`report`

Generate comprehensive performance reports

Usage:

ai-learner report [OPTIONS]

Options:

--format <FORMAT>: Body of the report: json, markdown or html
--output <FILE>: Write the report to this file. The path is ALREADY relative to the results directory, so pass a bare filename (not results/<name>). Parent ("..") components are rejected
--period <PERIOD>: Window to report on: last-day, last-7-days, last-30-days, last-year or all-time
--json: Wrap the result in a JSON envelope. Independent of --format, which selects the report body

Examples:

sudo ai-learner report

sudo ai-learner report --format markdown

sudo ai-learner report --format html --output learning-report.html

sudo ai-learner report --period all-time --format markdown --json

Status Operations

`status`

Show ai-learner status, database health, and activity metrics

Usage:

ai-learner status [OPTIONS]

Options:

--verbose: Also report the SQLite statistics: size, pages, freelist and fragmentation percent
--json: Emit initialized, database_path, database_exists, the totals, the last-7-days counts and the last_* timestamps as a JSON envelope

Examples:

ai-learner status

ai-learner status --json

ai-learner status --verbose

Operational Scenarios

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

Scenario 1: Basic Learning Operations

Run a learning cycle over the collected prediction feedback and update the model weights. Every `learn` run is auth-gated and writes into the results directory.

Step 1: Run a full learning cycle over all stored feedback

sudo ai-learner learn

Expected Output: A learning summary: feedback processed, accuracy before and after, and whether the run converged

Note

Requires a prior `online-auth` login (learn is not read-only).

Step 2: Only process feedback that arrived since the last learning run

sudo ai-learner learn --incremental

Expected Output: A shorter summary covering just the new feedback delta

Note

Requires a prior `online-auth` login. Incremental only makes sense once a full `learn` has established a baseline; with no previous run there is no delta to apply.

Step 3: Full learning cycle with a machine-readable result

sudo ai-learner learn --json

Expected Output: Envelope with the learning metrics for the run

Note

Requires a prior `online-auth` login.

Step 4: Slow the convergence down with a smaller learning rate

sudo ai-learner learn --learning-rate 0.05

Expected Output: The same learning summary, computed with the rate you passed

Note

Requires a prior `online-auth` login. --learning-rate must be finite and inside (0.0, 1.0]; anything else is rejected.

Step 5: Refuse to learn unless at least 100 feedback entries exist

sudo ai-learner learn --min-feedback 100

Expected Output: Either a normal learning run, or a message that learning was skipped for insufficient feedback

Note

Requires a prior `online-auth` login. Use this to avoid retraining on a statistically meaningless sample.

Step 6: A tuned learning run with both guards and JSON output

sudo ai-learner learn --learning-rate 0.05 --min-feedback 100 --json

Expected Output: Envelope with the metrics of the run, or the skipped reason

Note

Requires a prior `online-auth` login.

Step 7: Learn, then write the signed AI policy file the runtime reads

sudo ai-learner learn --output-policy

Expected Output: The learning summary plus results/ai-policy.json written and signed

Note

Requires a prior `online-auth` login. The policy holds the intent thresholds, the tool allowlist and the risk mode, and it OVERWRITES results/ai-policy.json.

Step 8: Learn and regenerate the policy in one step, machine-readable

sudo ai-learner learn --output-policy --json

Expected Output: Envelope with the learning metrics; after a successful learning run, results/ai-policy.json is also written and signed

Note

Requires a prior `online-auth` login. The JSON envelope does not include the policy path or signature. If minimum feedback is not met, learning is skipped and no policy is generated.

Scenario 2: Performance Analysis

Look at how well the model is doing, per intent and over time. `analyze` is read-only: it needs no authentication and no root.

Step 1: Analyze every metric over the default window

ai-learner analyze

Expected Output: A per-intent breakdown of accuracy, confidence and F1 score over the last 7 days

Note

--period defaults to last-7-days and --metric defaults to all, so bare `analyze` is not an empty query.

Step 2: Analyze performance over the past week

ai-learner analyze --period last-7-days

Expected Output: Per-intent accuracy and the trend across the window

Note

--period accepts exactly: last-day, last-7-days, last-30-days, last-year, all-time.

Step 3: Just the accuracy metric, machine-readable

ai-learner analyze --metric accuracy --json

Expected Output: Envelope with the per-intent accuracy breakdown

Note

--metric accepts exactly: accuracy, confidence, f1-score, all (default all).

Step 4: See how certain the model is about its predictions

ai-learner analyze --metric confidence

Expected Output: The confidence score distribution per intent

Step 5: F1 score per intent (precision and recall balanced)

ai-learner analyze --metric f1-score --json

Expected Output: Envelope with the F1 score for each intent

Step 6: Get the accuracy-over-time series so you can spot a plateau

ai-learner analyze --learning-curve

Expected Output: The default metric summary plus the all-time learning-run accuracy series

Note

--learning-curve appends the complete learning-run history; --period does not filter the curve.

Step 7: Analyze the entire history, machine-readable

ai-learner analyze --period all-time --json

Expected Output: Envelope with all-time accuracy and F1 data plus the confidence report for the last 7 days

Note

--period applies to accuracy and F1. Confidence remains a fixed 7-day calibration window.

Scenario 3: Report Generation

Turn the analysis into a JSON, Markdown or HTML document. `report` can write files, so it is auth-gated and its --output path is confined to the results directory.

Step 1: Print a summary report as JSON on stdout

sudo ai-learner report

Expected Output: A JSON report covering the last 30 days

Note

Requires a prior `online-auth` login (report is auth-gated because --output can write files). --format defaults to json and --period to last-30-days.

Step 2: Print the report as Markdown so you can paste it somewhere

sudo ai-learner report --format markdown

Expected Output: A Markdown document with the metric tables

Note

Requires a prior `online-auth` login. --format accepts exactly: json, markdown, html.

Step 3: A weekly report instead of the 30-day default

sudo ai-learner report --period last-7-days

Expected Output: A JSON report covering the last 7 days

Note

Requires a prior `online-auth` login. --period accepts: last-day, last-7-days, last-30-days, last-year, all-time.

Step 4: Write an HTML report to a file

sudo ai-learner report --format html --output learning-report.html

Expected Output: The report is written to the results directory as learning-report.html and the path is printed

Note

Requires a prior `online-auth` login. --output is ALREADY relative to the results directory: pass a bare filename. Do not prefix it with `results/` or the file lands in results/results/. Parent ("..") components are rejected.

Step 5: Write a full-history Markdown report to a file

sudo ai-learner report --period all-time --format markdown --output learning-report.md

Expected Output: learning-report.md written inside the results directory

Note

Requires a prior `online-auth` login. Overwrites the file if it already exists.

Step 6: Wrap the Markdown report inside a JSON envelope for a pipeline

sudo ai-learner report --period all-time --format markdown --json

Expected Output: Envelope whose payload carries the rendered Markdown

Note

Requires a prior `online-auth` login. --format selects the REPORT body; --json selects the ENVELOPE. They are independent.

Scenario 4: Status and Health

Check what the learner has collected so far. `status` is read-only: no authentication, no root.

Step 1: See whether the learner is initialized and what it has stored

ai-learner status

Expected Output: Whether the database exists, plus totals for predictions, feedback entries, learning runs, user queries and intents, and the last prediction, feedback and learning-run timestamps

Step 2: The same status as a JSON envelope for the dashboard

ai-learner status --json

Expected Output: Envelope with initialized, database_path, database_exists, the totals map, the last-7-days map and the last_* timestamps

Step 3: Add the SQLite database statistics

ai-learner status --verbose

Expected Output: The status block plus total_size_bytes, total_size_mb, page_count, page_size, freelist_count and fragmentation_percent

Note

Use the fragmentation percentage to decide whether the database needs a vacuum.

Scenario 5: Typical Workflow

The order these commands are normally run in: check what has been collected, look at the trend, then learn and publish a report.

Step 1: Step 1: is there enough feedback to be worth learning from

ai-learner status --json

Expected Output: Envelope with the feedback and prediction totals

Step 2: Step 2: has accuracy moved in the last day

ai-learner analyze --period last-day --json

Expected Output: Envelope with the per-intent metrics for the last day

Step 3: Step 3: fold the new feedback into the model

sudo ai-learner learn --incremental

Expected Output: An incremental learning summary with the convergence data

Note

Requires a prior `online-auth` login.

Step 4: Step 4: leave a weekly artifact behind for review

sudo ai-learner report --period last-7-days --format markdown --output weekly-review.md

Expected Output: weekly-review.md written inside the results directory

Note

Requires a prior `online-auth` login. The path is relative to the results directory already.

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
1	General error
0	Success
4	Network error
2	Invalid arguments
5	File not found
3	Permission denied