Metadata-Version: 2.4
Name: spine-assistant
Version: 0.1.0
Summary: Natural-language-to-script assistant for the SPINE neuronal simulator
Author: Zachary M. Miksis, Gillian Queisser
Maintainer-email: "Zachary M. Miksis" <miksis@temple.edu>
License-Expression: LGPL-3.0-or-later
Keywords: neuroscience,simulation,SPINE,assistant,code generation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: numpy>=2.2.4
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == "anthropic"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Dynamic: license-file

# 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](https://ollama.com) 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

```bash
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.

```bash
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](https://modelcontextprotocol.io)
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):

```bash
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):

```json
{ "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):

```bash
# 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

```bash
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.
