Architecture
Connect the paper's seven-layer recovery architecture to the SDK's ports, adapters, evidence, memory, and policy boundaries.
Seven-layer reference architecture
The published paper separates the system into seven logical responsibility layers. Known, low-risk incidents pass through deterministic policy before any model is considered; ambiguous incidents may use bounded agentic reasoning. Approval and guarded execution remain separate from reasoning, and verification closes the learning loop.
| Layer | Responsibility |
|---|---|
| 1 · Existing pipeline estate | The orchestrators, data systems, ML workflows, and delivery infrastructure being healed remain unchanged. |
| 2 · Telemetry and signals | Metrics, alerts, logs, traces, lineage, metadata, and data-quality signals provide live evidence. |
| 3 · Incident memory and knowledge | Confirmed incident history, versioned runbooks, playbooks, schemas, contracts, and owners ground decisions. |
| 4 · Deterministic policy and agentic reasoning | Rules handle known incidents first; bounded reasoning handles ambiguity across evidence and history. |
| 5 · Approval and governance | Risk tiers, human decisions, and audit records determine whether a proposed action may proceed. |
| 6 · Guarded execution | Only allowlisted, limited, reversible, and auditable mechanisms may act. |
| 7 · Verification and learning | Recovery checks establish truth, update memory, and surface recurring patterns for policy promotion. |
System map
The canonical picture: project entry points compose the framework core, and the core reaches infrastructure only through replaceable ports implemented by local reference adapters or independent plugins.
Dependency rule
- domain depends only on Python, Pydantic, and standard-library types.
- application coordinates use cases through domain models and ports.
- ports describe replaceable capabilities.
- adapters implement local or provider-specific behavior.
- cli selects and composes adapters.
Package map
| Package | Responsibility | Stability |
|---|---|---|
| lumis_sdk.domain | Incidents, evidence, diagnoses, truth states, playbooks, policies, proposals, approvals, verification, audit | Canonical pre-1.0 |
| lumis_sdk.application | Diagnosis, evidence collection, proposals, verification learning, and lifecycle orchestration | Canonical pre-1.0 |
| lumis_sdk.ports | Evidence, model, memory, reporting, context, policy, approval, verification, and audit boundaries | Experimental |
| lumis_sdk.adapters | Deterministic rules, SQLite memory, local JSON evidence, Markdown/JSON reports, webhook, plugins | Reference |
| lumis_sdk.config | Stable v1 documents, migration APIs, bounded loading, checked schemas | Stable API |
| lumis_sdk.security | Conservative redaction and evidence-safety utilities | Reference |
| lumis_sdk.testkit | Deterministic fakes, fixtures, and reusable contract assertions | Experimental |
| lumis_sdk.cli | Local composition and user commands | Pre-alpha interface |
Evidence boundary
EvidenceService requests typed evidence through the async EvidenceProvider port. It enforces timeouts, kind filtering, stable duplicate handling, item and character budgets, and optional redaction before evidence reaches diagnosis. Provider errors return as structured failures, so unavailable context cannot be mistaken for a confirmed observation. The local-json adapter is the offline reference; independent packages implement the same port without introducing vendor types into core.
Plugin boundary
Plugin distributions register the lumis_sdk.plugins entry-point group and ship a strict static manifest. Discovery validates identity, SDK compatibility, support status, capabilities, and authority requests without importing any plugin module. Loading is explicit, policy-checked, and denied sensitive authorities by default. Core remains fully usable with no plugins installed.
Optional model routing
DiagnosisService invokes a ModelGateway only when deterministic classification is unknown, ModelUsePolicy.enabled is true, and a gateway has been injected. The gateway receives bounded, redacted domain data and returns a schema-validated diagnosis plus provider, model, and prompt metadata. Provider SDK types never appear in domain or application contracts.