sphere-cli 0.1.40 → 0.1.41

package/bin/sphere.js

@@ -4,15 +4,12 @@
 /**
  * sphere — CLI entry point.
  *
- * This wrapper handles argument parsing, progress display, and license checks,
- * then delegates generation to sphere-node.jsc (V8 bytecode, bytenode-loaded).
- *
  * Commands:
  *   sphere generate  <input.csv>  -o <output.csv>  [options]
- *   sphere license   activate|status|clear
+ *   sphere evaluate  <real.csv>   <synth.csv>       [options]
+ *   sphere certify   <real.csv>   <synth.csv>  -o <cert.html>  [options]
  *   sphere demo
- *   sphere evaluate  — not available in this version (requires Python sidecar)
- *   sphere certify   — not available in this version (requires Python sidecar)
+ *   sphere license   activate|status|clear
  */
 
 const { spawn } = require('child_process');
@@ -23,6 +20,8 @@ const os     = require('os');
 
 const PKG_DIR        = path.join(__dirname, '..');
 const SPHERE_NODE_JS = path.join(PKG_DIR, 'sphere-node.js');
+const EVALUATE_PY    = path.join(PKG_DIR, 'scripts', 'evaluate.py');
+const CERTIFY_PY     = path.join(PKG_DIR, 'scripts', 'certify.py');
 const VERSION        = require(path.join(PKG_DIR, 'package.json')).version;
 
 // ── License ───────────────────────────────────────────────────────────────────
@@ -150,6 +149,132 @@ function clearLine() {
   process.stderr.write(`\r${' '.repeat(BAR_WIDTH + 60)}\r`);
 }
 
+// ── Score bar (for evaluate output) ──────────────────────────────────────────
+
+function scoreBar(score, width = 20) {
+  const filled = Math.round(width * score / 100);
+  return '█'.repeat(filled) + '░'.repeat(width - filled);
+}
+
+function printEvalResults(result) {
+  const fid  = result.fidelity;
+  const priv = result.privacy;
+  const sep  = '─'.repeat(36);
+
+  process.stdout.write('\n');
+  process.stdout.write('  Fidelity\n');
+  process.stdout.write(`  ${sep}\n`);
+  for (const [label, key] of [
+    ['Mean',        'meanScore'],
+    ['Variance',    'varScore'],
+    ['Correlation', 'corScore'],
+    ['KS',          'ksScore'],
+  ]) {
+    const v = fid[key];
+    process.stdout.write(`  ${label.padEnd(14)} ${v.toFixed(1).padStart(5)}  ${scoreBar(v)}\n`);
+  }
+  process.stdout.write(`  ${sep}\n`);
+  const fc = fid.composite;
+  process.stdout.write(`  ${'Composite'.padEnd(14)} ${fc.toFixed(1).padStart(5)}  ${scoreBar(fc)}\n`);
+
+  if (priv) {
+    process.stdout.write('\n');
+    process.stdout.write('  Privacy\n');
+    process.stdout.write(`  ${sep}\n`);
+    for (const [label, key] of [
+      ['Singling Out', 'singlingOut'],
+      ['Linkability',  'linkability'],
+      ['Inference',    'inference'],
+    ]) {
+      const v = priv[key].score;
+      process.stdout.write(`  ${label.padEnd(14)} ${v.toFixed(1).padStart(5)}  ${scoreBar(v)}\n`);
+    }
+    process.stdout.write(`  ${sep}\n`);
+    const pc = priv.composite;
+    process.stdout.write(`  ${'Composite'.padEnd(14)} ${pc.toFixed(1).padStart(5)}  ${scoreBar(pc)}\n`);
+  } else if (result.privacy === null) {
+    process.stdout.write('\n  Privacy: skipped (--skip-privacy)\n');
+  }
+
+  process.stdout.write('\n');
+  const excluded = result.idColsExcluded || [];
+  const exclNote = excluded.length ? `  (${excluded.length} ID col${excluded.length > 1 ? 's' : ''} excluded)` : '';
+  process.stdout.write(
+    `  ${(result.nReal || 0).toLocaleString()} real rows \xd7 ${result.pOrig || '?'} cols` +
+    `  vs  ${(result.nSynth || 0).toLocaleString()} synthetic rows${exclNote}\n`,
+  );
+  process.stdout.write('\n');
+}
+
+// ── Python runner (shared by evaluate + certify) ──────────────────────────────
+
+function findPython() {
+  // Try python3 first, then python
+  for (const bin of ['python3', 'python']) {
+    try {
+      const { execFileSync } = require('child_process');
+      const out = execFileSync(bin, ['--version'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+      if (out.includes('Python 3')) return bin;
+    } catch { /* try next */ }
+  }
+  return null;
+}
+
+function runPythonScript(script, scriptArgs, { json: jsonMode = false } = {}) {
+  return new Promise((resolve) => {
+    const python = findPython();
+    if (!python) {
+      process.stderr.write(
+        'Error: Python 3 not found. Evaluation requires Python 3.10+.\n' +
+        '       Install Python from https://python.org and retry.\n',
+      );
+      process.exit(1);
+    }
+
+    const proc = spawn(python, [script, ...scriptArgs], { stdio: ['ignore', 'pipe', 'pipe'] });
+
+    let resultLine = '';
+    let errorLine  = '';
+
+    proc.stdout.on('data', (d) => { resultLine += d.toString(); });
+
+    proc.stderr.on('data', (d) => {
+      for (const line of d.toString().split('\n')) {
+        const s = line.trim();
+        if (!s) continue;
+        try {
+          const msg = JSON.parse(s);
+          if (typeof msg.progress === 'number' && !jsonMode) {
+            progressBar(msg.progress, msg.msg || '');
+          } else if (msg.error) {
+            errorLine = msg.error;
+          }
+        } catch { /* ignore non-JSON lines */ }
+      }
+    });
+
+    proc.on('close', (code) => {
+      if (!jsonMode) clearLine();
+      if (code !== 0) {
+        process.stderr.write(`Error: ${errorLine || 'evaluation process exited with code ' + code}\n`);
+        process.exit(1);
+      }
+      let result;
+      try { result = JSON.parse(resultLine.trim()); }
+      catch {
+        process.stderr.write('Error: could not parse evaluation output\n');
+        process.exit(1);
+      }
+      resolve(result);
+    });
+
+    proc.on('error', (err) => {
+      process.stderr.write(`Error: failed to start Python: ${err.message}\n`);
+      process.exit(1);
+    });
+  });
+}
+
 // ── Argument parsing helpers ──────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -197,7 +322,6 @@ async function cmdGenerate(pos, flags) {
     process.stderr.write(`Generating synthetic data from ${path.basename(input)} …\n`);
   }
 
-  // Build args for sphere-node.js
   const nodeArgs = [SPHERE_NODE_JS, input, output];
   if (flags.k)           nodeArgs.push('--k',        String(flags.k));
   if (flags.theta)       nodeArgs.push('--theta',     String(flags.theta));
@@ -245,7 +369,7 @@ async function cmdGenerate(pos, flags) {
 
       if (flags.json) {
         process.stdout.write(JSON.stringify(result) + '\n');
-        resolve();
+        resolve(result);
         return;
       }
 
@@ -257,7 +381,7 @@ async function cmdGenerate(pos, flags) {
       if (result.idColDetected) {
         process.stdout.write(`  ID columns excluded: ${result.idColName}\n`);
       }
-      resolve();
+      resolve(result);
     });
 
     proc.on('error', (err) => {
@@ -267,6 +391,90 @@ async function cmdGenerate(pos, flags) {
   });
 }
 
+// ── sphere evaluate ───────────────────────────────────────────────────────────
+
+async function cmdEvaluate(pos, flags) {
+  await checkLicense();
+
+  const real  = pos[0];
+  const synth = pos[1];
+
+  if (!real)  { process.stderr.write('Error: missing real CSV\n');  process.exit(1); }
+  if (!synth) { process.stderr.write('Error: missing synth CSV\n'); process.exit(1); }
+  if (!fs.existsSync(real))  { process.stderr.write(`Error: file not found: ${real}\n`);  process.exit(1); }
+  if (!fs.existsSync(synth)) { process.stderr.write(`Error: file not found: ${synth}\n`); process.exit(1); }
+
+  if (!flags.json) {
+    process.stderr.write(`Evaluating ${path.basename(real)} vs ${path.basename(synth)} …\n`);
+  }
+
+  const scriptArgs = [real, synth];
+  if (flags['skip-privacy'])  scriptArgs.push('--skip-privacy');
+  if (flags['n-attacks'])     scriptArgs.push('--n-attacks',   String(flags['n-attacks']));
+  if (flags['n-secrets'])     scriptArgs.push('--n-secrets',   String(flags['n-secrets']));
+  if (flags['n-atk-cap'])     scriptArgs.push('--n-atk-cap',   String(flags['n-atk-cap']));
+  if (flags['n-neighbors'])   scriptArgs.push('--n-neighbors', String(flags['n-neighbors']));
+  if (flags['n-aux-cols'])    scriptArgs.push('--n-aux-cols',  String(flags['n-aux-cols']));
+  if (flags.seed)             scriptArgs.push('--seed',        String(flags.seed));
+
+  const result = await runPythonScript(EVALUATE_PY, scriptArgs, { json: !!flags.json });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return result;
+  }
+
+  const evalS = ((result.runMs || 0) / 1000).toFixed(1);
+  process.stdout.write(`✓ Evaluation complete  (${evalS} s)\n`);
+  printEvalResults(result);
+  return result;
+}
+
+// ── sphere certify ────────────────────────────────────────────────────────────
+
+async function cmdCertify(pos, flags) {
+  await checkLicense();
+
+  const real   = pos[0];
+  const synth  = pos[1];
+  const output = flags.output;
+
+  if (!real)   { process.stderr.write('Error: missing real CSV\n');  process.exit(1); }
+  if (!synth)  { process.stderr.write('Error: missing synth CSV\n'); process.exit(1); }
+  if (!output) { process.stderr.write('Error: missing -o / --output path\n'); process.exit(1); }
+  if (!fs.existsSync(real))  { process.stderr.write(`Error: file not found: ${real}\n`);  process.exit(1); }
+  if (!fs.existsSync(synth)) { process.stderr.write(`Error: file not found: ${synth}\n`); process.exit(1); }
+
+  if (!flags.json) {
+    process.stderr.write(`Certifying ${path.basename(real)} vs ${path.basename(synth)} …\n`);
+  }
+
+  const scriptArgs = [real, synth, '-o', output];
+  if (flags['skip-privacy'])  scriptArgs.push('--skip-privacy');
+  if (flags['n-attacks'])     scriptArgs.push('--n-attacks',   String(flags['n-attacks']));
+  if (flags['n-secrets'])     scriptArgs.push('--n-secrets',   String(flags['n-secrets']));
+  if (flags['n-atk-cap'])     scriptArgs.push('--n-atk-cap',   String(flags['n-atk-cap']));
+  if (flags['n-neighbors'])   scriptArgs.push('--n-neighbors', String(flags['n-neighbors']));
+  if (flags['n-aux-cols'])    scriptArgs.push('--n-aux-cols',  String(flags['n-aux-cols']));
+  if (flags.seed)             scriptArgs.push('--seed',        String(flags.seed));
+  if (flags.k)                scriptArgs.push('--k',           String(flags.k));
+  if (flags.theta)            scriptArgs.push('--theta',       String(flags.theta));
+  if (flags.delta)            scriptArgs.push('--delta',       String(flags.delta));
+  if (flags['mix-prob'])      scriptArgs.push('--mix-prob',    String(flags['mix-prob']));
+  if (flags['seed-gen'])      scriptArgs.push('--seed-gen',    String(flags['seed-gen']));
+  if (flags['generated-at'])  scriptArgs.push('--generated-at', flags['generated-at']);
+
+  const result = await runPythonScript(CERTIFY_PY, scriptArgs, { json: !!flags.json });
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+    return;
+  }
+
+  const elapsedS = ((result.elapsedMs || 0) / 1000).toFixed(1);
+  process.stdout.write(`✓ ${output}  (${elapsedS} s)\n`);
+}
+
 // ── sphere demo ───────────────────────────────────────────────────────────────
 
 async function cmdDemo() {
@@ -280,17 +488,35 @@ async function cmdDemo() {
   const tmpOut = path.join(os.tmpdir(), `sphere-demo-${randomUUID()}.csv`);
 
   process.stdout.write('SPHERE demo — built-in NHANES dataset (4,899 rows \xd7 18 cols)\n');
-  process.stdout.write('─'.repeat(52) + '\n\n');
+  process.stdout.write('─'.repeat(52) + '\n');
 
   try {
+    // ── Generate ──────────────────────────────────────────────────────────────
+    process.stdout.write('\n');
     await cmdGenerate([exampleCsv], { output: tmpOut });
+
+    // ── Evaluate ──────────────────────────────────────────────────────────────
+    process.stdout.write('\n');
+    process.stderr.write(`Evaluating ${path.basename(exampleCsv)} vs synthetic …\n`);
+
+    const scriptArgs = [exampleCsv, tmpOut, '--n-attacks', '200', '--n-atk-cap', '1000'];
+    const result = await runPythonScript(EVALUATE_PY, scriptArgs);
+
+    const evalS = ((result.runMs || 0) / 1000).toFixed(1);
+    process.stdout.write(`✓ Evaluation complete  (${evalS} s)\n`);
+    printEvalResults(result);
+
+  } catch (err) {
+    process.stderr.write(`\nError during demo: ${err.message}\n`);
   } finally {
     try { fs.unlinkSync(tmpOut); } catch {}
     try { fs.unlinkSync(tmpOut + '.sphere.json'); } catch {}
   }
 
-  process.stdout.write('\nTry it on your own data:\n');
-  process.stdout.write('  sphere generate your_data.csv -o synthetic.csv\n\n');
+  process.stdout.write('Try it on your own data:\n');
+  process.stdout.write('  sphere generate your_data.csv -o synthetic.csv\n');
+  process.stdout.write('  sphere evaluate your_data.csv synthetic.csv\n');
+  process.stdout.write('  sphere certify  your_data.csv synthetic.csv -o report.html\n\n');
 }
 
 // ── sphere license ────────────────────────────────────────────────────────────
@@ -299,7 +525,6 @@ async function cmdLicense(sub, pos, flags) {
   if (sub === 'activate') {
     let key = (pos[0] || flags.key || '').trim();
     if (!key) {
-      // Simple stdin prompt (no readline dependency)
       process.stdout.write('SPHERE license key (sphere_…): ');
       key = await new Promise((resolve) => {
         let buf = '';
@@ -395,9 +620,11 @@ async function main() {
 
   if (!cmd || flags.help || flags.h) {
     process.stdout.write(
-      `SPHERE CLI v${VERSION} — synthetic data generation\n\n` +
+      `SPHERE CLI v${VERSION} — synthetic data generation, evaluation & certification\n\n` +
       'Usage:\n' +
-      '  sphere generate <input.csv> -o <output.csv> [options]\n' +
+      '  sphere generate <input.csv> -o <output.csv>   [options]\n' +
+      '  sphere evaluate <real.csv>  <synth.csv>        [options]\n' +
+      '  sphere certify  <real.csv>  <synth.csv> -o <cert.html>  [options]\n' +
       '  sphere license  activate|status|clear\n' +
       '  sphere demo\n\n' +
       'Generate options:\n' +
@@ -406,6 +633,12 @@ async function main() {
       '  --delta <float>    Per-pair angle jitter (default: 5° ≈ 0.087)\n' +
       '  --mix-prob <float> Privacy/utility trade-off (default: 0.75)\n' +
       '  --seed <int>       Integer seed for reproducible output\n' +
+      '  --json             Machine-readable JSON output\n\n' +
+      'Evaluate / Certify options:\n' +
+      '  --skip-privacy     Fidelity only — skip privacy attacks (faster)\n' +
+      '  --n-attacks <int>  Attack draws per metric (default: 500)\n' +
+      '  --n-atk-cap <int>  Row subsample cap for attacks (default: 2000)\n' +
+      '  --seed <int>       RNG seed for reproducible scores\n' +
       '  --json             Machine-readable JSON output\n',
     );
     process.exit(0);
@@ -416,6 +649,16 @@ async function main() {
     return;
   }
 
+  if (cmd === 'evaluate') {
+    await cmdEvaluate(pos.slice(1), flags);
+    return;
+  }
+
+  if (cmd === 'certify') {
+    await cmdCertify(pos.slice(1), flags);
+    return;
+  }
+
   if (cmd === 'demo') {
     await cmdDemo();
     return;
@@ -426,14 +669,6 @@ async function main() {
     return;
   }
 
-  if (cmd === 'evaluate' || cmd === 'certify') {
-    process.stderr.write(
-      `'sphere ${cmd}' requires the Python evaluation engine, which is not included\n` +
-      'in this version. Coming soon.\n',
-    );
-    process.exit(1);
-  }
-
   process.stderr.write(`Unknown command: ${cmd}\nRun 'sphere --help' for usage.\n`);
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphere-cli",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "description": "SPHERE CLI — synthetic data generation, evaluation, and certification",
   "keywords": ["synthetic-data", "privacy", "cli", "data-science"],
   "homepage": "https://github.com/statzihuai/sphere-cli",
@@ -11,7 +11,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "bin": {
-    "sphere": "./bin/sphere.js"
+    "sphere": "bin/sphere.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js"
@@ -23,6 +23,9 @@
     "bin/",
     "examples/",
     "scripts/postinstall.js",
+    "scripts/evaluate.py",
+    "scripts/certify.py",
+    "sphere_cli/",
     "sphere-node.js"
   ],
   "engines": {

package/scripts/certify.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Thin subprocess wrapper — evaluate and produce an HTML certificate.
+
+Called by sphere.js as:
+  python3 <this-file> real.csv synth.csv -o cert.html [options]
+
+Streams {"progress": f, "msg": "..."} JSON lines to stderr.
+Writes {"ok": true, "output": "cert.html", "elapsedMs": N} to stdout on success,
+or {"error": "..."} on failure.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from pathlib import Path
+
+_PKG = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PKG))
+
+
+def main() -> None:
+    p = argparse.ArgumentParser()
+    p.add_argument('real')
+    p.add_argument('synth')
+    p.add_argument('-o', '--output', required=True)
+    p.add_argument('--skip-privacy',  action='store_true')
+    p.add_argument('--n-attacks',     type=int,   default=500)
+    p.add_argument('--n-secrets',     type=int,   default=5)
+    p.add_argument('--n-atk-cap',     type=int,   default=2000)
+    p.add_argument('--n-neighbors',   type=int,   default=1)
+    p.add_argument('--n-aux-cols',    type=int,   default=20)
+    p.add_argument('--seed',          type=int,   default=None)
+    # Generation provenance (optional — marks certificate as SPHERE-generated)
+    p.add_argument('--k',             type=int,   default=None)
+    p.add_argument('--theta',         type=float, default=None)
+    p.add_argument('--delta',         type=float, default=None)
+    p.add_argument('--mix-prob',      type=float, default=None)
+    p.add_argument('--seed-gen',      type=int,   default=None)
+    p.add_argument('--generated-at',  type=str,   default=None)
+    args = p.parse_args()
+
+    def on_progress(frac: float, msg: str) -> None:
+        sys.stderr.write(json.dumps({'progress': round(frac, 4), 'msg': msg}) + '\n')
+        sys.stderr.flush()
+
+    try:
+        from sphere_cli._evaluate import evaluate   # type: ignore
+        from sphere_cli._certify  import build_certificate_html  # type: ignore
+    except ImportError as e:
+        sys.stderr.write(json.dumps({'error': f'Evaluation engine not available: {e}'}) + '\n')
+        sys.exit(1)
+
+    t0 = time.perf_counter()
+
+    try:
+        result = evaluate(
+            real_path    = Path(args.real),
+            synth_path   = Path(args.synth),
+            n_attacks    = args.n_attacks,
+            n_secrets    = args.n_secrets,
+            n_atk_cap    = args.n_atk_cap,
+            n_neighbors  = args.n_neighbors,
+            n_aux_cols   = args.n_aux_cols,
+            seed         = args.seed,
+            skip_privacy = args.skip_privacy,
+            on_progress  = on_progress,
+        )
+    except ValueError as e:
+        sys.stderr.write(json.dumps({'error': str(e)}) + '\n')
+        sys.exit(1)
+    except Exception as e:
+        import traceback
+        sys.stderr.write(json.dumps({'error': f'Unexpected error: {e}\n{traceback.format_exc()}'}) + '\n')
+        sys.exit(1)
+
+    result['elapsedMs'] = int((time.perf_counter() - t0) * 1000)
+
+    # Auto-load .sphere.json sidecar written by sphere generate
+    synth_path = Path(args.synth)
+    meta: dict = {}
+    meta_path = synth_path.with_suffix('.sphere.json')
+    if meta_path.exists():
+        try:
+            meta = json.loads(meta_path.read_text(encoding='utf-8'))
+        except Exception:
+            pass
+
+    # CLI flags win; sidecar fills gaps; defaults last
+    _theta    = args.theta    if args.theta    is not None else meta.get('theta')
+    _delta    = args.delta    if args.delta    is not None else meta.get('delta')
+    _mix_prob = args.mix_prob if args.mix_prob is not None else meta.get('mix_prob')
+    _k        = args.k        if args.k        is not None else meta.get('k')
+    _seed_gen = args.seed_gen if args.seed_gen is not None else meta.get('seed')
+    _gen_at   = args.generated_at if args.generated_at is not None else meta.get('generated_at')
+
+    import math
+    gen_params = None
+    if any(x is not None for x in [_theta, _delta, _mix_prob, _k, _seed_gen, _gen_at]):
+        gen_params = {
+            'theta':    _theta    if _theta    is not None else math.pi / 6,
+            'delta':    _delta    if _delta    is not None else 5 * math.pi / 180,
+            'mix_prob': _mix_prob if _mix_prob is not None else 0.75,
+            'k':        _k        if _k        is not None else 2,
+            'seed':     _seed_gen,
+        }
+
+    try:
+        html = build_certificate_html(
+            result            = result,
+            real_path         = Path(args.real),
+            synth_path        = synth_path,
+            generation_params = gen_params,
+            generated_at      = _gen_at,
+        )
+    except Exception as e:
+        sys.stderr.write(json.dumps({'error': f'Certificate build failed: {e}'}) + '\n')
+        sys.exit(1)
+
+    out_path = Path(args.output)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(html, encoding='utf-8')
+
+    elapsed_ms = int((time.perf_counter() - t0) * 1000)
+    sys.stdout.write(json.dumps({'ok': True, 'output': str(out_path), 'elapsedMs': elapsed_ms}) + '\n')
+    sys.exit(0)
+
+
+if __name__ == '__main__':
+    main()

package/scripts/evaluate.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""Thin subprocess wrapper — evaluate a real/synthetic CSV pair.
+
+Called by sphere.js as:
+  python3 <this-file> real.csv synth.csv [options]
+
+Streams {"progress": f, "msg": "..."} JSON lines to stderr.
+Writes the final result dict as a single JSON line to stdout.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Make sphere_cli importable from the npm package root (one level up)
+_PKG = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PKG))
+
+
+def main() -> None:
+    p = argparse.ArgumentParser()
+    p.add_argument('real')
+    p.add_argument('synth')
+    p.add_argument('--skip-privacy', action='store_true')
+    p.add_argument('--n-attacks',   type=int,   default=500)
+    p.add_argument('--n-secrets',   type=int,   default=5)
+    p.add_argument('--n-atk-cap',   type=int,   default=2000)
+    p.add_argument('--n-neighbors', type=int,   default=1)
+    p.add_argument('--n-aux-cols',  type=int,   default=20)
+    p.add_argument('--seed',        type=int,   default=None)
+    args = p.parse_args()
+
+    def on_progress(frac: float, msg: str) -> None:
+        sys.stderr.write(json.dumps({'progress': round(frac, 4), 'msg': msg}) + '\n')
+        sys.stderr.flush()
+
+    try:
+        from sphere_cli._evaluate import evaluate  # type: ignore
+    except ImportError as e:
+        sys.stderr.write(json.dumps({'error': f'Evaluation engine not available: {e}'}) + '\n')
+        sys.exit(1)
+
+    try:
+        result = evaluate(
+            real_path    = Path(args.real),
+            synth_path   = Path(args.synth),
+            n_attacks    = args.n_attacks,
+            n_secrets    = args.n_secrets,
+            n_atk_cap    = args.n_atk_cap,
+            n_neighbors  = args.n_neighbors,
+            n_aux_cols   = args.n_aux_cols,
+            seed         = args.seed,
+            skip_privacy = args.skip_privacy,
+            on_progress  = on_progress,
+        )
+        sys.stdout.write(json.dumps(result) + '\n')
+        sys.exit(0)
+    except ValueError as e:
+        sys.stderr.write(json.dumps({'error': str(e)}) + '\n')
+        sys.exit(1)
+    except Exception as e:
+        import traceback
+        sys.stderr.write(json.dumps({'error': f'Unexpected error: {e}\n{traceback.format_exc()}'}) + '\n')
+        sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()