Lumis SDK documentation
Build deterministic-first, evidence-grounded incident diagnosis and guarded recovery workflows with a small, vendor-neutral Python core.
What is Lumis SDK?
Lumis SDK is the Apache-2.0 open-source implementation companion to the agentic recovery and incident response reference architecture proposed in the accompanying research. It turns bounded incident evidence—logs, schema diffs, metrics extracts, lineage context—into a structured, reviewable diagnosis, a Markdown or versioned JSON report, and an inspectable operational-memory record. Every step is designed so that facts, evidence, hypotheses, confidence, contradictions, and missing evidence remain distinguishable from each other.
The project starts with Diagnosis-as-Code: failure signatures, hypotheses, calibration, and safe investigation steps live in versioned configuration that teams review like application code. Its direction is Healing-as-Code: a guarded lifecycle for detect, triage, diagnose, plan, approve, remediate, verify, and learn—where consequential actions stay behind explicit policy, approval, and verification boundaries. The reference architecture itself comes from published research led by the project's maintainer—see the research behind Lumis SDK.
What ships today
Phase 1 of the roadmap — the trustworthy Python foundation — is complete on the main branch and heading into the 0.1.0 release. The latest published package is 0.0.8; the stable v1 configuration surface below ships with 0.1.0.
| Capability | Current behavior |
|---|---|
| Incident input | Local log normalization, typed vendor-neutral incident contracts, and a framework-neutral webhook normalizer. |
| Evidence collection | Async provider port, bounded collection service with timeouts and budgets, redaction, structured failures, and a local JSON reference adapter. |
| Deterministic diagnosis | Legacy ordered text rules plus structured all/any/not rules with typed comparisons, required evidence, ranking, and per-candidate explanations. |
| Configuration | Stable lumis.dev/v1 project, rule, report, manifest, playbook, and policy documents with checked JSON Schemas; released v1alpha1 documents migrate via lumis config migrate. |
| Reports | Deterministic Markdown or versioned JSON with facts, evidence, hypotheses, truth state, confidence, and review requirement. |
| Operational memory | SQLite reference store, human resolutions, visible truth state, transparent lexical search, and an independent PostgreSQL plugin. |
| Model boundary | Explicit opt-in policy, budgets, schema-validated output, deterministic fallback, and a fake gateway for CI. |
| Guarded lifecycle | Typed playbooks, default-deny policy, evidence-linked proposals, idempotent approvals, verification records, and conservative learning—no core action executor. |
| Plugin SDK | Static strict manifests, metadata-only discovery, explicit policy-checked loading, and reusable factory contract tests. |
| CLI | init, doctor, diagnose, report, resolve, memory search, rules validate, rules test, plugins list, plugins doctor, and config migrate. |
| Stability | A public API inventory and compatibility policy define exactly what stays compatible across the 1.x line. |
| Supply chain | SPDX SBOMs, signed provenance attestations, reproducible-build comparison, artifact content validation, and PyPI Trusted Publishing. |
Design principles
| Principle | Meaning |
|---|---|
| Deterministic first | Known signatures and project-owned rules run before optional model reasoning. |
| Evidence grounded | Facts, evidence, hypotheses, contradictions, confidence, and gaps stay separate. |
| Model optional | The core works offline; providers implement a narrow, explicitly enabled gateway port. |
| Local first | SQLite and Markdown are inspectable defaults, not mandatory hosted services. |
| Guarded recovery | Plans are allowlisted recommendations; approval and verification are explicit boundaries. |
| Confirmed memory | Model output is never silently promoted into confirmed operational truth. |
| Vendor agnostic | Domain and application packages import no observability, orchestration, cloud, or agent SDK. |
Choose a path
- New to Lumis SDK: complete the five-minute quickstart, then read the framework workflow.
- Embedding diagnosis in a Python application: start with the Python API overview.
- Defining project behavior: read the project configuration and rule references.
- Evaluating the architecture: review the architecture overview, ports and adapters, and the threat model.
- Extending the framework: read the plugin SDK and connector guides.
- Learning through runnable examples: open the cookbooks—every one is synthetic and offline by default.