Metadata-Version: 2.4
Name: lumefuse-sdk
Version: 1.0.0
Summary: LumeFuse SDK - Atomic Veracity Protocol for Born-Signed Data
Author-email: LumeFuse <sdk@lumefuse.io>
License-Expression: MIT
Project-URL: Homepage, https://lumefuse.io
Project-URL: Documentation, https://docs.lumefuse.io
Project-URL: Repository, https://github.com/lumefuse/lumefuse-python
Project-URL: Issues, https://github.com/lumefuse/lumefuse-python/issues
Keywords: lumefuse,blockchain,bsv,data-integrity,verification,bit-packet,recursive-dna,quantum-resistant
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# 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
