lowlightlog

A transaction-safe, zero-dependency, edge-native AI observability engine.

lowlightlog gives AI systems deployed on constrained edge hardware (Raspberry Pi–class devices, industrial IoT gateways, on-prem servers) a way to record inference activity locally — without cloud connectivity, third-party dependencies, or the memory/corruption/privacy failures of naive logging.

Why existing tools fail here

Install

pip install lowlightlog

No third-party dependencies are ever installed — lowlightlog uses only the Python standard library (sqlite3, asyncio, re, hashlib, json). Requires Python 3.9+.

Minimal example

import asyncio
from lowlightlog import EdgeAILogger

async def main():
    async with EdgeAILogger(path="./logs") as logger:
        await logger.log_inference(
            prompt="What is the capital of France?",
            response="Paris.",
            model="phi-3-mini",
            latency_ms=87.3,
        )
        print(logger.stats())

asyncio.run(main())

See examples/basic_example.py, examples/production_config_example.py (overflow policy, retention, backpressure alerting), and API.md for the full public surface.

Forensic export / verification CLI

lowlightlog export --path ./logs --since 2026-01-01 --fail-on-tamper

Read-only. Verifies the full SHA-256 hash chain and emits a JSON export (optionally date-filtered) with a content-integrity export_hash. Exits 1 if --fail-on-tamper is set and the chain is broken.

Guarantees

Full rationale in ARCHITECTURE.md.

Non-goals

• Application-layer encryption — use filesystem/disk encryption instead.
• Cloud export or remote log shipping.
• Token-perfect counting — token counts are a documented len(text)//4 estimate.
• NLP/ML-based PII detection — redaction is precompiled regex only.
• A UI, dashboard, or plugin system.
• On-disk compression. The live database is never compressed. Batched commits and a bounded WAL checkpoint threshold (see ARCHITECTURE.md) already keep flash write-wear low, which was the actual problem worth solving here — an always-live SQLite file isn't a great compression target anyway (it's actively appended to and checkpointed). If you need compressed long-term storage, export via lowlightlog export (see below) and compress the resulting JSON yourself; a built-in --compress export flag is a plausible future addition, not implemented today.

Failure behavior

Every documented failure mode has one deterministic outcome — see the Failure Behavior Contract table in ARCHITECTURE.md. In short: data still in the in-memory queue can be lost (per your configured overflow policy); data that reached a committed SQLite transaction can never be corrupted or partially written.

Development

pip install -e ".[dev]"
pytest

Roadmap

v0.2.0 delivered the forensic export CLI, policy-aware retention, backpressure alert hooks, and a multi-process stress-test suite (which caught and fixed a real hash-chain race — see CHANGELOG.md for details). Not planned: cloud dashboards, custom crypto, native tokenizers, a UI, or a plugin system — see CONTRIBUTING.md for the project's scope philosophy.

License

MIT — see LICENSE.