@2kw/ai 6.0.0-dev.4 → 6.1.0-dev.10

package/dist/commands/queues.js

@@ -0,0 +1,244 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { formatList, formatDetail, formatSuccess } from "../lib/output.js";
+/**
+ * Annotation queues let a human reviewer work through a curated list of
+ * subjects (run results, traces, spans, dataset items). This command group
+ * covers the queue itself plus the items inside it: creating a queue,
+ * bulk-adding subjects, claiming the next eligible item, and recording the
+ * outcome — the full loop an agent or a human reviewer needs to run review
+ * end to end from the CLI.
+ */
+export function makeQueuesCommand() {
+    const cmd = new Command("queues").description("Manage annotation queues for human review");
+    // ── list ──────────────────────────────────────────────────────
+    cmd
+        .command("list")
+        .description("List annotation queues")
+        .option("--archived", "List archived queues instead of active ones", false)
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues", {
+                params: { query: { archived: opts.archived } },
+            });
+            formatList(data, command, [
+                "id",
+                "name",
+                "description",
+                "archivedAt",
+                "createdAt",
+            ]);
+        });
+    });
+    // ── get ───────────────────────────────────────────────────────
+    cmd
+        .command("get")
+        .description("Get an annotation queue by ID")
+        .argument("<id>", "Queue ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues/{id}", {
+                params: { path: { id } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── create ────────────────────────────────────────────────────
+    cmd
+        .command("create")
+        .description("Create a new annotation queue")
+        .requiredOption("-n, --name <name>", "Queue name")
+        .option("-d, --description <text>", "Queue description")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.POST("/v1/annotation-queues", {
+                body: { name: opts.name, description: opts.description },
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── update ────────────────────────────────────────────────────
+    cmd
+        .command("update")
+        .description("Update a queue's name or description")
+        .argument("<id>", "Queue ID")
+        .option("-n, --name <name>", "New name")
+        .option("-d, --description <text>", "New description")
+        .action(async (id, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = {};
+            if (opts.name !== undefined)
+                body.name = opts.name;
+            if (opts.description !== undefined)
+                body.description = opts.description;
+            const { data } = await client.PATCH("/v1/annotation-queues/{id}", {
+                params: { path: { id } },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    // ── archive ───────────────────────────────────────────────────
+    cmd
+        .command("archive")
+        .description("Archive a queue (idempotent)")
+        .argument("<id>", "Queue ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.POST("/v1/annotation-queues/{id}/archive", {
+                params: { path: { id } },
+            });
+            formatSuccess(`Queue ${id} archived.`, command);
+        });
+    });
+    // ── by-subject ────────────────────────────────────────────────
+    cmd
+        .command("by-subject")
+        .description("Find queue items referencing a subject, across every queue")
+        .requiredOption("--subject-type <type>", "RUN_RESULT | TRACE | SPAN | DATASET_ITEM")
+        .requiredOption("--subject-id <id>", "Subject ID")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues/by-subject", {
+                params: {
+                    query: { subjectType: opts.subjectType, subjectId: opts.subjectId },
+                },
+            });
+            formatList(data, command, [
+                "id",
+                "queueId",
+                "subjectType",
+                "subjectId",
+                "status",
+                "assignedTo",
+            ]);
+        });
+    });
+    // ── next ──────────────────────────────────────────────────────
+    cmd
+        .command("next")
+        .description("Claim the next eligible item in a queue for the caller")
+        .argument("<id>", "Queue ID")
+        .action(async (id, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues/{id}/items/next", {
+                params: { path: { id } },
+            });
+            if (!data) {
+                // 204 No Content: the queue has nothing left for this caller. A
+                // normal end state, not an error — printed plainly either way.
+                if (isJsonOutput(command)) {
+                    console.log(JSON.stringify(null));
+                }
+                else {
+                    console.log(chalk.dim("No items available to claim — the queue is empty for you."));
+                }
+                return;
+            }
+            formatDetail(data, command);
+        });
+    });
+    // ── items ─────────────────────────────────────────────────────
+    const items = new Command("items").description("Manage items within an annotation queue");
+    items
+        .command("list")
+        .description("List items in a queue")
+        .requiredOption("--queue <id>", "Queue ID")
+        .option("--status <status>", "PENDING | IN_PROGRESS | DONE | SKIPPED")
+        .option("--assigned-to <userId>", "Filter by assignee")
+        .option("-p, --page <number>", "Page number (0-indexed)", "0")
+        .option("--size <number>", "Page size", "50")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues/{id}/items", {
+                params: {
+                    path: { id: opts.queue },
+                    query: {
+                        status: opts.status,
+                        assignedTo: opts.assignedTo,
+                        page: opts.page !== undefined ? parseInt(opts.page, 10) : undefined,
+                        size: opts.size !== undefined ? parseInt(opts.size, 10) : undefined,
+                    },
+                },
+            });
+            formatList(data, command, [
+                "id",
+                "subjectType",
+                "subjectId",
+                "status",
+                "assignedTo",
+                "createdAt",
+            ]);
+        });
+    });
+    items
+        .command("add")
+        .description("Bulk-add subjects to a queue (duplicates skipped)")
+        .requiredOption("--queue <id>", "Queue ID")
+        .requiredOption("--items <json>", 'JSON array of {"subjectType","subjectId"} objects')
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const parsedItems = JSON.parse(opts.items);
+            const { data } = await client.POST("/v1/annotation-queues/{id}/items", {
+                params: { path: { id: opts.queue } },
+                body: { items: parsedItems },
+            });
+            formatList(data, command, [
+                "id",
+                "subjectType",
+                "subjectId",
+                "status",
+            ]);
+        });
+    });
+    items
+        .command("get")
+        .description("Get a single queue item")
+        .argument("<itemId>", "Item ID")
+        .requiredOption("--queue <id>", "Queue ID")
+        .action(async (itemId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/annotation-queues/{id}/items/{itemId}", {
+                params: { path: { id: opts.queue, itemId } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    items
+        .command("update")
+        .description("Update a queue item's status or assignee — the outcome of a review")
+        .argument("<itemId>", "Item ID")
+        .requiredOption("--queue <id>", "Queue ID")
+        .option("--status <status>", "PENDING | IN_PROGRESS | DONE | SKIPPED")
+        .option("--assigned-to <userId>", "New assignee")
+        .action(async (itemId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const body = {};
+            if (opts.status !== undefined)
+                body.status = opts.status;
+            if (opts.assignedTo !== undefined)
+                body.assignedTo = opts.assignedTo;
+            const { data } = await client.PATCH("/v1/annotation-queues/{id}/items/{itemId}", {
+                params: { path: { id: opts.queue, itemId } },
+                body: body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(items);
+    return cmd;
+}
+//# sourceMappingURL=queues.js.map

package/dist/commands/schema-versions.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
-import { formatPage, formatDetail } from "../lib/output.js";
+import { formatPage, formatDetail, formatSuccess } from "../lib/output.js";
 import { addPaginationOptions, paginationParams } from "../lib/pagination.js";
 export function makeSchemaVersionsCommand() {
     const cmd = new Command("versions").description("Manage schema versions");
@@ -32,6 +32,29 @@ export function makeSchemaVersionsCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("latest")
+        .description("Get the latest active version of a schema")
+        .requiredOption("--schema <id>", "Schema ID")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/schemas/{schemaId}/versions/latest", { params: { path: { schemaId: opts.schema } } });
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("delete")
+        .description("Delete (deactivate) a schema version")
+        .argument("<versionId>", "Version ID")
+        .requiredOption("--schema <id>", "Schema ID")
+        .action(async (versionId, opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            await client.DELETE("/v1/schemas/{schemaId}/versions/{versionId}", { params: { path: { schemaId: opts.schema, versionId } } });
+            formatSuccess(`Schema version ${versionId} deleted.`, command);
+        });
+    });
     cmd
         .command("create")
         .description("Create a new schema version")

package/dist/commands/scores.js

@@ -1,14 +1,18 @@
 import { Command } from "commander";
 import { getClient, runAction } from "../lib/client.js";
-import { formatDetail } from "../lib/output.js";
+import { formatDetail, formatList } from "../lib/output.js";
 export function makeScoresCommand() {
-    const cmd = new Command("scores").description("Record evaluation scores on experiment run results");
+    const cmd = new Command("scores").description("Record and review evaluation scores on experiment run results and other subjects");
     cmd
         .command("human")
-        .description("Record a human score for a run result. Upserts by (runResultId, evaluatorId, annotatorId).")
-        .requiredOption("--run-result <id>", "Run result ID")
+        .description("Record a human score. Upserts by (subject, evaluatorId, annotatorId) — pass either " +
+        "--run-result, or --subject-type/--subject-id for a trace, span, or dataset item.")
+        .option("--run-result <id>", "Run result ID (legacy shape)")
+        .option("--subject-type <type>", "RUN_RESULT | TRACE | SPAN | DATASET_ITEM")
+        .option("--subject-id <id>", "Subject ID")
+        .option("--queue-item <id>", "Annotation queue item ID this score resolves")
         .requiredOption("--evaluator <id>", "Evaluator identifier (e.g. 'helpfulness' or a template id)")
-        .requiredOption("--score <number>", "Score between 0.0 and 1.0", parseFloat)
+        .option("--score <number>", "Score between 0.0 and 1.0", parseFloat)
         .option("--label <text>", "Short label (e.g. 'pass', 'fail', 'good')")
         .option("--comment <text>", "Optional reviewer note")
         .action(async (opts, command) => {
@@ -17,6 +21,9 @@ export function makeScoresCommand() {
             const { data } = await client.POST("/v1/evaluation-scores/human", {
                 body: {
                     runResultId: opts.runResult,
+                    subjectType: opts.subjectType,
+                    subjectId: opts.subjectId,
+                    annotationQueueItemId: opts.queueItem,
                     evaluatorId: opts.evaluator,
                     score: opts.score,
                     label: opts.label,
@@ -26,6 +33,37 @@ export function makeScoresCommand() {
             formatDetail(data, command);
         });
     });
+    cmd
+        .command("list")
+        .description("List human scores filed against a subject. Defaults to the caller's own scores — " +
+        "pass --annotator to see another reviewer's.")
+        .requiredOption("--subject-type <type>", "RUN_RESULT | TRACE | SPAN | DATASET_ITEM")
+        .requiredOption("--subject-id <id>", "Subject ID")
+        .option("--annotator <id>", "Annotator ID (defaults to the caller)")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/evaluation-scores/human", {
+                params: {
+                    query: {
+                        subjectType: opts.subjectType,
+                        subjectId: opts.subjectId,
+                        annotatorId: opts.annotator,
+                    },
+                },
+            });
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            formatList(data, command, [
+                "id",
+                "evaluatorId",
+                "score",
+                "label",
+                "annotatorId",
+                "comment",
+                "createdAt",
+            ]);
+        });
+    });
     return cmd;
 }
 //# sourceMappingURL=scores.js.map

package/dist/commands/tracing.js

@@ -80,6 +80,46 @@ export function makeTracingCommand() {
         });
     });
     cmd.addCommand(get);
+    // ── sessions ──────────────────────────────────────────────────
+    const sessions = new Command("sessions").description("Session-level trace views (spans grouped by exporter-stamped session id)");
+    const sessionsList = new Command("list").description("List trace sessions");
+    sessionsList.option("--search <query>", "Free-text search across session id and name");
+    sessionsList.option("--from <iso>", "Start of time range (ISO-8601)");
+    sessionsList.option("--to <iso>", "End of time range (ISO-8601)");
+    sessionsList.option("--page <n>", "Page index (0-based)", "0");
+    sessionsList.option("--size <n>", "Page size", "20");
+    sessionsList.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/traces/sessions", {
+                params: {
+                    query: {
+                        search: opts.search,
+                        from: opts.from,
+                        to: opts.to,
+                        page: parseInt(opts.page, 10),
+                        size: parseInt(opts.size, 10),
+                    },
+                },
+            });
+            const page = data;
+            formatList((page?.content ?? []), command, ["sessionId", "name", "startTime", "durationMs", "turnCount", "errorCount", "costUsd"]);
+        });
+    });
+    sessions.addCommand(sessionsList);
+    const sessionsGet = new Command("get").description("Get all spans of a session by id, sorted chronologically");
+    sessionsGet.argument("<sessionId>", "Session id");
+    sessionsGet.action(async (sessionId, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/traces/sessions/{sessionId}", {
+                params: { path: { sessionId } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    sessions.addCommand(sessionsGet);
+    cmd.addCommand(sessions);
     return cmd;
 }
 //# sourceMappingURL=tracing.js.map

package/dist/index.js

@@ -21,6 +21,12 @@ import { makeExperimentsCommand } from "./commands/experiments.js";
 import { makeTracingCommand } from "./commands/tracing.js";
 import { makeEvaluatorsCommand } from "./commands/evaluators.js";
 import { makeScoresCommand } from "./commands/scores.js";
+import { makeQueuesCommand } from "./commands/queues.js";
+import { makeAgentsCommand } from "./commands/agents.js";
+import { makeConversationsCommand } from "./commands/conversations.js";
+import { makeKnowledgeCommand } from "./commands/knowledge.js";
+import { makeFilesCommand } from "./commands/files.js";
+import { makeInstallationsCommand } from "./commands/installations.js";
 import { checkForUpdates } from "./lib/update-notifier.js";
 const updater = checkForUpdates(pkg.version);
 const program = new Command();
@@ -48,7 +54,13 @@ program.addCommand(makeDatasetsCommand());
 program.addCommand(makeExperimentsCommand());
 program.addCommand(makeEvaluatorsCommand());
 program.addCommand(makeScoresCommand());
+program.addCommand(makeQueuesCommand());
 program.addCommand(makeTracingCommand());
+program.addCommand(makeAgentsCommand());
+program.addCommand(makeConversationsCommand());
+program.addCommand(makeKnowledgeCommand());
+program.addCommand(makeFilesCommand());
+program.addCommand(makeInstallationsCommand());
 program.addCommand(makeDocsCommand());
 program.parseAsync().then(() => updater.notify());
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.0.0-dev.4",
+  "version": "6.1.0-dev.10",
   "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
   "keywords": [
     "cli",
@@ -37,6 +37,7 @@
     "check:spec": "tsx --env-file=.env openapi/scripts/check-drift.ts",
     "check:generated": "tsx openapi/scripts/check-generated.ts",
     "fix:generated": "tsx openapi/scripts/check-generated.ts --write",
+    "check:coverage": "tsx openapi/scripts/check-coverage.ts",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
     "test:run": "vitest run",