@zils/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zils contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Zils 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.
+Sign in with your Zils account, submit text training, follow runs, download
+accepted models, and call the decision API.
+
+Requires Node.js 20+ and **Python 3.11+**, including `venv` and `pip`. Install
+Python from [python.org](https://www.python.org/downloads/). On Debian/Ubuntu,
+install `python3-venv` if your Python installation does not include it.
+
+```sh
+npm install -g @zils/cli
+zils login
+zils train list
+```
+
+Or run without a global npm installation:
+
+```sh
+npx @zils/cli login
+```
+
+First use installs the bundled Python CLI and its dependencies from PyPI into a
+private cache. It needs internet access, takes longer than subsequent starts,
+and does not modify your system Python. npm installation itself runs no setup
+scripts. Set `ZILS_PYTHON` to an executable path if Python is not on your PATH.
+
+## Commands
+
+```sh
+zils --help
+zils train submit --help
+zils train list --json
+zils train status JOB_ID --watch
+zils train download JOB_ID --out ./accepted-model
+zils train cancel JOB_ID
+zils logout
+```
+
+`zils login` opens browser sign-in for training. Browser sign-in requires a local
+desktop browser and port 43187. Training uses your account's allowance/credit;
+only an accepted result can be downloaded. Login does not create an inference key.
+
+For inference, supply an existing key at the private prompt:
+
+```sh
+zils login --api-key
+zils models
+zils decide --state "Please refund the duplicate charge." \
+  --questions '{"refund":{"type":"noul","instructions":"Is a refund requested?"}}'
+```
+
+Keys are never supplied as command arguments. Existing `~/.zils` credentials and
+training receipts are shared with the Python CLI. Automatic request retries are
+off. `zils logout` removes local credentials; it does not revoke remote sessions.
+Windows users should protect their account's cache and configuration directories.
+
+## Submit training data
+
+Prepare separate UTF-8 JSONL files for training, calibration, and test cases.
+Every line is one case, for example:
+
+```json
+{"id":"train-1","group_id":"ticket-1","family":"refund","state":"Please refund the duplicate charge.","question":{"type":"noul","instructions":"Is a refund requested?"},"label":"true"}
+```
+
+Each case needs `id`, `group_id`, `family`, `state`, `question`, and `label`.
+IDs must be unique across all splits. Related groups and identical state/question
+pairs must stay in one split. Calibration and test families must match and occur
+in training. Labels are strings: `"false"`/`"true"` for `noul`, a criterion key for
+`choice`, or a zero-based index for `score`. Image cases are not supported.
+
+```sh
+zils train submit --name ticket-routing \
+  --train train.jsonl --calibration calibration.jsonl --test test.jsonl \
+  --min-accuracy 0.8 --min-brier-improvement 0.01 \
+  --allow-training-data-export --json
+```
+
+This submits a real training job and permits data export to approved workers.
+Both quality thresholds are required. Keep the returned job ID to follow the run.
+Run `zils train submit --help` for the available model/profile options.
+If an upload is interrupted, resume the same job with unchanged files:
+
+```sh
+zils train resume JOB_ID \
+  --train train.jsonl --calibration calibration.jsonl --test test.jsonl
+```
+
+Do not submit again after an ambiguous connection failure: first inspect
+`zils train list` and the website. Local recovery receipts are retained under
+`~/.zils/training`. Cancellation does not undo incurred costs or promise a refund.
+
+## Runtime cache
+
+The runtime cache lives under `~/Library/Caches/zils/cli` on macOS,
+`~/.cache/zils/cli` on Linux, or `%LOCALAPPDATA%\zils\cli` on Windows.
+`XDG_CACHE_HOME`, when set, overrides the cache base. Removing the runtime cache
+only forces setup on the next invocation; it does not remove credentials or jobs.
+
+The CLI bundles the same Python implementation as `zils-sdk`; no model weights,
+GPU runtime, or private repository access is required. The JavaScript/TypeScript
+application client is available separately as `@zils/sdk`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+The strict MCP argument check in `zils_sdk/mcp.py` is adapted from
+`nace-mcp` 0.1.0, https://pypi.org/project/nace-mcp/.
+No hosted Nace service is used.
+
+MIT License
+
+Copyright (c) 2026 Nace AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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.
+
+
+TypeSafe and the official MCP SDK are installed dependencies with their own
+license notices. Their implementations are not vendored in this package.

package/bin/zils.cjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawn, spawnSync } = require('node:child_process');
+const { join } = require('node:path');
+
+// Use an argument array throughout: dataset paths and questions are never shell code.
+const candidates = process.env.ZILS_PYTHON
+  ? [[process.env.ZILS_PYTHON]]
+  : process.platform === 'win32' ? [['py', '-3'], ['python'], ['python3']] : [['python3'], ['python']];
+const python = candidates.find(([command, ...prefix]) => {
+  const result = spawnSync(command, [...prefix, '-I', '-c',
+    'import sys; sys.exit(0 if sys.version_info >= (3, 11) else 1)'],
+  { stdio: 'ignore', timeout: 10000, windowsHide: true });
+  return result.status === 0;
+});
+
+if (!python) {
+  console.error('Zils requires Python 3.11+. Install it from https://www.python.org/downloads/ and try again.');
+  console.error('If Python is elsewhere, set ZILS_PYTHON to its executable path.');
+  process.exitCode = 2;
+} else {
+  const [command, ...prefix] = python;
+  const child = spawn(command, [...prefix, '-I', join(__dirname, '..', 'bootstrap.py'), ...process.argv.slice(2)],
+    { stdio: 'inherit' });
+  for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal));
+  child.on('error', () => { console.error('Could not start the Zils Python runtime.'); process.exitCode = 2; });
+  child.on('exit', (code, signal) => { process.exitCode = code ?? (signal === 'SIGINT' ? 130 : 143); });
+}

package/bootstrap.py

@@ -0,0 +1,122 @@
+"""Run the bundled CLI wheel in a private, versioned Python environment."""
+
+import hashlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def installation_lock(path):
+    with path.open("a+b") as lock:
+        if os.name == "nt":
+            import msvcrt
+
+            if path.stat().st_size == 0:
+                lock.write(b"0")
+                lock.flush()
+            deadline = time.monotonic() + 300
+            while True:
+                lock.seek(0)
+                try:
+                    msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)
+                    break
+                except OSError:
+                    if time.monotonic() >= deadline:
+                        raise RuntimeError("Another Zils setup is still running. Try again later.")
+                    time.sleep(0.1)
+            try:
+                yield
+            finally:
+                lock.seek(0)
+                msvcrt.locking(lock.fileno(), msvcrt.LK_UNLCK, 1)
+        else:
+            import fcntl
+
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(lock, fcntl.LOCK_UN)
+
+
+def runtime():
+    package = Path(__file__).resolve().parent
+    version = json.loads((package / "package.json").read_text())["version"]
+    wheel = package / "vendor" / f"zils_sdk-{version}-py3-none-any.whl"
+    digest = hashlib.sha256(wheel.read_bytes()).hexdigest()
+    cache = os.environ.get("XDG_CACHE_HOME")
+    if not cache:
+        if os.name == "nt":
+            cache = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        else:
+            cache = str(Path.home() / ("Library/Caches" if sys.platform == "darwin" else ".cache"))
+    root = (
+        Path(cache)
+        / "zils"
+        / "cli"
+        / f"{version}-{digest[:16]}-py{sys.version_info.major}.{sys.version_info.minor}"
+    )
+    root.mkdir(parents=True, exist_ok=True, mode=0o700)
+    environment = root / "runtime"
+    python = environment / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    ready = root / "ready"
+    with installation_lock(root / "install.lock"):
+        if not (ready.is_file() and python.is_file()):
+            print("Setting up Zils CLI dependencies (first use only)...", file=sys.stderr)
+            ready.unlink(missing_ok=True)
+            if environment.exists():
+                shutil.rmtree(environment)
+            subprocess.run(
+                [sys.executable, "-I", "-m", "venv", str(environment)],
+                stdout=sys.stderr,
+                check=True,
+            )
+            subprocess.run(
+                [
+                    str(python),
+                    "-I",
+                    "-m",
+                    "pip",
+                    "--isolated",
+                    "--disable-pip-version-check",
+                    "install",
+                    "--no-input",
+                    "--only-binary=:all:",
+                    "--index-url",
+                    "https://pypi.org/simple",
+                    str(wheel),
+                ],
+                stdout=sys.stderr,
+                check=True,
+            )
+            subprocess.run(
+                [str(python), "-I", "-c", "import zils_sdk; from zils_sdk.cli import main"],
+                stdout=sys.stderr,
+                check=True,
+            )
+            ready.write_text(digest + "\n")
+    return python
+
+
+if __name__ == "__main__":
+    try:
+        executable = runtime()
+        command = [str(executable), "-I", "-m", "zils_sdk.cli", *sys.argv[1:]]
+        if os.name == "nt":
+            # Windows exec does not preserve the caller's process/exit-code chain.
+            raise SystemExit(subprocess.run(command).returncode)
+        os.execv(str(executable), command)
+    except KeyboardInterrupt:
+        raise SystemExit(130)
+    except (OSError, RuntimeError, subprocess.CalledProcessError) as error:
+        print(
+            f"Zils setup failed: {error}. Check Python's venv/pip installation and network, then retry.",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@zils/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Sign in, train, and call Zils decision models from your terminal",
+  "license": "MIT",
+  "homepage": "https://zils.ai",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ooo-hq/zils-sdk.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "engines": { "node": ">=20" },
+  "bin": { "zils": "bin/zils.cjs" },
+  "files": ["bin", "bootstrap.py", "vendor", "README.md", "LICENSE", "THIRD_PARTY_NOTICES.md"],
+  "scripts": {
+    "prepack": "node scripts/build.cjs",
+    "test": "node --test test/installed.test.cjs"
+  }
+}