@2kw/ai 4.0.0-dev.2

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2025-present Manfred Kunze Dev
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. No part of the Software may be reproduced, distributed, or
+transmitted in any form or by any means, including photocopying, recording, or
+other electronic or mechanical methods, without the prior written permission of
+the copyright holder.
+
+The Software is provided "as is", without warranty of any kind, express or implied,
+including but not limited to the warranties of merchantability, fitness for a
+particular purpose, and noninfringement. In no event shall the authors or copyright
+holders be liable for any claim, damages, or other liability, whether in an action
+of contract, tort, or otherwise, arising from, out of, or in connection with the
+Software or the use or other dealings in the Software.
+
+Usage of this Software is permitted only in accordance with the terms and conditions
+set forth by Manfred Kunze Dev.

package/README.md

@@ -0,0 +1,91 @@
+# Backbone CLI
+
+A command-line interface for the [Backbone AI](https://backbone.manfred-kunze.dev) platform. Manage schemas, prompts, extractions, documents, and more — straight from your terminal.
+
+## Installation
+
+```bash
+# Latest stable release
+npm install -g @manfred-kunze-dev/backbone-cli
+
+# Pre-release (dev channel)
+npm install -g @manfred-kunze-dev/backbone-cli@dev
+```
+
+The CLI will notify you when a newer version is available.
+
+## Quick Start
+
+```bash
+# Authenticate
+backbone auth login
+
+# Define a schema and run an extraction
+backbone schemas create -n "Invoice"
+backbone extractions create --schema <id> -m gpt-4o --text "Invoice #123, Total: $500"
+```
+
+The CLI is also available as `bb` for quick access — e.g. `bb schemas list`.
+
+## Authentication
+
+The CLI supports multiple authentication methods (highest priority first):
+
+| Method | Example |
+|--------|---------|
+| CLI flags | `--api-key sk_... --base-url https://...` |
+| Environment variables | `BACKBONE_API_KEY`, `BACKBONE_BASE_URL` |
+| Local `.backbone` file | JSON file in the current directory |
+| Config store | `~/.config/backbone/config.json` (set via `backbone auth login`) |
+
+```bash
+backbone auth login     # Interactive setup
+backbone auth status    # Verify credentials
+backbone auth logout    # Clear stored credentials
+```
+
+## Contexts
+
+The CLI supports kubectl-style contexts for switching between organizations and environments:
+
+```bash
+# Contexts are created automatically via `backbone auth login`
+backbone context list              # List all contexts
+backbone context use acme-corp     # Switch active context
+backbone context create staging    # Create a new context
+backbone context rename old new    # Rename a context
+backbone context delete old        # Remove a context
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `auth` | Login, logout, and check auth status |
+| `config` | Get, set, and list configuration values |
+| `context` | Manage CLI contexts for multiple environments |
+| `schemas` | Manage schemas, versions, labels, validation, and testing |
+| `prompts` | Manage prompts, versions, labels, compilation, and testing |
+| `extractions` | Create extractions (text, file, images), list, re-run, estimate tokens |
+| `convert` | Convert documents (PDF, DOCX, images) to Markdown/text/HTML/JSON |
+| `ai` | Chat completions and model listing via the LLM Gateway |
+| `transcribe` | Transcribe audio files (mp3, wav, flac, ogg, etc.) |
+| `providers` | Manage BYOK AI providers |
+| `analytics` | View organization usage analytics |
+| `billing` | Check subscription tier and usage limits |
+| `docs` | Browse API documentation from the terminal |
+
+### Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--api-key <key>` | Override the API key |
+| `--base-url <url>` | Override the base URL (default: `https://backbone.manfred-kunze.dev/api`) |
+| `--json` | Output raw JSON instead of formatted tables |
+| `--no-color` | Disable colored output |
+
+For full command documentation, see the [Backbone docs](https://backbone.manfred-kunze.dev).
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE) for details.

package/dist/commands/ai.d.ts

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

package/dist/commands/ai.js

@@ -0,0 +1,72 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { formatList, withSpinner } from "../lib/output.js";
+import chalk from "chalk";
+export function makeAiCommand() {
+    const cmd = new Command("ai").description("AI gateway operations");
+    cmd
+        .command("chat")
+        .description("Send a chat completion request")
+        .requiredOption("-m, --model <model>", "Model (provider/model format)")
+        .requiredOption("--message <text>", "User message")
+        .option("--system <text>", "System message")
+        .option("--temperature <n>", "Temperature (0-2)")
+        .option("--max-tokens <n>", "Max tokens")
+        .option("--top-p <n>", "Top-p sampling")
+        .action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const messages = [];
+            if (opts.system) {
+                messages.push({ role: "system", content: opts.system });
+            }
+            messages.push({ role: "user", content: opts.message });
+            const body = {
+                model: opts.model,
+                messages,
+                stream: false,
+                temperature: opts.temperature ? parseFloat(opts.temperature) : undefined,
+                max_tokens: opts.maxTokens ? parseInt(opts.maxTokens, 10) : undefined,
+                top_p: opts.topP ? parseFloat(opts.topP) : undefined,
+            };
+            const { data } = await withSpinner("Thinking...", () => client.POST("/v1/chat/completions", { body }));
+            // Response type is untyped in OpenAPI spec (OpenAI-compatible format)
+            const result = data;
+            const json = isJsonOutput(command);
+            if (json) {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                const choices = result?.choices;
+                const content = choices?.[0]?.message?.content;
+                if (content) {
+                    console.log(content);
+                }
+                const usage = result?.usage;
+                if (usage) {
+                    console.log(chalk.dim(`\n[${result?.model} | ${usage.prompt_tokens} in / ${usage.completion_tokens} out / ${usage.total_tokens} total tokens]`));
+                }
+            }
+        });
+    });
+    cmd
+        .command("models")
+        .description("List available AI models")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/models");
+            const json = isJsonOutput(command);
+            if (json) {
+                console.log(JSON.stringify(data, null, 2));
+            }
+            else {
+                const models = data?.data ?? [];
+                formatList(models, command, ["id", "owned_by"]);
+            }
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=ai.js.map

package/dist/commands/analytics.d.ts

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

package/dist/commands/analytics.js

@@ -0,0 +1,161 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { formatDetail, formatList } from "../lib/output.js";
+function addDateOptions(cmd) {
+    return cmd
+        .option("--start <date>", "Start date (YYYY-MM-DD)")
+        .option("--end <date>", "End date (YYYY-MM-DD)");
+}
+export function makeAnalyticsCommand() {
+    const cmd = new Command("analytics").description("Organization analytics");
+    const summary = new Command("summary").description("Cross-surface summary (total ops, spend, p95, per-surface breakdown)");
+    addDateOptions(summary);
+    summary.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/summary", {
+                params: {
+                    query: { startDate: opts.start, endDate: opts.end },
+                },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(summary);
+    const timeSeries = new Command("time-series").description("Daily / weekly / monthly operations grouped by surface");
+    addDateOptions(timeSeries);
+    timeSeries.option("--group-by <interval>", "Group by: day, week, month", "day");
+    timeSeries.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/time-series", {
+                params: {
+                    query: {
+                        startDate: opts.start,
+                        endDate: opts.end,
+                        groupBy: opts.groupBy,
+                    },
+                },
+            });
+            // Rows carry `date` + `bySurface` (map keyed by Surface). Nothing
+            // sensible to tabulate across rows of different surface sets, so
+            // fall through to the JSON view via formatDetail per row.
+            formatList(data, command, ["date", "bySurface"]);
+        });
+    });
+    cmd.addCommand(timeSeries);
+    const schemas = new Command("schemas").description("Top schemas by extraction count (extraction surface only)");
+    addDateOptions(schemas);
+    schemas.option("--limit <n>", "Max results", "10");
+    schemas.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/schemas", {
+                params: {
+                    query: {
+                        startDate: opts.start,
+                        endDate: opts.end,
+                        limit: parseInt(opts.limit, 10),
+                    },
+                },
+            });
+            formatList(data, command, [
+                "schemaVersionId",
+                "schemaName",
+                "totalExtractions",
+                "successfulExtractions",
+                "successRate",
+                "totalTokens",
+                "totalCost",
+                "avgDurationMs",
+            ]);
+        });
+    });
+    cmd.addCommand(schemas);
+    const providers = new Command("providers").description("Provider usage breakdown (extraction surface only)");
+    addDateOptions(providers);
+    providers.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/providers", {
+                params: {
+                    query: { startDate: opts.start, endDate: opts.end },
+                },
+            });
+            formatList(data, command, [
+                "providerId",
+                "providerName",
+                "totalExtractions",
+                "successfulExtractions",
+                "successRate",
+                "totalTokens",
+                "totalCost",
+                "avgDurationMs",
+            ]);
+        });
+    });
+    cmd.addCommand(providers);
+    const errors = new Command("errors").description("Top failures grouped by surface + error message");
+    addDateOptions(errors);
+    errors.option("--limit <n>", "Max results", "10");
+    errors.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/errors", {
+                params: {
+                    query: {
+                        startDate: opts.start,
+                        endDate: opts.end,
+                        limit: parseInt(opts.limit, 10),
+                    },
+                },
+            });
+            formatList(data, command, [
+                "surface",
+                "errorMessage",
+                "count",
+                "lastOccurrence",
+            ]);
+        });
+    });
+    cmd.addCommand(errors);
+    const quality = new Command("quality").description("Total experiment runs in range + average evaluator score");
+    addDateOptions(quality);
+    quality.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/quality", {
+                params: {
+                    query: { startDate: opts.start, endDate: opts.end },
+                },
+            });
+            formatDetail(data, command);
+        });
+    });
+    cmd.addCommand(quality);
+    const qualityTrend = new Command("quality-trend").description("Average evaluator score over time");
+    addDateOptions(qualityTrend);
+    qualityTrend.option("--group-by <interval>", "Group by: day, week, month", "day");
+    qualityTrend.action(async (opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/analytics/quality/trend", {
+                params: {
+                    query: {
+                        startDate: opts.start,
+                        endDate: opts.end,
+                        groupBy: opts.groupBy,
+                    },
+                },
+            });
+            formatList(data, command, [
+                "date",
+                "runs",
+                "avgScore",
+            ]);
+        });
+    });
+    cmd.addCommand(qualityTrend);
+    return cmd;
+}
+//# sourceMappingURL=analytics.js.map

package/dist/commands/auth.d.ts

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

package/dist/commands/auth.js

@@ -0,0 +1,134 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { store, resolveConfig, isJsonOutput, getActiveContextName, getActiveContext, getContextCount, setContext, setActiveContext, deleteContext, DEFAULT_BASE_URL, } from "../lib/config.js";
+import { getClient, runAction } from "../lib/client.js";
+import { createInterface } from "node:readline/promises";
+export function makeAuthCommand() {
+    const cmd = new Command("auth").description("Manage authentication");
+    cmd
+        .command("login")
+        .description("Configure API credentials")
+        .option("--api-key <key>", "API key")
+        .option("--base-url <url>", "Base URL")
+        .action(async (opts) => {
+        let apiKey = opts.apiKey;
+        let baseUrl = opts.baseUrl;
+        const contextName = getActiveContextName();
+        const currentCtx = getActiveContext();
+        if (!apiKey || !baseUrl) {
+            const rl = createInterface({
+                input: process.stdin,
+                output: process.stdout,
+            });
+            try {
+                if (!baseUrl) {
+                    const defaultUrl = currentCtx?.baseUrl ?? DEFAULT_BASE_URL;
+                    baseUrl = await rl.question(`Base URL [${defaultUrl}]: `);
+                    if (!baseUrl)
+                        baseUrl = defaultUrl;
+                }
+                if (!apiKey) {
+                    apiKey = await rl.question("API Key (sk_...): ");
+                }
+            }
+            finally {
+                rl.close();
+            }
+        }
+        if (!apiKey) {
+            console.error(chalk.red("API key is required."));
+            process.exit(1);
+        }
+        setContext(contextName, { apiKey, baseUrl });
+        setActiveContext(contextName);
+        console.log(chalk.green("Credentials saved successfully."));
+        console.log(chalk.dim(`Config stored at: ${store.path}`));
+    });
+    cmd
+        .command("logout")
+        .description("Clear stored credentials")
+        .action(() => {
+        const contextName = getActiveContextName();
+        const count = getContextCount();
+        if (count <= 1) {
+            // Last context — clear it by resetting the store
+            store.store = { activeContext: "default", contexts: {} };
+        }
+        else {
+            deleteContext(contextName);
+            console.log(chalk.dim(`Removed context "${contextName}". Switched to "${getActiveContextName()}".`));
+        }
+        console.log(chalk.green("Credentials cleared."));
+    });
+    cmd
+        .command("status")
+        .description("Show current authentication status")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const json = isJsonOutput(command);
+            let config;
+            try {
+                config = resolveConfig(command);
+            }
+            catch {
+                if (json) {
+                    console.log(JSON.stringify({ authenticated: false }));
+                }
+                else {
+                    console.log(chalk.yellow("Not authenticated."));
+                    console.log(chalk.dim('Run "2kw auth login" to configure.'));
+                }
+                return;
+            }
+            const { apiKey, baseUrl } = config;
+            const keyPreview = apiKey.slice(0, 7) + "..." + apiKey.slice(-4);
+            const multiContext = getContextCount() > 1;
+            const contextName = getActiveContextName();
+            // Try to validate by listing models (lightweight call)
+            try {
+                const client = getClient(command);
+                const { data } = await client.GET("/v1/models");
+                const modelCount = data?.data?.length ?? 0;
+                if (json) {
+                    console.log(JSON.stringify({
+                        authenticated: true,
+                        ...(multiContext ? { context: contextName } : {}),
+                        baseUrl,
+                        apiKeyPreview: keyPreview,
+                        modelCount,
+                    }));
+                }
+                else {
+                    console.log(chalk.green("Authenticated"));
+                    if (multiContext) {
+                        console.log(`  Context: ${contextName}`);
+                    }
+                    console.log(`  Base URL:  ${baseUrl}`);
+                    console.log(`  API Key:   ${keyPreview}`);
+                    console.log(`  Models:    ${modelCount} available`);
+                }
+            }
+            catch {
+                if (json) {
+                    console.log(JSON.stringify({
+                        authenticated: false,
+                        ...(multiContext ? { context: contextName } : {}),
+                        baseUrl,
+                        apiKeyPreview: keyPreview,
+                        error: "Failed to validate credentials",
+                    }));
+                }
+                else {
+                    console.log(chalk.yellow("Credentials configured but validation failed."));
+                    if (multiContext) {
+                        console.log(`  Context: ${contextName}`);
+                    }
+                    console.log(`  Base URL:  ${baseUrl}`);
+                    console.log(`  API Key:   ${keyPreview}`);
+                }
+            }
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=auth.js.map

package/dist/commands/billing.d.ts

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

package/dist/commands/billing.js

@@ -0,0 +1,102 @@
+import { Command } from "commander";
+import { getClient, runAction } from "../lib/client.js";
+import { isJsonOutput } from "../lib/config.js";
+import { formatDetail, formatList } from "../lib/output.js";
+import chalk from "chalk";
+export function makeBillingCommand() {
+    const cmd = new Command("billing").description("Billing and subscription management");
+    cmd
+        .command("tiers")
+        .description("List available subscription tiers")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/billing/tiers");
+            formatList(data, command, ["name", "displayName", "maxProjects", "maxSchemas", "monthlyExtractionCredits", "monthlyGatewayTokens"]);
+        });
+    });
+    cmd
+        .command("tier")
+        .description("Show current organization tier")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/billing/tier");
+            formatDetail(data, command);
+        });
+    });
+    cmd
+        .command("limits")
+        .description("Show current usage and limits")
+        .action(async (_opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            const { data } = await client.GET("/v1/billing/limits");
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify(data, null, 2));
+            }
+            else {
+                console.log(chalk.cyan(`Tier: ${data?.tier ?? "unknown"}`));
+                console.log();
+                if (data?.resources?.length) {
+                    console.log(chalk.bold("Resources:"));
+                    for (const r of data.resources) {
+                        const label = r.displayName ?? r.resourceType;
+                        const bar = r.limit === -1
+                            ? chalk.green("unlimited")
+                            : `${r.used ?? 0} / ${r.limit ?? 0} (${r.remaining ?? 0} remaining)`;
+                        console.log(`  ${chalk.bold(String(label))}: ${bar}`);
+                    }
+                    console.log();
+                }
+                console.log(chalk.bold("Usage:"));
+                console.log(`  Schemas:      ${data?.currentSchemas ?? 0} / ${data?.maxSchemas ?? 0}`);
+                console.log(`  Prompts:      ${data?.currentPrompts ?? 0} / ${data?.maxPrompts ?? 0}`);
+                console.log(`  Team members: ${data?.currentTeamMembers ?? 0} / ${data?.maxTeamMembers ?? 0}`);
+                console.log();
+                console.log(chalk.bold("Features:"));
+                console.log(`  BYOK:             ${data?.byokEnabled ? chalk.green("yes") : chalk.dim("no")}`);
+                console.log(`  Priority support: ${data?.prioritySupport ? chalk.green("yes") : chalk.dim("no")}`);
+                if (data?.periodStart || data?.periodEnd) {
+                    console.log();
+                    console.log(chalk.dim(`Period: ${data.periodStart?.slice(0, 10) ?? "?"} \u2192 ${data.periodEnd?.slice(0, 10) ?? "?"}`));
+                }
+            }
+        });
+    });
+    cmd
+        .command("check")
+        .description("Check if a resource can be created")
+        .argument("<resource>", "Resource type: schema, prompt, team-member")
+        .action(async (resource, _opts, command) => {
+        await runAction(command, async () => {
+            const client = getClient(command);
+            let response;
+            switch (resource) {
+                case "schema":
+                    response = await client.GET("/v1/billing/can-create-schema");
+                    break;
+                case "prompt":
+                    response = await client.GET("/v1/billing/can-create-prompt");
+                    break;
+                case "team-member":
+                    response = await client.GET("/v1/billing/can-add-team-member");
+                    break;
+                default:
+                    throw new Error(`Unknown resource: "${resource}". Use: schema, prompt, team-member`);
+            }
+            const result = response.data?.result;
+            if (isJsonOutput(command)) {
+                console.log(JSON.stringify({ resource, canCreate: result }));
+            }
+            else if (result) {
+                console.log(chalk.green(`You can create a new ${resource}.`));
+            }
+            else {
+                console.log(chalk.yellow(`You cannot create a new ${resource}. Upgrade your tier or check limits.`));
+            }
+        });
+    });
+    return cmd;
+}
+//# sourceMappingURL=billing.js.map

package/dist/commands/config.d.ts

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