What it is
A PySpell program is a single expression (Python) or some let bindings followed by a
trailing expression (Rust). It evaluates to a value — a number, a boolean, a string, or a list. Free
identifiers are resolved at evaluation time against a host-supplied environment: CLI variables
on a laptop, or live device readings on a microcontroller. The only I/O is a host-granted, allowlisted
fetch_json; there are no loops, functions, or imports — that is the point: small, fast, and
safe to accept from elsewhere.
syn
(Rust) and rustpython-parser (Python). For "type code in a browser and run it on the
chip", a tiny hand-written parser (a few kB, no_std) builds the same AST on the device.
Either way: source → AST → evaluate.
An offline AI coding agent, served off the chip
Open http://<dongle>/ over the tunnel and you get a Cursor-like agent. Type
"flash the light", "show the text "hello"", "what is 7 plus 5",
or "reverse the word robot" — a ~0.45 M-parameter language model (< 500 kB, int8)
turns it into PySpell code, runs it live on the chip, and shows the result, or the
physical action (the screen lights up, the RGB LED blinks). Runtime, model, tokenizer and dictionary
are all served from the dongle, offline — no cloud, no key (OpenAI is optional, behind
the ⚙).
A model that small is only useful because of a chain of tricks — the full write-up is in
tech.md. The headlines:
The model points, the browser copies
A 0.45 M model can't reliably copy arbitrary tokens (numbers, strings, lists), so it isn't asked
to. It emits tiny semantic directives; the browser copies the literal content verbatim.
calculate 3 + 2 → print(3 + 2); change add to
subtract → @@ + ==> -. Quoted text is literal content — copied byte-for-byte,
excluded from vocab checks.
The device serves; the browser computes
Inference runs in WebAssembly, client-side. The 0.5 MB model image streams off flash a TCP segment at a time (HTTP Range) and is never resident in the chip's ~60 kB heap. Inverted edge inference: the constrained device serves and grades, the browser runs the model.
Frozen embeddings, distilled
The 512-token vocab is embedded with all-MiniLM (22 M params), PCA'd to 128 dims, folded with a part-of-speech vector, and frozen — the tiny model starts with meaningful word geometry instead of spending its tiny budget learning it.
The vocabulary is the dictionary
Those same 512 tokens + embeddings are served back to the browser for input validation ("outside the model's vocabulary…") and related-word RAG over the model's own vocabulary.
Syntax at a glance
Python
free_heap > 100000 and uptime_s < 60
250 if distance > 1000 else 0
0 < temp < 60 # chained
20 not in peers
sum([1, 2, 3])
readings[-1] # negative index
max(a, b)Rust
free_heap > 100000 && uptime_s < 60
if distance > 1000 { 250 } else { 0 }
let used = total - free; used * 100 / total
!peers.contains(20)
sum([1, 2, 3])
readings[readings.len() - 1]
max(a, b)Language reference
Literals & values
| Kind | Examples | Notes |
|---|---|---|
| Integer | 0, 42, -7 | 64-bit signed |
| Float | 1.5, 3.14 | 64-bit |
| Boolean | true/True, false/False | both spellings accepted |
| String | "hello", 'oslo' | + concatenates; ==/< compare; len() counts chars |
| List | [1, 2, 3] | elements are values |
Operators
| Group | Python | Rust | Notes |
|---|---|---|---|
| Arithmetic | + - * / % (and //) | on integers, / and // both truncate toward zero; a float operand promotes to float division. There is no separate float floor-div. | |
| Comparison | == != < <= > >= | Python allows chaining (a < b < c) | |
| Boolean | and, or, not | &&, ||, ! | short-circuiting |
| Unary | -x, not x / !x | ||
| Membership | x in list, x not in list | list.contains(x) | numeric equality |
| Index | list[i] | negative indexing supported | |
Control flow & bindings
| Feature | Python | Rust |
|---|---|---|
| Conditional | a if cond else b | if cond { a } else { b } (else required) |
| Local bindings | (single expression only) | let x = e; let y = e2; final_expr |
| Free variables | any bare name not bound by let is read from the host environment | |
Built-in functions
| Function | Result | Description |
|---|---|---|
len(list) | int | number of elements |
abs(x) | number | absolute value |
min(list) / min(a, b, …) | number | minimum |
max(list) / max(a, b, …) | number | maximum |
sum(list) | number | sum of a numeric list |
any(list) | bool | true if any element is truthy |
all(list) | bool | true if all elements are truthy |
round(x) | int | round to nearest integer |
int(x) | int | truncate toward zero |
float(x) | float | convert to float |
bool(x) | bool | truthiness |
index(list, x) | int | position of first x, or -1 |
before(list, a, b) | bool | true if a occurs before b |
first(list) | value | first element, or -1 if empty |
last(list) | value | last element, or -1 if empty |
str(x) | string | string representation of a value |
json_get(text, "a.b.0.c") | scalar | extract the scalar at a dotted/indexed JSON path (no full parse — only the matched value is materialized) |
fetch(url) | string | HTTP(S) GET body. Gated by a host allowlist; errors if the host isn't allowed or no network capability is present |
fetch_json(url, "a.b.0.c") | scalar | stream the response and extract just the scalar at the path, stopping as soon as it's found — never buffers the whole body. Preferred on the device. |
show(x) | x | render x to text and display it (the ESP32 screen; stdout on host), returning x so it composes. Device gates it via config (allow on/off, auto-revert seconds). |
Classic one-liner — fetch a value and show it on the dongle's screen:
show("Oslo: " + fetch_json(
"https://api.met.no/weatherapi/locationforecast/2.0/compact?lat=59.91&lon=10.75",
"properties.timeseries.0.data.instant.details.air_temperature") + " C")
# screen shows: Oslo: 14.9 C (and the call returns that string)Network & JSON
fetch(url) + json_get(text, path) let a program pull live data and read one
field out of it. fetch is a mediated capability — the host/device decides which hosts are
reachable (an allowlist), so a program can't reach arbitrary URLs.
# Host CLI (allow the host explicitly):
pyspell run oslo_temp.py --allow-host api.met.no
# where oslo_temp.py is:
json_get(
fetch("https://api.met.no/weatherapi/locationforecast/2.0/compact?lat=59.91&lon=10.75"),
"properties.timeseries.0.data.instant.details.air_temperature")
# → 14.9Memory note (device): json_get is path-directed so it never builds the
whole document in RAM — it materializes only the matched value. On the ESP32 (≈60 kB free, no PSRAM)
reading a field out of a large response is feasible because fetch_json streams the
HTTP(S) body and stops the moment the field is found (freeing the TLS buffers early) — so a ~50 kB yr.no
response never has to fit in RAM at once.
# On the ESP32, over Tailscale (single process; ≈60 kB free; verified live):
fetch_json(
"https://api.met.no/weatherapi/locationforecast/2.0/compact?lat=59.91&lon=10.75",
"properties.timeseries.0.data.instant.details.air_temperature")
# → 14.9 (the dongle fetched yr.no itself)Running on the host
# Evaluate, binding free variables:
cargo run -p pyspell-cli -- run examples/health.py --set free_heap=120000 --set uptime_ms=45000
# → true
# Compile to a portable IR blob:
cargo run -p pyspell-cli -- compile examples/health.py # → examples/health.py.psb
# Push live to a device over USB-serial, or an interactive REPL:
cargo run -p pyspell-cli -- repl --port /dev/cu.usbmodem2101 --lang pythonRunning on the ESP32
The portable evaluator (pyspell-core, no_std + alloc) runs unchanged on the
ESP32-S3. Programs read live device variables from the environment:
| Variable | Meaning |
|---|---|
free_heap | free heap, bytes |
min_free_heap | lowest free heap seen since boot, bytes |
uptime_ms | milliseconds since boot |
uptime_s | seconds since boot |
Demo: PySpell over Tailscale
The demo/esp32-tailscale-pyspell firmware adds a web text window and a /run
API inside a Tailscale tunnel — open the device's Tailscale IP in a browser, type an
expression, set a timeout, and run it on the chip. PySpell adds only ~62 kB on top of the networking
firmware.
# Web window:
open http://100.x.y.z/
# POST (preferred): program in the body, lang/timeout in the query.
# More room for code than a URL, and no percent-encoding.
curl -X POST 'http://100.x.y.z/run?lang=py&timeout=10' --data 'free_heap > 100000' # → true
curl -X POST 'http://100.x.y.z/run?lang=rs&timeout=10' --data 'uptime_ms / 1000' # → 22
# GET (also supported): code is URL-encoded in the query.
curl 'http://100.x.y.z/run?lang=py&timeout=10&code=free_heap%20%3E%20100000' # → truetimeout is in seconds, clamped to 1–60, and enforced as a real wall-clock deadline on
the device. The single request must fit one TCP segment (≈1.2 kB) — POST leaves more of that for code.
Response format
The reply is text/plain (no JSON wrapper):
| Outcome | Body |
|---|---|
| Success | the raw value — true/false, an integer, a float, or a list like [1, 2, 3] |
| Failure | a line starting with error: — e.g. error: parse error: unexpected end of input, error: unknown name `foo`, or error: program exceeded its time limit |
How it fits in 512 kB
The ESP32-S3 has 512 kB of SRAM and no PSRAM, yet it runs a full Tailscale node (control plane and DERP), the PySpell evaluator, a browser agent IDE served off the chip, a native MCP server, and TLS to api.met.no. That only fits because of a long chain of memory tricks.
Crypto & TLS
SPKI leaf-key pinning instead of CA-chain validation — one RSA-PSS verify, no 6 kB
chain buffer (a TLS fetch drops ~45→30 kB). A heap admission gate bounds concurrency
so peak heap is K × per-fetch, never N × per-fetch.
Stream, don't buffer
The netmap is read with serde_json::from_reader over the HTTP/2 frames, so serde
skips the huge DERPMap field instead of buffering it (~60 kB → one 4 kB chunk).
fetch_json stops the moment the value is found, and raw byte-scans
replace JSON DOM trees.
Pages from flash
Static content lives in flash as &'static str (zero heap) and is streamed out as
512-byte TCP segments — only the current segment is ever in RAM, so the 4.3 kB agent
IDE serves without a full-page buffer.
Allocator & sockets
Heap and stack share one DRAM pool (+16 kB heap = −16 kB stack), tuned by hand.
SO_LINGER=0 frees lwIP sockets immediately (no TIME_WAIT pile-up), and a
cooperative shared stack on the lean build makes parallelism cheap where per-thread
stacks can't.
The full catalog — every trick with the exact file and symbol — is in
docs/memory-512kb.md.
Sandbox & limits
- Deny-by-default grammar. Only the whitelisted expression nodes and the built-ins above exist — no loops, functions, recursion, attribute access, imports, strings, or I/O.
- Instruction budget. Every evaluation has a step limit (runaway guard).
- Wall-clock timeout. A caller can supply a deadline (e.g. 10 s); on the device the ESP timer enforces it.
- Parser stays small. The on-device parser accepts only the safe subset, so the device's attack surface is just a bounded decoder + evaluator.