User guide¶
What you get¶
pip install sweepx brings the sweep-agent CLI, the ~30-tool registry, the core
solver and the production runner (sweepx.tasks). Discovery, inspection, plotting,
forward modelling (acoustic + elastic), benchmark models and FWI / LSRTM
(build_*_spec, run_task, run_fwi, run_multiscale_fwi, …) all work. The
simulations take the GPU when the machine has one — the CUDA kernels for the
equations that have them, eager torch for the rest and for wavefield snapshots —
and the CPU or Apple's MPS otherwise; device / backend_impl override that.
A tool whose dependencies fail to import returns {"error": "… is not importable"}
rather than crashing — the agent stays up, and tools not offered this turn are
rejected (no hallucinated calls). An argument a tool does not take is an error
that names the tool's arguments, so a misspelt one is never dropped silently.
LLM backends¶
Chat needs any OpenAI-compatible endpoint with a 32k-token context. chat /
ui are zero-config by default (auto-detect Ollama / vLLM, use the model the
server serves; on Ollama pick a 7B and pull it on first run). To switch to
any other backend — a remote vLLM, a hosted endpoint, llama.cpp, LM Studio — pass
--url / --model / --api-key, or set the environment variables:
export SWEEP_AGENT_LLM_URL=... # or --url
export SWEEP_AGENT_LLM_MODEL=... # or --model
export SWEEP_AGENT_LLM_API_KEY=... # or --api-key
For a fully custom backend, subclass BaseLLM from sweepx.agent.llm.
Model quality matters for tool-calling
Heavily-quantized (Q4) local models are weaker at tool-calling and can drift
language. Prefer -q8_0, a larger model, or a full-precision vLLM endpoint.
Tools as functions¶
Every tool is a plain callable (.fn) with a pydantic params model, so the whole
toolset is usable from scripts and tests without an LLM:
from sweepx.agent.tools.inspect import inspect_file, InspectFileParams
print(inspect_file.fn(InspectFileParams(path="vp_init.npy")))
See the API reference for the full list.