@cloudverse/aix-cli 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# AIX CLI
+
+Command-line interface for the AIX Brain Decision Engine. Decision-only surface — no gateway behavior, no prompt proxying.
+
+## Setup
+
+```bash
+# From repo root
+cd packages/aix-cli
+
+# Set environment
+export AIX_API_URL=http://localhost:5000   # or https://aix.cloudverse.ai
+export AIX_TOKEN=your_api_key_here         # AIX API key or legacy key
+```
+
+## Commands
+
+### `aix decide`
+
+Request a routing decision from the AIX Brain.
+
+```bash
+# Basic decision
+npx tsx src/index.ts decide --execution-class conversation
+
+# With priority and constraints
+npx tsx src/index.ts decide \
+  --execution-class code_generation \
+  --priority quality \
+  --max-cost-usd 0.05 \
+  --max-latency-ms 3000
+
+# With token estimates for cost simulation
+npx tsx src/index.ts decide \
+  --execution-class conversation \
+  --input-tokens 1000 \
+  --output-tokens 500
+
+# JSON output
+npx tsx src/index.ts decide --execution-class conversation --format json
+
+# From intent JSON file
+npx tsx src/index.ts decide --intent-json ./my-request.json
+```
+
+### `aix explain <decision_id>`
+
+Get explanation and trace for a past decision.
+
+```bash
+npx tsx src/index.ts explain dec_abc123
+npx tsx src/index.ts explain dec_abc123 --format json
+```
+
+### `aix health`
+
+Check AIX Brain health and coverage.
+
+```bash
+npx tsx src/index.ts health
+```
+
+### `aix policy show`
+
+Show current org routing policy.
+
+```bash
+npx tsx src/index.ts policy show
+```
+
+### `aix catalog status`
+
+Show catalog status and coverage.
+
+```bash
+npx tsx src/index.ts catalog status
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `AIX_API_URL` | No | `http://localhost:5000` | AIX server base URL |
+| `AIX_TOKEN` | Yes* | — | API key for authentication |
+
+*Not required if server allows unauthenticated access in local dev mode.
+
+## Output Formats
+
+- `--format pretty` (default): Human-readable with color coding
+- `--format json`: Raw JSON for piping to other tools

package/dist/formatters.d.ts

@@ -0,0 +1,5 @@
+export declare function formatDecision(d: any): void;
+export declare function formatExplanation(d: any): void;
+export declare function formatHealth(h: any): void;
+export declare function formatPolicy(p: any): void;
+export declare function formatCatalogStatus(c: any): void;

package/dist/formatters.js

@@ -0,0 +1,164 @@
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+function check(ok) {
+    return ok ? `${GREEN}OK${RESET}` : `${YELLOW}WARN${RESET}`;
+}
+function statusIcon(status) {
+    if (status === 'ok' || status === 'healthy')
+        return `${GREEN}OK${RESET}`;
+    if (status === 'degraded')
+        return `${YELLOW}DEGRADED${RESET}`;
+    return `${RED}FAILED${RESET}`;
+}
+export function formatDecision(d) {
+    console.log(`\n${BOLD}AIX Brain Decision${RESET}`);
+    console.log(`${'─'.repeat(50)}`);
+    console.log(`  Status:     ${statusIcon(d.decision_status)} ${d.degraded_reason || d.degradation_reason || ''}`);
+    console.log(`  Provider:   ${CYAN}${d.provider}${RESET}`);
+    console.log(`  Model:      ${CYAN}${d.model_name || d.model_class}${RESET}`);
+    console.log(`  Class:      ${d.model_class}`);
+    console.log(`  Confidence: ${d.confidence?.toFixed(2) || 'N/A'}`);
+    console.log(`  Data Used:  ${d.data_used}`);
+    console.log(`  Decision:   ${DIM}${d.decision_id}${RESET}`);
+    if (d.reason) {
+        console.log(`\n  ${DIM}Reason: ${d.reason}${RESET}`);
+    }
+    if (d.explanation) {
+        console.log(`  ${DIM}Explanation: ${d.explanation}${RESET}`);
+    }
+    if (d.score_breakdown) {
+        console.log(`\n  ${BOLD}Score Breakdown${RESET}`);
+        const sb = d.score_breakdown;
+        console.log(`    Cost:        ${sb.cost?.toFixed(3) || '-'}`);
+        console.log(`    Latency:     ${sb.latency?.toFixed(3) || '-'}`);
+        console.log(`    QSR:         ${sb.qsr?.toFixed(3) || '-'}`);
+        console.log(`    Reliability: ${sb.reliability?.toFixed(3) || '-'}`);
+        console.log(`    Total:       ${BOLD}${sb.total?.toFixed(3) || '-'}${RESET}`);
+        if (sb.cost_source) {
+            console.log(`    Cost Source: ${sb.cost_source}`);
+        }
+    }
+    if (d.alternatives && d.alternatives.length > 0) {
+        console.log(`\n  ${BOLD}Top Alternatives${RESET}`);
+        d.alternatives.slice(0, 3).forEach((alt, i) => {
+            console.log(`    ${i + 1}. ${alt.provider}/${alt.model_name || alt.model_class} (score: ${alt.score?.toFixed(3)}, data: ${alt.data_used})`);
+        });
+    }
+    console.log('');
+}
+export function formatExplanation(d) {
+    console.log(`\n${BOLD}Decision Explanation${RESET}`);
+    console.log(`${'─'.repeat(50)}`);
+    console.log(`  Decision ID:      ${d.id || d.decision_id}`);
+    console.log(`  Execution Class:  ${d.execution_class}`);
+    console.log(`  Provider:         ${CYAN}${d.provider}${RESET}`);
+    console.log(`  Model:            ${CYAN}${d.model_name || d.model_class}${RESET}`);
+    console.log(`  Confidence:       ${d.confidence?.toFixed?.(2) || d.confidence || 'N/A'}`);
+    console.log(`  Data Used:        ${d.data_used}`);
+    console.log(`  Created:          ${d.created_at || 'N/A'}`);
+    if (d.reason) {
+        console.log(`\n  ${BOLD}Reason${RESET}`);
+        console.log(`  ${d.reason}`);
+    }
+    if (d.score_breakdown) {
+        console.log(`\n  ${BOLD}Score Breakdown${RESET}`);
+        console.log(`  ${JSON.stringify(d.score_breakdown, null, 4).split('\n').join('\n  ')}`);
+    }
+    console.log('');
+}
+export function formatHealth(h) {
+    console.log(`\n${BOLD}AIX Brain Health${RESET}`);
+    console.log(`${'─'.repeat(50)}`);
+    console.log(`  Overall: ${statusIcon(h.status)}`);
+    if (h.execution_class_coverage) {
+        const ec = h.execution_class_coverage;
+        console.log(`\n  ${BOLD}Execution Class Coverage${RESET}`);
+        console.log(`    Total classes:      ${ec.total}`);
+        console.log(`    With capabilities:  ${ec.with_capability_rows} ${check(ec.with_capability_rows > 0)}`);
+        if (ec.details && ec.details.length > 0) {
+            ec.details.forEach((d) => {
+                const icon = d.supported_rows > 0 ? `${GREEN}OK${RESET}` : `${RED}--${RESET}`;
+                console.log(`      ${icon}  ${d.name} (${d.supported_rows} providers)`);
+            });
+        }
+    }
+    if (h.routable_models) {
+        console.log(`\n  ${BOLD}Routable Models${RESET}`);
+        console.log(`    Active: ${h.routable_models.total} ${check(h.routable_models.total > 0)}`);
+    }
+    if (h.provider_defaults) {
+        console.log(`\n  ${BOLD}Provider Defaults${RESET}`);
+        console.log(`    Count:         ${h.provider_defaults.count}`);
+        console.log(`    Coverage:      ${check(h.provider_defaults.coverage === 'ok')}`);
+        console.log(`    Safe Fallback: ${check(h.provider_defaults.safe_fallback === 'ok')}`);
+    }
+    if (h.pricing) {
+        console.log(`\n  ${BOLD}Pricing${RESET}`);
+        console.log(`    Coverage:  ${h.pricing.coverage}`);
+        console.log(`    Last Sync: ${h.pricing.last_sync || 'never'}`);
+    }
+    console.log(`\n  Discovered Models: ${h.discovered_models || 0}`);
+    console.log('');
+}
+export function formatPolicy(p) {
+    console.log(`\n${BOLD}AIX Brain Routing Policy${RESET}`);
+    console.log(`${'─'.repeat(50)}`);
+    console.log(`  Org:    ${p.org_id}`);
+    console.log(`  Source: ${p.source}`);
+    if (p.policy) {
+        const pol = p.policy;
+        if (pol.allowed_providers && pol.allowed_providers.length > 0) {
+            console.log(`\n  ${BOLD}Allowed Providers${RESET}`);
+            pol.allowed_providers.forEach((prov) => {
+                console.log(`    - ${prov}`);
+            });
+        }
+        else {
+            console.log(`\n  Allowed Providers: ${DIM}all (no restrictions)${RESET}`);
+        }
+        if (pol.default_priority) {
+            console.log(`  Default Priority: ${pol.default_priority}`);
+        }
+        if (pol.mode) {
+            console.log(`  Routing Mode:     ${pol.mode}`);
+        }
+        if (pol.budget_guard) {
+            console.log(`\n  ${BOLD}Budget Guard${RESET}`);
+            console.log(`    ${JSON.stringify(pol.budget_guard, null, 4).split('\n').join('\n    ')}`);
+        }
+    }
+    console.log(`\n  Connected Providers: ${p.connected_providers_count}`);
+    if (p.connected_providers && p.connected_providers.length > 0) {
+        p.connected_providers.forEach((prov) => {
+            console.log(`    - ${prov}`);
+        });
+    }
+    console.log('');
+}
+export function formatCatalogStatus(c) {
+    console.log(`\n${BOLD}AIX Brain Catalog Status${RESET}`);
+    console.log(`${'─'.repeat(50)}`);
+    console.log(`  Discovered Models:  ${c.discovered_model_count}`);
+    console.log(`  Routable Models:    ${c.routable_model_count}`);
+    console.log(`  Provider Defaults:  ${c.defaults_count}`);
+    if (c.activation_gates) {
+        const ag = c.activation_gates;
+        console.log(`\n  ${BOLD}Activation Gates${RESET}`);
+        console.log(`    Pricing Coverage:     ${check(ag.has_pricing_coverage)}`);
+        console.log(`    Capability Rows:      ${check(ag.has_capability_rows)}`);
+        console.log(`    Execution Classes:    ${ag.execution_classes_with_coverage}/${ag.execution_classes_total} with coverage`);
+    }
+    if (c.pricing) {
+        console.log(`\n  ${BOLD}Pricing Catalog${RESET}`);
+        console.log(`    LLM Models:     ${c.pricing.llm_models}`);
+        console.log(`    GPU SKUs:       ${c.pricing.gpu_skus}`);
+        console.log(`    Providers:      ${c.pricing.providers}`);
+        console.log(`    Last Sync:      ${c.pricing.last_sync_at || 'never'}`);
+    }
+    console.log('');
+}

package/dist/http.d.ts

@@ -0,0 +1,12 @@
+export interface HttpConfig {
+    baseUrl: string;
+    token: string | null;
+}
+export declare function getConfig(): HttpConfig;
+export interface HttpResponse<T = any> {
+    ok: boolean;
+    status: number;
+    data: T;
+}
+export declare function request<T = any>(method: 'GET' | 'POST', path: string, body?: any): Promise<HttpResponse<T>>;
+export declare function exitWithError(message: string, details?: string): never;

package/dist/http.js

@@ -0,0 +1,37 @@
+const DEFAULT_BASE_URL = 'http://localhost:5000';
+export function getConfig() {
+    return {
+        baseUrl: (process.env.AIX_API_URL || DEFAULT_BASE_URL).replace(/\/$/, ''),
+        token: process.env.AIX_TOKEN || null,
+    };
+}
+export async function request(method, path, body) {
+    const config = getConfig();
+    const url = `${config.baseUrl}${path}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+    };
+    if (config.token) {
+        headers['Authorization'] = `Bearer ${config.token}`;
+    }
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    let data;
+    try {
+        data = await res.json();
+    }
+    catch {
+        data = { error: `HTTP ${res.status}: ${res.statusText}` };
+    }
+    return { ok: res.ok, status: res.status, data };
+}
+export function exitWithError(message, details) {
+    console.error(`\x1b[31mError:\x1b[0m ${message}`);
+    if (details)
+        console.error(`  ${details}`);
+    process.exit(1);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { request, exitWithError } from './http.js';
+import { formatDecision, formatExplanation, formatHealth, formatPolicy, formatCatalogStatus } from './formatters.js';
+const program = new Command();
+program
+    .name('aix')
+    .description('AIX Brain Decision Engine CLI — decision-only surface')
+    .version('1.0.0');
+program
+    .command('decide')
+    .description('Request a routing decision from the AIX Brain')
+    .requiredOption('--execution-class <string>', 'Execution class (e.g., conversation, code_generation)')
+    .option('--priority <string>', 'Scoring priority: cost | balanced | quality | latency', 'balanced')
+    .option('--allow-substitution <boolean>', 'Allow model substitution', 'true')
+    .option('--max-cost-usd <number>', 'Max cost constraint in USD')
+    .option('--max-latency-ms <number>', 'Max latency constraint in ms')
+    .option('--min-qsr <number>', 'Minimum quality score ratio')
+    .option('--compliance-tier <string>', 'Compliance tier (passed through)')
+    .option('--input-tokens <number>', 'Estimated input tokens for cost simulation')
+    .option('--output-tokens <number>', 'Estimated output tokens for cost simulation')
+    .option('--intent-json <path>', 'Path to JSON file with full request payload')
+    .option('--format <string>', 'Output format: pretty | json', 'pretty')
+    .action(async (opts) => {
+    let payload;
+    if (opts.intentJson) {
+        const fs = await import('fs');
+        try {
+            const raw = fs.readFileSync(opts.intentJson, 'utf-8');
+            payload = JSON.parse(raw);
+        }
+        catch (err) {
+            exitWithError(`Failed to read intent JSON file: ${opts.intentJson}`, err.message);
+        }
+    }
+    else {
+        payload = {
+            execution_class: opts.executionClass,
+            intent: {
+                priority: opts.priority,
+                constraints: {},
+            },
+            process_model: {
+                allow_model_substitution: opts.allowSubstitution === 'true',
+            },
+        };
+        if (opts.maxCostUsd)
+            payload.intent.constraints.max_cost_usd = parseFloat(opts.maxCostUsd);
+        if (opts.maxLatencyMs)
+            payload.intent.constraints.max_latency_ms = parseInt(opts.maxLatencyMs);
+        if (opts.minQsr)
+            payload.intent.constraints.min_qsr = parseFloat(opts.minQsr);
+        if (opts.complianceTier)
+            payload.compliance_tier = opts.complianceTier;
+        if (opts.inputTokens || opts.outputTokens) {
+            payload.token_estimates = {};
+            if (opts.inputTokens)
+                payload.token_estimates.input_tokens = parseInt(opts.inputTokens);
+            if (opts.outputTokens)
+                payload.token_estimates.output_tokens = parseInt(opts.outputTokens);
+        }
+    }
+    const res = await request('POST', '/api/brain/decide', payload);
+    if (!res.ok) {
+        exitWithError(`Decision failed (HTTP ${res.status})`, JSON.stringify(res.data, null, 2));
+    }
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(res.data, null, 2));
+    }
+    else {
+        formatDecision(res.data);
+    }
+});
+program
+    .command('explain <decision_id>')
+    .description('Get explanation and trace for a past decision')
+    .option('--format <string>', 'Output format: pretty | json', 'pretty')
+    .action(async (decisionId, opts) => {
+    const res = await request('GET', `/api/brain/decisions/${decisionId}`);
+    if (!res.ok) {
+        exitWithError(`Failed to fetch decision (HTTP ${res.status})`, JSON.stringify(res.data, null, 2));
+    }
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(res.data, null, 2));
+    }
+    else {
+        formatExplanation(res.data);
+    }
+});
+program
+    .command('health')
+    .description('Check AIX Brain health and coverage')
+    .option('--format <string>', 'Output format: pretty | json', 'pretty')
+    .action(async (opts) => {
+    const res = await request('GET', '/api/brain/health');
+    if (!res.ok) {
+        exitWithError(`Health check failed (HTTP ${res.status})`, JSON.stringify(res.data, null, 2));
+    }
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(res.data, null, 2));
+    }
+    else {
+        formatHealth(res.data);
+    }
+});
+const policyCmd = program
+    .command('policy')
+    .description('Brain routing policy commands');
+policyCmd
+    .command('show')
+    .description('Show current org routing policy')
+    .option('--format <string>', 'Output format: pretty | json', 'pretty')
+    .action(async (opts) => {
+    const res = await request('GET', '/api/brain/policy');
+    if (!res.ok) {
+        exitWithError(`Policy fetch failed (HTTP ${res.status})`, JSON.stringify(res.data, null, 2));
+    }
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(res.data, null, 2));
+    }
+    else {
+        formatPolicy(res.data);
+    }
+});
+const catalogCmd = program
+    .command('catalog')
+    .description('Brain catalog commands');
+catalogCmd
+    .command('status')
+    .description('Show catalog status and coverage')
+    .option('--format <string>', 'Output format: pretty | json', 'pretty')
+    .action(async (opts) => {
+    const res = await request('GET', '/api/brain/catalog/status');
+    if (!res.ok) {
+        exitWithError(`Catalog status failed (HTTP ${res.status})`, JSON.stringify(res.data, null, 2));
+    }
+    if (opts.format === 'json') {
+        console.log(JSON.stringify(res.data, null, 2));
+    }
+    else {
+        formatCatalogStatus(res.data);
+    }
+});
+program.parse();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cloudverse/aix-cli",
+  "version": "1.0.0",
+  "description": "AIX Brain Decision Engine CLI - decision-only surface for AI workload routing",
+  "type": "module",
+  "bin": {
+    "aix": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsx": "^4.7.0",
+    "@types/node": "^20.0.0"
+  },
+  "keywords": ["aix", "cloudverse", "cli", "brain", "decision", "llm", "routing", "ai", "gpu"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudverse-ai/aix-cli"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}