@2kw/ai 4.0.0-dev.2

package/dist/commands/experiments.js

@@ -0,0 +1,255 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { getClient, runAction } from "../lib/client.js";
+import { formatPage, formatDetail, formatList, formatSuccess, withSpinner } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { isJsonOutput } from "../lib/config.js";
+const TERMINAL_STATUSES = new Set(["COMPLETED", "FAILED"]);
+export function makeExperimentsCommand() {
+    const cmd = new Command("experiments").description("Manage experiments");
+    // ── list ──────────────────────────────────────────────────────
+    const list = new Command("list").description("List experiments");
+    addPaginationOptions(list);
+    list.option("-s, --search <term>", "Filter by name");
+    list.option("--status <status>", "Filter by status (DRAFT, RUNNING, COMPLETED, FAILED)");
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/experiments", {
+                params: {
+                    query: { search: opts.search, status: opts.status, ...paginationParams(opts) },
+                },
+            });
+            formatPage(data, command, ["id", "name", "status", "type", "datasetVersionId", "createdAt"]);
+        });
+    });
+    cmd.addCommand(list);
+    // ── get ───────────────────────────────────────────────────────
+    cmd
+        .command("get")
+        .description("Get an experiment by ID")
+        .argument("<id>", "Experiment ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/experiments/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── create ────────────────────────────────────────────────────
+    cmd
+        .command("create")
+        .description("Create a new experiment")
+        .requiredOption("-n, --name <name>", "Experiment name")
+        .option("-d, --description <text>", "Experiment description")
+        .option("-t, --type <type>", "Experiment type")
+        .option("--dataset-version <id>", "Dataset version ID to evaluate against")
+        .option("--metadata <json>", "Metadata (JSON)")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = { name: opts.name };
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.type !== undefined)
+                body.type = opts.type;
+            if (opts.datasetVersion !== undefined)
+                body.datasetVersionId = opts.datasetVersion;
+            if (opts.metadata)
+                body.metadata = JSON.parse(opts.metadata);
+            const { data } = await client.POST("/v1/experiments", {
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── update ────────────────────────────────────────────────────
+    cmd
+        .command("update")
+        .description("Update an experiment")
+        .argument("<id>", "Experiment ID")
+        .option("-n, --name <name>", "New name")
+        .option("-d, --description <text>", "New description")
+        .option("-t, --type <type>", "New type")
+        .option("--dataset-version <id>", "Dataset version ID")
+        .option("--metadata <json>", "Metadata (JSON)")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = {};
+            if (opts.name)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.type !== undefined)
+                body.type = opts.type;
+            if (opts.datasetVersion !== undefined)
+                body.datasetVersionId = opts.datasetVersion;
+            if (opts.metadata)
+                body.metadata = JSON.parse(opts.metadata);
+            const { data } = await client.PUT("/v1/experiments/{id}", {
+                params: { path: { id } },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── delete ────────────────────────────────────────────────────
+    cmd
+        .command("delete")
+        .description("Delete an experiment")
+        .argument("<id>", "Experiment ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/experiments/{id}", {
+                params: { path: { id } },
+            });
+            formatSuccess(`Experiment ${id} deleted.`, command);
+        });
+    });
+    // ── add-variant ───────────────────────────────────────────────
+    cmd
+        .command("add-variant")
+        .description("Add a variant to an experiment")
+        .requiredOption("--experiment <id>", "Experiment ID")
+        .requiredOption("-n, --name <name>", "Variant name")
+        .requiredOption("--task-type <type>", "Task type")
+        .requiredOption("--config <json>", "Variant configuration (JSON)")
+        .option("-d, --description <text>", "Variant description")
+        .option("--sort-order <n>", "Sort order", parseInt)
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = {
+                name: opts.name,
+                taskType: opts.taskType,
+                configuration: JSON.parse(opts.config),
+            };
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.sortOrder !== undefined)
+                body.sortOrder = opts.sortOrder;
+            const { data } = await client.POST("/v1/experiments/{id}/variants", {
+                params: {
+                    path: { id: opts.experiment },
+                },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── variants ──────────────────────────────────────────────────
+    cmd
+        .command("variants")
+        .description("List variants of an experiment")
+        .requiredOption("--experiment <id>", "Experiment ID")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/experiments/{id}/variants", {
+                params: {
+                    path: { id: opts.experiment },
+                },
+            });
+            formatList(data, command, ["id", "name", "taskType", "description", "sortOrder"]);
+        });
+    });
+    // ── run ───────────────────────────────────────────────────────
+    cmd
+        .command("run")
+        .description("Start an experiment run and wait for completion")
+        .argument("<id>", "Experiment ID")
+        .option("--variant <variantId>", "Run only the given variant instead of the full matrix")
+        .option("--no-wait", "Return immediately without polling for completion")
+        .option("--poll-interval <seconds>", "Poll interval in seconds", "5")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            // Start the run
+            const { data: run } = await withSpinner("Starting experiment run...", () => client.POST("/v1/experiments/{id}/runs", {
+                params: {
+                    path: { id },
+                },
+                body: opts.variant ? { variantId: opts.variant } : undefined,
+            }));
+            const runData = run;
+            const runId = runData?.id;
+            if (!opts.wait || isJsonOutput(command)) {
+                formatDetail(runData, command);
+                return;
+            }
+            console.log(chalk.green(`Run ${runId} started (status: ${runData?.status ?? "PENDING"})`));
+            // Poll until terminal status
+            const interval = parseInt(opts.pollInterval, 10) * 1000;
+            const spinner = ora("Running...").start();
+            while (true) {
+                await new Promise((r) => setTimeout(r, interval));
+                const { data: status } = await client.GET("/v1/experiments/{id}/runs/{runId}", {
+                    params: {
+                        path: { id, runId },
+                    },
+                });
+                const s = status;
+                const progress = s?.itemsTotal
+                    ? `${s.itemsCompleted ?? 0}/${s.itemsTotal}`
+                    : "...";
+                spinner.text = `Running... ${progress} items (${s?.status ?? "UNKNOWN"})`;
+                if (s?.status && TERMINAL_STATUSES.has(s.status)) {
+                    if (s.status === "COMPLETED") {
+                        spinner.succeed(`Run completed: ${progress} items`);
+                    }
+                    else {
+                        spinner.fail(`Run failed: ${s.itemsFailed ?? 0} failures`);
+                    }
+                    formatDetail(s, command);
+                    break;
+                }
+            }
+        });
+    });
+    // ── runs ──────────────────────────────────────────────────────
+    const runs = new Command("runs").description("List experiment runs");
+    addPaginationOptions(runs);
+    runs.requiredOption("--experiment <id>", "Experiment ID");
+    runs.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/experiments/{id}/runs", {
+                params: {
+                    path: { id: opts.experiment },
+                    query: paginationParams(opts),
+                },
+            });
+            formatPage(data, command, [
+                "id", "variantName", "status", "itemsCompleted", "itemsTotal", "itemsFailed", "startedAt", "completedAt",
+            ]);
+        });
+    });
+    cmd.addCommand(runs);
+    // ── results ───────────────────────────────────────────────────
+    const results = new Command("results").description("Get experiment run results");
+    addPaginationOptions(results);
+    results.requiredOption("--experiment <id>", "Experiment ID");
+    results.requiredOption("--run <id>", "Run ID");
+    results.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/experiments/{id}/runs/{runId}/results", {
+                params: {
+                    path: { id: opts.experiment, runId: opts.run },
+                    query: paginationParams(opts),
+                },
+            });
+            formatPage(data, command, [
+                "datasetItemId", "durationMs", "inputTokens", "outputTokens", "estimatedCost", "error",
+            ]);
+        });
+    });
+    cmd.addCommand(results);
+    return cmd;
+}
+//# sourceMappingURL=experiments.js.map

package/dist/commands/extractions.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makeExtractionsCommand(): Command;
+//# sourceMappingURL=extractions.d.ts.map

package/dist/commands/extractions.js

@@ -0,0 +1,134 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { getClient, runAction } from "../lib/client.js";
+import { formatPage, formatDetail, withSpinner } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+const IMAGE_MIME_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+    ".tiff": "image/tiff",
+};
+function readImages(paths) {
+    return paths.map((p) => {
+        const buffer = readFileSync(p);
+        const ext = extname(p).toLowerCase();
+        const mimeType = IMAGE_MIME_TYPES[ext] ?? "image/png";
+        return { data: buffer.toString("base64"), mimeType };
+    });
+}
+export function makeExtractionsCommand() {
+    const cmd = new Command("extractions").description("Manage extractions");
+    cmd
+        .command("create")
+        .description("Create a new extraction")
+        .requiredOption("--schema <id>", "Schema ID")
+        .requiredOption("-m, --model <model>", "Model to use (provider/model)")
+        .option("-t, --text <text>", "Input text (use - for stdin)")
+        .option("-f, --file <path>", "Read input text from file (use - for stdin)")
+        .option("--images <paths...>", "Image file paths")
+        .option("--version-id <id>", "Schema version ID")
+        .option("-l, --label <name>", "Schema label")
+        .option("--async", "Run asynchronously")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            let text = opts.text === "-" ? readFileSync(0, "utf-8") : opts.text;
+            if (opts.file) {
+                text = opts.file === "-" ? readFileSync(0, "utf-8") : readFileSync(opts.file, "utf-8");
+            }
+            const images = opts.images ? readImages(opts.images) : undefined;
+            const body = {
+                schemaId: opts.schema,
+                schemaVersionId: opts.versionId,
+                model: opts.model,
+                inputText: text,
+                inputImages: images,
+            };
+            if (opts.async) {
+                const { data } = await withSpinner("Extracting...", () => client.POST("/v1/extractions/async", {
+                    body,
+                }));
+                formatDetail(data, command);
+            }
+            else {
+                const { data } = await withSpinner("Extracting...", () => client.POST("/v1/extractions", {
+                    body,
+                }));
+                formatDetail(data, command);
+            }
+        });
+    });
+    cmd
+        .command("get")
+        .description("Get an extraction by ID")
+        .argument("<id>", "Extraction ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/extractions/{id}", { params: { path: { id } } });
+            formatDetail(data, command);
+        });
+    });
+    const list = new Command("list").description("List extractions");
+    addPaginationOptions(list);
+    list.option("-s, --search <term>", "Search text");
+    list.option("--schema-version <id>", "Filter by schema version ID");
+    list.option("--status <status>", "Filter by status (PENDING|PROCESSING|COMPLETED|FAILED)");
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/extractions", {
+                params: {
+                    query: {
+                        search: opts.search,
+                        schemaVersionId: opts.schemaVersion,
+                        status: opts.status,
+                        ...paginationParams(opts),
+                    },
+                },
+            });
+            formatPage(data, command, ["id", "schemaId", "model", "status", "totalTokens", "createdAt"]);
+        });
+    });
+    cmd.addCommand(list);
+    cmd
+        .command("estimate")
+        .description("Estimate token usage for an extraction")
+        .requiredOption("--schema <id>", "Schema ID")
+        .requiredOption("-m, --model <model>", "Model to use")
+        .option("-t, --text <text>", "Input text")
+        .option("--version-id <id>", "Schema version ID")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/extractions/estimate", {
+                body: {
+                    schemaId: opts.schema,
+                    schemaVersionId: opts.versionId,
+                    inputText: opts.text,
+                },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("rerun")
+        .description("Re-run an extraction")
+        .argument("<id>", "Extraction ID to rerun")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await withSpinner("Re-running extraction...", () => client.POST("/v1/extractions/{id}/rerun", {
+                params: { path: { id } },
+            }));
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=extractions.js.map

package/dist/commands/prompt-labels.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makePromptLabelsCommand(): Command;
+//# sourceMappingURL=prompt-labels.d.ts.map

package/dist/commands/prompt-labels.js

@@ -0,0 +1,67 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { formatList, formatDetail, formatSuccess } from "../lib/output.js";
+export function makePromptLabelsCommand() {
+    const cmd = new Command("labels").description("Manage prompt labels");
+    cmd
+        .command("list")
+        .description("List labels for a prompt")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/prompts/{promptId}/labels", { params: { path: { promptId: opts.prompt } } });
+            formatList(data, command, [
+                "name",
+                "promptVersionId",
+                "createdAt",
+            ]);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create a label for a prompt version")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .requiredOption("-n, --name <name>", "Label name")
+        .requiredOption("--version-id <id>", "Prompt version ID to label")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/prompts/{promptId}/labels", {
+                params: { path: { promptId: opts.prompt } },
+                body: { name: opts.name, promptVersionId: opts.versionId },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("update")
+        .description("Update a label to point to a different version")
+        .argument("<labelName>", "Label name")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .requiredOption("--version-id <id>", "New prompt version ID")
+        .action(async (labelName, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/prompts/{promptId}/labels/{labelName}", {
+                params: { path: { promptId: opts.prompt, labelName } },
+                body: { promptVersionId: opts.versionId },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("delete")
+        .description("Delete a prompt label")
+        .argument("<labelName>", "Label name")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .action(async (labelName, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/prompts/{promptId}/labels/{labelName}", { params: { path: { promptId: opts.prompt, labelName } } });
+            formatSuccess(`Label "${labelName}" deleted.`, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=prompt-labels.js.map

package/dist/commands/prompt-versions.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makePromptVersionsCommand(): Command;
+//# sourceMappingURL=prompt-versions.d.ts.map

package/dist/commands/prompt-versions.js

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { formatPage, formatDetail } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+export function makePromptVersionsCommand() {
+    const cmd = new Command("versions").description("Manage prompt versions");
+    const list = new Command("list").description("List versions of a prompt");
+    addPaginationOptions(list);
+    list.requiredOption("--prompt <id>", "Prompt ID");
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/prompts/{promptId}/versions", {
+                params: {
+                    path: { promptId: opts.prompt },
+                    query: paginationParams(opts),
+                },
+            });
+            formatPage(data, command, ["id", "version", "active", "changeDescription", "createdAt"]);
+        });
+    });
+    cmd.addCommand(list);
+    cmd
+        .command("get")
+        .description("Get a specific prompt version")
+        .argument("<versionId>", "Version ID")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .action(async (versionId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/prompts/{promptId}/versions/{versionId}", { params: { path: { promptId: opts.prompt, versionId } } });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create a new prompt version")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .requiredOption("-c, --content <text>", "Prompt content (template text)")
+        .option("-m, --message <text>", "Change description")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/prompts/{promptId}/versions", {
+                params: { path: { promptId: opts.prompt } },
+                body: { content: opts.content, changeDescription: opts.message },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("activate")
+        .description("Activate a prompt version")
+        .argument("<versionId>", "Version ID")
+        .requiredOption("--prompt <id>", "Prompt ID")
+        .action(async (versionId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.PUT("/v1/prompts/{promptId}/versions/{versionId}/activate", { params: { path: { promptId: opts.prompt, versionId } } });
+            formatDetail(data, command);
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=prompt-versions.js.map

package/dist/commands/prompts.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function makePromptsCommand(): Command;
+//# sourceMappingURL=prompts.d.ts.map