Python API and CLI

Use YamlProject.handle_incident from Python, prepare graph snapshots deliberately, store reports, and the full CLI reference.

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

The Python API

python

import asyncio
from pathlib import Path
from lumis_sdk.core import Incident
from lumis_sdk.runtime import IncidentStore, YamlProject

async def main():
    workspace = Path("./my-lumis")
    incident = Incident.model_validate_json((workspace / "incident.json").read_text())
    project = YamlProject.from_file(workspace / "lumis.yaml")
    report = await project.handle_incident(incident)
    print(report.conclusion, report.route)
    assert report.requires_human_review
    IncidentStore(workspace / "incidents.sqlite").save(report)

asyncio.run(main())

from_file validates the project locally. handle_incident prepares the graph at the incident's end time, runs triage and, if enabled, the investigator, and returns an IncidentReport. Pass observations= to replay facts, or observations=() to force missing evidence. No model is called unless you pass use_agent=True or inject an investigator.

Reusing a prepared graph

python

prepared = await project.prepare(at=incident.ended_at)
print(prepared.discovery.complete)
print([(s.name, s.status) for s in prepared.discovery.sources])
report = await prepared.handle_incident(incident)

Reuse a PreparedProject only when you want the same topology snapshot; call prepare again for fresh discovery. A failed source raises DiscoveryError, whose report lists each source's status.

CLI reference

Command	Effect
`lumis init --directory PATH`	Create an offline starter project, incident and observations.
`lumis doctor --project FILE`	Validate locally. No network or paid requests.
`lumis discover --project FILE [--report]`	Build the graph from all enabled sources; `--report` shows per-source status.
`lumis graph --project FILE [--entity ID --hops N] --format json\|dot\|svg\|terminal [--output FILE]`	Export or view the graph or a neighbourhood.
`lumis incident --project FILE --incident FILE`	Triage, optional investigator, report. Add `--observations`, `--store`, `--use-agent`.
`lumis record-resolution --store FILE --resolution FILE --confirm`	Append a human resolution to a stored incident.
`lumis console --project FILE`	Interactive menu over the same commands.
`lumis investigate --project FILE --incident FILE`	Lower-level candidate-only baseline, used for comparisons.

No command restarts a service, applies a patch or changes a rule. Error messages are deliberately sanitized so they do not leak credentials or payloads.

Extension points

Interface	Use
`Investigator`	Replace the reference investigator. Its output is still validated by Lumis.
`EvidenceConnector`	Add a read-only source: `async collect(query, incident)` returns observations.
`TriageGuard`	Add your own extra rule for when triage may conclude.
`ProbeRunner`	Provide a different, reviewed sandbox for experiments.

Source: Python API ↗ in the SDK repository.