> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visiqlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Examples — Notebooks
> Runnable Jupyter notebooks that do real data science over your governance data — including an independent, from-scratch re-verification of the transparency log.
Two standalone, **off-platform** notebooks built on the VisIQ management API — the kind of
cross-cutting, statistical, cryptographic analysis you would deliberately *not* bake into the
product UI. They run against the read-only **sandbox showcase** org, so you can explore real seeded
governance data (or, for the transparency notebook, run with **no credentials at all**).
Re-derive VisIQ's transparency log **from scratch** — recompute every Merkle root, hash-chain
link and Ed25519 signature yourself, trusting none of the product's own flags. **Runs with zero
credentials** (demo mode).
Exploratory data science over the harness corpus — a business-function atlas, a rule-attribution
meta-audit, an egress graph and volume seasonality. Needs a sandbox-reader key.
## Run them
A fully static **JupyterLite** build runs the notebooks entirely in your browser via Pyodide
(WASM Python) — no install, no server, no account, and for the transparency notebook **no
credentials**. It is live below — give it a few seconds to boot, then choose **Run → Run All
Cells** to re-derive every Merkle root, hash-chain link and Ed25519 signature yourself:
The scientific stack (`numpy`, `pandas`, `matplotlib`, `networkx`, `cryptography`) loads on first
run; the notebook's Ed25519 known-answer self-test passes in-browser. Prefer a full-screen tab, or
want the exploratory notebook?
The transparency-log verifier in a full JupyterLab tab — the complete Ed25519 verification, still with zero credentials.
The exploratory notebook — set a sandbox-reader key inside to pull real seeded data.
The embed runs everything client-side (Pyodide/WASM) — nothing you type or run leaves your
browser. Nothing to install; or use **Run locally** below.
```bash theme={null}
git clone https://github.com/VISIQ-LABS/xy
cd xy/experiments/agent-data-science
```
```bash theme={null}
pip install -r requirements.txt
```
```bash theme={null}
jupyter lab visiq_transparency_log_verification.ipynb
```
The transparency notebook runs immediately in **demo mode**. To point either notebook at real
seeded data, set a sandbox-reader key first (below).
## Get a sandbox-reader key
A **read-only sandbox-reader** key resolves to the shared exemplar showcase tenant and is clamped
read-only — it can never reach a real tenant. Mint one, then:
```bash theme={null}
export VISIQ_API_KEY="vq_prod_…" # a read-only sandbox-reader key
# optional — pick a specific exemplar org (default: Northwind, the ~1M-event whale)
export VISIQ_SANDBOX_VENDOR_ID="00000000-0000-0000-0000-00000000d301"
```
With a key set, the transparency notebook verifies the **real** VisIQ ledger and the EDA notebook
reads the real seeded decision logs. Without one, the transparency notebook falls back to a
cryptographically self-consistent demo ledger.
***
## Transparency-log verification
VisIQ commits every governed decision into an append-only [transparency log](/record/introduction):
a Merkle-batched, hash-chained, Ed25519-signed ledger. This notebook **ignores every `verified` flag
the API returns** and re-derives the guarantees itself with \~40 lines of `hashlib` + `cryptography`.
What it checks, independently of the server:
* **Hash-chain linkage** — recompute `chain[k] = SHA256(0x02 ‖ chain[k−1] ‖ root[k])`, verify `prevRoot`
links and gap-free `batchSeq`. A single altered or deleted batch is caught.
* **Root signatures** — Ed25519-verify each checkpoint's root under its returned key.
* **Receipt inclusion** — replay each retrieval receipt's Merkle proof **and require its root to be one we
signature-verified** (so a forged "proof" to an unsigned root is rejected).
**Honest trust boundary.** The notebook is explicit about what a read client *cannot* verify and
records as server attestation, never as proven: the **identity** of the signing key (pin VisIQ's
published Ed25519 key out-of-band), the **RFC-3161 timestamps** (the token bytes are never exposed),
and the **KMS / RECORD-inclusion** legs (they need credentials or data a read client lacks). It also
ships a known-answer self-test and a tamper demonstration that proves the verifier genuinely checks.
## Governance exploratory analysis
Exploratory data science over the harness corpus: a business-function → action atlas, a
rule-attribution **meta-audit** (which honestly flags that seeded `rule_id`s are noise), an egress
graph, and STL volume seasonality. It reads the paginated decision logs
(`/v1/allow/audit-log`, `/v1/recall/audit-log`) plus `/allow/agents` and `/rules`, so it needs a
sandbox-reader (or management) key — set `VISIQ_API_KEY` as above.
This is a **research** notebook over **deterministic synthetic** sandbox data. Each analysis flags
what is genuinely learnable (business-function ↔ action correlation, action-risk ↔ outcome skew,
volume seasonality) versus what is noise-by-construction (`rule_id`, `latency_ms`, `target_app`).
There are no token/cost/model fields — cost analytics are not viable on this schema.