@2kw/ai 4.0.0-dev.2

package/dist/commands/datasets.js

@@ -0,0 +1,150 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { resolveLatestVersionId } from "../lib/datasets.js";
+import { formatPage, formatDetail, formatSuccess } from "../lib/output.js";
+import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
+import { makeDatasetVersionsCommand } from "./dataset-versions.js";
+export function makeDatasetsCommand() {
+    const cmd = new Command("datasets").description("Manage datasets");
+    const list = new Command("list").description("List datasets");
+    addPaginationOptions(list);
+    list.option("-s, --search <term>", "Filter by name");
+    list.option("-t, --type <type>", "Filter by type");
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/datasets", {
+                params: {
+                    query: { search: opts.search, type: opts.type, ...paginationParams(opts) },
+                },
+            });
+            formatPage(data, command, ["id", "name", "type", "description", "latestVersionId", "createdAt"]);
+        });
+    });
+    cmd.addCommand(list);
+    cmd
+        .command("get")
+        .description("Get a dataset by ID")
+        .argument("<id>", "Dataset ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/datasets/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create a new dataset")
+        .requiredOption("-n, --name <name>", "Dataset name")
+        .option("-d, --description <text>", "Dataset description")
+        .option("-t, --type <type>", "Dataset type")
+        .option("--input-schema <json>", "Input JSON Schema")
+        .option("--expected-output-schema <json>", "Expected output JSON Schema")
+        .option("--metadata <json>", "Metadata (JSON)")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const body = { name: opts.name };
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            if (opts.type !== undefined)
+                body.type = opts.type;
+            if (opts.inputSchema)
+                body.inputSchema = JSON.parse(opts.inputSchema);
+            if (opts.expectedOutputSchema)
+                body.expectedOutputSchema = JSON.parse(opts.expectedOutputSchema);
+            if (opts.metadata)
+                body.metadata = JSON.parse(opts.metadata);
+            const { data } = await client.POST("/v1/datasets", {
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("update")
+        .description("Update a dataset")
+        .argument("<id>", "Dataset ID")
+        .option("-n, --name <name>", "New name")
+        .option("-d, --description <text>", "New description")
+        .option("-t, --type <type>", "New type")
+        .option("--input-schema <json>", "Input JSON Schema")
+        .option("--expected-output-schema <json>", "Expected output JSON Schema")
+        .option("--metadata <json>", "Metadata (JSON)")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            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.inputSchema)
+                body.inputSchema = JSON.parse(opts.inputSchema);
+            if (opts.expectedOutputSchema)
+                body.expectedOutputSchema = JSON.parse(opts.expectedOutputSchema);
+            if (opts.metadata)
+                body.metadata = JSON.parse(opts.metadata);
+            const { data } = await client.PUT("/v1/datasets/{id}", {
+                params: { path: { id } },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("delete")
+        .description("Delete a dataset")
+        .argument("<id>", "Dataset ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/datasets/{id}", {
+                params: { path: { id } },
+            });
+            formatSuccess(`Dataset ${id} deleted.`, command);
+        });
+    });
+    cmd
+        .command("add-item")
+        .description("Add an item to a dataset (uses the latest version)")
+        .requiredOption("--dataset <id>", "Dataset ID")
+        .requiredOption("--input <json>", "Item input data (JSON)")
+        .option("--expected-output <json>", "Expected output (JSON)")
+        .option("--tags <tags...>", "Tags")
+        .option("--metadata <json>", "Metadata (JSON)")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const versionId = await resolveLatestVersionId(client, opts.dataset);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const body = {
+                input: JSON.parse(opts.input),
+            };
+            if (opts.expectedOutput)
+                body.expectedOutput = JSON.parse(opts.expectedOutput);
+            if (opts.tags)
+                body.tags = opts.tags;
+            if (opts.metadata)
+                body.metadata = JSON.parse(opts.metadata);
+            const { data } = await client.POST("/v1/datasets/{id}/versions/{versionId}/items", {
+                params: {
+                    // OpenAPI spec omits `id` in declared path params though `{id}` is in the URL template.
+                    path: { id: opts.dataset, versionId },
+                },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(makeDatasetVersionsCommand());
+    return cmd;
+}
+//# sourceMappingURL=datasets.js.map

package/dist/commands/docs.d.ts

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

package/dist/commands/docs.js

@@ -0,0 +1,166 @@
+import { Command } from "commander";
+import { runAction } from "../lib/client.js";
+import { resolveConfig, isJsonOutput } from "../lib/config.js";
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/**
+ * Fetch the OpenAPI spec from the backend.
+ */
+async function fetchSpec(baseUrl, apiKey) {
+    const specUrl = `${baseUrl.replace(/\/+$/, "")}/v3/api-docs`;
+    const res = await fetch(specUrl, {
+        headers: { Authorization: `Bearer ${apiKey}` },
+    });
+    if (!res.ok) {
+        if (res.status === 404 || res.status === 403) {
+            throw new Error("API documentation is not available. Enable it by setting SPRINGDOC_ENABLED=true on the backend.");
+        }
+        throw new Error(`Failed to fetch API docs: ${res.status} ${res.statusText}`);
+    }
+    return (await res.json());
+}
+/**
+ * Collect all $ref strings from an object tree.
+ */
+function collectRefs(obj, refs) {
+    if (obj === null || obj === undefined || typeof obj !== "object")
+        return;
+    if (Array.isArray(obj)) {
+        for (const item of obj)
+            collectRefs(item, refs);
+        return;
+    }
+    const record = obj;
+    if (typeof record["$ref"] === "string") {
+        refs.add(record["$ref"]);
+    }
+    for (const value of Object.values(record)) {
+        collectRefs(value, refs);
+    }
+}
+/**
+ * Recursively resolve schema refs — the initial set plus any schemas they reference.
+ */
+function resolveSchemas(refPaths, allSchemas) {
+    const resolved = {};
+    const queue = [...refPaths];
+    const visited = new Set();
+    while (queue.length > 0) {
+        const ref = queue.pop();
+        if (visited.has(ref))
+            continue;
+        visited.add(ref);
+        const prefix = "#/components/schemas/";
+        if (!ref.startsWith(prefix))
+            continue;
+        const name = ref.slice(prefix.length);
+        const schema = allSchemas[name];
+        if (!schema)
+            continue;
+        resolved[name] = schema;
+        const nested = new Set();
+        collectRefs(schema, nested);
+        for (const n of nested) {
+            if (!visited.has(n))
+                queue.push(n);
+        }
+    }
+    return resolved;
+}
+export function makeDocsCommand() {
+    const cmd = new Command("docs").description("Browse API documentation");
+    cmd
+        .command("sections")
+        .description("List available API documentation sections")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const config = resolveConfig(command);
+            const spec = await fetchSpec(config.baseUrl, config.apiKey);
+            const tags = spec.tags ?? [];
+            const paths = spec.paths ?? {};
+            // Count endpoints per tag
+            const tagCounts = new Map();
+            for (const methods of Object.values(paths)) {
+                for (const operation of Object.values(methods)) {
+                    if (operation?.tags) {
+                        for (const tag of operation.tags) {
+                            tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+                        }
+                    }
+                }
+            }
+            if (isJsonOutput(command)) {
+                const data = tags.map((t) => ({
+                    name: t.name,
+                    description: t.description ?? null,
+                    endpoints: tagCounts.get(t.name) ?? 0,
+                }));
+                console.log(JSON.stringify(data, null, 2));
+            }
+            else {
+                const info = spec.info ?? {};
+                console.log(`${info.title ?? "API"} v${info.version ?? "?"}\n`);
+                console.log("Available sections:");
+                for (const t of tags) {
+                    const count = tagCounts.get(t.name) ?? 0;
+                    const desc = t.description ? ` — ${t.description}` : "";
+                    console.log(`  ${t.name} (${count} endpoint${count !== 1 ? "s" : ""})${desc}`);
+                }
+            }
+        });
+    });
+    cmd
+        .command("get")
+        .description("Get API documentation for a section")
+        .argument("<section>", "Section/tag name (e.g. Projects, Extractions)")
+        .action(async (section, _opts, command) => {
+        await runAction(command, async () => {
+            const config = resolveConfig(command);
+            const spec = await fetchSpec(config.baseUrl, config.apiKey);
+            const allTags = spec.tags ?? [];
+            const tagNames = allTags.map((t) => t.name);
+            if (!tagNames.includes(section)) {
+                throw new Error(`Section "${section}" not found. Available: ${tagNames.join(", ")}`);
+            }
+            const allPaths = spec.paths ?? {};
+            const allSchemas = spec.components?.schemas ?? {};
+            // Filter paths to only operations matching the requested tag
+            const filteredPaths = {};
+            const refs = new Set();
+            for (const [path, methods] of Object.entries(allPaths)) {
+                const filteredMethods = {};
+                for (const [method, operation] of Object.entries(methods)) {
+                    const op = operation;
+                    if (op?.tags?.includes(section)) {
+                        filteredMethods[method] = operation;
+                        collectRefs(operation, refs);
+                    }
+                }
+                if (Object.keys(filteredMethods).length > 0) {
+                    filteredPaths[path] = filteredMethods;
+                }
+            }
+            // Resolve referenced schemas (including transitive refs)
+            const referencedSchemas = resolveSchemas(refs, allSchemas);
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify({ paths: filteredPaths, schemas: referencedSchemas }, null, 2));
+            }
+            else {
+                // Human-readable summary
+                console.log(`\n${section}\n${"=".repeat(section.length)}\n`);
+                for (const [path, methods] of Object.entries(filteredPaths)) {
+                    for (const [method, operation] of Object.entries(methods)) {
+                        const op = operation;
+                        const label = op.summary ?? op.operationId ?? "";
+                        console.log(`  ${method.toUpperCase().padEnd(7)} ${path}`);
+                        if (label)
+                            console.log(`          ${label}`);
+                    }
+                }
+                console.log(`\nReferenced schemas: ${Object.keys(referencedSchemas).join(", ") || "(none)"}`);
+                console.log("\nUse --json for full endpoint and schema details.");
+            }
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=docs.js.map

package/dist/commands/evaluators.d.ts

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

package/dist/commands/evaluators.js

@@ -0,0 +1,124 @@
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { getClient, runAction } from "../lib/client.js";
+import { formatDetail, formatList } from "../lib/output.js";
+export function makeEvaluatorsCommand() {
+    const cmd = new Command("evaluators").description("Built-in evaluator types and reusable org-scoped evaluator templates");
+    // ── built-in types ────────────────────────────────────────────
+    cmd
+        .command("types")
+        .description("List built-in evaluator types (exact_match, grounding, llm_judge)")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/evaluators");
+            formatList(data, command, [
+                "id",
+                "displayName",
+                "type",
+            ]);
+        });
+    });
+    // ── templates ─────────────────────────────────────────────────
+    cmd
+        .command("list")
+        .description("List evaluator templates")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/evaluator-templates");
+            formatList(data, command, [
+                "id",
+                "name",
+                "type",
+                "description",
+            ]);
+        });
+    });
+    cmd
+        .command("get <id>")
+        .description("Show one template by id")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/evaluator-templates/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("create")
+        .description("Create an evaluator template. LLM-judge templates require --config with rubricPrompt + model.")
+        .requiredOption("--name <name>", "Template name")
+        .requiredOption("--type <type>", "Evaluator type (CODE, LLM_JUDGE, or HUMAN)")
+        .option("--description <text>", "Description")
+        .option("--config <json-or-file>", "Config as inline JSON string or path to a .json file")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/evaluator-templates", {
+                body: {
+                    name: opts.name,
+                    type: opts.type,
+                    description: opts.description,
+                    config: opts.config ? readConfigArg(opts.config) : undefined,
+                },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("update <id>")
+        .description("Replace a template (name / description / config)")
+        .option("--name <name>")
+        .option("--type <type>", "Evaluator type")
+        .option("--description <text>")
+        .option("--config <json-or-file>", "Config JSON string or path to a .json file")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            // PUT is a full replace — fetch current, merge explicit fields.
+            const { data: current } = await client.GET("/v1/evaluator-templates/{id}", { params: { path: { id } } });
+            const { data } = await client.PUT("/v1/evaluator-templates/{id}", {
+                params: { path: { id } },
+                body: {
+                    name: opts.name ?? current?.name,
+                    type: opts.type ?? current?.type,
+                    description: opts.description ?? current?.description,
+                    config: opts.config !== undefined
+                        ? readConfigArg(opts.config)
+                        : current?.config,
+                },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("delete <id>")
+        .description("Delete a template. Experiments already using it keep their past scores.")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/evaluator-templates/{id}", {
+                params: { path: { id } },
+            });
+            console.log(`Deleted evaluator template ${id}`);
+        });
+    });
+    return cmd;
+}
+// Accepts either a path to a .json file or an inline JSON string. The
+// file-first check keeps the common "--config ./judge.json" case simple
+// while still allowing "--config '{"model":"…","rubricPrompt":"…"}'" when
+// that's easier (e.g. shell pipelines).
+function readConfigArg(arg) {
+    try {
+        const raw = readFileSync(arg, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return JSON.parse(arg);
+    }
+}
+//# sourceMappingURL=evaluators.js.map

package/dist/commands/experiments.d.ts

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