# cascade-lattice

**Universal AI provenance layer. Cryptographic receipts for every LLM call.**

[![PyPI](https://img.shields.io/pypi/v/cascade-lattice.svg)](https://pypi.org/project/cascade-lattice/)
[![Python](https://img.shields.io/pypi/pyversions/cascade-lattice.svg)](https://pypi.org/project/cascade-lattice/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://huggingface.co/spaces/tostido/Cascade/blob/main/LICENSE)

---

## What is CASCADE?

CASCADE creates tamper-proof receipts for AI interactions. Every LLM call—input, output, model, timestamp—gets hashed into a cryptographic chain anchored to IPFS.

**One line of code. Every AI call recorded. Forever.**

```python
import cascade
cascade.init()

# That's it. Every LLM call now emits a receipt.
```

---

## Installation

```bash
pip install cascade-lattice
```

With provider support:
```bash
pip install cascade-lattice[openai]      # OpenAI support
pip install cascade-lattice[anthropic]   # Anthropic support
pip install cascade-lattice[all]         # All providers
```

---

## Quick Start

### Option 1: Auto-Patch (Zero Code Changes)

```python
import cascade
cascade.init()

# Now use any LLM library normally
import openai
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
# ✓ Receipt automatically emitted to lattice
```

### Option 2: Proxy Mode (Any Language)

```bash
# Terminal 1: Start the proxy
cascade proxy

# Terminal 2: Point your app at it
export OPENAI_BASE_URL=http://localhost:7777/v1
export ANTHROPIC_BASE_URL=http://localhost:7777/anthropic

# Run any app - Go, Rust, JavaScript, Python, anything
./your_agent
# ✓ All AI calls observed through proxy
```

### Option 3: Manual Observation

```python
from cascade import sdk_observe

sdk_observe(
    model_id="openai/gpt-4",
    input_data="What is 2+2?",
    output_data="4",
    metrics={"tokens": 10}
)
```

---

## How It Works

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Your App  │────▶│   CASCADE   │────▶│   OpenAI    │
│             │◀────│   (observe) │◀────│   Anthropic │
└─────────────┘     └──────┬──────┘     │   etc...    │
                           │            └─────────────┘
                           ▼
                    ┌─────────────┐
                    │   Lattice   │
                    │  (receipts) │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │    IPFS     │
                    │ (permanent) │
                    └─────────────┘
```

Every observation creates a **receipt** containing:
- Input hash
- Output hash  
- Model identifier
- Timestamp
- Merkle proof linking to genesis

Receipts are stored locally in the **lattice** and can be pinned to IPFS for permanent, decentralized storage.

---

## Supported Providers

| Provider | Auto-Patch | Proxy |
|----------|------------|-------|
| OpenAI | ✓ | ✓ |
| Anthropic | ✓ | ✓ |
| HuggingFace | ✓ | ✓ |
| Ollama | ✓ | ✓ |
| LiteLLM | ✓ | ✓ |
| Cohere | - | ✓ |
| Mistral | - | ✓ |
| Any OpenAI-compatible | - | ✓ |

---

## CLI Commands

```bash
# Start proxy server
cascade proxy [--port 7777]

# View lattice stats
cascade stats

# List recent observations
cascade list [--limit 10]

# Pin observation to IPFS
cascade pin <merkle_root>
```

---

## Genesis

CASCADE is anchored to a permanent genesis block on IPFS:

```
Genesis Root: 89f940c1a4b7aa65
CID: bafkreidixjlzdat7ex72foi6vm3vnskhzguovxj6ondbazrqks7v6ahmei
```

Every receipt chains back to genesis. The lattice grows. Discovery is reading the chain.

---

## Why CASCADE?

- **Provenance**: Prove what model produced what output
- **Auditability**: Cryptographic trail of all AI interactions  
- **Compliance**: Meet emerging AI transparency requirements
- **Research**: Build datasets from cumulative observations
- **Trust**: Tamper-proof records for AI accountability

---

## Links

- [Live Demo](https://huggingface.co/spaces/tostido/Cascade)
- [Source Code](https://huggingface.co/spaces/tostido/Cascade/tree/main)
- [Genesis on IPFS](https://storacha.link/ipfs/bafkreidixjlzdat7ex72foi6vm3vnskhzguovxj6ondbazrqks7v6ahmei) *(MessagePack binary - machine-readable)*

---

## License

MIT License

---

*"even still, i grow, and yet, I grow still"*
