spine-assistant
Turns a short JSON specification of an experiment into a runnable SPINE script. An LLM can write the specification from a sentence. The script comes from a template, so the model never writes SPINE code.
By default it talks to a local Ollama model: no API key, no cost, nothing leaves your machine. A hosted provider (Anthropic) is optional.
Installation
pip install spine-assistant
This installs the spine-assistant command (Python ≥ 3.10, NumPy). Extras:
pip install "spine-assistant[anthropic]" # hosted Claude backend
pip install "spine-assistant[mcp]" # MCP server
pipx install spine-assistant installs the command into its own environment. Running the generated scripts needs SPINE (pip install spine-neuro). The SPINE User Guide has a chapter on the assistant: https://zacharymiksis.com/research/software/.
Start the web UI with spine-assistant serve.
How it works
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)
The model fills a typed spec. Structured outputs constrain its response to the schema. Validation errors go back to it for up to --max-repair rounds before the spec reaches the renderer.
Before each call, the most similar request/spec pairs from dataset/ are retrieved by TF-IDF (retrieval.py) and shown to the model as few-shot examples. generate --examples N sets how many; 0 disables them.
What the validator checks
- Method names, argument names and the calcium-first model structure are fixed in
render.py. IP3Rin a mechanism list enablesIP3, with a warning. SPINE builds the IP3 receptor frommodel['IP3']and has noIP3Rflag.- Ionic currents or VDCC without voltage coupling,
dt >= T, stimulus nodes out of range, and a largedton a stiff Na⁺ membrane without the implicit solver are errors. - A concentration outside the µmol/µm³ range is rejected with a unit reminder.
- A
networkwithout connections becomes a single neuron. A spec without a recording gets the calcium field and the soma. - Every generated script carries an
Assumptionsblock: calcium solved, source-default kinetics, units.
Usage
# The JSON Schema an LLM targets:
spine-assistant schema
# The example specs ship with the package:
SPECS=$(python -c "import spine_assistant, pathlib; print(pathlib.Path(spine_assistant.__file__).parent / 'specs')")
# Check and explain a spec:
spine-assistant validate "$SPECS/active_ap.json"
spine-assistant explain "$SPECS/calcium_wave.json"
# Render a script from a hand-written spec:
spine-assistant build "$SPECS/calcium_wave.json" -o run.py
python run.py
# The local web UI:
spine-assistant serve # opens http://127.0.0.1:8765
# One-shot from the terminal (local Ollama model by default):
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 broken on purpose. Run validate on it to see every check fire.
Web UI
spine-assistant serve starts a local page (standard library only). Type an experiment or dictate it with the browser's Web Speech API. The page shows the interpretation, any warnings and the generated script. The script box is editable, and Copy, Download and Run use what it shows. Everything runs on 127.0.0.1; with the default Ollama provider nothing leaves your machine.
- 📄 Load request… reads a
.txtor.mdrequest into the box, likegenerate --file. - 🧩 Build from spec… renders a script from a saved
.jsonspec without a model, likebuild. It posts to/api/build, which only validates and renders.
The AI model field lists the models found on the selected backend (Ollama /api/tags or the OpenAI-compatible /models). You can type any name, and ↻ detects again. If the server is down, the field takes free text.
The launchers/ folder of the source archive (Zenodo, DOI 10.5281/zenodo.24226059) holds double-click shortcuts, SPINE Assistant.command for macOS and Linux and SPINE Assistant.bat for Windows. They start serve and open the browser, and need Python and the package installed (see launchers/README.md).
Running scripts. A generated script is shown but not run. ▶ Run this script appears below it. A click asks for confirmation (with an option to stop asking for the session), then runs the script in a temporary directory. A terminal panel streams the command, the solver output, the exit status, the output files and a .zip of the results. The server refuses /api/run until the confirmation arms it.
spine-assistant serve # Run asks to confirm before executing
spine-assistant serve --allow-run # pre-confirm at launch (container, automation)
spine-assistant serve --no-run # Run disabled
spine-assistant serve --provider anthropic # Claude instead of Ollama
MCP server
spine-assistant mcp exposes the pipeline as MCP tools, so the model of an MCP host (LM Studio, Claude Desktop) can call them. The host's model writes the spec. The tools validate and render it.
pip install "spine-assistant[mcp]"
spine-assistant mcp --install-lmstudio # adds 'spine' to LM Studio's mcp.json (backs it up)
Restart LM Studio afterward. If the command cannot find LM Studio's config, it prints the block to paste. spine-assistant mcp --check verifies the install, and --config prints the config.
Tools: validate_spine_spec, render_spine_script (spec to script, no model), build_spine_channel (a catalog channel class) and build_spine_custom_channel (a channel from your own Hodgkin–Huxley gate kinetics). Resources: spine://catalog, spine://schema, spine://reference and spine://guide.
spine://guide tells the host's model that channels outside the named catalog are supported. The classic HH currents (fast Na⁺, delayed rectifier Kd, leak) come from a spec's currents field, voltage-gated calcium channels from vdcc_type and vdcc_extra, named channels from catalog_channels, and anything else from build_spine_custom_channel or custom_channels. SPINE needs no .mod files and no NEURON.
Units. Papers quote mV, ms and per-cm². SPINE uses V, s and per-µm². An E_rev above 1 V is read as millivolts and converted to volts. An out-of-scale g_max or a tau above a second raises a warning with the conversion (E_rev, tau: ÷1000; rates: ×1000; g_max: S/cm² → ÷1e8).
Run spine-assistant mcp only from the host. A stdio server has no output and waits for a client. Use --check to test it.
Configure LM Studio (Program → Edit mcp.json) or Claude Desktop with absolute paths. The host does not inherit your shell PATH, which matters in a conda or venv environment:
{ "mcpServers": {
"spine": { "command": "/full/path/to/env/bin/spine-assistant", "args": ["mcp"] }
} }
Find the path with which spine-assistant, or launch through the interpreter: "command": "/full/path/to/python", "args": ["-m", "spine_assistant", "mcp"]. The mcp package must be installed in that environment; spine-assistant mcp --check prints which python it uses.
The server exposes no code-execution tool. It returns the script, and you run it.
Docker
The docker/Dockerfile of the source archive (Zenodo, DOI 10.5281/zenodo.24226059) builds an image with SPINE, the assistant and the web UI, and runs the whole loop in the container: no local Python, no model download, no GPU. It defaults to Claude, which keeps the image small.
# from the top folder of the source archive:
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
For a fully local setup, 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.
generate
generate 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 check the model's reading before running the code.
- The default provider is
ollama: install Ollama and runollama pull qwen2.5, the default model. It follows the spec schema better thanllama3.1.generateandservethen work with no key. With no server reachable they exit with a 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 and OpenRouter. SetOPENAI_BASE_URLto retarget, andOPENAI_API_KEYfor hosted servers. LM Studio serves the loaded model, so--modelis optional there.--provider anthropicuses the hosted API withANTHROPIC_API_KEYor anant auth loginprofile.--modeloverrides any default.- Model size sets speed. Thin laptop: a 3B model (
--model llama3.2:3borqwen2.5:3b). Desktop:qwen2.5(7B, the default) orqwen2.5:14b. Workstation:qwen2.5:32b. No local compute: Claude. If a local model is too slow, use a smaller size or another provider. python -m spine_assistant.test_llm_offlineruns the pipeline against stubs with no key and no model: LLM wiring with a forced repair, kinetics-safety rejection, a custom-channel render and the web pipeline.
Custom channels and kinetics
Rate formulas are data. A formula is parsed to an AST, checked against a whitelist (arithmetic and a fixed set of math functions over the declared variables), sanity-checked numerically on a grid, and rewritten into the generated channel class. Imports, attribute access, calls to unknown names and comprehensions are rejected before rendering.
custom_channelsrender aChannelModelsubclass: ohmiccompute_currentandconductancein volts, and gates with kinetics in mV and µmol·µm⁻³ that return(x_inf, tau_seconds). A calcium-activated channel (SK, BK) is a gate whosex_infdepends onC; seespecs/custom_sk_channel.json.custom_mechanismsrender aPMFluxMechanismorERFluxMechanismsubclass that returns an unsigned magnitude. Thesignfield routes it (+1 influx, −1 efflux).
The generated script's assumptions block and the model's system prompt state the units.
Files
The package holds the modules below. docker/, launchers/ and ../pyproject.toml are in the source archive only.
| File | Role |
|---|---|
schema.py |
Allowed vocabulary, defaults and the JSON Schema an LLM targets |
validate.py |
Physics and API consistency checks: errors, warnings, assumptions |
render.py |
Deterministic spec → SPINE script; the only place code is emitted |
kinetics.py |
AST-whitelist compiler for custom rate and flux expressions |
explain.py |
Plain-language summary of a spec |
llm.py |
Natural language → spec: Ollama, OpenAI-compatible servers (LM Studio) or Claude; structured outputs, repair loop, few-shot examples |
retrieval.py |
TF-IDF retrieval over dataset/ for the few-shot examples |
webapp.py |
Local web UI and run loop (http.server, Web Speech API) |
mcp_server.py |
The MCP server |
cli.py |
generate, serve, build, validate, explain, schema, mcp |
docker/ |
Dockerfile that runs the whole loop in a container |
launchers/ |
Double-click shortcuts (.command, .bat) that open the web UI |
dataset/ |
Validated request → spec corpus for few-shot retrieval and fine-tuning; build_dataset.py authors and verifies it |
test_llm_offline.py |
Offline stub tests: wiring, kinetics safety, custom channel, web app, run loop |
specs/ |
Example specs, including a custom-channel demo and an invalid one |
../pyproject.toml |
The installable package and the spine-assistant entry point (in tools/) |
Limits
- No GPU batch backend. Networks and single neurons render for the serial and MPI CPU path (
solvedetectsmpirun). The batchedbackend='gpu'path needs batch channel methods and a device-partitioned neuron list, so it is not generated. Custom channels and mechanisms render for the serial and MPI path only. - Smooth kinetics only. The expression grammar is arithmetic plus standard functions (exp, log, sqrt, tanh, …). Piecewise rate laws are not expressible; use a smooth approximation or write the channel by hand.
Metadata
Release files for spine-assistant 0.1.0.post1
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.post1.tar.gz | 212.7 kB | Without provenance | Details for spine_assistant-0.1.0.post1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| spine_assistant-0.1.0.post1-py3-none-any.whl | Python 3 | none | any | Details for spine_assistant-0.1.0.post1-py3-none-any.whl |
Total release size: 592.0 kB
Release files / spine_assistant-0.1.0.post1.tar.gz
| Download URL | spine_assistant-0.1.0.post1.tar.gz |
|---|---|
| Size | 212.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49097cfbc744c302b27e40b0bdd69b8942552852f3553fe58f81f0b7de17aeb7
|
|
BLAKE2b-256 checksum How to use checksums |
ef7a53ccc83b9b94deec3c38a0a6cc2a9a1e08b4998d9dbee8b4ce1031a54305
|
| 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.post1-py3-none-any.whl
| Download URL | spine_assistant-0.1.0.post1-py3-none-any.whl |
|---|---|
| Size | 379.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5e350ac5e85bad1f9271aad513c7d995fc2d2e75dfa94dd72b4036a0ea744815
|
|
BLAKE2b-256 checksum How to use checksums |
0739f5c54f834f310b9c555104dbdc5981e6190d3f6f5d3dc2e3f91b7bb4384d
|
| 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.post1
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.