kaax-mcp 0.1.10 → 0.1.11

package/dist/index.js

@@ -30,7 +30,7 @@ import { buildResources } from "./resources.js";
 import { buildPrompts } from "./prompts.js";
 import { runInit } from "./init.js";
 const SERVER_NAME = "kaax-mcp";
-const SERVER_VERSION = "0.1.10";
+const SERVER_VERSION = "0.1.11";
 function bail(msg) {
     // stderr only — MCP clients pipe stdout for protocol traffic.
     process.stderr.write(`[${SERVER_NAME}] ${msg}\n`);

package/dist/python.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Python + ultralytics bridge — detect what the user already has so YOLO
+ * training can be driven locally. Same philosophy as gdal.ts: we never
+ * bundle multi-hundred-MB native deps, we probe for them on PATH and
+ * give per-OS install hints when missing.
+ *
+ * What we look for:
+ *   - python3 / python (in that order — POSIX prefers `python3`, Windows
+ *     often only has `python` on PATH).
+ *   - pip (via `python -m pip --version`).
+ *   - ultralytics package (via `python -c "import ultralytics"`).
+ *   - CUDA availability through PyTorch (the user might have ultralytics
+ *     on CPU only — training a YOLOv8/11 on CPU is 30-100× slower, so
+ *     it's worth surfacing).
+ *
+ * Security:
+ *   - execFile only (no shell). User-controlled paths never enter argv.
+ *   - 5-15 s timeouts on every probe.
+ *   - We treat `python` invocations the same as any other PATH binary;
+ *     the user's local PATH is the trust boundary.
+ */
+export interface ToolPresence {
+    available: boolean;
+    command?: string;
+    version?: string;
+}
+export interface CudaInfo {
+    available: boolean;
+    deviceName?: string;
+    deviceCount?: number;
+}
+export interface PythonCheckResult {
+    /** True iff python + ultralytics are both reachable (the minimum needed to train). */
+    ready: boolean;
+    python: ToolPresence;
+    pip: ToolPresence;
+    ultralytics: ToolPresence;
+    /** Undefined if we can't determine (ultralytics or torch missing). */
+    cuda?: CudaInfo;
+    /** Per-OS install instructions per dependency. */
+    installHints: {
+        python: string;
+        ultralytics: string;
+        cuda: string;
+    };
+}
+/**
+ * Probe the user's PATH for a working Python + ultralytics setup.
+ * Order: python3 → python (Windows fallback). Each subsequent probe
+ * uses the python we found; we don't mix interpreters.
+ */
+export declare function checkTrainingEnvironment(): Promise<PythonCheckResult>;

package/dist/python.js

@@ -0,0 +1,152 @@
+/**
+ * Python + ultralytics bridge — detect what the user already has so YOLO
+ * training can be driven locally. Same philosophy as gdal.ts: we never
+ * bundle multi-hundred-MB native deps, we probe for them on PATH and
+ * give per-OS install hints when missing.
+ *
+ * What we look for:
+ *   - python3 / python (in that order — POSIX prefers `python3`, Windows
+ *     often only has `python` on PATH).
+ *   - pip (via `python -m pip --version`).
+ *   - ultralytics package (via `python -c "import ultralytics"`).
+ *   - CUDA availability through PyTorch (the user might have ultralytics
+ *     on CPU only — training a YOLOv8/11 on CPU is 30-100× slower, so
+ *     it's worth surfacing).
+ *
+ * Security:
+ *   - execFile only (no shell). User-controlled paths never enter argv.
+ *   - 5-15 s timeouts on every probe.
+ *   - We treat `python` invocations the same as any other PATH binary;
+ *     the user's local PATH is the trust boundary.
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+const execFileP = promisify(execFile);
+const TIMEOUTS = {
+    version: 5_000,
+    import: 15_000, // importing ultralytics is slow first time (it pulls in torch)
+};
+/**
+ * Probe the user's PATH for a working Python + ultralytics setup.
+ * Order: python3 → python (Windows fallback). Each subsequent probe
+ * uses the python we found; we don't mix interpreters.
+ */
+export async function checkTrainingEnvironment() {
+    const result = {
+        ready: false,
+        python: { available: false },
+        pip: { available: false },
+        ultralytics: { available: false },
+        installHints: {
+            python: pythonInstallHint(),
+            ultralytics: "Once you have Python on PATH:\n  python -m pip install ultralytics\n(adds torch + everything else needed for YOLOv8 / v11 training.)",
+            cuda: "For GPU acceleration: install CUDA 11.8+ and the matching PyTorch from\n  https://pytorch.org/get-started/locally/\nIf you skip this, training falls back to CPU — works, but 30-100× slower on real datasets.",
+        },
+    };
+    // 1. Find a Python. Order:
+    //    - python3: POSIX standard
+    //    - python : Linux fallback, also Windows when properly installed
+    //    - py     : Windows Python Launcher (`py.exe`), the only command
+    //               that works on a fresh Windows install with Python from
+    //               python.org if 'Add to PATH' was unchecked.
+    for (const cmd of ["python3", "python", "py"]) {
+        try {
+            const { stdout, stderr } = await execFileP(cmd, ["--version"], {
+                timeout: TIMEOUTS.version,
+            });
+            // Python prints to stderr on some versions, stdout on others. On
+            // Windows, an un-installed `python` resolves to the Microsoft
+            // Store app-execution stub, which exits non-zero — that throws
+            // and falls through to the next candidate.
+            const line = (stdout || stderr).trim().split("\n")[0];
+            if (line.toLowerCase().startsWith("python")) {
+                result.python = { available: true, command: cmd, version: line };
+                break;
+            }
+        }
+        catch {
+            /* try next */
+        }
+    }
+    if (!result.python.available)
+        return result;
+    // 2. pip via `python -m pip`. Robust to setups where `pip` itself isn't
+    //    on PATH but is invokable as a module.
+    try {
+        const { stdout } = await execFileP(result.python.command, ["-m", "pip", "--version"], { timeout: TIMEOUTS.version });
+        result.pip = {
+            available: true,
+            command: `${result.python.command} -m pip`,
+            version: stdout.trim().split("\n")[0],
+        };
+    }
+    catch {
+        /* pip missing — keep going, we still want to report what we have */
+    }
+    // 3. ultralytics — single-shot import. First run is slow (~10 s on a
+    //    cold install) because it pulls torch into the namespace.
+    try {
+        const { stdout } = await execFileP(result.python.command, [
+            "-c",
+            "import ultralytics, sys; sys.stdout.write(ultralytics.__version__)",
+        ], { timeout: TIMEOUTS.import });
+        result.ultralytics = {
+            available: true,
+            version: stdout.trim(),
+        };
+    }
+    catch {
+        /* not installed */
+    }
+    if (result.ultralytics.available) {
+        // 4. CUDA via torch. We don't probe torch separately — it's a
+        //    transitive dep of ultralytics, so if ultralytics imports OK
+        //    torch is necessarily there.
+        try {
+            const probe = [
+                "import torch, sys",
+                "ok = torch.cuda.is_available()",
+                "name = torch.cuda.get_device_name(0) if ok else ''",
+                "count = torch.cuda.device_count() if ok else 0",
+                "sys.stdout.write(str(ok) + chr(10) + name + chr(10) + str(count))",
+            ].join("; ");
+            const { stdout } = await execFileP(result.python.command, ["-c", probe], { timeout: TIMEOUTS.import });
+            const lines = stdout.split("\n");
+            const ok = lines[0]?.trim() === "True";
+            result.cuda = {
+                available: ok,
+                deviceName: ok ? lines[1]?.trim() || undefined : undefined,
+                deviceCount: ok ? Number(lines[2]?.trim() ?? "0") : 0,
+            };
+        }
+        catch {
+            /* torch query failed; leave cuda undefined */
+        }
+    }
+    result.ready = result.python.available && result.ultralytics.available;
+    return result;
+}
+function pythonInstallHint() {
+    const os = process.platform;
+    if (os === "win32") {
+        return [
+            "Windows install: download Python 3.10+ from https://www.python.org/downloads/",
+            "Tick 'Add python.exe to PATH' on the first install screen.",
+            "After install, open a new PowerShell so the PATH refreshes, then re-run kaax_check_training_environment.",
+        ].join("\n");
+    }
+    if (os === "darwin") {
+        return [
+            "macOS install: with Homebrew (https://brew.sh/):",
+            "  brew install python",
+            "Restart your shell after install.",
+        ].join("\n");
+    }
+    return [
+        "Linux install:",
+        "  Debian / Ubuntu: sudo apt install python3 python3-pip python3-venv",
+        "  Fedora:          sudo dnf install python3 python3-pip",
+        "  Arch:            sudo pacman -S python python-pip",
+    ].join("\n");
+}
+//# sourceMappingURL=python.js.map

package/dist/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../src/python.ts"],"names":[],"mappings":"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"}

package/dist/tools.js

@@ -17,6 +17,8 @@ import { addIdField, bufferLayer, clipByMask, differenceLayers, extractFeaturesI
 import { clusterPointsByRow, detectRowOrientation, generateRowLines, } from "./gis-rows.js";
 import { defaultLayerName, exportLayersToExcel, generateMarkdownSummary, } from "./gis-reports.js";
 import { checkGdal, generateGeoPdf } from "./gdal.js";
+import { checkTrainingEnvironment } from "./python.js";
+import { getTrainingStatus, listTrainings, startTraining, validateDataset, } from "./training.js";
 import { existsSync } from "fs";
 import { mkdir } from "fs/promises";
 import { homedir } from "os";
@@ -411,6 +413,48 @@ const SummaryReportArgs = z.object({
     title: z.string().optional(),
 });
 const CheckGdalArgs = z.object({});
+const CheckTrainingEnvArgs = z.object({});
+const ValidateDatasetArgs = z.object({
+    path: z
+        .string()
+        .describe("Path to data.yaml OR to a directory that contains it. The tool will resolve the train/val image and label subdirectories from the YAML."),
+});
+const StartTrainingArgs = z.object({
+    dataYaml: z
+        .string()
+        .describe("Path to the dataset's data.yaml (resolve with kaax_validate_training_dataset first)."),
+    pythonCommand: z
+        .string()
+        .optional()
+        .describe("Python command to use. Defaults to whatever kaax_check_training_environment found."),
+    model: z
+        .string()
+        .optional()
+        .describe("Base weights — `yolo11n.pt` (default), `yolo11s.pt`, `yolo11m.pt`, etc."),
+    epochs: z.number().int().min(1).max(2000).optional().describe("Default 100."),
+    imgsz: z.number().int().min(64).optional().describe("Image size, default 640."),
+    batch: z
+        .number()
+        .int()
+        .optional()
+        .describe("Batch size. Default = auto (ultralytics' -1)."),
+    project: z
+        .string()
+        .optional()
+        .describe("YOLO output project dir. Default 'runs/detect'."),
+    name: z
+        .string()
+        .optional()
+        .describe("Run name under the project dir. Default 'kaax-mcp'."),
+    extraYoloArgs: z
+        .array(z.string())
+        .optional()
+        .describe("Optional extra args forwarded verbatim to the YOLO Python API. Refused if they contain shell metacharacters."),
+});
+const CheckTrainingStatusArgs = z.object({
+    trainingId: z.string().min(8).describe("ID returned by kaax_start_yolo_training"),
+});
+const ListTrainingsArgs = z.object({});
 const GenerateGeoPdfArgs = z.object({
     layers: z
         .array(z.object({
@@ -1586,6 +1630,199 @@ export function buildTools() {
                 }
             },
         },
+        // ── Local YOLO training — environment detection ──────────────────
+        {
+            name: "kaax_check_training_environment",
+            description: "[Free] Probe the user's machine for the Python + ultralytics + CUDA stack needed to train a YOLO model locally. Reports what's present (Python version, pip, ultralytics version, GPU name if available) and provides per-OS install commands for whatever is missing. Call this BEFORE any training tool so the user knows what to install. The training itself runs entirely on the user's machine — Kaax's server never sees the dataset.",
+            inputSchema: zodToJsonSchema(CheckTrainingEnvArgs),
+            async handler() {
+                try {
+                    const r = await checkTrainingEnvironment();
+                    const lines = [];
+                    if (r.ready) {
+                        lines.push("✅ Ready to train YOLO locally.");
+                    }
+                    else {
+                        lines.push("⚠️  Training environment is not complete yet.");
+                    }
+                    lines.push("");
+                    lines.push(`  • Python:       ${r.python.available ? `${r.python.version} (${r.python.command})` : "❌ not on PATH"}`);
+                    lines.push(`  • pip:          ${r.pip.available ? r.pip.version : "❌ not invokable"}`);
+                    lines.push(`  • ultralytics:  ${r.ultralytics.available ? r.ultralytics.version : "❌ not installed"}`);
+                    if (r.cuda) {
+                        lines.push(`  • CUDA / GPU:   ${r.cuda.available
+                            ? `✅ ${r.cuda.deviceName ?? "(unnamed GPU)"} · ${r.cuda.deviceCount ?? 1} device(s)`
+                            : "❌ unavailable — training will run on CPU (30-100× slower)"}`);
+                    }
+                    else if (r.ultralytics.available) {
+                        lines.push(`  • CUDA / GPU:   ⚠️  couldn't query torch`);
+                    }
+                    lines.push("");
+                    // Actionable install hints when something's missing.
+                    if (!r.python.available) {
+                        lines.push("📦 To install Python:");
+                        lines.push(r.installHints.python.split("\n").map((s) => `   ${s}`).join("\n"));
+                        lines.push("");
+                    }
+                    if (r.python.available && !r.ultralytics.available) {
+                        lines.push("📦 To install ultralytics (YOLO):");
+                        lines.push(r.installHints.ultralytics.split("\n").map((s) => `   ${s}`).join("\n"));
+                        lines.push("");
+                    }
+                    if (r.ready && r.cuda && !r.cuda.available) {
+                        lines.push("💡 Optional — to enable GPU training:");
+                        lines.push(r.installHints.cuda.split("\n").map((s) => `   ${s}`).join("\n"));
+                        lines.push("");
+                    }
+                    if (r.ready) {
+                        lines.push("Next: kaax_validate_training_dataset (Phase 2B) once it ships — for now, this tool tells you the env is ready and you can run `yolo train …` by hand.");
+                    }
+                    return text(...lines);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_validate_training_dataset",
+            description: "[Free] Sanity-check a local YOLO dataset before training. Resolves data.yaml + train/val image and label dirs, counts files, lists class names. Reports issues (missing dirs, no val set, missing names) so the user fixes them BEFORE wasting GPU hours on a broken dataset.",
+            inputSchema: zodToJsonSchema(ValidateDatasetArgs),
+            async handler(args) {
+                try {
+                    const { path } = ValidateDatasetArgs.parse(args);
+                    const r = await validateDataset(path);
+                    const lines = [];
+                    if (r.ok) {
+                        lines.push("✅ Dataset looks ready to train.");
+                    }
+                    else {
+                        lines.push("⚠️  Dataset has issues — fix them before training.");
+                    }
+                    lines.push("");
+                    if (r.dataYamlPath)
+                        lines.push(`   data.yaml: ${r.dataYamlPath}`);
+                    if (r.classes && r.classes.length > 0) {
+                        lines.push(`   Classes (${r.classes.length}): ${r.classes.slice(0, 10).join(", ")}${r.classes.length > 10 ? ", …" : ""}`);
+                    }
+                    if (r.imagesTrain)
+                        lines.push(`   Train images: ${r.imagesTrain.fileCount} files in ${r.imagesTrain.path}`);
+                    if (r.labelsTrain)
+                        lines.push(`   Train labels: ${r.labelsTrain.fileCount} files in ${r.labelsTrain.path}`);
+                    if (r.imagesVal)
+                        lines.push(`   Val images:   ${r.imagesVal.fileCount} files in ${r.imagesVal.path}`);
+                    if (r.labelsVal)
+                        lines.push(`   Val labels:   ${r.labelsVal.fileCount} files in ${r.labelsVal.path}`);
+                    if (r.issues.length > 0) {
+                        lines.push("");
+                        lines.push("Issues:");
+                        for (const i of r.issues) {
+                            lines.push(`   ${i.level === "error" ? "🔴" : "🟡"} ${i.message}`);
+                        }
+                    }
+                    return text(...lines);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_start_yolo_training",
+            description: "[Free] Kick off YOLO training **locally** as a detached background process. Returns a trainingId immediately; the training continues even if the MCP exits. Poll kaax_check_training_status with the trainingId to watch progress. The dataset never leaves the user's machine — Kaax's server is not involved. Requires Python + ultralytics on PATH (see kaax_check_training_environment).",
+            inputSchema: zodToJsonSchema(StartTrainingArgs),
+            async handler(args) {
+                try {
+                    const parsed = StartTrainingArgs.parse(args);
+                    let python = parsed.pythonCommand;
+                    if (!python) {
+                        const env = await checkTrainingEnvironment();
+                        if (!env.ready || !env.python.command) {
+                            return text("❌ Cannot start training — Python or ultralytics is missing. Run kaax_check_training_environment for install instructions.");
+                        }
+                        python = env.python.command;
+                    }
+                    const meta = await startTraining({
+                        pythonCommand: python,
+                        dataYaml: parsed.dataYaml,
+                        model: parsed.model,
+                        epochs: parsed.epochs,
+                        imgsz: parsed.imgsz,
+                        batch: parsed.batch,
+                        project: parsed.project,
+                        name: parsed.name,
+                        extraYoloArgs: parsed.extraYoloArgs,
+                    });
+                    return text("🚀 Training started in the background.", "", `   Training id : ${meta.id}`, `   Process id  : ${meta.pid}`, `   Model       : ${meta.model}`, `   Epochs      : ${meta.epochs}`, `   Image size  : ${meta.imgsz}`, `   Batch       : ${meta.batch}`, `   Logs        : ~/.kaax/training/${meta.id}/stdout.log`, "", "Use kaax_check_training_status(trainingId) to poll progress.", "Heads up: on CPU this can take many hours per epoch — go grab coffee.");
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_check_training_status",
+            description: "[Free] Poll the state of a training run started with kaax_start_yolo_training. Reports whether the process is still alive, how many epochs have completed (from the log), and the path to `best.pt` once training finishes. Safe to call repeatedly.",
+            inputSchema: zodToJsonSchema(CheckTrainingStatusArgs),
+            async handler(args) {
+                try {
+                    const { trainingId } = CheckTrainingStatusArgs.parse(args);
+                    const s = await getTrainingStatus(trainingId);
+                    const lines = [];
+                    const m = s.meta;
+                    lines.push(`Training ${m.id} — status: ${m.status}`);
+                    lines.push(`   Started: ${m.startedAt}`);
+                    if (m.endedAt)
+                        lines.push(`   Ended:   ${m.endedAt}`);
+                    lines.push(`   Model: ${m.model}  ·  epochs: ${m.epochs}  ·  imgsz: ${m.imgsz}`);
+                    if (s.epochsCompleted !== undefined) {
+                        lines.push(`   Epochs completed: ${s.epochsCompleted}/${m.epochs}`);
+                    }
+                    if (s.bestPt) {
+                        lines.push(`   best.pt: ${s.bestPt}`);
+                    }
+                    if (m.exitCode !== undefined && m.exitCode !== null) {
+                        lines.push(`   Exit code: ${m.exitCode}`);
+                    }
+                    lines.push("");
+                    lines.push("Recent log:");
+                    for (const line of s.logTail.slice(-12)) {
+                        lines.push(`   ${line}`);
+                    }
+                    if (m.status === "completed") {
+                        lines.push("");
+                        lines.push("✅ Training done. Next: upload the model to Kaax with kaax_upload_model_to_kaax (Phase 2C — coming).");
+                    }
+                    return text(...lines);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
+        {
+            name: "kaax_list_trainings",
+            description: "[Free] List every YOLO training run kept under ~/.kaax/training. Newest first. Useful when the user has lost track of a trainingId.",
+            inputSchema: zodToJsonSchema(ListTrainingsArgs),
+            async handler() {
+                try {
+                    const all = await listTrainings();
+                    if (all.length === 0) {
+                        return text("No training runs found under ~/.kaax/training. Start one with kaax_start_yolo_training.");
+                    }
+                    const lines = [`Found ${all.length} training run(s):`, ""];
+                    for (const m of all.slice(0, 20)) {
+                        lines.push(`  • ${m.id}  ${m.status.padEnd(10)} ${m.startedAt}  ${m.model}  epochs=${m.epochs}`);
+                    }
+                    if (all.length > 20)
+                        lines.push(`  … and ${all.length - 20} more`);
+                    return text(...lines);
+                }
+                catch (err) {
+                    return errorText(err);
+                }
+            },
+        },
         {
             name: "kaax_cross_validate_analyses",
             description: "[Pro] High-level orchestrator for the canonical 'lines of A inside zones of B' cross-validation. Given two analysisIds (Pro because it reads analyses): downloads both, locates the SHP layers inside each report ZIP, runs extract_features_in_polygons, writes <outputDir>/<idA>_inside.zip + _outside.zip, and reports stats. One tool call does what would otherwise need 5.",