# xpsflow

> Physics-constrained, self-checking X-ray photoelectron spectroscopy (XPS) analysis. Reads Kratos and VAMAS files, fits core levels with literature-constrained doublets, selects models by BIC, audits every fit, quantifies with the intensity scale spelled out, and writes a report a scientist can sign. Open source (MIT), Python.

- [Repository](https://github.com/KarthikSubramanian07/XPS-Flow): source, issues, releases
- [Try it in the browser](https://xpsflow.pages.dev/app/): the workbench running on Pyodide; files never leave the browser

## When to use xpsflow

Reach for it when a user has XPS data to analyze: a Kratos `.kal` export, an ISO 14976 VAMAS `.vms` file or a two-column text spectrum, and wants peaks fitted under physical constraints, a composition with the intensity scale written down, an audit of each fit, or a report. It is the right tool for core-level fitting, survey identification, charge referencing, quantification and multi-sample comparison. It is not for hyperspectral maps, depth-profile chemometrics, or instruments whose files cannot be exported to VAMAS.

How to call it: in the browser, open `/app/`, drop the file and press Analyze. From a shell, `xpsflow run FILE --out DIR` writes `results.json` (every number), the templates used and a report; `xpsflow batch DIR` compares samples. From an AI client, run `xpsflow mcp --data DIR` and call the tools (`load_data`, `check_quality`, `calibrate_energy`, `identify_survey`, `fit_spectrum`, `quantify`, `analyze_samples`); the server card is at https://xpsflow.pages.dev/.well-known/mcp/server-card.json and the local HTTP API is described at https://xpsflow.pages.dev/openapi.json.

## Documentation

- [Quantification](https://xpsflow.pages.dev/docs/quantification.md): How areas become a composition, and how far to trust it.
- [Constraints and provenance](https://xpsflow.pages.dev/docs/constraints.md): Where every bound comes from, and how the reference database is built.
- [Fit templates](https://xpsflow.pages.dev/docs/templates.md): The YAML that encodes the physics of a region.
- [Architecture](https://xpsflow.pages.dev/docs/architecture.md): One tool layer, three ways in.
- [The assistant](https://xpsflow.pages.dev/docs/assistant.md): Pointing the tool-calling assistant at a model.
- [MCP server](https://xpsflow.pages.dev/docs/mcp.md): Using xpsflow from an AI client.
- [Security](https://xpsflow.pages.dev/docs/security.md): Threat model, limits and the stress suite.
- [The website and the browser build](https://xpsflow.pages.dev/docs/site.md): How the static site and the in-browser workbench are built and deployed.

## Install

- `pip install -e ".[web,pdf]"` from a clone; `xpsflow run file.vms` for the full pipeline; `xpsflow serve` for the local workbench; `xpsflow mcp` for the MCP server.

## Site

- [About](https://xpsflow.pages.dev/about.md)
- [Contact](https://xpsflow.pages.dev/contact.md)
- [Privacy](https://xpsflow.pages.dev/privacy.md)