Copyright © 2026 Saccadic LLC · Patent pending.

Browse chapters
  1. Release NotesChanges by version
  2. Chapter 1What IRIS Is and Is Not
  3. Chapter 2The IRIS Data Model
  4. Chapter 3How IRIS Measures
  5. Chapter 4Safe Interpretation and the First 15 Minutes
  6. Chapter 5Dashboard Overview
  7. Chapter 6Installation
  8. Chapter 7Configuration
  9. Chapter 8Build the Model Spec and Probe Set
  10. Chapter 9Minimal Tracker Integration
  11. Chapter 10Launch the Bench and Verify Capture
  12. Chapter 11Runtime Control, Signals, Metrics, and Logs
  13. Chapter 12Integration Patterns by Model Family
  14. Chapter 13Distributed Training
  15. Chapter 14Artifacts, Reports, Export, and Security
  16. Chapter 15Troubleshooting
  17. Chapter 16Whole Model and Layer Structure
  18. Chapter 17Domain Training and Affinity
  19. Chapter 18Attention-Head Diagnostics
  20. Chapter 19MoE Expert and Router Diagnostics
  21. Chapter 20Facets and Emergent Pathways
  22. Chapter 21Gradient Residuals, Stability, Curvature, and Update Efficiency
  23. Chapter 22Adaptive Cadence and Event Detection
  24. Chapter 23CLI Reference
  25. Chapter 24Configuration-Key Reference
  26. Chapter 25API Reference
  27. Chapter 26File and Schema Reference
  28. Chapter 27Glossary and Concept Index
  29. Chapter 28The Flow Map
  30. Appendix ADiagnostic Availability Matrix
  31. Appendix BLLM Prompt Library
On this page

Chapter 2 — The IRIS™ Data Model

How data flows through IRIS

Before the term-by-term glossary below, here is how the objects fit together end to end, and what actually lands on disk in the run directory — corrected against the current bench implementation.

  1. Spec. A spec dict (or spec JSON file) describes the model's architecture — the shapes and module paths IRIS needs to attach to, independent of any specific model name. You supply this once per model family (see Creating a Spec Dict/File, later in this manual).
  2. Probes. A probes file supplies the labeled inputs — grouped into domains and subdomains — that the tracker feeds through the model to inspect its internal organization (see Creating a Probes File, later in this manual).
  3. Tracker. The inline tracker runs inside your training script. On each selected training step it runs an extraction: it passes the probes through the model, captures the resulting representations, and appends the result as one frame to an encrypted .iris bundle in the run directory. The tracker also writes iris.log (its private ASCII log), reads and deletes iris.cmd (a staged command file), and maintains a scratch/ directory (pid file, last_step.json, checkpoint state) — all in the run directory.
  4. Run directory. The captured run contains its .iris bundle, iris.log, and runtime scratch/ files. A clean tracker close removes its temporary scratch files. Supported live commands may be staged in this directory, but the Bench keeps its derived analysis elsewhere.
  5. Bench. The local browser dashboard reads the .iris bundle while training runs or after it ends, without loading the model again. Derived analysis, caches, and the Bench log live in a separate machine store. They can be rebuilt from the bundle, so a copied run or a run on a read-only volume can still be inspected. User-requested exports and recordings remain separate artifacts to review before sharing. See Chapter 14 and Chapter 26.

Key Concepts for New Users

Probe. A probe is one labeled input used by IRIS to inspect the model.

{
  "domain": "arithmetic",
  "subdomain": "carry_addition",
  "input": "99+1=100"
}

The model does not need to answer the probe correctly for the probe to be useful. Even wrong answers produce internal activations IRIS can measure.

Domain. A domain is a top-level probe category, such as arithmetic, code, grammar, legal text, or customer support. Domains let IRIS show whether different kinds of inputs are represented similarly or differently inside the model. A probe that declares no subdomain has its domain as its category.

Subdomain. A subdomain is a finer category inside a domain — for example, arithmetic → simple addition, carry addition, multiplication, word problems. Subdomains help users inspect whether related task types are represented similarly or differently. If carry addition and word problems occupy different regions, show different k95 values, or move differently over training, the user can inspect whether the model is treating those task types differently under IRIS's measurements. A probe that declares a subdomain has it as its category.

Category. A probe's category is its subdomain when one is declared, and otherwise its domain, so a probe set that declares no subdomains has a category equal to its domain for every probe. Several figures in §4, §6 and §8 (per-subdomain k95, subdomain subspace similarity, per-category head affinity, per-category facet views) are drawn only when at least one probe's category differs from its domain — the heterogeneity gate — and otherwise show a not-available note in place of a copy of the domain-level view. Chapter 9 shows how to declare a distinct category.

Frame. A frame is one diagnostic snapshot captured during training. Most IRIS time-series charts show how a measurement changes from frame to frame.

k95. k95 is the number of spectral directions needed to capture 95% of the measured variance in a layer. Lower k95 means the measured structure is concentrated in fewer dominant directions; higher k95 means it is spread across more directions. High or low k95 is not automatically good or bad; context matters.

Spectral Entropy. Spectral entropy shows how evenly a layer's measured structure is distributed across spectral directions. High spectral entropy means many directions share the structure more evenly; low spectral entropy means a few dominant directions carry more of it.

Spectral Exponent. The spectral exponent describes the slope of the eigenvalue spectrum. A steeper slope means the largest directions dominate more strongly; a flatter slope means the measured structure is spread more broadly.

Basis Rotation. Basis rotation measures how much the model's main internal directions turn over time. A spike means the internal orientation changed sharply between diagnostic frames. That may be normal during reorganization; it is not automatically a failure signal.

Training Affinity. Training affinity measures whether different domains pull the model's weights in similar or opposing gradient directions. Positive affinity means two domains pull in similar directions; negative affinity means they pull against each other under this measurement.