Metadata-Version: 2.4
Name: lightbox-rec
Version: 0.1.0
Summary: Flight recorder for AI agents - append-only, tamper-evident tool execution logs
Project-URL: Homepage, https://uselightbox.app
Project-URL: Documentation, https://github.com/robertkeenan/lightbox#readme
Project-URL: Repository, https://github.com/robertkeenan/lightbox
Project-URL: Issues, https://github.com/robertkeenan/lightbox/issues
Project-URL: Changelog, https://github.com/robertkeenan/lightbox/blob/main/CHANGELOG.md
Author-email: Robert Keenan <rob@uselightbox.app>
License-Expression: MIT
License-File: LICENSE
Keywords: agents,ai,langchain,logging,observability,tracing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click>=8.0
Provides-Extra: all
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: mypy>=1.10; extra == 'all'
Requires-Dist: pre-commit>=3.7; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Description-Content-Type: text/markdown

# Lightbox

Flight recorder for AI agents. Append-only, tamper-evident tool execution logs.

## What it is / isn't

- Records **tool calls** (send_email, read_file, api_call) - not LLM prompts/responses
- **Append-only** JSONL with SHA-256 hash chaining
- **Offline verification** - no network needed
- **Local-first** - sessions are portable directories you can zip and share
- **Not** a debugger, profiler, or execution controller - recording only

## Quickstart

```bash
pip install lightbox-rec
```

### SDK Usage

```python
from lightbox import Session

session = Session()
session.emit("send_email", {"to": "user@example.com"}, {"success": True})
session.emit("read_file", {"path": "/data.txt"}, {"content": "Hello"})
```

### LangChain Integration

```python
from lightbox.integrations.langchain import wrap

agent = wrap(your_agent)  # Automatically records tool calls
agent.invoke({"input": "Do the thing"})
```

### CLI

```bash
lightbox list                    # Show all sessions
lightbox show <session>          # Display events
lightbox replay <session>        # Animated playback
lightbox verify <session>        # Check integrity
```

## Where logs live

```
~/.lightbox/sessions/<session_id>/
    events.jsonl     # Append-only event log
    meta.json        # Session metadata
```

Override with `LIGHTBOX_DIR` environment variable.

## Exit codes (verify)

| Code | Status | Meaning |
|------|--------|---------|
| 0 | VALID | All checks pass |
| 1 | TAMPERED | Hash mismatch or chain break |
| 2 | TRUNCATED | Incomplete last line (crash mid-write) |
| 3 | PARSE_ERROR | Invalid JSON in event file |
| 4 | NOT_FOUND | Session doesn't exist |

## Redaction

```python
from lightbox import Session, RedactionConfig

config = RedactionConfig(
    redact_keys=["api_key", "password"],  # Always redact
    max_inline_bytes=64 * 1024,           # Hash content over 64KB
)
session = Session(redaction_config=config)
```

## Documentation

- [Event Format](docs/FORMAT.md) - Event schema and canonicalization rules
- [Integrations](docs/INTEGRATIONS.md) - LangChain and framework usage
- [Security](SECURITY.md) - Threat model and verification
- [Changelog](CHANGELOG.md) - Version history

## License

MIT - see [LICENSE](LICENSE)
