Beacon signs. Lantern reads.
AIGovOps Lantern™ is the human-carried companion to AIGovOps Beacon™ within the Umbrella-GovOps framework maintained by the AIGovOps Foundation.
Where Beacon is the always-on policy-as-code runtime — signing, attesting, and emitting machine-verifiable artifacts — Lantern is the carried light. It reads those artifacts and illuminates conformance for the people doing the work: engineers reviewing a PR, compliance leads scoping a control, auditors tracing an evidence bundle, and regulators reading a crosswalk.
Status: v0.1.1 · CLI shipped · 103 tests (unit + E2E + scale + chaos) · 87% coverage · ruff/mypy strict clean · DRAFT OpenAPI for v0.2
pip install aigovops-lantern # once published; for now:
pip install git+https://github.com/aigovops-foundation/aigovops-lantern.gitRequires Python 3.11+.
Render a Beacon-signed evidence bundle (NDJSON, JSONL, or JSON array) as text, Markdown, or JSON — optionally through a role lens.
lantern read ./evidence-bundle.ndjson
lantern read -f markdown -r auditor ./evidence-bundle.ndjson
lantern read -f json ./evidence-bundle.ndjson | jq '.event_types'Output (Markdown excerpt):
# Bundle: `evidence-bundle.ndjson`
_AIGovOps Lantern — Beacon signs. Lantern reads._
> **Auditor view.** Focus on the chain of custody: who produced each
> receipt, when, in which environment, and whether the receipt carries
> a signature.
- **Receipts:** 46
- **Signed:** 46 of 46
- **Distinct event types:** 7
- **Distinct evidence types:** 41Compare two bundles. The narrative is targeted to a role: engineers see pipeline-integrity callouts; compliance sees UCID mapping prompts; auditors get chain-of-custody flags; regulators see framework-citation deltas.
lantern diff ./before.ndjson ./after.ndjson
lantern diff -r engineer ./before.ndjson ./after.ndjson
lantern diff -f markdown -r compliance ./before.ndjson ./after.ndjson \
>> $GITHUB_STEP_SUMMARYResolve a Unified Control Identifier (UCID) against the Umbrella-GovOps UCID Registry and render its framework citations.
lantern explain UCID-DATA-BIAS-001
lantern explain --registry ../umbrella-govops/crosswalks/unified-control-id.yaml \
UCID-OVERSIGHT-001Output:
# UCID-DATA-BIAS-001 — Dataset bias examination
Status: provisional
NIST AI RMF: MEASURE-2.11, MAP-2.3, MANAGE-2.3
EU AI Act: Articles 10(2)(f), 10(3) · Annex IV 2(d), 2(g)
ISO/IEC 42001: A.7.4
Implementing controls: DG-002
Without --registry, Lantern falls back to a small embedded snapshot
used for offline demos. The registry source of truth lives in
umbrella-govops — Lantern never mutates it.
Beacon answers the machine question: "Is this artifact signed, attested, and conformant?"
Lantern answers the human question: "Can I, the person who has to act on this, understand what it means, what changed, and what I need to do?"
The Foundation's premise is humans are worthy — the carried light, not just the spotlight. Lantern is the reader, translator, and dignity layer on top of the policy-as-code substrate.
- Read-only by construction. Lantern never produces signed artifacts. If a user needs a signature, they go to Beacon.
- Local-first. Works against local files with no network.
- No telemetry. Lantern is a tool people carry — surveillance is inconsistent with the dignity premise.
- Small dependency footprint. Three runtime deps (typer, rich, pyyaml). Auditors and regulators must be able to install Lantern without an enterprise approval chain.
| Concern | Beacon | Lantern |
|---|---|---|
| Audience | Machines, pipelines, signers | Humans, reviewers, auditors |
| Primary verb | Sign / attest / emit | Read / interpret / translate |
| Failure mode | Refuses to sign | Refuses to confuse |
| Runtime | Always-on infrastructure | Person-carried, on-demand |
| Output | Cryptographic artifacts | Human narratives + diffs |
| Cadence | Per commit / per release | Per review / per question |
Lantern consumes Beacon output. It never re-signs, and it does not
verify cryptographic signatures — it reports their presence. For
verified chain-of-custody, run beacon verify first.
- v0.1 (shipped) — v0.1.0-alpha release. CLI:
read,diff,explain. Three output formats. Four role lenses. UCID lookup against local or embedded registry. - v0.2 — Web view for Beacon bundles. Per-receipt drill-in, richer diff narratives, shareable URL state. Tracking: #2.
- v0.3 — GitHub Action wrapping
lantern diffto post bundle diffs as PR comments. Tracking: #3. - v1.0 — Stable role taxonomy. i18n. Reference renderers for at least one major regulator template (e.g., EU AI Act Annex IV form).
Lantern ships a four-layer test pyramid. Unit + E2E + schema tests run on every push; scale and chaos tests are opt-in via env flags and run weekly in CI.
| Layer | File | Count | Trigger | What it covers |
|---|---|---|---|---|
| Unit | tests/test_*.py (excluding the three below) |
~43 | every push | Library functions in isolation |
| E2E | tests/test_e2e.py |
39 | every push | CLI invocations via subprocess across every role × format × command combo, plus error paths |
| Schema | tests/test_schemas.py |
7 | every push | JSON Schemas are valid and every --format json output validates against its schema |
| Scale | tests/test_scale.py |
3 | RUN_SCALE=1 or weekly CI |
10k / 50k / 100k receipt bundles against time and RSS-memory budgets |
| Chaos | tests/test_chaos.py |
11 | RUN_CHAOS=1 or weekly CI |
Hypothesis fuzz (random / binary / unicode / UCID) + I/O failure injection (permission errors, truncated files, directory-as-file, malformed YAML) |
# default suite (CI default)
pytest -m "not scale and not chaos"
# scale
RUN_SCALE=1 pytest -m scale -v
# chaos (Hypothesis + I/O failure injection)
RUN_CHAOS=1 pytest -m chaos -v
# everything
RUN_SCALE=1 RUN_CHAOS=1 pytestLantern's machine-readable contracts live in two places:
/schemas— JSON Schema 2020-12 documents for every--format jsonoutput (read,diff,explain). The CLI and the planned web view return the same shapes./docs/api— DRAFT OpenAPI 3.1 spec for the v0.2 web view (openapi.yaml), plusdata-model.md,flows.md(Mermaid sequence diagrams), andactions.md(event-type × role-lens matrix).
The v0.2 web view is tracked in #2; the spec is published with v0.1 so downstream tooling can generate clients against a stable contract.
git clone https://github.com/aigovops-foundation/aigovops-lantern
cd aigovops-lantern
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
mypy src
pytest --cov=aigovops_lanternAll commits must be DCO-signed (git commit -s).
Contributions are welcome under the same governance that covers the broader Umbrella-GovOps framework. Please read:
Apache License 2.0 — see LICENSE.
AIGovOps Lantern™ is an unregistered trademark of the AIGovOps
Foundation, a U.S. 501(c)(3) nonprofit. The mark must always appear in
its compound AIGovOps Lantern form in product branding, package names,
and domain names. Bare "Lantern" is not a Foundation mark.
See the full Trademark Policy.
Maintained by the AIGovOps Foundation · trademark@aigovopsfoundation.org
- Redwood v2 (draft FEP) — Foundation Enhancement Proposal currently in WG bootstrap. Tracks ratification of receipt schemas, UCID registry, and viability lens (Ashby + Beer + sociotechnical). See the ratification project and v0.1.0-draft release.