cascade-lattice 0.8.0

Universal AI provenance layer — cryptographic receipts for every call, HOLD inference halt protocol, and code diagnostics

cascade-lattice

Universal AI provenance + inference intervention + code diagnostics. See what AI sees. Choose what AI chooses. Find bugs before they find you.

pip install cascade-lattice

Import with either style:

import cascade                # Preferred
import cascade_lattice        # Also works (alias)
from cascade import Hold      # Works
from cascade_lattice import Hold  # Also works

---

🎮 Interactive Demo

See CASCADE-LATTICE in action — fly a lunar lander with AI, take control anytime:

pip install cascade-lattice[demo]
cascade-demo

Controls:

• [H] HOLD-FREEZE — Pause time, see AI's decision matrix, override with WASD
• [T] HOLD-TAKEOVER — You fly the lander, AI watches, provenance records everything
• [ESC] Release hold, return to AI control

Every action is merkle-chained. Every decision has provenance. This is the future of human-AI interaction.

---

🌐 TUI Explorer

Navigate the entire cascade-lattice ecosystem in a beautiful terminal interface:

pip install cascade-lattice[tui]
cascade-tui

┌──────────────────────────────────────────────────────────────────────────────┐
│  📍 🌐 cascade_lattice → 🧠 core → 📊 provenance                             │
├──────────────────────────────────────────────────────────────────────────────┤
│                        │                              │                      │
│  🗂️ MODULES            │  📖 DOCUMENTATION            │  🔗 CONNECTIONS      │
│                        │                              │                      │
│  🌐 cascade_lattice    │  # 📊 Provenance             │  ⬆️ 🧠 core          │
│   ├─ 🧠 core           │                              │  ⬇️ 📡 Monitor       │
│   │  ├─ 📊 provenance  │  **What is this?**           │  📥 🌅 genesis       │
│   │  ├─ 📈 graph       │  The cryptographic backbone  │  📤 💾 store         │
│   │  ├─ 🔌 adapter     │  that makes everything       │                      │
│   │  └─ 📡 event       │  tamper-proof.               │  📦 EXPORTS          │
│   ├─ ⏸️ hold           │                              │                      │
│   ├─ 💾 store          │  Like a notary stamp on      │  ● ProvenanceChain   │
│   ├─ 🌅 genesis        │  every AI decision...        │  ● ProvenanceRecord  │
│   └─ 🎨 viz            │                              │  ○ hash_tensor()     │
│                        │  [Toggle: 📚 Dummies Mode]   │  ○ compute_merkle()  │
│                        │                              │                      │
├──────────────────────────────────────────────────────────────────────────────┤
│  [E] Explorer  [S] Stats  [D] Demo  [T] Toggle Mode  [H] Home  [Q] Quit      │
└──────────────────────────────────────────────────────────────────────────────┘

Features:

• 🗂️ Module Tree — Click to drill into any module
• 🔗 Connections Panel — Navigate via relationships (parent, children, imports, used-by)
• 📖 Dual Explanations — Toggle between "For Dummies" 📚 and "Scientist Mode" 🧪
• 📊 Live Stats — See your 82,000+ observations, genesis root, top models
• 🎮 Interactive Demos — Run HOLD, Observe, Genesis, Provenance demos live

Creative Navigation: Take different routes through the module graph. Discover connections. Learn at your own pace.

---

Two Superpowers

1. OBSERVE - Cryptographic receipts for every AI call

from cascade.store import observe

# Every inference -> hashed -> chained -> stored
receipt = observe("my_agent", {"action": "jump", "confidence": 0.92})
print(receipt.cid)  # bafyrei... (permanent content address)

2. HOLD - Pause AI at decision points

from cascade.hold import Hold
import numpy as np

hold = Hold.get()

# Your model (any framework)
action_probs = model.predict(state)

resolution = hold.yield_point(
    action_probs=action_probs,
    value=0.72,
    observation={"state": state},
    brain_id="my_model",
    action_labels=["up", "down", "left", "right"],  # Human-readable
)

# AI pauses. You see the decision matrix.
# Accept or override. Then it continues.
action = resolution.action

3. DIAGNOSE - Find bugs before they find you

from cascade.diagnostics import diagnose, BugDetector

# Quick one-liner analysis
report = diagnose("path/to/your/code.py")
print(report)  # Markdown-formatted bug report

# Deep scan a whole project
detector = BugDetector()
issues = detector.scan_directory("./my_project")

for issue in issues:
    print(f"[{issue.severity}] {issue.file}:{issue.line}")
    print(f"  {issue.message}")
    print(f"  Pattern: {issue.pattern.name}")

What it catches:

• 🔴 Critical: Division by zero, null pointer access, infinite loops
• 🟠 High: Bare except clauses, resource leaks, race conditions
• 🟡 Medium: Unused variables, dead code, type mismatches
• 🔵 Low: Style issues, naming conventions, complexity warnings

Runtime tracing:

from cascade.diagnostics import CodeTracer

tracer = CodeTracer()

@tracer.trace
def my_function(x):
    return x / (x - 1)  # Potential div by zero when x=1

# After execution, trace root causes
tracer.find_root_causes("error_event_id")

4. FORENSICS - Read the shape of failure payloads

import pandas as pd
from cascade.forensics import DataForensics

payload = {
    "component": "debug_runtime",
    "tool": "forensics_analyze",
    "status": 404,
    "trace_id": "trace-123",
    "retry_count": 2,
    "timestamp": "2026-03-06T03:40:15Z",
    "context": {"route": "caller", "source": "agent-inner"},
    "error": "HTTP Error 404: Not Found",
}

forensics = DataForensics()
report = forensics.analyze(pd.DataFrame([payload]), mode="auto")

print(report.summary())
print(report.ghost_log.to_narrative())

Modes:

• dataset - preserve the original artifact archaeology behavior for multi-row data
• anomaly - inspect single-event or tiny structured debug payloads
• auto - choose anomaly mode for small structured payloads, dataset mode otherwise

---

Quick Start

Zero-Config Auto-Patch

import cascade
cascade.init()

# That's it. Every call is now observed.
import openai
# ... use normally, receipts emit automatically

Manual Observation

from cascade.store import observe, query

# Write
observe("gpt-4", {"prompt": "Hello", "response": "Hi!", "tokens": 5})

# Read
for receipt in query("gpt-4", limit=10):
    print(receipt.cid, receipt.data)

---

HOLD: Inference-Level Intervention

HOLD lets you pause any AI at decision points:

══════════════════════════════════════════════════
🛑 HOLD #1
   Merkle: 3f92e75df4bf653f
   AI Choice: FORWARD (confidence: 45.00%)
   Value: 0.7200
   Probabilities: FORWARD:0.45, BACK:0.30, LEFT:0.15, RIGHT:0.10
   Wealth: attention, features, reasoning
   Waiting for resolution (timeout: 30s)...
══════════════════════════════════════════════════

Model-agnostic - works with:

• PyTorch, JAX, TensorFlow
• HuggingFace, OpenAI, Anthropic
• Stable Baselines, RLlib
• Any function that outputs probabilities

Informational Wealth

Pass everything your model knows to help humans decide:

resolution = hold.yield_point(
    action_probs=probs,
    value=value_estimate,
    observation=obs,
    brain_id="my_model",
    
    # THE WEALTH (all optional):
    action_labels=["FORWARD", "BACK", "LEFT", "RIGHT"],
    latent=model.get_latent(),           # Internal activations
    attention={"position": 0.7, "health": 0.3},
    features={"danger": 0.2, "goal_align": 0.8},
    imagination={                         # Per-action predictions
        0: {"trajectory": ["pos", "pos"], "expected_value": 0.8},
        1: {"trajectory": ["neg", "neg"], "expected_value": -0.3},
    },
    logits=raw_logits,
    reasoning=["High reward path", "Low risk"],
)

Build Your Own Interface

Register a listener to receive full HoldPoint data:

def my_ui_handler(hold_point):
    # hold_point contains ALL the wealth
    print(hold_point.action_labels)
    print(hold_point.imagination)
    # Send to your UI, game engine, logger, etc.

hold.register_listener(my_ui_handler)

---

Collective Intelligence

Every observation goes into the lattice:

from cascade.store import observe, query

# Agent A observes
observe("pathfinder", {"state": [1,2], "action": 3, "reward": 1.0})

# Agent B queries
past = query("pathfinder")
for r in past:
    print(r.data["action"], r.data["reward"])

---

CLI

# View lattice stats
cascade stats

# List observations  
cascade list --limit 20

# HOLD info
cascade hold

# HOLD system status
cascade hold-status

# Start proxy
cascade proxy --port 7777

---

Installation

# Core
pip install cascade-lattice

# With interactive demo (LunarLander)
pip install cascade-lattice[demo]

# With LLM providers
pip install cascade-lattice[openai]
pip install cascade-lattice[anthropic]
pip install cascade-lattice[all]

---

How It Works

Your Model                    CASCADE                      Storage
    |                            |                            |
    |  action_probs = [0.1,     |                            |
    |                  0.6,     |                            |
    |                  0.3]     |                            |
    | ------------------------->|                            |
    |                           |  hash(probs) -> CID        |
    |        HOLD               |  chain(prev_cid, cid)      |
    |   +-------------+         | -------------------------> |
    |   | See matrix  |         |              ~/.cascade/   |
    |   | Override?   |         |              lattice/      |
    |   +-------------+         |                            |
    | <-------------------------|                            |
    |   resolution.action       |                            |

---

Genesis

Every receipt chains back to genesis:

Genesis: 89f940c1a4b7aa65

The lattice grows. Discovery is reading the chain.

---

Links

• PyPI
• Issues

---

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

Documentation

Research & Theory

📄 Research Paper: Kleene Fixed-Point Framework
Deep dive into the mathematical foundations—how CASCADE-LATTICE maps neural network computations to Kleene fixed points, creating verifiable provenance chains through distributed lattice networks.

📖 Accessible Guide: From Theory to Practice
For everyone from data scientists to curious users—understand how CASCADE works, with examples ranging from medical AI oversight to autonomous drone coordination.

Key Concepts:

• Kleene Fixed Points: Neural networks as monotonic functions converging to stable outputs
• Provenance Chains: Cryptographic Merkle trees tracking every layer's computation
• HOLD Protocol: Human-in-the-loop intervention at decision boundaries
• Lattice Network: Distributed fixed-point convergence across AI agents

Quick Links

• Theory: Research Paper | Mathematical Proofs
• Practice: Accessible Guide | Real-World Examples

---

References

Built on foundational work in:

• Kleene Fixed Points (Kleene, 1952) — Theoretical basis for provenance convergence
• Merkle Trees (Merkle, 1987) — Cryptographic integrity guarantees
• IPFS/IPLD (Benet, 2014) — Content-addressed distributed storage

See full bibliography in the research paper.