nxspice

AI-native SPICE simulation & power-electronics design platform. ngspice + Xyce + Octave as deterministic ground truth; LangGraph agents as orchestrators. Every reported number traces to a closed form in nxspice/math/ or to an engine measurement in the pinned container; every citation resolves against a knowledge pack or an ingested book.

Personal + OSS. CLI-first / API-first / MCP + A2A.

See PLAN.md for the roadmap, SESSION_STATE.md for status, and docs/user-guide.md for capabilities and documented limits.

Quickstart

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
docker build -f docker/engines.Dockerfile -t nxspice/engines:0.1 docker/   # ngspice + octave
pytest

Design + report a spec (REST job, CLI, or MCP — the same pipeline):

nxspice report --vin 12 --vout 1.2 --iout 10 --fsw 500e3 -o out/
nxspice survey --vin 48 --vout 12 --iout 10 --fsw 200e3 --isolation
nxspice example list && nxspice example run buck-flagship-12v

Interfaces

nxspice version                # print the installed version
nxspice doctor                 # engine availability
nxspice report                 # design loop -> LaTeX/HTML/Markdown reports
nxspice survey                 # topology screening + ranking (no LLMs needed)
nxspice serve --port 8787      # REST/SSE API + web console at http://127.0.0.1:8787/
nxspice mcp                    # MCP stdio server (design / run / report / job / book_*)
nxspice jobs submit --wait     # SDK-backed job control against a server
nxspice book search <query>    # deterministic book-RAG retrieval (cited passages)

Job kinds: design (loop + JSON digest), report (loop/digest + rendered report), topologies (per-topology digest). REST: POST /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/events (SSE), GET /v1/jobs/{id}/artifacts/{name}. Python SDK:

from nxspice.api.sdk import NxspiceClient

client.report(spec, out_dir)   # the two-line path

The report content-model JSON is the stable job artifact: re-render without re-simulating.

What a PASS means

A report job's verification pack carries two check classes, and a PASS requires both: spec-compliance (engine vs requirement — output voltage within 5 % of spec.vout, ripple within spec.ripple_voltage when given) and model fidelity (engine vs the design's own analytic targets). Current and stress are engine-measured too (peak/RMS inductor current, switch current, time-weighted dissipation; the Isat gate has zero tolerance). See docs/user-guide.md §3 for the full gate list and §5 for documented limits.

Structure

nxspice/core/netlist    SPICE IR, values, deterministic generators
nxspice/core/models     canonical model library (IR, flavors, validation, seed parts)
nxspice/core/engines    ngspice / Xyce(stub) adapters, docker runner (resource-limited)
nxspice/core/extract    raw-file parser, engine-neutral SimResult, FFT / bode measures
nxspice/core/storage    artifact store, spec model
nxspice/math            buck design, averaged plants, magnetics, EMC filters, topologies
nxspice/agents          knowledge packs, budgets, audit, routing, design loop, example corpus
nxspice/reporting       results content model + LaTeX/HTML renderers
nxspice/api             REST/SSE + SDK + MCP server + A2A + web console
nxspice/cli             typer CLI: report / survey / serve / mcp / jobs / book / example
docs/                   user guide, loop architecture, flavor status, reviews
tests/                  unit + docker golden suite + offline loop oracle

Packaging

pip install nxspice ships the Python package plus its runtime data: the knowledge packs, the seed model library, the routing example, the committed book fixtures, the web console assets, and the worked-example corpus. The version is single-sourced from nxspice.__version__ (pyproject.toml dynamic = ["version"]); the type marker py.typed is included, so downstream users get types under mypy --strict.

Gates

tools/gate.sh runs the same checks CI enforces (ruff → ruff format → mypy --strict → pytest), plus the docker-marked integration tests when the engines image is present. Full pytest needs a 3000 s budget (docker engine gates included). CI: .github/workflows/ci.yml.