---
title: Cascade
emoji: 🌊
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false
license: mit
short_description: Cryptographic AI Provenance & Data Unity
---

# 🌊 CASCADE

**Universal AI Observability with Cryptographic Provenance**

*The bullshit button for AI.*

---

## What Is This?

CASCADE creates **cryptographic proof** of what happens inside AI systems — both **models** and **datasets**. Every layer, every activation, every data transformation — hashed, chained, and verifiable.

```
AI Company: "The AI said X"
You:        "Prove it."
CASCADE:    merkle_root: 0x7a3f9b2e... ✓ VERIFIED

AI Company: "Our datasets are unified correctly"
You:        "Prove it."
CASCADE:    provenance_chain: A → B → C... ✓ VERIFIED
```

---

## Two Tabs, Complete Coverage

### 🔬 Tab 1: Model Observatory
- Search any model on HuggingFace Hub
- Watch real-time 3D topology as inference flows
- Get cryptographic proof of every layer activation
- Download attestation JSON with full provenance chain

### 🔗 Tab 2: Data Unity
- Connect two HuggingFace datasets
- Discover matching entities via semantic similarity (Kleene fixed-point iteration)
- **🔮 Live Document Trace** — Watch the data light up as matches are discovered
- Push unified results back to Hub with W3C PROV-O provenance bundle

---

## Core Capabilities

### 🔍 Universal Model Support
- **Any HuggingFace model** — Search and load dynamically via `pipeline()` API
- **Kleene Fixed-Point Task Taxonomy** — Complete coverage of ALL pipeline tasks:

  | Modality | Tasks |
  |----------|-------|
  | **Text** | text-generation, text2text-generation, text-classification, sentiment-analysis, fill-mask, token-classification, NER, question-answering, summarization, translation, zero-shot-classification, feature-extraction |
  | **Table** | table-question-answering |
  | **Image** | image-classification, object-detection, image-segmentation, depth-estimation, image-to-image, image-to-text, zero-shot-image-classification, zero-shot-object-detection, mask-generation |
  | **Image+Text** | image-text-to-text, visual-question-answering, document-question-answering |
  | **Audio** | audio-classification, automatic-speech-recognition, zero-shot-audio-classification, text-to-audio |
  | **Video** | video-classification |
- **Dynamic dependency installation** — Auto-installs einops, easydict, etc.
- **Model blocklist** — Filters out incompatible models (flash-attn requirements)
- **Size limits** — 10GB CPU / 80% of detected VRAM (dynamic)

### 🔗 Data Unity (Entity Resolution)
- **Semantic Similarity** — sentence-transformers embeddings for fuzzy matching
- **Kleene Fixed-Point** — Iterates until no new matches found (mathematical completeness)
- **Live Document Tracing** — Real-time visualization of document processing:
  - 📊 Stats bar with event/match/document counters
  - 🔗 Association cards showing source→target with confidence
  - 📋 Event timeline with icons and timestamps
- **W3C PROV-O Provenance** — Full lineage tracking of all operations
- **Hub Export** — Push unified results with Croissant metadata

### 🔐 Cryptographic Provenance
- **SHA-256 hashing** of every tensor activation
- **Parent-child linking** — Each layer's hash chains to previous
- **Merkle root** — Single hash verifies entire inference
- **Model hash** — Fingerprint of model weights
- **Input hash** — Fingerprint of input data
- **Output hash** — Fingerprint of model output
- **Hardware info** — GPU count, VRAM, device name in attestation

### 📊 Real-time Health Monitoring
- **Anomaly detection** — Flags unusual activation patterns
- **5-metric health check:**
  - Loss indicators
  - Gradient health
  - Efficiency metrics
  - Overfitting detection
  - Anomaly flagging
- **Confidence scoring** — 0-100% health confidence
- **Correlation analysis** — Auto-discovers metric relationships

### 🧠 Deep Metric Capture
Automatically categorized metrics:

| Category | Metrics |
|----------|---------|
| **SYSTEM** | hidden_size, num_layers, num_heads, hooked_modules, input_tokens, chain_length |
| **ACTIVATION_FLOW** | mean, std, min, max, sparsity |
| **WEIGHT_DYNAMICS** | params, gradient norms |
| **ATTENTION_MECHANICS** | attn_entropy, attn_sparsity, attn_max, attn_self |
| **TRAINING_DYNAMICS** | predicted_class, confidence, score |

### 🎥 3D Visualization ("THE BRIDGE")
- **Emergent topology** — Graph structure emerges from actual computation
- **Circuit-board camera** — Automated tracing through layers  
- **AUTO/MANUAL toggle** — Click indicator to switch camera modes
- **Real-time event stream** — Watch activations flow through network
- **Node selection** — Click any node to drill into causation chain
- **Mobile touch support** — Pinch to zoom, drag to orbit

### 📱 Mobile Support
- **Touch controls** — Single-finger orbit, two-finger pinch zoom
- **WebGL recovery** — Auto-recovers from GPU context loss
- **Memory management** — Limits events to prevent crashes
- **Optimized rendering** — Reduced quality for battery/performance

### 🛡️ Model Protection
- **Pre-flight checks** — Validates model access before loading
- **Gated model detection** — Clear errors for access-restricted models
- **Size filtering** — Prevents OOM crashes
- **Timeout handling** — 10 minute GPU allocation for large models
- **Blocklist** — Filters models requiring unavailable dependencies
- **Multi-GPU sharding** — Automatic model distribution via `device_map="auto"`

---

## The Architecture

```
                    ┌─────────────────────────────────────┐
                    │         HuggingFace Hub             │
                    │    (Any model, any architecture)    │
                    └──────────────┬──────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────┐
                    │       Smart Model Detection         │
                    │  config.model_type + architectures  │
                    │  is_encoder_decoder detection       │
                    └──────────────┬──────────────────────┘
                                   │
    ┌──────────────────────────────┼──────────────────────────────┐
    │                              │                              │
    ▼                              ▼                              ▼
┌─────────┐                 ┌─────────────┐                ┌────────────┐
│CausalLM │                 │ Seq2SeqLM   │                │ Classifier │
│GPT, LLM │                 │ T5, BART    │                │BERT,DeBERTa│
└────┬────┘                 └──────┬──────┘                └─────┬──────┘
     │                             │                             │
     └─────────────────────────────┼─────────────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────┐
                    │     Forward Hook on ALL Modules     │
                    │   register_forward_hook(capture)    │
                    └──────────────┬──────────────────────┘
                                   │
Input → [Layer₀] → [Layer₁] → ... → [Layerₙ] → Output
           │          │                │
           ▼          ▼                ▼
         Hash₀ ──► Hash₁ ──► ... ──► Hashₙ
           │                           │
           └───────── Merkle Root ─────┘
                          │
                ┌─────────┴─────────┐
                │   THE BRIDGE      │
                │   3D Topology     │
                │   Health Monitor  │
                │   Provenance UI   │
                └───────────────────┘
```

---

## Supported Model Types

### Universal Task Taxonomy (Kleene Fixed-Point)

Instead of adding handlers case-by-case (an infinite ascending chain), CASCADE implements the **supremum** — a universal runner that adapts to any task based on modality classification:

```
┌─────────────────────────────────────────────────────────────────┐
│                      TASK_TAXONOMY                              │
├─────────────┬───────────────────────────────────────────────────┤
│  Modality   │  Tasks                                            │
├─────────────┼───────────────────────────────────────────────────┤
│  text       │  text-generation, summarization, translation,     │
│             │  fill-mask, text-classification, NER, sentiment   │
├─────────────┼───────────────────────────────────────────────────┤
│  text_pair  │  question-answering (context + question)          │
├─────────────┼───────────────────────────────────────────────────┤
│  table      │  table-question-answering                         │
├─────────────┼───────────────────────────────────────────────────┤
│  image      │  image-classification, object-detection,          │
│             │  segmentation, depth-estimation, image-to-text    │
├─────────────┼───────────────────────────────────────────────────┤
│  image+text │  VQA, document-QA, image-text-to-text             │
├─────────────┼───────────────────────────────────────────────────┤
│  audio      │  audio-classification, ASR, text-to-audio         │
├─────────────┼───────────────────────────────────────────────────┤
│  video      │  video-classification                             │
└─────────────┴───────────────────────────────────────────────────┘
```

### Architecture Examples:

**Seq2Seq (Encoder-Decoder):**
- T5, mT5, Flan-T5, LongT5
- BART, mBART, mBART-50
- Pegasus, BigBird-Pegasus
- MarianMT, LED, ProphetNet

**Causal LM (Decoder-only):**
- GPT-2, GPT-Neo, GPT-NeoX, GPT-J
- LLaMA, Mistral, Falcon
- OPT, BLOOM, Phi, Qwen, Gemma

**Classification (Encoder-only):**
- BERT, RoBERTa, DeBERTa
- DistilBERT, ALBERT, ELECTRA
- XLNet

**Vision:**
- ViT, DeiT, Swin, BEiT
- DETR, YOLOS (detection)
- SegFormer, Mask2Former (segmentation)

**Audio:**
- Whisper (ASR)
- Wav2Vec2, HuBERT
- Audio Spectrogram Transformer

**Multimodal:**
- BLIP, BLIP-2 (vision-language)
- LLaVA, Idefics (VLM)
- TAPAS, TAPEX (table understanding)

---

## Why This Matters

| Problem | Before | After CASCADE |
|---------|--------|---------------|
| "Did AI generate this?" | Trust provider | Verify merkle_root |
| "Which model was used?" | Ask nicely | Check model_hash |
| "Was input tampered?" | No way to know | Verify input_hash |
| "Prove inference happened" | Impossible | merkle_root on-chain |
| "Audit AI decisions" | Trust logs | Trustless verification |
| "Debug model behavior" | Print statements | Full layer observability |
| "Compare architectures" | Read papers | Visual topology comparison |

---

## Quick Start

### Web Interface

1. Go to [huggingface.co/spaces/tostido/Cascade](https://huggingface.co/spaces/tostido/Cascade)
2. Search for any model (e.g., "t5", "gpt2", "bert")
3. Select task type (translation, generation, classification, etc.)
4. Enter input text
5. Click **"🔬 BEGIN OBSERVATION"**
6. Watch the 3D visualization + get your Merkle root

### Understanding the Output

```
PROVENANCE
◉ MERKLE ROOT: 3ced2a4d9a1be241
MODEL:         f95dd06ab65e64...
INPUT:         6e766a49e512e0ba
517 layers in chain
```

- **Merkle Root**: Single hash proving entire inference
- **Model Hash**: SHA-256 of model weights
- **Input Hash**: SHA-256 of tokenized input
- **Chain Length**: Number of layers observed

---

## Visualization Guide

### THE BRIDGE (3D View)

- **Nodes**: Each sphere is a layer/module
- **Edges**: Connections show data flow
- **Colors**: Based on module type
- **Size**: Reflects activation magnitude

### Camera Modes

| Mode | Behavior |
|------|----------|
| **AUTO** | Camera traces through layers like circuit inspection |
| **MANUAL** | Drag to orbit, scroll to zoom |

Click the camera indicator to toggle modes.

### Health Panel

```
✓ HEALTHY (100% confidence)
○ loss      ○ gradient    ○ efficiency
○ overfit   ✓ anomalies
```

- Green ✓ = No issues detected
- Yellow ○ = Pending/neutral
- Red ✗ = Issue flagged with details

---

## Components

### `app.py`
- `search_models()` — HuggingFace Hub dynamic search
- Subprocess spawning to `worker.py`
- Real-time event streaming from worker stdout
- Gated model pre-flight checks

### `worker.py`
- **`TASK_TAXONOMY`** — Complete mapping of ~40 HuggingFace tasks
- **`get_data_generators()`** — Test data for all modalities
- **`run_universal()`** — The Kleene fixed-point: single handler for ALL tasks
- **`format_result()`** — Polymorphic result formatting

### `cascade/viz/live_v2.py`
- THE BRIDGE visualization engine
- 3D topology from architecture
- Real-time event streaming
- Health monitoring UI

### `cascade/core/`
- `provenance.py` — Hash chains, Merkle trees
- `web3_bridge.py` — Blockchain attestation
- `event.py` — Event system
- `adapter.py` — Gradio integration

---

## Technical Details

### Model Size Limits

| Hardware | Limit |
|----------|-------|
| CPU | 10GB |
| GPU | 80% of detected VRAM (auto) |
| Multi-GPU | 80% of total VRAM across all GPUs |

VRAM is detected dynamically at startup. Models exceeding limits are filtered from search results.

### Timeouts

| Operation | Duration |
|-----------|----------|
| GPU allocation | 10 minutes |
| Pip install | 120 seconds |
| Model load | Varies by size |

### Blocked Models

Some models require dependencies that can't be installed at runtime:
- Models requiring `flash-attn` (needs CUDA compilation)
- DeepSeek-V* series
- Custom models with complex dependencies

### Task Mapping

Invalid HuggingFace task tags are mapped to valid pipeline tasks:
- `sentence-similarity` → `feature-extraction`
- `image-text-to-text` → `image-to-text` (VLMs supported!)
- `text-to-image` → blocked (needs diffusers)

### Multi-GPU Support

For multi-GPU setups or models >20GB:
- Uses `device_map="auto"` for automatic model sharding
- Accelerate library distributes layers across all available GPUs
- Total VRAM from all GPUs is summed for size limits

### Hash Algorithm

```python
# Tensor hashing (deterministic)
tensor_bytes = tensor.cpu().float().numpy().tobytes()
hash = hashlib.sha256(tensor_bytes).hexdigest()

# Parent chaining
combined = f"{parent_hash}:{current_hash}"
linked_hash = hashlib.sha256(combined.encode()).hexdigest()
```

---

## Attestation Output

After running a model, CASCADE generates a full attestation JSON:

```json
{
  "document_type": "CASCADE Provenance Attestation",
  "version": "1.0",
  "summary": {
    "merkle_root": "f7d222ca4d457bc1",
    "what_this_proves": [
      "The exact model that was used",
      "The exact input that was processed",
      "Every layer's activation statistics",
      "The order of computations",
      "That this record has not been tampered with"
    ]
  },
  "model": {
    "identifier": "google-bert/bert-large-uncased",
    "weight_hash": "742aaf217d8ec777..."
  },
  "input": {
    "content_hash": "9f86d081884c7d65"
  },
  "computation": {
    "total_layers": 417,
    "layer_trace": [...]
  },
  "output": {
    "output_hash": "98620a019b01be29"
  },
  "hardware": {
    "gpu_count": 4,
    "vram_gb": 88,
    "device_name": "NVIDIA L4"
  }
}
```

---

## The Philosophy

> *"Observation and decision are mutually exclusive."*

CASCADE observes. It doesn't decide. It doesn't enforce. It records.

- **Governance without prescription** — Here are the facts. You decide.
- **Accountability without surveillance** — Opt-in verification.
- **Trust without authority** — Math, not institutions.

*Due process infrastructure for AI.*

---

## Roadmap

- [x] Universal pipeline() model support
- [x] Mobile touch controls
- [x] WebGL context recovery
- [x] Dynamic dependency installation
- [x] Model blocklist for incompatible deps
- [x] Task mapping for invalid tags
- [x] Attestation JSON export
- [x] Multi-GPU model sharding
- [x] Dynamic VRAM detection
- [x] Hardware info in attestation
- [x] VLM support (image-text-to-text)
- [ ] Attention pattern visualization
- [ ] Gradient flow tracking (training mode)
- [ ] Multi-model comparison
- [ ] Blockchain attestation UI
- [ ] IPFS attestation storage
- [ ] Custom model upload

---

## License

MIT

---

*The pudding exists. Taste it or don't. The hash doesn't care.* 🍮
