v2: real 'superesp' console command (editable + wheel), install-safe export path, version 2.0.0, consistent CLI messages

Atome LM Team · Atome LM Team · commit c9a81884af4e · 2026-06-29T19:25:02.000Z
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "atome-llm"
-version = "0.3.0"
+version = "2.0.0"
 description = "Atome LM — a tiny ternary language model designed for microcontroller deployment via the Atome C99 inference engine."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -29,11 +29,19 @@ dependencies = [
 Homepage = "https://atomelm.com"
 Demo = "https://atomelm.com/demo.html"
 
+[project.scripts]
+superesp = "superesp.cli:main"
+
 [project.optional-dependencies]
 dev = ["pytest>=7", "cryptography>=41", "scipy>=1.10"]
 # SuperESP (v2) runtime extras: Ed25519 attestation + audio/voice feature extraction
 # (+ pyserial for on-device log capture). Install with: pip install -e ".[superesp]"
 superesp = ["cryptography>=41", "scipy>=1.10", "pyserial>=3.5", "esptool>=4.7"]
 
 [tool.setuptools.packages.find]
-include = ["atome_llm*"]
+include = ["atome_llm*", "superesp*"]
+
+# Ship the read-only data a fresh install needs (signed head blobs, zoo registry,
+# prebuilt firmware). Training/firmware-build still expect a source checkout.
+[tool.setuptools.package-data]
+"superesp" = ["artifacts/*", "artifacts/reports/*", "esp32/prebuilt/**", "zoo/*.json", "zoo/*.html"]
diff --git a/superesp/cli.py b/superesp/cli.py
@@ -1,9 +1,12 @@
 """superesp.cli — one-command reproduction of SuperESP applications.
 
-    python3 -m superesp.cli list
-    python3 -m superesp.cli train  <head>          # a built-in head
-    python3 -m superesp.cli train  --csv my.csv --label-col state --name mysensor
-    python3 -m superesp.cli flashplan <name>        # how to bake the blob into firmware
+After `pip install -e .` the `superesp` command is available (or use
+`python3 -m superesp.cli` without installing):
+
+    superesp list
+    superesp train  <head>          # a built-in head
+    superesp train  --csv my.csv --label-col state --name mysensor
+    superesp flashplan <name>        # how to bake the blob into firmware
 
 `train` does the whole pipeline: split (leak-free) -> train tiny ternary head ->
 held-out eval + abstention + novelty -> export ATOMECL01 -> Ed25519 attestation,
@@ -33,7 +36,7 @@ def _load(args):
         return load_csv(args.csv, label_col=args.label_col, name=args.name)
     from superesp.heads import BY_NAME
     if args.head not in BY_NAME:
-        raise SystemExit(f"unknown head {args.head!r}; see `cli list`")
+        raise SystemExit(f"unknown head {args.head!r}; see `superesp list`")
     return BY_NAME[args.head].loader(seed=0)
 
 
@@ -42,7 +45,7 @@ def cmd_list(_):
     print("Built-in SuperESP heads:")
     for h in HEADS:
         print(f"  {h.name:11s} — {h.blurb}")
-    print("\nOr bring your own:  cli train --csv data.csv --label-col <col> --name <name>")
+    print("\nOr bring your own:  superesp train --csv data.csv --label-col <col> --name <name>")
 
 
 def cmd_train(args):
@@ -67,7 +70,7 @@ def cmd_train(args):
     sign.save_attestation(att, ART / f"{name}.att.json")
     ok, _ = sign.verify(blob, att)
     print(f"  exported {st['total_bytes']} B -> {blob.name}; attestation verify={'OK' if ok else 'FAIL'}")
-    print(f"  next: python3 -m superesp.cli flashplan {name}")
+    print(f"  next: superesp flashplan {name}")
 
 
 def cmd_targets(_):
diff --git a/superesp/framework/export.py b/superesp/framework/export.py
@@ -16,20 +16,38 @@
 import sys
 from pathlib import Path
 
-_REPO = Path(__file__).resolve().parents[2]
-sys.path.insert(0, str(_REPO))
-
-# Load scripts/export_to_atome.py as a module to reuse its writers.
-_spec = importlib.util.spec_from_file_location(
-    "_atome_export", _REPO / "scripts" / "export_to_atome.py"
-)
-_exp = importlib.util.module_from_spec(_spec)
-_spec.loader.exec_module(_exp)
-
-write_ternary = _exp.write_ternary
-write_conv = _exp.write_conv
-write_norm = _exp.write_norm
-write_ssm = _exp.write_ssm
+def _find_export_script() -> Path | None:
+    """Locate scripts/export_to_atome.py by walking up from this file.
+
+    Works from a source checkout or an editable install (files stay in place).
+    A non-editable wheel install has no scripts/ dir; in that case exporting a
+    new blob needs a source checkout, so we defer a clear error to call time
+    rather than crashing at import (read-only commands stay usable).
+    """
+    for base in Path(__file__).resolve().parents:
+        cand = base / "scripts" / "export_to_atome.py"
+        if cand.exists():
+            sys.path.insert(0, str(base))
+            return cand
+    return None
+
+_SCRIPT = _find_export_script()
+if _SCRIPT is not None:
+    _spec = importlib.util.spec_from_file_location("_atome_export", _SCRIPT)
+    _exp = importlib.util.module_from_spec(_spec)
+    _spec.loader.exec_module(_exp)
+    write_ternary = _exp.write_ternary
+    write_conv = _exp.write_conv
+    write_norm = _exp.write_norm
+    write_ssm = _exp.write_ssm
+else:
+    def _need_checkout(*_a, **_k):
+        raise RuntimeError(
+            "Exporting a blob needs the Atome source tree (scripts/export_to_atome.py).\n"
+            "Install from a checkout:  git clone …/atome-lm && pip install -e .\n"
+            "(A plain wheel install can run read-only commands but not train/export.)"
+        )
+    write_ternary = write_conv = write_norm = write_ssm = _need_checkout
 
 MAGIC = b"ATOMECL01"
 
