embedding-studio-cli 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2026 Embedding Space Private Limited
+
+Permission is granted to use, copy and redistribute this client, unmodified or
+modified, for the purpose of accessing the Embedding Studio service. Use of the
+service itself is governed by the terms at https://studio.embedding.in/terms.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# embedding-studio-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Embedding Studio](https://studio.embedding.in) API from a terminal. Push labelled
+data, fit and calibrate a decision model, place the review band, ask for decisions, and
+download the calibration file. Everything the console does, behind a contract a script
+or a coding agent can rely on: JSON on stdout, non-zero exit with the API's own message
+on stderr when something is refused.
+
+```
+npm install -g embedding-studio-cli
+export STUDIO_API_KEY=esk_...        # issued once, in the console, under API keys
+
+studio create --name "Support routing" --template support-routing
+studio upload support-routing cases.csv --watch
+studio band <fit_id> --precision 0.9
+studio decide support-routing --text "I was billed twice, refund one"
+studio calibration support-routing -o calibration.json
+```
+
+No dependencies: Node 18 or newer is the whole requirement. `STUDIO_API_URL` points it
+at a self-hosted deployment. The same tool ships as a single Python file at
+`https://studio.embedding.in/cli.py`; the two carry one command surface, pinned equal
+by a test.
+
+Docs: https://studio.embedding.in/docs

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "embedding-studio-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "The Embedding Studio API from a terminal: push labelled data, fit and calibrate, place the review band, decide, and download the calibration file. JSON out, non-zero exit on refusal.",
+  "bin": {
+    "studio": "studio.js"
+  },
+  "files": [
+    "studio.js"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://studio.embedding.in/docs",
+  "author": "Embedding Space Private Limited <nandakishor@embedding.in>",
+  "keywords": [
+    "embedding-studio",
+    "calibration",
+    "decisions",
+    "cli",
+    "conformal"
+  ],
+  "bugs": {
+    "email": "nandakishor@embedding.in"
+  }
+}

package/studio.js

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+/* studio: the Embedding Studio API from a terminal, for the Node world.
+ *
+ * The same contract as the Python file served at /cli.py: every command prints JSON to stdout,
+ * every refusal exits non-zero with the API's own message on stderr, auth is STUDIO_API_KEY in
+ * the environment and STUDIO_API_URL points anywhere other than the hosted service. The command
+ * surface is pinned equal to the Python client by a test, so the npm install and the curl
+ * install cannot drift apart.
+ *
+ * No dependencies: Node 18 ships fetch, FormData and Blob, which is everything an API client
+ * needs. Global install is `npm install -g embedding-studio-cli`, and then `studio projects`.
+ */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_URL = "https://embedding-studio-api.fly.dev";
+
+function fail(msg, code) {
+  process.stderr.write(msg + "\n");
+  process.exit(code);
+}
+
+function say(data) {
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+
+async function call(method, p, { body, file, raw } = {}) {
+  const base = (opts.url || DEFAULT_URL).replace(/\/+$/, "");
+  const headers = {};
+  const key = process.env.STUDIO_API_KEY || "";
+  if (key) headers["x-api-key"] = key;
+  let payload;
+  if (file !== undefined) {
+    const form = new FormData();
+    const name = path.basename(file);
+    const type = name.toLowerCase().endsWith(".csv") ? "text/csv" : "text/plain";
+    form.append("file", new Blob([fs.readFileSync(file)], { type }), name);
+    payload = form;
+  } else if (body !== undefined) {
+    headers["content-type"] = "application/json";
+    payload = JSON.stringify(body);
+  }
+  let r;
+  try {
+    r = await fetch(base + p, { method, headers, body: payload });
+  } catch (e) {
+    fail(`error network: could not reach ${base + p} (${e.cause?.code || e.message})`, 1);
+  }
+  if (!r.ok) {
+    let detail = "";
+    const text = await r.text();
+    try { detail = JSON.parse(text).detail ?? ""; } catch { /* not json */ }
+    fail(`error ${r.status}: ${String(detail) || text.slice(0, 500)}`, 1);
+  }
+  if (raw) return Buffer.from(await r.arrayBuffer());
+  const text = await r.text();
+  return text ? JSON.parse(text) : {};
+}
+
+async function watchJob(jobId, interval) {
+  let last = "";
+  for (;;) {
+    const job = await call("GET", `/v1/jobs/${jobId}`);
+    const line = `${job.state} ${job.stage} ${job.done_rows}/${job.total_rows}`;
+    if (line !== last) { process.stderr.write(line + "\n"); last = line; }
+    if (["done", "failed", "cancelled"].includes(job.state)) return job;
+    await new Promise((res) => setTimeout(res, interval * 1000));
+  }
+}
+
+function readStdin() {
+  return new Promise((res) => {
+    let got = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => { got += c; });
+    process.stdin.on("end", () => res(got));
+  });
+}
+
+/* ---- a small flag parser: --name value, --flag, and positionals, nothing cleverer ---- */
+function parse(argv, spec) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-o") {                      /* the one short flag argparse gives the Python side */
+      out.o = argv[++i];
+      continue;
+    }
+    if (a.startsWith("--")) {
+      const name = a.slice(2);
+      if (!(name in spec)) fail(`unknown flag --${name}`, 2);
+      if (spec[name] === "flag") out[name] = true;
+      else out[name] = argv[++i];
+    } else out._.push(a);
+  }
+  return out;
+}
+
+/* The registry. Names and flags mirror the Python client exactly; the parity test reads them. */
+const COMMANDS = {
+  "health": async () => say(await call("GET", "/v1/health")),
+  "templates": async () => say(await call("GET", "/v1/templates")),
+  "projects": async () => say(await call("GET", "/v1/projects")),
+  "project": async (argv) => {
+    const a = parse(argv, {});
+    say(await call("GET", `/v1/projects/${a._[0]}`));
+  },
+  "create": async (argv) => {
+    const a = parse(argv, { "name": "value", "template": "value", "sheet": "value",
+                            "text-column": "value" });
+    if (!a.name || (!a.template === !a.sheet)) {
+      fail("create needs --name and exactly one of --template or --sheet", 2);
+    }
+    const body = { name: a.name };
+    if (a.template) body.template = a.template;
+    else body.sheet = JSON.parse(fs.readFileSync(a.sheet, "utf8"));
+    if (a["text-column"]) body.text_column = a["text-column"];
+    say(await call("POST", "/v1/projects", { body }));
+  },
+  "delete": async (argv) => {
+    const a = parse(argv, { "yes": "flag" });
+    if (!a.yes) fail("refusing without --yes: deleting a project has no undo", 2);
+    say(await call("DELETE", `/v1/projects/${a._[0]}`));
+  },
+  "upload": async (argv) => {
+    const a = parse(argv, { "watch": "flag", "interval": "value" });
+    const out = await call("POST", `/v1/projects/${a._[0]}/datasets`, { file: a._[1] });
+    if (a.watch && out.job_id) {
+      const job = await watchJob(out.job_id, Number(a.interval || 2));
+      say(job);
+      process.exit(job.state === "done" ? 0 : 1);
+    }
+    say(out);
+  },
+  "sample": async (argv) => {
+    const a = parse(argv, { "watch": "flag", "interval": "value" });
+    const out = await call("POST", `/v1/projects/${a._[0]}/samples`, { file: a._[1] });
+    if (a.watch && out.job_id) {
+      const job = await watchJob(out.job_id, Number(a.interval || 2));
+      say(job);
+      process.exit(job.state === "done" ? 0 : 1);
+    }
+    say(out);
+  },
+  "job": async (argv) => {
+    const a = parse(argv, { "watch": "flag", "interval": "value" });
+    if (a.watch) {
+      const job = await watchJob(a._[0], Number(a.interval || 2));
+      say(job);
+      process.exit(job.state === "done" ? 0 : 1);
+    }
+    say(await call("GET", `/v1/jobs/${a._[0]}`));
+  },
+  "stop": async (argv) => say(await call("DELETE", `/v1/jobs/${parse(argv, {})._[0]}`)),
+  "restart": async (argv) =>
+    say(await call("POST", `/v1/jobs/${parse(argv, {})._[0]}/restart`, { body: {} })),
+  "fits": async (argv) => say(await call("GET", `/v1/projects/${parse(argv, {})._[0]}/fits`)),
+  "fit": async (argv) => say(await call("GET", `/v1/fits/${parse(argv, {})._[0]}`)),
+  "band": async (argv) => {
+    const a = parse(argv, { "precision": "value", "review-rate": "value",
+                            "max-review-rate": "value", "monthly-volume": "value",
+                            "minutes-per-review": "value", "no-activate": "flag" });
+    if (!a.precision === !a["review-rate"]) {
+      fail("band needs exactly one of --precision or --review-rate", 2);
+    }
+    const body = { activate: !a["no-activate"] };
+    if (a.precision) body.target_precision = Number(a.precision);
+    if (a["review-rate"]) body.review_rate = Number(a["review-rate"]);
+    if (a["max-review-rate"]) body.max_review_rate = Number(a["max-review-rate"]);
+    if (a["monthly-volume"]) body.monthly_volume = Number(a["monthly-volume"]);
+    if (a["minutes-per-review"]) body.minutes_per_review = Number(a["minutes-per-review"]);
+    say(await call("POST", `/v1/fits/${a._[0]}/policy`, { body }));
+  },
+  "serving": async (argv) =>
+    say(await call("GET", `/v1/projects/${parse(argv, {})._[0]}/serving`)),
+  "calibration": async (argv) => {
+    const a = parse(argv, { "out": "value", "o": "value" });
+    const buf = await call("GET", `/v1/projects/${a._[0]}/calibration/export`, { raw: true });
+    const out = a.out || a.o;
+    if (out) {
+      fs.writeFileSync(out, buf);
+      say({ saved: out, bytes: buf.length });
+    } else process.stdout.write(buf.toString("utf8"));
+  },
+  "decide": async (argv) => {
+    const a = parse(argv, { "text": "value", "idempotency-key": "value" });
+    const text = a.text !== undefined ? a.text : await readStdin();
+    const body = { text };
+    if (a["idempotency-key"]) body.idempotency_key = a["idempotency-key"];
+    say(await call("POST", `/v1/projects/${a._[0]}/decide`, { body }));
+  },
+  "ask": async (argv) => {
+    const a = parse(argv, { "text": "value", "template": "value", "questions": "value" });
+    if (!a.template === !a.questions) fail("ask needs exactly one of --template or --questions", 2);
+    const text = a.text !== undefined ? a.text : await readStdin();
+    const body = { text };
+    if (a.template) body.template = a.template;
+    else body.questions = JSON.parse(fs.readFileSync(a.questions, "utf8"));
+    say(await call("POST", "/v1/decide", { body }));
+  },
+  "decisions": async (argv) =>
+    say(await call("GET", `/v1/projects/${parse(argv, {})._[0]}/decisions`)),
+  "audit": async (argv) => say(await call("GET", `/v1/projects/${parse(argv, {})._[0]}/audit`)),
+  "drift": async (argv) => {
+    const a = parse(argv, { "sample-id": "value", "min-answers": "value" });
+    say(await call("POST", `/v1/projects/${a._[0]}/watch`,
+                   { body: { sample_id: a["sample-id"],
+                             min_answers: Number(a["min-answers"] || 50) } }));
+  },
+  "keys": async () => say(await call("GET", "/v1/keys")),
+  "key-rotate": async (argv) =>
+    say(await call("POST", `/v1/keys/${parse(argv, {})._[0]}/rotate`, { body: {} })),
+  "key-revoke": async (argv) => say(await call("DELETE", `/v1/keys/${parse(argv, {})._[0]}`)),
+  "billing": async () => say(await call("GET", "/v1/billing")),
+  "credits": async () => say(await call("GET", "/v1/credits")),
+};
+
+const opts = {};
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv[0] === "--url") { opts.url = argv[1]; argv.splice(0, 2); }
+  const cmd = argv.shift();
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    process.stderr.write(
+      "studio: the Embedding Studio API from a terminal. JSON out, non-zero exit on refusal.\n" +
+      "Auth is STUDIO_API_KEY in the environment; STUDIO_API_URL or --url overrides the base.\n" +
+      "commands: " + Object.keys(COMMANDS).join(", ") + "\n");
+    process.exit(cmd ? 0 : 2);
+  }
+  if (!(cmd in COMMANDS)) fail(`unknown command ${cmd}`, 2);
+  if (!opts.url) opts.url = process.env.STUDIO_API_URL || DEFAULT_URL;
+  await COMMANDS[cmd](argv);
+}
+
+main().catch((e) => fail(`error: ${e.message}`, 1));