Quickstart

Requirements

• Python 3.11 or newer.
• uv for environment and dependency management (pip also works).
• No credentials, model keys, or network access—the entire quickstart runs offline.

Install

Lumis SDK is published to PyPI as lumis-sdk. Reviewed releases are published through GitHub Actions with PyPI Trusted Publishing, so every package is traceable to a reviewed commit.

uv add "lumis-sdk>=0.0.8,<0.1.0"

# or, with pip
pip install "lumis-sdk==0.0.8"

To explore the repository, cookbooks, and tests directly, clone and sync instead:

git clone https://github.com/soloshun/lumis-sdk.git
cd lumis-sdk
uv sync --all-groups
uv run lumis --help

Run the local example

The simple-log-diagnosis cookbook contains a synthetic failure log, a project document, and a small rule set. First validate the setup, then diagnose:

uv run lumis doctor \
  --config cookbook/simple-log-diagnosis/lumis/lumis.yml

uv run lumis diagnose \
  --config cookbook/simple-log-diagnosis/lumis/lumis.yml

diagnose reads the bounded local log, evaluates the configured rules in deterministic order, writes a Markdown report to the configured output directory, stores an unconfirmed incident episode in local SQLite, and prints the incident ID. doctor validates configuration and paths without writing any state; neither command makes a network or model call.

Inspect, confirm, and search

uv run lumis report <incident-id> --config path/to/lumis.yml

uv run lumis resolve <incident-id> \
  --resolution "Human-confirmed cause, action, and outcome." \
  --config path/to/lumis.yml

uv run lumis memory search "KeyError customer_id" --config path/to/lumis.yml

report prints the stored diagnosis and any confirmed resolution. resolve records what a person actually confirmed—the cause, the action taken, and the outcome. memory search retrieves past episodes with transparent keyword scoring, so you can see exactly why a record matched.

Next steps

• Create your own project with lumis init—it writes a minimal Project and rule set without overwriting existing files.
• Read the project configuration reference before adapting a real log source.
• Read the framework workflow to see how the pieces compose end to end.
• Learn the Python API if you are embedding diagnosis into another application.