lumefuse-sdk 1.0.0
LumeFuse SDK - Atomic Veracity Protocol for Born-Signed Data
Requires Python: >=3.8
Keywords: lumefuse, blockchain, bsv, data-integrity, verification, bit-packet, recursive-dna, quantum-resistant

# LumeFuse Python SDK

The official Python SDK for [LumeFuse](https://lumefuse.io) - Atomic Veracity Protocol for Born-Signed Data.

## Installation

```bash
pip install lumefuse-sdk
```

## Quick Start

```python
from lumefuse import LumeFuse

# Initialize the client
lf = LumeFuse(api_key="lf_your_api_key")

# Open a data stream (The "Latch")
stream = lf.open_stream("medical_lab_results")

# Every data point is automatically:
# 1. Hashed (SHA-256)
# 2. Linked to previous packet (Recursive DNA)
# 3. Anchored to BSV ledger

stream.write({"patient_id": "P-001", "glucose": 95, "timestamp": "2026-02-20T14:30:00Z"})
stream.write({"patient_id": "P-001", "glucose": 102, "timestamp": "2026-02-20T15:30:00Z"})

# Close stream and get the Merkle root
result = stream.close()
print(f"Chain Root: {result.merkle_root}")
print(f"Total Packets: {result.total_packets}")
print(f"BSV TX: {result.anchor_txid}")
```

## Features

### Recursive DNA Binding (The Cryptographic Heartbeat)

Every Bit-Packet contains the DNA of the previous packet:

```
H_N = SHA256(Data_N + H_{N-1})
```

This creates an unbreakable chain where altering any packet breaks all subsequent packets.

### Quantum Resistance

The recursive hashing model provides practical resistance against quantum computing attacks. Even if a single hash is compromised, the entire chain cannot be altered without breaking the recursive DNA sequence.

### Self-Healing Data

The Sentinel system automatically detects and heals data corruption:

```python
# Verify chain integrity
status = lf.verify_chain("medical_lab_results")

if status.chain_intact:
    print("Data integrity verified")
else:
    print(f"Break detected at sequence {status.break_sequence}")
    if status.healed:
        print("Data automatically healed!")
```

## API Reference

### LumeFuse Client

```python
from lumefuse import LumeFuse

# Initialize with API key
lf = LumeFuse(
    api_key="lf_your_api_key",
    base_url="https://api.lumefuse.io/v1",  # Optional
    timeout=30.0,  # Optional
    auto_heal=True  # Optional - auto-heal on chain breaks
)
```

### Data Streams

```python
# Open a stream
stream = lf.open_stream("source_id")

# Write data (any JSON-serializable object)
stream.write({"key": "value"})
stream.write(["array", "of", "items"])
stream.write("plain string")

# Close and get result
result = stream.close()
```

### Verification

```python
# Verify single data item
result = lf.verify({"key": "value"})
print(f"Verified: {result.verified}")

# Verify entire chain
status = lf.verify_chain("source_id")
print(f"Chain intact: {status.chain_intact}")
print(f"Quantum resistant: {status.quantum_resistant}")
```

### Sentinel (Self-Healing)

```python
# Get sentinel status
status = lf.get_sentinel_status()

# Manually trigger audit
audit = lf.trigger_audit()

# Manually heal a break
result = lf.heal("source_id", break_sequence=5)

# Get healing history
history = lf.get_healing_history("source_id")
```

### Credits

```python
# Get credit balance
balance = lf.get_credits()
print(f"Packets available: {balance.packets_available}")
print(f"Satoshi balance: {balance.satoshi_balance}")
```

## Context Manager

```python
with LumeFuse(api_key="lf_your_key") as lf:
    stream = lf.open_stream("data")
    stream.write({"event": "action"})
    result = stream.close()
```

## Error Handling

```python
from lumefuse import LumeFuse
from lumefuse.exceptions import (
    AuthenticationError,
    RateLimitError,
    ChainIntegrityError,
    InsufficientCreditsError
)

try:
    lf = LumeFuse(api_key="lf_invalid")
except AuthenticationError:
    print("Invalid API key")

try:
    status = lf.verify_chain("source", auto_heal=False)
except ChainIntegrityError as e:
    print(f"Chain broken at sequence {e.break_sequence}")
```

## Environment Variables

- `LUMEFUSE_API_KEY` - Your API key
- `LUMEFUSE_BASE_URL` - Custom API base URL (optional)

## Publishing to PyPI

```bash
# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI
twine upload dist/*
```

## License

MIT License - see LICENSE file for details.

## Support

- Documentation: https://docs.lumefuse.io
- Email: support@lumefuse.io
- Enterprise: enterprise@lumefuse.io