gsas2-query — GSAS-II Documentation Assistant

Semantic search + AI answers over the GSAS-II documentation set: 128 HTML pages by default (home, help, and all 64 tutorials), with the Developer's Guide and Powder Crystallography textbook available as optional additions (see Doc sources).

Answers include inline citations — every [N] in the response is a clickable link to the exact documentation section that supported that sentence.

All embedding and retrieval runs on your machine — no data is sent externally unless you explicitly choose the Anthropic API backend.

Authors

Pawan K. Tripathi — X-ray Science Division, Argonne National Laboratory (ptripathi@anl.gov)
Mathew J. Cherukara — X-ray Science Division, Argonne National Laboratory (mcherukara@anl.gov)
Brian H. Toby — X-ray Science Division, Argonne National Laboratory (toby@anl.gov)

Installation

pip

pip install gsas2-query

Or install directly from source:

pip install git+https://github.com/AdvancedPhotonSource/Query-GSAS-II.git

conda

conda install -c conda-forge gsas2-query

Into an existing GSAS-II environment

# Activate the GSAS-II conda environment first, then:
pip install gsas2-query

Development / editable install

git clone https://github.com/AdvancedPhotonSource/Query-GSAS-II.git
cd Query-GSAS-II
pip install -e ".[dev]"

Ollama — free local LLM (recommended when llama.cpp is not installed)

brew install ollama          # macOS; see https://ollama.com for other platforms
ollama serve &               # start the local server
ollama pull llama3           # ~5 GB one-time download

Other model options: llama3:70b (better quality, ~40 GB), mistral (faster, ~4 GB).

llama-cpp-python — in-process local LLM (auto-selected when installed)

llama-cpp-python runs a GGUF model directly inside the Python process — no separate server required. It is cross-platform and available from conda-forge.

When llama-cpp-python is importable, gsas2-query selects it automatically without any LLM_BACKEND setting.

Install

conda install -c conda-forge llama-cpp-python   # recommended
# or:
pip install "gsas2-query[llama_cpp]"

Download a GGUF model

Download any GGUF-format model from Hugging Face, for example:

# Llama 3.1 8B (Q4_K_M quantisation, ~5 GB):
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf

Configure

Set the model path in your .env or environment:

LLAMA_CPP_MODEL=/path/to/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf
# Optional tuning:
# LLAMA_CPP_N_CTX=4096       # context window (default: 4096)
# LLAMA_CPP_MAX_TOKENS=1500  # max tokens to generate (default: 1500)

First-time setup — index the documentation

Run once, or again when the docs are updated. Fetches ~128 HTML pages (home, help, and all tutorials) and embeds everything locally. Takes roughly 10–20 minutes.

By default the index is stored in ~/.GSASII/query_gsas2/chroma_db (see User data directory for details).

gsas2-query --setup              # default sources (home, help, tutorials)
gsas2-query --setup --html-only  # skip PDF ingestion (PDFs are not used by default anyway)
gsas2-query --setup --reset      # drop index and rebuild from scratch

The default index is tens of MB. The Developer's Guide and Powder Crystallography textbook are not included by the gsas2-query CLI's --setup — they're opt-in via the standalone ingestion script (python -m gsas_query.ingest --manual --book), which is what builds the full ~324-source, ~65 MB index described in the project's paper and used for the pre-built index released on GitHub (see Re-indexing when docs update).

Usage

Command-line — single question

gsas2-query "How do I set up a sequential refinement?"
gsas2-query "What parameters control the background in Rietveld?"
gsas2-query "How do I export a CIF for publication?"

Command-line — interactive REPL

Multi-turn conversation that remembers previous questions in the session.

gsas2-query

GSAS-II Documentation Assistant
════════════════════════════════════════════════════════════════════════════════

Knowledge base: 2,336 indexed chunks.
LLM backend: ollama
Type your question and press Enter. 'clear' resets history, 'quit' exits.

────────────────────────────────────────────────────────────────────────────────
You: How do I constrain lattice parameters?
Thinking…
Assistant: To constrain lattice parameters in GSAS-II, open the Constraints
tab in the Phase panel [1]…

Sources:
  [94%] Help: Phase General  ›  Constraints
         https://advancedphotonsource.github.io/GSAS-II-tutorials/help/phasegeneral.html

Commands inside the REPL: clear (reset history), quit / exit (exit).

Desktop GUI

Opens a standalone floating dialog — stays open while you work in GSAS-II.

gsas2-query --gui

Embed in GSAS-II Help menu

Add one call to the GSAS-II menu handler (e.g. in GSASIIctrl.py):

def OnDocAssistant(self, event):
    try:
        from gsas_query.gui import show_assistant
        show_assistant(self)          # self = GSAS-II main frame
    except ImportError:
        wx.MessageBox(
            "GSAS-II Assistant not installed.\n"
            "Run: pip install gsas2-query",
            "Not available"
        )

show_assistant() is idempotent — calling it a second time raises the existing window rather than opening a duplicate.

Web UI

gsas2-query-web                          # serves on 0.0.0.0:8000
HOST=127.0.0.1 PORT=8765 gsas2-query-web

Then open http://localhost:8000 in a browser. The web UI shows inline citations as clickable superscript links and source chips below each answer.

CLI flags reference

Flag	Description
`--setup`	Index all documentation sources
`--setup --reset`	Drop the existing index and rebuild
`--setup --html-only`	Index HTML only, skip PDFs
`--gui`	Open the wxPython desktop assistant
`--backend ollama\|anthropic\|retrieval\|llama_cpp`	Override `LLM_BACKEND` env var
`--model <name>`	Override OLLAMA_MODEL, ANTHROPIC_MODEL, or LLAMA_CPP_MODEL
`--stats`	Show chunk count, backend, and DB path

LLM backend configuration

Backend selection precedence:

LLM_BACKEND env var (or --backend CLI flag) always takes effect when set.
If LLM_BACKEND is not set and llama-cpp-python is importable, llama_cpp is selected automatically.
Otherwise the default is ollama.

Backend	Config	Notes
`llama_cpp` (auto)	`LLAMA_CPP_MODEL=/path/to/model.gguf`	In-process, no daemon needed; auto-selected when llama-cpp-python is installed
`ollama` (default)	`OLLAMA_MODEL=llama3`	Free, fully local — no data leaves the network
`anthropic`	`ANTHROPIC_API_KEY=sk-ant-…`	Better answers; queries sent to Anthropic
`retrieval`	—	No LLM — returns raw matched chunks; useful offline or for testing

gsas2-query --backend retrieval "What is Le Bail extraction?"
gsas2-query --backend ollama --model mistral "How do I index peaks?"
gsas2-query --backend llama_cpp --model /path/to/model.gguf "How do I refine a structure?"

Inline citations

When using Ollama, llama_cpp, or Anthropic backends, answers contain [N] markers inline. In the web UI these render as clickable superscript links opening the exact source section. In the CLI, source URLs are listed below the answer with relevance scores.

Doc sources

Category	Count	Included by default?
Home / installation pages	22	Yes
Help pages (all sections)	42	Yes
Tutorials (resolved dynamically)	64	Yes
Default total	128 sources
Developer's Guide (ReadTheDocs HTML)	23	Only with `--manual`
Powder Crystallography textbook (HTML)	173	Only with `--book`
Full total (with `--manual --book`)	324 sources

All HTML sources are fetched from https://advancedphotonsource.github.io/GSAS-II-tutorials/. Tutorial URLs are resolved dynamically from the GSAS-II repository at ingest time, so this count grows automatically as new tutorials are added. The Developer's Guide is fetched from gsas-ii.readthedocs.io, and the textbook from the latest GitHub Pages build of briantoby/PowderCrystallography. Both --manual and --book are flags on the standalone gsas_query.ingest module (see First-time setup); they are not currently exposed as gsas2-query --setup flags.

Re-indexing when docs update

gsas2-query --setup --reset

Or trigger via the web API (requires ADMIN_KEY set in .env):

curl -X POST http://localhost:8000/ingest -H "X-Admin-Key: your-key"

Security and deployment notes

All embeddings and vector search run locally (sentence-transformers, ChromaDB).
Ollama runs entirely on-premises — no queries leave the network.
The anthropic backend sends question text and retrieved doc chunks to Anthropic. Do not use it in air-gapped or data-sensitive environments.
The web server applies per-IP rate limiting (default 30 req/min, configurable via RATE_LIMIT_RPM in .env).
The /ingest endpoint is protected by X-Admin-Key; leave ADMIN_KEY blank to disable remote re-indexing.

User data directory

The ChromaDB index is stored at ~/.GSASII/query_gsas2/chroma_db by default. Override with the GSAS_QUERY_DATA_DIR environment variable:

GSAS_QUERY_DATA_DIR=/data/gsas_query gsas2-query --setup

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
conda-recipe		conda-recipe
evaluation		evaluation
gsas_query		gsas_query
static		static
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
app.py		app.py
cli.py		cli.py
gui.py		gui.py
ingest.py		ingest.py
main.py		main.py
pyproject.toml		pyproject.toml
rag.py		rag.py
requirements.txt		requirements.txt
sources.py		sources.py

Navigation Menu

Repository navigation

About

Repository files navigation

gsas2-query — GSAS-II Documentation Assistant

Authors

Installation

pip

conda

Into an existing GSAS-II environment

Development / editable install

Ollama — free local LLM (recommended when llama.cpp is not installed)

llama-cpp-python — in-process local LLM (auto-selected when installed)

Install

Download a GGUF model

Configure

First-time setup — index the documentation

Usage

Command-line — single question

Command-line — interactive REPL

Desktop GUI

Embed in GSAS-II Help menu

Web UI

CLI flags reference

LLM backend configuration

Inline citations

Doc sources

Re-indexing when docs update

Security and deployment notes

User data directory

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

gsas2-query — GSAS-II Documentation Assistant

Authors

Installation

pip

conda

Into an existing GSAS-II environment

Development / editable install

Ollama — free local LLM (recommended when llama.cpp is not installed)

llama-cpp-python — in-process local LLM (auto-selected when installed)

Install

Download a GGUF model

Configure

First-time setup — index the documentation

Usage

Command-line — single question

Command-line — interactive REPL

Desktop GUI

Embed in GSAS-II Help menu

Web UI

CLI flags reference

LLM backend configuration

Inline citations

Doc sources

Re-indexing when docs update

Security and deployment notes

User data directory

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages