@2kw/ai 4.0.0-dev.2

package/dist/commands/tracing.js

@@ -0,0 +1,85 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { formatDetail, formatList } from "../lib/output.js";
+export function makeTracingCommand() {
+    const cmd = new Command("tracing").description("Traces and per-org tracing settings (prompt / completion capture)");
+    // ── settings ──────────────────────────────────────────────────
+    const settings = new Command("settings").description("Manage per-org tracing settings (includePrompts / includeCompletions)");
+    settings
+        .command("get")
+        .description("Show current tracing settings")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/tracing/settings");
+            formatDetail(data, command);
+        });
+    });
+    settings
+        .command("set")
+        .description("Update tracing settings. Both toggles control PII capture — default is false for both.")
+        .option("--include-prompts <bool>", "Retain prompt content on ingested spans (true/false)")
+        .option("--include-completions <bool>", "Retain completion content on ingested spans (true/false)")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            // Fetch current state so the user can flip a single toggle without
+            // resetting the other. Otherwise an unset flag defaults to false
+            // and silently disables capture the admin had already enabled.
+            const { data: current } = await client.GET("/v1/tracing/settings");
+            const body = {
+                includePrompts: opts.includePrompts !== undefined
+                    ? opts.includePrompts === "true"
+                    : (current?.includePrompts ?? false),
+                includeCompletions: opts.includeCompletions !== undefined
+                    ? opts.includeCompletions === "true"
+                    : (current?.includeCompletions ?? false),
+            };
+            const { data } = await client.PUT("/v1/tracing/settings", {
+                body,
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(settings);
+    // ── traces ────────────────────────────────────────────────────
+    const list = new Command("list").description("List recent traces");
+    list.option("--source-service <name>", "Filter by source_service");
+    list.option("--status <code>", "Filter by status (OK, ERROR, UNSET — comma-separated for multiple)");
+    list.option("--search <query>", "Free-text search across trace id, span name, service, operation");
+    list.option("--page <n>", "Page index (0-based)", "0");
+    list.option("--size <n>", "Page size", "20");
+    list.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/traces", {
+                params: {
+                    query: {
+                        sourceService: opts.sourceService,
+                        statusCode: opts.status,
+                        search: opts.search,
+                        page: parseInt(opts.page, 10),
+                        size: parseInt(opts.size, 10),
+                    },
+                },
+            });
+            const page = data;
+            formatList((page?.content ?? []), command, ["traceId", "rootSpanName", "statusCode", "durationMs", "spanCount", "sourceServices"]);
+        });
+    });
+    cmd.addCommand(list);
+    const get = new Command("get").description("Get all spans of a trace by id");
+    get.argument("<traceId>", "Trace id");
+    get.action(async (traceId, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/traces/{traceId}", {
+                params: { path: { traceId } },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(get);
+    return cmd;
+}
+//# sourceMappingURL=tracing.js.map

package/dist/commands/transcribe.d.ts

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

package/dist/commands/transcribe.js

@@ -0,0 +1,65 @@
+import { Command } from "commander";
+import { resolveConfig, isJsonOutput } from "../lib/config.js";
+import { handleError } from "../lib/errors.js";
+import { formatDetail, withSpinner } from "../lib/output.js";
+import { fileToBlob } from "../lib/multipart.js";
+import { BackboneApiError } from "../lib/errors.js";
+export function makeTranscribeCommand() {
+    const cmd = new Command("transcribe")
+        .description("Transcribe an audio file")
+        .argument("<file>", "Audio file path")
+        .requiredOption("-m, --model <model>", "Model (e.g., openai/whisper-1)")
+        .option("--language <code>", "Language code (e.g., en, de)")
+        .option("--prompt <text>", "Optional prompt to guide transcription")
+        .option("--format <fmt>", "Response format (json, text, srt, verbose_json, vtt)")
+        .option("--temperature <n>", "Temperature")
+        .action(async (file, opts, command) => {
+        const json = isJsonOutput(command);
+        try {
+            const config = resolveConfig(command);
+            const { blob, filename } = fileToBlob(file);
+            const formData = new FormData();
+            formData.append("file", blob, filename);
+            formData.append("model", opts.model);
+            if (opts.language)
+                formData.append("language", opts.language);
+            if (opts.prompt)
+                formData.append("prompt", opts.prompt);
+            if (opts.format)
+                formData.append("response_format", opts.format);
+            if (opts.temperature)
+                formData.append("temperature", opts.temperature);
+            const baseUrl = config.baseUrl.replace(/\/+$/, "");
+            const url = `${baseUrl}/v1/audio/transcriptions`;
+            const data = await withSpinner("Transcribing...", async () => {
+                const res = await fetch(url, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${config.apiKey}` },
+                    body: formData,
+                });
+                if (!res.ok) {
+                    let body;
+                    try {
+                        body = await res.json();
+                    }
+                    catch {
+                        body = {
+                            error: res.statusText,
+                            message: `HTTP ${res.status}: ${res.statusText}`,
+                            status: res.status,
+                            timestamp: new Date().toISOString(),
+                        };
+                    }
+                    throw new BackboneApiError(body);
+                }
+                return res.json();
+            });
+            formatDetail(data, command);
+        }
+        catch (err) {
+            handleError(err, json);
+        }
+    });
+    return cmd;
+}
+//# sourceMappingURL=transcribe.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { makeAuthCommand } from "./commands/auth.js";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+import { makeConfigCommand } from "./commands/config.js";
+import { makeSchemasCommand } from "./commands/schemas.js";
+import { makePromptsCommand } from "./commands/prompts.js";
+import { makeExtractionsCommand } from "./commands/extractions.js";
+import { makeConvertCommand } from "./commands/convert.js";
+import { makeAiCommand } from "./commands/ai.js";
+import { makeTranscribeCommand } from "./commands/transcribe.js";
+import { makeProvidersCommand } from "./commands/providers.js";
+import { makeAnalyticsCommand } from "./commands/analytics.js";
+import { makeBillingCommand } from "./commands/billing.js";
+import { makeDatasetsCommand } from "./commands/datasets.js";
+import { makeDocsCommand } from "./commands/docs.js";
+import { makeContextCommand } from "./commands/context.js";
+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 { checkForUpdates } from "./lib/update-notifier.js";
+const updater = checkForUpdates(pkg.version);
+const program = new Command();
+program
+    .name("2kw")
+    .description("CLI for the 2kw.ai platform (also installed as `backbone` and `bb`)")
+    .version(pkg.version)
+    .option("--api-key <key>", "API key (overrides config)")
+    .option("--base-url <url>", "Base URL (overrides config)")
+    .option("--json", "Output as JSON")
+    .option("--no-color", "Disable colored output");
+program.addCommand(makeAuthCommand());
+program.addCommand(makeConfigCommand());
+program.addCommand(makeContextCommand());
+program.addCommand(makeSchemasCommand());
+program.addCommand(makePromptsCommand());
+program.addCommand(makeExtractionsCommand());
+program.addCommand(makeConvertCommand());
+program.addCommand(makeAiCommand());
+program.addCommand(makeTranscribeCommand());
+program.addCommand(makeProvidersCommand());
+program.addCommand(makeAnalyticsCommand());
+program.addCommand(makeBillingCommand());
+program.addCommand(makeDatasetsCommand());
+program.addCommand(makeExperimentsCommand());
+program.addCommand(makeEvaluatorsCommand());
+program.addCommand(makeScoresCommand());
+program.addCommand(makeTracingCommand());
+program.addCommand(makeDocsCommand());
+program.parseAsync().then(() => updater.notify());
+//# sourceMappingURL=index.js.map

package/dist/lib/client.d.ts

@@ -0,0 +1,12 @@
+import type { paths } from "../generated/openapi.js";
+import type { Command } from "commander";
+/**
+ * Create a typed openapi-fetch client from the resolved config.
+ * Attaches Bearer auth and error middleware automatically.
+ */
+export declare function getClient(command: Command): import("openapi-fetch").Client<paths, `${string}/${string}`>;
+/**
+ * Convenience: run an async action with consistent error handling.
+ */
+export declare function runAction(command: Command, action: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -0,0 +1,52 @@
+import createClient from "openapi-fetch";
+import { resolveConfig, isJsonOutput } from "./config.js";
+import { BackboneApiError, handleError } from "./errors.js";
+/**
+ * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ */
+const errorMiddleware = {
+    async onResponse({ response }) {
+        if (response.ok)
+            return undefined;
+        let body;
+        try {
+            body = await response.clone().json();
+        }
+        catch {
+            body = {};
+        }
+        throw new BackboneApiError({
+            status: body.status ?? response.status,
+            error: body.title ?? body.error ?? response.statusText,
+            message: body.detail ?? body.message ?? `HTTP ${response.status}: ${response.statusText}`,
+            timestamp: body.timestamp ?? new Date().toISOString(),
+        });
+    },
+};
+/**
+ * Create a typed openapi-fetch client from the resolved config.
+ * Attaches Bearer auth and error middleware automatically.
+ */
+export function getClient(command) {
+    const config = resolveConfig(command);
+    const client = createClient({
+        baseUrl: config.baseUrl.replace(/\/+$/, ""),
+        headers: {
+            Authorization: `Bearer ${config.apiKey}`,
+        },
+    });
+    client.use(errorMiddleware);
+    return client;
+}
+/**
+ * Convenience: run an async action with consistent error handling.
+ */
+export async function runAction(command, action) {
+    try {
+        await action();
+    }
+    catch (err) {
+        handleError(err, isJsonOutput(command));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/config.d.ts

@@ -0,0 +1,44 @@
+import Conf from "conf";
+import type { Command } from "commander";
+export interface ContextEntry {
+    baseUrl: string;
+    apiKey: string;
+}
+export interface BackboneConfigStore {
+    activeContext: string;
+    contexts: Record<string, ContextEntry>;
+}
+export interface BackboneConfig {
+    apiKey: string;
+    baseUrl: string;
+}
+/**
+ * Fallback base URL when the user has no context, env var, or local config.
+ * Override at runtime by setting AI_2KW_DEFAULT_BASE_URL (or the legacy
+ * BACKBONE_DEFAULT_BASE_URL) — e.g. for builds targeting a different
+ * deployment.
+ */
+export declare const DEFAULT_BASE_URL: string;
+declare const store: Conf<BackboneConfigStore>;
+export { store };
+export declare function validateContextName(name: string): void;
+export declare function getActiveContextName(): string;
+export declare function getActiveContext(): ContextEntry | undefined;
+export declare function getAllContexts(): Record<string, ContextEntry>;
+export declare function getContextCount(): number;
+export declare function setContext(name: string, entry: ContextEntry): void;
+export declare function deleteContext(name: string): void;
+export declare function renameContext(oldName: string, newName: string): void;
+export declare function setActiveContext(name: string): void;
+/**
+ * Resolve configuration with priority:
+ *   1. CLI flags (--api-key, --base-url)
+ *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
+ *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
+ *   3. Local .2kw file (or legacy .backbone)
+ *   4. Active context from config store
+ */
+export declare function resolveConfig(command: Command): BackboneConfig;
+/** Check if --json flag is set on root command */
+export declare function isJsonOutput(command: Command): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/lib/config.js

@@ -0,0 +1,217 @@
+import Conf from "conf";
+import { readFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Fallback base URL when the user has no context, env var, or local config.
+ * Override at runtime by setting AI_2KW_DEFAULT_BASE_URL (or the legacy
+ * BACKBONE_DEFAULT_BASE_URL) — e.g. for builds targeting a different
+ * deployment.
+ */
+export const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
+    process.env.BACKBONE_DEFAULT_BASE_URL ??
+    "https://backbone.manfred-kunze.dev/api";
+// One-shot flag so we only print the deprecation warning once per process,
+// even if resolveConfig is called multiple times across commands.
+let legacyEnvWarned = false;
+function warnLegacyEnv(legacyName, canonicalName) {
+    if (legacyEnvWarned)
+        return;
+    legacyEnvWarned = true;
+    // Write to stderr so JSON output on stdout stays clean.
+    process.stderr.write(`[deprecation] ${legacyName} is read for backwards compatibility. ` +
+        `Switch to ${canonicalName} — the BACKBONE_* names will be removed ` +
+        `in a future release.\n`);
+}
+const store = new Conf({
+    projectName: "2kw",
+    projectSuffix: "",
+    defaults: {
+        activeContext: "default",
+        contexts: {},
+    },
+});
+// One-shot migration: copy any legacy ~/.config/backbone/ store into the new
+// ~/.config/2kw/ store on first run. Triggered only if the new store has no
+// contexts AND the legacy file exists. The legacy file is preserved so users
+// can roll back by deleting the new store.
+//
+// Also handles the very-old flat format ({ apiKey, baseUrl }) that predates
+// contexts — folds it into a "default" context.
+(function migrateFromLegacyStore() {
+    // Already configured in the new location? Nothing to do.
+    if (Object.keys(store.get("contexts") ?? {}).length > 0)
+        return;
+    // Conf instantiation never creates the file proactively (it writes on first
+    // mutation), so spinning up a second instance pointed at the legacy
+    // projectName is a safe way to compute the legacy path.
+    const legacy = new Conf({
+        projectName: "backbone",
+        projectSuffix: "",
+        defaults: { activeContext: "default", contexts: {} },
+    });
+    if (!existsSync(legacy.path))
+        return;
+    let contexts = {};
+    let activeContext = "default";
+    try {
+        const raw = JSON.parse(readFileSync(legacy.path, "utf-8"));
+        if (raw.contexts && Object.keys(raw.contexts).length > 0) {
+            contexts = raw.contexts;
+            activeContext = raw.activeContext ?? "default";
+        }
+        else if (typeof raw.apiKey === "string") {
+            // Pre-context flat format — promote into a single "default" context.
+            contexts = {
+                default: {
+                    apiKey: raw.apiKey,
+                    baseUrl: raw.baseUrl ?? DEFAULT_BASE_URL,
+                },
+            };
+        }
+    }
+    catch {
+        // Unparseable legacy file — leave both stores untouched and let the
+        // user re-run "2kw auth login".
+        return;
+    }
+    if (Object.keys(contexts).length === 0)
+        return;
+    store.store = { activeContext, contexts };
+    process.stderr.write(`[migration] Copied legacy backbone CLI config to ${store.path}. ` +
+        `The original at ${legacy.path} is preserved.\n`);
+})();
+export { store };
+const CONTEXT_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+export function validateContextName(name) {
+    if (!CONTEXT_NAME_RE.test(name)) {
+        throw new Error("Context name must contain only letters, numbers, hyphens, and underscores.");
+    }
+}
+export function getActiveContextName() {
+    return store.get("activeContext") ?? "default";
+}
+export function getActiveContext() {
+    const name = getActiveContextName();
+    const contexts = store.get("contexts") ?? {};
+    return contexts[name];
+}
+export function getAllContexts() {
+    return store.get("contexts") ?? {};
+}
+export function getContextCount() {
+    return Object.keys(getAllContexts()).length;
+}
+export function setContext(name, entry) {
+    validateContextName(name);
+    const contexts = getAllContexts();
+    contexts[name] = entry;
+    store.set("contexts", contexts);
+}
+export function deleteContext(name) {
+    const contexts = getAllContexts();
+    if (!contexts[name]) {
+        throw new Error(`Context "${name}" does not exist.`);
+    }
+    if (Object.keys(contexts).length === 1) {
+        throw new Error("Cannot delete the last remaining context.");
+    }
+    delete contexts[name];
+    store.set("contexts", contexts);
+    if (getActiveContextName() === name) {
+        const remaining = Object.keys(contexts)[0];
+        store.set("activeContext", remaining);
+    }
+}
+export function renameContext(oldName, newName) {
+    validateContextName(newName);
+    const contexts = getAllContexts();
+    if (!contexts[oldName]) {
+        throw new Error(`Context "${oldName}" does not exist.`);
+    }
+    if (contexts[newName]) {
+        throw new Error(`Context "${newName}" already exists.`);
+    }
+    contexts[newName] = contexts[oldName];
+    delete contexts[oldName];
+    store.set("contexts", contexts);
+    if (getActiveContextName() === oldName) {
+        store.set("activeContext", newName);
+    }
+}
+export function setActiveContext(name) {
+    const contexts = getAllContexts();
+    if (!contexts[name]) {
+        throw new Error(`Context "${name}" does not exist. Available contexts: ${Object.keys(contexts).join(", ")}`);
+    }
+    store.set("activeContext", name);
+}
+/**
+ * Read local config file from current directory.
+ * Prefers .2kw, falls back to legacy .backbone for existing setups.
+ */
+function readLocalFile() {
+    const candidates = [".2kw", ".backbone"];
+    for (const name of candidates) {
+        const p = resolve(process.cwd(), name);
+        if (!existsSync(p))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(p, "utf-8"));
+            return { apiKey: parsed.apiKey, baseUrl: parsed.baseUrl };
+        }
+        catch {
+            // Try the next candidate
+        }
+    }
+    return {};
+}
+function readEnv(canonical, legacy) {
+    const v = process.env[canonical];
+    if (v)
+        return v;
+    const legacyV = process.env[legacy];
+    if (legacyV) {
+        warnLegacyEnv(legacy, canonical);
+        return legacyV;
+    }
+    return undefined;
+}
+/**
+ * Resolve configuration with priority:
+ *   1. CLI flags (--api-key, --base-url)
+ *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
+ *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
+ *   3. Local .2kw file (or legacy .backbone)
+ *   4. Active context from config store
+ */
+export function resolveConfig(command) {
+    const root = getRootCommand(command);
+    const opts = root.opts();
+    const local = readLocalFile();
+    const activeCtx = getActiveContext();
+    const apiKey = opts.apiKey ??
+        readEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY") ??
+        local.apiKey ??
+        activeCtx?.apiKey;
+    const baseUrl = opts.baseUrl ??
+        readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL") ??
+        local.baseUrl ??
+        activeCtx?.baseUrl ??
+        DEFAULT_BASE_URL;
+    if (!apiKey) {
+        throw new Error('No API key configured. Run "2kw auth login" (or "backbone auth login") or set AI_2KW_API_KEY.');
+    }
+    return { apiKey, baseUrl };
+}
+/** Walk up Commander's parent chain to find root program */
+function getRootCommand(cmd) {
+    let root = cmd;
+    while (root.parent)
+        root = root.parent;
+    return root;
+}
+/** Check if --json flag is set on root command */
+export function isJsonOutput(command) {
+    return getRootCommand(command).opts().json === true;
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/datasets.d.ts

@@ -0,0 +1,6 @@
+import type createClient from "openapi-fetch";
+import type { paths } from "../generated/openapi.js";
+type BackboneClient = ReturnType<typeof createClient<paths>>;
+export declare function resolveLatestVersionId(client: BackboneClient, datasetId: string): Promise<string>;
+export {};
+//# sourceMappingURL=datasets.d.ts.map

package/dist/lib/datasets.js

@@ -0,0 +1,10 @@
+export async function resolveLatestVersionId(client, datasetId) {
+    const { data } = await client.GET("/v1/datasets/{id}/versions/latest", { params: { path: { id: datasetId } } });
+    const versionId = data?.id;
+    if (!versionId) {
+        throw new Error(`Could not resolve latest version for dataset ${datasetId}. ` +
+            `Create a version first with 'bb datasets versions create --dataset ${datasetId}'.`);
+    }
+    return versionId;
+}
+//# sourceMappingURL=datasets.js.map

package/dist/lib/errors.d.ts

@@ -0,0 +1,14 @@
+export interface ApiErrorBody {
+    status: number;
+    error: string;
+    message: string;
+    timestamp: string;
+}
+export declare class BackboneApiError extends Error {
+    readonly status: number;
+    readonly errorType: string;
+    readonly timestamp: string;
+    constructor(body: ApiErrorBody);
+}
+export declare function handleError(err: unknown, json: boolean): void;
+//# sourceMappingURL=errors.d.ts.map

package/dist/lib/errors.js

@@ -0,0 +1,54 @@
+import chalk from "chalk";
+export class BackboneApiError extends Error {
+    status;
+    errorType;
+    timestamp;
+    constructor(body) {
+        super(body.message);
+        this.name = "BackboneApiError";
+        this.status = body.status;
+        this.errorType = body.error;
+        this.timestamp = body.timestamp;
+    }
+}
+const HINTS = {
+    401: 'Invalid or missing API key. Run "backbone auth login" to configure credentials.',
+    402: "Billing limit reached. Check your plan limits or upgrade at the dashboard.",
+    403: "You don't have permission for this action. Check your organization role.",
+    404: "Resource not found. Verify the ID is correct.",
+    409: "Conflict — the resource may already exist or was modified concurrently.",
+    422: "Validation error. Check the input values.",
+    429: "Rate limit exceeded. Wait a moment and try again.",
+};
+export function handleError(err, json) {
+    if (err instanceof BackboneApiError) {
+        if (json) {
+            console.error(JSON.stringify({
+                error: err.errorType,
+                status: err.status,
+                message: err.message,
+                timestamp: err.timestamp,
+            }));
+        }
+        else {
+            console.error(chalk.red(`Error ${err.status}: ${err.message}`));
+            const hint = HINTS[err.status];
+            if (hint) {
+                console.error(chalk.yellow(`Hint: ${hint}`));
+            }
+        }
+    }
+    else if (err instanceof Error) {
+        if (json) {
+            console.error(JSON.stringify({ error: err.name, message: err.message }));
+        }
+        else {
+            console.error(chalk.red(`Error: ${err.message}`));
+        }
+    }
+    else {
+        console.error(chalk.red(`Unknown error: ${String(err)}`));
+    }
+    process.exitCode = 1;
+}
+//# sourceMappingURL=errors.js.map

package/dist/lib/multipart.d.ts

@@ -0,0 +1,10 @@
+export declare function getMimeType(filename: string): string;
+/**
+ * Read a local file and return a Blob suitable for FormData.
+ */
+export declare function fileToBlob(filePath: string): {
+    blob: Blob;
+    filename: string;
+    mimeType: string;
+};
+//# sourceMappingURL=multipart.d.ts.map