@nm-lang/cli 0.4.0 → 0.6.0

package/python/nm_jupyter/extension.py

@@ -0,0 +1,135 @@
+"""Explicit %%nm cells. This module is only needed with optional IPython.
+
+Arguments are data, client names are direct namespace lookups, and the cell is
+passed unchanged as N/M source. No Python evaluation, shell or grants are added.
+"""
+from __future__ import annotations
+
+import argparse
+import math
+import re
+import shlex
+
+from IPython.core.error import UsageError
+from IPython.core.magic import no_var_expand
+
+from nm_bridge import NMClient
+
+_COPY = {
+    "en": {
+        "arguments": "Invalid %%nm arguments. Choose --client NAME and exactly one of --check, --run or --train.",
+        "client": "--client must name an explicitly configured NMClient in this notebook's Python namespace.",
+        "training": "Training options require --train and bounded, supported values. Steps: 1-100; learning rate: (0,5]; pilot shots: 2-32; absolute error: (0,1000000].",
+        "source": "The cell must contain non-empty N/M source of at most 32768 UTF-8 bytes.",
+    },
+    "tr": {
+        "arguments": "%%nm argümanları geçersiz. --client ADI ve --check, --run veya --train seçeneklerinden tam birini seçin.",
+        "client": "--client, bu notebook'un Python ad alanında açıkça yapılandırılmış bir NMClient adı olmalıdır.",
+        "training": "Eğitim seçenekleri --train ve sınırlı, desteklenen değerler gerektirir. Adımlar: 1-100; öğrenme oranı: (0,5]; pilot ölçümler: 2-32; mutlak hata: (0,1000000].",
+        "source": "Hücre en fazla 32768 UTF-8 baytlık, boş olmayan N/M kaynak içermelidir.",
+    },
+}
+_IDENTIFIER = re.compile(r"[A-Za-z_][A-Za-z_0-9]{0,127}\Z")
+_TRAINING_FLAGS = {
+    "steps": "steps", "learning_rate": "learningRate", "optimizer": "optimizer",
+    "objective": "objective", "objective_target": "objectiveTarget", "gradient_method": "gradientMethod",
+}
+
+
+class _ArgumentsError(ValueError):
+    pass
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message):
+        raise _ArgumentsError from None
+
+
+def _parser():
+    parser = _Parser(prog="%%nm", add_help=False, allow_abbrev=False)
+    parser.add_argument("--client", required=True)
+    mode = parser.add_mutually_exclusive_group(required=True)
+    for operation in ("check", "run", "train"):
+        mode.add_argument("--" + operation, dest="operation", action="store_const", const=operation)
+    parser.add_argument("--steps", type=int)
+    parser.add_argument("--learning-rate", type=float)
+    parser.add_argument("--optimizer", choices=("gd", "momentum", "adam", "spsa", "qng"))
+    parser.add_argument("--objective", choices=("minimize", "maximize"))
+    parser.add_argument("--objective-target")
+    parser.add_argument("--gradient-method", choices=("parameter-shift", "adjoint", "auto"))
+    parser.add_argument("--measurement-allocation", choices=("fixed", "adaptive"))
+    parser.add_argument("--pilot-shots", type=int)
+    parser.add_argument("--absolute-error", type=float)
+    return parser
+
+
+def _fail(key, locale=None):
+    message = _COPY[locale][key] if locale in _COPY else _COPY["en"][key] + " / " + _COPY["tr"][key]
+    raise UsageError("NM-JUPYTER-001: " + message) from None
+
+
+def _options(args, locale):
+    options = {key: getattr(args, flag) for flag, key in _TRAINING_FLAGS.items() if getattr(args, flag) is not None}
+    allocation, pilot, error = args.measurement_allocation, args.pilot_shots, args.absolute_error
+    if (args.operation != "train" and (options or allocation is not None or pilot is not None or error is not None)
+            or args.steps is not None and not 1 <= args.steps <= 100
+            or args.learning_rate is not None and not (math.isfinite(args.learning_rate) and 0 < args.learning_rate <= 5)
+            or args.objective_target is not None and not _IDENTIFIER.fullmatch(args.objective_target)
+            or pilot is not None and (allocation != "adaptive" or not 2 <= pilot <= 32)
+            or error is not None and not (math.isfinite(error) and 0 < error <= 1_000_000)):
+        _fail("training", locale)
+    if allocation is not None:
+        options["measurementAllocation"] = {"method": allocation}
+        if pilot is not None:
+            options["measurementAllocation"]["pilotShots"] = pilot
+    if error is not None:
+        options["targetAccuracy"] = {"absoluteError": error}
+    return options or None
+
+
+class _NMCell:
+    def __init__(self, shell):
+        self.shell = shell
+
+    def __call__(self, line, cell):
+        try:
+            if not isinstance(line, str) or len(line.encode("utf-8")) > 4096:
+                raise _ArgumentsError
+            tokens = shlex.split(line, posix=True)
+            flags = [token.partition("=")[0] for token in tokens if token.startswith("--")]
+            if len(flags) != len(set(flags)):
+                raise _ArgumentsError
+            args = _parser().parse_args(tokens)
+        except (ValueError, UnicodeError):
+            _fail("arguments")
+        if not _IDENTIFIER.fullmatch(args.client):
+            _fail("client")
+        client = self.shell.user_ns.get(args.client)
+        if not isinstance(client, NMClient):
+            _fail("client")
+        options = _options(args, client.locale)
+        try:
+            if not isinstance(cell, str) or not cell.strip() or len(cell.encode("utf-8")) > 32768:
+                _fail("source", client.locale)
+        except UnicodeError:
+            _fail("source", client.locale)
+        if args.operation == "train":
+            return client.train(cell, options=options)
+        return getattr(client, args.operation)(cell)
+
+
+def load_ipython_extension(ipython):
+    # Registration changes no authority and does not invoke any client.
+    current = ipython.find_cell_magic("nm")
+    if isinstance(current, _NMCell):
+        return
+    if current is not None:
+        _fail("arguments")  # Never overwrite another extension's %%nm.
+    # IPython normally expands $names/{Python expressions} in magic arguments.
+    # Disable that before parsing so even the argument line remains plain data.
+    ipython.register_magic_function(no_var_expand(_NMCell(ipython)), magic_kind="cell", magic_name="nm")
+
+
+def unload_ipython_extension(ipython):
+    if isinstance(ipython.find_cell_magic("nm"), _NMCell):
+        del ipython.magics_manager.magics["cell"]["nm"]

package/python/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools==80.9.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nm-jupyter-adapter"
+version = "0.0.0.dev0"
+description = "Local development Python/IPython adapter for the separately installed N/M CLI"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-QuantumSoftware-NM-Free-Use"
+license-files = ["LICENSE.txt", "NOTICE.txt"]
+dependencies = []
+
+[project.optional-dependencies]
+notebook = ["ipython==9.17.1; python_version >= '3.11'"]
+
+[tool.setuptools]
+py-modules = ["nm_bridge"]
+packages = ["nm_jupyter"]
+include-package-data = false