Quickstart

Install Lumis SDK from PyPI and run a complete, offline incident investigation with no cluster, API key or model call.

v0.1.0 · experimentalPython 3.11+Updated 2026-10-05

1. Install

You need Python 3.11 or newer. The core package has no network dependencies; extras add them when you need them.

bash

pip install lumis-sdk                  # core: offline investigation
pip install "lumis-sdk[http]"          # + Prometheus, Loki, Tempo, Prefect connectors
pip install "lumis-sdk[http,agent]"    # + the optional model investigator
pip install "lumis-sdk[sql]"           # + read-only PostgreSQL evidence

With uv, use uv add "lumis-sdk[http,agent]" in a project, or uvx --from lumis-sdk lumis --help to try the CLI without installing. Check the install with lumis --version.

2. Create a starter project

bash

lumis init --directory ./my-lumis
lumis doctor --project ./my-lumis/lumis.yaml

init writes three files and refuses to overwrite existing ones: lumis.yaml (the project: one service, one registered query and one check), incident.json (an example incident with a time window) and observations.json (recorded facts to replay offline). doctor validates the project locally; it makes no network calls.

3. Investigate the incident

bash

lumis incident \
  --project ./my-lumis/lumis.yaml \
  --incident ./my-lumis/incident.json \
  --observations ./my-lumis/observations.json

The command prints a JSON report. In the scaffold, the recorded observation says the service was unhealthy, so the check matches. The check is deliberately not terminal (one symptom is a lead, not a full explanation), and no investigator is enabled, so the incident goes to a person.

Report field	Value	Meaning
`findings[0].status`	`match`	The recorded fact agrees with the check's prediction.
`route`	`human`	No sufficient check and no investigator enabled.
`conclusion`	`requires_human_expert`	More investigation is needed; nothing was concluded.
`truth_state`	`unconfirmed_hypothesis`	Lumis never marks anything as confirmed.
`requires_human_review`	`true`	Always true, on every path.

Run it again without --observations: the finding becomes unknown. Missing data is never treated as a measurement.

4. Keep and inspect the results

bash

lumis incident --project ./my-lumis/lumis.yaml --incident ./my-lumis/incident.json \
  --observations ./my-lumis/observations.json --store ./my-lumis/incidents.sqlite
lumis graph --project ./my-lumis/lumis.yaml --format svg --output ./my-lumis/graph.svg
lumis console --project ./my-lumis/lumis.yaml

--store saves the report in a local SQLite audit file; reusing an incident ID is refused so history is never overwritten. graph exports the operational graph (json, dot, svg or terminal). console is a small interactive menu over the same commands.

5. Next

Connect Lumis to a real service in your first real project, or read how Lumis works first.

Source: CLI walkthrough ↗ in the SDK repository.