Spotlight VM: the model and the programs from the post

LICENSE.md

@@ -0,0 +1,248 @@
+# License
+
+Spotlight VM is licensed under the Apache License, Version 2.0.
+
+```text
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Percepta
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+```
+
+## Third-party components
+
+These parts remain under their own licenses.
+
+### MicroPython v1.28.0 (`memory/core.safetensors`)
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2013-2026 Damien P. George
+
+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.
+```
+
+### sortedcontainers 2.4.0 (`memory/sortedcontainers.safetensors`)
+
+```
+Copyright 2014-2019 Grant Jenks
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
+
+### MNIST (`memory/mnist.safetensors`)
+
+The network was trained on the MNIST database of handwritten digits by Yann LeCun, Corinna Cortes and Christopher J. C. Burges.

README.md

@@ -0,0 +1,39 @@
+---
+license: apache-2.0
+library_name: transformers
+---
+
+# Spotlight VM
+
+A small, hand-constructed [Spotlight](https://percepta.ai/blog/spotlight-memory) transformer that runs Python:
+the examples from [Growing Intelligence Beyond the Weights](https://percepta.ai/blog/growing-intelligence-beyond-the-weights).
+`intelligence/` holds the weights (under 100K parameters), which never change. `memory/` holds MicroPython
+v1.28.0 (`core.safetensors`) and two packages.
+
+```sh
+cc -O3 -std=c99 spotlight.c -lm -o spotlight
+./spotlight < examples/euler1.py            # 233168; -v also prints every generated token
+cat examples/tax_brackets/*.py | ./spotlight
+```
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained("percepta-ai/spotlight-vm", trust_remote_code=True)
+tokenizer = AutoTokenizer.from_pretrained("percepta-ai/spotlight-vm", trust_remote_code=True)
+output = model.generate(**tokenizer("print(1 + 2)\n", return_tensors="pt"))
+print(tokenizer.decode(output[0]))  # 3
+```
+
+In a local copy of this folder, `from_pretrained(".")` works the same way.
+
+| Example | In the post | Output |
+|---|---|---|
+| `examples/euler1.py`, `euler2.py`, `euler3.py` | Project Euler problems 1 to 3 | `233168`, `4613732`, `6857` |
+| `examples/memory_loader.py` | Loading memory selectively | `4` |
+| `examples/tax_brackets/` | Acquiring and updating knowledge | `$17400`, then `$16914` |
+| `examples/mnist_digit.py` | Growing capabilities and intelligence | `7` |
+
+It runs on one CPU core at about 120K tokens per second: minutes for the Project Euler examples,
+about half an hour for MNIST (245M tokens). This MicroPython build has no floating point. License: Apache 2.0,
+see [LICENSE.md](LICENSE.md).

config.json

@@ -0,0 +1 @@
+{"model_type":"spotlight","architectures":["SpotlightForCausalLM"],"auto_map":{"AutoConfig":"spotlight.SpotlightConfig","AutoModelForCausalLM":"spotlight.SpotlightForCausalLM","AutoTokenizer":["spotlight.SpotlightTokenizer",null]}}

examples/euler1.py

@@ -0,0 +1,12 @@
+# https://projecteuler.net/problem=1
+# Sum the multiples of 3 or 5 below 1000.
+# Memory allocation within the program translates to Spotlight Memory
+def euler1(limit=1000):
+    marked = bytearray(limit)
+    for n in range(0, limit, 3):
+        marked[n] = 1
+    for n in range(0, limit, 5):
+        marked[n] = 1
+    return sum(n for n in range(limit) if marked[n])
+
+print(euler1())

examples/euler2.py

@@ -0,0 +1,24 @@
+# https://projecteuler.net/problem=2
+# Sum the even Fibonacci terms not exceeding 4,000,000.
+# Recursive function calling, generators and Python idioms
+def fib():
+    a, b = 1, 2
+    while True:
+        yield a
+        a, b = b, a + b
+
+def evens(it):
+    for x in it:
+        if x % 2 == 0:
+            yield x
+
+def upto(limit, it):
+    for x in it:
+        if x > limit:
+            return
+        yield x
+
+def euler2(limit=4000000):
+    return sum(evens(upto(limit, fib())))
+
+print(euler2())

examples/euler3.py

@@ -0,0 +1,11 @@
+# https://projecteuler.net/problem=3
+# Find the largest prime factor of 600851475143.
+def euler3(n=600851475143):
+    i = 2
+    while i * i <= n:
+        while n % i == 0:
+            n //= i
+        i += 1
+    return n
+
+print(euler3())

examples/memory_loader.py

@@ -0,0 +1,4 @@
+from sortedcontainers import SortedList
+from math import log
+values = SortedList([9, 4, 16])
+print(log(values.pop(), 2))

examples/mnist_digit.py

@@ -0,0 +1,4 @@
+# The first MNIST test image (a 7), classified by the 784-80-10 network in memory/mnist.safetensors.
+import mnist
+x=b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00T\xb9\x9f\x97<$\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\xde\xfe\xfe\xfe\xfe\xf1\xc6\xc6\xc6\xc6\xc6\xc6\xc6\xc6\xaa4\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00CrHr\xa3\xe3\xfe\xe1\xfe\xfe\xfe\xfa\xe5\xfe\xfe\x8c\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x11B\x0eCCC;\x15\xec\xfej\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00S\xfd\xd1\x12\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x16\xe9\xffS\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x81\xfe\xee,\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00;\xf9\xfe>\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x85\xfe\xbb\x05\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\t\xcd\xf8:\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00~\xfe\xb6\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00K\xfb\xf09\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x13\xdd\xfe\xa6\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x03\xcb\xfe\xdb#\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00&\xfe\xfeM\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x1f\xe0\xfes\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x85\xfe\xfe4\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00=\xf2\xfe\xfe4\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00y\xfe\xfe\xdb(\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00y\xfe\xcf\x12\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'
+print(mnist.predict(x))

examples/tax_brackets/1_create.py

@@ -0,0 +1,10 @@
+import sys
+brackets = [0, 11_000, 44_725, 95_375,
+            182_100, 231_250, 578_125]
+increments = [10, 2, 10, 2, 8, 3, 2]
+sys.modules["tax_brackets"] = type("tax_brackets", (), {
+"owed_tax": lambda income: sum(
+    rate * max(0, income - b)
+    for b, rate in zip(brackets, increments)
+) // 100})
+print("Tax brackets installed.")

examples/tax_brackets/2_use.py

@@ -0,0 +1,3 @@
+import tax_brackets
+income = 100_000
+print(f"${tax_brackets.owed_tax(income)}")

examples/tax_brackets/3_update.py

@@ -0,0 +1,10 @@
+import sys
+brackets = [0, 11_925, 48_475, 103_350,
+            197_300, 250_525, 626_350]
+increments = [10, 2, 10, 2, 8, 3, 2]
+sys.modules["tax_brackets"] = type("tax_brackets", (), {
+"owed_tax": lambda income: sum(
+    rate * max(0, income - b)
+    for b, rate in zip(brackets, increments)
+) // 100})
+print("Tax brackets updated.")

examples/tax_brackets/4_use_again.py

@@ -0,0 +1,3 @@
+import tax_brackets
+income = 100_000
+print(f"${tax_brackets.owed_tax(income)}")

intelligence/config.json

@@ -0,0 +1 @@
+{"d_model":16,"n_heads":8,"n_layers":8,"vocab_size":922,"proj_out":64,"stop_id":635,"n_out":786,"d_ffn":48,"head_rank":3,"d_rest":0,"d_v":2,"alpha_rows":1,"spacing":2.0,"memory_layer":4,"memory_head":4,"input_base":4475392,"registry_base":4587520,"registry_root_word":4475376,"memory_pages_word":4522008,"image_pages":70}

intelligence/model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e09af3088c603c3641923f8c1554fa6657573570b5eb251ed8c73c5ca543df7a
+size 378560

intelligence/vocab.json

@@ -0,0 +1 @@
+["!", "\"", "#", "$", "%", "&", "'", "(", ")", "*", "+", ",", "-", ".", "/", "0", "00", "00'", "01", "01'", "02", "02'", "03", "03'", "04", "04'", "05", "05'", "06", "06'", "07", "07'", "08", "08'", "09", "09'", "0a", "0a'", "0b", "0b'", "0c", "0c'", "0d", "0d'", "0e", "0e'", "0f", "0f'", "1", "10", "10'", "11", "11'", "12", "12'", "13", "13'", "14", "14'", "15", "15'", "16", "16'", "17", "17'", "18", "18'", "19", "19'", "1a", "1a'", "1b", "1b'", "1c", "1c'", "1d", "1d'", "1e", "1e'", "1f", "1f'", "2", "20", "20'", "21", "21'", "22", "22'", "23", "23'", "24", "24'", "25", "25'", "26", "26'", "27", "27'", "28", "28'", "29", "29'", "2a", "2a'", "2b", "2b'", "2c", "2c'", "2d", "2d'", "2e", "2e'", "2f", "2f'", "3", "30", "30'", "31", "31'", "32", "32'", "33", "33'", "34", "34'", "35", "35'", "36", "36'", "37", "37'", "38", "38'", "39", "39'", "3a", "3a'", "3b", "3b'", "3c", "3c'", "3d", "3d'", "3e", "3e'", "3f", "3f'", "4", "40", "40'", "41", "41'", "42", "42'", "43", "43'", "44", "44'", "45", "45'", "46", "46'", "47", "47'", "48", "48'", "49", "49'", "4a", "4a'", "4b", "4b'", "4c", "4c'", "4d", "4d'", "4e", "4e'", "4f", "4f'", "5", "50", "50'", "51", "51'", "52", "52'", "53", "53'", "54", "54'", "55", "55'", "56", "56'", "57", "57'", "58", "58'", "59", "59'", "5a", "5a'", "5b", "5b'", "5c", "5c'", "5d", "5d'", "5e", "5e'", "5f", "5f'", "6", "60", "60'", "61", "61'", "62", "62'", "63", "63'", "64", "64'", "65", "65'", "66", "66'", "67", "67'", "68", "68'", "69", "69'", "6a", "6a'", "6b", "6b'", "6c", "6c'", "6d", "6d'", "6e", "6e'", "6f", "6f'", "7", "70", "70'", "71", "71'", "72", "72'", "73", "73'", "74", "74'", "75", "75'", "76", "76'", "77", "77'", "78", "78'", "79", "79'", "7a", "7a'", "7b", "7b'", "7c", "7c'", "7d", "7d'", "7e", "7e'", "7f", "7f'", "8", "80", "80'", "81", "81'", "82", "82'", "83", "83'", "84", "84'", "85", "85'", "86", "86'", "87", "87'", "88", "88'", "89", "89'", "8a", "8a'", "8b", "8b'", "8c", "8c'", "8d", "8d'", "8e", "8e'", "8f", "8f'", "9", "90", "90'", "91", "91'", "92", "92'", "93", "93'", "94", "94'", "95", "95'", "96", "96'", "97", "97'", "98", "98'", "99", "99'", "9a", "9a'", "9b", "9b'", "9c", "9c'", "9d", "9d'", "9e", "9e'", "9f", "9f'", ":", ";", "<", "=", ">", "?", "@", "A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "[", "\\", "]", "^", "_", "`", "a", "a0", "a0'", "a1", "a1'", "a2", "a2'", "a3", "a3'", "a4", "a4'", "a5", "a5'", "a6", "a6'", "a7", "a7'", "a8", "a8'", "a9", "a9'", "aa", "aa'", "ab", "ab'", "ac", "ac'", "ad", "ad'", "ae", "ae'", "af", "af'", "ascii(00)", "ascii(01)", "ascii(02)", "ascii(03)", "ascii(04)", "ascii(05)", "ascii(06)", "ascii(07)", "ascii(08)", "ascii(09)", "ascii(0a)", "ascii(0b)", "ascii(0c)", "ascii(0d)", "ascii(0e)", "ascii(0f)", "ascii(10)", "ascii(11)", "ascii(12)", "ascii(13)", "ascii(14)", "ascii(15)", "ascii(16)", "ascii(17)", "ascii(18)", "ascii(19)", "ascii(1a)", "ascii(1b)", "ascii(1c)", "ascii(1d)", "ascii(1e)", "ascii(1f)", "ascii(20)", "ascii(7f)", "b", "b0", "b0'", "b1", "b1'", "b2", "b2'", "b3", "b3'", "b4", "b4'", "b5", "b5'", "b6", "b6'", "b7", "b7'", "b8", "b8'", "b9", "b9'", "ba", "ba'", "bb", "bb'", "bc", "bc'", "bd", "bd'", "be", "be'", "bf", "bf'", "branch_taken", "c", "c0", "c0'", "c1", "c1'", "c2", "c2'", "c3", "c3'", "c4", "c4'", "c5", "c5'", "c6", "c6'", "c7", "c7'", "c8", "c8'", "c9", "c9'", "ca", "ca'", "call_commit", "cb", "cb'", "cc", "cc'", "cd", "cd'", "ce", "ce'", "cf", "cf'", "commit(+0,sts=0,bt=0)", "commit(+0,sts=0,bt=1)", "commit(+0,sts=1,bt=0)", "commit(+0,sts=1,bt=1)", "commit(+1,sts=1,bt=0)", "commit(+1,sts=1,bt=1)", "commit(-1,sts=0,bt=0)", "commit(-1,sts=0,bt=1)", "commit(-1,sts=1,bt=0)", "commit(-1,sts=1,bt=1)", "commit(-2,sts=0,bt=0)", "commit(-2,sts=0,bt=1)", "commit(-2,sts=1,bt=0)", "commit(-2,sts=1,bt=1)", "d", "d0", "d0'", "d1", "d1'", "d2", "d2'", "d3", "d3'", "d4", "d4'", "d5", "d5'", "d6", "d6'", "d7", "d7'", "d8", "d8'", "d9", "d9'", "da", "da'", "db", "db'", "dc", "dc'", "dd", "dd'", "de", "de'", "df", "df'", "e", "e0", "e0'", "e1", "e1'", "e2", "e2'", "e3", "e3'", "e4", "e4'", "e5", "e5'", "e6", "e6'", "e7", "e7'", "e8", "e8'", "e9", "e9'", "ea", "ea'", "eb", "eb'", "ec", "ec'", "ed", "ed'", "ee", "ee'", "ef", "ef'", "execute", "f", "f0", "f0'", "f1", "f1'", "f2", "f2'", "f3", "f3'", "f4", "f4'", "f5", "f5'", "f6", "f6'", "f7", "f7'", "f8", "f8'", "f9", "f9'", "fa", "fa'", "fb", "fb'", "fc", "fc'", "fd", "fd'", "fe", "fe'", "ff", "ff'", "g", "h", "halt", "i", "i32.and", "i32.extend16_s", "i32.extend8_s", "i32.or", "i32.xor", "j", "k", "l", "m", "n", "o", "out(!)", "out(\")", "out(#)", "out($)", "out(%)", "out(&)", "out(')", "out(()", "out())", "out(*)", "out(+)", "out(,)", "out(-)", "out(.)", "out(/)", "out(0)", "out(00)", "out(01)", "out(02)", "out(03)", "out(04)", "out(05)", "out(06)", "out(07)", "out(08)", "out(09)", "out(0a)", "out(0b)", "out(0c)", "out(0d)", "out(0e)", "out(0f)", "out(1)", "out(10)", "out(11)", "out(12)", "out(13)", "out(14)", "out(15)", "out(16)", "out(17)", "out(18)", "out(19)", "out(1a)", "out(1b)", "out(1c)", "out(1d)", "out(1e)", "out(1f)", "out(2)", "out(20)", "out(3)", "out(4)", "out(5)", "out(6)", "out(7)", "out(7f)", "out(8)", "out(80)", "out(81)", "out(82)", "out(83)", "out(84)", "out(85)", "out(86)", "out(87)", "out(88)", "out(89)", "out(8a)", "out(8b)", "out(8c)", "out(8d)", "out(8e)", "out(8f)", "out(9)", "out(90)", "out(91)", "out(92)", "out(93)", "out(94)", "out(95)", "out(96)", "out(97)", "out(98)", "out(99)", "out(9a)", "out(9b)", "out(9c)", "out(9d)", "out(9e)", "out(9f)", "out(:)", "out(;)", "out(<)", "out(=)", "out(>)", "out(?)", "out(@)", "out(A)", "out(B)", "out(C)", "out(D)", "out(E)", "out(F)", "out(G)", "out(H)", "out(I)", "out(J)", "out(K)", "out(L)", "out(M)", "out(N)", "out(O)", "out(P)", "out(Q)", "out(R)", "out(S)", "out(T)", "out(U)", "out(V)", "out(W)", "out(X)", "out(Y)", "out(Z)", "out([)", "out(\\)", "out(])", "out(^)", "out(_)", "out(`)", "out(a)", "out(a0)", "out(a1)", "out(a2)", "out(a3)", "out(a4)", "out(a5)", "out(a6)", "out(a7)", "out(a8)", "out(a9)", "out(aa)", "out(ab)", "out(ac)", "out(ad)", "out(ae)", "out(af)", "out(b)", "out(b0)", "out(b1)", "out(b2)", "out(b3)", "out(b4)", "out(b5)", "out(b6)", "out(b7)", "out(b8)", "out(b9)", "out(ba)", "out(bb)", "out(bc)", "out(bd)", "out(be)", "out(bf)", "out(c)", "out(c0)", "out(c1)", "out(c2)", "out(c3)", "out(c4)", "out(c5)", "out(c6)", "out(c7)", "out(c8)", "out(c9)", "out(ca)", "out(cb)", "out(cc)", "out(cd)", "out(ce)", "out(cf)", "out(d)", "out(d0)", "out(d1)", "out(d2)", "out(d3)", "out(d4)", "out(d5)", "out(d6)", "out(d7)", "out(d8)", "out(d9)", "out(da)", "out(db)", "out(dc)", "out(dd)", "out(de)", "out(df)", "out(e)", "out(e0)", "out(e1)", "out(e2)", "out(e3)", "out(e4)", "out(e5)", "out(e6)", "out(e7)", "out(e8)", "out(e9)", "out(ea)", "out(eb)", "out(ec)", "out(ed)", "out(ee)", "out(ef)", "out(f)", "out(f0)", "out(f1)", "out(f2)", "out(f3)", "out(f4)", "out(f5)", "out(f6)", "out(f7)", "out(f8)", "out(f9)", "out(fa)", "out(fb)", "out(fc)", "out(fd)", "out(fe)", "out(ff)", "out(g)", "out(h)", "out(i)", "out(j)", "out(k)", "out(l)", "out(m)", "out(n)", "out(o)", "out(p)", "out(q)", "out(r)", "out(s)", "out(t)", "out(u)", "out(v)", "out(w)", "out(x)", "out(y)", "out(z)", "out({)", "out(|)", "out(})", "out(~)", "p", "page", "q", "r", "return_commit", "s", "t", "u", "unpage", "v", "w", "x", "y", "z", "{", "|", "}", "~"]

memory/core.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:79ed099f59fe3c62cc70595f9b09c4655b9cf5ed2be22042cc59de61afe156b3
+size 23989346

memory/mnist.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:45b8d1aafa55fa579c7995a74fa978cacfca8a3abbb6fe372719723fa7c223c4
+size 64556

memory/sortedcontainers.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5b173f11870edf27424391bb4dc6f3f9c65761f03d81bb58f43e4052664b887b
+size 26921

spotlight.c

@@ -0,0 +1,304 @@
+/* spotlight.c -- runs a Python program on the Spotlight VM model: ./spotlight [-v] < program.py
+ * Run it in the model folder; it loads intelligence/ and every package in memory/, and -v also
+ * prints each generated token. Built with -shared -DSPOTLIGHT_LIBRARY, spotlight.py loads it. */
+#define _POSIX_C_SOURCE 200809L
+#include <dirent.h>
+#include <math.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+typedef float real_t;
+static void die(const char *what) { fprintf(stderr, "spotlight: %s\n", what); exit(1); }
+static void *alloc(size_t n) { void *p = calloc(n ? n : 1, 1); if (!p) die("out of memory"); return p; }
+static char folder[4096] = ".";
+static const char *file(const char *name) { static char path[4200]; snprintf(path, sizeof path, "%s/%s", folder, name); return path; }
+
+static char *slurp(const char *path, size_t *size) {
+    FILE *f = path ? fopen(path, "rb") : stdin;
+    if (!f) die(path);
+    size_t cap = 1 << 16, n = 0, got; char *buf = alloc(cap);
+    while ((got = fread(buf + n, 1, cap - n - 1, f)) > 0) if ((n += got) == cap - 1) buf = realloc(buf, cap *= 2);
+    if (path) fclose(f);
+    buf[n] = 0; if (size) *size = n;
+    return buf;
+}
+
+/* ── config.json and safetensors ─────────────────────────────────────── */
+static char *config;
+static double number(const char *key) {
+    char pattern[64]; snprintf(pattern, sizeof pattern, "\"%s\":", key);
+    const char *p = strstr(config, pattern);
+    if (!p) die(key);
+    return strtod(p + strlen(pattern), NULL);
+}
+
+typedef struct { char dtype[4]; const char *data; int64_t count; } Tensor;
+static int tensor(const char *file_bytes, const char *name, Tensor *out) {
+    char pattern[96]; snprintf(pattern, sizeof pattern, "\"%s\":", name);
+    uint64_t header; memcpy(&header, file_bytes, 8);
+    const char *p = strstr(file_bytes + 8, pattern);
+    if (!p || p > file_bytes + 8 + header) return 0;
+    const char *dtype = strstr(p, "\"dtype\":\"") + 9; char *offsets = strstr(p, "\"data_offsets\":[") + 16;
+    memset(out->dtype, 0, 4); memcpy(out->dtype, dtype, strchr(dtype, '"') - dtype);
+    int64_t begin = strtoll(offsets, &offsets, 10), end = strtoll(offsets + 1, NULL, 10);
+    int width = out->dtype[1] == '8' ? 1 : out->dtype[1] == '1' ? 2 : out->dtype[1] == '3' ? 4 : 8;
+    out->data = file_bytes + 8 + header + begin; out->count = (end - begin) / width;
+    return 1;
+}
+static double item(const Tensor *t, int64_t i) {
+    double f; int32_t i32; int16_t i16;
+    switch (t->dtype[0] == 'F' ? 'F' : t->dtype[1]) {
+        case 'F': memcpy(&f, t->data + 8 * i, 8); return f;
+        case '3': memcpy(&i32, t->data + 4 * i, 4); return i32;
+        case '1': memcpy(&i16, t->data + 2 * i, 2); return i16;
+        default: return t->dtype[0] == 'U' ? (double)(uint8_t)t->data[i] : (double)(int8_t)t->data[i];
+    }
+}
+static real_t *load(const char *file_bytes, const char *name, int64_t count) {
+    Tensor x; if (!tensor(file_bytes, name, &x) || x.count != count) die(name);
+    real_t *out = alloc((size_t)count * sizeof(real_t));
+    for (int64_t i = 0; i < count; i++) out[i] = (real_t)item(&x, i);
+    return out;
+}
+
+/* ── the memory: one hash map from (table, x, y) to a cell's state ──── */
+typedef struct { int64_t x, y; int32_t table, used; real_t s[2]; } Cell;
+static Cell *cells; static size_t cells_cap, cells_n;
+static const real_t ZERO[2] = {0, 0};
+
+static size_t cell_slot(int table, int64_t x, int64_t y) {
+    uint64_t h = (uint64_t)x * 0x9E3779B97F4A7C15ull ^ (uint64_t)y * 0xC2B2AE3D27D4EB4Full ^ (uint64_t)table * 0x165667B19E3779F9ull;
+    size_t i = (size_t)(h ^ h >> 29) & (cells_cap - 1);
+    while (cells[i].used && (cells[i].x != x || cells[i].y != y || cells[i].table != table)) i = (i + 1) & (cells_cap - 1);
+    return i;
+}
+static real_t *cell_write(int table, int64_t x, int64_t y) {
+    if (2 * (cells_n + 1) > cells_cap) {
+        Cell *old = cells; size_t n = cells_cap;
+        cells_cap = cells_cap ? 2 * cells_cap : 1 << 22; cells = alloc(cells_cap * sizeof(Cell));
+        for (size_t i = 0; i < n; i++) if (old[i].used) cells[cell_slot(old[i].table, old[i].x, old[i].y)] = old[i];
+        free(old);
+    }
+    size_t i = cell_slot(table, x, y);
+    if (!cells[i].used) { cells[i].x = x; cells[i].y = y; cells[i].table = table; cells[i].used = 1; cells_n++; }
+    return cells[i].s;
+}
+static const real_t *cell_read(int table, int64_t x, int64_t y) {
+    size_t i = cell_slot(table, x, y);
+    return cells[i].used ? cells[i].s : ZERO;
+}
+
+/* ── the model ───────────────────────────────────────────────────────── */
+/* The Spotlight kernel: phi_z(x) = b(x - z) / sqrt(sum_j b(x - j)^2) over the three nearest cells,
+ * with b(t) = cos^2(pi t / 2) for |t| < 1. */
+static void phi(real_t x, int64_t *z0, real_t w[3]) {
+    int64_t c = (int64_t)floor(x + 0.5); real_t norm = 0;
+    for (int i = 0; i < 3; i++) {
+        real_t t = x - (real_t)(c + i - 1), b = fabsf(t) < 1 ? cosf(3.14159265f * t / 2) : 0;
+        w[i] = b * b; norm += w[i] * w[i];
+    }
+    for (int i = 0; i < 3; i++) w[i] /= sqrtf(norm);
+    *z0 = c - 1;
+}
+static real_t sigmoid(real_t z) { return 1 / (1 + expf(-z)); }
+static real_t dot(const real_t *row, const real_t *x, int cols) {   /* 8 lanes, so it vectorizes */
+    real_t a[8] = {0}, acc; int c = 0;
+    for (; c + 8 <= cols; c += 8) for (int k = 0; k < 8; k++) a[k] += row[c + k] * x[c + k];
+    acc = ((a[0] + a[1]) + (a[2] + a[3])) + ((a[4] + a[5]) + (a[6] + a[7]));
+    for (; c < cols; c++) acc += row[c] * x[c];
+    return acc;
+}
+static void matvec(const real_t *m, int rows, int cols, const real_t *x, const real_t *bias, real_t *y) {
+    for (int r = 0; r < rows; r++) y[r] = bias ? dot(m + (size_t)r * cols, x, cols) + bias[r] : dot(m + (size_t)r * cols, x, cols);
+}
+
+typedef struct { real_t *qkv_w, *qkv_b, *out_w, *ff_in_w, *ff_out_w; } Layer;
+static struct {
+    int D, H, layers, vocab, proj_out, stop_id, n_out, d_ffn, rank;
+    Layer *layer; real_t *embed, *basis, *coeff; int32_t *out_ids; char **tokens;
+} M;
+
+/* One head, one token: a delta-rule write into the 3x3 cells around the key, then a read of the
+ * 3x3 cells around the query. */
+static void memory_step(int table, const real_t *p, int h, real_t *out) {
+    const int H = M.H; const real_t *v = p + 6 * H + 2 * h;
+    real_t beta = sigmoid(p[4 * H + h]), alpha = sigmoid(-p[5 * H + h]), wx[3], wy[3];
+    int64_t x0, y0;
+    phi(p[2 * h], &x0, wx); phi(p[2 * h + 1], &y0, wy);
+    for (int i = 0; i < 3; i++) for (int j = 0; j < 3; j++) {
+        real_t w = wx[i] * wy[j] * beta;
+        if (w == 0.0) continue;
+        real_t *S = cell_write(table, x0 + i, y0 + j);
+        real_t d0 = (v[0] - alpha * S[0]) * w, d1 = (v[1] - alpha * S[1]) * w;
+        S[0] += d0; S[1] += d1;
+    }
+    phi(p[2 * H + 2 * h], &x0, wx); phi(p[2 * H + 2 * h + 1], &y0, wy);
+    out[0] = out[1] = 0.0;
+    for (int i = 0; i < 3; i++) for (int j = 0; j < 3; j++) {
+        const real_t *S = cell_read(table, x0 + i, y0 + j);
+        out[0] += wx[i] * wy[j] * S[0]; out[1] += wx[i] * wy[j] * S[1];
+    }
+}
+
+/* One token through every layer, then the most likely next token. */
+static int32_t forward(int32_t token) {
+    static real_t x[64], proj[512], mem[64], res[64], pre[256], gate[128], feat[16];
+    const int D = M.D;
+    memcpy(x, M.embed + (size_t)token * D, D * sizeof(real_t));
+    for (int l = 0; l < M.layers; l++) {
+        const Layer *L = &M.layer[l];
+        matvec(L->qkv_w, M.proj_out, D, x, L->qkv_b, proj);
+        for (int h = 0; h < M.H; h++) memory_step(l * M.H + h, proj, h, mem + 2 * h);
+        matvec(L->out_w, D, 2 * M.H, mem, NULL, res);
+        for (int i = 0; i < D; i++) x[i] += res[i];
+        matvec(L->ff_in_w, 2 * M.d_ffn, D, x, NULL, pre);
+        for (int j = 0; j < M.d_ffn; j++) gate[j] = (pre[j] > 0.0 ? pre[j] : 0.0) * pre[M.d_ffn + j];
+        matvec(L->ff_out_w, D, M.d_ffn, gate, NULL, res);
+        for (int i = 0; i < D; i++) x[i] += res[i];
+    }
+    matvec(M.basis, M.rank, D, x, NULL, feat);
+    real_t best = -HUGE_VAL; int32_t best_row = 0;
+    for (int r = 0; r < M.n_out; r++) {
+        real_t acc = 0.0;
+        for (int k = 0; k < M.rank; k++) acc += M.coeff[(size_t)r * M.rank + k] * feat[k];
+        if (acc > best) { best = acc; best_row = r; }
+    }
+    return M.out_ids[best_row];
+}
+
+/* ── loading ─────────────────────────────────────────────────────────── */
+static void poke(int64_t address, const uint8_t *bytes, size_t n) {   /* bytes into the memory's cells */
+    int table = number("memory_layer") * M.H + number("memory_head"); double spacing = number("spacing");
+    for (size_t i = 0; i < n; i++, address++) {
+        real_t *s = cell_write(table, (int64_t)(spacing * (double)(address % 65536)), (int64_t)(spacing * (double)(address / 65536)));
+        s[0] = (real_t)bytes[i]; s[1] = 0.0;
+    }
+}
+static void poke_word(int64_t address, uint32_t v) { uint8_t b[4] = {v & 255, v >> 8 & 255, v >> 16 & 255, v >> 24}; poke(address, b, 4); }
+
+int spotlight_load(const char *dir) {
+    snprintf(folder, sizeof folder, "%s", dir);
+    config = slurp(file("intelligence/config.json"), NULL);
+    M.D = number("d_model"); M.H = number("n_heads"); M.layers = number("n_layers"); M.vocab = number("vocab_size");
+    M.proj_out = number("proj_out"); M.stop_id = number("stop_id"); M.n_out = number("n_out");
+    M.d_ffn = number("d_ffn"); M.rank = number("head_rank");
+    if (number("d_rest") != 0 || number("d_v") != 2 || number("alpha_rows") != 1) die("unsupported model shape");
+    char *vocab = slurp(file("intelligence/vocab.json"), NULL), *p = vocab, name[64];
+    M.tokens = alloc(M.vocab * sizeof(char *));
+    for (int i = 0; i < M.vocab; i++) {
+        p = strchr(p, '"') + 1; char *q = M.tokens[i] = alloc(64);
+        while (*p != '"') { if (*p == '\\') p++; *q++ = *p++; }
+        p++;
+    }
+    char *w = slurp(file("intelligence/model.safetensors"), NULL);
+    M.layer = alloc(M.layers * sizeof(Layer));
+    for (int l = 0; l < M.layers; l++) {
+        Layer *L = &M.layer[l];
+        snprintf(name, sizeof name, "layers.%d.qkv_w", l); L->qkv_w = load(w, name, (int64_t)M.proj_out * M.D);
+        snprintf(name, sizeof name, "layers.%d.qkv_b", l); L->qkv_b = load(w, name, M.proj_out);
+        snprintf(name, sizeof name, "layers.%d.out_w", l); L->out_w = load(w, name, (int64_t)M.D * 2 * M.H);
+        snprintf(name, sizeof name, "layers.%d.ff_in_w", l); L->ff_in_w = load(w, name, (int64_t)2 * M.d_ffn * M.D);
+        snprintf(name, sizeof name, "layers.%d.ff_out_w", l); L->ff_out_w = load(w, name, (int64_t)M.D * M.d_ffn);
+    }
+    M.embed = load(w, "embed_tokens.weight", (int64_t)M.vocab * M.D);
+    M.basis = load(w, "head_basis", (int64_t)M.rank * M.D);
+    M.coeff = load(w, "head_coeff", (int64_t)M.n_out * M.rank);
+    real_t *ids = load(w, "out_ids", M.n_out);
+    M.out_ids = alloc(M.n_out * sizeof(int32_t));
+    for (int i = 0; i < M.n_out; i++) M.out_ids[i] = (int32_t)ids[i];
+    free(vocab); free(w); free(ids);
+    return M.vocab;
+}
+
+/* A fresh memory: MicroPython's code, tables and boot state, then the packages in one registry. */
+static void load_memory(char **packages, int n) {
+    free(cells); cells = NULL; cells_cap = cells_n = 0;
+    char *core = slurp(file("memory/core.safetensors"), NULL), name[64];
+    for (int t = 0; t < M.layers * M.H; t++) {
+        Tensor xy, value;
+        snprintf(name, sizeof name, "cells.%d.%d.xy", t / M.H, t % M.H); if (!tensor(core, name, &xy)) continue;
+        snprintf(name, sizeof name, "cells.%d.%d.value", t / M.H, t % M.H); if (!tensor(core, name, &value)) continue;
+        for (int64_t i = 0; i < xy.count / 2; i++) {
+            real_t *s = cell_write(t, (int64_t)item(&xy, 2 * i), (int64_t)item(&xy, 2 * i + 1));
+            s[0] = (real_t)item(&value, 2 * i); s[1] = (real_t)item(&value, 2 * i + 1);
+        }
+    }
+    free(core);
+    if (n == 0) return;
+    int64_t base = number("registry_base"), size = 16, pages, modules = 0;
+    for (int i = 0; i < n; i++) {
+        char *bytes = slurp(packages[i], NULL); Tensor b;
+        if (!tensor(bytes, "bundle", &b) || memcmp(b.data, "SPKG", 4)) die("not a package");
+        poke(base + size, (const uint8_t *)b.data + 16, b.count - 16);
+        uint32_t count; memcpy(&count, b.data + 12, 4);
+        size += b.count - 16; modules += count;
+        free(bytes);
+    }
+    uint8_t header[8] = {'S', 'P', 'K', 'G', 1};
+    poke(base, header, 8); poke_word(base + 8, (uint32_t)size); poke_word(base + 12, (uint32_t)modules);
+    poke_word(number("registry_root_word"), (uint32_t)base);
+    pages = (base + size + 65535) / 65536;
+    poke_word(number("memory_pages_word"), (uint32_t)(pages > number("image_pages") ? pages : number("image_pages")));
+}
+
+/* ── running ─────────────────────────────────────────────────────────── */
+static int32_t *kept; static int64_t kept_n, kept_cap; static int printing = 0, verbose = 0;
+
+/* Runs a prompt from a fresh memory until the stop token (or max_new tokens). The command line
+ * prints the output as it comes; the library keeps the tokens that carry it, and the stop token. */
+int64_t spotlight_generate(const int32_t *prompt, int64_t n, int64_t max_new, char **packages, int n_packages) {
+    load_memory(packages, n_packages);
+    int32_t next = 0; kept_n = 0;
+    for (int64_t i = 0; i < n; i++) next = forward(prompt[i]);
+    for (int64_t count = 1;; count++, next = forward(next)) {
+        const char *t = M.tokens[next]; int out = !strncmp(t, "out(", 4);
+        if (verbose) fprintf(stderr, "%s ", t);
+        if (printing && out) { putchar(strlen(t) == 6 ? t[4] : (int)strtol(t + 4, NULL, 16)); fflush(stdout); }
+        if (!printing && (out || next == M.stop_id)) {
+            if (kept_n == kept_cap) kept = realloc(kept, (kept_cap = kept_cap ? 2 * kept_cap : 1024) * sizeof(int32_t));
+            kept[kept_n++] = next;
+        }
+        if (next == M.stop_id || count == max_new) return count;
+    }
+}
+const int32_t *spotlight_kept(int64_t *n) { *n = kept_n; return kept; }
+
+#ifndef SPOTLIGHT_LIBRARY
+static int32_t token(const char *name) {
+    for (int32_t i = 0; i < M.vocab; i++) if (!strcmp(M.tokens[i], name)) return i;
+    die(name); return -1;
+}
+static int is_package(const struct dirent *e) {
+    size_t n = strlen(e->d_name);
+    return n > 12 && !strcmp(e->d_name + n - 12, ".safetensors") && strcmp(e->d_name, "core.safetensors");
+}
+int main(int argc, char **argv) {
+    verbose = argc > 1 && !strcmp(argv[1], "-v"); printing = 1;
+    spotlight_load(".");
+    struct dirent **list; int n_packages = scandir("memory", &list, is_package, alphasort);
+    char **packages = alloc((n_packages > 0 ? n_packages : 1) * sizeof(char *));
+    for (int i = 0; i < n_packages; i++) { packages[i] = alloc(300); snprintf(packages[i], 300, "memory/%s", list[i]->d_name); }
+    /* The prompt: where the source goes, its bytes (and a NUL) page by page, then execute. */
+    size_t n; char *src = slurp(NULL, &n), hex[16];
+    int64_t input = number("input_base"), pages = (input % 65536 + (int64_t)n) / 65536 + 1, count = 0;
+    int32_t *prompt = alloc((n + 16 * pages + 8) * sizeof(int32_t));
+    for (int64_t r = pages - 1; r >= 0; r--) {
+        uint32_t address = (uint32_t)(r ? (input / 65536 + r) * 65536 : input);
+        for (int lane = 0; lane < 4; lane++) { snprintf(hex, sizeof hex, "%02x", address >> 8 * lane & 255); prompt[count++] = token(hex); }
+        prompt[count++] = token("page");
+    }
+    for (int64_t i = 0; i <= (int64_t)n; i++) {
+        unsigned char b = i < (int64_t)n ? src[i] : 0;
+        if (b >= 128) die("the program must be ASCII");
+        if (i && (input + i) % 65536 == 0) prompt[count++] = token("unpage");
+        if (b > 0x20 && b < 0x7f) { hex[0] = b; hex[1] = 0; } else snprintf(hex, sizeof hex, "ascii(%02x)", b);
+        prompt[count++] = token(hex);
+    }
+    prompt[count++] = token("execute");
+    count = spotlight_generate(prompt, count, INT64_MAX, packages, n_packages > 0 ? n_packages : 0);
+    fprintf(stderr, "%s%lld tokens generated\n", verbose ? "\n" : "", (long long)count);
+    return 0;
+}
+#endif

spotlight.py

@@ -0,0 +1,76 @@
+"""Spotlight VM as a `transformers` model. The model runs spotlight.c, built into build/ on first use."""
+import ctypes, glob, json, os, subprocess
+
+import torch
+from huggingface_hub import snapshot_download
+from transformers import PretrainedConfig, PreTrainedModel, PreTrainedTokenizer
+
+
+class SpotlightConfig(PretrainedConfig):
+    model_type = "spotlight"
+
+
+class SpotlightForCausalLM(PreTrainedModel):
+    config_class = SpotlightConfig
+
+    @classmethod
+    def from_pretrained(cls, name_or_path, *args, **kwargs):
+        folder = os.path.abspath(name_or_path if os.path.isdir(name_or_path) else snapshot_download(name_or_path))
+        library = os.path.join(folder, "build", "libspotlight.so")
+        if not os.path.exists(library):
+            os.makedirs(os.path.dirname(library), exist_ok=True)
+            source = os.path.join(folder, "spotlight.c")
+            subprocess.run(["cc", "-O3", "-std=c99", "-shared", "-fPIC", "-DSPOTLIGHT_LIBRARY", source, "-lm", "-o", library], check=True)
+        model = cls(SpotlightConfig.from_pretrained(folder))
+        model.folder, model.lib = folder, ctypes.CDLL(library)
+        model.lib.spotlight_generate.restype = ctypes.c_int64
+        model.lib.spotlight_kept.restype = ctypes.POINTER(ctypes.c_int32)
+        model.lib.spotlight_load(folder.encode())
+        return model
+
+    @torch.no_grad()
+    def generate(self, input_ids, max_new_tokens=10**12, packages=None, **kwargs):
+        """Runs the program from a fresh memory: the core plus `packages` (default: all in memory/).
+        Returns the prompt followed by the generated tokens that carry output, and the stop token."""
+        if packages is None:
+            packages = [p for p in sorted(glob.glob(os.path.join(self.folder, "memory", "*.safetensors")))
+                        if not p.endswith("core.safetensors")]
+        paths = (ctypes.c_char_p * max(1, len(packages)))(*[os.path.abspath(p).encode() for p in packages])
+        prompt = input_ids[0].to(torch.int32).contiguous()
+        self.generated_tokens = self.lib.spotlight_generate(ctypes.c_void_p(prompt.data_ptr()), ctypes.c_int64(prompt.numel()),
+                                                            ctypes.c_int64(max_new_tokens), paths, len(packages))
+        n = ctypes.c_int64()
+        kept = ctypes.string_at(self.lib.spotlight_kept(ctypes.byref(n)), 4 * n.value)
+        return torch.cat([prompt, torch.frombuffer(bytearray(kept), dtype=torch.int32)]).long()[None]
+
+
+class SpotlightTokenizer(PreTrainedTokenizer):
+    vocab_files_names = {"vocab_file": "intelligence/vocab.json", "config_file": "intelligence/config.json"}
+
+    def __init__(self, vocab_file, config_file, **kwargs):
+        with open(vocab_file) as f:
+            self.names = json.load(f)
+        self.ids = {name: i for i, name in enumerate(self.names)}
+        with open(config_file) as f:
+            self.input_base = json.load(f)["input_base"]
+        super().__init__(**kwargs)
+
+    vocab_size = property(lambda self: len(self.names))
+    get_vocab = lambda self: dict(self.ids)
+    _convert_token_to_id = lambda self, token: self.ids[token]
+    _convert_id_to_token = lambda self, index: self.names[index]
+
+    def _tokenize(self, text, **kwargs):
+        """Where the source goes, its bytes (and a NUL) page by page, then execute -- as spotlight.c does."""
+        data, base, tokens = text.encode("ascii") + b"\0", self.input_base, []
+        for page in reversed(range((base % 65536 + len(data) - 1) // 65536 + 1)):
+            address = (base // 65536 + page) * 65536 if page else base
+            tokens += [f"{address >> 8 * lane & 255:02x}" for lane in range(4)] + ["page"]
+        for i, b in enumerate(data):
+            tokens += (["unpage"] if i and (base + i) % 65536 == 0 else []) + [chr(b) if 0x20 < b < 0x7F else f"ascii({b:02x})"]
+        return tokens + ["execute"]
+
+    def decode(self, token_ids, **kwargs):
+        """The program's printed output: the bytes carried by the out(..) tokens."""
+        names = [self.names[i] for i in (token_ids.tolist() if hasattr(token_ids, "tolist") else token_ids)]
+        return bytes(ord(n[4]) if len(n) == 6 else int(n[4:-1], 16) for n in names if n.startswith("out(")).decode("latin-1")