Python SDK · Apache-2.0 · proof of concept

Incident investigation, grounded in evidence.

Name: Lumis SDK
Author: Solomon Eshun

Lumis checks known failure signatures first, lets a bounded model investigate only when they are not enough, and tests every explanation against evidence it collected itself. It reads; it never acts. A person decides.

pip install "lumis-sdk[http,agent]"

Get started How it works GitHub ↗

Python 3.11+Read-only by designModel optional

lumis.yaml — one deterministic checkfrom the small-project guide

checks:
  - id: api-down
    terminal: true
    explains_entities: [service:api]
    hypothesis:
      id: api-unavailable
      statement: The API is down; both its scrape target
        and an external HTTP probe fail.
      causal_path: [service:api]
      evidence_needed: [api-up, api-probe]
      predictions:
        - {entity_id: "service:api", key: up, operator: eq, value: 0}
        - {entity_id: "service:api", key: probe_success, operator: eq, value: 0}
      falsifiers:
        - {entity_id: "service:api", key: up, operator: eq, value: 1}
        - {entity_id: "service:api", key: probe_success, operator: eq, value: 1}

lumis incident … → reportboth signals at 0

finding api-downmatch · terminal
routedeterministic
conclusionsupported_diagnosis
model requests0
requires_human_reviewtrue

If the API is up the check is falsified; if data is missing it stays unknown. Neither is reported as a diagnosis.

How it works

Checks first. A model only when needed. Evidence decides.

Every path ends in the same structured report for a person to review: what was found, what supports it, what contradicts it, and what is still unknown.

Prepare

Build an operational graph of your services from what you declare and what Lumis discovers, then scope it to the incident.

Kubernetes · Prometheus · Tempo · Prefect

Triage

Test your known failure signatures against facts from operator-registered queries. A sufficient signature concludes with no model call.

match · no_match · unknown

Investigate

Only if needed and enabled: one bounded model proposes explanations and asks for evidence by query ID. It cannot write queries or change anything.

OpenRouter · OpenAI · Anthropic · Gemini

Assess

Every explanation's predictions and falsifiers are checked mechanically. A diagnosis needs supported explanations that agree on one cause.

supported · contradicted · unresolved

Read-only throughout: there is no remediation executor. Read the full walkthrough →

First results

Tested on a live estate with fifteen injected failures.

GridCast is an open reference estate we built: a demand-forecasting system on Kubernetes with Prometheus, Loki, Tempo, Prefect and PostgreSQL. We broke it fifteen ways and asked each system to find the cause of the same frozen incident.

15failures injected through releases, config, vendors and data

25 / 28runs where Lumis named the right component and mechanism

7 / 8on the hard, silent faults, against 2 / 8 for one model call

How it was measured, and what went wrong →

Correct root cause (component and mechanism)

Same model, DeepSeek v4 pro, for every model-based system. 28 runs each.

A model given only the alert0.04

The same model plus the service graph0.18

One model call with curated evidence0.54

Lumis: triage, investigator, assessment0.89

A proof of concept, not a benchmark: one synthetic estate written by our team, one model, two runs per system per scenario. One scenario is excluded after we found a ground-truth leak. Full research notes ↗

Scope

What the SDK does today, and what it does not.

Lumis is research software at version 0.1.0. It is useful for investigation now, and deliberately narrow.

Included

YAML-declared, read-only sources: Kubernetes, Prometheus, Loki, Tempo, Prefect, PostgreSQL, Git and rollout history
An operational graph scoped to each incident
Deterministic checks with strict rules for concluding
One optional tool-using investigator with budgets
Mechanical assessment and a structured, auditable report
Local SQLite audit records and separate human resolutions

Not included

Any action on your systems: no restarts, rollbacks or applied patches
Automatic learning or promotion of new rules
A hosted service, dashboard or alert receiver
Confirmed root cause: “supported” means supported by evidence, not proven
Evaluation beyond one estate and one model family

Get started

Run your first investigation in a minute.

The scaffold is fully offline: no cluster, no API key, no model call. Then point it at one real service with the small-project guide.

Quickstart Your first real project

Terminal

pip install "lumis-sdk[http,agent]"
lumis init --directory ./my-lumis
lumis doctor --project ./my-lumis/lumis.yaml
lumis incident --project ./my-lumis/lumis.yaml \
  --incident ./my-lumis/incident.json \
  --observations ./my-lumis/observations.json

Research

Where Lumis comes from.

Lumis grew out of research into guarded, vendor-neutral self-healing. The SDK narrows that work to the part that can be tested today: investigation.

Visit the Lumis website ↗Read the blog ↗

arXiv 2608.01955 · preprint

Agentic Self-Healing for Data & AI Pipelines: An Affordable Vendor-Agnostic Architecture using Open-Source Software

Solomon Eshun et al. · August 2026. The broader architecture includes recovery and learning; the current SDK implements investigation only.

Read on arXiv ↗Download PDF

The SDK is open source

An open-source proof of concept, under Apache-2.0.

Lumis SDK is the proof of concept of Lumis’ investigation core, and it is released as open source: read the source, run it locally, and see exactly what it checked. Other Lumis products and services are separate and are not necessarily open source.

Contributors

Lumis is early, and small. Questions, ideas, bug reports and offers to help are all welcome by email.

Email solomon@qadimlabs.com

GITHUB STARS

Live count unavailable