spine-assistant (proof of concept)
A constrained natural-language-to-script backbone for SPINE. It turns a small JSON specification of an experiment into a runnable SPINE Python script — deterministically, using only verified API and source-default units.
Local and free by default. The front-end talks to a local
Ollama model (no API key, no per-token cost, nothing
leaves the machine). A one-page web UI (serve) gives non-experts a
click-and-talk surface: type or speak the experiment, get a runnable
script. A hosted provider (Anthropic) is available with --provider anthropic
but is never required.
The LLM front-end is wired (llm.py), but the trustworthy core still does not
depend on a model — the model only fills a typed spec:
natural language ──▶ [ LLM ] ──▶ spec.json ──▶ [ validate ] ──▶ [ render ] ──▶ script.py
(a human sentence) llm.py constrained physics/API template runnable
(Claude, JSON object checks (no free- SPINE code
structured │ form codegen)
outputs) └─ on failure, the errors are
fed back to the model
(validate → repair loop)
Before each call, the most similar authored (request → spec) pairs from
dataset/ are retrieved (dependency-free TF-IDF, retrieval.py) and shown to
the model as few-shot examples, so it imitates good choices — correct node
placement, minimal specs, sane units — without any fine-tuning. Control it with
generate --examples N (0 disables; lower it for very small context windows).
The LLM only ever chooses values in a typed spec; it never writes SPINE
code. That is what neutralizes the scary failure mode — a script that runs
but encodes wrong physics or wrong units — because program structure and units
come from a human-written template, not the model. Two guards wrap the call:
structured outputs constrain the response to the schema, and a
validate → repair loop feeds any physics/API errors back to the model
(up to --max-repair rounds) before a spec reaches the renderer.
Why this is the safe design
- No hallucinated API. Method names, argument names, and the calcium-first
model structure are fixed in
render.py. The model can't inventneuron.setCalcium(). - Silent-no-op trap closed. SPINE builds the IP3 receptor from
model['IP3']and never reads anIP3Rflag. A naive generator copying the docs would setmodel['IP3R']=Trueand get no receptor. The validator detectsIP3Rin the mechanism list and enablesIP3instead, with a warning. - Physics consistency is checked, not assumed. Ionic currents / VDCC
without voltage coupling,
dt >= T, out-of-range stimulus nodes, a largedton a stiff Na⁺ membrane without the implicit solver — all caught before a line is emitted. - Over-generation is contained. Weak models tend to bolt on things nobody
asked for. A concentration outside the physical µmol/µm³ range (a model
writing
1.0/5.0instead of~1e-16) is rejected with a unit reminder; anetworkwith no connections is dropped to a single neuron; and a spec with no recording is defaulted to the calcium field + soma so the run isn't empty. - Assumptions are surfaced. Every generated script carries an
Assumptionsblock (calcium always solved, source-default kinetics, unit conventions) so a non-expert isn't trusting a black box.
Usage
cd tools
# See what an LLM would be constrained to emit:
python -m spine_assistant schema
# Check / explain a spec before building:
python -m spine_assistant validate spine_assistant/specs/active_ap.json
python -m spine_assistant explain spine_assistant/specs/calcium_wave.json
# Render a runnable script from a hand-written spec:
python -m spine_assistant build spine_assistant/specs/calcium_wave.json -o run.py
python run.py
# "Click and talk" — the local web UI (recommended for non-experts):
python -m spine_assistant serve # opens http://127.0.0.1:8765
# Or one-shot from the terminal (local Ollama model by default, no key):
python -m spine_assistant generate \
"a calcium wave triggered by a synapse at the tip of a 100um dendrite" \
-o run.py --spec-out run.spec.json
specs/_invalid_demo.json is intentionally broken — run validate on it to see
every check fire.
serve — the click-and-talk web UI
python -m spine_assistant serve launches a single local page (stdlib only, no
framework). Type or click the mic and speak the experiment (browser Web
Speech API); it shows the plain-language interpretation, any warnings, and the
generated script. The script box is editable — fix anything by hand before
running, and Copy, Download, and Run all use exactly what is shown. Everything
runs on 127.0.0.1; with the default Ollama provider nothing leaves the machine.
The page mirrors the CLI's two input paths as buttons:
- 📄 Load request… reads a natural-language
.txt/.mdfile into the box (client-side; same as the CLI'sgenerate --file). - 🧩 Build from spec… renders a runnable script directly from a saved
.jsonspec — no model, fully reproducible (the CLI'sbuild). It posts to/api/build, which only validates and renders.
The AI model field auto-detects installed models for the selected backend
(via Ollama's /api/tags or the OpenAI-compatible /models) and offers them as
a dropdown; you can still type any name, and ↻ re-detects. Detection is
best-effort — if the server isn't up, the field just falls back to free text.
No command line at all. launchers/ holds double-clickable shortcuts
(SPINE Assistant.command for macOS/Linux, SPINE Assistant.bat for Windows)
that start serve and open the browser for you. They still assume Python + the
package are installed — a genuinely zero-install double-click needs a signed
packaged app; see launchers/README.md.
Run it here (closing the loop). Once a script is generated it is shown, not
run. A ▶ Run this script button appears below the code — running is a
separate, deliberate step, so you can read the script, tweak your prompt, and
regenerate as many times as you like before anything executes. Clicking it asks
you to confirm (“Yes, run it”, with an optional don't ask again this
session); only then does it execute the script in an isolated temp directory.
A live terminal then streams the run as it happens — it first echoes the
exact command (python -u run.py and the working dir) so you can confirm what
is executing, then the solver's output line by line — followed by the exit
status, the output files, and a .zip of the results.
Because this runs generated code, the confirmation — not a pre-checked box —
is the opt-in, so consent happens after you've seen the code. The gate is
server-enforced: /api/run refuses until that confirmation arms the server,
so the clickable launcher needs no flag and never runs anything on its own.
python -m spine_assistant serve # Run button asks to confirm before executing
python -m spine_assistant serve --allow-run # pre-confirm at launch (container/automation)
python -m spine_assistant serve --no-run # forbid running entirely; Run button disabled
python -m spine_assistant serve --provider anthropic # use Claude instead of Ollama
MCP server (use it from LM Studio / Claude Desktop)
The deterministic pipeline can also be exposed as an MCP server, so an MCP host's own model calls it as tools (the inverse of the usual setup — the model orchestrates, the tools validate/render deterministically, and the model still never writes SPINE code):
Simplest path (two commands, no path-hunting or JSON editing):
pip install "./tools[mcp]" # the optional 'mcp' dependency
spine-assistant mcp --install-lmstudio # adds 'spine' to LM Studio's mcp.json (backs it up)
then restart LM Studio. If it can't find LM Studio's config, it prints the exact
block to paste. To just verify the install: spine-assistant mcp --check. To
print the ready-to-paste config yourself: spine-assistant mcp --config.
Tools: validate_spine_spec, render_spine_script (spec → runnable script, no
model), build_spine_channel (a paste-ready catalog channel class), and
build_spine_custom_channel (a channel from your own Hodgkin–Huxley gate
kinetics — for anything outside the catalog). Resources: spine://catalog,
spine://schema, spine://reference, and spine://guide. The host's model does
the natural-language → spec step; these tools do the rest.
spine://guide exists to stop a common host-model mistake: assuming a channel
that is not in the named catalog is impossible or needs NMODL/NEURON. It never
is. SPINE is a native solver — the classic HH currents (fast Na⁺, delayed
rectifier Kd, leak) are built in via a spec's currents field, voltage-gated
calcium channels via vdcc_type/vdcc_extra, named channels via
catalog_channels, and everything else via build_spine_custom_channel /
custom_channels. No .mod files, no NEURON, ever.
Units. Papers quote mV / ms / per-cm²; SPINE uses V / s / per-µm². The
validator guards against the transcription slip: an E_rev above 1 V is read as
millivolts and repaired to volts, while an out-of-scale g_max or a tau above
a second raises a warning with the exact conversion (E_rev, tau: ÷1000;
rates: ×1000; g_max: S/cm²→÷1e8). So a model that free-writes a channel from a
paper is steered to SI instead of silently producing a run that diverges.
Don't run spine-assistant mcp by hand to "use" it — an stdio server has no
output; it blocks waiting for a client. The MCP host launches it. Use --check
to confirm it works.
LM Studio (Program → Edit mcp.json) or Claude Desktop config. Use absolute
paths — the host does not inherit your shell PATH (this matters especially in
a conda/venv, where a bare spine-assistant won't be found):
{ "mcpServers": {
"spine": { "command": "/full/path/to/env/bin/spine-assistant", "args": ["mcp"] }
} }
Find the path with which spine-assistant (or, equivalently, use the
interpreter: "command": "/full/path/to/python", "args": ["-m", "spine_assistant", "mcp"]).
The mcp/fastmcp package must be installed in that same environment —
spine-assistant mcp --check prints which python it uses.
No code-execution tool is exposed — the server returns the script; running it stays a deliberate step (as with the web UI's Run button).
Plug-and-play container
The docker/Dockerfile bundles SPINE + the assistant + the web UI and runs the
whole loop in the container — no local Python, no model download, no GPU.
Claude-first, so the image stays small (nothing to bundle but the code):
# from the repo root:
docker build -f tools/spine_assistant/docker/Dockerfile -t spine-assistant .
docker run --rm -e ANTHROPIC_API_KEY=sk-ant-... -p 8765:8765 spine-assistant
# open http://127.0.0.1:8765
Fully local instead (no key, no cost): run Ollama on the host and point the
container at it —
docker run -e SPINE_PROVIDER=ollama -e OLLAMA_HOST=http://host.docker.internal:11434 -p 8765:8765 spine-assistant.
Install as a command
pipx install ./tools # the `spine-assistant` CLI (needs NumPy)
pipx install "./tools[anthropic]" # + the hosted Claude backend
SPINE itself is a separate install (needed only to run the generated
scripts, e.g. under serve --allow-run).
generate — one-shot from the terminal
Turns a sentence into a spec, validates it (repairing up to --max-repair
times), and renders the script. It prints the interpretation and warnings to
stderr so you can sanity-check the model's reading before running the code.
- Provider defaults to
ollama(local, free): install Ollama, runollama pull qwen2.5(the default model — it follows the constrained spec schema better than llama3.1, which tends to over-fill optional fields on simple prompts), andgenerate/servejust work — no key, no cost. With no server reachable it exits with an actionable message and code 2. --provider openaitargets any OpenAI-compatible server — LM Studio (default,http://localhost:1234/v1), llama.cpp'sserver, Jan, vLLM, or hosted OpenAI/OpenRouter. Retarget withOPENAI_BASE_URL(andOPENAI_API_KEYfor hosted). LM Studio serves the loaded model, so--modelis optional there.--provider anthropicuses the hosted API instead (ANTHROPIC_API_KEYor anant auth loginprofile);--modeloverrides any default.- Pick a model to fit your hardware. Size drives speed: on a thin laptop use
a 3B model (
--model llama3.2:3borqwen2.5:3b); on a desktopqwen2.5(7B, default) orqwen2.5:14b; on a workstationqwen2.5:32b; or Claude for no local compute. If a local model is disastrously slow, drop to a smaller size or switch providers — it is not a fault in the assistant. - No network needed to trust it:
python -m spine_assistant.test_llm_offlineruns the whole pipeline (LLM wiring + forced repair, kinetics-safety rejection, custom-channel render, web pipeline) against stubs — no key, no model.
Custom channels & kinetics (the hard part, made safe)
Writing a custom ion channel or a novel calcium pump is exactly what non-experts can't do by hand — and where an LLM emitting raw Python would be most dangerous. So kinetics are treated as data, not code (the NMODL approach): a rate formula is parsed to an AST, checked against a whitelist (only arithmetic and a fixed set of math functions over the declared variables), numerically sanity-checked on a grid, and only then rewritten into the generated channel class. Anything else — imports, attribute access, calls to unknown names, comprehensions — is rejected before it reaches the renderer.
- Custom channels (
custom_channels) render a realChannelModelsubclass: ohmiccompute_current/conductancein Volts, gates with kinetics in mV / (µmol·µm⁻³) returning(x_inf, tau_seconds). A calcium-activated channel (SK/BK) is just a gate whosex_infdepends onC— seespecs/custom_sk_channel.json, which runs end-to-end against SPINE. - Custom mechanisms (
custom_mechanisms) render aPMFluxMechanism/ERFluxMechanismsubclass returning an unsigned magnitude; thesignfield does the routing (+1 influx / −1 efflux), matching SPINE's orchestrator.
The units are the trap here, so the generated script's assumptions block and the model's system prompt both state them explicitly.
Files
| File | Role |
|---|---|
schema.py |
Allowed vocabulary + defaults + the JSON Schema an LLM targets |
validate.py |
Physics/API consistency checks → errors, warnings, assumptions |
render.py |
Deterministic spec → SPINE script (the only place code is emitted) |
kinetics.py |
Safe AST-whitelist compiler for custom rate/flux expressions |
explain.py |
Plain-language summary of a spec (teach, don't just emit) |
llm.py |
Natural language → spec (local Ollama or OpenAI-compatible/LM Studio, or hosted Claude; structured outputs + repair loop + few-shot) |
retrieval.py |
Dependency-free TF-IDF retrieval over dataset/ — picks similar request→spec pairs for few-shot prompting |
webapp.py |
Local click-and-talk web UI + in-place run loop (stdlib http.server + Web Speech API) |
cli.py |
generate / serve / build / validate / explain / schema |
docker/ |
Claude-first Dockerfile that runs the whole loop in a container |
launchers/ |
Double-clickable shortcuts (.command/.bat) that open the web UI, no CLI |
dataset/ |
Validated request→spec corpus (few-shot/RAG + fine-tuning seed); build_dataset.py authors and verifies it |
test_llm_offline.py |
Offline stub tests (wiring, kinetics safety, custom channel, webapp, run loop) |
specs/ |
Example specs, including a custom-channel demo and an invalid one |
../pyproject.toml |
Installable package + spine-assistant entry point (in tools/) |
What is deliberately out of scope
- The GPU batch backend. Networks and single neurons run on the serial/MPI
CPU path (
solveauto-detectsmpirun); thebackend='gpu'batched path is not generated — it needs batch channel methods and a device-partitioned neuron list. Custom channels/mechanisms likewise render for the serial/MPI path only. - Non-smooth kinetics. The expression grammar is smooth arithmetic + standard functions (exp, log, sqrt, tanh, …). Piecewise/discontinuous rate laws aren't expressible; use a smooth approximation or hand-write the channel.
Verified against source
Every enum in schema.py was checked against src/spine, and the generated
scripts were executed against an editable install: all imports resolve,
build_neuron() constructs for all example specs, and short specs run full
solves to completion — including a custom calcium-activated channel and a
custom PM flux mechanism, each producing cyt.txt, per-node traces, and VTU
output. The LLM front-end, the kinetics-safety whitelist, and the web pipeline
are verified offline via test_llm_offline.py, and the Ollama wire format was
checked against a stub server — so the whole thing is auditable without a live
key or model.
Metadata
Release files for spine-assistant 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| spine_assistant-0.1.0.tar.gz | 216.9 kB | Without provenance | Details for spine_assistant-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spine_assistant-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for spine_assistant-0.1.0-py3-none-any.whl |
Total release size: 600.5 kB
Release files / spine_assistant-0.1.0.tar.gz
| Download URL | spine_assistant-0.1.0.tar.gz |
|---|---|
| Size | 216.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
451d542c20613a5405d22070ceb926fcbb0419a289be3952713cc741fc372af3
|
|
BLAKE2b-256 checksum How to use checksums |
5d367a80bdb58194b0911401f4dbe0b34dacea78f58e7befe9154bc03b6b3308
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.9
|
Release files / spine_assistant-0.1.0-py3-none-any.whl
| Download URL | spine_assistant-0.1.0-py3-none-any.whl |
|---|---|
| Size | 383.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b05fcccb06fcdfcf890bb6c13deb2ce3cc9b1960c9f666673019866608441535
|
|
BLAKE2b-256 checksum How to use checksums |
683aab2b9dcf97697d98cb3027968803809c30cd7e7ce9751f230ad41dffc362
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.9
|
Security for spine-assistant 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.