{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:23Z", "binary_name": "ai-learner" }, "binary": { "name": "ai-learner", "path": "/opt/kodachi/dashboard/hooks/ai-learner", "timestamp": "2026-07-21T01:54:23Z", "file_info": { "size": 24381444, "sha256": "282af9d807bf64f570680947890c7c1eb2d5a5445e1839fd18f2266f9f3a1c1b" }, "flag_n": { "status": "success", "timestamp": "2026-07-21T01:54:23.409072156Z", "command": "info", "version": "9.8.4", "data": { "name": "ai-learner", "version": "9.8.4", "author": "Warith Al Maawali ", "description": "AI learning engine for continuous improvement and performance analysis", "copyright": "© 2013-2026 Warith Al Maawali - Kodachi OS", "website": "https://kodachi.cloud", "license": "LicenseRef-Kodachi-SAN-1.1", "features": [ "Feedback aggregation and analysis", "Incremental learning with convergence detection", "Performance tracking and trend analysis", "Multi-format report generation (JSON, Markdown, HTML)" ], "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:23.633092942Z", "command": "version", "version": "9.8.4", "data": { "name": "ai-learner", "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:23.928712879Z", "command": "help", "version": "9.8.4", "data": { "name": "ai-learner", "description": "AI learning engine for continuous improvement and performance analysis", "usage": "ai-learner [OPTIONS] [COMMAND] [ARGS]", "commandCategories": [ { "category": "Analysis Operations", "commands": [ { "name": "analyze", "description": "Analyze model performance and trends", "usage": "ai-learner analyze [OPTIONS]", "options": [ { "flag": "--period ", "description": "Accuracy and F1 window: last-day, last-7-days, last-30-days, last-year or all-time. Confidence always uses the last 7 days", "default": "last-7-days" }, { "flag": "--metric ", "description": "Metric to report: accuracy, confidence, f1-score or all", "default": "all" }, { "flag": "--learning-curve", "description": "Append the all-time learning-run accuracy series to the selected metric summary" }, { "flag": "--json", "description": "Emit the per-intent metrics as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-learner analyze", "ai-learner analyze --period last-7-days", "ai-learner analyze --metric accuracy --json", "ai-learner analyze --learning-curve" ] } ] }, { "category": "Learning Operations", "commands": [ { "name": "learn", "description": "Run learning cycle to improve model based on feedback", "usage": "ai-learner learn [OPTIONS]", "options": [ { "flag": "--incremental", "description": "Only process feedback recorded since the last learning run. Needs a previous full run to have a baseline" }, { "flag": "--learning-rate ", "description": "Override the learning rate. Must be finite and inside (0.0, 1.0]", "default": "the engine default" }, { "flag": "--min-feedback ", "description": "Skip the learning run unless at least this many feedback entries exist" }, { "flag": "--output-policy", "description": "After learning, write and sign results/ai-policy.json (intent thresholds, tool allowlist, risk mode). Overwrites the existing policy" }, { "flag": "--json", "description": "Emit the learning metrics as a JSON envelope" } ], "requires_sudo": false, "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" ] } ] }, { "category": "Reporting Operations", "commands": [ { "name": "report", "description": "Generate comprehensive performance reports", "usage": "ai-learner report [OPTIONS]", "options": [ { "flag": "--format ", "description": "Body of the report: json, markdown or html", "default": "json" }, { "flag": "--output ", "description": "Write the report to this file. The path is ALREADY relative to the results directory, so pass a bare filename (not results/). Parent (\"..\") components are rejected", "default": "print to stdout" }, { "flag": "--period ", "description": "Window to report on: last-day, last-7-days, last-30-days, last-year or all-time", "default": "last-30-days" }, { "flag": "--json", "description": "Wrap the result in a JSON envelope. Independent of --format, which selects the report body" } ], "requires_sudo": false, "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" ] } ] }, { "category": "Status Operations", "commands": [ { "name": "status", "description": "Show ai-learner status, database health, and activity metrics", "usage": "ai-learner status [OPTIONS]", "options": [ { "flag": "--verbose", "description": "Also report the SQLite statistics: size, pages, freelist and fragmentation percent" }, { "flag": "--json", "description": "Emit initialized, database_path, database_exists, the totals, the last-7-days counts and the last_* timestamps as a JSON envelope" } ], "requires_sudo": false, "examples": [ "ai-learner status", "ai-learner status --json", "ai-learner status --verbose" ] } ] } ], "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": { "5": "File not found", "4": "Network error", "1": "General error", "0": "Success", "2": "Invalid arguments", "3": "Permission denied" } }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } }, "flag_e": { "status": "success", "timestamp": "2026-07-21T01:54:24.998935379Z", "command": "examples", "version": "9.8.4", "data": { "name": "ai-learner", "description": "Usage examples for ai-learner", "categories": [ { "id": "1_basic_learning", "title": "Basic Learning Operations", "description": "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.", "examples": [ { "command": "sudo ai-learner learn", "description": "Run a full learning cycle over all stored feedback", "expectedOutput": "A learning summary: feedback processed, accuracy before and after, and whether the run converged", "notes": "Requires a prior `online-auth` login (learn is not read-only)." }, { "command": "sudo ai-learner learn --incremental", "description": "Only process feedback that arrived since the last learning run", "expectedOutput": "A shorter summary covering just the new feedback delta", "notes": "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." }, { "command": "sudo ai-learner learn --json", "description": "Full learning cycle with a machine-readable result", "expectedOutput": "Envelope with the learning metrics for the run", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner learn --learning-rate 0.05", "description": "Slow the convergence down with a smaller learning rate", "expectedOutput": "The same learning summary, computed with the rate you passed", "notes": "Requires a prior `online-auth` login. --learning-rate must be finite and inside (0.0, 1.0]; anything else is rejected." }, { "command": "sudo ai-learner learn --min-feedback 100", "description": "Refuse to learn unless at least 100 feedback entries exist", "expectedOutput": "Either a normal learning run, or a message that learning was skipped for insufficient feedback", "notes": "Requires a prior `online-auth` login. Use this to avoid retraining on a statistically meaningless sample." }, { "command": "sudo ai-learner learn --learning-rate 0.05 --min-feedback 100 --json", "description": "A tuned learning run with both guards and JSON output", "expectedOutput": "Envelope with the metrics of the run, or the skipped reason", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner learn --output-policy", "description": "Learn, then write the signed AI policy file the runtime reads", "expectedOutput": "The learning summary plus results/ai-policy.json written and signed", "notes": "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." }, { "command": "sudo ai-learner learn --output-policy --json", "description": "Learn and regenerate the policy in one step, machine-readable", "expectedOutput": "Envelope with the learning metrics; after a successful learning run, results/ai-policy.json is also written and signed", "notes": "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." } ] }, { "id": "2_performance_analysis", "title": "Performance Analysis", "description": "Look at how well the model is doing, per intent and over time. `analyze` is read-only: it needs no authentication and no root.", "examples": [ { "command": "ai-learner analyze", "description": "Analyze every metric over the default window", "expectedOutput": "A per-intent breakdown of accuracy, confidence and F1 score over the last 7 days", "notes": "--period defaults to last-7-days and --metric defaults to all, so bare `analyze` is not an empty query." }, { "command": "ai-learner analyze --period last-7-days", "description": "Analyze performance over the past week", "expectedOutput": "Per-intent accuracy and the trend across the window", "notes": "--period accepts exactly: last-day, last-7-days, last-30-days, last-year, all-time." }, { "command": "ai-learner analyze --metric accuracy --json", "description": "Just the accuracy metric, machine-readable", "expectedOutput": "Envelope with the per-intent accuracy breakdown", "notes": "--metric accepts exactly: accuracy, confidence, f1-score, all (default all)." }, { "command": "ai-learner analyze --metric confidence", "description": "See how certain the model is about its predictions", "expectedOutput": "The confidence score distribution per intent" }, { "command": "ai-learner analyze --metric f1-score --json", "description": "F1 score per intent (precision and recall balanced)", "expectedOutput": "Envelope with the F1 score for each intent" }, { "command": "ai-learner analyze --learning-curve", "description": "Get the accuracy-over-time series so you can spot a plateau", "expectedOutput": "The default metric summary plus the all-time learning-run accuracy series", "notes": "--learning-curve appends the complete learning-run history; --period does not filter the curve." }, { "command": "ai-learner analyze --period all-time --json", "description": "Analyze the entire history, machine-readable", "expectedOutput": "Envelope with all-time accuracy and F1 data plus the confidence report for the last 7 days", "notes": "--period applies to accuracy and F1. Confidence remains a fixed 7-day calibration window." } ] }, { "id": "3_reporting", "title": "Report Generation", "description": "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.", "examples": [ { "command": "sudo ai-learner report", "description": "Print a summary report as JSON on stdout", "expectedOutput": "A JSON report covering the last 30 days", "notes": "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." }, { "command": "sudo ai-learner report --format markdown", "description": "Print the report as Markdown so you can paste it somewhere", "expectedOutput": "A Markdown document with the metric tables", "notes": "Requires a prior `online-auth` login. --format accepts exactly: json, markdown, html." }, { "command": "sudo ai-learner report --period last-7-days", "description": "A weekly report instead of the 30-day default", "expectedOutput": "A JSON report covering the last 7 days", "notes": "Requires a prior `online-auth` login. --period accepts: last-day, last-7-days, last-30-days, last-year, all-time." }, { "command": "sudo ai-learner report --format html --output learning-report.html", "description": "Write an HTML report to a file", "expectedOutput": "The report is written to the results directory as learning-report.html and the path is printed", "notes": "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." }, { "command": "sudo ai-learner report --period all-time --format markdown --output learning-report.md", "description": "Write a full-history Markdown report to a file", "expectedOutput": "learning-report.md written inside the results directory", "notes": "Requires a prior `online-auth` login. Overwrites the file if it already exists." }, { "command": "sudo ai-learner report --period all-time --format markdown --json", "description": "Wrap the Markdown report inside a JSON envelope for a pipeline", "expectedOutput": "Envelope whose payload carries the rendered Markdown", "notes": "Requires a prior `online-auth` login. --format selects the REPORT body; --json selects the ENVELOPE. They are independent." } ] }, { "id": "4_status", "title": "Status and Health", "description": "Check what the learner has collected so far. `status` is read-only: no authentication, no root.", "examples": [ { "command": "ai-learner status", "description": "See whether the learner is initialized and what it has stored", "expectedOutput": "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" }, { "command": "ai-learner status --json", "description": "The same status as a JSON envelope for the dashboard", "expectedOutput": "Envelope with initialized, database_path, database_exists, the totals map, the last-7-days map and the last_* timestamps" }, { "command": "ai-learner status --verbose", "description": "Add the SQLite database statistics", "expectedOutput": "The status block plus total_size_bytes, total_size_mb, page_count, page_size, freelist_count and fragmentation_percent", "notes": "Use the fragmentation percentage to decide whether the database needs a vacuum." } ] }, { "id": "5_workflow", "title": "Typical Workflow", "description": "The order these commands are normally run in: check what has been collected, look at the trend, then learn and publish a report.", "examples": [ { "command": "ai-learner status --json", "description": "Step 1: is there enough feedback to be worth learning from", "expectedOutput": "Envelope with the feedback and prediction totals" }, { "command": "ai-learner analyze --period last-day --json", "description": "Step 2: has accuracy moved in the last day", "expectedOutput": "Envelope with the per-intent metrics for the last day" }, { "command": "sudo ai-learner learn --incremental", "description": "Step 3: fold the new feedback into the model", "expectedOutput": "An incremental learning summary with the convergence data", "notes": "Requires a prior `online-auth` login." }, { "command": "sudo ai-learner report --period last-7-days --format markdown --output weekly-review.md", "description": "Step 4: leave a weekly artifact behind for review", "expectedOutput": "weekly-review.md written inside the results directory", "notes": "Requires a prior `online-auth` login. The path is relative to the results directory already." } ] } ], "quickReference": [ "ai-learner --help", "ai-learner --version", "ai-learner --info --json", "ai-learner --examples", "ai-learner status", "ai-learner analyze --period last-7-days", "sudo ai-learner learn", "sudo ai-learner report --format markdown" ] }, "errors": [], "warnings": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" } } } }