Developers: every way into xpsflow

xpsflow is one tool layer with several doors. Whichever you walk through, the same deterministic functions run, the same results.json comes out, and every number in it can be traced to the call that produced it. Pick the door that fits your workflow.

Install

pip install "xpsflow[web,pdf,mcp]"          # once the first release is on PyPI
pip install "xpsflow[web,pdf,mcp] @ git+https://github.com/KarthikSubramanian07/XPS-Flow"   # today

xpsflow version prints the version; xpsflow --help lists every command. The extras are optional: web adds the local workbench and HTTP API, pdf adds PDF reports (WeasyPrint), mcp adds the Model Context Protocol server.

Command line

xpsflow run sample.vms --out runs/sample          # the whole pipeline: results.json, report.pdf, figures
xpsflow run sample.kal --template templates/Ti2p.yaml --out runs/ti
xpsflow batch data/ --out runs/batch              # every sample in a directory, one comparison report
xpsflow inspect sample.vms                        # what is in the file, before anything is fitted
xpsflow serve                                     # the workbench at http://127.0.0.1:8765
xpsflow chat sample.vms                           # the assistant, in the terminal
xpsflow mcp --data ./data                         # the MCP server over stdio
xpsflow models                                    # which models the configured endpoint serves

results.json holds every number: spectra metadata, quality grades, the calibration shift, survey matches, each fit with its components, uncertainties, model-selection table and audit, the composition in three readings, and the templates that were used, with their provenance. A run can be repeated from that file and the saved templates alone.

Python

from pathlib import Path
from xpsflow.agent.session import Session
from xpsflow.agent.tools import registry

# A session: where it writes, and the only directory its tools may read from.
s = Session(id="demo", work_dir=Path("runs/demo"), sandbox=Path("examples"))
registry.call(s, "load_data", {"paths": ["demo.vms"]})
registry.call(s, "check_quality", {})
registry.call(s, "calibrate_energy", {"mode": "adventitious_carbon"})
registry.call(s, "use_template", {"key": "demo/Te 3d", "template": "Te3d"})
fit = registry.call(s, "fit_spectrum", {"key": "demo/Te 3d"})["result"]
print(fit["components"], fit["audit"])
print(registry.call(s, "quantify", {})["result"]["atomic_percent"])

Every call returns {"ok": true, "result": ...} or {"ok": false, "error": ...}, the same compact JSON the assistant and the MCP client receive. The registry is the same list of tools every other door exposes, so a script written against it behaves exactly like the workbench; registry.tool_schemas() returns the JSON schema of each tool, and xpsflow.pipeline runs the whole sequence in one call when you want the report too.

HTTP API

xpsflow serve starts the workbench and its API on http://127.0.0.1:8765. The surface is described by an OpenAPI document, published here at /openapi.json and served live at /openapi.json on the local server, with an interactive explorer at /api/docs.

SID=$(curl -s http://127.0.0.1:8765/api/session | jq -r .sid)
curl -s -F files=@sample.vms "http://127.0.0.1:8765/api/upload?sid=$SID"
curl -s "http://127.0.0.1:8765/api/tools" | jq '.tools[].name'
curl -s -X POST "http://127.0.0.1:8765/api/tool/fit_spectrum?sid=$SID" \
     -H 'Content-Type: application/json' -d '{"arguments": {"key": "sample/Ti 2p"}}'
curl -s "http://127.0.0.1:8765/api/composition?sid=$SID"
curl -s "http://127.0.0.1:8765/api/report?sid=$SID&format=pdf" -o report.pdf

Every error is JSON with the same shape: a detail message and an error object with a stable code, the status, a one-sentence message, a hint that says what to do, and a docs link. A request to an unknown tool, for example, returns 404 with "code": "not_found" and the hint to list the tools first. The server answers only to localhost and 127.0.0.1 unless started otherwise, refuses cross-origin writes, and caps upload and body sizes; the security page has the limits.

MCP: the analysis tools, from any AI client

xpsflow mcp --data ./data                 # stdio, for desktop clients and editors
xpsflow mcp --http --port 8766            # streamable HTTP at http://127.0.0.1:8766/mcp

Register the stdio server with any client that reads an MCP configuration:

{ "mcpServers": { "xpsflow": { "command": "xpsflow", "args": ["mcp", "--data", "/path/to/data"] } } }

Nineteen tools (load_data, check_quality, calibrate_energy, identify_survey, propose_fit, use_template, fit_spectrum, quantify, ..., and, with the crucible extra, crucible_search, crucible_load and crucible_publish), two resources (the templates and each element's curated states) and an analyze-sample prompt that walks a client through the standard workflow. Each connection gets its own sandboxed session that can only read the directory you point it at. The MCP page documents every tool and the security model.

MCP: reference data, hosted on this site

This site also serves a read-only MCP server over streamable HTTP at https://xpsflow.pages.dev/mcp, so an agent can look things up before anyone installs anything: lookup_element, lines_near (which core levels sit near a binding energy), find_chemical_state (by name or by energy, with citations), list_templates, get_template and read_docs. Point an MCP client at the URL, or call it by hand:

curl -s https://xpsflow.pages.dev/mcp -H 'Content-Type: application/json' \
     -H 'Accept: application/json, text/event-stream' \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"find_chemical_state","arguments":{"query":"TiO2"}}}'

The server card at /.well-known/mcp/server-card.json lists both servers and their transports. Nothing is analyzed on the site; the hosted endpoint only answers from the curated tables and the documentation.

The assistant

The assistant is a short tool-calling loop around the same registry. It needs a chat-completions endpoint that supports tool calling; a 7B-class local model is enough.

export XPSFLOW_LLM_PRESET=ollama           # or cborg, openai, custom
xpsflow chat sample.vms

Raw spectra are never sent to the model; it sees compact JSON results and explains them. The assistant page covers each preset and how to check that a model can call tools.

For agents reading this page

Machine-readable entry points: /llms.txt (what exists and when to use it), /agents.md (when to reach for xpsflow and how to call it), /openapi.json (the local HTTP API), /.well-known/mcp/server-card.json (both MCP servers), /sitemap.xml. Every documentation page has a Markdown twin at the same address with .md appended, or by asking for Accept: text/markdown.