# Lumis SDK > Lumis SDK 0.1.0-dev is an Apache-2.0, vendor-agnostic Python framework for agentic self-healing across data, ML, and software-delivery pipelines. It combines deterministic-first, evidence-grounded incident diagnosis with guarded recovery, operational memory, explicit approval, verification, and governed learning. Models are optional, storage is local-first, and consequential actions stay behind explicit policy boundaries. Repository: https://github.com/soloshun/lumis-sdk Python package: https://pypi.org/project/lumis-sdk/ Research paper: https://arxiv.org/abs/2608.01955 Full documentation as one Markdown file: https://lumis-sdk.vercel.app/llms-full.txt ## Start here - [Lumis SDK documentation](https://lumis-sdk.vercel.app/docs): Build deterministic-first, evidence-grounded incident diagnosis and guarded recovery workflows with a small, vendor-neutral Python core. ## Getting started - [Quickstart](https://lumis-sdk.vercel.app/docs/getting-started/quickstart): Run a complete deterministic diagnosis locally—without a cloud account, model key, or network call. - [The framework workflow](https://lumis-sdk.vercel.app/docs/getting-started/framework-workflow): See how incident context moves through bounded evidence, deterministic diagnosis, optional reasoning, guarded proposals, verification, and confirmed learning. ## Concepts - [Diagnosis-as-Code](https://lumis-sdk.vercel.app/docs/concepts/diagnosis-as-code): Represent incident diagnosis as versioned, reviewable configuration and typed evidence—not opaque model output. - [Healing-as-Code](https://lumis-sdk.vercel.app/docs/concepts/healing-as-code): Understand the long-term direction: a versioned, policy-controlled recovery lifecycle whose decisions and outcomes can be inspected. - [Deterministic-first reasoning](https://lumis-sdk.vercel.app/docs/concepts/deterministic-first): Make known incident behavior reproducible and explainable before introducing probabilistic reasoning. - [Evidence-grounded recovery](https://lumis-sdk.vercel.app/docs/concepts/evidence-grounded): Keep observation, hypothesis, uncertainty, contradiction, and missing context visible throughout the recovery lifecycle. - [Guarded recovery](https://lumis-sdk.vercel.app/docs/concepts/guarded-recovery): Follow a full recovery lifecycle while keeping policy, approval, actuation, verification, and learning explicit. - [Operational memory](https://lumis-sdk.vercel.app/docs/concepts/operational-memory): Retain incident knowledge with visible truth state and transparent retrieval rather than silently promoting generated text into fact. ## Architecture - [Architecture](https://lumis-sdk.vercel.app/docs/architecture/overview): Connect the paper's seven-layer recovery architecture to the SDK's ports, adapters, evidence, memory, and policy boundaries. - [Ports and adapters](https://lumis-sdk.vercel.app/docs/architecture/ports-and-adapters): Trace the dependency direction that keeps incident and recovery semantics independent of infrastructure vendors. - [Guarded lifecycle contracts](https://lumis-sdk.vercel.app/docs/architecture/lifecycle-contracts): Inspect the transport-neutral contracts for context, playbooks, proposals, approval, verification, audit, and lifecycle results. - [Optional model boundary](https://lumis-sdk.vercel.app/docs/architecture/model-boundary): Integrate probabilistic reasoning without coupling the core to a provider or granting a model execution authority. - [Framework, applications, and cookbooks](https://lumis-sdk.vercel.app/docs/architecture/framework-and-cookbooks): Separate reusable SDK capability from consuming applications, agent runtimes, synthetic scenarios, and hosted control planes. ## Configuration - [Project configuration](https://lumis-sdk.vercel.app/docs/configuration/project): Configure local memory, reports, incident sources, evidence providers, rules, and model policy through a strict versioned public API. - [Deterministic text rules](https://lumis-sdk.vercel.app/docs/configuration/rules): Encode stable log-signature rules, evidence gaps, and safe investigation steps in a versioned rule set. - [Structured rules](https://lumis-sdk.vercel.app/docs/configuration/structured-rules): Match typed incident fields with all/any/not conditions, comparisons, quantifiers, and required evidence—deterministically ranked and fully explainable. - [Migrate to lumis.dev/v1](https://lumis-sdk.vercel.app/docs/configuration/migrate-to-v1): Upgrade released v1alpha1 documents to the stable v1 envelopes with a validated, deterministic, idempotent migration. ## Python API - [Python API](https://lumis-sdk.vercel.app/docs/python-api/overview): Use the public domain contracts, application services, and reference adapters from your own Python application. - [Evidence collection and JSON reports](https://lumis-sdk.vercel.app/docs/python-api/evidence-and-reports): Collect bounded, typed, failure-aware evidence through the provider port, and emit versioned machine-readable reports. - [Operational memory API](https://lumis-sdk.vercel.app/docs/python-api/memory): Persist incident episodes and confirmed resolutions through the provider-neutral MemoryStore port—locally in SQLite or shared in PostgreSQL. - [Policy, verification, and learning](https://lumis-sdk.vercel.app/docs/python-api/policy-verification-learning): Propose allowlisted actions under default-deny policy, record explicit verification outcomes, and promote only confirmed truth into memory. - [Webhook and evidence connectors](https://lumis-sdk.vercel.app/docs/python-api/connectors): Normalize authenticated webhook deliveries into incidents, and collect remote evidence through the hardened HTTP JSON plugin. - [Plugin SDK](https://lumis-sdk.vercel.app/docs/python-api/plugins): Package adapters as independent distributions with static manifests, metadata-only discovery, and explicit policy-checked loading. ## Reference - [CLI reference](https://lumis-sdk.vercel.app/docs/reference/cli): Initialize projects, validate configuration and rules, diagnose local logs, inspect reports, confirm resolutions, search memory, and inspect plugins. - [Domain model reference](https://lumis-sdk.vercel.app/docs/reference/domain-models): Review the strict, vendor-neutral Pydantic contracts exported from lumis_sdk.domain. - [Port reference](https://lumis-sdk.vercel.app/docs/reference/ports): Implement replaceable capabilities without changing the Lumis SDK domain or application layer. ## Learn - [Cookbooks](https://lumis-sdk.vercel.app/docs/cookbooks/overview): Learn the framework through reproducible, synthetic incident investigations with explicit safety boundaries. - [Videos, tutorials, and posts](https://lumis-sdk.vercel.app/docs/learn/videos): Watch and read your way into the framework—recorded sessions, walkthroughs, and community builds. ## Safety - [Safety and threat model](https://lumis-sdk.vercel.app/docs/safety/threat-model): Treat operational evidence and model output as untrusted data while preserving local control and honest truth state. ## Project - [Roadmap](https://lumis-sdk.vercel.app/docs/project/roadmap): A four-phase path from a trustworthy Python foundation to a guarded recovery ecosystem—without ever granting ambient production authority. - [Contributing](https://lumis-sdk.vercel.app/docs/project/contributing): Contribute focused code, documentation, tests, and cookbooks while preserving the project's clean-room and safety boundaries. - [Stability and compatibility](https://lumis-sdk.vercel.app/docs/project/stability): Know exactly what stays compatible across the 1.x line—and what is provisional or internal. - [The research behind Lumis SDK](https://lumis-sdk.vercel.app/docs/project/research): Lumis SDK is the open-source implementation companion to a peer-oriented research paper on agentic self-healing pipelines. - [Lumis SDK and Lumis](https://lumis-sdk.vercel.app/docs/project/lumis-and-sdk): Understand the open-source framework boundary and the planned managed Lumis platform from Qadim Labs.