Metadata-Version: 2.4
Name: lowlightlog
Version: 0.4.0
Summary: Transaction-safe, zero-dependency, edge-native AI observability engine.
Author: lowlightlog contributors
License: MIT
Project-URL: Homepage, https://github.com/Navneet-Scaler/lowlightlog
Project-URL: Issues, https://github.com/Navneet-Scaler/lowlightlog/issues
Project-URL: Changelog, https://github.com/Navneet-Scaler/lowlightlog/blob/main/CHANGELOG.md
Keywords: observability,logging,edge,ai,sqlite,audit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Logging
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# lowlightlog

[![test](https://github.com/Navneet-Scaler/lowlightlog/actions/workflows/test.yml/badge.svg)](https://github.com/Navneet-Scaler/lowlightlog/actions/workflows/test.yml)
[![PyPI](https://img.shields.io/pypi/v/lowlightlog.svg)](https://pypi.org/project/lowlightlog/)
[![Python versions](https://img.shields.io/pypi/pyversions/lowlightlog.svg)](https://pypi.org/project/lowlightlog/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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

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

```python
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/basic_example.py),
[examples/production_config_example.py](examples/production_config_example.py)
(overflow policy, retention, backpressure alerting), and [API.md](API.md) for
the full public surface.

## Forensic export / verification CLI

```bash
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](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](ARCHITECTURE.md#wal-checkpointing)) 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](ARCHITECTURE.md#failure-behavior-contract).
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

```bash
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](CHANGELOG.md) for details). Not
planned: cloud dashboards, custom crypto, native tokenizers, a UI, or a
plugin system — see [CONTRIBUTING.md](CONTRIBUTING.md) for the project's
scope philosophy.

## License

MIT — see [LICENSE](LICENSE).
