lowlightlog 0.3.0

Transaction-safe, zero-dependency, edge-native AI observability engine.

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

Tool	Fails at
LangSmith / Phoenix / OpenInference	Cloud-bound, heavy dependency trees, needs connectivity
stdlib logging / Loguru / Structlog	No transactional safety, unbounded memory, no redaction, not AI-aware
Custom file writers	Corruption on power loss, TOCTOU races on log rotation
"Encrypted" logging shims	Fake crypto (XOR/obfuscation), fails real audits

Install

pip install -e .

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 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

Guarantee	Mechanism
No cloud dependency	No network code in the package
No third-party packages	Standard library only
No OOM crashes	Bounded queue, deterministic overflow policy
No corrupted logs	SQLite WAL, atomic batched commits
No race conditions	Single background writer, single-writer WAL semantics
No fake security	No app-layer crypto; relies on WAL integrity + filesystem encryption
No PII leakage	Redaction runs before enqueue, before any disk touch
Survives power loss	WAL + fsync at commit boundaries
Tamper-evident	SHA-256 hash chain over rows

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.