@nm-lang/cli 0.4.0 → 0.6.0

package/dist/version.d.ts

@@ -29,7 +29,7 @@ export type NMLanguageReleaseChange = {
 };
 export declare const nmVersionManifest: {
     readonly languageVersion: "0.2.0";
-    readonly packageVersion: "0.4.0";
+    readonly packageVersion: "0.6.0";
     readonly irVersion: "0.1";
     readonly qasm3SidecarVersion: "0.3";
     readonly learningPackageVersion: "0.1";

package/dist/version.js

@@ -2,7 +2,7 @@ export const NM_LANGUAGE_PREVIEW_READINESS_FORMAT = "nm-language-preview-readine
 export const NM_LANGUAGE_PREVIEW_READINESS_VERSION = "0.1";
 export const nmVersionManifest = {
     languageVersion: "0.2.0",
-    packageVersion: "0.4.0",
+    packageVersion: "0.6.0",
     irVersion: "0.1",
     qasm3SidecarVersion: "0.3",
     learningPackageVersion: "0.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nm-lang/cli",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Command-line tools for formatting, linting, testing, workspace snapshots, execution, and exports for N/M quantum programs.",
   "repository": {
@@ -36,6 +36,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./project-create": {
+      "types": "./bin/project-create.d.mts",
+      "import": "./bin/project-create.mjs"
     }
   },
   "bin": {
@@ -44,11 +48,12 @@
   "files": [
     "bin",
     "dist",
+    "python",
     "LICENSE.txt",
     "NOTICE.txt"
   ],
   "dependencies": {
-    "@nm-lang/core": "0.4.0",
+    "@nm-lang/core": "0.6.0",
     "jiti": "^2.7.0"
   },
   "scripts": {

package/python/LICENSE.txt

@@ -0,0 +1,57 @@
+QuantumSoftware N/M npm Packages — Free Use License
+Version 1.0, 5 October 2026
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+
+1. Scope
+This license covers QuantumSoftware-owned code and assets in the official
+@nm-lang/core, @nm-lang/cli, @nm-lang/language-server and @nm-lang/mcp npm
+packages. It does not license the rest of the repository or the separately
+distributed VS Code extension. Third-party components remain subject to their
+respective licenses; their notices and permissions take precedence for those
+components.
+
+2. Free use
+You may download, install and use these official packages without charge for
+personal, educational and commercial purposes, import their APIs into your own
+programs, and make backup copies for your own use. QuantumSoftware authorizes
+distribution of its official packages through the nm-lang organization on the
+npm registry, including the registry's normal delivery and package-manager
+installation and caching mechanisms.
+
+3. Reserved rights
+This is not an open-source license. Except for the permissions above, rights
+to QuantumSoftware-owned code and assets are reserved. Modification,
+redistribution, sublicensing, sale or publication of that code or those assets
+requires separate permission from the rights holders, unless applicable law
+provides otherwise. Do not remove copyright or license notices. These
+restrictions do not override rights granted by any third-party license.
+
+4. Your programs
+This license imposes no restrictions on N/M programs you write, their source
+code, or simulation results produced using these packages. It does not
+transfer ownership of your work to QuantumSoftware. This clause does not grant
+additional redistribution rights to QuantumSoftware-owned runtime code bundled
+with your application; those rights are governed by sections 2 and 3.
+
+5. No warranty
+THE PACKAGES ARE PROVIDED "AS IS", WITHOUT WARRANTIES OF ANY KIND, TO THE
+EXTENT PERMITTED BY APPLICABLE LAW. TO THAT SAME EXTENT, THE RIGHTS HOLDERS
+ARE NOT LIABLE FOR DAMAGES ARISING FROM USE OF THE PACKAGES. RIGHTS THAT
+CANNOT BE EXCLUDED UNDER APPLICABLE LAW ARE NOT AFFECTED.
+
+6. Permission requests
+For additional permissions, contact the publisher through:
+https://quantumsoftware.tech/en/#contact
+
+Türkçe açıklama
+Resmî dört npm paketi kişisel, eğitim ve ticari amaçlarla ücretsiz kurulup
+kullanılabilir; API'leri kendi programlarınızdan çağırabilir ve kendi kullanımınız
+için yedek kopya alabilirsiniz. Bu bir açık kaynak lisansı değildir.
+QuantumSoftware'a ait kod ve varlıkları değiştirmek veya yeniden dağıtmak için
+ayrıca izin gerekir. Paketleri indirilebilir kılmak, kaynak kodu üzerinde açık
+kaynak hakları vermez. Üçüncü taraf lisanslarının ve yürürlükteki hukukun verdiği
+haklar korunur. Yazdığınız N/M programları ve ürettiğiniz sonuçların mülkiyeti
+size aittir. Uygulamanızla birlikte dağıtacağınız QuantumSoftware çalışma zamanı
+dosyaları için yukarıdaki izin ve kısıtlamalar geçerlidir. Yukarıdaki İngilizce
+metin lisansın koşullarını belirler.

package/python/NOTICE.txt

@@ -0,0 +1,11 @@
+QuantumSoftware N/M package notices
+
+Copyright (c) 2026 QuantumSoftware.tech contributors. All rights reserved.
+QuantumSoftware-owned code is licensed under LICENSE.txt.
+
+Runtime dependencies listed in package.json are installed separately by npm.
+Their own licenses and notices remain applicable. The QuantumSoftware license
+does not restrict the rights granted for those third-party components.
+
+jiti 2.x is a separately installed runtime dependency licensed under MIT.
+Its original LICENSE is included in the jiti package.

package/python/README.md

@@ -0,0 +1,174 @@
+# N/M Python/Jupyter adapter / adaptörü
+
+This source tree adds a **local development wheel**, `nm-jupyter-adapter==0.0.0.dev0`,
+over the stdlib bridge included in `@nm-lang/cli`. This is not a PyPI release or
+an npm/VSIX version change. Install Node and a trusted N/M CLI separately; the
+wheel contains only the adapter, optional extension and usage/license metadata.
+Source-code rights remain reserved under the unchanged LICENSE.txt and NOTICE.txt.
+
+Bu kaynak ağacı, `@nm-lang/cli` içindeki standart kütüphane köprüsünü
+`nm-jupyter-adapter==0.0.0.dev0` **yerel geliştirme wheel'i** olarak kurmayı sağlar.
+PyPI yayını veya npm/VSIX sürüm değişikliği değildir. Node ve güvenilir N/M CLI
+ayrıca kurulur. Wheel yalnız adaptörü, isteğe bağlı uzantıyı ve kullanım/lisans
+metaverisini içerir. LICENSE.txt ve NOTICE.txt değişmeden korunur; kaynak hakları saklıdır.
+
+## Installation / Kurulum
+
+From the repository root, create disposable environments; nothing is installed
+into global Python. / Depo kökünde geçici ortamlar oluşturun; global Python'a
+kurulum yapılmaz.
+
+```powershell
+py -m venv .qa/python-adapter/tools
+.qa/python-adapter/tools/Scripts/python.exe -m pip install -r tests/python/requirements-adapter-build.txt
+.qa/python-adapter/tools/Scripts/python.exe -B scripts/build-nm-python-adapter.py
+py -m venv .qa/python-adapter/notebook
+.qa/python-adapter/notebook/Scripts/python.exe -m pip install --no-index --no-deps .qa/python-adapter/dist/nm_jupyter_adapter-0.0.0.dev0-py3-none-any.whl
+# Optional IPython/Jupyter; Python 3.11+ / İsteğe bağlı IPython/Jupyter; Python 3.11+
+.qa/python-adapter/notebook/Scripts/python.exe -m pip install -r tests/python/requirements-notebook.txt
+```
+
+On Unix, use `python3` and `bin/python` instead of `py` and `Scripts/python.exe`.
+The stdlib adapter and legacy imports support Python 3.10+. The pinned optional
+IPython 9.17.1 notebook environment requires Python 3.11+; installing the
+`notebook` extra on Python 3.10 does not install IPython. No global kernel is registered.
+Unix'te `python3` ve `bin/python` kullanın. Standart kütüphane adaptörü Python
+3.10+ destekler; sabitlenmiş IPython 9.17.1 notebook ortamı Python 3.11+ gerektirir.
+Python 3.10'da `notebook` ek bağımlılığı IPython kurmaz. Global kernel kaydı yapılmaz.
+
+## Explicit CLI selection / Açık CLI seçimi
+
+```python
+from pathlib import Path
+from nm_bridge import NMClient, NMResult  # Legacy import stays valid / Eski import korunur.
+
+# Select an existing trusted CLI script; replace this example absolute path.
+# Mevcut güvenilir CLI dosyanızı seçin; örnek mutlak yolu değiştirin.
+client = NMClient(cli_path=Path("C:/trusted/nm-cli/bin/nm.mjs"), locale="tr",
+                  experimental=("hamiltonianEvolution", "measurementGrouping"), timeout=30)
+record = client.train(source, options={"steps": 2, "targetAccuracy": {"absoluteError": 0.5}})
+record  # Escaped Jupyter table / Kaçışlanmış Jupyter tablosu
+restored = NMResult.from_json(record.to_json())  # Data only / Yalnız veri
+```
+
+Standalone wheel clients require `cli_path=` or the existing trusted `command=`
+argument sequence. `cli_path` must resolve to an existing absolute file and is
+mutually exclusive with `command`. No PATH/cwd search for the N/M CLI occurs.
+Inside the original npm `python/` layout, `NMClient()` still selects the adjacent
+`../bin/nm.mjs`; adding that `python/` directory to `sys.path` remains supported.
+`from nm_jupyter import NMClient, NMResult` exposes the same classes.
+The npm default verifies the physical module origin, the parent `package.json`
+identity (`@nm-lang/cli` and its `nm` entry), and local Python distribution
+metadata. Wheel/RECORD ownership or incomplete/ambiguous markers require explicit
+CLI selection even when the wheel target directory happens to be named `python`.
+
+Bağımsız wheel, açık `cli_path=` veya mevcut güvenilir `command=` dizisi gerektirir.
+`cli_path`, mevcut bir mutlak dosyaya çözülmelidir ve `command` ile birlikte
+verilemez. N/M CLI için PATH/çalışma dizini araması yapılmaz. npm paketinin özgün
+`python/` diziliminde `NMClient()` komşu `../bin/nm.mjs` dosyasını kullanmaya devam
+eder; bu dizini `sys.path` içine eklemek desteklenir. `nm_jupyter` aynı sınıfları dışa aktarır.
+npm varsayılanı gerçek modül konumunu, üst `package.json` kimliğini ve yerel Python
+dağıtım metaverisini doğrular. Wheel/RECORD sahipliği veya eksik/belirsiz işaretler,
+kurulum hedefinin adı `python` olsa bile açık CLI seçimi gerektirir.
+
+Default Node lookup accepts only absolute PATH directories outside the working
+directory and resolves an absolute executable. Empty/relative entries and cwd
+aliases are skipped on every supported Python version. Missing Node raises
+`NM-PY-011`; no bare-name fallback is used. Missing/invalid CLI selection raises
+`NM-PY-012`. Explicit `command=` remains trusted caller input, unchanged and passed
+with `shell=False`; trust its executable and arguments yourself.
+
+Varsayılan Node araması yalnız çalışma dizini dışındaki mutlak PATH dizinlerini
+kullanır. Boş/göreli girdiler ve çalışma dizinine çözülen yollar atlanır. Node
+bulunamazsa `NM-PY-011`, CLI seçimi eksik/geçersizse `NM-PY-012` verilir.
+Yalın program adı fallback'i yoktur. Açık `command=` değiştirilmeden `shell=False`
+ile kullanılır; program ve argümanların güvenilirliğini çağıran sağlar.
+
+## Optional explicit cells / İsteğe bağlı açık hücreler
+
+```python
+%load_ext nm_jupyter
+```
+
+```text
+%%nm --client client --check
+module notebook_check;
+fn main(){let q=qreg[1];H(q[0]);return q;}
+```
+
+Use `--run` for simulation or `--train` for training; exactly one mode and an
+existing Python variable naming an explicitly configured `NMClient` are required
+on every cell. Names are direct identifier lookups, not Python expressions.
+Import/load/save/display never invokes a client. Execution occurs only when you
+explicitly run a cell or call the Python API. `%unload_ext nm_jupyter` removes the magic.
+
+Simülasyon için `--run`, eğitim için `--train` seçin. Her hücre tam bir mod ve
+açıkça yapılandırılmış bir `NMClient` Python değişkeni gerektirir. Adlar doğrudan
+aranır; Python ifadesi değildir. Import/uzantı yükleme/kaydetme/gösterim CLI çağırmaz.
+Yürütme yalnız hücreyi veya Python API'yi açıkça çalıştırınca olur.
+
+```text
+%%nm --client client --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9
+module notebook_training;
+@seed(27);
+@shots_budget(4096);
+param theta:Angle=0;
+fn main(){
+ let q=qreg[1];
+ observable Hamiltonian=theta*X(q[0])+0.25*theta*I;
+ evolve Hamiltonian for 0.4 steps 1 order 1 on q;
+ let energy=expect Y(q[0])+0.5*Z(q[0]);
+ return q;
+}
+```
+
+The cell returns `NMResult`; in the next Python cell, use `record = _` to retain it.
+Options omitted from the magic remain absent, preserving source training defaults.
+Training flags are accepted only with `--train`. Steps: 1–100; learning rate:
+finite `(0,5]`; adaptive pilot shots: 2–32; absolute error: finite `(0,1000000]`.
+No shot override or feature grant is accepted in the magic. See the full guide
+for the enum choices. Nested SPSA/QNG tuning remains in `NMClient.train(options=...)`.
+
+Hücre `NMResult` döndürür; sonraki Python hücresinde `record = _` ile saklayın.
+Verilmeyen eğitim seçenekleri eklenmez; kaynağın varsayılanları korunur. Eğitim
+bayrakları yalnız `--train` ile geçerlidir. Adım 1–100, öğrenme oranı sonlu `(0,5]`,
+adaptif pilot ölçüm 2–32, mutlak hata sonlu `(0,1000000]` olur. Hücreye ölçüm sayısı
+override'ı veya özellik izni eklenmez. İç SPSA/QNG ayarları Python API'sinde kalır.
+
+## Limits and records / Sınırlar ve kayıtlar
+
+The bridge v1 limits remain: 32 KiB source, 256 KiB request, 4 MiB response,
+64 KiB stderr, request/result JSON depth 32/64, 14 qubits, 8 training parameters,
+100 steps, one inclusive shot budget up to 4096 and a 0.1–60 second deadline.
+Pipe I/O and EOF share the deadline; no I/O threads survive a call. Windows
+Python 3.10/3.11 retains the stdlib Win32 compatibility path. Cancellation kills
+the direct process and yields `NM-PY-009`; this is not a process-tree sandbox.
+
+Köprü v1 sınırları korunur: 32 KiB kaynak, 256 KiB istek, 4 MiB yanıt, 64 KiB stderr,
+32/64 JSON derinliği, 14 kübit, 8 parametre, 100 adım, pilotlar dahil en fazla
+4096 ölçüm ve 0.1–60 saniye süre. Giriş/çıkış ve EOF aynı süreye bağlıdır; I/O iş
+parçacığı kalmaz. Windows Python 3.10/3.11 desteği korunur. İptal doğrudan süreci
+sonlandırıp `NM-PY-009` verir; süreç ağacı sandbox'ı değildir.
+
+Saved JSON is data and grants no permission. Replay with
+`client.execute(restored.request)` needs independent caller permissions. Compact
+saving preserves wire number spellings; pretty output exceeding 4 MiB is rejected.
+Source snapshots are not checkpoints. Confidence and precision targets do not
+certify convergence, an optimum or hardware accuracy. Required-shot estimates
+are informational final-cost estimates, exclude pilots and never take extra shots.
+Source, options, shot accounting and confidence assumptions remain in the record;
+all user text in the rich table is HTML escaped.
+
+Kaydedilmiş JSON veridir; izin vermez. Yeniden yürütme bağımsız çağıran yetkisi
+gerektirir. Kompakt kayıt özgün sayı gösterimini korur; 4 MiB'ı aşan girintili çıktı
+reddedilir. Kaynak checkpoint, hassasiyet hedefi yakınsama/optimum/donanım belgesi
+değildir. Ölçüm tahmini bilgi amaçlıdır; pilotları içermez ve ek ölçüm almaz.
+Özgün kaynak, seçenekler ve ölçüm/güven varsayımları kayıtta kalır; tablo metni kaçışlanır.
+
+`examples/magic.ipynb` is an unexecuted TR/EN explicit-cell example. It is included
+with the npm source layout, not bundled into the minimal wheel. The existing
+`examples/training.ipynb` and legacy Python bridge API remain usable.
+
+Full guide / Tam rehber: `docs/NM_PYTHON_JUPYTER_ADAPTER_GUIDE.md`.
+Protocol and precision details / Protokol ve hassasiyet:
+`docs/NM_PYTHON_JUPYTER_BRIDGE_GUIDE.md`.

package/python/examples/magic.ipynb

@@ -0,0 +1,98 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {"kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"}, "language_info": {"name": "python"}},
+ "cells": [
+  {"cell_type": "markdown", "id": "scope", "metadata": {}, "source": [
+   "# Explicit N/M cells / Açık N/M hücreleri\n",
+   "Local development adapter; not a PyPI release. / Yerel geliştirme adaptörü; PyPI yayını değildir.\n",
+   "Install the local wheel and optional Python 3.11+ IPython/kernel requirements first. / Önce yerel wheel ve isteğe bağlı Python 3.11+ IPython/kernel gereksinimlerini kurun.\n",
+   "Select an existing trusted absolute CLI file by explicitly setting NM_ADAPTER_CLI_PATH before running this setup cell. The adapter does not discover it. / Setup hücresinden önce NM_ADAPTER_CLI_PATH ile güvenilir mutlak CLI dosyasını açıkça seçin.\n",
+   "Opening or saving this notebook does not execute it. Outputs are not pre-executed or saved. / Notebook'u açmak veya kaydetmek yürütme başlatmaz; önceden çalıştırılmış çıktı yoktur."
+  ]},
+  {"cell_type": "code", "id": "setup", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "import os\n",
+   "from pathlib import Path\n",
+   "from nm_bridge import NMClient, NMResult\n",
+   "cli_path = Path(os.environ['NM_ADAPTER_CLI_PATH'])  # Explicit trusted user/test selection / Açık güvenilir seçim\n",
+   "features = ('hamiltonianEvolution', 'measurementGrouping')\n",
+   "client_en = NMClient(cli_path=cli_path, locale='en', experimental=features)\n",
+   "client_tr = NMClient(cli_path=cli_path, locale='tr', experimental=features)\n",
+   "%load_ext nm_jupyter"
+  ]},
+  {"cell_type": "code", "id": "check-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --check\n",
+   "module magic_check;\n",
+   "fn main(){let q=qreg[1];H(q[0]);return q;}\n",
+   "// İı çğ üş 😀 <script>source is data</script> $literal {literal}"
+  ]},
+  {"cell_type": "code", "id": "retain-check-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["checked_en = _\n", "assert checked_en.success, checked_en.to_json()"]},
+  {"cell_type": "code", "id": "run-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --run\n",
+   "module magic_run;\n",
+   "@seed(17);\n",
+   "fn main(){let q=qreg[1];H(q[0]);let cost=expect Z(q[0]);return cost;}\n",
+   "// İı çğ üş 😀 <script>source is data</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-run-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["ran_en = _\n", "assert ran_en.success, ran_en.to_json()"]},
+  {"cell_type": "code", "id": "train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_en --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9\n",
+   "module magic_training;\n",
+   "@seed(27);\n",
+   "@shots_budget(4096);\n",
+   "param theta:Angle=0;\n",
+   "fn main(){\n",
+   " let q=qreg[1];\n",
+   " observable Hamiltonian=theta*X(q[0])+0.25*theta*I;\n",
+   " evolve Hamiltonian for 0.4 steps 1 order 1 on q;\n",
+   " let energy=expect Y(q[0])+0.5*Z(q[0]);\n",
+   " return q;\n",
+   "}\n",
+   "// İı çğ üş 😀 <script>source is data</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": ["trained_en = _\n", "assert trained_en.success, trained_en.to_json()"]},
+  {"cell_type": "code", "id": "check-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --check\n",
+   "module magic_kontrol;\n",
+   "@dil(\"tr\");\n",
+   "fn main(){let q=qreg[1];H(q[0]);return q;}\n",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-check-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": ["checked_tr = _\n", "assert checked_tr.success, checked_tr.to_json()"]},
+  {"cell_type": "code", "id": "run-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --run\n",
+   "module magic_yurutme;\n",
+   "@dil(\"tr\");\n",
+   "@seed(17);\n",
+   "fn main(){let q=qreg[1];H(q[0]);let cost=expect Z(q[0]);return cost;}\n",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retain-run-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": ["ran_tr = _\n", "assert ran_tr.success, ran_tr.to_json()"]},
+  {"cell_type": "code", "id": "train-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "%%nm --client client_tr --train --steps 2 --learning-rate 0.17 --optimizer adam --objective minimize --objective-target energy --gradient-method parameter-shift --measurement-allocation adaptive --pilot-shots 8 --absolute-error 1e-9\n",
+   "module magic_egitimi;\n",
+   "@dil(\"tr\");\n",
+   "@seed(27);\n",
+   "@shots_budget(4096);\n",
+   "param theta:Angle=0;\n",
+   "fn main(){\n",
+   " let q=qreg[1];\n",
+   " observable Hamiltonian=theta*X(q[0])+0.25*theta*I;\n",
+   " evolve Hamiltonian for 0.4 adımlar 1 order 1 on q;\n",
+   " let energy=expect Y(q[0])+0.5*Z(q[0]);\n",
+   " return q;\n",
+   "}\n",
+   "// İı çğ üş 😀 <script>kaynak veridir</script>"
+  ]},
+  {"cell_type": "code", "id": "retained-records", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "trained_tr = _\n",
+   "assert trained_tr.success, trained_tr.to_json()\n",
+   "assert trained_tr.result == trained_en.result\n",
+   "restored = NMResult.from_json(trained_en.to_json())\n",
+   "assert restored.record == trained_en.record\n",
+   "denied = NMClient(cli_path=cli_path).execute(restored.request)\n",
+   "assert not denied.success and denied.record['error']['code'] == 'NM-PY-003'\n",
+   "# Replay needs a separate explicit API call with client permissions. / Yeniden yürütme ayrıca izinli API çağrısı gerektirir."
+  ]}
+ ]
+}

package/python/examples/training.ipynb

@@ -0,0 +1,78 @@
+{
+ "nbformat": 4,
+ "nbformat_minor": 5,
+ "metadata": {
+  "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+  "language_info": {"name": "python"}
+ },
+ "cells": [
+  {"cell_type": "markdown", "id": "scope", "metadata": {}, "source": [
+   "# N/M Python/Jupyter — CLI 0.5.0 / CLI bridge\n",
+   "Henüz yayımlanmadı. Önce bu dalın CLI'sini derleyin; Python 3.10+ ve Node gerekir. / Not published. Build the branch CLI first; Python 3.10+ and Node are required.\n",
+   "Her eğitim toplam 4096 ölçüm kullanır; pilotlar dahildir. Hedef hassasiyet yakınsama belgesi değildir. / Each training call uses 4096 total shots including pilots. Precision is not a convergence certificate.\n",
+   "Çıktılar önceden çalıştırılıp kaydedilmedi. / Outputs have not been pre-executed or saved."
+  ]},
+  {"cell_type": "code", "id": "setup", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "import os, sys\n",
+   "from pathlib import Path\n",
+   "# Explicit library location override / Açık kütüphane dizini seçimi\n",
+   "candidates = [Path(os.environ['NM_BRIDGE_PYTHON_PATH'])] if 'NM_BRIDGE_PYTHON_PATH' in os.environ else [Path.cwd(), Path.cwd().parent, Path.cwd() / 'packages/nm-cli/python']\n",
+   "adapter_dir = next((p.resolve() for p in candidates if (p / 'nm_bridge.py').is_file()), None)\n",
+   "assert adapter_dir is not None, 'Set NM_BRIDGE_PYTHON_PATH to the CLI python directory / CLI python dizinini belirtin'\n",
+   "sys.path.insert(0, str(adapter_dir))\n",
+   "from nm_bridge import NMClient, NMResult\n",
+   "features = ('hamiltonianEvolution', 'measurementGrouping')\n",
+   "options = {'steps': 2, 'learningRate': 0.17, 'optimizer': 'adam', 'objective': 'minimize', 'objectiveTarget': 'energy', 'gradientMethod': 'parameter-shift', 'measurementAllocation': {'method': 'adaptive', 'pilotShots': 8}, 'targetAccuracy': {'absoluteError': 1e-9}}"
+  ]},
+  {"cell_type": "markdown", "id": "turkish", "metadata": {}, "source": [
+   "## Türkçe\n",
+   "İzinleri çağıran açıkça seçer. Kaynak, seçenekler, grup tohumları ve güven aralıkları tam kayıtta korunur. / Caller permissions are explicit; source, options, group seeds and confidence bounds are retained."
+  ]},
+  {"cell_type": "code", "id": "train-tr", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "source_tr = '''module notebook_egitimi;\n",
+   "@dil(\"tr\");\n",
+   "@seed(27);\n",
+   "@shots_budget(4096);\n",
+   "param theta:Angle=0;\n",
+   "fn main(){\n",
+   "  let q=qreg[1];\n",
+   "  observable Hamiltonian=theta*X(q[0])+0.25*theta*I;\n",
+   "  evolve Hamiltonian for 0.4 adımlar 1 order 1 on q;\n",
+   "  let energy=expect Y(q[0])+0.5*Z(q[0]);\n",
+   "  return q;\n",
+   "}\n",
+   "// Özgün kaynak: İı çğ üş 😀 <script>source is data</script>\n",
+   "'''\n",
+   "record_tr = NMClient(experimental=features, locale='tr').train(source_tr, options=options)\n",
+   "assert record_tr.success, record_tr.to_json()\n",
+   "assert record_tr.result['groupedMeasurements']['usedShots'] == 4096\n",
+   "assert record_tr.result['groupedMeasurements']['targetAccuracy']['status'] == 'not-met'\n",
+   "record_tr"
+  ]},
+  {"cell_type": "markdown", "id": "english", "metadata": {}, "source": [
+   "## English\n",
+   "The same options and one inclusive budget apply. Held-out estimates do not reuse pilots. No source string becomes executable HTML."
+  ]},
+  {"cell_type": "code", "id": "train-en", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "source_en = source_tr.replace('@dil(\"tr\");\\n', '').replace('notebook_egitimi', 'notebook_training').replace('adımlar 1', 'steps 1')\n",
+   "client_en = NMClient(experimental=features, locale='en')\n",
+   "record_en = client_en.train(source_en, options=options)\n",
+   "assert record_en.success, record_en.to_json()\n",
+   "evidence = record_en.result['groupedMeasurements']\n",
+   "assert evidence['usedShots'] == evidence['adaptive']['pilotUsedShots'] + evidence['adaptive']['estimationUsedShots'] == 4096\n",
+   "assert evidence['targetAccuracy']['finalCost'] == evidence['costs'][-1]\n",
+   "record_en"
+  ]},
+  {"cell_type": "code", "id": "data-only-replay", "metadata": {}, "execution_count": null, "outputs": [], "source": [
+   "restored = NMResult.from_json(record_en.to_json())\n",
+   "assert restored.record == record_en.record\n",
+   "assert restored.request['source'] == source_en\n",
+   "# Deserialization grants no permission / Kaydı okumak izin vermez.\n",
+   "denied = NMClient(locale='en').execute(restored.request)\n",
+   "assert not denied.success and denied.record['error']['code'] == 'NM-PY-003'\n",
+   "replayed = client_en.execute(restored.request)\n",
+   "assert replayed.result == record_en.result\n",
+   "print('Round-trip + independent replay permissions verified / Kayıt ve bağımsız yeniden yürütme izinleri doğrulandı')"
+  ]}
+ ]
+}