Skip to main content

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 invent neuron.setCalcium().
  • Silent-no-op trap closed. SPINE builds the IP3 receptor from model['IP3'] and never reads an IP3R flag. A naive generator copying the docs would set model['IP3R']=True and get no receptor. The validator detects IP3R in the mechanism list and enables IP3 instead, with a warning.
  • Physics consistency is checked, not assumed. Ionic currents / VDCC without voltage coupling, dt >= T, out-of-range stimulus nodes, a large dt on 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.0 instead of ~1e-16) is rejected with a unit reminder; a network with 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 Assumptions block (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/.md file into the box (client-side; same as the CLI's generate --file).
  • 🧩 Build from spec… renders a runnable script directly from a saved .json spec — no model, fully reproducible (the CLI's build). 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, run ollama 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), and generate/serve just work — no key, no cost. With no server reachable it exits with an actionable message and code 2.
  • --provider openai targets any OpenAI-compatible server — LM Studio (default, http://localhost:1234/v1), llama.cpp's server, Jan, vLLM, or hosted OpenAI/OpenRouter. Retarget with OPENAI_BASE_URL (and OPENAI_API_KEY for hosted). LM Studio serves the loaded model, so --model is optional there.
  • --provider anthropic uses the hosted API instead (ANTHROPIC_API_KEY or an ant auth login profile); --model overrides any default.
  • Pick a model to fit your hardware. Size drives speed: on a thin laptop use a 3B model (--model llama3.2:3b or qwen2.5:3b); on a desktop qwen2.5 (7B, default) or qwen2.5:14b; on a workstation qwen2.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_offline runs 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 real ChannelModel subclass: ohmic compute_current/conductance in Volts, gates with kinetics in mV / (µmol·µm⁻³) returning (x_inf, tau_seconds). A calcium-activated channel (SK/BK) is just a gate whose x_inf depends on C — see specs/custom_sk_channel.json, which runs end-to-end against SPINE.
  • Custom mechanisms (custom_mechanisms) render a PMFluxMechanism / ERFluxMechanism subclass returning an unsigned magnitude; the sign field 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 (solve auto-detects mpirun); the backend='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)

Source distribution for spine-assistant 0.1.0
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)

Table of built distributions (wheels) for spine-assistant 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page